@agent-api/sdk 1.1.5 → 1.2.1

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog — @agent-api/sdk
 
-## 1.1.5
+## 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
 
@@ -9,18 +15,19 @@
 
 ### Changed
 
+- Renamed local SDK concepts from workspace to workdir to avoid confusion with platform identity workspaces.
 - Extended response input types so tool-call continuations can carry function-call metadata consistently.
 
 ## 1.1.2
 
 ### Added
 
-- Added a model-facing `local_workspace` driver/tool primitive for local workspace operations.
-- Added approval-aware dispatch for mutating local workspace actions.
+- Added a model-facing `local_workdir` driver/tool primitive for local workdir operations.
+- Added approval-aware dispatch for mutating local workdir actions.
 
 ### Changed
 
-- Replaced fragmented local workspace tool presentation with an action-based adapter over the low-level local APIs.
+- Replaced fragmented local workdir tool presentation with an action-based adapter over the low-level local APIs.
 
 ## 1.1.1
 
@@ -38,9 +45,9 @@
 - Cross-platform app directory resolution for data, config, cache, logs, and temp files.
 - Root-scoped local file stores with path traversal protection, atomic writes, JSON helpers, recursive listing, and local skill discovery.
 - Local workdir operations for entry search, file delivery, line-range reads and edits, literal grep, and directory summaries.
-- `LocalWorkspace` and `LocalWorkspaceManager` for project roots, default ignore rules, patch previews, snapshots, diffs, and file-watch handles.
+- `LocalWorkdir` and `LocalWorkdirManager` for project roots, default ignore rules, patch previews, snapshots, diffs, and file-watch handles.
 - Typed local errors, `.gitignore` loading, sensitivity classification for likely secret paths, and multi-file line-edit plans with conflict detection and rollback.
-- `createLocalContextPackage()` for bounded, secret-aware local workspace manifests that app integrations can hand to agent workflows.
+- `createLocalContextPackage()` for bounded, secret-aware local workdir manifests that app integrations can hand to agent workflows.
 
 ### Changed
 

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.1)
 
 ## 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, workspace, context, and local workspace 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`.
 
 ```
@@ -114,7 +114,7 @@ const binary = await client.volumes.readFile(volume.volume_id, "assets/logo.png"
 
 const response = await client.agent.create({
   preset: "pro-search",
-  input: "Use the attached workspace volume.",
+  input: "Use the attached agent volume.",
   volume_id: volume.volume_id,
 });
 ```
@@ -125,14 +125,15 @@ const response = await client.agent.create({
 
 ```typescript
 import { resolvePresetTools } from "@agent-api/sdk";
-import { createLocalWorkspaceToolRegistry, LocalWorkspace } from "@agent-api/sdk/local";
+import { createLocalShellToolRegistry, createLocalWorkdirToolRegistry, LocalWorkdir } from "@agent-api/sdk/local";
 
-const workspace = new LocalWorkspace("/path/to/project", { trusted: true });
-const registry = createLocalWorkspaceToolRegistry(workspace);
+const workdir = new LocalWorkdir("/path/to/project", { trusted: true });
+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({
@@ -188,32 +189,35 @@ The runtime provides:
 - Root-scoped file stores with path traversal protection.
 - 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 workspaces with default ignore rules, scoped workbench operations, patch previews, snapshots, diffs, file-watch handles, and budgeted context packaging.
+- 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 workspace = local.data.child("workspaces/demo");
+const workdir = local.data.child("workdirs/demo");
 
-await workspace.writeText("src/index.ts", "console.log('hello');\n");
+await workdir.writeText("src/index.ts", "console.log('hello');\n");
 
-const matches = await workspace.grep({ pattern: "hello", path: "src" });
-const lines = await workspace.readLines("src/index.ts", { startLine: 1, endLine: 20 });
-await workspace.patchLines("src/index.ts", {
+const matches = await workdir.grep({ pattern: "hello", path: "src" });
+const lines = await workdir.readLines("src/index.ts", { startLine: 1, endLine: 20 });
+await workdir.patchLines("src/index.ts", {
   startLine: 1,
   replacement: "console.log('patched');",
 });
 
-const summary = await workspace.summarize();
+const summary = await workdir.summarize();
 ```
 
-For project/workspace roots, prefer `local.workspace()` so SDK defaults protect common generated directories such as `.git`, `node_modules`, `dist`, and build caches.
+For project/workdir roots, prefer `local.workdir()` so SDK defaults protect common generated directories such as `.git`, `node_modules`, `dist`, and build caches.
 
 ```typescript
-const project = local.workspace("/path/to/project", {
+const project = local.workdir("/path/to/project", {
   name: "my-project",
   trusted: true,
   ignore: ["vendor", /^tmp\//],
@@ -236,7 +240,7 @@ const diff = project.diff(before, after);
 const sensitivity = project.classifyPath(".env");
 ```
 
-Use `createLocalContextPackage()` when a local app needs to prepare bounded workspace context for an agent request. The package includes a manifest, selected file previews, optional search matches, hashes, sensitivity labels, and secret-aware omission by default.
+Use `createLocalContextPackage()` when a local app needs to prepare bounded workdir context for an agent request. The package includes a manifest, selected file previews, optional search matches, hashes, sensitivity labels, and secret-aware omission by default.
 
 ```typescript
 import { createLocalContextPackage } from "@agent-api/sdk/local";

package/dist/local/context.d.ts

@@ -1,4 +1,4 @@
-import { type LocalFileDeliver, type LocalGrepResponse, type LocalPathSensitivity, type LocalPathSensitivityInfo, type LocalSummary, type LocalWorkspace, type LocalWorkspaceSnapshotFile } from "./core.js";
+import { type LocalFileDeliver, type LocalGrepResponse, type LocalPathSensitivity, type LocalPathSensitivityInfo, type LocalSummary, type LocalWorkdir, type LocalWorkdirSnapshotFile } from "./core.js";
 export interface LocalContextPackageParams {
     path?: string;
     include?: string[];
@@ -30,7 +30,7 @@ export interface LocalContextFile {
 export interface LocalContextManifest {
     object: "local_context_manifest";
     root: string;
-    workspace_name: string;
+    workdir_name: string;
     generated_at_unix: number;
     base_path: string;
     file_count: number;
@@ -41,9 +41,9 @@ export interface LocalContextManifest {
     summary?: LocalSummary;
     search?: LocalGrepResponse;
 }
-export declare function createLocalContextPackage(workspace: LocalWorkspace, params?: LocalContextPackageParams): Promise<LocalContextManifest>;
+export declare function createLocalContextPackage(workdir: LocalWorkdir, params?: LocalContextPackageParams): Promise<LocalContextManifest>;
 export declare function summarizeLocalContextSensitivity(files: Array<Pick<LocalContextFile, "path" | "sensitivity" | "sensitivity_reason">>): {
     highest: LocalPathSensitivity;
     files: LocalPathSensitivityInfo[];
 };
-export type LocalContextSnapshotFile = LocalWorkspaceSnapshotFile;
+export type LocalContextSnapshotFile = LocalWorkdirSnapshotFile;

package/dist/local/context.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { classifyLocalPathSensitivity, } from "./core.js";
-export async function createLocalContextPackage(workspace, params = {}) {
+export async function createLocalContextPackage(workdir, params = {}) {
     const basePath = params.path ?? ".";
     const maxFiles = positiveInt(params.maxFiles, 80);
     const maxBytes = positiveInt(params.maxBytes, 256 * 1024);
@@ -12,7 +12,7 @@ export async function createLocalContextPackage(workspace, params = {}) {
     const includeSummary = params.includeSummary ?? true;
     const includeSearch = Boolean(params.includeSearch && params.query?.trim());
     const includeSecrets = params.includeSecrets ?? false;
-    const stats = await workspace.list(basePath, { recursive: true });
+    const stats = await workdir.list(basePath, { recursive: true });
     const fileStats = stats
         .filter((item) => item.type === "file")
         .filter((item) => matchesPathFilters(item.path, params.include, params.exclude))
@@ -49,7 +49,7 @@ export async function createLocalContextPackage(workspace, params = {}) {
             truncated = true;
             continue;
         }
-        const delivered = await workspace.readFile(item.path, { maxBytes: readBudget });
+        const delivered = await workdir.readFile(item.path, { maxBytes: readBudget });
         includedBytes += delivered.encoding === "text"
             ? Buffer.byteLength(delivered.content ?? "", "utf8")
             : Buffer.byteLength(delivered.content_base64 ?? "", "base64");
@@ -64,7 +64,7 @@ export async function createLocalContextPackage(workspace, params = {}) {
             packaged.content_base64 = delivered.content_base64;
         }
         if (includeHashes) {
-            packaged.sha256 = await sha256File(workspace, item.path);
+            packaged.sha256 = await sha256File(workdir, item.path);
         }
         if (delivered.truncated) {
             truncated = true;
@@ -72,7 +72,7 @@ export async function createLocalContextPackage(workspace, params = {}) {
         files.push(packaged);
     }
     const summary = includeSummary
-        ? await workspace.summarize({
+        ? await workdir.summarize({
             path: basePath,
             maxFiles,
             previewBytes,
@@ -80,7 +80,7 @@ export async function createLocalContextPackage(workspace, params = {}) {
         })
         : undefined;
     const search = includeSearch
-        ? await workspace.grep({
+        ? await workdir.grep({
             pattern: params.query,
             path: basePath,
             limit: maxFiles,
@@ -90,8 +90,8 @@ export async function createLocalContextPackage(workspace, params = {}) {
         : undefined;
     return {
         object: "local_context_manifest",
-        root: workspace.root,
-        workspace_name: workspace.name,
+        root: workdir.root,
+        workdir_name: workdir.name,
         generated_at_unix: Math.floor(Date.now() / 1000),
         base_path: basePath,
         file_count: fileStats.length,
@@ -148,7 +148,7 @@ function positiveInt(value, fallback) {
     const parsed = Number(value);
     return Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : fallback;
 }
-async function sha256File(workspace, relativePath) {
-    const fullPath = workspace.files.resolvePath(relativePath);
+async function sha256File(workdir, relativePath) {
+    const fullPath = workdir.files.resolvePath(relativePath);
     return createHash("sha256").update(await readFile(fullPath)).digest("hex");
 }

package/dist/local/core.d.ts

@@ -174,7 +174,7 @@ export interface LocalSummary {
     generated_at_unix: number;
     scan_truncated: boolean;
 }
-export interface LocalWorkspaceOptions {
+export interface LocalWorkdirOptions {
     name?: string;
     metadata?: Record<string, unknown>;
     trusted?: boolean;
@@ -182,31 +182,31 @@ export interface LocalWorkspaceOptions {
     gitignore?: boolean;
     maxFileBytes?: number;
 }
-export interface LocalWorkspaceSnapshotParams {
+export interface LocalWorkdirSnapshotParams {
     path?: string;
     hash?: boolean;
     maxBytesPerFile?: number;
 }
-export interface LocalWorkspaceSnapshotFile {
+export interface LocalWorkdirSnapshotFile {
     path: string;
     size: number;
     modified_at_unix?: number;
     sha256?: string;
 }
-export interface LocalWorkspaceSnapshot {
+export interface LocalWorkdirSnapshot {
     root: string;
     name: string;
     generated_at_unix: number;
-    files: LocalWorkspaceSnapshotFile[];
+    files: LocalWorkdirSnapshotFile[];
 }
-export interface LocalWorkspaceDiff {
-    added: LocalWorkspaceSnapshotFile[];
+export interface LocalWorkdirDiff {
+    added: LocalWorkdirSnapshotFile[];
     modified: Array<{
-        before: LocalWorkspaceSnapshotFile;
-        after: LocalWorkspaceSnapshotFile;
+        before: LocalWorkdirSnapshotFile;
+        after: LocalWorkdirSnapshotFile;
     }>;
-    deleted: LocalWorkspaceSnapshotFile[];
-    unchanged: LocalWorkspaceSnapshotFile[];
+    deleted: LocalWorkdirSnapshotFile[];
+    unchanged: LocalWorkdirSnapshotFile[];
 }
 export interface LocalLinePatchPreview {
     path: string;
@@ -216,18 +216,18 @@ export interface LocalLinePatchPreview {
     before: string[];
     after: string[];
 }
-export interface LocalWorkspaceLineEdit {
+export interface LocalWorkdirLineEdit {
     path: string;
     startLine: number;
     endLine?: number;
     replacement?: string;
     expectedSha256?: string;
 }
-export interface LocalWorkspaceEditPlan {
-    edits: LocalWorkspaceLineEdit[];
+export interface LocalWorkdirEditPlan {
+    edits: LocalWorkdirLineEdit[];
     previews: LocalLinePatchPreview[];
 }
-export interface LocalWorkspaceEditResult {
+export interface LocalWorkdirEditResult {
     applied: LocalFileLinesPatch[];
     backups: Array<{
         path: string;
@@ -240,11 +240,11 @@ export interface LocalPathSensitivityInfo {
     sensitivity: LocalPathSensitivity;
     reason?: string;
 }
-export interface LocalWorkspaceWatchEvent {
+export interface LocalWorkdirWatchEvent {
     type: "change" | "rename";
     path: string;
 }
-export interface LocalWorkspaceWatcher {
+export interface LocalWorkdirWatcher {
     close(): void;
 }
 export interface LocalSkillDiscoveryOptions extends LocalSkillDirectoryOptions {
@@ -262,8 +262,8 @@ export interface LocalRuntime {
     temp: LocalFileStore;
     config: LocalConfigStore;
     skills: LocalSkillStore;
-    workspaces: LocalWorkspaceManager;
-    workspace(root: string, options?: LocalWorkspaceOptions): LocalWorkspace;
+    workdirs: LocalWorkdirManager;
+    workdir(root: string, options?: LocalWorkdirOptions): LocalWorkdir;
     ensure(): Promise<void>;
 }
 export declare function createLocalRuntime(options: LocalRuntimeOptions): LocalRuntime;
@@ -322,10 +322,10 @@ export declare class LocalConfigStore {
     delete(name: string, key: string): Promise<string>;
     private readRecord;
 }
-export declare class LocalWorkspaceManager {
-    open(root: string, options?: LocalWorkspaceOptions): LocalWorkspace;
+export declare class LocalWorkdirManager {
+    open(root: string, options?: LocalWorkdirOptions): LocalWorkdir;
 }
-export declare class LocalWorkspace {
+export declare class LocalWorkdir {
     readonly root: string;
     readonly name: string;
     readonly metadata: Record<string, unknown>;
@@ -334,10 +334,10 @@ export declare class LocalWorkspace {
     readonly ignore: LocalIgnoreRule[];
     readonly gitignore: boolean;
     readonly maxFileBytes: number;
-    constructor(root: string, options?: LocalWorkspaceOptions);
+    constructor(root: string, options?: LocalWorkdirOptions);
     ensure(): Promise<void>;
     loadIgnoreFiles(files?: string[]): Promise<LocalIgnoreRule[]>;
-    child(relativePath: string, options?: LocalWorkspaceOptions): LocalWorkspace;
+    child(relativePath: string, options?: LocalWorkdirOptions): LocalWorkdir;
     resolvePath(relativePath?: string): string;
     list(relativePath?: string, options?: LocalListOptions): Promise<LocalFileStat[]>;
     listEntries(relativePath?: string, options?: LocalListOptions): Promise<LocalEntryList>;
@@ -358,16 +358,16 @@ export declare class LocalWorkspace {
     readLines(relativePath: string, params: LocalReadLinesParams): Promise<LocalFileLines>;
     previewPatchLines(relativePath: string, params: LocalPatchLinesParams): Promise<LocalLinePatchPreview>;
     patchLines(relativePath: string, params: LocalPatchLinesParams): Promise<LocalFileLinesPatch>;
-    previewEdits(edits: LocalWorkspaceLineEdit[]): Promise<LocalWorkspaceEditPlan>;
-    applyEdits(edits: LocalWorkspaceLineEdit[]): Promise<LocalWorkspaceEditResult>;
+    previewEdits(edits: LocalWorkdirLineEdit[]): Promise<LocalWorkdirEditPlan>;
+    applyEdits(edits: LocalWorkdirLineEdit[]): Promise<LocalWorkdirEditResult>;
     classifyPath(relativePath: string): LocalPathSensitivityInfo;
     grep(params: LocalGrepParams): Promise<LocalGrepResponse>;
     summarize(params?: LocalSummarizeParams): Promise<LocalSummary>;
-    snapshot(params?: LocalWorkspaceSnapshotParams): Promise<LocalWorkspaceSnapshot>;
-    diff(before: LocalWorkspaceSnapshot, after: LocalWorkspaceSnapshot): LocalWorkspaceDiff;
-    watch(onEvent: (event: LocalWorkspaceWatchEvent) => void, options?: {
+    snapshot(params?: LocalWorkdirSnapshotParams): Promise<LocalWorkdirSnapshot>;
+    diff(before: LocalWorkdirSnapshot, after: LocalWorkdirSnapshot): LocalWorkdirDiff;
+    watch(onEvent: (event: LocalWorkdirWatchEvent) => void, options?: {
         recursive?: boolean;
-    }): LocalWorkspaceWatcher;
+    }): LocalWorkdirWatcher;
     private scopedListOptions;
     private mergeIgnore;
     private assertAllowed;

package/dist/local/core.js

@@ -22,7 +22,7 @@ export class LocalPathError extends LocalError {
 }
 export class LocalIgnoredPathError extends LocalError {
     constructor(path) {
-        super("local_ignored_path", `local workspace path is ignored: ${path}`, { path });
+        super("local_ignored_path", `local workdir path is ignored: ${path}`, { path });
         this.name = "LocalIgnoredPathError";
     }
 }
@@ -62,9 +62,9 @@ export function createLocalRuntime(options) {
         temp,
         config: new LocalConfigStore(configFiles),
         skills: new LocalSkillStore(data.child("skills")),
-        workspaces: new LocalWorkspaceManager(),
-        workspace(root, workspaceOptions = {}) {
-            return new LocalWorkspace(root, workspaceOptions);
+        workdirs: new LocalWorkdirManager(),
+        workdir(root, workdirOptions = {}) {
+            return new LocalWorkdir(root, workdirOptions);
         },
         async ensure() {
             await Promise.all([data.ensure(), cache.ensure(), logs.ensure(), temp.ensure(), configFiles.ensure()]);
@@ -456,12 +456,12 @@ export class LocalConfigStore {
         return value;
     }
 }
-export class LocalWorkspaceManager {
+export class LocalWorkdirManager {
     open(root, options = {}) {
-        return new LocalWorkspace(root, options);
+        return new LocalWorkdir(root, options);
     }
 }
-export class LocalWorkspace {
+export class LocalWorkdir {
     root;
     name;
     metadata;
@@ -472,11 +472,11 @@ export class LocalWorkspace {
     maxFileBytes;
     constructor(root, options = {}) {
         this.root = path.resolve(root);
-        this.name = options.name?.trim() || path.basename(this.root) || "workspace";
+        this.name = options.name?.trim() || path.basename(this.root) || "workdir";
         this.metadata = { ...(options.metadata ?? {}) };
         this.trusted = options.trusted ?? false;
-        this.files = new LocalFileStore(this.root, { label: "workspace" });
-        this.ignore = [...defaultWorkspaceIgnoreRules(), ...(options.ignore ?? [])];
+        this.files = new LocalFileStore(this.root, { label: "workdir" });
+        this.ignore = [...defaultWorkdirIgnoreRules(), ...(options.ignore ?? [])];
         this.gitignore = options.gitignore ?? true;
         this.maxFileBytes = positiveInt(options.maxFileBytes, 10 * 1024 * 1024);
     }
@@ -503,7 +503,7 @@ export class LocalWorkspace {
         return loaded;
     }
     child(relativePath, options = {}) {
-        return new LocalWorkspace(this.files.resolvePath(relativePath), {
+        return new LocalWorkdir(this.files.resolvePath(relativePath), {
             name: options.name,
             metadata: options.metadata ?? this.metadata,
             trusted: options.trusted ?? this.trusted,
@@ -884,7 +884,7 @@ function ignored(relativePath, ignore) {
 function ignoredDirectoryName(name) {
     return name === ".git" || name === "node_modules" || name === "__pycache__";
 }
-function defaultWorkspaceIgnoreRules() {
+function defaultWorkdirIgnoreRules() {
     return [
         ".git",
         "node_modules",

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;