SandboxedSkillScriptRunner

Namespace Tracon · Assembly Tracon.Core.dll

Tracon’s single script execution path, which runs skill scripts in an isolated operating-system process.

public sealed class SandboxedSkillScriptRunner : IDisposable

Inheritance

object ← SandboxedSkillScriptRunner

Implements

IDisposable

Inherited Members

object.GetType(), object.ToString(), object.Equals(object?), object.Equals(object?, object?), object.ReferenceEquals(object?, object?), object.GetHashCode()

Remarks

Microsoft Agent Framework never runs a script on its own. AgentFileSkillScriptRunner is a call point; the sandbox, timeout, resource limits, and audit trail are entirely Tracon’s responsibility.

Every run passes through these gates in order. If one is closed, the script never starts at all:

• Is the feature enabled (TraconSkillScriptOptions.Enabled)
• Is there a valid SkillScriptGrant for the tenant
• Is the extension on the interpreter allow-list
• Did the arguments pass size and schema validation
• Was the audit trail entry written

The last item is a deliberate exception to the “observability does not break functionality” rule: a script run that cannot be written to the audit trail would be a remote code execution with no record at all.

MAF’s approval flow stays active: DisableRunSkillScriptApproval is not set, meaning every script call waits for user approval first.

Constructors

SandboxedSkillScriptRunner(IOptions<TraconOptions>, ITenantContext, ISkillScriptGrantStore, IAuditLog, IAuditActorResolver, ILogger<SandboxedSkillScriptRunner>, IRunStore?, TraconMetrics?, TimeProvider?)

Creates a new runner.

public SandboxedSkillScriptRunner(IOptions<TraconOptions> options, ITenantContext tenantContext, ISkillScriptGrantStore grantStore, IAuditLog auditLog, IAuditActorResolver actorResolver, ILogger<SandboxedSkillScriptRunner> logger, IRunStore? runStore = null, TraconMetrics? metrics = null, TimeProvider? timeProvider = null)

Parameters

options IOptions<TraconOptions>

The Tracon settings.

tenantContext ITenantContext

The tenant context.

grantStore ISkillScriptGrantStore

The grant record store.

auditLog IAuditLog

The audit trail.

actorResolver IAuditActorResolver

The actor resolver.

logger ILogger<SandboxedSkillScriptRunner>

The logger.

runStore IRunStore?

The store the tool call record is written to. Not written if null.

metrics TraconMetrics?

The metrics instruments. No metrics are emitted if null.

timeProvider TimeProvider?

The time source. The system clock is used if null.

Exceptions

ArgumentNullException

One of the required dependencies is null.

Methods

Dispose()

public void Dispose()

RunFileScriptAsync(AgentFileSkill, AgentFileSkillScript, JsonElement?, IServiceProvider?, CancellationToken)

Runs a skill script from disk. Wired to MAF’s AgentFileSkillScriptRunner delegate.

public Task<object?> RunFileScriptAsync(AgentFileSkill skill, AgentFileSkillScript script, JsonElement? arguments, IServiceProvider? serviceProvider, CancellationToken cancellationToken)

Parameters

skill AgentFileSkill

The skill that carries the script.

script AgentFileSkillScript

The script to run.

arguments JsonElement?

The arguments produced by the model.

serviceProvider IServiceProvider?

The service provider given by MAF. Not used.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<object?>

The text result to return to the model.

Exceptions

TraconException

One of the gates is closed.

RunStoredScriptAsync(string, AgentSkillScriptDefinition, JsonElement?, CancellationToken)

Runs a skill script stored in the database.

public Task<object?> RunStoredScriptAsync(string skillName, AgentSkillScriptDefinition script, JsonElement? arguments, CancellationToken cancellationToken)

Parameters

skillName string

The skill’s name.

script AgentSkillScriptDefinition

The script definition.

arguments JsonElement?

The arguments produced by the model.

cancellationToken CancellationToken

The cancellation token.

Returns

Task<object?>

The text result to return to the model.

Remarks

This path is used only when TraconSkillScriptOptions.AllowStoredScripts is enabled. The content is written to a temporary directory accessible only to its owner, only for the duration of the run, and deleted afterward.

Exceptions

TraconException

One of the gates is closed.