# Bash 执行器

[English](bash.md) | 中文

Bash 执行 seam：典型的[能力 seam](../rfc/implemented/architecture/2026-06-13-capability-seams.md) 示例，拆分为三个包（package）：接口（[dsh-bash](../../packages/bash/bash)，`ctx.bash`）、实现（[dsh-bash-local](../../packages/bash/bash-local)，本地子进程）、消费方（[dsh-tool-bash](../../packages/bash/tool-bash)，`bash`/`bash_output`/`bash_kill` 工具 schema）。Bash 是**一项可选能力**，不属于 agent loop（智能体循环）主干，因此其词汇定义在此，而非 [core.md](core.md)。沙箱化、容器化或远程后端只需作为兄弟包实现同一接口。

源码：[`packages/bash/bash/src/types.ts`](../../packages/bash/bash/src/types.ts)

## 请求与规格：`resolve()` 拆分

该 seam 将**面向模型/插件的请求**（`workdir`/`timeoutMs` 可选，由配置填充）与**执行器实际执行的完全解析规格**（这些字段为必填）分开。工具层在二者之间调用 `ctx.bash.resolve(request)`。这是本仓库「包边界处显式优于隐式」规则的具体体现：读到一个 `BashExecSpec` 的人永远不必猜测工作目录从何而来。

```ts type-equiv
interface BashExecRequest {
  command: string
  /** Working directory override (default: implementation-configured). */
  workdir?: string | undefined
  /** Timeout override in milliseconds (implementations cap it). */
  timeoutMs?: number | undefined
  /** Abort signal — implementations kill the command when it fires. */
  signal?: AbortSignal | undefined
  /**
   * Bytes to write to the command's stdin, then close it. Absent leaves stdin
   * closed/empty (the default for model-driven tool calls). Set by in-process
   * plugins (e.g. the hooks bridges, which write a hook command's JSON payload
   * to its stdin); the model-facing bash tool does not expose it as a parameter
   * (a model that needs stdin uses shell syntax like a heredoc or a pipe).
   */
  stdin?: string | undefined
  /**
   * Extra environment entries for the command, merged AFTER the
   * implementation's credential scrub (so an explicit entry here is honored even
   * when its name matches the scrub pattern — the caller named a value it holds,
   * not the harness's ambient secret). Set by in-process plugins (the hooks
   * bridges set `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the model-facing
   * bash tool does not expose it as a parameter (a model that needs an env var
   * uses shell syntax like `FOO=bar cmd`).
   */
  env?: Record<string, string> | undefined
  /**
   * Opaque OWNER token for a background task — the consumer's isolation key
   * (the tool layer passes the owning agent's `session.header.id`). The
   * executor stores it on the task and exposes it via {@link BashExecutor.ownerOf};
   * the executor itself NEVER interprets it (no access policy lives in the
   * seam — that is the consumer's job). Absent for foreground runs and for an
   * ownerless background start (a non-agent caller).
   */
  owner?: OwnerToken | undefined
  /**
   * Explicit per-call sandbox-policy input, overriding the executor's
   * configured default mode for THIS call. Never a silent default: a
   * consumer sets it only from an explicit policy source — an
   * `'allowed-once'` grant a human just issued through `ctx.approval` (the
   * escalation flow in the sandbox RFC § Escalation, which outranks), or the
   * session's standing override folded from its own `bash/sandbox-mode`
   * events (the sandbox RFC § Per-session mode switching — the user's recorded per-session
   * choice). A sandboxing executor confines THIS call under the given mode;
   * a non-sandboxing executor carries the field and confines nothing (the
   * tool layer stamps neither escalation nor overrides without a sandboxing
   * executor — see {@link BashExecutor.sandboxMode}).
   */
  sandboxMode?: SandboxMode | undefined
}
```

```ts type-equiv
interface BashExecSpec {
  command: string
  workdir: string
  timeoutMs: number
  /** Abort signal — implementations kill the command when it fires. */
  signal?: AbortSignal | undefined
  /**
   * Bytes to write to the command's stdin (then close it), carried through
   * verbatim from {@link BashExecRequest.stdin}. OPTIONAL on the resolved spec
   * (unlike `owner`): it has no config default, so a missing one means "no
   * stdin" — the safe, ordinary case — not a silent footgun, so it stays a
   * plain optional rather than required-but-nullable (see the request field).
   */
  stdin?: string | undefined
  /**
   * Extra environment entries, carried through verbatim from
   * {@link BashExecRequest.env} and merged by the implementation AFTER its
   * credential scrub (an explicit entry wins even when its name matches the
   * scrub pattern). OPTIONAL on the spec for the same reason as `stdin` — no
   * config default, absent means "no extra env".
   */
  env?: Record<string, string> | undefined
  /**
   * Opaque owner token, REQUIRED-but-nullable (mirrors `workdir`/`timeoutMs`
   * being required on the resolved spec): {@link BashExecutor.resolve} carries
   * the request's `owner` through, defaulting a missing one to `undefined`. A
   * required field makes a forgotten owner a VISIBLE `undefined` rather than a
   * silently-absent property that yields an unowned (cross-session-readable)
   * task. `start()` stores it; `run()` (foreground) ignores it.
   */
  owner: OwnerToken | undefined
  /**
   * The sandbox mode this call executes under, REQUIRED-but-nullable for the
   * same visibility reason as `owner`. A sandboxing executor's `resolve()`
   * stamps the effective mode (the request's explicit override, else its
   * configured default) so `run()`/`start()` read the spec, never the config;
   * a non-sandboxing executor carries the request value through verbatim and
   * ignores it (`undefined` under such an executor means what its README says:
   * unconfined execution).
   */
  sandboxMode: SandboxMode | undefined
}
```

`owner` token 是隔离键：执行器存储它但从不解释它（访问策略是消费方的职责），因此一个 agent 启动的后台任务不会被跨会话读取。必填但可空的字段设计使得遗忘 owner 会表现为一个可见的 `undefined`，而非一个静默无主的任务。

受信的进程内插件使用 `stdin` 和 `env` 传递钩子载荷和钩子专用变量。面向模型的 bash 工具从其命名 schema 字段构造请求，不暴露这两个输入，因为 shell 语法已提供等价能力；测试会防止未来出现 `...args` 展开。这是请求形状纪律，而非安全边界：`dsh-bash-local` 无论这些字段如何都会清洗环境凭证，然后叠加调用方已持有的显式值。详见 [bash stdin/env RFC](../rfc/implemented/architecture/2026-06-30-bash-stdin-env-trusted-plugin-surface.md)。

该 seam 处理的两个 id 都是[品牌化](core.md)的（零成本 `string` 品牌，与 `SessionId`/`AgentId` 同一套机制）：`BashTaskId`（被追踪的后台任务，由本地执行器生成 `bash-N`）和 `OwnerToken`（不透明的隔离键）。`OwnerToken` 刻意是与 `SessionId` **不同**的品牌，而非别名：bash seam 是一个能力 seam，它不得知道 owner token *意味着什么*，因此从不导入 `dsh-session` 的词汇。将所属 agent 的 `SessionId` 转换为 `OwnerToken` 的唯一边界是 `dsh-tool-bash` 消费方。对两者都做品牌化，可以防止裸 `string`（或在需要 `OwnerToken` 的位置传入 `BashTaskId`，反之亦然）在面向模型的 `task_id` 路径上通过类型检查。

## 前台运行：`BashRunResult`

一次已完成（或被终止）的前台运行的结果。正交的结果**独立报告**：一个进程可以既超时又以 exit 0 退出（因为它捕获了信号），因此 `timedOut`、`aborted`、`signal` 和 `exitCode` 各自独立为一个字段；调用方永远不会把一次被截断的运行误读为干净的成功。

```ts type-equiv
interface BashRunResult {
  /** Exit code; null when the process died from a signal. */
  exitCode: number | null
  /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
  signal: NodeJS.Signals | null
  /** True when the executor's own timeout killed the command. */
  timedOut: boolean
  /** True when the caller's AbortSignal killed the command. */
  aborted: boolean
  /** The effective timeout applied to this run (after defaulting/capping). */
  timeoutMs: number
  stdout: CollectedOutput
  stderr: CollectedOutput
  /**
   * Sandbox facts, present iff a sandboxing executor ran the command — an
   * unsandboxed executor (e.g. `dsh-bash-local`) never sets it. See
   * {@link BashSandboxInfo} for the `denied` classification semantics.
   */
  sandbox?: BashSandboxInfo
}
```

每个流是一个 `CollectedOutput`：（可能被截断的）文本加恢复信息。截断时，`text` 是**尾部**，完整流溢出到一个私有文件：

```ts type-equiv
interface CollectedOutput {
  /** Collected text — the TAIL of the stream when truncated. */
  text: string
  /** True when bytes were dropped from `text`. */
  truncated: boolean
  /** Path to a file holding the COMPLETE stream, when truncated and available. */
  spillPath?: string
}
```

## 文件沙箱：`BashSandboxInfo`

消费沙箱的执行器（`dsh-bash-sandbox`）通过 `BashExecutor.sandboxMode` 暴露其配置的回退模式。工具层折叠每个 agent 会话的持久 `bash/sandbox-mode` 覆盖，将生效模式盖章到请求上，并可能为一次用户批准的严格更宽调用替换它。工具层刻意不声明当前模式，也不叙述切换过程；拒绝结果会指明该命令实际运行时所处的模式。模式/强制词汇由 [`@deepseek-ai/dsh-sandbox` seam](sandbox.md) 拥有并编目，其提供方包装执行器的 argv；模式仅管辖文件效果，不管网络或进程可见性。

沙箱化运行始终在 `BashRunResult.sandbox` 上报告其执行时的事实：`denied` 是执行器对「失败由沙箱引起」的保守分类（一次失败退出且 stderr 带有文件系统权限签名——从不是干净退出或信号终止），从收集的 stderr 尾部读取；`enforcement` 报告所选后端对该模式文件效果的治理完整度（`SandboxEnforcement = 'full' | 'partial'`——当较旧的 Landlock ABI 仅治理所请求访问的子集时为 `partial`；`danger-full-access` 下不存在，因为什么都没被限制）；`runnerFailed` 标记与拒绝相反的情况——沙箱 runner 本身失败，命令从未运行（仅在已结算的后台任务上盖章；前台运行通过抛出 `SANDBOX_UNAVAILABLE` 错误暴露同一状况）：

```ts type-equiv
interface BashSandboxInfo {
  /** The mode the command actually ran under. */
  mode: SandboxMode
  /**
   * True when the executor classifies this run's failure as the sandbox
   * denying a file operation. The classification is CONSERVATIVE (a failed
   * exit whose stderr carries a filesystem-permission signature) and reads
   * the COLLECTED stderr — the bounded in-memory tail per
   * {@link CollectedOutput} semantics, so a signature that survives only in a
   * spill file is missed toward `denied: false`. A plain command failure
   * keeps `denied: false` even under a sandboxed mode.
   */
  denied: boolean
  /**
   * How completely the runner enforced `mode`'s file effects — see
   * {@link SandboxEnforcement}. Absent exactly when `mode` is
   * `danger-full-access`: nothing is confined, so there is no enforcement to
   * report.
   */
  enforcement?: SandboxEnforcement
  /**
   * True when the executor classifies this failure as the SANDBOX RUNNER
   * itself failing (missing binary, refused profile, fail-closed refusal
   * before exec) — the command NEVER RAN; this is a sandbox failure, not a
   * task failure, and it outranks `denied` (a runner's own error text can
   * contain denial words). Only ever stamped on settled BACKGROUND tasks: a
   * foreground run surfaces the same condition as the thrown
   * `SANDBOX_UNAVAILABLE` error instead (the foreground path has an error
   * channel; a settled task's facts are its only channel).
   */
  runnerFailed?: boolean
}
```

还有一个词汇完成整幅图景：`SANDBOX_UNAVAILABLE` 错误码（由 [sandbox seam](sandbox.md) 拥有）是 `ctx.sandbox` 提供方在受限模式没有可用后端时抛出的——执行器将其传播。所选 runner 拒绝其 profile 也会到达同一个快速失败的前台错误；已结算的后台任务则记录 `runnerFailed`。模型在结果中收到拒绝/runner 事实，仅在拒绝标记指明模式时才得知生效模式，并可通过 `sandbox_permissions` 加 `justification` 请求一次严格更宽的重试；`ctx.approval` 必须在任何执行之前批准该确切调用。完整的策略与切换设计见 [sandbox RFC](../rfc/implemented/feature/2026-07-06-sandbox.md)。

## 后台任务：`BashTask`

通过 `start()` 启动的长时间运行命令被追踪为 `BashTask`。`BashTaskStatus` 为 `'running' | 'completed' | 'killed'`；`done` 在底层进程关闭时 resolve，从不 reject。沙箱化执行器在任务结算后盖章 `sandbox`（分类针对已结算任务收集的 stderr 运行），因此该字段在运行中以及非沙箱化执行器下不存在。

```ts type-equiv
interface BashTask {
  readonly id: BashTaskId
  status: BashTaskStatus
  /** Exit code once finished (null = killed by signal / still running). */
  exitCode: number | null
  /** Terminating signal name, when signal-killed. */
  signal: NodeJS.Signals | null
  /** Resolves when the underlying process closes (never rejects). */
  readonly done: Promise<void>
  /**
   * Sandbox facts for this task's execution, stamped by a sandboxing executor
   * once the task settles and BEFORE completion listeners are notified — an
   * `onTaskDone` consumer and a `done` awaiter both see it. Denial
   * classification runs against the settled task's collected stderr, so the
   * field cannot exist earlier: absent while the task is running and under an
   * executor that does not sandbox. See {@link BashSandboxInfo} for the
   * `denied` semantics.
   */
  sandbox?: BashSandboxInfo
}
```

`readOutput()` 返回增量的 `BashTaskRead`：自上次读取以来产生的输出，附带一个 `lossy` 标志表示截断丢弃了未读字节：

```ts type-equiv
interface BashTaskRead {
  task: BashTask
  /** Output produced since the previous read (stderr in a marked section). */
  delta: string
  /** True when truncation dropped unread bytes the delta cannot include. */
  lossy: boolean
  /** Full stdout spill file, when stdout truncation occurred and a safe path is available. */
  stdoutSpillPath?: string
  /** Full stderr spill file, when stderr truncation occurred and a safe path is available. */
  stderrSpillPath?: string
}
```

## 服务

`BashExecutor`（`ctx.bash`，抽象——定义于 [`packages/bash/bash/src/index.ts`](../../packages/bash/bash/src/index.ts)）镜像 `LlmService`/`LlmAdapter` 的拆分：`resolve`（请求→规格）、`run`（前台）、`start`（后台）、`get`/`ownerOf`/`list`/`readOutput`/`kill`，以及 `onTaskDone`（`BashTaskListener` 完成回调）。spawn 的命令获得一个**清洗后的 env**（丢弃 `*KEY*`/`*SECRET*`/`*TOKEN*`），溢出文件使用一个权限为 0700 的私有目录（随机文件名、仅所有者可打开）——模型输出永远拿不到宿主环境或可预测路径。提供这一切的实现是 `dsh-bash-local`；调用它的面向模型的 `bash`/`bash_output`/`bash_kill` schema 位于 `dsh-tool-bash`（并通过[工具呈现词汇](tools.md#tool-presentation-ui-vocabulary)以终端形式展示）。