@downcity/shell 0.1.4

package/bin/types/Shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Shell.d.ts","sourceRoot":"","sources":["../../src/types/Shell.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,cAAc,CAAC;AAEvD;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qBAAqB;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sBAAsB;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sBAAsB;IACtB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,gBAAgB;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kBAAkB;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+BAA+B;IAC/B,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sBAAsB;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC"}

package/bin/types/Shell.js

@@ -0,0 +1,9 @@
+/**
+ * Shell 工具类型定义。
+ *
+ * 关键点（中文）
+ * - 统一沉淀 `shell_start/shell_status/shell_read/shell_write/shell_wait/shell_close` 类型。
+ * - `shell_id` 与 chat `sessionId` 严格分离，避免语义混淆。
+ */
+export {};
+//# sourceMappingURL=Shell.js.map

package/bin/types/Shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Shell.js","sourceRoot":"","sources":["../../src/types/Shell.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/ShellAction.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Shell action 类型定义。
+ *
+ * 关键点（中文）
+ * - `shell_id` 是 shell 会话的唯一标识，与 chat `sessionId` 严格区分。
+ * - 这些类型同时服务于 shell runtime 状态管理与 agent tool 协议。
+ */
+export type ShellSessionStatus = "starting" | "running" | "completed" | "failed" | "killed" | "expired";
+/**
+ * shell 执行 sandbox 模式。
+ */
+export type ShellSandboxMode = "safe" | "unrestricted";
+/**
+ * unrestricted sandbox 审批状态。
+ */
+export type ShellApprovalStatus = "approved" | "denied" | "expired";
+/**
+ * shell unrestricted sandbox 审批来源工具。
+ */
+export type ShellApprovalToolName = "shell_exec" | "shell_start" | "shell_write";
+/**
+ * shell 会话关联的外部引用。
+ *
+ * 说明（中文）
+ * - 用于记录诸如第三方平台 `thread_id`、任务链接等弱结构化引用。
+ * - 不要求所有 shell 都存在该信息；仅在可识别时附加。
+ */
+export type ShellExternalRef = {
+    /** 引用类别，例如 `thread_id`。 */
+    kind: string;
+    /** 引用的原始值。 */
+    value: string;
+    /** 可选的人类可读标签。 */
+    label?: string;
+};
+/**
+ * shell 会话快照。
+ *
+ * 说明（中文）
+ * - 该对象是 shell runtime 对外暴露的统一状态视图。
+ * - 内部运行态（child process / waiter 集合）不会暴露给上层。
+ */
+export type ShellSessionSnapshot = {
+    /** shell 唯一标识。 */
+    shellId: string;
+    /** 发起该 shell 的 chat/context 标识；不存在时表示非聊天上下文触发。 */
+    ownerContextId?: string;
+    /** 原始命令字符串。 */
+    cmd: string;
+    /** 命令执行工作目录（绝对路径）。 */
+    cwd: string;
+    /** 实际使用的 shell 可执行文件路径。 */
+    shellPath: string;
+    /** 当前 shell 是否运行在 sandbox 中。 */
+    sandboxed?: boolean;
+    /** 当前 shell 的 Downcity sandbox 模式。 */
+    sandboxMode?: ShellSandboxMode;
+    /** unrestricted sandbox 审批状态。 */
+    approvalStatus?: ShellApprovalStatus;
+    /** unrestricted sandbox 审批请求 ID。 */
+    approvalId?: string;
+    /** unrestricted sandbox 申请原因。 */
+    approvalReason?: string;
+    /** 当前 shell 是否允许继续写入 stdin。 */
+    stdinWritable?: boolean;
+    /** 当前 shell 使用的 sandbox backend。 */
+    sandboxBackend?: string;
+    /** 当前 shell 采用的 sandbox 网络模式。 */
+    sandboxNetworkMode?: "off" | "restricted" | "full";
+    /** 当前 agent 级 sandbox 的持久目录。 */
+    sandboxDir?: string;
+    /** 当前 shell 在 sandbox 中使用的 HOME。 */
+    sandboxHomeDir?: string;
+    /** 当前 shell 在 sandbox 中使用的临时目录。 */
+    sandboxTmpDir?: string;
+    /** 当前 shell 在 sandbox 中使用的 XDG cache 目录。 */
+    sandboxCacheDir?: string;
+    /** 当前 shell 状态。 */
+    status: ShellSessionStatus;
+    /** 子进程 pid；若尚未创建成功则为空。 */
+    pid?: number;
+    /** shell 创建时间戳（毫秒）。 */
+    startedAt: number;
+    /** 最近一次状态或输出变更时间戳（毫秒）。 */
+    updatedAt: number;
+    /** shell 结束时间戳（毫秒）；运行中为空。 */
+    endedAt?: number;
+    /** 进程退出码；运行中为空。 */
+    exitCode?: number;
+    /** 最近一次收到输出的时间戳（毫秒）。 */
+    lastOutputAt?: number;
+    /** 最近一小段输出预览，供状态查询快速展示。 */
+    lastOutputPreview?: string;
+    /** 当前累计输出字符数。 */
+    outputChars: number;
+    /** 因内存缓存裁剪而丢弃的字符数。 */
+    droppedChars: number;
+    /** 状态版本号；任意输出/状态变化都递增。 */
+    version: number;
+    /** 是否在 shell 结束后自动回投到所属 chat，让主 agent 自己回复。 */
+    autoNotifyOnExit: boolean;
+    /** 自动回投是否已经发送，避免重复通知。 */
+    notificationSent: boolean;
+    /** 从输出中识别到的外部引用集合。 */
+    externalRefs: ShellExternalRef[];
+};
+/**
+ * shell 启动请求。
+ */
+export type ShellStartRequest = {
+    /** 要执行的完整 shell 命令。 */
+    cmd: string;
+    /** 可选工作目录；为空时回退项目根目录。 */
+    cwd?: string;
+    /** 可选 shell 路径，例如 `/bin/zsh`。 */
+    shell?: string;
+    /** 是否以 login shell 方式启动；默认 `true`。 */
+    login?: boolean;
+    /** 启动后内联等待多久再返回首批状态/输出。 */
+    inlineWaitMs?: number;
+    /** 单次读取输出返回给模型的 token 上限。 */
+    maxOutputTokens?: number;
+    /** 显式指定 owner sessionId；为空时优先从 SessionRunScope 推断。 */
+    ownerContextId?: string;
+    /** 是否在 shell 结束后自动回投主 chat agent。 */
+    autoNotifyOnExit?: boolean;
+    /** 命令执行 sandbox 模式；默认 safe。 */
+    sandbox?: ShellSandboxMode;
+    /** 请求 unrestricted sandbox 时展示给用户的原因。 */
+    reason?: string;
+    /** 内部审批来源工具名；普通调用方不需要传。 */
+    approvalToolName?: ShellApprovalToolName;
+};
+/**
+ * shell 一次性执行请求。
+ *
+ * 说明（中文）
+ * - 适合短命令与无需中途查询状态的场景。
+ * - 底层仍复用 shell session 引擎，但调用方不需要管理 `shell_id`。
+ */
+export type ShellExecRequest = {
+    /** 要执行的完整 shell 命令。 */
+    cmd: string;
+    /** 可选工作目录；为空时回退项目根目录。 */
+    cwd?: string;
+    /** 可选 shell 路径，例如 `/bin/zsh`。 */
+    shell?: string;
+    /** 是否以 login shell 方式启动；默认 `true`。 */
+    login?: boolean;
+    /** 整个一次性执行的总超时时间（毫秒）。 */
+    timeoutMs?: number;
+    /** 单次读取输出返回给模型的 token 上限。 */
+    maxOutputTokens?: number;
+    /** 命令执行 sandbox 模式；默认 safe。 */
+    sandbox?: ShellSandboxMode;
+    /** 请求 unrestricted sandbox 时展示给用户的原因。 */
+    reason?: string;
+};
+/**
+ * shell 查询请求。
+ *
+ * 说明（中文）
+ * - `shellId` 优先级最高。
+ * - 若未提供 `shellId`，允许在同一 owner context 下按 `cmd` 模糊匹配最近一个会话。
+ */
+export type ShellQueryRequest = {
+    /** 目标 shell_id。 */
+    shellId?: string;
+    /** 命令关键字；用于在当前 context 下查找最近匹配会话。 */
+    cmd?: string;
+    /** 指定 owner sessionId；为空时优先从 SessionRunScope 推断。 */
+    ownerContextId?: string;
+    /** 是否允许匹配已结束会话。 */
+    includeCompleted?: boolean;
+};
+/**
+ * shell 输出读取请求。
+ */
+export type ShellReadRequest = ShellQueryRequest & {
+    /** 从哪个字符偏移开始读取；默认从头或从最新游标外部自行维护。 */
+    fromCursor?: number;
+    /** 单次读取输出返回给模型的 token 上限。 */
+    maxOutputTokens?: number;
+};
+/**
+ * shell stdin 写入请求。
+ */
+export type ShellWriteRequest = {
+    /** 目标 shell_id。 */
+    shellId: string;
+    /** 要写入 stdin 的原始文本。 */
+    chars: string;
+    /** 向 unrestricted shell session 写入 stdin 时展示给用户的原因。 */
+    reason?: string;
+};
+/**
+ * shell 等待请求。
+ *
+ * 说明（中文）
+ * - `afterVersion` 用于等待“状态变化”而非模型侧空轮询。
+ * - 可同时附带 `fromCursor`，一旦变化就顺便取回新的输出增量。
+ */
+export type ShellWaitRequest = {
+    /** 目标 shell_id。 */
+    shellId: string;
+    /** 仅当版本号大于该值时才立即返回。 */
+    afterVersion?: number;
+    /** 读取输出的起始字符游标。 */
+    fromCursor?: number;
+    /** 最大等待时间（毫秒）。 */
+    timeoutMs?: number;
+    /** 单次读取输出返回给模型的 token 上限。 */
+    maxOutputTokens?: number;
+};
+/**
+ * shell 关闭请求。
+ */
+export type ShellCloseRequest = {
+    /** 目标 shell_id。 */
+    shellId: string;
+    /** 是否强制 kill（SIGKILL）；默认优雅终止。 */
+    force?: boolean;
+};
+/**
+ * shell 输出块。
+ *
+ * 说明（中文）
+ * - 统一用于 `start/read/wait` 的输出增量返回。
+ * - `startCursor/endCursor` 采用字符偏移，便于上层自行维护断点。
+ */
+export type ShellOutputChunk = {
+    /** 本次输出块对应的 shell_id。 */
+    shellId: string;
+    /** 本次读取返回的文本。 */
+    output: string;
+    /** 本次读取的起始字符游标。 */
+    startCursor: number;
+    /** 本次读取结束后的字符游标。 */
+    endCursor: number;
+    /** 原始待读取文本字符数。 */
+    originalChars: number;
+    /** 原始待读取文本行数。 */
+    originalLines: number;
+    /** 是否仍有未读输出。 */
+    hasMoreOutput: boolean;
+};
+/**
+ * shell runtime 对 agent tool 返回的统一数据结构。
+ */
+export type ShellActionResponse = {
+    /** shell 当前快照。 */
+    shell: ShellSessionSnapshot;
+    /** 可选输出块；仅在 start/read/wait 中返回。 */
+    chunk?: ShellOutputChunk;
+    /** 操作说明或附加提示。 */
+    note?: string;
+};
+//# sourceMappingURL=ShellAction.d.ts.map

package/bin/types/ShellAction.d.ts.map

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

package/bin/types/ShellAction.js

@@ -0,0 +1,9 @@
+/**
+ * Shell action 类型定义。
+ *
+ * 关键点（中文）
+ * - `shell_id` 是 shell 会话的唯一标识，与 chat `sessionId` 严格区分。
+ * - 这些类型同时服务于 shell runtime 状态管理与 agent tool 协议。
+ */
+export {};
+//# sourceMappingURL=ShellAction.js.map

package/bin/types/ShellAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellAction.js","sourceRoot":"","sources":["../../src/types/ShellAction.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/ShellHostContext.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shell 宿主上下文类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 shell / sandbox 需要的最小宿主能力。
+ * - 不引用 agent 的 ShellHostContext，避免 shell 包反向绑定 agent session/runtime。
+ */
+import type { SandboxProjectConfig } from "../sandbox/types/Sandbox.js";
+export type ShellLogger = {
+    /**
+     * 输出 warning 日志。
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+};
+export type ShellSessionEventPublisher = {
+    /**
+     * 发布宿主 session event。
+     */
+    publishEvent(event: Record<string, unknown>): void;
+};
+export type ShellHostSessionAccessor = {
+    /**
+     * 通过 session id 取得可发布事件的 session 视图。
+     */
+    get(session_id: string): ShellSessionEventPublisher;
+};
+export type ShellRunContext = {
+    /**
+     * 当前 session id。
+     */
+    sessionId?: string;
+    /**
+     * 当前 turn id。
+     */
+    turnId?: string;
+};
+export type ShellHostIntegration = {
+    /**
+     * 获取当前 agent/session run 上下文。
+     */
+    getRunContext?(): ShellRunContext | null | undefined;
+};
+export type ShellHostContext = {
+    /**
+     * 当前项目根目录。
+     */
+    rootPath: string;
+    /**
+     * 传给 shell 的显式环境变量。
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * Agent 配置的最小视图。
+     */
+    config?: {
+        /**
+         * Agent id。
+         */
+        id?: string;
+        /**
+         * Sandbox 配置。
+         */
+        sandbox?: SandboxProjectConfig;
+    };
+    /**
+     * 可选日志器。
+     */
+    logger?: ShellLogger;
+    /**
+     * session event 发布器。
+     */
+    session?: ShellHostSessionAccessor;
+    /**
+     * 宿主注入的 shell 集成能力。
+     */
+    shellIntegration?: ShellHostIntegration;
+};
+//# sourceMappingURL=ShellHostContext.d.ts.map

package/bin/types/ShellHostContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellHostContext.d.ts","sourceRoot":"","sources":["../../src/types/ShellHostContext.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAEvE,MAAM,MAAM,WAAW,GAAG;IACxB;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,0BAA0B,CAAC;CACrD,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC;;OAEG;IACH,aAAa,CAAC,IAAI,eAAe,GAAG,IAAI,GAAG,SAAS,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC;;OAEG;IACH,MAAM,CAAC,EAAE;QACP;;WAEG;QACH,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ;;WAEG;QACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;KAChC,CAAC;IACF;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;OAEG;IACH,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC;;OAEG;IACH,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;CACzC,CAAC"}

package/bin/types/ShellHostContext.js

@@ -0,0 +1,9 @@
+/**
+ * Shell 宿主上下文类型。
+ *
+ * 关键点（中文）
+ * - 这里只描述 shell / sandbox 需要的最小宿主能力。
+ * - 不引用 agent 的 ShellHostContext，避免 shell 包反向绑定 agent session/runtime。
+ */
+export {};
+//# sourceMappingURL=ShellHostContext.js.map

package/bin/types/ShellHostContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellHostContext.js","sourceRoot":"","sources":["../../src/types/ShellHostContext.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/ShellRuntime.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Shell 对象运行时类型。
+ *
+ * 关键点（中文）
+ * - 这里定义 `new Shell(...)` 对外可见的最小构造参数。
+ * - Shell 自己拥有 tools、sessions、sandbox 与 approvals；Agent 只负责提供宿主上下文。
+ */
+import type { Tool } from "ai";
+import type { SandboxProjectConfig } from "../sandbox/types/Sandbox.js";
+import type { ShellApprovalStatus } from "../types/ShellAction.js";
+/**
+ * Shell 运行时日志器。
+ */
+export interface ShellRuntimeLogger {
+    /**
+     * 输出 warning 日志。
+     */
+    warn(message: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Shell 事件。
+ */
+export type ShellEvent = Record<string, unknown>;
+/**
+ * Shell 构造参数。
+ */
+export interface ShellOptions {
+    /**
+     * 项目根目录。未传时由 Agent 构造阶段补齐。
+     */
+    root_path?: string;
+    /**
+     * 传给 shell 子进程的基础环境变量。
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * Safe sandbox 配置。
+     */
+    sandbox?: SandboxProjectConfig;
+    /**
+     * 可选日志器。
+     */
+    logger?: ShellRuntimeLogger;
+    /**
+     * Shell 事件出口。Agent 会把这些事件转成 session event。
+     */
+    emit_event?: (event: ShellEvent) => void;
+}
+/**
+ * Agent 内部补齐给 Shell 的宿主参数。
+ */
+export interface ShellConfigureOptions extends ShellOptions {
+    /**
+     * Agent id。
+     */
+    agent_id?: string;
+}
+/**
+ * Shell approval 视图。
+ */
+export interface ShellApprovalView {
+    /**
+     * approval id。
+     */
+    approval_id: string;
+    /**
+     * shell session id。
+     */
+    shell_id: string;
+    /**
+     * 归属的 agent session id。
+     */
+    session_id?: string;
+    /**
+     * 来源工具名称。
+     */
+    tool_name: string;
+    /**
+     * 请求执行的命令或 stdin 文本。
+     */
+    cmd: string;
+    /**
+     * 操作类型。
+     */
+    operation: "exec" | "start" | "write";
+    /**
+     * stdin 输入预览。
+     */
+    input_preview?: string;
+    /**
+     * stdin 输入字符数。
+     */
+    input_chars?: number;
+    /**
+     * 工作目录。
+     */
+    cwd: string;
+    /**
+     * 申请原因。
+     */
+    reason: string;
+    /**
+     * 创建时间戳。
+     */
+    created_at: number;
+}
+/**
+ * Shell approval 决策结果。
+ */
+export interface ShellApprovalDecisionResult {
+    /**
+     * 操作是否命中 pending approval。
+     */
+    success: boolean;
+    /**
+     * approval id。
+     */
+    approval_id: string;
+    /**
+     * 决策。
+     */
+    decision: Extract<ShellApprovalStatus, "approved" | "denied">;
+}
+/**
+ * Shell 工具集合。
+ */
+export type ShellToolSet = Record<string, Tool>;
+//# sourceMappingURL=ShellRuntime.d.ts.map

package/bin/types/ShellRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellRuntime.d.ts","sourceRoot":"","sources":["../../src/types/ShellRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7D;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC;;OAEG;IACH,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAC1C;AAED;;GAEG;AACH,MAAM,WAAW,qBAAsB,SAAQ,YAAY;IACzD;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IACtC;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC,mBAAmB,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;CAC/D;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC"}

package/bin/types/ShellRuntime.js

@@ -0,0 +1,9 @@
+/**
+ * Shell 对象运行时类型。
+ *
+ * 关键点（中文）
+ * - 这里定义 `new Shell(...)` 对外可见的最小构造参数。
+ * - Shell 自己拥有 tools、sessions、sandbox 与 approvals；Agent 只负责提供宿主上下文。
+ */
+export {};
+//# sourceMappingURL=ShellRuntime.js.map

package/bin/types/ShellRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellRuntime.js","sourceRoot":"","sources":["../../src/types/ShellRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/bin/types/ShellRuntimeOptions.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Shell constructor 参数类型。
+ *
+ * 关键点（中文）
+ * - 所有字段都是可选 runtime 调参。
+ * - 不传参数时保持 Shell 既有硬编码默认行为。
+ * - 这些参数只影响 shell runtime，不改变 sandbox 权限模型。
+ */
+/**
+ * Shell 可选运行参数。
+ */
+export interface ShellRuntimeOptions {
+    /**
+     * 最大 in-memory shell session 数量。
+     *
+     * 超过该数量时，runtime 会优先清理已经结束的旧 session；如果仍然超限则拒绝启动新 shell。
+     */
+    maxActiveShells?: number;
+    /**
+     * 终态 shell session 在内存中保留多久后自动清理，单位毫秒。
+     */
+    cleanupDelayMs?: number;
+    /**
+     * 单个 shell session 在内存中保留的最大输出字符数。
+     *
+     * 超出的历史输出仍会写入持久化输出文件，但内存快照只保留尾部内容。
+     */
+    maxInMemoryOutputChars?: number;
+    /**
+     * shell 输出预览保留的最大字符数。
+     */
+    outputPreviewChars?: number;
+    /**
+     * wait/timeout 参数允许的最小毫秒数。
+     */
+    minWaitMs?: number;
+    /**
+     * wait/timeout 参数允许的最大毫秒数。
+     */
+    maxWaitMs?: number;
+    /**
+     * `shell.start` 默认内联等待时间，单位毫秒。
+     */
+    defaultInlineWaitMs?: number;
+    /**
+     * `shell.wait` 默认等待超时，单位毫秒。
+     */
+    defaultWaitTimeoutMs?: number;
+    /**
+     * `shell.exec` 默认总超时，单位毫秒。
+     */
+    defaultExecTimeoutMs?: number;
+    /**
+     * unrestricted sandbox 审批默认超时时间，单位毫秒。
+     */
+    defaultApprovalTimeoutMs?: number;
+}
+/**
+ * Shell 归一化后的运行参数。
+ */
+export interface ResolvedShellRuntimeOptions {
+    /**
+     * 最大 in-memory shell session 数量。
+     */
+    maxActiveShells: number;
+    /**
+     * 终态 shell session 在内存中保留多久后自动清理，单位毫秒。
+     */
+    cleanupDelayMs: number;
+    /**
+     * 单个 shell session 在内存中保留的最大输出字符数。
+     */
+    maxInMemoryOutputChars: number;
+    /**
+     * shell 输出预览保留的最大字符数。
+     */
+    outputPreviewChars: number;
+    /**
+     * wait/timeout 参数允许的最小毫秒数。
+     */
+    minWaitMs: number;
+    /**
+     * wait/timeout 参数允许的最大毫秒数。
+     */
+    maxWaitMs: number;
+    /**
+     * `shell.start` 默认内联等待时间，单位毫秒。
+     */
+    defaultInlineWaitMs: number;
+    /**
+     * `shell.wait` 默认等待超时，单位毫秒。
+     */
+    defaultWaitTimeoutMs: number;
+    /**
+     * `shell.exec` 默认总超时，单位毫秒。
+     */
+    defaultExecTimeoutMs: number;
+    /**
+     * unrestricted sandbox 审批默认超时时间，单位毫秒。
+     */
+    defaultApprovalTimeoutMs: number;
+}
+//# sourceMappingURL=ShellRuntimeOptions.d.ts.map

package/bin/types/ShellRuntimeOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellRuntimeOptions.d.ts","sourceRoot":"","sources":["../../src/types/ShellRuntimeOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,sBAAsB,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,kBAAkB,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,wBAAwB,EAAE,MAAM,CAAC;CAClC"}

package/bin/types/ShellRuntimeOptions.js

@@ -0,0 +1,10 @@
+/**
+ * Shell constructor 参数类型。
+ *
+ * 关键点（中文）
+ * - 所有字段都是可选 runtime 调参。
+ * - 不传参数时保持 Shell 既有硬编码默认行为。
+ * - 这些参数只影响 shell runtime，不改变 sandbox 权限模型。
+ */
+export {};
+//# sourceMappingURL=ShellRuntimeOptions.js.map

package/bin/types/ShellRuntimeOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShellRuntimeOptions.js","sourceRoot":"","sources":["../../src/types/ShellRuntimeOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}