Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,17 @@ public static HyperlightCodeActProviderOptions CreateForJavaScript()
/// </summary>
public CodeActApprovalMode ApprovalMode { get; set; } = CodeActApprovalMode.NeverRequire;

/// <summary>
/// Gets or sets whether host exception details are exposed to generated code and in execution errors.
/// Defaults to <see langword="false"/>.
/// </summary>
/// <remarks>
/// Detailed errors include exception types, stack traces, and inner exceptions.
/// Enable only for a trusted channel: diagnostics can contain sensitive host data.
/// This is independent of the outer chat client's error policy and sensitive-data logging.
/// </remarks>
public bool IncludeDetailedErrors { get; set; }

/// <summary>
/// Gets or sets an optional host directory exposed to the sandbox as its
/// <c>/input</c> directory.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ public RunSnapshot(
this.HeapSize = options.HeapSize;
this.StackSize = options.StackSize;
this.HostInputDirectory = options.HostInputDirectory;
this.IncludeDetailedErrors = options.IncludeDetailedErrors;
this.ToolRegistryVersion = toolRegistryVersion;
this.ConfigFingerprint = ComputeFingerprint(
this.Tools,
Expand All @@ -62,7 +63,8 @@ public RunSnapshot(
this.Backend,
this.ModulePath,
this.HeapSize,
this.StackSize);
this.StackSize,
this.IncludeDetailedErrors);
}

public IReadOnlyList<AIFunction> Tools { get; }
Expand All @@ -81,6 +83,8 @@ public RunSnapshot(

public string? HostInputDirectory { get; }

public bool IncludeDetailedErrors { get; }

public Guid ToolRegistryVersion { get; }

/// <summary>
Expand All @@ -100,7 +104,8 @@ internal static string ComputeFingerprint(
SandboxBackend backend = SandboxBackend.JavaScript,
string? modulePath = null,
string? heapSize = null,
string? stackSize = null)
string? stackSize = null,
bool includeDetailedErrors = false)
{
var buffer = new ArrayBufferWriter<byte>();
using (var writer = new Utf8JsonWriter(buffer))
Expand All @@ -111,6 +116,7 @@ internal static string ComputeFingerprint(
writer.WriteString("heapSize", heapSize);
writer.WriteString("stackSize", stackSize);
writer.WriteString("hostInputDirectory", hostInputDirectory);
writer.WriteBoolean("includeDetailedErrors", includeDetailedErrors);
writer.WriteString("toolRegistryVersion", toolRegistryVersion);

writer.WritePropertyName("tools");
Expand Down Expand Up @@ -225,20 +231,24 @@ public async Task<string> ExecuteAsync(RunSnapshot snapshot, string code, Cancel
this._sandbox!.Restore(this._warmSnapshot);
}

ExecutionResult result;
return BuildResult(this._sandbox!.Run(code));
}
#pragma warning disable CA1031 // Return ordinary lifecycle failures as policy-controlled execution errors.
catch (Exception ex) when (ex is not OperationCanceledException)
{
Exception failure = ex;
try
{
result = this._sandbox!.Run(code);
this.ClearSandboxState();
}
#pragma warning disable CA1031 // Surface sandbox execution failures as structured JSON rather than propagating.
catch (Exception ex)
#pragma warning restore CA1031
catch (Exception cleanupError) when (cleanupError is not OperationCanceledException)
{
return BuildErrorResult(ex.Message);
failure = new AggregateException(ex, cleanupError);
}

return BuildResult(result);
return BuildErrorResult(snapshot.IncludeDetailedErrors ? failure.ToString() : "Code execution failed.");
}
#pragma warning restore CA1031
finally
{
this._executionLock.Release();
Expand All @@ -254,12 +264,25 @@ private void EnsureInitialized(RunSnapshot snapshot)

// Configuration changed (or first run) — dispose the previous sandbox
// so the new one picks up the current capabilities and runtime options.
this._warmSnapshot?.Dispose();
this._sandbox?.Dispose();
this.ClearSandboxState();
this.BuildAndWarmUp(snapshot);
}

private void ClearSandboxState()
{
var warmSnapshot = this._warmSnapshot;
var sandbox = this._sandbox;
this._warmSnapshot = null;
this._sandbox = null;

this.BuildAndWarmUp(snapshot);
this._lastConfigFingerprint = null;
try
{
warmSnapshot?.Dispose();
}
finally
{
sandbox?.Dispose();
}
}

private void BuildAndWarmUp(RunSnapshot snapshot)
Expand Down Expand Up @@ -298,9 +321,10 @@ private void BuildAndWarmUp(RunSnapshot snapshot)
}

var sandbox = builder.Build();
this._sandbox = sandbox;

// Tools must be registered before the first Run() call.
ToolBridge.RegisterAll(sandbox, snapshot.Tools);
ToolBridge.RegisterAll(sandbox, snapshot.Tools, snapshot.IncludeDetailedErrors);

foreach (var allowedDomain in snapshot.AllowedDomains)
{
Expand All @@ -314,7 +338,6 @@ private void BuildAndWarmUp(RunSnapshot snapshot)
// upstream HyperlightSandbox.Extensions.AI CodeExecutionTool reference.
_ = sandbox.Run(snapshot.Backend == SandboxBackend.JavaScript ? "void 0;" : "None");
this._warmSnapshot = sandbox.Snapshot();
this._sandbox = sandbox;
this._lastConfigFingerprint = snapshot.ConfigFingerprint;
}

Expand All @@ -340,8 +363,13 @@ public void Dispose()
}

this._disposed = true;
this._warmSnapshot?.Dispose();
this._sandbox?.Dispose();
this._executionLock.Dispose();
try
{
this.ClearSandboxState();
}
finally
{
this._executionLock.Dispose();
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -21,35 +21,47 @@ internal static class ToolBridge
/// Registers every <paramref name="tools"/> entry against the provided
/// <paramref name="sandbox"/> as a raw JSON-in / JSON-out async tool.
/// </summary>
public static void RegisterAll(Sandbox sandbox, IReadOnlyList<AIFunction> tools)
public static void RegisterAll(Sandbox sandbox, IReadOnlyList<AIFunction> tools, bool includeDetailedErrors = false)
{
foreach (var tool in tools)
{
RegisterOne(sandbox, tool);
RegisterOne(sandbox, tool, includeDetailedErrors);
}
}

private static void RegisterOne(Sandbox sandbox, AIFunction tool)
private static void RegisterOne(Sandbox sandbox, AIFunction tool, bool includeDetailedErrors)
=> sandbox.RegisterToolAsync(
tool.Name,
async (string argsJson) => await InvokeAsync(tool, argsJson).ConfigureAwait(false));
async (string argsJson) => await InvokeAsync(tool, argsJson, includeDetailedErrors).ConfigureAwait(false));

internal static async Task<string> InvokeAsync(AIFunction tool, string argsJson)
internal static async Task<string> InvokeAsync(AIFunction tool, string argsJson, bool includeDetailedErrors = false)
{
try
{
var arguments = ParseArguments(argsJson);
IDictionary<string, object?> arguments;
try
{
arguments = ParseArguments(argsJson);
}
catch (Exception ex) when (ex is JsonException or ArgumentException)
{
return SerializeError(includeDetailedErrors ? ex.ToString() : ex.Message);
}

var result = await tool.InvokeAsync(new AIFunctionArguments(arguments)).ConfigureAwait(false);
return SerializeResult(result);
}
#pragma warning disable CA1031 // Catch all: we must surface every failure as a JSON error to the guest rather than crash the FFI boundary.
catch (Exception ex)
#pragma warning restore CA1031
{
return JsonSerializer.Serialize(new HyperlightToolError(ex.Message), HyperlightJsonContext.Default.HyperlightToolError);
return SerializeError(includeDetailedErrors ? ex.ToString() : "Host tool execution failed.");
}
}

private static string SerializeError(string message) =>
JsonSerializer.Serialize(new HyperlightToolError(message), HyperlightJsonContext.Default.HyperlightToolError);

internal static IDictionary<string, object?> ParseArguments(string argsJson)
{
if (string.IsNullOrWhiteSpace(argsJson))
Expand Down
19 changes: 19 additions & 0 deletions dotnet/src/Microsoft.Agents.AI.Hyperlight/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,25 @@ Both surfaces support:
the meantime.
* A Hyperlight Python guest module when using `SandboxBackend.Wasm`.

## Error diagnostics

Host tool failures return a generic JSON error by default. Host execution
exceptions returned by the executor also use a generic message.
`HyperlightCodeActProviderOptions.IncludeDetailedErrors` defaults to `false`
for both the provider and standalone function. Set it to `true` only for a
trusted channel: full exception details, including stack traces and inner
exceptions, can contain sensitive data. Argument-validation errors keep their
safe messages by default and include stack traces only with this opt-in.

This option is independent of the outer `FunctionInvokingChatClient` error policy
and sensitive-data logging. Outer error handling cannot redact diagnostics that
generated code has already caught and included in normal output. Run snapshots
capture the policy, and sandbox configuration fingerprints include it so cached
callbacks cannot retain a different disclosure policy.
The same boundary covers initialization, warm-up, snapshot restore, and execution
failures. Ordinary failures dispose and clear failed sandbox state before returning
an error; cancellation still propagates.

## Network access and guest packages

`HyperlightCodeActProviderOptions.AllowedDomains` controls outbound requests
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,18 @@ public CodeExecutor(
/// <summary>Immutable snapshot of provider state captured at the start of an invocation.</summary>
public sealed class RunSnapshot
{
public RunSnapshot(IReadOnlyList<AIFunction> tools, IReadOnlyList<FileMount> fileMounts)
public RunSnapshot(IReadOnlyList<AIFunction> tools, IReadOnlyList<FileMount> fileMounts, bool includeDetailedErrors = false)
{
this.Tools = tools;
this.FileMounts = fileMounts;
this.IncludeDetailedErrors = includeDetailedErrors;
}

public IReadOnlyList<AIFunction> Tools { get; }

public IReadOnlyList<FileMount> FileMounts { get; }

public bool IncludeDetailedErrors { get; }
}

public async Task<List<AIContent>> ExecuteAsync(RunSnapshot snapshot, string code, CancellationToken cancellationToken)
Expand All @@ -65,7 +68,8 @@ public async Task<List<AIContent>> ExecuteAsync(RunSnapshot snapshot, string cod
snapshot.Tools,
this._limits,
this._environment,
this._workingDirectory);
this._workingDirectory,
snapshot.IncludeDetailedErrors);

var result = await bridge.RunAsync(code, cancellationToken).ConfigureAwait(false);

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,21 +31,24 @@ internal sealed class ProcessBridge
private readonly ProcessExecutionLimits _limits;
private readonly IReadOnlyDictionary<string, string>? _environment;
private readonly string? _workingDirectory;
private readonly bool _includeDetailedErrors;

public ProcessBridge(
string pythonExecutable,
string runnerScript,
IReadOnlyList<AIFunction> tools,
ProcessExecutionLimits limits,
IReadOnlyDictionary<string, string>? environment,
string? workingDirectory)
string? workingDirectory,
bool includeDetailedErrors = false)
{
this._pythonExecutable = pythonExecutable;
this._runnerScript = runnerScript;
this._tools = tools.ToDictionary(t => t.Name, StringComparer.Ordinal);
this._limits = limits;
this._environment = environment;
this._workingDirectory = workingDirectory;
this._includeDetailedErrors = includeDetailedErrors;
}

/// <summary>Represents the parsed final result returned by the Python runner.</summary>
Expand Down Expand Up @@ -264,7 +267,9 @@ await SendToolResponseAsync(process, callId, ok: false, result: null,
#pragma warning restore CA1031
{
await SendToolResponseAsync(process, callId, ok: false, result: null,
excType: ex.GetType().Name, excMessage: ex.Message, cancellationToken).ConfigureAwait(false);
excType: this._includeDetailedErrors ? ex.GetType().Name : "RuntimeError",
excMessage: this._includeDetailedErrors ? ex.ToString() : "Host tool execution failed.",
cancellationToken).ConfigureAwait(false);
}
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ public sealed class LocalCodeActProvider : AIContextProvider, IDisposable

private readonly CodeExecutor _executor;
private readonly LocalCodeActApprovalMode _approvalMode;
private readonly bool _includeDetailedErrors;

private readonly ConcurrentDictionary<string, AIFunction> _tools = new(StringComparer.Ordinal);
private readonly ConcurrentDictionary<string, FileMount> _fileMounts = new(StringComparer.Ordinal);
Expand Down Expand Up @@ -68,6 +69,7 @@ public LocalCodeActProvider(string pythonExecutablePath, LocalCodeActProviderOpt
}

this._approvalMode = options.ApprovalMode;
this._includeDetailedErrors = options.IncludeDetailedErrors;

this._executor = new CodeExecutor(
pythonExecutablePath,
Expand Down Expand Up @@ -190,7 +192,8 @@ protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext co
this.ThrowIfDisposed();
snapshot = new CodeExecutor.RunSnapshot(
this._tools.Values.ToList(),
this._fileMounts.Values.ToList());
this._fileMounts.Values.ToList(),
this._includeDetailedErrors);

FeatureUsageMarker.MarkUsed();
var approvalRequired = ComputeApprovalRequired(this._approvalMode, snapshot.Tools);
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,17 @@ public sealed class LocalCodeActProviderOptions
/// </remarks>
public LocalCodeActApprovalMode ApprovalMode { get; set; } = LocalCodeActApprovalMode.NeverRequire;

/// <summary>
/// Gets or sets whether host exception details are exposed to generated code.
/// Defaults to <see langword="false"/>.
/// </summary>
/// <remarks>
/// Detailed errors include exception types, stack traces, and inner exceptions.
/// Enable only for a trusted channel: diagnostics can contain sensitive host data.
/// This is independent of the outer chat client's error policy and sensitive-data logging.
/// </remarks>
public bool IncludeDetailedErrors { get; set; }

/// <summary>
/// Gets or sets the initial set of file mounts exposed to generated code.
/// </summary>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ public LocalExecuteCodeFunction(string pythonExecutablePath, LocalCodeActProvide
options.Environment,
options.WorkingDirectory);

this._snapshot = new CodeExecutor.RunSnapshot(tools, fileMounts);
this._snapshot = new CodeExecutor.RunSnapshot(tools, fileMounts, options.IncludeDetailedErrors);
this._inner = AIFunctionFactory.Create(
this.ExecuteCodeAsync,
new AIFunctionFactoryOptions
Expand Down
14 changes: 14 additions & 0 deletions dotnet/src/Microsoft.Agents.AI.LocalCodeAct/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,20 @@ using var provider = new LocalCodeActProvider("/usr/bin/python3", options);
// Register provider with your AIAgent's context providers.
```

## Error diagnostics

Host tool failures send a generic failed response to generated Python code by
default. `LocalCodeActProviderOptions.IncludeDetailedErrors` defaults to `false`
for both the provider and standalone function. Set it to `true` only for a
trusted channel: full exception details, including stack traces and inner
exceptions, can contain sensitive data.

The policy is captured at construction and passed through run snapshots. It is
independent of the outer `FunctionInvokingChatClient` error policy and
sensitive-data logging. Outer error handling still applies to uncaught failures,
but cannot redact diagnostics that generated code has already caught and printed
or returned. Successful results and failure signaling are unchanged.

## What the Package Controls

- **AST validation** (default on): Validates generated code against allow-lists
Expand Down
Loading
Loading