@downcity/shell 0.1.4

package/bin/tool/ShellToolSchemas.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shell tool 输入 schema。
+ *
+ * 关键点（中文）
+ * - 所有 schema 统一集中，避免 `Tool.ts` 里同时混杂协议定义与执行逻辑。
+ * - 这里保持纯声明，不放任何运行时桥接细节。
+ */
+import { z } from "zod";
+export declare const shellStartInputSchema: z.ZodObject<{
+    cmd: z.ZodString;
+    workdir: z.ZodOptional<z.ZodString>;
+    shell: z.ZodOptional<z.ZodString>;
+    login: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    inline_wait_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    max_output_tokens: z.ZodOptional<z.ZodNumber>;
+    auto_notify_on_exit: z.ZodOptional<z.ZodBoolean>;
+    sandbox: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        safe: "safe";
+        unrestricted: "unrestricted";
+    }>>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const shellExecInputSchema: z.ZodObject<{
+    cmd: z.ZodString;
+    workdir: z.ZodOptional<z.ZodString>;
+    shell: z.ZodOptional<z.ZodString>;
+    login: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    max_output_tokens: z.ZodOptional<z.ZodNumber>;
+    sandbox: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        safe: "safe";
+        unrestricted: "unrestricted";
+    }>>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const shellStatusInputSchema: z.ZodObject<{
+    shell_id: z.ZodOptional<z.ZodString>;
+    cmd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const shellReadInputSchema: z.ZodObject<{
+    shell_id: z.ZodString;
+    from_cursor: z.ZodOptional<z.ZodNumber>;
+    max_output_tokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const shellWriteInputSchema: z.ZodObject<{
+    shell_id: z.ZodString;
+    chars: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const shellWaitInputSchema: z.ZodObject<{
+    shell_id: z.ZodString;
+    after_version: z.ZodOptional<z.ZodNumber>;
+    from_cursor: z.ZodOptional<z.ZodNumber>;
+    timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    max_output_tokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const shellCloseInputSchema: z.ZodObject<{
+    shell_id: z.ZodString;
+    force: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+//# sourceMappingURL=ShellToolSchemas.d.ts.map

package/bin/tool/ShellToolSchemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellToolSchemas.d.ts","sourceRoot":"","sources":["../../src/tool/ShellToolSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;iBA8BhC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;iBA0B/B,CAAC;AAEH,eAAO,MAAM,sBAAsB;;;iBAMjC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;iBAU/B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;iBAOhC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;;;;;iBAmB/B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;iBAOhC,CAAC"}

package/bin/tool/ShellToolSchemas.js

@@ -0,0 +1,130 @@
+/**
+ * Shell tool 输入 schema。
+ *
+ * 关键点（中文）
+ * - 所有 schema 统一集中，避免 `Tool.ts` 里同时混杂协议定义与执行逻辑。
+ * - 这里保持纯声明，不放任何运行时桥接细节。
+ */
+import { z } from "zod";
+const shellSandboxModeSchema = z
+    .enum(["safe", "unrestricted"])
+    .optional()
+    .default("safe")
+    .describe("Sandbox mode. safe is the default; unrestricted requires user approval.");
+const shellUnrestrictedReasonSchema = z
+    .string()
+    .optional()
+    .describe("Required when sandbox is unrestricted. Explain why host-level execution is needed.");
+export const shellStartInputSchema = z.object({
+    cmd: z.string().describe("Shell command to execute."),
+    workdir: z
+        .string()
+        .optional()
+        .describe("Optional working directory. Relative path is resolved from project root."),
+    shell: z
+        .string()
+        .optional()
+        .describe("Optional shell executable path. Example: /bin/zsh"),
+    login: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Whether to run shell as login shell (-lc). false uses -c."),
+    inline_wait_ms: z
+        .number()
+        .optional()
+        .default(1200)
+        .describe("How long to inline-wait for initial output before returning."),
+    max_output_tokens: z
+        .number()
+        .optional()
+        .describe("Maximum output tokens returned in a single read chunk."),
+    auto_notify_on_exit: z
+        .boolean()
+        .optional()
+        .describe("Whether the shell runtime should emit a completion notification when the command exits."),
+    sandbox: shellSandboxModeSchema,
+    reason: shellUnrestrictedReasonSchema,
+});
+export const shellExecInputSchema = z.object({
+    cmd: z.string().describe("Shell command to execute once and wait until completion."),
+    workdir: z
+        .string()
+        .optional()
+        .describe("Optional working directory. Relative path is resolved from project root."),
+    shell: z
+        .string()
+        .optional()
+        .describe("Optional shell executable path. Example: /bin/zsh"),
+    login: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe("Whether to run shell as login shell (-lc). false uses -c."),
+    timeout_ms: z
+        .number()
+        .optional()
+        .default(60000)
+        .describe("Total timeout for one-shot execution. Use shell_start for long-running commands."),
+    max_output_tokens: z
+        .number()
+        .optional()
+        .describe("Maximum output tokens returned in the final result."),
+    sandbox: shellSandboxModeSchema,
+    reason: shellUnrestrictedReasonSchema,
+});
+export const shellStatusInputSchema = z.object({
+    shell_id: z.string().optional().describe("Existing shell identifier."),
+    cmd: z
+        .string()
+        .optional()
+        .describe("Optional command substring to resolve the latest shell in the current chat."),
+});
+export const shellReadInputSchema = z.object({
+    shell_id: z.string().describe("Existing shell identifier."),
+    from_cursor: z
+        .number()
+        .optional()
+        .describe("Character cursor to continue reading from."),
+    max_output_tokens: z
+        .number()
+        .optional()
+        .describe("Maximum output tokens returned in this chunk."),
+});
+export const shellWriteInputSchema = z.object({
+    shell_id: z.string().describe("Existing shell identifier."),
+    chars: z.string().describe("Bytes to write to stdin."),
+    reason: z
+        .string()
+        .optional()
+        .describe("Required when writing to an unrestricted shell session. Explain why this stdin input is needed."),
+});
+export const shellWaitInputSchema = z.object({
+    shell_id: z.string().describe("Existing shell identifier."),
+    after_version: z
+        .number()
+        .optional()
+        .describe("Only return once the shell version is greater than this value."),
+    from_cursor: z
+        .number()
+        .optional()
+        .describe("Character cursor to continue reading from after the wait."),
+    timeout_ms: z
+        .number()
+        .optional()
+        .default(10000)
+        .describe("Maximum time to wait for state/output changes."),
+    max_output_tokens: z
+        .number()
+        .optional()
+        .describe("Maximum output tokens returned in this chunk."),
+});
+export const shellCloseInputSchema = z.object({
+    shell_id: z.string().describe("Existing shell identifier."),
+    force: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Whether to force-kill the shell with SIGKILL."),
+});
+//# sourceMappingURL=ShellToolSchemas.js.map

package/bin/tool/ShellToolSchemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellToolSchemas.js","sourceRoot":"","sources":["../../src/tool/ShellToolSchemas.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,sBAAsB,GAAG,CAAC;KAC7B,IAAI,CAAC,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;KAC9B,QAAQ,EAAE;KACV,OAAO,CAAC,MAAM,CAAC;KACf,QAAQ,CAAC,yEAAyE,CAAC,CAAC;AAEvF,MAAM,6BAA6B,GAAG,CAAC;KACpC,MAAM,EAAE;KACR,QAAQ,EAAE;KACV,QAAQ,CAAC,oFAAoF,CAAC,CAAC;AAElG,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACrD,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,0EAA0E,CAAC;IACvF,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,mDAAmD,CAAC;IAChE,KAAK,EAAE,CAAC;SACL,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,2DAA2D,CAAC;IACxE,cAAc,EAAE,CAAC;SACd,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,8DAA8D,CAAC;IAC3E,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,wDAAwD,CAAC;IACrE,mBAAmB,EAAE,CAAC;SACnB,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,QAAQ,CAAC,yFAAyF,CAAC;IACtG,OAAO,EAAE,sBAAsB;IAC/B,MAAM,EAAE,6BAA6B;CACtC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0DAA0D,CAAC;IACpF,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,0EAA0E,CAAC;IACvF,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,mDAAmD,CAAC;IAChE,KAAK,EAAE,CAAC;SACL,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,2DAA2D,CAAC;IACxE,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,kFAAkF,CAAC;IAC/F,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,qDAAqD,CAAC;IAClE,OAAO,EAAE,sBAAsB;IAC/B,MAAM,EAAE,6BAA6B;CACtC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IACtE,GAAG,EAAE,CAAC;SACH,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,6EAA6E,CAAC;CAC3F,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAC3D,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,4CAA4C,CAAC;IACzD,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,+CAA+C,CAAC;CAC7D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAC3D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;IACtD,MAAM,EAAE,CAAC;SACN,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,iGAAiG,CAAC;CAC/G,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAC3D,aAAa,EAAE,CAAC;SACb,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,gEAAgE,CAAC;IAC7E,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,2DAA2D,CAAC;IACxE,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,gDAAgD,CAAC;IAC7D,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,+CAA+C,CAAC;CAC7D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAC3D,KAAK,EAAE,CAAC;SACL,OAAO,EAAE;SACT,QAAQ,EAAE;SACV,OAAO,CAAC,KAAK,CAAC;SACd,QAAQ,CAAC,+CAA+C,CAAC;CAC7D,CAAC,CAAC"}

package/bin/tool/ShellTools.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shell tool 定义。
+ *
+ * 关键点（中文）
+ * - `@downcity/shell` 自己拥有 shell tool 的 schema、执行逻辑与响应整理。
+ * - Agent 只把 Shell 实例的 tools 合并到模型可调用工具集合中。
+ */
+import type { ShellActionResponse } from "../types/ShellAction.js";
+import type { ShellToolSet } from "../types/ShellRuntime.js";
+type JsonObject = Record<string, unknown>;
+export type ShellToolAction = "start" | "exec" | "status" | "read" | "write" | "wait" | "close";
+export interface ShellToolRunner {
+    /**
+     * 执行 shell action。
+     */
+    run_action(params: {
+        /**
+         * action 名称。
+         */
+        action: ShellToolAction;
+        /**
+         * action payload。
+         */
+        payload: JsonObject;
+    }): Promise<ShellActionResponse>;
+}
+/**
+ * 创建 shell tools。
+ */
+export declare function createShellTools(runner: ShellToolRunner): ShellToolSet;
+export {};
+//# sourceMappingURL=ShellTools.d.ts.map

package/bin/tool/ShellTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellTools.d.ts","sourceRoot":"","sources":["../../src/tool/ShellTools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAWlE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,MAAM,GACN,OAAO,CAAC;AAEZ,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE;QACjB;;WAEG;QACH,MAAM,EAAE,eAAe,CAAC;QACxB;;WAEG;QACH,OAAO,EAAE,UAAU,CAAC;KACrB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAClC;AAmHD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,YAAY,CAwOtE"}

package/bin/tool/ShellTools.js

@@ -0,0 +1,296 @@
+/**
+ * Shell tool 定义。
+ *
+ * 关键点（中文）
+ * - `@downcity/shell` 自己拥有 shell tool 的 schema、执行逻辑与响应整理。
+ * - Agent 只把 Shell 实例的 tools 合并到模型可调用工具集合中。
+ */
+import { tool } from "ai";
+import { shellCloseInputSchema, shellExecInputSchema, shellReadInputSchema, shellStartInputSchema, shellStatusInputSchema, shellWaitInputSchema, shellWriteInputSchema, } from "../tool/ShellToolSchemas.js";
+import { validateChatSendCommand } from "../tool/ShellToolFormatting.js";
+function flattenShellActionResponse(params) {
+    const shell_snapshot = params.response.shell;
+    const chunk = params.response.chunk;
+    const exit_code = typeof shell_snapshot.exitCode === "number" ? shell_snapshot.exitCode : null;
+    const success = shell_snapshot.approvalStatus !== "denied" &&
+        shell_snapshot.approvalStatus !== "expired" &&
+        (exit_code === null || exit_code === 0);
+    return {
+        success,
+        shell_id: shell_snapshot.shellId,
+        status: shell_snapshot.status,
+        cmd: shell_snapshot.cmd,
+        cwd: shell_snapshot.cwd,
+        sandboxed: shell_snapshot.sandboxed === true,
+        sandbox: shell_snapshot.sandboxMode || (shell_snapshot.sandboxed === false ? "unrestricted" : "safe"),
+        approval_status: shell_snapshot.approvalStatus || null,
+        approval_id: shell_snapshot.approvalId || null,
+        approval_reason: shell_snapshot.approvalReason || null,
+        stdin_writable: shell_snapshot.stdinWritable !== false,
+        sandbox_backend: shell_snapshot.sandboxBackend || null,
+        sandbox_network_mode: shell_snapshot.sandboxNetworkMode || null,
+        sandbox_dir: shell_snapshot.sandboxDir || null,
+        sandbox_home_dir: shell_snapshot.sandboxHomeDir || null,
+        sandbox_tmp_dir: shell_snapshot.sandboxTmpDir || null,
+        sandbox_cache_dir: shell_snapshot.sandboxCacheDir || null,
+        pid: typeof shell_snapshot.pid === "number" ? shell_snapshot.pid : null,
+        version: shell_snapshot.version,
+        started_at: shell_snapshot.startedAt,
+        updated_at: shell_snapshot.updatedAt,
+        ended_at: typeof shell_snapshot.endedAt === "number" ? shell_snapshot.endedAt : null,
+        exit_code,
+        output: chunk?.output || "",
+        start_cursor: typeof chunk?.startCursor === "number" ? chunk.startCursor : null,
+        end_cursor: typeof chunk?.endCursor === "number" ? chunk.endCursor : null,
+        original_chars: chunk?.originalChars ?? 0,
+        original_lines: chunk?.originalLines ?? 0,
+        has_more_output: chunk?.hasMoreOutput === true,
+        last_output_preview: shell_snapshot.lastOutputPreview || "",
+        output_chars: shell_snapshot.outputChars,
+        dropped_chars: shell_snapshot.droppedChars,
+        auto_notify_on_exit: shell_snapshot.autoNotifyOnExit,
+        notification_sent: shell_snapshot.notificationSent,
+        owner_context_id: shell_snapshot.ownerContextId || null,
+        external_refs: shell_snapshot.externalRefs,
+        wall_time_seconds: Math.max(0, (Date.now() - params.started_at) / 1000),
+        ...(params.response.note ? { note: params.response.note } : {}),
+    };
+}
+function flattenShellExecResponse(params) {
+    const shell_snapshot = params.response.shell;
+    const chunk = params.response.chunk;
+    const exit_code = typeof shell_snapshot.exitCode === "number" ? shell_snapshot.exitCode : null;
+    const success = shell_snapshot.approvalStatus !== "denied" &&
+        shell_snapshot.approvalStatus !== "expired" &&
+        (exit_code === null || exit_code === 0);
+    return {
+        success,
+        status: shell_snapshot.status,
+        cmd: shell_snapshot.cmd,
+        cwd: shell_snapshot.cwd,
+        sandboxed: shell_snapshot.sandboxed === true,
+        sandbox: shell_snapshot.sandboxMode || (shell_snapshot.sandboxed === false ? "unrestricted" : "safe"),
+        approval_status: shell_snapshot.approvalStatus || null,
+        approval_id: shell_snapshot.approvalId || null,
+        approval_reason: shell_snapshot.approvalReason || null,
+        stdin_writable: shell_snapshot.stdinWritable !== false,
+        sandbox_backend: shell_snapshot.sandboxBackend || null,
+        sandbox_network_mode: shell_snapshot.sandboxNetworkMode || null,
+        sandbox_dir: shell_snapshot.sandboxDir || null,
+        sandbox_home_dir: shell_snapshot.sandboxHomeDir || null,
+        sandbox_tmp_dir: shell_snapshot.sandboxTmpDir || null,
+        sandbox_cache_dir: shell_snapshot.sandboxCacheDir || null,
+        exit_code,
+        output: chunk?.output || "",
+        original_chars: chunk?.originalChars ?? 0,
+        original_lines: chunk?.originalLines ?? 0,
+        external_refs: shell_snapshot.externalRefs,
+        wall_time_seconds: Math.max(0, (Date.now() - params.started_at) / 1000),
+        ...(params.response.note ? { note: params.response.note } : {}),
+    };
+}
+function formatToolError(prefix, error) {
+    return {
+        success: false,
+        error: `${prefix}: ${String(error)}`,
+    };
+}
+/**
+ * 创建 shell tools。
+ */
+export function createShellTools(runner) {
+    const shell_start = tool({
+        description: "Start a shell session. Returns shell_id plus initial status/output. Long-running commands should usually be checked later with shell_status or shell_wait instead of repeated polling.",
+        inputSchema: shellStartInputSchema,
+        execute: async ({ cmd, workdir, shell, login = true, inline_wait_ms = 1200, max_output_tokens, auto_notify_on_exit, sandbox = "safe", reason, }) => {
+            const started_at = Date.now();
+            try {
+                const validation_error = validateChatSendCommand(cmd);
+                if (validation_error) {
+                    return {
+                        success: false,
+                        error: `shell_start rejected: ${validation_error}`,
+                    };
+                }
+                const response = await runner.run_action({
+                    action: "start",
+                    payload: {
+                        cmd,
+                        ...(workdir ? { cwd: workdir } : {}),
+                        ...(shell ? { shell } : {}),
+                        login,
+                        inlineWaitMs: inline_wait_ms,
+                        ...(typeof max_output_tokens === "number"
+                            ? { maxOutputTokens: max_output_tokens }
+                            : {}),
+                        ...(typeof auto_notify_on_exit === "boolean"
+                            ? { autoNotifyOnExit: auto_notify_on_exit }
+                            : {}),
+                        sandbox,
+                        ...(reason ? { reason } : {}),
+                    },
+                });
+                return flattenShellActionResponse({ response, started_at });
+            }
+            catch (error) {
+                return formatToolError("shell_start failed", error);
+            }
+        },
+    });
+    const shell_exec = tool({
+        description: "Execute a short shell command in one-shot mode and wait for completion. Prefer shell_start for long-running or interactive commands.",
+        inputSchema: shellExecInputSchema,
+        execute: async ({ cmd, workdir, shell, login = true, timeout_ms = 60000, max_output_tokens, sandbox = "safe", reason, }) => {
+            const started_at = Date.now();
+            try {
+                const validation_error = validateChatSendCommand(cmd);
+                if (validation_error) {
+                    return {
+                        success: false,
+                        error: `shell_exec rejected: ${validation_error}`,
+                    };
+                }
+                const response = await runner.run_action({
+                    action: "exec",
+                    payload: {
+                        cmd,
+                        ...(workdir ? { cwd: workdir } : {}),
+                        ...(shell ? { shell } : {}),
+                        login,
+                        timeoutMs: timeout_ms,
+                        ...(typeof max_output_tokens === "number"
+                            ? { maxOutputTokens: max_output_tokens }
+                            : {}),
+                        sandbox,
+                        ...(reason ? { reason } : {}),
+                    },
+                });
+                return flattenShellExecResponse({ response, started_at });
+            }
+            catch (error) {
+                return formatToolError("shell_exec failed", error);
+            }
+        },
+    });
+    const shell_status = tool({
+        description: "Query the current status of a shell session. Prefer this to ask for progress during long-running commands.",
+        inputSchema: shellStatusInputSchema,
+        execute: async ({ shell_id, cmd }) => {
+            const started_at = Date.now();
+            try {
+                const response = await runner.run_action({
+                    action: "status",
+                    payload: {
+                        ...(shell_id ? { shellId: shell_id } : {}),
+                        ...(cmd ? { cmd } : {}),
+                        includeCompleted: true,
+                    },
+                });
+                return flattenShellActionResponse({ response, started_at });
+            }
+            catch (error) {
+                return formatToolError("shell_status failed", error);
+            }
+        },
+    });
+    const shell_read = tool({
+        description: "Read output from a shell session starting at a character cursor. Use this only when you truly need the raw incremental output.",
+        inputSchema: shellReadInputSchema,
+        execute: async ({ shell_id, from_cursor, max_output_tokens, }) => {
+            const started_at = Date.now();
+            try {
+                const response = await runner.run_action({
+                    action: "read",
+                    payload: {
+                        shellId: shell_id,
+                        ...(typeof from_cursor === "number" ? { fromCursor: from_cursor } : {}),
+                        ...(typeof max_output_tokens === "number"
+                            ? { maxOutputTokens: max_output_tokens }
+                            : {}),
+                        includeCompleted: true,
+                    },
+                });
+                return flattenShellActionResponse({ response, started_at });
+            }
+            catch (error) {
+                return formatToolError("shell_read failed", error);
+            }
+        },
+    });
+    const shell_write = tool({
+        description: "Write text to the stdin of an existing shell session. When the target session runs in unrestricted sandbox mode, provide reason; every write requires user approval.",
+        inputSchema: shellWriteInputSchema,
+        execute: async ({ shell_id, chars, reason }) => {
+            const started_at = Date.now();
+            try {
+                const response = await runner.run_action({
+                    action: "write",
+                    payload: {
+                        shellId: shell_id,
+                        chars,
+                        ...(reason ? { reason } : {}),
+                    },
+                });
+                return flattenShellActionResponse({ response, started_at });
+            }
+            catch (error) {
+                return formatToolError("shell_write failed", error);
+            }
+        },
+    });
+    const shell_wait = tool({
+        description: "Wait for a shell session to change state or produce more output. Prefer this over manual high-frequency polling loops.",
+        inputSchema: shellWaitInputSchema,
+        execute: async ({ shell_id, after_version, from_cursor, timeout_ms = 10000, max_output_tokens, }) => {
+            const started_at = Date.now();
+            try {
+                const response = await runner.run_action({
+                    action: "wait",
+                    payload: {
+                        shellId: shell_id,
+                        ...(typeof after_version === "number" ? { afterVersion: after_version } : {}),
+                        ...(typeof from_cursor === "number" ? { fromCursor: from_cursor } : {}),
+                        timeoutMs: timeout_ms,
+                        ...(typeof max_output_tokens === "number"
+                            ? { maxOutputTokens: max_output_tokens }
+                            : {}),
+                    },
+                });
+                return flattenShellActionResponse({ response, started_at });
+            }
+            catch (error) {
+                return formatToolError("shell_wait failed", error);
+            }
+        },
+    });
+    const shell_close = tool({
+        description: "Close a shell session and release runtime resources. Use force only when a process will not exit normally.",
+        inputSchema: shellCloseInputSchema,
+        execute: async ({ shell_id, force = false }) => {
+            const started_at = Date.now();
+            try {
+                const response = await runner.run_action({
+                    action: "close",
+                    payload: {
+                        shellId: shell_id,
+                        force,
+                    },
+                });
+                return flattenShellActionResponse({ response, started_at });
+            }
+            catch (error) {
+                return formatToolError("shell_close failed", error);
+            }
+        },
+    });
+    return {
+        shell_exec,
+        shell_start,
+        shell_status,
+        shell_read,
+        shell_write,
+        shell_wait,
+        shell_close,
+    };
+}
+//# sourceMappingURL=ShellTools.js.map

package/bin/tool/ShellTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellTools.js","sourceRoot":"","sources":["../../src/tool/ShellTools.ts"],"names":[],"mappings":"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"}

package/bin/types/Shell.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Shell 工具类型定义。
+ *
+ * 关键点（中文）
+ * - 统一沉淀 `shell_start/shell_status/shell_read/shell_write/shell_wait/shell_close` 类型。
+ * - `shell_id` 与 chat `sessionId` 严格分离，避免语义混淆。
+ */
+/**
+ * shell 执行 sandbox 模式。
+ */
+export type ShellSandboxMode = "safe" | "unrestricted";
+/**
+ * shell unrestricted sandbox 申请原因。
+ */
+export type ShellUnrestrictedReason = string;
+/**
+ * 启动一个交互式 shell session 的输入。
+ */
+export type ShellStartInput = {
+    /** 要启动的命令文本。 */
+    cmd: string;
+    /** shell 进程的工作目录。 */
+    workdir?: string;
+    /** 显式指定 shell 可执行文件。 */
+    shell?: string;
+    /** 是否使用 login shell 语义启动。 */
+    login?: boolean;
+    /** 启动后内联等待输出的毫秒数。 */
+    inline_wait_ms?: number;
+    /** 最多返回多少输出 token。 */
+    max_output_tokens?: number;
+    /** 进程退出时是否自动通知调用方。 */
+    auto_notify_on_exit?: boolean;
+    /** 命令执行 sandbox 模式；默认 safe。 */
+    sandbox?: ShellSandboxMode;
+    /** 请求 unrestricted sandbox 时展示给用户的原因。 */
+    reason?: string;
+};
+/**
+ * 执行一次非持久 shell 命令的输入。
+ */
+export type ShellExecInput = {
+    /** 要执行的命令文本。 */
+    cmd: string;
+    /** 命令执行工作目录。 */
+    workdir?: string;
+    /** 显式指定 shell 可执行文件。 */
+    shell?: string;
+    /** 是否使用 login shell 语义启动。 */
+    login?: boolean;
+    /** 本次命令执行超时时间。 */
+    timeout_ms?: number;
+    /** 最多返回多少输出 token。 */
+    max_output_tokens?: number;
+    /** 命令执行 sandbox 模式；默认 safe。 */
+    sandbox?: ShellSandboxMode;
+    /** 请求 unrestricted sandbox 时展示给用户的原因。 */
+    reason?: string;
+};
+/**
+ * 查询 shell 运行状态的输入。
+ */
+export type ShellStatusInput = {
+    /** 要查询的 shell session ID。 */
+    shell_id?: string;
+    /** 可选的原始命令文本，用于宽松筛选。 */
+    cmd?: string;
+};
+/**
+ * 读取 shell 输出流的输入。
+ */
+export type ShellReadInput = {
+    /** 要读取的 shell session ID。 */
+    shell_id: string;
+    /** 从哪个游标开始增量读取。 */
+    from_cursor?: number;
+    /** 最多返回多少输出 token。 */
+    max_output_tokens?: number;
+};
+/**
+ * 向 shell session 写入输入字符。
+ */
+export type ShellWriteInput = {
+    /** 要写入的 shell session ID。 */
+    shell_id: string;
+    /** 要发送到 stdin 的字符内容。 */
+    chars: string;
+    /** 向 unrestricted shell session 写入 stdin 时展示给用户的原因。 */
+    reason?: ShellUnrestrictedReason;
+};
+/**
+ * 等待 shell 新输出的输入。
+ */
+export type ShellWaitInput = {
+    /** 要等待的 shell session ID。 */
+    shell_id: string;
+    /** 从哪个版本号之后开始等待变更。 */
+    after_version?: number;
+    /** 从哪个输出游标开始读取。 */
+    from_cursor?: number;
+    /** 最长等待时间。 */
+    timeout_ms?: number;
+    /** 最多返回多少输出 token。 */
+    max_output_tokens?: number;
+};
+/**
+ * 关闭 shell session 的输入。
+ */
+export type ShellCloseInput = {
+    /** 要关闭的 shell session ID。 */
+    shell_id: string;
+    /** 是否强制结束子进程。 */
+    force?: boolean;
+};
+//# sourceMappingURL=Shell.d.ts.map