@agent-api/sdk 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog — @agent-api/sdk
 
+## 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
+
+- Hardened local workdir scans so broken symlinks and files that disappear during recursive list, grep, and summarize operations do not abort the scan.
+
 ## 1.2.2
 
 ### Added

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.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { constants as fsConstants, watch as watchFS } from "node:fs";
-import { access, copyFile, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { access, copyFile, lstat, mkdir, readdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { localSkillFromDirectory } from "../local-skills.js";
@@ -322,12 +322,15 @@ export class LocalFileStore {
             if (item.type !== "file" || item.size > maxBytesPerFile || !isLikelyTextFile(item.path)) {
                 continue;
             }
-            const raw = await readFile(item.fullPath);
+            const raw = await readOptionalFile(item.fullPath);
+            if (!raw) {
+                continue;
+            }
             if (looksBinary(raw)) {
                 continue;
             }
             filesScanned++;
-            const lines = splitLines(raw.toString("utf8"));
+            const lines = splitLines(Buffer.from(raw).toString("utf8"));
             for (let i = 0; i < lines.length; i++) {
                 if (!lines[i].includes(pattern)) {
                     continue;
@@ -363,7 +366,10 @@ export class LocalFileStore {
             if (!isLikelyTextFile(item.path) || item.size > previewBytes * 4) {
                 continue;
             }
-            const raw = await readFile(item.fullPath);
+            const raw = await readOptionalFile(item.fullPath);
+            if (!raw) {
+                continue;
+            }
             if (looksBinary(raw)) {
                 continue;
             }
@@ -371,7 +377,7 @@ export class LocalFileStore {
             previews.push({
                 path: item.path,
                 size: item.size,
-                preview: raw.subarray(0, previewBytes).toString("utf8"),
+                preview: Buffer.from(raw.subarray(0, previewBytes)).toString("utf8"),
                 preview_truncated: truncated || undefined,
             });
         }
@@ -393,7 +399,10 @@ export class LocalFileStore {
             if (ignored(relativePath, options.ignore)) {
                 continue;
             }
-            const info = await stat(fullPath);
+            const info = await lstatOptional(fullPath);
+            if (!info) {
+                continue;
+            }
             const item = {
                 path: relativePath,
                 fullPath,
@@ -401,7 +410,7 @@ export class LocalFileStore {
                 size: info.size,
                 modifiedAt: info.mtime,
             };
-            if (entry.isDirectory()) {
+            if (info.isDirectory()) {
                 if (options.includeDirectories) {
                     out.push(item);
                 }
@@ -813,6 +822,28 @@ async function fileExists(fullPath) {
         return false;
     }
 }
+async function lstatOptional(fullPath) {
+    try {
+        return await lstat(fullPath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function readOptionalFile(fullPath) {
+    try {
+        return await readFile(fullPath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT" || error?.code === "ENOTDIR" || error?.code === "EISDIR") {
+            return null;
+        }
+        throw error;
+    }
+}
 function normalizeAppName(appName) {
     const trimmed = appName.trim();
     if (!trimmed) {

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/node.d.ts

@@ -1,8 +1,8 @@
 export * from "./index.js";
 export { NodeAgentAPI } from "./node-client.js";
 export { NodeSkillsResource } from "./resources/skills-node.js";
-export { createLocalShellToolRegistry, LocalWorkdirDriver, HostLocalShellRunner, LocalShellDriver, localShellToolDefinition, localShellToolInstructions, createLocalWorkdirToolRegistry, localWorkdirToolDefinition, localWorkdirToolInstructions, } from "./local/index.js";
-export type { LocalCommandRunner, LocalShellAccessMode, LocalShellContext, LocalShellRequest, LocalShellResult, LocalShellToolRegistry, LocalShellToolRegistryOptions, LocalWorkdirAction, LocalWorkdirAccessMode, LocalWorkdirToolRegistry, LocalWorkdirToolRegistryOptions, } from "./local/index.js";
+export { createLocalShellToolRegistry, LocalWorkdirDriver, HostLocalShellRunner, IsolatorLocalShellRunner, LocalShellDriver, localShellToolDefinition, localShellToolInstructions, createLocalWorkdirToolRegistry, localWorkdirToolDefinition, localWorkdirToolInstructions, } from "./local/index.js";
+export type { LocalCommandRunner, LocalShellAccessMode, LocalShellContext, LocalShellIsolationGuarantees, LocalShellIsolationMode, LocalShellIsolationOptions, LocalShellIsolationResourceOptions, LocalShellIsolationStatus, LocalShellIsolatorStatusResult, LocalShellRequest, LocalShellResult, LocalShellToolRegistry, LocalShellToolRegistryOptions, IsolatorLocalShellRunnerOptions, LocalWorkdirAction, LocalWorkdirAccessMode, LocalWorkdirToolRegistry, LocalWorkdirToolRegistryOptions, } from "./local/index.js";
 export { localSkillFromDirectory, pendingLocalSkillCalls, runLocalSkillHandlers } from "./local-skills.js";
 export type { LocalSkillDirectoryOptions } from "./local-skills.js";
 export * from "./local/index.js";

package/dist/node.js

@@ -1,6 +1,6 @@
 export * from "./index.js";
 export { NodeAgentAPI } from "./node-client.js";
 export { NodeSkillsResource } from "./resources/skills-node.js";
-export { createLocalShellToolRegistry, LocalWorkdirDriver, HostLocalShellRunner, LocalShellDriver, localShellToolDefinition, localShellToolInstructions, createLocalWorkdirToolRegistry, localWorkdirToolDefinition, localWorkdirToolInstructions, } from "./local/index.js";
+export { createLocalShellToolRegistry, LocalWorkdirDriver, HostLocalShellRunner, IsolatorLocalShellRunner, LocalShellDriver, localShellToolDefinition, localShellToolInstructions, createLocalWorkdirToolRegistry, localWorkdirToolDefinition, localWorkdirToolInstructions, } from "./local/index.js";
 export { localSkillFromDirectory, pendingLocalSkillCalls, runLocalSkillHandlers } from "./local-skills.js";
 export * from "./local/index.js";

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.2.2";
-export declare const USER_AGENT = "@agent-api/sdk/1.2.2";
+export declare const VERSION = "1.3.0";
+export declare const USER_AGENT = "@agent-api/sdk/1.3.0";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "1.2.2";
+export const VERSION = "1.3.0";
 export const USER_AGENT = `@agent-api/sdk/${VERSION}`;

package/dist-cjs/local/core.js

@@ -337,12 +337,15 @@ class LocalFileStore {
             if (item.type !== "file" || item.size > maxBytesPerFile || !isLikelyTextFile(item.path)) {
                 continue;
             }
-            const raw = await (0, promises_1.readFile)(item.fullPath);
+            const raw = await readOptionalFile(item.fullPath);
+            if (!raw) {
+                continue;
+            }
             if (looksBinary(raw)) {
                 continue;
             }
             filesScanned++;
-            const lines = splitLines(raw.toString("utf8"));
+            const lines = splitLines(Buffer.from(raw).toString("utf8"));
             for (let i = 0; i < lines.length; i++) {
                 if (!lines[i].includes(pattern)) {
                     continue;
@@ -378,7 +381,10 @@ class LocalFileStore {
             if (!isLikelyTextFile(item.path) || item.size > previewBytes * 4) {
                 continue;
             }
-            const raw = await (0, promises_1.readFile)(item.fullPath);
+            const raw = await readOptionalFile(item.fullPath);
+            if (!raw) {
+                continue;
+            }
             if (looksBinary(raw)) {
                 continue;
             }
@@ -386,7 +392,7 @@ class LocalFileStore {
             previews.push({
                 path: item.path,
                 size: item.size,
-                preview: raw.subarray(0, previewBytes).toString("utf8"),
+                preview: Buffer.from(raw.subarray(0, previewBytes)).toString("utf8"),
                 preview_truncated: truncated || undefined,
             });
         }
@@ -408,7 +414,10 @@ class LocalFileStore {
             if (ignored(relativePath, options.ignore)) {
                 continue;
             }
-            const info = await (0, promises_1.stat)(fullPath);
+            const info = await lstatOptional(fullPath);
+            if (!info) {
+                continue;
+            }
             const item = {
                 path: relativePath,
                 fullPath,
@@ -416,7 +425,7 @@ class LocalFileStore {
                 size: info.size,
                 modifiedAt: info.mtime,
             };
-            if (entry.isDirectory()) {
+            if (info.isDirectory()) {
                 if (options.includeDirectories) {
                     out.push(item);
                 }
@@ -833,6 +842,28 @@ async function fileExists(fullPath) {
         return false;
     }
 }
+async function lstatOptional(fullPath) {
+    try {
+        return await (0, promises_1.lstat)(fullPath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT" || error?.code === "ENOTDIR") {
+            return null;
+        }
+        throw error;
+    }
+}
+async function readOptionalFile(fullPath) {
+    try {
+        return await (0, promises_1.readFile)(fullPath);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT" || error?.code === "ENOTDIR" || error?.code === "EISDIR") {
+            return null;
+        }
+        throw error;
+    }
+}
 function normalizeAppName(appName) {
     const trimmed = appName.trim();
     if (!trimmed) {

package/dist-cjs/local/shell.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LocalShellDriver = exports.HostLocalShellRunner = void 0;
+exports.LocalShellDriver = exports.IsolatorLocalShellRunner = exports.HostLocalShellRunner = void 0;
 exports.createLocalShellToolRegistry = createLocalShellToolRegistry;
 exports.localShellToolDefinition = localShellToolDefinition;
 exports.localShellToolInstructions = localShellToolInstructions;
@@ -15,12 +15,14 @@ class HostLocalShellRunner {
     timeoutMs;
     maxOutputBytes;
     env;
+    isolationStatus;
     constructor(options = {}) {
         this.cwd = node_path_1.default.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");
@@ -63,6 +65,7 @@ class HostLocalShellRunner {
                     duration_ms: Date.now() - started,
                     timed_out: timedOut,
                     truncated: stdout.truncated || stderr.truncated,
+                    shell_isolation: this.isolationStatus,
                 });
             };
             const kill = () => {
@@ -103,23 +106,62 @@ class HostLocalShellRunner {
     }
 }
 exports.HostLocalShellRunner = HostLocalShellRunner;
+class IsolatorLocalShellRunner {
+    executablePath;
+    driver;
+    cwd;
+    timeoutMs;
+    maxOutputBytes;
+    isolationOptions;
+    isolationStatus;
+    statusResult;
+    constructor(options = {}) {
+        this.executablePath = resolveIsolatorExecutablePath(options.executablePath);
+        this.driver = options.driver ?? "auto";
+        this.cwd = node_path_1.default.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);
+    }
+}
+exports.IsolatorLocalShellRunner = IsolatorLocalShellRunner;
 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));
     }
@@ -128,16 +170,80 @@ class LocalShellDriver {
     }
 }
 exports.LocalShellDriver = LocalShellDriver;
+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);
+}
 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,
@@ -169,13 +275,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 ? node_path_1.default.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.",
@@ -217,7 +326,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,
@@ -226,9 +335,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 = (0, node_child_process_1.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 = (0, node_child_process_1.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-cjs/node.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.runLocalSkillHandlers = exports.pendingLocalSkillCalls = exports.localSkillFromDirectory = exports.localWorkdirToolInstructions = exports.localWorkdirToolDefinition = exports.createLocalWorkdirToolRegistry = exports.localShellToolInstructions = exports.localShellToolDefinition = exports.LocalShellDriver = exports.HostLocalShellRunner = exports.LocalWorkdirDriver = exports.createLocalShellToolRegistry = exports.NodeSkillsResource = exports.NodeAgentAPI = void 0;
+exports.runLocalSkillHandlers = exports.pendingLocalSkillCalls = exports.localSkillFromDirectory = exports.localWorkdirToolInstructions = exports.localWorkdirToolDefinition = exports.createLocalWorkdirToolRegistry = exports.localShellToolInstructions = exports.localShellToolDefinition = exports.LocalShellDriver = exports.IsolatorLocalShellRunner = exports.HostLocalShellRunner = exports.LocalWorkdirDriver = exports.createLocalShellToolRegistry = exports.NodeSkillsResource = exports.NodeAgentAPI = void 0;
 __exportStar(require("./index.js"), exports);
 var node_client_js_1 = require("./node-client.js");
 Object.defineProperty(exports, "NodeAgentAPI", { enumerable: true, get: function () { return node_client_js_1.NodeAgentAPI; } });
@@ -24,6 +24,7 @@ var index_js_1 = require("./local/index.js");
 Object.defineProperty(exports, "createLocalShellToolRegistry", { enumerable: true, get: function () { return index_js_1.createLocalShellToolRegistry; } });
 Object.defineProperty(exports, "LocalWorkdirDriver", { enumerable: true, get: function () { return index_js_1.LocalWorkdirDriver; } });
 Object.defineProperty(exports, "HostLocalShellRunner", { enumerable: true, get: function () { return index_js_1.HostLocalShellRunner; } });
+Object.defineProperty(exports, "IsolatorLocalShellRunner", { enumerable: true, get: function () { return index_js_1.IsolatorLocalShellRunner; } });
 Object.defineProperty(exports, "LocalShellDriver", { enumerable: true, get: function () { return index_js_1.LocalShellDriver; } });
 Object.defineProperty(exports, "localShellToolDefinition", { enumerable: true, get: function () { return index_js_1.localShellToolDefinition; } });
 Object.defineProperty(exports, "localShellToolInstructions", { enumerable: true, get: function () { return index_js_1.localShellToolInstructions; } });

package/dist-cjs/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.USER_AGENT = exports.VERSION = void 0;
-exports.VERSION = "1.2.2";
+exports.VERSION = "1.3.0";
 exports.USER_AGENT = `@agent-api/sdk/${exports.VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-api/sdk",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Production JavaScript SDK for the Managed Agent API",
   "license": "MIT",
   "repository": {