@agent-api/sdk 1.2.3 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog — @agent-api/sdk
 
+## 1.3.1
+
+### Fixed
+
+- Made `local_workdir` grep behave like familiar grep: `path` may be omitted, a file path, or a directory subtree.
+- Model-facing `local_workdir` execution errors now return structured `{ ok: false, error }` tool results instead of aborting agent runs.
+
+## 1.3.0
+
+### Added
+
+- Added SDK support for `local_shell` isolation modes: `none`, `auto`, and `required`.
+- Added `IsolatorLocalShellRunner`, a Node-local runner that delegates shell execution to the shared `agent-isolator` binary.
+- Added model-facing `shell_isolation` metadata for approval previews and execution results.
+
+### Changed
+
+- `local_shell` auto isolation now tries an explicitly configured `agent-isolator` path first and falls back to direct host execution when isolation is unavailable.
+- SDKs no longer assume `agent-isolator` is discoverable on `PATH`; pass `isolator.executablePath` or set `AGENT_ISOLATOR_PATH`.
+- Direct host execution remains the default/fallback path and reports its actual non-isolated guarantees.
+
 ## 1.2.3
 
 ### Fixed

package/README.md

@@ -199,6 +199,14 @@ Keep UI and OS interaction policy in your host framework. Electron, Tauri, Qt, o
 
 `local_shell` executes commands through a pluggable command runner. The default `HostLocalShellRunner` runs on the user's local machine, bounds captured output, enforces a timeout, and confines relative `workdir` overrides under the configured cwd. It is not a security sandbox; use approval mode unless your application intentionally grants full local command access.
 
+For OS-level isolation, install the standalone `agent-isolator` binary from the
+GitHub Release artifacts and pass its explicit path through
+`isolator.executablePath` or `AGENT_ISOLATOR_PATH`. `isolation: "auto"` tries
+that configured isolator first and falls back to direct execution if it is
+missing or unavailable. `isolation: "required"` fails closed when an isolating
+runner cannot be selected. The SDK does not search `PATH`, run postinstall
+scripts, or build native binaries during package installation.
+
 ```typescript
 const workdir = local.data.child("workdirs/demo");
 

package/dist/local/core.d.ts

@@ -309,6 +309,7 @@ export declare class LocalFileStore {
     readLines(relativePath: string, params: LocalReadLinesParams): Promise<LocalFileLines>;
     patchLines(relativePath: string, params: LocalPatchLinesParams): Promise<LocalFileLinesPatch>;
     grep(params: LocalGrepParams): Promise<LocalGrepResponse>;
+    private grepCandidates;
     summarize(params?: LocalSummarizeParams): Promise<LocalSummary>;
     private walk;
 }

package/dist/local/core.js

@@ -310,7 +310,7 @@ export class LocalFileStore {
         const maxFiles = positiveInt(params.maxFiles, 500);
         const maxBytesPerFile = positiveInt(params.maxBytesPerFile, 512 * 1024);
         const maxLineLength = positiveInt(params.maxLineLength, 500);
-        const stats = await this.list(params.path ?? ".", { recursive: true, ignore: params.ignore });
+        const stats = await this.grepCandidates(params.path ?? ".", params.ignore);
         const matches = [];
         let filesScanned = 0;
         let scanTruncated = false;
@@ -348,6 +348,27 @@ export class LocalFileStore {
         }
         return { object: "list", matches, files_scanned: filesScanned, scan_truncated: scanTruncated };
     }
+    async grepCandidates(relativePath, ignore) {
+        const fullPath = this.resolvePath(relativePath);
+        const info = await stat(fullPath);
+        const portablePath = toPortablePath(path.relative(this.root, fullPath)) || ".";
+        if (ignored(portablePath, ignore)) {
+            return [];
+        }
+        if (info.isFile()) {
+            return [{
+                    path: portablePath,
+                    fullPath,
+                    type: "file",
+                    size: info.size,
+                    modifiedAt: info.mtime,
+                }];
+        }
+        if (info.isDirectory()) {
+            return await this.list(relativePath, { recursive: true, ignore });
+        }
+        return [];
+    }
     async summarize(params = {}) {
         const maxFiles = positiveInt(params.maxFiles, 2000);
         const maxPreviews = positiveInt(params.maxPreviews, 20);

package/dist/local/shell.d.ts

@@ -1,6 +1,52 @@
 import type { FunctionTool } from "../types/tools.js";
 import type { LocalWorkdir } from "./core.js";
 export type LocalShellAccessMode = "approval" | "full";
+/**
+ * Requested isolation policy for local shell execution.
+ * - none: direct host execution.
+ * - auto: use an isolating runner when the host app provides one; otherwise fall back to direct execution.
+ * - required: fail closed unless the configured runner reports real isolation.
+ */
+export type LocalShellIsolationMode = "none" | "auto" | "required";
+export interface LocalShellIsolationGuarantees {
+    filesystem: "none" | "workdir-mounted" | "policy-enforced";
+    network: "allowed" | "blocked" | "configurable";
+    user: "host-user" | "unprivileged-user" | "namespace-user";
+    process: "host-process-tree" | "child-contained" | "pid-namespace";
+    resources: "none" | "timeout-only" | "cpu-memory-limits";
+}
+export interface LocalShellIsolationResourceOptions {
+    memoryMb?: number;
+    cpuCount?: number;
+}
+export interface LocalShellIsolationOptions {
+    filesystem?: "host" | "workdir-readonly" | "workdir-readwrite";
+    network?: "allowed" | "blocked";
+    env?: "inherit" | "minimal";
+    resources?: LocalShellIsolationResourceOptions;
+}
+export interface LocalShellIsolationStatus {
+    executor: "direct" | "isolator";
+    driver: string;
+    isolated: boolean;
+    fallback: boolean;
+    requested: Required<LocalShellIsolationOptions> & {
+        resources: LocalShellIsolationResourceOptions;
+    };
+    guarantees: LocalShellIsolationGuarantees;
+    warnings: string[];
+}
+export interface LocalShellIsolatorStatusResult {
+    version?: string;
+    driver: string;
+    status: LocalShellIsolationStatus;
+    drivers?: Array<{
+        name: string;
+        platform: string;
+        available: boolean;
+        warnings?: string[];
+    }>;
+}
 export interface LocalShellRequest {
     command: string;
     description?: string;
@@ -24,8 +70,10 @@ export interface LocalShellResult {
     duration_ms: number;
     timed_out: boolean;
     truncated: boolean;
+    shell_isolation: LocalShellIsolationStatus;
 }
 export interface LocalCommandRunner {
+    readonly isolationStatus?: LocalShellIsolationStatus;
     run(request: LocalShellRequest, context?: LocalShellContext): Promise<LocalShellResult>;
 }
 export interface HostLocalShellRunnerOptions {
@@ -34,6 +82,15 @@ export interface HostLocalShellRunnerOptions {
     timeoutMs?: number;
     maxOutputBytes?: number;
     env?: NodeJS.ProcessEnv;
+    isolationOptions?: LocalShellIsolationOptions;
+}
+export interface IsolatorLocalShellRunnerOptions {
+    executablePath?: string;
+    driver?: "auto" | "direct" | "bwrap" | "sandbox-exec" | "windows-job" | string;
+    cwd?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    isolationOptions?: LocalShellIsolationOptions;
 }
 export declare class HostLocalShellRunner implements LocalCommandRunner {
     readonly cwd: string;
@@ -41,11 +98,27 @@ export declare class HostLocalShellRunner implements LocalCommandRunner {
     readonly timeoutMs: number;
     readonly maxOutputBytes: number;
     readonly env: NodeJS.ProcessEnv;
+    readonly isolationStatus: LocalShellIsolationStatus;
     constructor(options?: HostLocalShellRunnerOptions);
     run(request: LocalShellRequest, context?: LocalShellContext): Promise<LocalShellResult>;
 }
+export declare class IsolatorLocalShellRunner implements LocalCommandRunner {
+    readonly executablePath: string;
+    readonly driver: string;
+    readonly cwd: string;
+    readonly timeoutMs: number;
+    readonly maxOutputBytes: number;
+    readonly isolationOptions: LocalShellIsolationOptions;
+    readonly isolationStatus: LocalShellIsolationStatus;
+    readonly statusResult: LocalShellIsolatorStatusResult;
+    constructor(options?: IsolatorLocalShellRunnerOptions);
+    run(request: LocalShellRequest, context?: LocalShellContext): Promise<LocalShellResult>;
+}
 export interface LocalShellToolRegistryOptions {
     accessMode?: LocalShellAccessMode;
+    isolation?: LocalShellIsolationMode;
+    isolationOptions?: LocalShellIsolationOptions;
+    isolator?: IsolatorLocalShellRunnerOptions | boolean;
     toolName?: string;
     runner?: LocalCommandRunner;
     cwd?: string;
@@ -56,6 +129,8 @@ export interface LocalShellToolRegistryOptions {
 }
 export interface LocalShellToolPresentationOptions {
     accessMode?: LocalShellAccessMode;
+    isolationStatus?: LocalShellIsolationStatus;
+    isolationOptions?: LocalShellIsolationOptions;
     cwd?: string;
     shell?: string | boolean;
     platform?: NodeJS.Platform;
@@ -73,6 +148,7 @@ export interface LocalShellToolRegistry {
 export declare class LocalShellDriver {
     readonly accessMode: LocalShellAccessMode;
     readonly runner: LocalCommandRunner;
+    readonly isolationStatus: LocalShellIsolationStatus;
     constructor(options?: LocalShellToolRegistryOptions);
     dispatch(args: Record<string, unknown>, context?: LocalShellContext): Promise<Record<string, unknown>>;
     requiresApproval(): boolean;

package/dist/local/shell.js

@@ -1,4 +1,4 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import path from "node:path";
 export class HostLocalShellRunner {
     cwd;
@@ -6,12 +6,14 @@ export class HostLocalShellRunner {
     timeoutMs;
     maxOutputBytes;
     env;
+    isolationStatus;
     constructor(options = {}) {
         this.cwd = path.resolve(options.cwd ?? process.cwd());
         this.shell = options.shell ?? true;
         this.timeoutMs = positiveInteger(options.timeoutMs, 2 * 60 * 1000, "timeoutMs");
         this.maxOutputBytes = positiveInteger(options.maxOutputBytes, 128 * 1024, "maxOutputBytes");
         this.env = { ...process.env, ...(options.env ?? {}) };
+        this.isolationStatus = directIsolationStatus(false, options.isolationOptions);
     }
     async run(request, context = {}) {
         const command = requiredString(request.command, "command");
@@ -54,6 +56,7 @@ export class HostLocalShellRunner {
                     duration_ms: Date.now() - started,
                     timed_out: timedOut,
                     truncated: stdout.truncated || stderr.truncated,
+                    shell_isolation: this.isolationStatus,
                 });
             };
             const kill = () => {
@@ -93,23 +96,61 @@ export class HostLocalShellRunner {
         });
     }
 }
+export class IsolatorLocalShellRunner {
+    executablePath;
+    driver;
+    cwd;
+    timeoutMs;
+    maxOutputBytes;
+    isolationOptions;
+    isolationStatus;
+    statusResult;
+    constructor(options = {}) {
+        this.executablePath = resolveIsolatorExecutablePath(options.executablePath);
+        this.driver = options.driver ?? "auto";
+        this.cwd = path.resolve(options.cwd ?? process.cwd());
+        this.timeoutMs = positiveInteger(options.timeoutMs, 2 * 60 * 1000, "timeoutMs");
+        this.maxOutputBytes = positiveInteger(options.maxOutputBytes, 128 * 1024, "maxOutputBytes");
+        this.isolationOptions = options.isolationOptions ?? {};
+        this.statusResult = isolatorStatusSync(this.executablePath, this.driver);
+        this.isolationStatus = this.statusResult.status;
+    }
+    async run(request, context = {}) {
+        const command = requiredString(request.command, "command");
+        const cwd = resolveContainedPath(this.cwd, request.workdir);
+        const timeoutMs = request.timeoutMs == null
+            ? this.timeoutMs
+            : positiveInteger(request.timeoutMs, this.timeoutMs, "timeoutMs");
+        const response = await isolatorRequest(this.executablePath, this.driver, {
+            id: `run_${Date.now().toString(36)}`,
+            method: "run",
+            params: {
+                command,
+                description: request.description,
+                cwd,
+                timeout_ms: timeoutMs,
+                max_output_bytes: this.maxOutputBytes,
+                env: request.env,
+                isolation: this.isolationOptions,
+            },
+        }, context);
+        return isolatorRunResult(response.result);
+    }
+}
 export class LocalShellDriver {
     accessMode;
     runner;
+    isolationStatus;
     constructor(options = {}) {
         const cwd = options.workdir?.root ?? options.cwd;
         this.accessMode = options.accessMode ?? "approval";
-        this.runner = options.runner ?? new HostLocalShellRunner({
-            cwd,
-            shell: options.shell,
-            timeoutMs: options.timeoutMs,
-            maxOutputBytes: options.maxOutputBytes,
-        });
+        this.runner = resolveShellRunner(options, cwd);
+        this.isolationStatus = this.runner.isolationStatus ?? directIsolationStatus(options.isolation === "auto", options.isolationOptions);
     }
     async dispatch(args, context = {}) {
         const request = shellRequest(args);
         if (this.accessMode !== "full") {
-            return shellApprovalRequired(request);
+            return shellApprovalRequired(request, this.isolationStatus);
         }
         return shellToolResult(await this.runner.run(request, context));
     }
@@ -117,16 +158,80 @@ export class LocalShellDriver {
         return this.accessMode !== "full";
     }
 }
+function resolveShellRunner(options, cwd) {
+    if (options.runner) {
+        if (options.isolation === "required" && options.runner.isolationStatus?.isolated !== true) {
+            throw new Error("local_shell isolation is required, but the configured runner does not report isolation");
+        }
+        return options.runner;
+    }
+    let isolatorFallbackWarning;
+    if (options.isolation === "auto" || options.isolation === "required" || options.isolator) {
+        const isolatorOptions = typeof options.isolator === "object" ? options.isolator : {};
+        try {
+            const runner = new IsolatorLocalShellRunner({
+                cwd,
+                timeoutMs: options.timeoutMs,
+                maxOutputBytes: options.maxOutputBytes,
+                isolationOptions: options.isolationOptions,
+                ...isolatorOptions,
+            });
+            if (options.isolation === "required" && runner.isolationStatus.isolated !== true) {
+                throw new Error(`local_shell isolation is required, but agent-isolator selected non-isolated driver ${runner.isolationStatus.driver}`);
+            }
+            if (options.isolation !== "none" || options.isolator) {
+                return runner;
+            }
+        }
+        catch (error) {
+            if (options.isolation === "required") {
+                throw error;
+            }
+            isolatorFallbackWarning = errorMessage(error);
+        }
+    }
+    const runner = new HostLocalShellRunner({
+        cwd,
+        shell: options.shell,
+        timeoutMs: options.timeoutMs,
+        maxOutputBytes: options.maxOutputBytes,
+        isolationOptions: options.isolationOptions,
+    });
+    if (options.isolation === "auto") {
+        let status = directIsolationStatus(true, options.isolationOptions);
+        if (isolatorFallbackWarning) {
+            status = {
+                ...status,
+                warnings: [...status.warnings, `Isolator unavailable: ${isolatorFallbackWarning}`],
+            };
+        }
+        return withIsolationStatus(runner, status);
+    }
+    return runner;
+}
+function resolveIsolatorExecutablePath(explicitPath) {
+    const configured = (explicitPath?.trim() || process.env.AGENT_ISOLATOR_PATH?.trim() || "");
+    if (!configured) {
+        throw new Error("agent-isolator executable path is not configured; pass isolator.executablePath or set AGENT_ISOLATOR_PATH");
+    }
+    return configured;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 export function createLocalShellToolRegistry(options = {}) {
     const toolName = options.toolName ?? "local_shell";
     const driver = new LocalShellDriver(options);
     const hostRunner = driver.runner instanceof HostLocalShellRunner ? driver.runner : undefined;
+    const isolatorRunner = driver.runner instanceof IsolatorLocalShellRunner ? driver.runner : undefined;
     const definition = localShellToolDefinition(toolName, {
         accessMode: driver.accessMode,
-        cwd: options.workdir?.root ?? hostRunner?.cwd ?? options.cwd,
+        cwd: options.workdir?.root ?? hostRunner?.cwd ?? isolatorRunner?.cwd ?? options.cwd,
         shell: hostRunner?.shell ?? options.shell,
-        timeoutMs: hostRunner?.timeoutMs ?? options.timeoutMs,
-        maxOutputBytes: hostRunner?.maxOutputBytes ?? options.maxOutputBytes,
+        timeoutMs: hostRunner?.timeoutMs ?? isolatorRunner?.timeoutMs ?? options.timeoutMs,
+        maxOutputBytes: hostRunner?.maxOutputBytes ?? isolatorRunner?.maxOutputBytes ?? options.maxOutputBytes,
+        isolationStatus: driver.isolationStatus,
+        isolationOptions: options.isolationOptions,
     });
     return {
         accessMode: driver.accessMode,
@@ -158,13 +263,16 @@ function localShellToolDescription(options = {}) {
     const platform = options.platform ?? process.platform;
     const shell = shellDisplayName(options.shell);
     const accessMode = options.accessMode ?? "approval";
+    const isolation = options.isolationStatus ?? directIsolationStatus(false, options.isolationOptions);
     const cwd = options.cwd ? path.resolve(options.cwd) : undefined;
     const timeoutMs = options.timeoutMs ?? 2 * 60 * 1000;
     const maxOutputBytes = options.maxOutputBytes ?? 128 * 1024;
     return [
         "Run a local shell command through one model-facing primitive.",
         "Prefer local_workdir for file discovery, reading, and editing. Use local_shell for package managers, tests, build commands, git, and other process-level tasks.",
-        `Execution environment: platform=${platform}; shell=${shell}; access_mode=${accessMode}; default_timeout_ms=${timeoutMs}; max_output_bytes=${maxOutputBytes}.`,
+        `Execution environment: platform=${platform}; shell=${shell}; access_mode=${accessMode}; isolation_driver=${isolation.driver}; isolated=${isolation.isolated}; fallback=${isolation.fallback}; default_timeout_ms=${timeoutMs}; max_output_bytes=${maxOutputBytes}.`,
+        isolationRequestDescription(isolation.requested),
+        isolation.warnings.length > 0 ? `Isolation warning: ${isolation.warnings.join(" ")}` : "",
         cwd ? `Default cwd: ${cwd}. Relative command paths resolve from this cwd unless workdir is set.` : "Relative command paths resolve from the configured cwd unless workdir is set.",
         "The workdir parameter must be a relative child path of the configured cwd. Use workdir instead of cd when possible.",
         "Absolute paths inside the command are permitted by the host OS if the user/process has permission; this tool is not a filesystem sandbox or security sandbox.",
@@ -206,7 +314,7 @@ function shellRequest(args) {
         timeoutMs: optionalNumber(args.timeoutMs ?? args.timeout_ms, "timeout_ms"),
     };
 }
-function shellApprovalRequired(request) {
+function shellApprovalRequired(request, isolationStatus) {
     return {
         ok: false,
         requires_approval: true,
@@ -215,9 +323,235 @@ function shellApprovalRequired(request) {
         description: request.description,
         workdir: request.workdir,
         timeout_ms: request.timeoutMs,
+        shell_isolation: isolationStatus,
         message: "local_shell command execution requires approval",
     };
 }
+function directIsolationStatus(fallback, options = {}) {
+    const requested = normalizeIsolationOptions(options);
+    const warnings = directIsolationWarnings(fallback, requested);
+    return {
+        executor: "direct",
+        driver: "direct",
+        isolated: false,
+        fallback,
+        requested,
+        guarantees: {
+            filesystem: "none",
+            network: "allowed",
+            user: "host-user",
+            process: "host-process-tree",
+            resources: "timeout-only",
+        },
+        warnings,
+    };
+}
+function normalizeIsolationOptions(options = {}) {
+    return {
+        filesystem: options.filesystem ?? "host",
+        network: options.network ?? "allowed",
+        env: options.env ?? "inherit",
+        resources: {
+            memoryMb: options.resources?.memoryMb,
+            cpuCount: options.resources?.cpuCount,
+        },
+    };
+}
+function directIsolationWarnings(fallback, requested) {
+    const warnings = [
+        fallback
+            ? "No local shell isolator is configured; falling back to direct host execution."
+            : "Direct host execution has no OS-level isolation.",
+    ];
+    if (requested.filesystem !== "host") {
+        warnings.push(`Requested filesystem isolation (${requested.filesystem}) is not enforced by direct execution.`);
+    }
+    if (requested.network === "blocked") {
+        warnings.push("Requested network blocking is not enforced by direct execution.");
+    }
+    if (requested.env === "minimal") {
+        warnings.push("Requested minimal environment is not enforced by direct execution.");
+    }
+    if (requested.resources.memoryMb != null || requested.resources.cpuCount != null) {
+        warnings.push("Requested CPU or memory limits are not enforced by direct execution.");
+    }
+    return warnings;
+}
+function isolationRequestDescription(options) {
+    const resources = [
+        options.resources.memoryMb == null ? "" : `memory_mb=${options.resources.memoryMb}`,
+        options.resources.cpuCount == null ? "" : `cpu_count=${options.resources.cpuCount}`,
+    ].filter(Boolean).join("; ");
+    return `Requested isolation: filesystem=${options.filesystem}; network=${options.network}; env=${options.env}${resources ? `; ${resources}` : ""}.`;
+}
+function withIsolationStatus(runner, status) {
+    Object.defineProperty(runner, "isolationStatus", {
+        configurable: true,
+        enumerable: true,
+        value: status,
+    });
+    return runner;
+}
+function isolatorStatusSync(executablePath, driver) {
+    const request = JSON.stringify({ id: "status", method: "status", params: {} });
+    const result = spawnSync(executablePath, ["--once", `--driver=${driver}`], {
+        input: request,
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024,
+        windowsHide: true,
+    });
+    if (result.error) {
+        throw result.error;
+    }
+    if (result.status !== 0) {
+        throw new Error((result.stderr || result.stdout || `agent-isolator exited with status ${result.status}`).trim());
+    }
+    const envelope = parseIsolatorEnvelope(result.stdout);
+    if (envelope.error) {
+        throw new Error(envelope.error.message || envelope.error.code || "agent-isolator status failed");
+    }
+    return isolatorStatusResult(envelope.result);
+}
+async function isolatorRequest(executablePath, driver, envelope, context) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(executablePath, ["--once", `--driver=${driver}`], {
+            stdio: ["pipe", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const stdout = new BoundedText(1024 * 1024);
+        const stderr = new BoundedText(1024 * 1024);
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            context.signal?.removeEventListener("abort", abort);
+            if (error) {
+                reject(error);
+                return;
+            }
+            try {
+                const parsed = parseIsolatorEnvelope(stdout.text());
+                if (parsed.error) {
+                    reject(new Error(parsed.error.message || parsed.error.code || "agent-isolator request failed"));
+                    return;
+                }
+                resolve({ result: parsed.result });
+            }
+            catch (parseError) {
+                const details = stderr.text();
+                reject(new Error(`${parseError instanceof Error ? parseError.message : String(parseError)}${details ? `: ${details}` : ""}`));
+            }
+        };
+        const abort = () => {
+            if (!child.killed)
+                child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+        };
+        if (context.signal?.aborted) {
+            abort();
+        }
+        else {
+            context.signal?.addEventListener("abort", abort, { once: true });
+        }
+        child.stdout?.on("data", (chunk) => stdout.append(chunk));
+        child.stderr?.on("data", (chunk) => stderr.append(chunk));
+        child.on("error", finish);
+        child.on("close", (code) => {
+            if (code !== 0) {
+                finish(new Error((stderr.text() || stdout.text() || `agent-isolator exited with status ${code}`).trim()));
+                return;
+            }
+            finish();
+        });
+        child.stdin?.end(JSON.stringify(envelope));
+    });
+}
+function parseIsolatorEnvelope(text) {
+    const trimmed = text.trim();
+    if (!trimmed) {
+        throw new Error("agent-isolator returned an empty response");
+    }
+    return JSON.parse(trimmed);
+}
+function isolatorStatusResult(value) {
+    if (!isRecord(value)) {
+        throw new Error("agent-isolator status result must be an object");
+    }
+    return {
+        version: typeof value.version === "string" ? value.version : undefined,
+        driver: requiredString(value.driver, "driver"),
+        status: isolationStatusFromUnknown(value.status),
+        drivers: Array.isArray(value.drivers)
+            ? value.drivers.filter(isRecord).map((item) => ({
+                name: String(item.name ?? ""),
+                platform: String(item.platform ?? ""),
+                available: item.available === true,
+                warnings: Array.isArray(item.warnings) ? item.warnings.map(String) : undefined,
+            }))
+            : undefined,
+    };
+}
+function isolatorRunResult(value) {
+    if (!isRecord(value)) {
+        throw new Error("agent-isolator run result must be an object");
+    }
+    return {
+        ok: value.ok === true,
+        command: requiredString(value.command, "command"),
+        description: optionalString(value.description, "description"),
+        cwd: requiredString(value.cwd, "cwd"),
+        exit_code: typeof value.exit_code === "number" ? value.exit_code : null,
+        signal: typeof value.signal === "string" ? value.signal : null,
+        stdout: typeof value.stdout === "string" ? value.stdout : "",
+        stderr: typeof value.stderr === "string" ? value.stderr : "",
+        output: typeof value.output === "string" ? value.output : "(no output)",
+        duration_ms: typeof value.duration_ms === "number" ? value.duration_ms : 0,
+        timed_out: value.timed_out === true,
+        truncated: value.truncated === true,
+        shell_isolation: isolationStatusFromUnknown(value.shell_isolation),
+    };
+}
+function isolationStatusFromUnknown(value) {
+    if (!isRecord(value)) {
+        throw new Error("shell isolation status must be an object");
+    }
+    return {
+        executor: value.executor === "isolator" ? "isolator" : "direct",
+        driver: requiredString(value.driver, "shell_isolation.driver"),
+        isolated: value.isolated === true,
+        fallback: value.fallback === true,
+        requested: normalizeIsolationOptions(isRecord(value.requested) ? isolationOptionsFromUnknown(value.requested) : {}),
+        guarantees: isolationGuaranteesFromUnknown(value.guarantees),
+        warnings: Array.isArray(value.warnings) ? value.warnings.map(String) : [],
+    };
+}
+function isolationOptionsFromUnknown(value) {
+    const resources = isRecord(value.resources) ? value.resources : {};
+    return {
+        filesystem: value.filesystem === "workdir-readonly" || value.filesystem === "workdir-readwrite" || value.filesystem === "host"
+            ? value.filesystem
+            : undefined,
+        network: value.network === "blocked" || value.network === "allowed" ? value.network : undefined,
+        env: value.env === "minimal" || value.env === "inherit" ? value.env : undefined,
+        resources: {
+            memoryMb: typeof resources.memoryMb === "number" ? resources.memoryMb : undefined,
+            cpuCount: typeof resources.cpuCount === "number" ? resources.cpuCount : undefined,
+        },
+    };
+}
+function isolationGuaranteesFromUnknown(value) {
+    const record = isRecord(value) ? value : {};
+    return {
+        filesystem: record.filesystem === "workdir-mounted" || record.filesystem === "policy-enforced" ? record.filesystem : "none",
+        network: record.network === "blocked" || record.network === "configurable" ? record.network : "allowed",
+        user: record.user === "unprivileged-user" || record.user === "namespace-user" ? record.user : "host-user",
+        process: record.process === "child-contained" || record.process === "pid-namespace" ? record.process : "host-process-tree",
+        resources: record.resources === "cpu-memory-limits" ? "cpu-memory-limits" : record.resources === "timeout-only" ? "timeout-only" : "none",
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function shellToolResult(result) {
     return {
         ...result,

package/dist/local/tools.d.ts

@@ -23,6 +23,7 @@ export declare class LocalWorkdirDriver {
     readonly accessMode: LocalWorkdirAccessMode;
     constructor(workdir: LocalWorkdir, options?: LocalWorkdirDriverOptions);
     dispatch(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private dispatchUnsafe;
     requiresApproval(args: Record<string, unknown>): boolean;
     private dispatchApplyEdits;
     private dispatchWrite;