2026-06-20implementedarchitecture

Branded IDs everywhere they belong

在所有应有之处使用 branded ID

The harness brands `CallId` (`packages/llm/llm/src/brand.ts`) and the shared agent/session `SessionId` (`packages/core/session/src/types.ts`) using the `Branded<B> = string & { readonly [BRAND]: B }` machinery (owned by the type-only `@deepseek-ai/dsh-brand` package at `packages/util/brand/` — see its [README](../../../../packages/util/brand/README.md)) and a zero-cost cast factory per type. `dsh-brand` also states t

.agents/notes/implemented/architecture/2026-06-20-branded-ids.md

English

Problem

The harness brands CallId (packages/llm/llm/src/brand.ts) and the shared agent/session SessionId (packages/core/session/src/types.ts) using the Branded<B> = string & { readonly [BRAND]: B } machinery (owned by the type-only @deepseek-ai/dsh-brand package at packages/util/brand/ — see its README) and a zero-cost cast factory per type. dsh-brand also states the governing policy: "Branding is for ids that cross package boundaries and could plausibly be confused; not every string needs a brand." That policy is right; the problem is that it is only half-applied. Two gaps let a structurally-identical-but-semantically-wrong string slip through the type checker today.

Gap 1 — unbranded cross-boundary IDs in the bash seam. The background-job id is a plain string: BashTask.id: string (packages/shell/shell/src/types.ts), carried as string through the whole executor seam (ShellExecutor.get/ownerOf/readOutput/kill(id: string) in packages/shell/shell/src/index.ts) and validated/passed as string by the model-facing tools (validateJobId, assertTaskAccess, the job_id schema arg in packages/shell/tool-bash/src/index.ts). It is generated by a per-executor counter — `bash-${this.nextTaskId++}` in packages/shell/bash-local/src/index.ts — which gives it exactly the same name-N shape as SessionId's default (`session-${++counter}` in packages/core/session/src/index.ts). A bash job id and a session id are trivially swappable at a call site and the compiler says nothing. It is a model-facing id (the model passes job_id back to bash_output/bash_kill), so a confusion here is reachable from untrusted input.

The bash owner token is the related sub-case: ShellExecRequest.owner?: string and ShellExecSpec.owner: string | undefined (packages/shell/shell/src/types.ts) are documented as a deliberately opaque isolation key, but in every live caller the value IS the owning agent's shared Agent.id/SessionId (callerToken = (exec) => exec.agent?.id in packages/shell/tool-bash/src/index.ts) wearing a different seam-local name. It is compared for access control (owner !== callerToken(exec)), so a mismatched-but-well-typed string here is a cross-session isolation bug the type system currently cannot catch. This is the shared id alias covered by the unified agent/session identity decision.

Gap 2 — brand erosion at the boundaries of the already-branded IDs. Even CallId and SessionId decay back to bare string at exactly the places confusion is most likely: registry/store key types and public method params. Representative sites include the session store, the agent registry (both keyed by the shared SessionId), tool-presentation call-id maps, ACP's session records, and the persistence coordinator. A brand that is dropped at a collection key buys nothing on lookups — the value of the existing brands is partly unrealized.

Decision

A type-only change. Brands are zero-cost casts; nothing about runtime behavior, serialization, comparison, or the wire format changes. The decision has three parts, all honoring the existing "not every string" policy.

Brand the bash job id. Add BashTaskId = Branded<'BashTaskId'> plus its same-named factory in packages/shell/shell/src/types.ts (the package that owns the id), importing Branded from @deepseek-ai/dsh-brand exactly as SessionId does. The brand primitive lives in the dependency-free dsh-brand utility package precisely so dsh-shell can brand its ids by depending on it alone — it never pulls in dsh-llm (or dsh-session) just to reach Branded. Thread it through BashTask.id, the ShellExecutor Service Definition methods (get/ownerOf/readOutput/kill), the generation site in dsh-bash-local (brand the counter output once, at creation), and the dsh-tool-bash validate/access surface (validateJobId returns a BashTaskId; job_id is branded at the tool boundary where the model's string arrives).
Mint a distinct OwnerToken brand. Add OwnerToken = Branded<'OwnerToken'> in packages/shell/shell/src/types.ts; type ShellExecRequest.owner / ShellExecSpec.owner / ShellExecutor.ownerOf as OwnerToken | undefined. The dsh-tool-bash consumer casts the agent's shared id (SessionId) into an OwnerToken at the boundary — the one place the two vocabularies meet. The bash Service Definition never imports dsh-session. (Rationale in the next section.)
Stop the brand erosion. Propagate the existing brands to the Map key types and public method params listed under Gap 2 — Map<SessionId, Session>, Map<SessionId, Agent>, get(id: SessionId), Map<CallId, …>, ACP's SessionId surface, and the coordinator's Map<SessionId, …>. This is the larger mechanical share of the change and the part that makes the existing brands actually load-bearing on lookups, not just on struct fields.

Illustrative shape (the factory pattern is identical to the three existing brands):

import type { Branded } from '@deepseek-ai/dsh-brand'

/** A background bash task handle (generated `bash-N` by the local executor). */
export type BashTaskId = Branded<'BashTaskId'>
export function BashTaskId(id: string): BashTaskId {
  return id as BashTaskId
}

/** A bash task's opaque isolation key — the consumer's owner identity, NOT the bash seam's. */
export type OwnerToken = Branded<'OwnerToken'>
export function OwnerToken(id: string): OwnerToken {
  return id as OwnerToken
}

Alternatives considered

Why not typing `owner` as `SessionId`?

The obvious shortcut is to type owner as SessionId directly — it always is one. We reject that. The bash executor seam is a capability seam (Service Definition dsh-shell, Service Provider dsh-bash-local, Consumer dsh-tool-bash) and its owner token is documented as deliberately opaque: the executor "never interprets it (no access policy lives in the seam — that is the consumer's job)" (packages/shell/shell/src/types.ts). Typing the Service Definition's field as SessionId would import dsh-session's vocabulary into a package that must not know what an owner token means — it would couple a generic execution backend to the session model and contradict the opaque-token design. A sandboxed or remote executor that replaces dsh-bash-local should not inherit a session dependency. The distinct OwnerToken brand keeps the seam decoupled: dsh-shell knows only "an owner is some opaque branded token," and the dsh-tool-bash consumer — which already decides the access policy — is the single boundary that casts its SessionId into an OwnerToken. The brand still delivers the safety win (you cannot pass a BashTaskId or a raw string where an owner is expected) without the coupling.

Out of scope / possible extensions

Kept deliberately narrow per the "not every string needs a brand" policy. Each of these is a plausible future brand, deferred with a reason, not a commitment:

ModelId (GenerateOptions.model, the LlmRuntime adapter-registry key) — a real cross-package lookup key (config → agent → llm → adapter); a reasonable next brand, left out only to keep this decision's blast radius focused.
ToolName (the ToolRuntime key) — author-defined, human-readable, and rarely confused with another id; the weakest candidate, likely not worth a brand.
ErrorCode (HarnessError.code) — a closed vocabulary (ABORTED, NO_ADAPTER, …), not a per-instance id; better served by a string-literal union than a brand, if anything.
Numeric ordinals — turn number, step number, and the event seq are number, not string, so Branded<string> does not apply; a parallel number & { readonly [BRAND]: B } variant could brand them, but they are positional ordinals rarely passed across boundaries, so the payoff is low.
Validated construction — the brand factories are pure casts with no runtime check, and every boundary (ACP sessionId, provider-issued call.id, the empty-string fallback in dsh-llm-deepseek) trusts the raw string today. A SessionId.parse() / isValid() companion that throws on malformed input at boundaries is a genuine gap, but it is a runtime-behavior change with its own design (what is "malformed"? what happens on failure?) and belongs in its own decision, not bundled into this type-only change.

Verification

The landed invariants: BashTaskId and OwnerToken are defined in dsh-shell and threaded end-to-end (Service Definition, the dsh-bash-local generation site, the dsh-tool-bash model-facing tool) with no dsh-shell dependency on dsh-session; no collection keyed by an in-scope branded id (CallId/SessionId/BashTaskId) is keyed by bare string; public method params and exported signatures keep the brand; and brands are constructed via the cast factory at each boundary where a raw string enters (provider call id, ACP session id, model-supplied job_id), never as scattered as casts.

Consequences

Mechanical churn across two surfaces. Propagating brands touches the bash seam (Service Definition + Service Provider + Consumer) and the ACP session-id surface plus the persistence coordinator. The churn is broad but low-severity: a missed site is a compile error, not a silent bug. The change is observably type-only — no snapshot or e2e behavioral diff. It sits next to the unified agent/session identity decision because both touch the session-id / owner-token boundary; OwnerToken stays distinct from the unified id for the decoupling reason above.
Brands do not validate. A brand is a confusability guard, not a correctness proof: a wrong session id that is still a well-formed string passes the type checker exactly as before. This decision does not close that gap (see Out of scope) — it only stops the category error of passing the wrong kind of id.
The "where to stop" line stays a judgment call. Branding BashTaskId but not ToolName, OwnerToken but not ModelId, is a taste call about which strings "could plausibly be confused." Reasonable reviewers may want more or fewer; the policy in brand.ts is the tie-breaker, and this decision errs toward the ids that are model-facing or used for access control.

中文

问题

harness 使用 Branded<B> = string & { readonly [BRAND]: B } 机制，为 CallId（packages/llm/llm/src/brand.ts）和 agent（智能体）/会话共享的 SessionId（packages/core/session/src/types.ts）做 brand 处理；该机制由纯类型包 @deepseek-ai/dsh-brand 拥有，位于 packages/util/brand/，见其 README，并为每个类型提供零开销的 cast 工厂。dsh-brand 还声明了治理策略：「Branding 用于跨包边界且可能被混淆的 id；不是每个 string 都需要 brand。」 这条策略是正确的；问题在于它只落实了一半。两处缺口使得结构相同但语义错误的 string 今天仍能通过类型检查器。

缺口 1：bash seam 中未 brand 的跨边界 ID。 后台 job id 是普通 string：BashTask.id: string（packages/shell/shell/src/types.ts），作为 string 贯穿整个执行器 seam（packages/shell/shell/src/index.ts 中的 ShellExecutor.get/ownerOf/readOutput/kill(id: string)），再由面向模型的工具以 string 校验并传递（validateJobId、assertTaskAccess、packages/shell/tool-bash/src/index.ts 中 job_id 的 schema 参数）。它由每执行器计数器生成——packages/shell/bash-local/src/index.ts 中的 `bash-${this.nextTaskId++}`——其形状与 SessionId 的默认值完全相同，都是 name-N（packages/core/session/src/index.ts 中的 `session-${++counter}`）。bash job id 和会话 id 在调用点轻易就能互换，而编译器毫无反应。它是面向模型的 id（模型会把 job_id 传回 bash_output/bash_kill），所以该混淆可由不受信任的输入触达。

bash owner token 是相关的子情形：ShellExecRequest.owner?: string 和 ShellExecSpec.owner: string | undefined（packages/shell/shell/src/types.ts）被文档描述为刻意不透明的隔离键，但在所有实际调用方中，该值就是所属 agent 共享的 Agent.id/SessionId（callerToken = (exec) => exec.agent?.id，位于 packages/shell/tool-bash/src/index.ts），只是披着另一个 seam 本地名称。它被用于访问控制比较（owner !== callerToken(exec)），因此一个不匹配但类型正确的 string 在此处就是跨会话隔离 bug，而当前类型系统无法捕获。这正是统一 agent/session 标识决策覆盖的共享 id 别名。

缺口 2：已经 brand 的 ID 在边界处被侵蚀。 就连 CallId 和 SessionId 也恰好在最容易混淆的地方退化为裸 string：注册表/store 键类型和公开方法参数。代表性位置包括会话存储、agent 注册表（二者都以共享的 SessionId 为键）、工具展示层的 call-id map、ACP（Agent Client Protocol）的会话记录，以及持久化协调器。在集合键处丢弃 brand，会让既有 brand 在查找时毫无价值；它们的价值只实现了一部分。

决策

纯类型变更。Brand 是零开销 cast；运行时行为、序列化、比较和协议格式（wire format）均不变。该决策分三部分，全部遵循既有的「不是每个 string 都需要」策略。

为 bash job id 加 brand。 在 packages/shell/shell/src/types.ts（拥有该 id 的包）中添加 BashTaskId = Branded<'BashTaskId'> 及其同名工厂，从 @deepseek-ai/dsh-brand 导入 Branded，方式与 SessionId 完全一致。brand 原语位于无依赖的 dsh-brand 工具包中，正是为了让 dsh-shell 仅依赖它就能为自己的 id 加 brand，而无需引入 dsh-llm（或 dsh-session）来获取 Branded。将其贯穿 BashTask.id、ShellExecutor Service Definition 方法（get/ownerOf/readOutput/kill）、dsh-bash-local 中的生成点（在创建时对计数器输出做一次 brand），以及 dsh-tool-bash 的校验/访问面（validateJobId 返回 BashTaskId；job_id 在模型 string 到达的工具边界处被 brand）。
铸造独立的 OwnerToken brand。 在 packages/shell/shell/src/types.ts 中添加 OwnerToken = Branded<'OwnerToken'>；将 ShellExecRequest.owner / ShellExecSpec.owner / ShellExecutor.ownerOf 的类型标注为 OwnerToken | undefined。dsh-tool-bash 消费方在边界处将 agent 共享的 id（SessionId）cast 为 OwnerToken——这是两套词汇唯一交汇的地方。bash Service Definition 从不导入 dsh-session。（理由见下一节。）
阻止 brand 侵蚀。 将既有 brand 传播到缺口 2 列出的 Map 键类型和公开方法参数中：Map<SessionId, Session>、Map<SessionId, Agent>、get(id: SessionId)、Map<CallId, …>、ACP 的 SessionId surface、协调器的 Map<SessionId, …>。这是变更中机械量最大的部分，也是让既有 brand 在查找处真正发挥作用（而不仅仅标注在结构体字段上）的关键。

示意形状（工厂模式与已有的三个 brand 完全一致）：

import type { Branded } from '@deepseek-ai/dsh-brand'

/** A background bash task handle (generated `bash-N` by the local executor). */
export type BashTaskId = Branded<'BashTaskId'>
export function BashTaskId(id: string): BashTaskId {
  return id as BashTaskId
}

/** A bash task's opaque isolation key — the consumer's owner identity, NOT the bash seam's. */
export type OwnerToken = Branded<'OwnerToken'>
export function OwnerToken(id: string): OwnerToken {
  return id as OwnerToken
}

曾考虑的替代方案

为什么不把 `owner` 类型标注为 `SessionId`？

显而易见的捷径是直接把 owner 类型标注为 SessionId——它确实总是一个会话 id。我们否决这个方案。bash 执行器 seam 是能力 seam（Service Definition dsh-shell、Service Provider dsh-bash-local、Consumer dsh-tool-bash），其 owner token 被明确记录为刻意不透明：执行器「从不解释它（seam 中没有访问策略——那是消费方的职责）」（packages/shell/shell/src/types.ts）。把 Service Definition 的字段类型标注为 SessionId，会把 dsh-session 的词汇引入一个不应知道 owner token 含义的包——这会让通用执行后端耦合会话模型，并违背不透明 token 的设计。取代 dsh-bash-local 的沙箱化执行器或远程执行器不应继承会话依赖。独立的 OwnerToken brand 使 seam 保持解耦：dsh-shell 只知道「owner 是某种带 brand 的不透明 token」，而已经决定访问策略的 dsh-tool-bash 消费方，是把其 SessionId cast 为 OwnerToken 的唯一边界。该 brand 仍带来安全收益（不能把 BashTaskId 或裸 string 传到 owner 位置），且不引入耦合。

不在范围内 / 可能的扩展

遵循「不是每个 string 都需要 brand」的策略，刻意保持窄范围。以下每项都是合理的未来 brand 候选，附带推迟理由而非承诺：

ModelId（GenerateOptions.model，LlmRuntime 适配器注册表的键）：一个真正的跨包查找键（config → agent → llm → 适配器）；合理的下一个 brand，仅为控制本决策的影响范围而暂不纳入。
ToolName（ToolRuntime 的键）：由作者定义、人类可读，且很少与其他 id 混淆；最弱的候选，可能不值得加 brand。
ErrorCode（HarnessError.code）：一个封闭词汇（ABORTED、NO_ADAPTER……），不是逐实例的 id；如果要做，string 字面量联合类型比 brand 更合适。
数值序号：轮次号、步骤号和事件 seq 是 number 而非 string，Branded<string> 不适用；可以用并行的 number & { readonly [BRAND]: B } 变体来 brand 它们，但它们是位置序号、很少跨边界传递，收益较低。
带校验的构造：brand 工厂是纯 cast，无运行时检查，且每个边界（ACP sessionId、提供方签发的 call.id、dsh-llm-deepseek 中的空字符串回退）今天都信任裸 string。一个在边界处对格式错误的输入抛异常的 SessionId.parse() / isValid() 配套工具确实是缺口，但它是运行时行为变更，有自己的设计问题（什么算「格式错误」？失败时会怎样？），应在独立决策中处理，不应捆绑进这次纯类型变更。

验证

已落地的不变式如下：BashTaskId 和 OwnerToken 定义在 dsh-shell 中，并端到端贯穿 Service Definition、dsh-bash-local 生成点与 dsh-tool-bash 面向模型的工具，且 dsh-shell 未添加对 dsh-session 的依赖；没有任何以范围内 brand id（CallId/SessionId/BashTaskId）为键的集合使用裸 string；公开方法参数和导出签名保留 brand；每个原始 string 进入的边界（提供方 call id、ACP 会话 id、模型提供的 job_id）都通过 cast 工厂构造 brand，而不是散落的 as cast。

后果

两个接口面的机械性改动。 传播 brand 涉及 bash seam（Service Definition + Service Provider + Consumer）以及 ACP 会话 id 接口和持久化协调器。改动面广但严重度低：遗漏的位置是编译错误而非静默 bug。从可观察行为看，这是一项纯类型变更——无快照或 e2e 行为差异。它与统一 agent/会话标识决策相邻，因为二者都触及会话 id / owner-token 边界；OwnerToken 出于上述解耦理由仍与统一后的 id 保持独立。
Brand 不做校验。 Brand 是混淆防护，不是正确性证明：一个错误的会话 id 只要仍是格式正确的 string，就和以前一样能通过类型检查器。本决策不关闭这个缺口（见「不在范围内」）——它只阻止这类类别错误：传入错误种类的 id。
「在哪里停下」仍是判断题。 为 BashTaskId 加 brand 但不为 ToolName 加，为 OwnerToken 加但不为 ModelId 加，是对哪些 string「可能被混淆」的品味判断。合理的评审者可能想要更多或更少；brand.ts 中的策略是裁决依据，本决策倾向于面向模型或用于访问控制的 id。