@agent-api/sdk 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog — @agent-api/sdk
 
+## 1.2.2
+
+### Added
+
+- Added `RequestOptions.signal` so CLI, TUI, and desktop integrations can abort in-flight HTTP requests and response streams before a response ID is available.
+- Documented and tested response cancellation behavior alongside the existing `responses.cancel(responseID)` backend cancellation API.
+
+## 1.2.1
+
+### Added
+
+- Added a model-facing `local_shell` tool primitive with approval/full-access modes, bounded host command execution, timeout handling, execution-environment context, and a pluggable command-runner boundary for future isolation backends.
+
 ## 1.2.0
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 Production JavaScript/TypeScript SDK for the Managed Agent API.
 
-**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.1.4)
+**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.2.2)
 
 ## Install
 
@@ -44,7 +44,7 @@ Public package entrypoints:
 
 - `@agent-api/sdk`: browser-safe REST client, public types, auth, responses, models, presets, tools, volumes, and skills HTTP APIs.
 - `@agent-api/sdk/browser`: explicit alias of the browser-safe REST client entry.
-- `@agent-api/sdk/local`: Node-only local runtime, workdir, context, and local workdir tool support.
+- `@agent-api/sdk/local`: Node-only local runtime, workdir, context, local workdir tools, and local shell tools.
 - `@agent-api/sdk/node`: Node aggregate entry for local helpers such as `localSkillFromDirectory()` plus `NodeAgentAPI`.
 
 ```
@@ -125,14 +125,15 @@ const response = await client.agent.create({
 
 ```typescript
 import { resolvePresetTools } from "@agent-api/sdk";
-import { createLocalWorkdirToolRegistry, LocalWorkdir } from "@agent-api/sdk/local";
+import { createLocalShellToolRegistry, createLocalWorkdirToolRegistry, LocalWorkdir } from "@agent-api/sdk/local";
 
 const workdir = new LocalWorkdir("/path/to/project", { trusted: true });
-const registry = createLocalWorkdirToolRegistry(workdir);
+const workdirRegistry = createLocalWorkdirToolRegistry(workdir);
+const shellRegistry = createLocalShellToolRegistry({ workdir });
 
 const { tools } = await resolvePresetTools(client, {
   preset: "pro-search",
-  tools: registry.definitions(),
+  tools: [...workdirRegistry.definitions(), ...shellRegistry.definitions()],
 });
 
 const response = await client.agent.create({
@@ -189,12 +190,15 @@ The runtime provides:
 - Atomic text/JSON writes, byte reads/writes, recursive listing, copy, remove, and stat helpers.
 - Local workdir operations inspired by platform volumes: `listEntries`, `searchEntries`, `readFile`, `writeFile`, `deletePath`, `createDirectory`, `readLines`, `patchLines`, `grep`, and `summarize`.
 - First-class local workdirs with default ignore rules, scoped workbench operations, patch previews, snapshots, diffs, file-watch handles, and budgeted context packaging.
+- Model-facing local tools for workdir operations (`local_workdir`) and command execution (`local_shell`) with approval/full-access dispatch conventions.
 - Typed local errors, `.gitignore` loading, sensitivity classification, and multi-file edit plans with rollback on failure.
 - JSON config helpers for typed app settings.
 - Local skill discovery built on `localSkillFromDirectory()`.
 
 Keep UI and OS interaction policy in your host framework. Electron, Tauri, Qt, or native apps should call this layer from their trusted local process and expose only the capabilities their UI needs.
 
+`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.
+
 ```typescript
 const workdir = local.data.child("workdirs/demo");
 
@@ -253,6 +257,7 @@ const context = await createLocalContextPackage(project, {
 
 - **Retries:** automatic exponential backoff for network failures, 429, and 5xx (default 2 retries).
 - **Timeouts:** 10 minute default for requests; 1 hour for streaming agent runs (configurable via `timeout` / `streamTimeout`).
+- **Cancellation:** pass `signal` in request options to abort local HTTP waiting, and call `client.responses.cancel(responseID)` for backend best-effort cancellation after a response ID exists.
 - **Typed errors:** `AuthenticationError`, `RateLimitError`, `NotFoundError`, `BadRequestError`, etc.
 - **Pagination:** `listPage` returns a cursor page; `listIterator` auto-fetches all pages.
 
@@ -269,7 +274,7 @@ const stream = await client.responses.create({
   preset: "fast-search",
   input: "Summarize today's AI news.",
   stream: true,
-});
+}, { signal: abortController.signal });
 
 for await (const event of stream) {
   if (event.type === "response.output_text.delta") {

package/dist/internal/http.js

@@ -33,6 +33,9 @@ export class HTTPClient {
                 return await this.fetchOnce(method, path, body, options, stream, rawBody);
             }
             catch (error) {
+                if (options.signal?.aborted) {
+                    throw error;
+                }
                 if (!(error instanceof APIError) || attempt >= maxRetries) {
                     throw error;
                 }
@@ -43,14 +46,29 @@ export class HTTPClient {
                 }
                 attempt += 1;
                 const delayMs = retryDelayMs(error, attempt);
-                await sleep(delayMs);
+                await sleep(delayMs, options.signal);
             }
         }
     }
     async fetchOnce(method, path, body, options, stream, rawBody) {
         const controller = new AbortController();
         const timeout = options.timeout ?? (stream ? this.options.streamTimeout : this.options.timeout);
-        const timeoutID = setTimeout(() => controller.abort(), timeout);
+        let timedOut = false;
+        let callerAborted = options.signal?.aborted ?? false;
+        const timeoutID = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        const abortFromCaller = () => {
+            callerAborted = true;
+            controller.abort();
+        };
+        if (options.signal?.aborted) {
+            controller.abort();
+        }
+        else {
+            options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+        }
         try {
             const headers = {
                 Accept: stream ? "text/event-stream" : "application/json",
@@ -80,12 +98,19 @@ export class HTTPClient {
                 throw error;
             }
             if (error instanceof Error && error.name === "AbortError") {
-                throw new APIConnectionError(`Request timed out after ${timeout}ms`, error);
+                if (callerAborted || options.signal?.aborted) {
+                    throw new APIConnectionError("Request aborted", error);
+                }
+                if (timedOut) {
+                    throw new APIConnectionError(`Request timed out after ${timeout}ms`, error);
+                }
+                throw new APIConnectionError("Request aborted", error);
             }
             throw new APIConnectionError("Request failed", error);
         }
         finally {
             clearTimeout(timeoutID);
+            options.signal?.removeEventListener("abort", abortFromCaller);
         }
     }
 }
@@ -99,6 +124,23 @@ function retryDelayMs(error, attempt) {
     const jitter = Math.floor(Math.random() * 100);
     return exponential + jitter;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    if (signal.aborted) {
+        return Promise.reject(new APIConnectionError("Request aborted"));
+    }
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", abort);
+            reject(new APIConnectionError("Request aborted"));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+    });
 }

package/dist/local/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./core.js";
 export * from "./context.js";
+export * from "./shell.js";
 export * from "./tools.js";

package/dist/local/index.js

@@ -1,3 +1,4 @@
 export * from "./core.js";
 export * from "./context.js";
+export * from "./shell.js";
 export * from "./tools.js";

package/dist/local/shell.d.ts

@@ -0,0 +1,82 @@
+import type { FunctionTool } from "../types/tools.js";
+import type { LocalWorkdir } from "./core.js";
+export type LocalShellAccessMode = "approval" | "full";
+export interface LocalShellRequest {
+    command: string;
+    description?: string;
+    workdir?: string;
+    timeoutMs?: number;
+    env?: Record<string, string | undefined>;
+}
+export interface LocalShellContext {
+    signal?: AbortSignal;
+}
+export interface LocalShellResult {
+    ok: boolean;
+    command: string;
+    description?: string;
+    cwd: string;
+    exit_code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    output: string;
+    duration_ms: number;
+    timed_out: boolean;
+    truncated: boolean;
+}
+export interface LocalCommandRunner {
+    run(request: LocalShellRequest, context?: LocalShellContext): Promise<LocalShellResult>;
+}
+export interface HostLocalShellRunnerOptions {
+    cwd?: string;
+    shell?: string | boolean;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare class HostLocalShellRunner implements LocalCommandRunner {
+    readonly cwd: string;
+    readonly shell: string | boolean;
+    readonly timeoutMs: number;
+    readonly maxOutputBytes: number;
+    readonly env: NodeJS.ProcessEnv;
+    constructor(options?: HostLocalShellRunnerOptions);
+    run(request: LocalShellRequest, context?: LocalShellContext): Promise<LocalShellResult>;
+}
+export interface LocalShellToolRegistryOptions {
+    accessMode?: LocalShellAccessMode;
+    toolName?: string;
+    runner?: LocalCommandRunner;
+    cwd?: string;
+    workdir?: LocalWorkdir;
+    shell?: string | boolean;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+export interface LocalShellToolPresentationOptions {
+    accessMode?: LocalShellAccessMode;
+    cwd?: string;
+    shell?: string | boolean;
+    platform?: NodeJS.Platform;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+export interface LocalShellToolRegistry {
+    readonly accessMode: LocalShellAccessMode;
+    readonly toolName: string;
+    definitions(): FunctionTool[];
+    handlers(): Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>>;
+    execute(name: string, args: Record<string, unknown>, context?: LocalShellContext): Promise<Record<string, unknown>>;
+    requiresApproval(name: string, args?: Record<string, unknown>): boolean;
+}
+export declare class LocalShellDriver {
+    readonly accessMode: LocalShellAccessMode;
+    readonly runner: LocalCommandRunner;
+    constructor(options?: LocalShellToolRegistryOptions);
+    dispatch(args: Record<string, unknown>, context?: LocalShellContext): Promise<Record<string, unknown>>;
+    requiresApproval(): boolean;
+}
+export declare function createLocalShellToolRegistry(options?: LocalShellToolRegistryOptions): LocalShellToolRegistry;
+export declare function localShellToolDefinition(name?: string, options?: LocalShellToolPresentationOptions): FunctionTool;
+export declare function localShellToolInstructions(options?: LocalShellToolPresentationOptions): string;

package/dist/local/shell.js

@@ -0,0 +1,318 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+export class HostLocalShellRunner {
+    cwd;
+    shell;
+    timeoutMs;
+    maxOutputBytes;
+    env;
+    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 ?? {}) };
+    }
+    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 started = Date.now();
+        const stdout = new BoundedText(this.maxOutputBytes);
+        const stderr = new BoundedText(this.maxOutputBytes);
+        let timedOut = false;
+        return await new Promise((resolve, reject) => {
+            const child = spawn(command, [], {
+                cwd,
+                env: { ...this.env, ...(request.env ?? {}) },
+                shell: this.shell,
+                stdio: ["ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            let settled = false;
+            const finish = (exitCode, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                context.signal?.removeEventListener("abort", abort);
+                const stdoutText = stdout.text();
+                const stderrText = stderr.text();
+                const output = [stdoutText, stderrText].filter(Boolean).join(stderrText ? "\n" : "");
+                resolve({
+                    ok: true,
+                    command,
+                    description: request.description,
+                    cwd,
+                    exit_code: exitCode,
+                    signal,
+                    stdout: stdoutText,
+                    stderr: stderrText,
+                    output: output || "(no output)",
+                    duration_ms: Date.now() - started,
+                    timed_out: timedOut,
+                    truncated: stdout.truncated || stderr.truncated,
+                });
+            };
+            const kill = () => {
+                if (child.killed)
+                    return;
+                child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+                setTimeout(() => {
+                    if (!child.killed)
+                        child.kill(process.platform === "win32" ? undefined : "SIGKILL");
+                }, 3000).unref();
+            };
+            const abort = () => {
+                kill();
+            };
+            const timer = setTimeout(() => {
+                timedOut = true;
+                kill();
+            }, timeoutMs);
+            timer.unref();
+            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", (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                context.signal?.removeEventListener("abort", abort);
+                reject(error);
+            });
+            child.on("close", finish);
+        });
+    }
+}
+export class LocalShellDriver {
+    accessMode;
+    runner;
+    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,
+        });
+    }
+    async dispatch(args, context = {}) {
+        const request = shellRequest(args);
+        if (this.accessMode !== "full") {
+            return shellApprovalRequired(request);
+        }
+        return shellToolResult(await this.runner.run(request, context));
+    }
+    requiresApproval() {
+        return this.accessMode !== "full";
+    }
+}
+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 definition = localShellToolDefinition(toolName, {
+        accessMode: driver.accessMode,
+        cwd: options.workdir?.root ?? hostRunner?.cwd ?? options.cwd,
+        shell: hostRunner?.shell ?? options.shell,
+        timeoutMs: hostRunner?.timeoutMs ?? options.timeoutMs,
+        maxOutputBytes: hostRunner?.maxOutputBytes ?? options.maxOutputBytes,
+    });
+    return {
+        accessMode: driver.accessMode,
+        toolName,
+        definitions: () => [{ ...definition }],
+        handlers: () => ({ [toolName]: (args) => driver.dispatch(args) }),
+        execute: async (name, args, context = {}) => {
+            if (name !== toolName) {
+                throw new Error(`unknown local shell tool: ${name}`);
+            }
+            return await driver.dispatch(args, context);
+        },
+        requiresApproval: (name) => name === toolName && driver.requiresApproval(),
+    };
+}
+export function localShellToolDefinition(name = "local_shell", options = {}) {
+    return {
+        type: "function",
+        name,
+        description: localShellToolDescription(options),
+        parameters: localShellToolParameters(),
+        strict: false,
+    };
+}
+export function localShellToolInstructions(options = {}) {
+    return localShellToolDescription(options);
+}
+function localShellToolDescription(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const shell = shellDisplayName(options.shell);
+    const accessMode = options.accessMode ?? "approval";
+    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}.`,
+        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.",
+        "Captured stdout/stderr may be truncated when output exceeds the advertised max_output_bytes.",
+        "In approval mode, calls return requires_approval instead of executing. In full mode, commands execute immediately.",
+        shellGuidance(platform, options.shell),
+    ].filter(Boolean).join(" ");
+}
+function localShellToolParameters() {
+    return {
+        type: "object",
+        properties: {
+            command: {
+                type: "string",
+                description: "Shell command to execute. Keep it focused and quote paths containing spaces.",
+            },
+            description: {
+                type: "string",
+                description: "Short human-readable description of why this command is being run.",
+            },
+            workdir: {
+                type: "string",
+                description: "Optional relative working directory. Use this instead of cd. Absolute paths are rejected by the default host runner.",
+            },
+            timeout_ms: {
+                type: "integer",
+                description: "Optional timeout in milliseconds.",
+            },
+        },
+        required: ["command"],
+        additionalProperties: false,
+    };
+}
+function shellRequest(args) {
+    return {
+        command: requiredString(args.command, "command"),
+        description: optionalString(args.description, "description"),
+        workdir: optionalString(args.workdir, "workdir"),
+        timeoutMs: optionalNumber(args.timeoutMs ?? args.timeout_ms, "timeout_ms"),
+    };
+}
+function shellApprovalRequired(request) {
+    return {
+        ok: false,
+        requires_approval: true,
+        action: "run",
+        command: request.command,
+        description: request.description,
+        workdir: request.workdir,
+        timeout_ms: request.timeoutMs,
+        message: "local_shell command execution requires approval",
+    };
+}
+function shellToolResult(result) {
+    return {
+        ...result,
+        action: "run",
+    };
+}
+function resolveContainedPath(root, child) {
+    if (!child)
+        return root;
+    if (path.isAbsolute(child)) {
+        throw new Error("workdir must be relative to the configured local shell cwd");
+    }
+    const resolved = path.resolve(root, child);
+    const relative = path.relative(root, resolved);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error("workdir must stay inside the configured local shell cwd");
+    }
+    return resolved;
+}
+function requiredString(value, name) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(value, name) {
+    if (value == null || value === "")
+        return undefined;
+    if (typeof value !== "string") {
+        throw new Error(`${name} must be a string`);
+    }
+    return value;
+}
+function optionalNumber(value, name) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${name} must be a number`);
+    }
+    return Math.trunc(value);
+}
+function positiveInteger(value, fallback, name) {
+    if (value == null)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`${name} must be a positive number`);
+    }
+    return Math.trunc(value);
+}
+function shellDisplayName(shell) {
+    if (typeof shell === "string" && shell.trim())
+        return shell;
+    if (shell === false)
+        return "direct process execution";
+    if (process.platform === "win32")
+        return "cmd.exe";
+    return "/bin/sh";
+}
+function shellGuidance(platform, shell) {
+    const name = typeof shell === "string" ? path.basename(shell).toLowerCase() : shellDisplayName(shell).toLowerCase();
+    if (platform === "win32" || name.includes("powershell") || name === "pwsh") {
+        return "On Windows/PowerShell, prefer PowerShell-compatible commands and quote paths with spaces.";
+    }
+    if (name.includes("cmd.exe") || name === "cmd") {
+        return "On cmd.exe, prefer cmd-compatible syntax and use && only for dependent command chaining.";
+    }
+    return "On POSIX shells, prefer portable shell syntax, quote paths with spaces, and use && only when later commands depend on earlier success.";
+}
+class BoundedText {
+    maxBytes;
+    chunks = [];
+    size = 0;
+    truncated = false;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    append(chunk) {
+        this.chunks.push(chunk);
+        this.size += chunk.byteLength;
+        while (this.size > this.maxBytes && this.chunks.length > 1) {
+            const removed = this.chunks.shift();
+            if (!removed)
+                break;
+            this.size -= removed.byteLength;
+            this.truncated = true;
+        }
+        if (this.size > this.maxBytes && this.chunks.length === 1) {
+            const current = this.chunks[0];
+            this.chunks[0] = current.subarray(current.byteLength - this.maxBytes);
+            this.size = this.chunks[0].byteLength;
+            this.truncated = true;
+        }
+    }
+    text() {
+        const value = Buffer.concat(this.chunks, this.size).toString("utf8");
+        return this.truncated ? `...output truncated...\n${value}` : value;
+    }
+}

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 { LocalWorkdirDriver, createLocalWorkdirToolRegistry, localWorkdirToolDefinition, localWorkdirToolInstructions, } from "./local/tools.js";
-export type { LocalWorkdirAction, LocalWorkdirAccessMode, LocalWorkdirToolRegistry, LocalWorkdirToolRegistryOptions, } from "./local/tools.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 { 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 { LocalWorkdirDriver, createLocalWorkdirToolRegistry, localWorkdirToolDefinition, localWorkdirToolInstructions, } from "./local/tools.js";
+export { createLocalShellToolRegistry, LocalWorkdirDriver, HostLocalShellRunner, 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/types/common.d.ts

@@ -20,6 +20,8 @@ export interface ClientOptions {
 export interface RequestOptions {
     headers?: Record<string, string>;
     timeout?: number;
+    /** Abort the underlying HTTP request or stream from caller-controlled UI/runtime state. */
+    signal?: AbortSignal;
     /** Override automatic retries for this request. */
     maxRetries?: number;
 }

package/dist/version.d.ts

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

package/dist/version.js

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

package/dist-cjs/internal/http.js

@@ -36,6 +36,9 @@ class HTTPClient {
                 return await this.fetchOnce(method, path, body, options, stream, rawBody);
             }
             catch (error) {
+                if (options.signal?.aborted) {
+                    throw error;
+                }
                 if (!(error instanceof errors_js_1.APIError) || attempt >= maxRetries) {
                     throw error;
                 }
@@ -46,14 +49,29 @@ class HTTPClient {
                 }
                 attempt += 1;
                 const delayMs = retryDelayMs(error, attempt);
-                await sleep(delayMs);
+                await sleep(delayMs, options.signal);
             }
         }
     }
     async fetchOnce(method, path, body, options, stream, rawBody) {
         const controller = new AbortController();
         const timeout = options.timeout ?? (stream ? this.options.streamTimeout : this.options.timeout);
-        const timeoutID = setTimeout(() => controller.abort(), timeout);
+        let timedOut = false;
+        let callerAborted = options.signal?.aborted ?? false;
+        const timeoutID = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeout);
+        const abortFromCaller = () => {
+            callerAborted = true;
+            controller.abort();
+        };
+        if (options.signal?.aborted) {
+            controller.abort();
+        }
+        else {
+            options.signal?.addEventListener("abort", abortFromCaller, { once: true });
+        }
         try {
             const headers = {
                 Accept: stream ? "text/event-stream" : "application/json",
@@ -83,12 +101,19 @@ class HTTPClient {
                 throw error;
             }
             if (error instanceof Error && error.name === "AbortError") {
-                throw new errors_js_1.APIConnectionError(`Request timed out after ${timeout}ms`, error);
+                if (callerAborted || options.signal?.aborted) {
+                    throw new errors_js_1.APIConnectionError("Request aborted", error);
+                }
+                if (timedOut) {
+                    throw new errors_js_1.APIConnectionError(`Request timed out after ${timeout}ms`, error);
+                }
+                throw new errors_js_1.APIConnectionError("Request aborted", error);
             }
             throw new errors_js_1.APIConnectionError("Request failed", error);
         }
         finally {
             clearTimeout(timeoutID);
+            options.signal?.removeEventListener("abort", abortFromCaller);
         }
     }
 }
@@ -103,6 +128,23 @@ function retryDelayMs(error, attempt) {
     const jitter = Math.floor(Math.random() * 100);
     return exponential + jitter;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    if (signal.aborted) {
+        return Promise.reject(new errors_js_1.APIConnectionError("Request aborted"));
+    }
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        const abort = () => {
+            clearTimeout(timeout);
+            signal.removeEventListener("abort", abort);
+            reject(new errors_js_1.APIConnectionError("Request aborted"));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+    });
 }

package/dist-cjs/local/index.js

@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./core.js"), exports);
 __exportStar(require("./context.js"), exports);
+__exportStar(require("./shell.js"), exports);
 __exportStar(require("./tools.js"), exports);

package/dist-cjs/local/shell.js

@@ -0,0 +1,329 @@
+"use strict";
+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.createLocalShellToolRegistry = createLocalShellToolRegistry;
+exports.localShellToolDefinition = localShellToolDefinition;
+exports.localShellToolInstructions = localShellToolInstructions;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = __importDefault(require("node:path"));
+class HostLocalShellRunner {
+    cwd;
+    shell;
+    timeoutMs;
+    maxOutputBytes;
+    env;
+    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 ?? {}) };
+    }
+    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 started = Date.now();
+        const stdout = new BoundedText(this.maxOutputBytes);
+        const stderr = new BoundedText(this.maxOutputBytes);
+        let timedOut = false;
+        return await new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)(command, [], {
+                cwd,
+                env: { ...this.env, ...(request.env ?? {}) },
+                shell: this.shell,
+                stdio: ["ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            let settled = false;
+            const finish = (exitCode, signal) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                context.signal?.removeEventListener("abort", abort);
+                const stdoutText = stdout.text();
+                const stderrText = stderr.text();
+                const output = [stdoutText, stderrText].filter(Boolean).join(stderrText ? "\n" : "");
+                resolve({
+                    ok: true,
+                    command,
+                    description: request.description,
+                    cwd,
+                    exit_code: exitCode,
+                    signal,
+                    stdout: stdoutText,
+                    stderr: stderrText,
+                    output: output || "(no output)",
+                    duration_ms: Date.now() - started,
+                    timed_out: timedOut,
+                    truncated: stdout.truncated || stderr.truncated,
+                });
+            };
+            const kill = () => {
+                if (child.killed)
+                    return;
+                child.kill(process.platform === "win32" ? undefined : "SIGTERM");
+                setTimeout(() => {
+                    if (!child.killed)
+                        child.kill(process.platform === "win32" ? undefined : "SIGKILL");
+                }, 3000).unref();
+            };
+            const abort = () => {
+                kill();
+            };
+            const timer = setTimeout(() => {
+                timedOut = true;
+                kill();
+            }, timeoutMs);
+            timer.unref();
+            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", (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                context.signal?.removeEventListener("abort", abort);
+                reject(error);
+            });
+            child.on("close", finish);
+        });
+    }
+}
+exports.HostLocalShellRunner = HostLocalShellRunner;
+class LocalShellDriver {
+    accessMode;
+    runner;
+    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,
+        });
+    }
+    async dispatch(args, context = {}) {
+        const request = shellRequest(args);
+        if (this.accessMode !== "full") {
+            return shellApprovalRequired(request);
+        }
+        return shellToolResult(await this.runner.run(request, context));
+    }
+    requiresApproval() {
+        return this.accessMode !== "full";
+    }
+}
+exports.LocalShellDriver = LocalShellDriver;
+function createLocalShellToolRegistry(options = {}) {
+    const toolName = options.toolName ?? "local_shell";
+    const driver = new LocalShellDriver(options);
+    const hostRunner = driver.runner instanceof HostLocalShellRunner ? driver.runner : undefined;
+    const definition = localShellToolDefinition(toolName, {
+        accessMode: driver.accessMode,
+        cwd: options.workdir?.root ?? hostRunner?.cwd ?? options.cwd,
+        shell: hostRunner?.shell ?? options.shell,
+        timeoutMs: hostRunner?.timeoutMs ?? options.timeoutMs,
+        maxOutputBytes: hostRunner?.maxOutputBytes ?? options.maxOutputBytes,
+    });
+    return {
+        accessMode: driver.accessMode,
+        toolName,
+        definitions: () => [{ ...definition }],
+        handlers: () => ({ [toolName]: (args) => driver.dispatch(args) }),
+        execute: async (name, args, context = {}) => {
+            if (name !== toolName) {
+                throw new Error(`unknown local shell tool: ${name}`);
+            }
+            return await driver.dispatch(args, context);
+        },
+        requiresApproval: (name) => name === toolName && driver.requiresApproval(),
+    };
+}
+function localShellToolDefinition(name = "local_shell", options = {}) {
+    return {
+        type: "function",
+        name,
+        description: localShellToolDescription(options),
+        parameters: localShellToolParameters(),
+        strict: false,
+    };
+}
+function localShellToolInstructions(options = {}) {
+    return localShellToolDescription(options);
+}
+function localShellToolDescription(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const shell = shellDisplayName(options.shell);
+    const accessMode = options.accessMode ?? "approval";
+    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}.`,
+        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.",
+        "Captured stdout/stderr may be truncated when output exceeds the advertised max_output_bytes.",
+        "In approval mode, calls return requires_approval instead of executing. In full mode, commands execute immediately.",
+        shellGuidance(platform, options.shell),
+    ].filter(Boolean).join(" ");
+}
+function localShellToolParameters() {
+    return {
+        type: "object",
+        properties: {
+            command: {
+                type: "string",
+                description: "Shell command to execute. Keep it focused and quote paths containing spaces.",
+            },
+            description: {
+                type: "string",
+                description: "Short human-readable description of why this command is being run.",
+            },
+            workdir: {
+                type: "string",
+                description: "Optional relative working directory. Use this instead of cd. Absolute paths are rejected by the default host runner.",
+            },
+            timeout_ms: {
+                type: "integer",
+                description: "Optional timeout in milliseconds.",
+            },
+        },
+        required: ["command"],
+        additionalProperties: false,
+    };
+}
+function shellRequest(args) {
+    return {
+        command: requiredString(args.command, "command"),
+        description: optionalString(args.description, "description"),
+        workdir: optionalString(args.workdir, "workdir"),
+        timeoutMs: optionalNumber(args.timeoutMs ?? args.timeout_ms, "timeout_ms"),
+    };
+}
+function shellApprovalRequired(request) {
+    return {
+        ok: false,
+        requires_approval: true,
+        action: "run",
+        command: request.command,
+        description: request.description,
+        workdir: request.workdir,
+        timeout_ms: request.timeoutMs,
+        message: "local_shell command execution requires approval",
+    };
+}
+function shellToolResult(result) {
+    return {
+        ...result,
+        action: "run",
+    };
+}
+function resolveContainedPath(root, child) {
+    if (!child)
+        return root;
+    if (node_path_1.default.isAbsolute(child)) {
+        throw new Error("workdir must be relative to the configured local shell cwd");
+    }
+    const resolved = node_path_1.default.resolve(root, child);
+    const relative = node_path_1.default.relative(root, resolved);
+    if (relative.startsWith("..") || node_path_1.default.isAbsolute(relative)) {
+        throw new Error("workdir must stay inside the configured local shell cwd");
+    }
+    return resolved;
+}
+function requiredString(value, name) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalString(value, name) {
+    if (value == null || value === "")
+        return undefined;
+    if (typeof value !== "string") {
+        throw new Error(`${name} must be a string`);
+    }
+    return value;
+}
+function optionalNumber(value, name) {
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${name} must be a number`);
+    }
+    return Math.trunc(value);
+}
+function positiveInteger(value, fallback, name) {
+    if (value == null)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new Error(`${name} must be a positive number`);
+    }
+    return Math.trunc(value);
+}
+function shellDisplayName(shell) {
+    if (typeof shell === "string" && shell.trim())
+        return shell;
+    if (shell === false)
+        return "direct process execution";
+    if (process.platform === "win32")
+        return "cmd.exe";
+    return "/bin/sh";
+}
+function shellGuidance(platform, shell) {
+    const name = typeof shell === "string" ? node_path_1.default.basename(shell).toLowerCase() : shellDisplayName(shell).toLowerCase();
+    if (platform === "win32" || name.includes("powershell") || name === "pwsh") {
+        return "On Windows/PowerShell, prefer PowerShell-compatible commands and quote paths with spaces.";
+    }
+    if (name.includes("cmd.exe") || name === "cmd") {
+        return "On cmd.exe, prefer cmd-compatible syntax and use && only for dependent command chaining.";
+    }
+    return "On POSIX shells, prefer portable shell syntax, quote paths with spaces, and use && only when later commands depend on earlier success.";
+}
+class BoundedText {
+    maxBytes;
+    chunks = [];
+    size = 0;
+    truncated = false;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+    }
+    append(chunk) {
+        this.chunks.push(chunk);
+        this.size += chunk.byteLength;
+        while (this.size > this.maxBytes && this.chunks.length > 1) {
+            const removed = this.chunks.shift();
+            if (!removed)
+                break;
+            this.size -= removed.byteLength;
+            this.truncated = true;
+        }
+        if (this.size > this.maxBytes && this.chunks.length === 1) {
+            const current = this.chunks[0];
+            this.chunks[0] = current.subarray(current.byteLength - this.maxBytes);
+            this.size = this.chunks[0].byteLength;
+            this.truncated = true;
+        }
+    }
+    text() {
+        const value = Buffer.concat(this.chunks, this.size).toString("utf8");
+        return this.truncated ? `...output truncated...\n${value}` : value;
+    }
+}

package/dist-cjs/node.js

@@ -14,17 +14,22 @@ 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.LocalWorkdirDriver = 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.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; } });
 var skills_node_js_1 = require("./resources/skills-node.js");
 Object.defineProperty(exports, "NodeSkillsResource", { enumerable: true, get: function () { return skills_node_js_1.NodeSkillsResource; } });
-var tools_js_1 = require("./local/tools.js");
-Object.defineProperty(exports, "LocalWorkdirDriver", { enumerable: true, get: function () { return tools_js_1.LocalWorkdirDriver; } });
-Object.defineProperty(exports, "createLocalWorkdirToolRegistry", { enumerable: true, get: function () { return tools_js_1.createLocalWorkdirToolRegistry; } });
-Object.defineProperty(exports, "localWorkdirToolDefinition", { enumerable: true, get: function () { return tools_js_1.localWorkdirToolDefinition; } });
-Object.defineProperty(exports, "localWorkdirToolInstructions", { enumerable: true, get: function () { return tools_js_1.localWorkdirToolInstructions; } });
+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, "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; } });
+Object.defineProperty(exports, "createLocalWorkdirToolRegistry", { enumerable: true, get: function () { return index_js_1.createLocalWorkdirToolRegistry; } });
+Object.defineProperty(exports, "localWorkdirToolDefinition", { enumerable: true, get: function () { return index_js_1.localWorkdirToolDefinition; } });
+Object.defineProperty(exports, "localWorkdirToolInstructions", { enumerable: true, get: function () { return index_js_1.localWorkdirToolInstructions; } });
 var local_skills_js_1 = require("./local-skills.js");
 Object.defineProperty(exports, "localSkillFromDirectory", { enumerable: true, get: function () { return local_skills_js_1.localSkillFromDirectory; } });
 Object.defineProperty(exports, "pendingLocalSkillCalls", { enumerable: true, get: function () { return local_skills_js_1.pendingLocalSkillCalls; } });

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.0";
+exports.VERSION = "1.2.2";
 exports.USER_AGENT = `@agent-api/sdk/${exports.VERSION}`;

package/package.json

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