super-dsh 0.3.0-a → 0.3.0-d

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch13-subsystems-core-session.md

@@ -1,106 +0,0 @@
-# Chapter 13: Subsystems — Core, Session & Conversation
-
-## Core Idea
-The `packages/core` spine drives one loop — claim queued input → open a turn on the append-only `SessionEvent` log → assemble the request prefix via `ctx.systemPrompt` → stream the model → dispatch tools → append every model-visible fact back to the log. Message history is *derived* from the log (`deriveMessages()`), never stored; everything a plugin touches (agent handle, inbox, prompt sections, conversation nodes, scope) hangs off that log.
-
-## Frameworks Introduced
-- **Core spine (6 packages)**: `session/` (log, `ctx.sessions`), `system-prompt/` (`ctx.systemPrompt`), `tools/` (`ctx.tools`), `agent/` (`ctx.agents`), `agent-loop/` (concrete driver, `ctx.agentLoop`), `scope/` (dependency-free primitive below session/system-prompt to avoid cycles).
-  - When to use: any extension — depend on `agent`, never `agent-loop` directly (keeps the loop swappable). `dsh-base` is the default composition; `dsh-sdk-minimal` the smaller tree.
-- **Subsystem taxonomy (README grouping)**: ~50 pages, one per subsystem, each owning vocabulary + wiring + generated Cordis API section. Clusters: core loop (core, session, system-prompt, tools, scope), LLM (llm-streaming, token-meter), persistence/settings/credentials seams, session-derived surfaces (query, feedback, title, reference, projection, telemetry), execution seams (shell, subprocess, terminal, sandbox, code-runtime, filesystem, lsp), agent fan-out (subagent, agent-team, workflow, jobs), UI (web-client, client-modules, slots, conversation), gating/audit (approval, permission-presets, plan, invariants), infra (web-server, webhook, storage, workspace, extensions).
-- **AgentHandle ownership model**: `AgentHandle { agent, dispose() }` from `ctx.agents.create()/resume()`; dispose = stop loop → await exit → unregister → remove session → unwind scoped world. The factory provider is a structural owner; config-created agents are owned by the loop fiber.
-  - How: `setup(agentCtx)` composes the scoped world before `agent/created` publication; a setup rejection/commit throw/owner disposal rolls back both ids unpublished.
-- **Inbox delivery vocabulary**: `InboxTarget = 'next-turn' | 'next-step'`; `send(message, target, wakeup)` is the unified route; `followup`/`steer`/`inject` are fixed presets (sole ordinary turn message / nearest step boundary / next pre-step without waking).
-- **Conversation node assembly**: one `ConversationNodeAssembler` per Session applies registered Definitions over a contiguous `SessionEventLikeEntry` window; Definitions correlate by stable `(kind, id)`, fold deterministic State, publish target-owned nodes.
-- **Runtime invariants registry** (`ctx.invariants`): package-owned checks; every workspace package publishes a `./invariant` companion registering under its exact npm name.
-
-## Key Concepts
-- **AgentStatus**: `'idle' | 'running'`; `running` is the driver-wide drain interval (may span queued turns), not proof a turn is open; disposal is not a status.
-- **SessionEvent envelope**: `{ type, seq (monotonic, seq = log.length), time, data }`, discriminated union over `type`; conditional `sourceEventSeqs`/`surfaceOp` only on surface types; optional `ignorable?: true` lets safe-skipping readers skip unknown informational events (absent = required — refuse to reconstruct).
-- **SurfaceEventType**: `user/message | assistant/message | tool/result` — the only types producing LLM messages; `SurfaceOp = 'append' | { op: 'replace', start, end }` (compaction shadows inclusive seq ranges).
-- **EpochHeader**: logged request state — `{ config: LlmCallConfig, adapterDefaults?, system?, tools? }`; `request/header` reasons: `'initial' | 'resume' | 'change' | 'series'` (+ `startsSeries`); `foldRequestHeader` takes the latest snapshot. `request/context` records route capacity separately (never folded into header equality).
-- **TurnEndReason** (merge-extensible): `completed | aborted(reason: TurnEndCancelCause) | blocked | error(LlmFailure) | max-tokens | interrupted` — `interrupted` is synthesized only by crash recovery, never emitted live; any max-tokens step makes the whole turn `max-tokens`.
-- **session/end-seed**: constructor-only writer marking seed-vs-live cut; last `{ inherited: true }` marker = fork lineage cut; lets bracket owners (e.g. compaction) treat pre-boundary open markers as dead lifecycles.
-- **Initiator scope**: `ctx.agents.currentInitiator()/requireInitiator()/withInitiator(agent, op)/withoutInitiator(op)` — same-process causal attribution only; ambient presence is neither liveness proof nor authorization.
-- **Predecessor reads**: `start` receives a `ConversationContextReader`; `reader.previous<State>(kind)` returns the nearest earlier started Context; the assembler reruns dependents when an older prepend revises it.
-- **Dynamic Cordis extensions**: `ctx.dynamicCordisRunner` — versioned immutable Packages under stable Plugin ids, Host/Client halves, approval-gated Client activation (`ApprovalRequestId`, `approveFutureVersions`), `inventory()`/`snapshot(agent)`/`inspectPackage()` source-free reads.
-
-## Mental Models
-- Think of the Session log as the database and `deriveMessages()` as a materialized cached view — replay is re-derivation, requests are pure functions of the log (reconstructability).
-- Use `inject()` for model-facing context without waking the driver; `steer()` to bend the nearest step; `followup()` when the message must own its own turn.
-- Think of Scope as "one registration context = per-agent visibility + shared lifetime": `ScopeKey` (opaque object; the live Agent is its own key), `Scoped<T>` carrier for scope-filtered events, `Scope { ctx, rawDispose, dispose }` for ordered composite teardown.
-- Treat prompt assembly as cooperative: sections/contexts/tools/variables assemble → `system-prompt/assemble` waterfall → an effective `complete` section is restored afterwards as the sole section.
-
-## Anti-patterns
-- **Switching with `assertNever` over `SessionEvent`**: the map is merge-extensible; a plugin variant is a valid unknown — handle known cases, fall through `default`.
-- **Scanning the event window / all Contexts per append in a Definition**: breaks the D-matches + O(1) key-lookup property; use State, Location data, `reader.previous()`.
-- **Appending `session/end-seed` from a plugin**: would silently classify all live events before it as seed history; the Session constructor is the only legitimate writer.
-- **Non-JSON event data (Map/Set/Date/class instance, negative zero, …)**: `Session.append` throws at the source — fail at append, never at backend flush.
-- **Withdrawing a published conversation node with `null`**: keep the key, use `visibility: 'hidden'`.
-- **Assigning updates to "the latest unfinished Context"**: every correlated event must carry or derive the same stable business id.
-
-## Code Examples
-```ts
-// Delivery routing (Agent handle)
-send(message: UserMessage, target: 'next-turn' | 'next-step', wakeup: boolean): void
-cancel(cause: AgentCancelCause /* 'user'|'parent'|{kind:'hook',reason}|'disposed' */,
-       options?: { keepInbox?: boolean }): void
-runMaintenance<T>(task: (signal: AbortSignal) => Promise<T>): Promise<T> // from true idle only
-
-// Inbox splices (durable, via agent/inbox/spliced)
-claim(target): removes all next-step input + one next-turn message at turn boundary (no discard emits)
-
-// Conversation Definition shape
-interface ConversationNodeDefinition<S> {
-  kind: string; target: string;
-  match(event): { id: string; role: 'start' | 'update' } | null;
-  start(context, match): S; update(context, match): S;
-  publication?: 'immediate' | 'animation-frame' | 'none';
-  buildLocationData?(context, scope): LocationData | null;
-  buildViewNode?(context): Node | null; // must pair with target
-}
-
-// Invariants
-type InvariantFailure = (message: string) => never  // throws InvariantError code:'INVARIANT'
-ctx.invariants.register(packageName, { inject?, (ctx, fail) => {...} })
-```
-
-## Reference Tables
-| Prompt contributor | Register via | Ordering |
-|---|---|---|
-| PromptSection (`complete?`, `{{var}}` text) | `ctx.systemPrompt.section()` | ascending `order`, ties by name; repo orders via `getSectionOrder()` |
-| PromptContext (durable user-role snapshot) | `ctx.systemPrompt.context()` | ascending `order`; `getContextOrder()`; `suppressRuntimeContext()` to hide all |
-| Tool schemas | `ctx.systemPrompt.tools(provider)` | `ToolProviderResult { schemas, knownNames? }`; reserved `TOOL_ORDER_REST` name fails assembly |
-| Variables `[a-z][a-z0-9_]*` | `ctx.systemPrompt.variable(name, provider)` | scoped shadows global |
-
-| Agent event | Mode | Contract |
-|---|---|---|
-| `agent/pre-step` | waterfall | reject/enter with messages; only waterfall before request derivation |
-| `agent/request` | waterfall | replace frozen `LlmCallConfig`; cannot mutate messages |
-| `agent/request-error` | waterfall | return `{kind:'retry'}` without `next()` to own recovery |
-| `agent/turn-stopping` | serial | object by calling `agent.steer(...)`; data decides, order can't |
-| `agent/session-start` | emit | seed via `agent.inject()`; source `startup|resume|clear|compact` |
-| `agent/assistant-stream` | emit | transient start/chunk/end frames before durable settlement |
-| `session/event` | emit | post-commit firehose; constructor seeds never emit |
-| `session/flush` | parallel | durability checkpoint via `ctx.sessions.flush(session)` only |
-
-| Invariant selection (`Config`) | Default | Semantics |
-|---|---|---|
-| `enabled` | `true` | global switch |
-| `package_allowlist` | `[]` (admit all) | unanchored regex sources, `new RegExp(source)` |
-| `package_blocklist` | — | overrides an allowlist match |
-
-## Key Takeaways
-1. Never persist or cache message history — derive from the log; append is synchronous, durability is async (`session/flush` via `ctx.sessions.flush`).
-2. Plugin event types must be log-only (no `surfaceOp`) unless they produce messages; merge `SessionEventMap`/`TurnEndReasonMap` by declaration merging, switch with `default` not `assertNever`.
-3. For ordered agent teardown use `prepare`/`enter`/`announce` (exact Cordis disposer identity is load-bearing); plain `ctx.sessions.create` is for fiber-owned sessions only.
-4. Fork via `ctx.sessions.fork(source, boundary?)` — must end outside an open turn; `recompose`/`composeFrom` bind children to the parent's exact preset generation, never re-resolve by id.
-5. Invariant companions: register under the exact npm name; empty installers must start `No runtime invariant:` with a package-specific reason — `verify-package-invariants` mechanically rejects violations.
-6. Checks assert event/data relationships, never service or method presence; a reservation holds even when filters disable the installer (no silent name theft).
-
-## Connects To
-- **Ch 14**: the agent loop drives this spine turn-by-turn; interception contracts detail.
-- **Ch 15**: `ctx.tools` registry and the guarded execution pipeline behind `tool/call`/`tool/result`.
-- **Ch 16**: persistence (`SessionPersistence`, JSONL, crash recovery, `SessionHeader`) consumes the durability contract here.
-- **Ch 17**: `Message`/`ContentBlock`/`StreamChunk` vocabulary the log embeds.
-- **Ch 08**: architecture page owns the cross-subsystem event taxonomy and lifecycle.
-- **Ch 04/05**: Scope/ScopedLayers and the dispatch modes (emit/waterfall/serial/parallel) are Cordis primitives used throughout.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch14-subsystems-agent-loop.md

@@ -1,111 +0,0 @@
-# Chapter 14: Subsystems — Agent Loop (Goals, Plans, Subagents, Compaction)
-
-## Core Idea
-The agent-loop **spine** lives in core; these are **optional capability seams** the loop never depends on. Delegation (subagent), orchestration (workflow, agent-team), persistent collaboration state (goal, plan, todo), and context management (compaction, spill) each compose in only when a provider/consumer plugin is loaded.
-
-## Frameworks Introduced
-- **Subagent capability seam** (`ctx.subagents` → `SubagentRuntime`): named provider registry; one-shot `SubagentRun` + continuable children. Providers are trusted same-process transports.
-  - When to use: delegate one self-contained task (`start`) or a steerable multi-turn child (`startContinuable`).
-  - How: `start(name, request)` → `SubagentRun` (await `result`, always `dispose`); continuable path uses `startContinuable`/`sendMessage`/`interrupt`.
-- **SubagentCapabilities** (`agentOptions`, `outputSchema`, `depthLimit`, `toolFilter`, `persona`): start-time feature flags.
-  - When to use: request any non-default option; the service rejects unsupported requests loud (`SubagentError('UNSUPPORTED_CAPABILITY')`) — never accepted-then-ignored.
-- **Continuation manager / Activation**: one durable child `Session` ⇒ at most one process-local **Activation** (resident reconstructed `Agent`).
-  - How: `startContinuable` → `{ childId, messageId }`; turns ordered via `Agent.steer()` into the Agent inbox (the only queue).
-- **Workflow seam** (`ctx.workflowEngine` → `WorkflowEngine`, abstract): runs a model-written orchestration **script** that spawns subagents.
-  - How: `start(request)` → `WorkflowRun`; `meta`/`args` are plain JSON DATA validated before any script text runs.
-- **GoalService** (`ctx.goals`): event-sourced same-session goal, backed exclusively by the owning session log.
-  - How: compare-and-set mutations via `GoalRef {id, revision}`; every mutation appends a `goal/change` event.
-- **CompactionEngine** (`ctx.compaction`, abstract): replaces a surface range with one summary node.
-  - How: `compactIfNeeded(agent, trigger, signal)` / `compactNow` / `compactRegion(start, end, agent, signal)`.
-- **SpillStore** (`ctx.spillStore`, abstract): persists oversized tool text, returns a locator + retrieval hint.
-  - How: `saveText(input) → Promise<SpillRef>`.
-- **TeamService** (`ctx.agentTeams`): experimental implicit-root multi-agent topology.
-- **PlanModeController** (`ctx.planMode`): soft plan-mode guidance.
-
-## Key Concepts
-- **Activation**: process-local period a continuable child `Agent` is resident; one per child Session, may run many FIFO turns, stays while descendants run.
-- **Continuable child**: durable child Session with an optional live Activation; no `SubagentRun`, no Task wrapper.
-- **SubagentRun**: holder-owned one-shot handle — `id`, `localAgent?`, `result`, `dispose()`. No steering/resume.
-- **SubagentStopReason**: merge-extensible `completed | aborted | error | max-tokens | refusal`; map non-`completed` to `isError`.
-- **WorkflowMeta**: identity block `{name, description, whenToUse?, phases?}`; matches Claude Code dynamic-workflows meta vocabulary.
-- **WorkflowError.fatal**: hook misuse (`fatal: true`) is re-thrown by `parallel()`/`pipeline()`, never folded to `null`.
-- **GoalPhase**: durable `active | paused | blocked | complete`; **activation** (process-local continuation eligibility) is separate and never persisted.
-- **GoalMessageSource**: `{kind:'goal', goalId, revision, round}` — positive sequential round attribution on admitted `user/message`.
-- **CompactionTrigger**: `'pressure' | 'context-overflow'`; overflow may force a reduction even below threshold.
-- **SpillRef / SpillLocator**: saved artifact (`locator` opaque branded, `bytes`, `retrievalHint`); consumers render hint, never parse locator.
-
-## Mental Models
-- Use **one-shot subagents** when the child is a single foreground delegation you await and dispose; use **continuable children** when the parent must steer/interrupt/resume across turns.
-- Think of **compaction as surface-node shadowing, not deletion**: the append-only log retains everything; `shadowedSeqs` is the authoritative shadowed set, `shadowedRange` a position span (can have `start > end` after prior replaces).
-- Think of **goal phase vs activation** as two questions: "what happened to the objective" (durable) vs "may a continuation consumer start another round" (process-local).
-- Think of **spill** as "save text, return locator" — storage only; no retention, no tool-result replacement, no retrieval API.
-
-## Anti-patterns
-- **Accepting an unsupported subagent capability silently**: requests must reject loud; flags are checked before `start()`.
-- **Reporting partial output as success**: a non-`completed` `stopReason` means `output` may be partial — map to `isError`.
-- **Rejecting `result` on child-level failure**: a model/transport failure resolves with `stopReason:'error'`; only unrepresentable infrastructure faults reject.
-- **Folding workflow hook misuse into `null`**: fatal `WorkflowError` must kill the script; `null` is reserved for child-run failures and ordinary stage errors.
-- **Giving a listener a live `WorkflowRun` or the result value**: events carry DATA SNAPSHOTS (`WorkflowRunInfo`), and `workflow/end` omits `value`.
-- **Coupling a provider's settlement/cleanup to a sibling**: providers isolate operation-local mutable state; a shared capacity controller may delay but never couple.
-
-## Code Examples
-```ts
-// subagent routing by Activation state (SubagentRuntime.sendMessage)
-//   running  → steer nearest step in same Activation
-//   waiting  → wake and steer same Activation
-//   no Activation → cold-resume a new Activation, then steer
-
-// goal lifecycle (ctx.goals)
-get(agent): GoalView | undefined
-create(agent, { objective, maxGoalRounds? }): GoalView
-edit(agent, ref, { objective?, maxGoalRounds? }): GoalView
-pause(agent, ref) | resume(agent, ref) | complete(agent, ref): GoalView
-block(agent, ref, { code, message }): GoalView
-clear(agent, ref): GoalRef          // durable tombstone
-disarm(agent): GoalView | undefined // process-local, no phase change
-
-// plan mode (ctx.planMode)
-get(agent): { active: boolean; pending?: boolean }
-set(agent, active): 'committed' | 'queued' | 'cancelled' | 'noop'
-
-// compaction (ctx.compaction)
-compactIfNeeded(agent, 'pressure'|'context-overflow', signal): Promise<CompactionResult | null>
-compactNow(agent, signal, sourceCommandId?): Promise<CompactionResult | null>
-compactRegion(start, end, agent, signal?): Promise<CompactionResult>
-
-// spill (ctx.spillStore)
-saveText({ owner: {sessionId}, source: {toolName, callId, label},
-           suggestedName, content }): Promise<SpillRef>
-```
-
-## Reference Tables
-
-**Compaction session events (all log-only):**
-| Event | Payload | Role |
-|---|---|---|
-| `compaction/start` | `{ turn }` | lock; number = open auto turn, `null` = standalone manual |
-| `compaction/summary` | `{ summary, rawOutput?, llmStreamCall?, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, maxTokens?, usage? }` | safe projection + reconstructable one-shot call envelope |
-| `compaction/end` | `{ turn, error? }` | releases lock; `error` = unsuccessful attempt |
-
-**`ManualCompactionErrorCode`:** `busy` · `cancelled` · `changed` · `summary` · `commit` · `persistence`.
-
-**Subagent provider registry names:** `spawn`, `fork`, `acp`, `codex`, `claude-code`, `dsh-sdk` (packages `dsh-subagent-<name>-in-process` / `-acp` / `-codex` / `-claude-code` / `-dsh-sdk`).
-
-**Team task DAG statuses:** `pending` (unstarted/released) · `in_progress` (has owner) · `completed` (satisfies blockers) · `deleted` (tombstone); `blockedBy` must be acyclic and name non-deleted tasks.
-
-## Key Takeaways
-1. `subagent`, `workflow`, `compaction`, `spill`, `plan`, `goal` are all optional seams — the loop spine never imports them.
-2. `sendMessage` routes purely by Activation residency; authority comes from the exact live sender (direct parent or direct continuable child only — siblings, ancestors, self, one-shot rejected).
-3. `ctx.tokenMeter` owns compaction estimation/replay; `dsh-compaction-basic` owns thresholds, retention, sequencing, and routed summarization calls.
-4. Compaction's only surface mutation is a `user/message` with `surfaceOp: {op:'replace', start, end}`; region edges must preserve tool-call/result pairing (`toolPairingBalancedBefore/After`).
-5. Goal `resume` re-arms after a session-start edge while round budget remains; `create` may replace only a `complete` goal — otherwise `clear` or `resume` first.
-6. Plan mode is soft guidance — sandbox mode and approval policy enforce independently and never read/write plan state.
-7. Spill `saveText` rejects on real storage failure; the policy consumer degrades best-effort by keeping the inline result.
-
-## Connects To
-- **Ch15 (Tool Execution)**: `ctx.spillStore`/`dsh-spill-policy` are invoked from the `tools/post-execute` policy seam; `todo/write`, `exit_plan_mode` are model-facing tools.
-- **Ch13 (Core Session)**: `Session`, `SessionSeq`, `session/end-seed`, `Agent.steer()`, inbox events, and `surfaceOp` underpin subagent, compaction, goal, and plan state.
-- **Ch17 (LLM Streaming)**: compaction uses `ctx.llm.stream()` (the `llmStreamCall` marker); `ContentBlock` vocabulary is shared.
-- **Ch16 (Session Data)**: `subagent/descriptor`, `goal/change`, `todo/write`, `plan/mode`, `compaction/*` are durable session events recovered on resume/fork/compaction.
-- **Ch06 (Architecture) / Ch07 (Capability Seams)**: every entry here follows the Service Definition / Provider / Consumer split (e.g. `dsh-spill` + `dsh-spill-local` + `dsh-spill-policy`).
-- **Ch09 (API Gateway)**: `ctx.subagents` exposes `@Remote` faces (`remoteExportList`, `prompt`, `interruptByParent`); `ctx.agentTeams` exposes `remoteView`/`remoteCreateTask`/`remoteUpdateTask`.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch15-subsystems-tool-execution.md

@@ -1,106 +0,0 @@
-# Chapter 15: Subsystems — Tool Execution (Shell, Sandbox, FS)
-
-## Core Idea
-`ctx.tools` (`ToolRuntime`) is the single registration/dispatch pipeline every tool call traverses (`tools/pre-execute` → guards → `tools/execute` → `tools/post-execute` → `finalizeContent` → `tools/result`), while each execution capability — shell, filesystem, subprocess, sandbox, LSP, code-runtime — is an optional **capability seam** (Service Definition + Provider + Consumer) whose provider can be swapped without changing tool schemas. Two independent knobs, sandbox mode (`sandbox/mode`) and approval policy (`approval/policy`), are resolved **per call** and fail closed.
-
-## Frameworks Introduced
-- **ToolRuntime dispatch pipeline**: registry + extensible waterfalls over one call.
-  - When to use: register tools, gate calls, wrap dispatch, observe outcomes.
-  - How: `ctx.tools.register(definition)` (global or agent scope); `execute(ToolExecutionInput)` materializes/freezes args, assigns an opaque `ToolExecutionToken`, then runs the waterfalls in fixed order; `schemas(scope)` projects an allowlist (`name`/`description`/`parameters` only) so `output`/`execute`/callbacks never leak into model requests.
-- **Capability seam pattern**: abstract service (`ctx.shell`, `ctx.fs`, `ctx.subprocess`, `ctx.sandbox`, `ctx.lsp`, `ctx.codeRuntime`), one provider per context (a second throws, cordis duplicate-service behavior), and a tool Consumer owning the model-facing schema.
-  - When to use: adding an alternate backend (remote fs, sandboxed bash) or a new tool-backed capability.
-  - How: subclass the abstract seam, load as plugin; the seam — not the loop spine — owns the vocabulary.
-- **`resolve()` request/spec split**: caller-facing request has optional fields; `resolve()` fills implementation defaults/caps into a fully-resolved spec.
-  - When to use: "explicit > implicit at package boundaries" — never hide a `??` default inside the execution method. Used by `ctx.shell.resolve`, mirrored by `SubprocessSpawnSpec` (no defaults at all).
-- **Observation policy (read-before-write)**: `dsh-fs-observation-policy` turns bare `write`/`edit` into guarded mutations via `fs/*` events.
-  - How: tool dispatches `fs/write-intent`/`fs/edit-intent` (single-slot first-wins waterfalls) and emits `fs/observed` (sync, side-effect-only listener); policy keeps `WeakMap<owner(session), Map<targetKey, FsObservation>>`.
-- **Per-call sandbox policy**: `ctx.sandboxPolicy.resolve({session, mode?})` — precedence: approved explicit mode > session's last `sandbox/mode` event > deployment default; workspace root = session's immutable cwd (fs-canonicalized before lexical normalization). `ctx.sandbox.confine(argv, policy)` returns wrapped argv or throws.
-- **Fail-closed approval**: only `allowed-once` grants; everything else denies.
-
-## Key Concepts
-- **ToolDefinition**: `ToolSchema` + mandatory `output` (schema + `render` + optional `presentationMeta`), `execute(args, exec)`, optional `timeoutMs`, `isConcurrencySafe`, `finalizeContent`, `presentCall`/`presentResult`.
-- **PreToolDecision**: `{allow}` / `{deny, reason}` / `{ask, reason?}` — `ask` proceeds only on `allowed-once`; arguments can never be rewritten (history/audit/UI/execution must agree).
-- **ToolGuard**: monotonic post-waterfall check — returns a denial reason or `undefined`; no allow result, so ordering can't undo a denial.
-- **PostToolDecision**: `accept` (replace content XOR value — value is revalidated and recomputes content) or `block` (feedback becomes `isError`).
-- **ToolRestriction**: per-scope `{allow?, deny?}` over inherited global tools; restrictions intersect; own scoped registrations stay exempt (delegated children keep their tools).
-- **ShellExecSpec / ShellRunResult**: resolved spec; orthogonal outcome fields (`timedOut` XOR `aborted`, `exitCode`, `signal`) so a killed run never reads as clean success.
-- **ShellProcess**: background handle — `readOutput()` is incremental/consuming, `done` never rejects, `kill()` idempotent; no id/owner (generic job runtime owns identity).
-- **CollectedOutput**: truncated stream keeps the **tail** in `text` + `spillPath` to the complete stream.
-- **FsTarget / FsVersion**: opaque branded identity and freshness token — consumers must not parse `targetKey` or interpret versions; use `processPath`/`fileUrl`/`contains` for cross-capability coordinates.
-- **ConfinedArgv**: wrapped argv + `enforcement` + `denialSignatures` (this backend's dialect) + `runnerFailureRules`.
-- **ApprovalOutcome**: `'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'` — closed; missing/throwing/non-conforming answerer normalizes to `unavailable`.
-- **CodeBindingNamespace**: one program-visible global of async host functions; args/resolutions must be lossless JSON; names are hostile input (null-prototype, `__proto__` is an own property).
-
-## Mental Models
-- Think of tool dispatch as a **fixed waterfall with monotone permissions**: policy can only shrink access (pre-execute deny/ask → guard deny); post-execute can reshape results but never retro-authorize.
-- Use `ask` when a call is conditionally safe — it is a denial unless an approval service returns `allowed-once`; prefer `deny` for never-safe and `allow` for always-safe.
-- Think of the sandbox as an **argv wrapper, not a jail**: `confine()` swaps the argv and hands back classification dialects; the consumer spawns and attributes outcomes. Network/process visibility are outside the vocabulary.
-- Treat FS authorization as **freshness, not windows**: any windowed read that emits a present `fs/observed` authorizes a later guarded write/edit iff the version is unchanged; there is deliberately no `FS_PARTIAL_OBSERVATION`.
-
-## Anti-patterns
-- **Silent unconfined passthrough**: illegal for a confined policy — no usable backend must surface as `SANDBOX_UNAVAILABLE` (foreground throw) or `runnerFailed` (settled background), never as an unsandboxed run.
-- **Inferring denial from exit status or cross-backend stderr unions**: exit status never proves runner failure; match only the returned backend's own `denialSignatures` (EROFS/bwrap, EACCES/Landlock, EPERM/Seatbelt), and check `runnerFailureRules` (fatal signature + optional exit-code gate, informational lines excluded) first.
-- **Parsing `targetKey`/`FsVersion` or host-path rules on LSP URIs**: both are branded opaque; use `processPath`, `contains`, and `resolvedWorkspaceUri`.
-- **Adding a `timeoutMs` to fs reads**: the seam can't enforce a deadline on an in-progress `fsync`/`rename` — cancellation propagates via the execution signal only (bash/web/glob/grep are process-backed and do carry timeouts).
-- **Treating `isolation` (`'worker-thread'|'process'|'container'`) as a security claim**: it's a diagnostic label; sandboxing is the sandbox seam's job.
-- **Async listener in `fs/observed`**: must be synchronous and side-effect-free — a throw can replace a read error or surface after a successful mutation.
-
-## Code Examples
-```ts
-type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
-type SandboxEnforcement = 'full' | 'partial';
-type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
-type ApprovalPolicy = 'ask' | 'never';   // never: rejected before any answerer runs
-type PreToolDecision =
-  | { kind: 'allow' }
-  | { kind: 'deny'; reason: string }
-  | { kind: 'ask'; reason?: string };
-type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover';
-type CodeRunFailureKind =
-  'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit';
-```
-```ts
-// Escalation path (one-shot, strictly wider):
-const spec = ctx.shell.resolve({ command, workdir, sandboxPolicy:
-  ctx.sandboxPolicy.resolve({ session, mode: 'workspace-write' }) });
-// model-side: sandbox_permissions + justification on a denied call;
-// ctx.approval must grant that exact call before anything executes.
-```
-
-## Reference Tables
-
-| SandboxMode | File effects | Notes |
-|---|---|---|
-| `read-only` | denies writes; POSIX grants `/dev/null` sink | Windows ACL runner: no writable root, reports `partial` |
-| `workspace-write` | workspace root + backend temp area | root = session immutable cwd |
-| `danger-full-access` | bypass | consumer spawns original argv, never calls `ctx.sandbox` |
-
-| FS state → decision | write | edit |
-|---|---|---|
-| unseen | `createIfAbsent` | `FS_NOT_OBSERVED` |
-| absent | `createIfAbsent` | `FS_NOT_FOUND` |
-| present@version | `replaceIfVersion` | version guard (checked **before** literal match) |
-
-| Preset (default table) | sandbox | approval |
-|---|---|---|
-| `workspace-write` | workspace-write | ask |
-| `danger-full-access` | danger-full-access | never |
-| `custom` (derived-only) | — | — reserved key, never a switch target |
-
-Key `FsErrorCode`s: `FS_NOT_OBSERVED` (no prior observation / create hit existing), `FS_STALE_VERSION`, `FS_SANDBOX_DENIED` (policy fence — distinct from kernel `FS_PERMISSION_DENIED`), `FS_TOO_LARGE`, `FS_AMBIGUOUS_EDIT`, `FS_EDIT_NOT_FOUND`, `FS_ABORTED`. LSP codes: `LSP_UNAVAILABLE`, `LSP_CONFLICT`, `LSP_INVALID_PROVIDER`, `LSP_DISPOSED`, `LSP_UNSUPPORTED_OPERATION`, `LSP_MALFORMED_RESPONSE`.
-
-## Key Takeaways
-1. Register via `defineTool` (validates/narrows args, infers return from `output.schema`); raw `ToolDefinition`s validate their own `args: unknown`. Mismatches throw `ToolArgsError` (`INVALID_ARGS`) / `ToolOutputError` (`INVALID_TOOL_OUTPUT`); invisible tools fail as `UNKNOWN_TOOL` without ending the turn.
-2. `ctx.shell.run()` resolves on nonzero exit/timeout/abort (rejects only for infrastructure failures); `start()` returns a handle the tool adapts into `ctx.jobs` — the shell seam itself is task-free.
-3. `DSH_*` env is a managed namespace: executors discard ambient values and merge `ctx.shellEnv`'s snapshot last, so caller `env` entries can never displace managed facts; `stdin`/`env`/`stdoutMaxBytes` are trusted-plugin-only, not model parameters.
-4. `SubprocessHandle.terminate()` (SIGTERM→`graceMs`→SIGKILL, tree-scoped, also fired by the spec's abort signal) is the only termination verb; `waitForExit()` observes the whole tree; `done` carries exit facts only — cause classification (`timedOut`/`aborted`) belongs to the caller.
-5. Approval `request()` requires an open turn and appends the `approval/asked`/`approval/decided` audit pair (log-only, outside the model transcript); abort → `cancelled`, late answers discarded.
-6. Presets own no enforcement: `set()` writes through `setSandboxMode` + `setApprovalPolicy` only when a knob changes, after a log-only `permission/preset` event; requires a confining executor (with `sandboxMode` capability fact) or load fails.
-7. `ctx.codeRuntime.run()` reports errors as result fields, never rejections; programs run as async-function bodies (top-level `await`/`return`); `language` is `'typescript'` (released) / `'python'` (experimental, private).
-
-## Connects To
-- **Ch 07**: capability seams — the Service Definition/Provider/Consumer split formalized here per capability.
-- **Ch 11**: tool catalog — the concrete first-party tools (`bash`, `read`/`write`/`edit`, `lsp`, `run_code`) built on these seams.
-- **Ch 14**: the agent loop drives `executionMode` (parallel/exclusive barriers from `isConcurrencySafe`) and commits `tool/call`/`tool/result` events.
-- **Ch 10**: config keys (`sandbox/mode`, `approval/policy`, preset tables, executor defaults/caps).
-- **Ch 16**: `fs/observed` state and audit/preset events are session-log-owned durable facts.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch16-subsystems-session-data.md

@@ -1,132 +0,0 @@
-# Chapter 16: Subsystems — Session Data (Projection, Storage, Jobs)
-
-## Core Idea
-Every subsystem around the event log — projections, queries, references, titles, telemetry, persistence, domain storage, attachments, workspaces, jobs — layers over one source of truth: the in-memory append-only `Session` log, made durable by `SessionPersistence`. Derive rather than duplicate: fold the log into whole values, and keep non-log state in typed storage domains.
-
-## Frameworks Introduced
-- **ProjectionDefinition** (`ctx.sessionProjections.register`): "the framework drives, the domain computes" — the registry subscribes to `session/event` once and folds every committed event through every registered unit; domains hold no subscriptions, clients never fold.
-  - When to use: any per-session derived state, host-only or client-visible.
-  - How: `{key, stateSchema, init(header, inheritedEventCount), apply(state, event), wire?: {viewSchema, view}, stateVersion}` — all functions synchronous, state plain JSON; the disposer rides the calling fiber (unload ⇒ key reads as capability absence).
-- **SessionQueryEngine** (`ctx.sessionQuery`): live-preferred reads over live + persisted sessions.
-  - When to use: list/filter/search/trace anything beyond the current live session.
-  - How: concrete `listSessions` (newest-first), `readSession`, `readSurface`, `filterSessions`/`filterEvents`, `readEvent`, `traceSession`, `traceEvent`, `readTitle(s)`; a backend implements only the abstract `searchSessions`/`searchEvents`.
-- **SessionReferenceResolver** (`ctx.sessionReferenceResolver`): structured cross-session references (not fork semantics).
-  - When to use: host mention/autocomplete (`@[label](dsh-session:…)`) and cross-session context injection.
-  - How: `listCandidates(agent, query)` (keystroke-rate, self excluded, cwd-affinity ranked); `prepare(agent, content, references)` snapshots the referenced session's current surface into one aggregated untrusted `additionalContext`.
-- **SessionTitleService** (`ctx.sessionTitle`): log-backed latest-wins title fold plus one optional async provider.
-  - When to use: naming sessions or shipping a custom title generator.
-  - How: `get`/`rename`/`refresh`/`register(provider)`; provider `{id, automatic: 'first-prompt'|'all-prompts', generate(request)}`; the service owns acceptance (seq ordering, normalization, byte limit).
-- **SessionTelemetrySink** (`ctx.sessionTelemetry`): canonical-event capture under the boundary axiom — the harness aspect ends at `emit()`; batching, retry, queueing, and loss policy belong to the reporting SDK.
-  - When to use: outbound session reporting (the OTel backend is the shipped provider).
-  - How: implement `emit` (non-blocking enqueue), optional `flush`, `shutdown` (drain to quiescence); redact through the `session-telemetry/record` waterfall.
-- **SessionPersistence** (`ctx.sessionPersistence`): the durability seam — `create`/`open`/`stat`/`list` returning per-session `SessionHandle` (`read`/`append`/`flush`/`close`).
-  - When to use: resume, cold reads, out-of-tree storage backends.
-  - How: `open(id, 'write')` claims single-writer ownership (`SessionAlreadyOwnedError` on contention); `append` is best-effort — only a resolved `flush` (handle or service-wide) promises crash survival and cross-process materialization.
-- **DomainSpec / defineDomain** (`ctx.storageDomain` ≡ `ctx.storage.domain`): typed KV domains routed over registered backends (`json`, `sqlite`).
-  - When to use: plugin-owned persistent data that is not a session event.
-  - How: declare the spec once (zod record schemas, `layout: 'single'|'per-record'`, `compatibleVersions`, `invalidRecords: 'backup-and-skip'`); `open(spec)` validates the medium; reads are synchronous, writes chain durability → memory → `domain/changed`.
-- **AttachmentStore** (`ctx.attachments`) + **FileUploads** (`ctx.fileUploads`): immutable content-addressed binaries under the persist-before-event rule.
-  - When to use: images/files in prompts or model output; browser upload staging.
-  - How: `saveImages`/`admitPromptContent` validate every member before committing any; session events carry refs (`ImageAttachmentRef`/`FileAttachmentRef`), never bytes, object URLs, or paths; `ctx.fileUploads` stages receipts bound to the receiving Agent (`bindPrompt`/`retirePrompt`).
-- **WorkspaceRegistry** (`ctx.workspaceRegistry`): stable uuid identity over canonical (`fs.realpath`) directories plus header-validated session accounts.
-  - When to use: host-side grouping of sessions by working directory (invisible to models).
-  - How: `create(path, title?)` is idempotent per canonical path; membership = account entry ∧ canonical header cwd equals path; `attachSession` prepends, activity never reorders.
-- **JobRegistry** (`ctx.jobs`): background job identity, authorization, and settlement.
-  - When to use: long-running producers (shipped kinds `bash`, `subagent`; extend `JobKindMap` by declaration merging).
-  - How: `start({kind, label, owner?, run(): JobHooks})` after preflight; hooks `{cancel, done, readOutput?}`; `kill` requests cancellation and marks `stopping`/`reported`.
-
-## Key Concepts
-- **Whole-value event rule**: state-carrying log events carry the complete post-change state, never a delta — transitions stay trivially cheap, served values self-describing.
-- **`Object.is` discipline**: `apply` returns the same state reference when uninterested (zero downstream work); an object-valued `view` reuses its reference to suppress publication.
-- **`asOfSeq`**: snapshot watermark — seq of the last event every value reflects (`-1` for an empty log); `snapshot()` is fully synchronous, so one cut covers values and cursor in one tick.
-- **Live-preferred corpus**: query prefers live `ctx.sessions`, falls back to persisted logs; `SessionRecord {header, live, persisted}` separates source availability from the cloned header.
-- **`inheritedEventCount`**: exact fork-inherited prefix length stored beside the header; seeds projection `init` and completes cache-row identity.
-- **Projection cache rows**: `(sessionId, key, ver, seq, val)` in the `session_projcache` domain; a `stateVersion` mismatch discards old rows rather than forward-folding them into garbage.
-- **Revision token**: opaque change token from `stat`/`list`; equal ⇒ may treat the log as unchanged, unequal promises nothing; keys cold-read caches and plays no part in open/read/resume.
-- **`domain/changed`**: fires strictly after backend durability in write-chain order; `put` carries only the new value (never the old); a throwing listener is contained — the write is already durable.
-- **`reported` flag**: suppresses redundant job-completion notices once any reporter commits; teardown claims it so owner disposal spends no model request.
-- **Telemetry dedupe**: ledger records mirror events one-to-one — receivers dedupe on `(session.id, session.format_version, event.seq)`; ops records (`agent-error`, `shutdown`) deliberately carry no identity.
-
-## Mental Models
-- Think of projections as a fold server: domains register pure units, carriers receive finished whole values — never fold `session/event` client-side.
-- Think of a storage domain as a synchronous cache over a serial write chain: a rejected backend write leaves memory untouched, so reads never diverge from the medium.
-- Think of jobs as split ownership: runtime owns identity/access/lifecycle, producer owns execution resources; `done` resolves after resources are released, not when work finishes.
-- Treat `SessionHeader` as metadata-beside-the-log (`cwd`, `parentSession`, `isSeeded`, `origin`, `delegationDepth`, `agentPreset`) — it never enters `SessionEventMap` or `deriveMessages()`.
-
-## Anti-patterns
-- **Async projection unit / non-JSON state**: tears the carriers' consistency cut and breaks the persisted-cache precondition.
-- **Mutating returned references**: `stateOf` values and domain table records are live or shared — replace via `put`/`update`, never mutate in place.
-- **Parsing `AttachmentId` as a path**: it is opaque (`sha256:<digest>` today); ask `imageHostPath()`/`fileHostPath()` and let the execution world judge readability.
-- **Blocking `emit()`**: it runs synchronously on the `session/event` hot path — anything slower than a queue push taxes the agent loop.
-- **Expecting persistence to repair crashed turns**: it returns the valid contiguous log and truncates only the torn physical tail; appending `interruptedTurnClosers` is the resuming reader's job, under write ownership.
-- **Relying on job-id secrecy**: ids are predictable (`<kind>-N`); the boundary is owner-session authorization.
-
-## Code Examples
-```ts
-ctx.sessionProjections.register({
-  key, stateSchema, stateVersion: 1,
-  init: (header, inheritedEventCount) => empty,
-  apply: (s, e) => e.type === 'my/state' ? e.data.state : s, // same ref ⇒ no work
-  wire: { viewSchema, view: s => clientShape(s) },
-}); // disposer rides the calling fiber
-
-const spec = defineDomain({
-  name: 'my-plugin', version: 2, layout: 'per-record',
-  compatibleVersions: [1], invalidRecords: 'backup-and-skip',
-  tables: { items: domainTable<ItemId, Item>(ItemSchema) },
-});
-const domain = await ctx.storageDomain.open(spec);
-
-const id = ctx.jobs.start({
-  kind: 'bash', label: command, owner: agent,
-  run: () => ({ cancel: reason => proc.kill(), done, readOutput: () => drain() }),
-});
-```
-
-## Reference Tables
-
-| Projection read ladder | I/O | freshness |
-|---|---|---|
-| `sessionProjectionCache.cachedSnapshot(meta, inheritedEventCount)` / registry `viewCheckpoint(rows)` | zero | as stale as the last checkpoint, never wrong |
-| `sessionProjectionCache.hydratePrepared(session, events)` | no extra read | observation cut |
-| `sessionProjectionCache.coldSnapshot(meta, inheritedEventCount, events)` / registry `restore(rows, events, baseSeq)` | log suffix from `restoreFloor`, seeded by usable rows | log end |
-
-| Storage `open(spec)` failure ladder | code |
-|---|---|
-| name already open/closing | `already-open` |
-| route unresolved | `backend-not-found` |
-| backend lacks `kv` facet | `facet-unsupported` |
-| unit stamp/parse | `version-mismatch` / `malformed-medium` |
-| record schema | `invalid-record` (or backup-and-skip) |
-
-| Jobs semantics | rule |
-|---|---|
-| `start` | preflight (access, cleanup, admission) → sync `run()`; after it returns, registration cannot fail |
-| `kill` | returns `'requested' \| 'already-finished'`; marks `stopping` + `reported` |
-| `wait(id, timeoutMs)` | bounded, never cancels; post-settlement the terminal snapshot wins |
-| settlement | first-wins; completion announced last (a reporter may open a model turn) |
-| admission | `maxConcurrentJobsPerOwner` default 10, counting `running`+`stopping` per exact owner |
-
-| Attachment admission (local backend) | limit |
-|---|---|
-| images / encoded bytes per message | 20 / 200 MiB |
-| per source | 20 MiB, 64,000,000 px, ≤8192 px per side |
-| normalization defaults | long edge 2048 px, 4 MiB encoded |
-
-## Key Takeaways
-1. Register a projection unit instead of subscribing to `session/event`: the framework drives every unit once per committed event, lazily backfolds late registrations over the in-memory log, and checkpoints through `session_projcache` (mandatory points: session creation, `turn/end`, disposal; otherwise throttled write-behind).
-2. Gate crash survival on `flush`, not `append` — a session that never materialized before a crash never existed. Repair of an interrupted turn (missing tool errors, open `step/end`, synthetic `turn/end {reason: 'interrupted'}`) is written by resume under write ownership; `interrupted` is the one `TurnEndReason` no loop emits.
-3. Fork/replay is `ctx.agents.create({sessionId, seed, meta})` with `inheritedEventCount` and `meta.isSeeded: true`; resuming a persisted session is `ctx.agents.resume({resumeSessionId})`.
-4. Prefer `per-record` layout + `compatibleVersions` + `invalidRecords: 'backup-and-skip'` for disposable derived data (the projection-cache pattern); keep the rejecting `single` default for authoritative data.
-5. Consume sessions through `ctx.sessionQuery` concrete reads; full-text queries are data, never executable FTS syntax, and within-session pages carry the target header even with zero hits.
-6. Workspace membership needs both the account entry and canonical header-cwd equality — one session belongs to at most one workspace; registry `delete` retains sessions (they become Ungrouped). A `user`-source title rename pins the title; `refresh` is the deliberate unpin.
-7. Redaction lives in the `session-telemetry/record` waterfall (fail-closed, exported copy only — the canonical log is never rewritten); the seam ships no rules, so exported data is exactly as clean as what the deployment mounts.
-
-## Connects To
-- **Ch 13**: the `Session`/`SessionEvent`/`SessionHeader` vocabulary every fold and read here consumes.
-- **Ch 12**: persistence-catalog enumerates the exact log events mirrored by ledger telemetry and query folds.
-- **Ch 14**: agent-loop owns resume repair and the `turn/end`/`session/flush` checkpoints that drain persistence write-behind.
-- **Ch 15**: tool-execution backgrounds `bash`/`subagent` work through `ctx.jobs` kinds.
-- **Ch 09**: gateway controllers (session, workspace, file-upload, directory-picker) are the Remote consumers of these registries.
-- **Ch 07**: each subsystem here is an optional capability seam, deliberately off the agent-loop spine.
-- **Ch 05**: registration-as-effect, merge-extensible maps (`JobKindMap`, `StorageForms`), and waterfall semantics are Cordis mechanics.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch17-subsystems-llm-streaming.md

@@ -1,128 +0,0 @@
-# Chapter 17: Subsystems — LLM Streaming, Tokens & Credentials
-
-## Core Idea
-dsh's LLM spine is provider-neutral at the wire: adapters emit a closed `StreamChunk` protocol, one shared `BlockAssembler` folds it back into `ContentBlock`s, and four edges handle the rest — credentials (secrets stay out of config), token metering (request-pressure pricing), typert (Remote-call typing), and client-modules (browser bundle loading).
-
-## Frameworks Introduced
-- **`StreamChunk`**: closed discriminated union (7 variants) — raw adapter protocol; `switch` over `type` ends in `assertNever`, so a new variant breaks every consumer that must handle it.
-  - When to use: every adapter `stream()` return; every consumer fold.
-  - How: emit `usage` before `finish`, nothing after; `index` ties deltas to a block, `block-end` carries the assembled `ContentBlock`.
-- **`LlmAdapter`** (abstract class): the provider contract — subclass, implement `stream()`, register with `ctx.llm.registerAdapter(providers, adapter)`.
-  - When to use: adding a model provider.
-  - How: `GenerateOptions.provider` selects the adapter; `model` need not be registered at lifecycle start; duplicate routes fail atomically.
-- **`BlockAssembler`**: single shared fold from `StreamChunk` stream → `ContentBlock[]` + usage + finish + replay.
-  - When to use: any consumer needing the assembled result without re-implementing the fold.
-  - How: `push()` each chunk, then read `blocks()` / `message()` / `usage` / `finish`; `interruptedBlocks()` on cancellation.
-- **`CredentialProvider`** (abstract seam): two disjoint key spaces answer two questions.
-  - When to use: reading/writing secrets for plugins.
-  - How: `CredentialRef` (env-var name) resolves per operation; `CredentialKey` (plugin id) uses read-modify-write only.
-- **`TokenMeter`**: replay owner for request-pressure + surface pricing; `measure(session, requestHeader?)` / `estimateMessage(message)`.
-- **Typert**: generated Remote-call typing via `InvocationDescriptor` + `TypertCodec` (`strict` schema | `src-json`).
-- **`ClientModuleRegistry`**: Node half of `dsh.client` scan → `WebBootGraph` → `/plugins` combo route + index-injection rows.
-
-## Key Concepts
-- **`ContentBlockMap`** — merge-extensible union: `text`, `reasoning`, `image`, `file`, `tool-call`, `tool-result`; a new modality lands only when adapter, UI, compaction, and replay all honor it.
-- **`Message`** — immutable `{ id, role: 'system'|'user'|'assistant', content: ContentBlock[], source }` shared by delivery, durable history, and model requests.
-- **`MessageSourceMap`** — merge-extensible provenance sum: `user`, `plugin` (with `plugin` + `ContextFormed`), `model`, `tool`.
-- **`ContextForm`** — semantic producer-declared info kind: `instructions` | `catalog` | `snapshot` (has `sections`) | `notice` (has `summary`) | `relay` | `recall`; never visual (colors/icons/ordering are the consumer's).
-- **`TokenUsage`** — disjoint counts: `inputTokens` (uncached only) + `cacheReadTokens?` + `cacheWriteTokens?` = billed input; `outputTokens`; `reasoningTokens?` already inside `outputTokens`; `totalTokens?` exact or omitted.
-- **`LlmFailure`** — serializable provider-neutral failure: `message`, `code`, `status?`, `providerRetryAfterMs?` (validated delay, not a retry decision), `requestId?: ProviderRequestId`.
-- **`FinishReasonMap`** — `stop`, `tool-calls`, `max-tokens`, `aborted {failure}`, `error {failure}`.
-- **`ReplayEnvelope`** — `{ response: unknown, blocks?: readonly unknown[] }`; adapter-owned halves, shared split so assembly prunes per-block entries in step with dropped blocks.
-- **`ResolvedRetryPolicy`** — immutable discriminated union: `normal` (`maxRetries`, `retryableCodes`, `initialDelayMs`, `maxDelayMs`, `jitterRatio`) or `always` (same backoff, no cap); normal default = 5 retries.
-- **`CredentialRef`** — `Branded<'CredentialRef'>`; a POSIX-style env-var name (shell-identifier syntax validated).
-- **`WebBootGraph`** — `{ rev, entries, batches }` injected as `window.__DSH_BOOT__`; single wire source between Node and browser halves.
-
-## Mental Models
-- **Use one adapter call = one provider attempt**: adapters disable library retries; agent-level recovery opens another numbered turn.
-- **Think of credential resolution as a per-operation read**: `resolve(ref)` re-reads every call; that (not the `reference-updated` event) is the hot-update path — a rotated credential reaches the next request with no restart.
-- **Think of the model catalog as advisory, never a whitelist**: routing keys on the registered provider; adapters may accept unlisted ids.
-- **Think of `usage before finish` as the ordering invariant**: defer both to the provider's end-of-stream marker so a trailing usage-only chunk can't violate it.
-
-## Anti-patterns
-- **Caching a credential across operations**: breaks hot-update; re-resolve per operation.
-- **Folding cache hits into `inputTokens`**: counts are disjoint; DeepSeek adapters subtract `prompt_tokens` cache fold back out.
-- **Treating catalog absence as request rejection**: `listModels` is advisory; consumers must not turn absence into a 404.
-- **Re-stringifying parsed tool args mid-stream**: keep `arguments` raw JSON end-to-end; partials via `argumentsDelta`.
-- **Hand-copying the version into `AppIdentity`**: source it from package metadata; all fields are public product facts (no secrets, paths, session ids).
-
-## Code Examples
-
-```ts
-type StreamChunk =
-  | { type: 'block-start'; index: number; blockType: ContentBlockType }
-  | { type: 'text-delta'; index: number; text: string }
-  | { type: 'reasoning-delta'; index: number; text: string }
-  | { type: 'tool-call-delta'; index: number; id: ToolCallId; name?: string; argumentsDelta: string }
-  | { type: 'block-end'; index: number; block: ContentBlock }
-  | { type: 'usage'; usage: TokenUsage }
-  | { type: 'finish'; reason: FinishReason; replayState?: ReplayEnvelope }
-```
-
-```ts
-abstract class LlmAdapter {
-  providerInfo(provider: string): LlmProviderInfo
-  providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined
-  imageRequestPricing(_provider: string, _model: string): LlmImageRequestPricing | undefined
-  listModels(_provider: string): Promise<readonly LlmModelInfo[]>
-  resolveModel(provider, model, _signal?): Promise<LlmResolvedModelInfo>
-  async prepareCall(provider, model, signal?): Promise<PreparedAdapterCall>
-  abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>
-}
-```
-
-```ts
-ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle
-ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>  // wrapped by 'llm/stream' waterfall
-ctx.credentials.resolve(ref): Promise<ResolvedCredential | undefined>
-ctx.credentials.modifyRecord(key, mutate): Promise<CredentialRecord | undefined>
-ctx.tokenMeter.measure(session, requestHeader?): TokenMeasurement
-ctx.clientModules.rebuilt(id): string | undefined   // ONLY entry point for bundle content changes
-```
-
-`/plugins/??<a>/client.js,<b>/client.js&rev=<rev>` — one-or-more-resource combo; `sourceMappingURL` mirrors as `.client.js.map` (Indexed Source Map v3); unknown/altered/stale lists → 404, other methods → 405.
-
-## Reference Tables
-
-| StreamChunk | payload |
-|---|---|
-| `block-start` | `index`, `blockType` |
-| `text-delta` / `reasoning-delta` | `index`, `text` |
-| `tool-call-delta` | `index`, `id`, `name?`, `argumentsDelta` |
-| `block-end` | `index`, `block: ContentBlock` |
-| `usage` | `usage: TokenUsage` |
-| `finish` | `reason: FinishReason`, `replayState?` |
-
-| LlmRuntime event | mode | purpose |
-|---|---|---|
-| `llm/stream` | waterfall | around every model call (retry/replay/routing); `next()` reaches adapter |
-| `llm/adapters-updated` | emit | registry topology changed; re-read `listProviders()` etc. |
-| `credentials/reference-updated(ref)` | emit | set/unset/external edit; ambient env changes never emit |
-| `credentials/record-updated(key)` | emit | `modifyRecord`/`deleteRecord`/external edit |
-| `authorization/settled(key, settlement)` | emit | every terminal attempt outcome, failures included |
-
-| Error code | meaning |
-|---|---|
-| `DUPLICATE_ADAPTER` | provider already has an adapter (all-or-nothing) |
-| `REGISTRATION_DISPOSED` | `replace()` after release |
-| `CONTEXT_WINDOW_EXCEEDED` | canonical overflow code; route on code, not provider text |
-| `EMPTY_RESPONSE` | terminal `stop` with zero content blocks — retryable |
-| `gateway/*` (e.g. `lookup-not-found`, `service-unavailable`) | `TypertGatewayErrorCode` — ordinary `RemoteError` codes |
-
-## Key Takeaways
-1. The `StreamChunk` closed union + `BlockAssembler` split means an adapter only emits well-formed chunks — block reassembly is never each adapter's problem.
-2. Tool-call `arguments` stay raw JSON strings end-to-end; `block-end` re-stringifies if the provider parsed them.
-3. Two sanctioned failure paths, one `LlmFailure` type: THROW from `stream()` (transport) or end with `finish {kind:'error'|'aborted'}` (in-band).
-4. Secrets live in `CredentialProvider`, not config — settings carry `CredentialRef` names only; resolve per operation.
-5. `TokenMeasurement` reprices images through `ctx.llm.imageRequestPricing` per route; `baseline.kind` is `usage` (reusable anchor) or `estimated`.
-6. A browser page with no valid `dsh.client` manifest cannot boot; `rebuilt(id)` is the sole path by which bundle content reaches the graph.
-
-## Connects To
-- **Ch04 cordis-fundamentals / Ch05 cordis-api**: all services here (`ctx.llm`, `ctx.credentials`, `ctx.tokenMeter`, `ctx.typert`, `ctx.clientModules`) are Cordis services; `llm/stream` is a waterfall, others emit.
-- **Ch06 architecture**: `ctx.llm.stream()` and the `llm/stream` waterfall sit in the turn flow.
-- **Ch14 subsystems-agent-loop**: the loop builds `GenerateOptions` from logged `EpochHeader`, logs raw chunks, and commits `assistant/attempt` on failure.
-- **Ch15 subsystems-tool-execution**: `ToolSchema` is the wire type; `ToolDefinition` (schema + `execute`) lives in dsh-tools.
-- **Ch16 subsystems-session-data**: the Session log embeds `AssistantStreamRecord[]` under `assistant/message` / `assistant/attempt`; `EpochHeader` is the token meter's request envelope.
-- **Ch18 subsystems-web-ui**: `ctx.clientModules` feeds the web stack's `webserver/index-inject`; `ctx.credentialsController` backs `ctx.remote.credentials`.
-- **Ch09 api-gateway**: typert's `TypertGateway` and `gateway/*` codes are the Remote-call dispatch seam.
-- **Ch10 config-catalog**: `LlmCallConfig` input fields and credential references surface in settings schemas.