@agent-api/sdk 1.1.5 → 1.2.1

package/dist-cjs/local/context.js

@@ -5,7 +5,7 @@ exports.summarizeLocalContextSensitivity = summarizeLocalContextSensitivity;
 const node_crypto_1 = require("node:crypto");
 const promises_1 = require("node:fs/promises");
 const core_js_1 = require("./core.js");
-async function createLocalContextPackage(workspace, params = {}) {
+async function createLocalContextPackage(workdir, params = {}) {
     const basePath = params.path ?? ".";
     const maxFiles = positiveInt(params.maxFiles, 80);
     const maxBytes = positiveInt(params.maxBytes, 256 * 1024);
@@ -16,7 +16,7 @@ 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))
@@ -53,7 +53,7 @@ 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");
@@ -68,7 +68,7 @@ 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;
@@ -76,7 +76,7 @@ async function createLocalContextPackage(workspace, params = {}) {
         files.push(packaged);
     }
     const summary = includeSummary
-        ? await workspace.summarize({
+        ? await workdir.summarize({
             path: basePath,
             maxFiles,
             previewBytes,
@@ -84,7 +84,7 @@ async function createLocalContextPackage(workspace, params = {}) {
         })
         : undefined;
     const search = includeSearch
-        ? await workspace.grep({
+        ? await workdir.grep({
             pattern: params.query,
             path: basePath,
             limit: maxFiles,
@@ -94,8 +94,8 @@ 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,
@@ -152,7 +152,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 (0, node_crypto_1.createHash)("sha256").update(await (0, promises_1.readFile)(fullPath)).digest("hex");
 }

package/dist-cjs/local/core.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.LocalSkillStore = exports.LocalWorkspace = exports.LocalWorkspaceManager = exports.LocalConfigStore = exports.LocalFileStore = exports.LocalConfigError = exports.LocalNotTextFileError = exports.LocalFileTooLargeError = exports.LocalIgnoredPathError = exports.LocalPathError = exports.LocalError = void 0;
+exports.LocalSkillStore = exports.LocalWorkdir = exports.LocalWorkdirManager = exports.LocalConfigStore = exports.LocalFileStore = exports.LocalConfigError = exports.LocalNotTextFileError = exports.LocalFileTooLargeError = exports.LocalIgnoredPathError = exports.LocalPathError = exports.LocalError = void 0;
 exports.createLocalRuntime = createLocalRuntime;
 exports.localAppDirs = localAppDirs;
 exports.classifyLocalPathSensitivity = classifyLocalPathSensitivity;
@@ -33,7 +33,7 @@ class LocalPathError extends LocalError {
 exports.LocalPathError = LocalPathError;
 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";
     }
 }
@@ -77,9 +77,9 @@ 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()]);
@@ -473,13 +473,13 @@ class LocalConfigStore {
     }
 }
 exports.LocalConfigStore = LocalConfigStore;
-class LocalWorkspaceManager {
+class LocalWorkdirManager {
     open(root, options = {}) {
-        return new LocalWorkspace(root, options);
+        return new LocalWorkdir(root, options);
     }
 }
-exports.LocalWorkspaceManager = LocalWorkspaceManager;
-class LocalWorkspace {
+exports.LocalWorkdirManager = LocalWorkdirManager;
+class LocalWorkdir {
     root;
     name;
     metadata;
@@ -490,11 +490,11 @@ class LocalWorkspace {
     maxFileBytes;
     constructor(root, options = {}) {
         this.root = node_path_1.default.resolve(root);
-        this.name = options.name?.trim() || node_path_1.default.basename(this.root) || "workspace";
+        this.name = options.name?.trim() || node_path_1.default.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);
     }
@@ -521,7 +521,7 @@ 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,
@@ -731,7 +731,7 @@ class LocalWorkspace {
         }
     }
 }
-exports.LocalWorkspace = LocalWorkspace;
+exports.LocalWorkdir = LocalWorkdir;
 class LocalSkillStore {
     files;
     constructor(files) {
@@ -904,7 +904,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-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;
+    }
+}