184e164091
One shared ctx.tasks registry (branded <kind>-N ids, owner-fenced read/kill/wait/list, attachSurface misconfiguration fence, reported-flag notice dedup, atomic register) + dsh-tool-tasks (task_output/task_list/ task_kill, completion-notice injection, background prompt habit). Producers opt in via their own enableRunInBackground config: bash (stream kind; seam slimmed to resolve/run/start returning a BashProcess handle, bash_output/bash_kill deleted) and subagent (final-output kind; done settles after run.dispose()). Owner disposal drains tasks through the new awaited ctx.agents.onCleanup seam in the loop's disposal chain. Both RFCs moved to implemented/; docs, catalogs, snapshots re-pinned.
27 lines
1.6 KiB
Markdown
27 lines
1.6 KiB
Markdown
# dsh-brand
|
|
|
|
The `Branded<B>` nominal-typing primitive — a tiny, **type-only** package (no runtime code, no harness-package dependency) shared by every package that owns a cross-boundary id.
|
|
|
|
## What `Branded` is
|
|
|
|
A brand makes structurally-identical strings non-interchangeable at the type level: an `AgentId` cannot be passed where a `CallId` is expected, even though both are plain `string`s at runtime.
|
|
|
|
```ts
|
|
import type { Branded } from '@deepseek-ai/dsh-brand'
|
|
|
|
export type SessionId = Branded<'SessionId'>
|
|
|
|
/** Brand a string as a SessionId (a plain cast — zero runtime cost). */
|
|
export function SessionId(id: string): SessionId {
|
|
return id as SessionId
|
|
}
|
|
```
|
|
|
|
Construction goes through the per-id factory in the OWNING package (a plain cast inside — zero runtime cost). Comparison, logging, JSON serialization, and the wire format all behave exactly as for an ordinary string; the brand is erased at compile time.
|
|
|
|
## Policy: brand ids that cross package boundaries
|
|
|
|
A package brands the ids it OWNS — `CallId` in `dsh-llm` (tool-call correlation), `SessionId` in `dsh-session`, `AgentId` in `dsh-agent`, `TaskId` in `dsh-tasks`. Branding is for ids that cross package boundaries and could plausibly be confused; **not every string needs a brand.**
|
|
|
|
This package owns ONLY the primitive — no concrete id, no runtime code beyond the (erased) type. Keeping the primitive dependency-free is the point: a capability package can brand its ids without depending on an unrelated package. `dsh-tasks`, for example, brands `TaskId` by depending on `dsh-brand` alone — it never pulls in `dsh-llm` (or `dsh-session`) just to reach `Branded`.
|