better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch07-capability-seams.md

@@ -0,0 +1,97 @@
+# Chapter 7: Capability Seams
+
+## Core Idea
+A seam is a swappable capability with three roles — a **Service Definition** declaring the interface, a **Service Provider** implementing it, and a **Consumer** using it (commonly a model-facing tool); one role alone is not a seam, and adding a capability means designing all three. Because filesystem and subprocess providers share one execution world, one provider swap — e.g. to a remote sandbox — moves Bash, PTY, and LSP with it, with no provider forks.
+
+## Frameworks Introduced
+- **Three-role seam (Definition / Provider / Consumer)**: the unit of extensibility.
+  - When to use: any capability that should be swappable — LLM, fs, shell, sandbox, storage, subagents, web, skills.
+  - How: declare the interface as a Cordis service; providers register implementations into it; keep consumers provider-neutral.
+- **Service classification (`core` / `seam` / `bundle`)**: every `ctx` service carries a Role in the capability graph — `core` = spine with one owner (project onto it, don't replace it), `seam` = swappable with named implementations, `bundle` = composition point (only `ctx.agentLoop`).
+- **Execution world**: `ctx.fs` + `ctx.subprocess` + `ctx.sandbox` (+ `ctx.e2b`, one shared E2B SDK handle so both E2B providers inhabit the same Linux runtime) move together; swap the set, not one package.
+- **Companion plugin / event gate**: policy contributed via events instead of a provider — `fs-observation-policy` adds observed-state checks through the `fs/*` gate without replacing `ctx.fs`; `spill-policy` decides spilling at `tools/post-execute` while `ctx.spillStore` just saves.
+
+## Key Concepts
+- **Sole-provider seam**: exactly one optional async provider allowed (`ctx.sessionTitle`: first-prompt-llm or all-prompts-llm), with the deterministic fallback owned by the seam itself.
+- **Named side-by-side providers**: backends register under names in one registry (`ctx.storage` json/sqlite; `ctx.llm`; `ctx.web`).
+- **Single-engine service**: no provider registry at all — `ctx.workflowEngine` is one engine per context.
+- **Provider-neutral tool**: model-facing tools consume the seam, never an implementation (`tool-web` owns the stable model-facing names over `ctx.web` providers; `tool-bash`/`tool-pwsh` over `ctx.shell`).
+- **Remote controller**: API controllers (`ctx.sessionController`, `ctx.settingsController`, `ctx.workspaceController`, `ctx.credentialsController`, `ctx.directoryPickerController`) project seams onto the generated Remote namespace — redaction and refusal classification live in the controller, not the seam Definition.
+- **Fails-closed approval**: `ctx.approval` dispatches one-shot decisions over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents); absence fails closed to `unavailable`.
+- **Per-operation credential resolution**: config carries references, providers own values (`ctx.credentials`); a rotated credential reaches the very next request; views are value-free, storage write-only.
+- **`ctx.invariants`**: companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, package-attributed failures.
+
+## Mental Models
+- Use a seam when two or more implementations are plausible (local vs sandbox vs remote); use `core` when the service is a spine others project onto.
+- Think of providers as replaceable behind one interface, with tools as the stable model-facing names layered on top.
+- Think of controllers as projection layers: the seam stays wire-free; redaction/refusal mapping never leaks into the Definition.
+
+## Anti-patterns
+- **Depending on `ctx.agentLoop`**: it is the one `bundle`-role concrete loop plugin; extension packages depend on `dsh-agent` events and services, not this package.
+- **Expecting a provider registry where there is none**: `ctx.workflowEngine` is a single engine — don't design "workflow providers".
+- **Adding a protocol escape hatch**: `ctx.lsp` exposes exactly four normalized operations; a backend translates into the normalized request/result, no raw-protocol bypass.
+- **Shipping a provider without Definition and Consumer**: one role alone is not a seam.
+- **Assuming approval defaults open**: no answerer = `unavailable` (fail closed), never auto-allow.
+- **Reading sandbox mode ad hoc**: `ctx.sandboxPolicy` is the one home for deployment default mode + workspace root, read by both bash and fs enforcing families precisely so they cannot confine to different roots.
+
+## Code Examples
+Consumer → seam → provider wiring (from the capability graph):
+```text
+ctx.llm:        [llm-deepseek, llm-pi-ai, llm-replay] → seam → [agent-loop, compaction-basic]
+ctx.subprocess: [subprocess-local, subprocess-e2b] → seam → [bash-local, bash-sandbox, terminal-bash, lsp-stdio, subagent-acp/codex/claude-code]
+ctx.fs:         [fs-local, fs-sandbox, fs-e2b] → seam → [tool-fs]  (+ fs-observation-policy via fs/* event gate)
+ctx.shell:      [bash-local, bash-sandbox, pwsh-local] → seam → [tool-bash, tool-pwsh, hooks-claude-code, hooks-codex]
+```
+
+## Reference Tables
+Seam-selection decision table:
+| Want to… | Seam | Implementations | Rule / limit |
+|---|---|---|---|
+| Swap LLM provider | `ctx.llm` | llm-deepseek, llm-pi-ai, llm-replay | loop + compaction call the provider-neutral stream service |
+| Extend official DeepSeek requests | `ctx.deepseekLlmApiExtensions` | session-log-deepseek, plugin-package-inventory-deepseek | plugins prepare independent top-level fields; official adapter merges and commits delivery state after HTTP acceptance |
+| Replace bash executor | `ctx.shell` | bash-local, bash-sandbox, pwsh-local | tools + hook bridges untouched by the swap |
+| Relocate process spawning | `ctx.subprocess` | subprocess-local, subprocess-e2b | service owns process coordinates, tree/session lifetime, stdio, kill escalation |
+| Swap filesystem | `ctx.fs` | fs-local, fs-sandbox, fs-e2b | fs-sandbox fences by shared sandbox mode; observation via `fs/*` gate |
+| Confine spawns | `ctx.sandbox` | sandbox-local | consumers hand over the exact argv; backends wrap per-call and report enforcement |
+| Gate permissions | `ctx.approval` | listeners (ACP bridge) | `approval/request` waterfall; fails closed to `unavailable`; `ctx.permissionPresets` bundles sandbox-mode + approval-policy knobs |
+| Persist sessions | `ctx.sessionPersistence` | session-persistence-jsonl | one artifact per Session |
+| Search sessions | `ctx.sessionQuery` | session-query-sqlite | interface = exact reads/filters/traces; backend adds full-text, ranking, snippets |
+| Store typed state | `ctx.storage` → `ctx.storageDomain` | storage-json, storage-sqlite | backends side by side under names; domain form waits for every configured backend |
+| Read/write settings | `ctx.settings` | settings-file | plugins register namespace schemas, resolve layered values; provider stores the raw document |
+| Resolve secrets | `ctx.credentials` | credentials-local | references in config; resolve per operation |
+| Delegate work | `ctx.subagents` | spawn/fork-in-process, acp, codex, claude-code, dsh-sdk | service owns continuation orchestration; tool-subagent picks one-shot vs continuable; tool-ralph requires one fresh structured-output route |
+| Run background work | `ctx.jobs` | jobs-local | producers register; tool-jobs is the model-facing controller |
+| Search/fetch the web | `ctx.web` | web-search-exa/perplexity/deepseek, web-fetch-http | tool-web owns model-facing names |
+| Run model-written code | `ctx.codeRuntime` | code-runtime-worker-thread, experimental-code-runtime-python | consumed by `ctx.tools` for PTC mode |
+| Compact context | `ctx.compaction` | compaction-basic | consumes post-step pressure + request-error recovery; no model-facing compact tool |
+| Spill oversized output | `ctx.spillStore` | spill-local | returns model-facing locator + retrieval hint; spill-policy decides when |
+| Language servers | `ctx.lsp` | lsp-stdio | exactly four operations, no escape hatch |
+| Run workflows | `ctx.workflowEngine` | workflow-worker-thread | one engine per context; `agent()` fans out through `ctx.subagents` |
+| Name sessions | `ctx.sessionTitle` | first-prompt-llm / all-prompts-llm | sole optional async provider; deterministic fallback + latest-title fold owned by seam |
+| Ask a human | `ctx.userQuestions` | UI front ends | tool-ask-user pauses on the provider-neutral `ask()` promise |
+| Pick directories | `ctx.directoryPicker` | native, browse | dual-face backends fill ui-workspace directory-flow slots from browser halves |
+| Emit telemetry | `ctx.sessionTelemetry` | session-telemetry-otel | nothing else consumes it — output leaves the process |
+| Authorize / telemetry / attachments | `ctx.authorization` / `ctx.sessionTelemetry` / `ctx.attachments` | — / otel / attachment-local | authorization owns the conversation + one-attempt-per-key lifecycle, never the protocol; telemetry output leaves the process; host commits images before session events |
+
+Core spine services (one owner, not swappable): `ctx.sessions`, `ctx.systemPrompt`, `ctx.tools`, `ctx.agents`, `ctx.agentDefaultModel`, `ctx.sessionProjections`(+`Cache`), `ctx.planMode`, `ctx.agentPresets`, `ctx.goals`, `ctx.messageFeedback`, `ctx.workspaceRegistry`, `ctx.webServer`, `ctx.clientModules`, `ctx.webhookRuntime`, `ctx.typert`(+`Gateway`), `ctx.invariants`, `ctx.inspector`, `ctx.dynamicCordisRunner`/`cordisInspect`, `ctx.e2b`, `ctx.shellEnv`, `ctx.agentTeams` (experimental), API controllers.
+
+Exclusivity & collision rules: sole-provider seams take one registration (`sessionTitle`); registries take named side-by-side providers (`storage`, `llm`, `web`, `skills`); single-engine services take none (`workflowEngine`); approval answerers are event listeners, not registrations.
+
+Maintenance: the capability graph is `hybrid generated` — services are discovered from Cordis declarations; Definition/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard.
+
+## Key Takeaways
+1. Design Definition + Provider + Consumer together; a provider alone is not a seam.
+2. Swap at the seam, not at the tool: tools own stable model-facing names over swappable providers.
+3. Check the Role column first — `core` services are spines to consume/project onto, `bundle` (`ctx.agentLoop`) is depended on by nobody.
+4. Prefer event-gate companions (`fs/*`, `tools/post-execute`) for policy that should not fork providers.
+5. Keep seams wire-free: redaction, refusal mapping, and capability gating live in the Remote controllers.
+6. Execution-world seams move together; read confinement config only from `ctx.sandboxPolicy`.
+
+## Connects To
+- **Ch 6**: architecture and lifecycle these seams hang off; the three-role definition.
+- **Ch 8**: pipelines that fire the `tools/*` events companions listen to.
+- **Ch 11**: tool catalog — the Consumer role made concrete.
+- **Ch 12**: persistence seams (`sessionPersistence`, `storage`, `spill`) in depth.
+- **Ch 13–17**: subsystem deep-dives per seam domain (session, agent loop, tool execution, session data, LLM streaming).
+- **Ch 3**: how plugin code actually registers providers and companions.
+- **Ch 19**: cookbook recipes mapped onto these seams.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch08-internals-pipelines.md

@@ -0,0 +1,111 @@
+# Chapter 8: Internals — Module Graph & Core Pipelines
+
+## Core Idea
+dsh's packages form a peer-dependency graph of *shared service instances*, wired at runtime by typed events and by a fixed three-waterfall tool-execution pipeline; two generated matrices (module graph, event producer–consumer matrix) tell you who owns an instance, who dispatches an event, and where policy inserts into a tool call.
+
+## Frameworks Introduced
+- **Shared-instance dependency graph** (`pnpm run gen-module-graph`): peer deps among `@deepseek-ai/dsh-*` packages; edge `a --> b` = `a` requires `b` as a host-provided shared instance. Runtime deps and dev-only relations deliberately absent.
+  - When to use: deciding which services a new package/plugin may consume, or which peers it must declare.
+  - How: Mermaid chart grouped by `packages/<group>/<pkg>` (50 groups, ~790 edges, names omit `@deepseek-ai/dsh-`) or the table `Package | Group | Peer dependencies`.
+- **Event Producer–Consumer Matrix** (`pnpm run gen-doc-graphs`): every harness-owned event as `Event | Mode | Declared in | Dispatchers | Listeners`; types also cover contained dispatch sites that deliberately bypass `ctx.emit` (subagent lifecycle containment).
+  - When to use: choosing a hook point, or auditing blast radius before changing an event payload.
+  - How: Mode = contract, Dispatchers = owner, Listeners = insertion precedent; empty Listeners = open extension point.
+- **Tool Execution Pipeline**: fixed stage order from model `tool_call` to model-facing `tool/result` hosting policy, hooks, sandboxing, rewriting, observation, UI "without changing the loop".
+  - When to use: adding approval, guards, timeout/retry, result post-processing, or tool UI.
+  - How: listen on the right waterfall (`tools/pre-execute` → guards → `tools/execute` → `tools/post-execute`); all three may transform a call.
+
+## Key Concepts
+- **Peer dependency**: a requirement for the host's shared instance; bundling your own copy breaks service identity.
+- **Event mode**: `emit` (broadcast), `waterfall` (value-transform chain), `serial` (ordered await), `parallel` (fan-out await).
+- **Monotonic guard**: registered deny-or-abstain check with protected identity, running after `tools/pre-execute` allow and before `tools/execute`; owner policy that must not be reordered lives here.
+- **`ctx.approval`**: one-shot user prompt resolving `ask` verdicts *before* monotonic guards; absent or unanswerable approver = deny.
+- **`ToolDefinition.finalizeContent`**: definition-owned last content-only invariant, synchronous, applied to a snapshotted result.
+- **Registry outer normalization**: the registry losslessly snapshots the candidate result; snapshot throws become `isError` so failures never escape the pipeline.
+- **`additionalContexts` FIFO**: active-batch extra contexts injected as user/message *after* recorded tool results.
+- **PTC sub-calls**: serialized sub-calls of the reserved `run_code` transport; carry the parent token, log `tool/code-dispatch`, return denials as binding rejections, omit `additionalContexts` to preserve call/result adjacency.
+- **`internal/*` events**: undeclared strings (`internal/dispatch`, `internal/plugin`, `internal/service`, `internal/status`) consumed by core machinery (loader, gateway, inspector) — not a public surface.
+
+## Mental Models
+- Think of the module graph as a *sharing contract*, not an import graph: edges mark services you receive, never services you bundle.
+- Use the event matrix as a *bus map*: the dispatcher owns the stop; listeners are the passengers you ride with.
+- Think of tool execution as *fixed track, movable signals*: stage order never changes; you add behavior by listening at a waterfall.
+
+## Anti-patterns
+- **Bundling a peer**: a second instance breaks shared identity; consume the host's copy.
+- **Putting reorder-sensitive owner policy in `tools/pre-execute`**: it can be bypassed/reshaped by other listeners; register it as a monotonic guard instead.
+- **Doing read-before-edit fs checks above `tool-fs`**: they stay below `tool-fs` on `fs/*` events.
+- **Reading `agent/status`/`whenIdle()` as "my follow-up finished"**: several queued follow-ups share one `running` interval; an owner must define its interval explicitly (durable inbox receipt → next whole-agent `idle`) and handle the "nothing to wait for" branch or hang.
+
+## Code Examples
+```ts
+// fs gates (dispatched by tool-fs / tool-str-replace-editor)
+ctx.waterfall('fs/write-intent', intent)    // → fs-observation-policy
+ctx.emit('fs/observed', obs)                // → fs-observation-policy, skill-filesystem
+
+// Both-sides contract: LlmAdapter vs LlmRuntime
+adapter.stream():  may throw OR emit finish { kind: 'error' | 'aborted' }
+runtime.stream():  model-request failures ONLY as terminal finish chunks
+
+// Dispose to quiescence
+registry.close(); proc.kill(); await done   // close listeners BEFORE killing
+
+// Unlink link-shaped paths
+if (lstatSync(p).isSymbolicLink()) unlinkSync(p)  // rmSync(junction) → ERR_FS_EISDIR
+```
+
+## Reference Tables
+
+### Tool execution stages (exact order)
+| # | Stage | Notes |
+|---|---|---|
+| 1 | model tool-call block | assistant message contains tool-call |
+| 2 | `tool/call` session event | logged before execution |
+| 3 | UI pending card | `presentCall(args)` |
+| 4 | `tools/pre-execute` waterfall | hooks, permission, sandbox → allow / deny / ask |
+| 5 | `ctx.approval` (ask path) | one-shot; rejected/cancelled/unavailable → denied |
+| 6 | monotonic guards | deny or abstain; identity protected |
+| 7 | `tools/execute` waterfall | around-dispatch: timeout, retry, metrics |
+| 8 | tool `execute()` body | may fire fs gates + tool-owned events (`todo/write`, `fs/observed`, `hook/invoked`, `hook/result`, `tool/code-dispatch`) |
+| 9 | `tools/post-execute` waterfall | accept, block, replace, add context |
+| 10 | registry outer normalization | snapshot throws → `isError` |
+| 11 | `ToolDefinition.finalizeContent` | last content-only invariant |
+| 12 | `tools/result` emit | frozen authoritative outcome |
+| 13 | `tool/result` session event | single model-facing outcome; batch settled |
+| 14 | `additionalContexts` FIFO | injected after recorded tool results |
+| 15 | UI completed card | `presentResult(args, result)` |
+
+Throws from stages 4–9 route to stage 10; denied calls skip the body but still traverse `tools/post-execute`.
+
+### Load-bearing events
+| Event | Mode | Dispatcher → listeners |
+|---|---|---|
+| `agent/pre-step` | waterfall | agent-loop → 15 pkgs (time-context, agent-instructions, plan-mode, hooks-*, tool-skill, tool-subagent…) |
+| `agent/request` · `agent/request-error` | waterfall | agent-loop → agent, webhook · compaction-basic, llm-retry |
+| `agent/turn-stopping` | serial | agent-loop → hooks-claude-code, hooks-codex |
+| `llm/stream` | waterfall | llm → agent-loop, llm-replay, session-checkpoint-policy, session-title |
+| `session/event` | emit | session → 27 pkgs (persistence, projection, telemetry, tools, server…) |
+| `session/flush` | parallel | session → session-persistence-jsonl, session-telemetry |
+| `system-prompt/assemble` | waterfall | system-prompt → agent, agent-presets |
+| `tools/pre-execute` · `execute` · `post-execute` | waterfall | tools → hooks-*, tool-jobs · session-checkpoint-policy, timeout-policy · spill-policy, repeat-tool-reminder, tool-fs-search |
+| `fs/write-intent` · `fs/edit-intent` | waterfall | tool-fs, tool-str-replace-editor → fs-observation-policy |
+| `approval/request` | waterfall | user-approval → acp, remotes |
+| `webserver/index-inject` | emit | webserver → inspector, modules |
+
+### Shared-instance hubs (fan-in, ~790 peer edges)
+`session` (92) > `llm` (83) > `agent` (64) > `tools` (42) > `invariants` (34) > `system-prompt`/`session-projection` (29) > `scope` (21). Top consumers: `api-session-controller` (26 peers), `subagent` (19). `llm` has zero outgoing peers (pure foundation); `tools --> agent` but not reverse; `session --> scope` only.
+
+## Key Takeaways
+1. Read the peer graph before adding a dependency — an edge means "require the host's shared instance", and fan-in hubs (session, llm, agent, tools) are the services everyone shares.
+2. Pick event hooks by matrix lookup, not guesswork: Mode defines the contract, Dispatchers define the owner, empty Listeners mark open extension points.
+3. Insert tool policy only at its designated waterfall; keep order-sensitive rules as registered monotonic guards, with `ctx.approval` resolving asks before guards.
+4. Normalize both sides of every public contract (adapter throws vs runtime terminal finish chunks) and report orthogonal outcome flags (`timedOut`, `signal`, `exitCode`) independently.
+5. Teardown must reach quiescence: close listener registries before killing, then `kill → await done`; dispatch loops must contain listener exceptions.
+6. Scrub env (`*KEY*/*SECRET*/*TOKEN*/*PASSWORD*`) and use 0700 dirs + random `'wx' 0o600` files around untrusted output; unlink — never recursively delete — link-shaped paths.
+
+## Connects To
+- **Ch 4**: peer = shared Cordis service instance; duplicate-identity errors.
+- **Ch 6**: the package groups/layers the graph visualizes.
+- **Ch 7**: the event matrix is the canonical capability-seam inventory.
+- **Ch 14**: agent-loop as chief dispatcher of `agent/*` events.
+- **Ch 15**: tool-execution subsystem detail behind the stage table.
+- **Ch 17**: `LlmAdapter`/`LlmRuntime` failure contract.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch09-api-gateway.md

@@ -0,0 +1,106 @@
+# Chapter 9: API Gateway & LLM Wire Extensions
+
+## Core Idea
+dsh exposes Host business logic to the Client through the **Typert API Gateway**: `@Remote`/`@RemoteScope` decorators select unary service methods, the build generates strict Host+Client contracts, and calls reuse the Connection RPC over `POST /api/<namespace>/<method>`. Separately, `@deepseek-ai/dsh-llm-deepseek` adds DeepSeek-specific HTTP headers and additive request-body fields (`dsh_plugin_packages`, `dsh_session_log`) that never enter model input.
+
+## Frameworks Introduced
+- **Typert API Gateway**: unary-only Remote-method bridge. Layers run `remotes → gateway → connection → webserver`; `packages/api` holds BFF+Typert, `packages/client/connection` and `packages/host/webserver` hold transport.
+  - When to use: any Host service method a browser/SDK client must call with one request → one result.
+  - How: mark methods `@Remote`/`@RemoteScope`, extend `TypertRemoteService`, generate contracts, mount via `api-remotes`, call `ctx.remote.<namespace>.<method>(...)`.
+- **`@Remote`**: calls a Cordis service registered on the root Host Context. Host objects (e.g. `Agent`) cannot cross the wire — declare a `TypertLookupMap` so a parameter `agent` becomes an `agentId` wire field the Gateway resolves back to the object.
+- **`@RemoteScope(key)`**: resolves an identity to a scoped Context via `ctx.typert.contexts`, gets the service from that Context. Use when the method depends on scoped composition and needn't receive objects like `Agent` explicitly.
+- **`TypertRemoteService` / `bindTypertRemote(this, serviceKey)`**: explicit service-key + namespace binding (no compiler-injected symbol). `bindTypertRemote` for services with another base class.
+- **Strict generation pipeline**: root build runs `build:lib:host` → `build:lib:client` → `build:web`. Host pass = `tsc -b tsconfig.host.json` then `tsdown --env.DSH_BUILD_FACE host` (runs Typert generator); Client pass = `tsc -b tsconfig.client.json` + `tsdown --env.DSH_BUILD_FACE client`, consuming generated artifacts without restarting Typert.
+- **SRC development fallback**: `node --import tsx/esm` skips the Typert compiler; decorator initializers still record a versioned descriptor so the Gateway builds a weaker descriptor with no `ts.Program`. Solves Host dispatch from source only — Client still refuses SRC descriptors lacking strict codecs.
+- **`DeepSeekLlmApiExtensionRegistry`**: one provider per top-level extension name; empty/padded names, duplicate registrations, and collisions with the base request fail before HTTP dispatch.
+- **Body-extension transaction**: serialize base body (incl. exact `messages`) → ask registered providers to `prepare()` fields → merge as top-level siblings → on HTTP 2xx run `accept()` before reading SSE. No registry = unextended base body sent.
+
+## Key Concepts
+- **`ctx.remote.<namespace>`** (root) / **`agentCtx.remote.<namespace>`** (scoped): concrete Client functions on ordinary objects; each namespace is a traced Cordis child Service registered as `remote.<namespace>`, mounted through `ctx.remote.$mount()`.
+- **`TypertLookupMap`**: wire-identity association for complex Host params; `ctx.typert.lookups.register()` = declaration+default resolver, `.configure()` = async Host-composition override scoped to an effect lifetime.
+- **`api-remotes` assembly**: only `@deepseek-ai/dsh-api-remotes` is assembled; it imports business packages' `/remote` subpaths, mounts contributions, re-exports declaration merges. Host-method surface = only what's selected at generation time.
+- **`/api` route**: Client calls `connection.rpc.call('/api', '<ns>/<method>', { args }, signal)` → `POST /api/<ns>/<method>` with `{ args }`. Gateway claims only two-segment endpoints with a strict descriptor or SRC marker; other requests 404.
+- **Wire namespaces**: HTTP fields = lowercase kebab (`x-deepseek-harness-session-id`); request-body extensions = snake with reserved `dsh_` prefix; DSH-owned nested JSON = camelCase (`afterSeq`); tagged values = kebab, durable events `domain/action`.
+- **`dsh_plugin_packages`** (enabled by default): complete active Loader-backed `{name,version}` package inventory; deduped, sorted by name then version; disabled/failed/unloading entries and non-package provenance absent; `packages: []` when none qualify.
+- **`dsh_session_log`** (disabled by default): contiguous suffix of the canonical Session log, version 2. First upload `afterSeq: -1`; later uploads start after the greatest accepted watermark. `session` member projects `Session.header` (id, createdAt, `isSeeded` lineage bit, optional cwd/parentSession/origin/delegationDepth/agentPreset).
+- **`delivery-accepted` watermark event**: appended after HTTP 2xx — type `session-log-deepseek/delivery-accepted`, data `{sessionId, sessionFormatVersion, throughSeq}`. Binds watermark to the logical format generation.
+- **At-least-once delivery**: crash after acceptance but before persistence may resend an already-accepted range → duplicates, never a gap. Fork ignores inherited watermarks naming another Session.
+
+## Mental Models
+- **Use `@Remote` for root-Host services, `@RemoteScope` for scoped-composition methods.** Complex Host objects never cross the wire — think of the lookup map as the wire↔object identity table.
+- **Think of Remote as unary-only.** Session event streams, pagination, incremental reduce, projection, entity substreams → register an exact Connection Fetch route, never a Remote method.
+- **Think of the extension transaction as prepare-then-accept.** Only a 2xx endpoint accepts any contribution; a non-2xx or transport failure sends nothing and appends no watermark.
+- **Think of extension fields as "outside the model."** They sit outside `messages`/system prompt/tool schemas, so they add no input tokens and don't alter the model-visible prefix.
+
+## Anti-patterns
+- **Modeling a streamed/browser-native feature as a Remote method**: Remote is strictly one request → one result; streaming must use a separate data protocol + registration model even if it shares the Connection.
+- **Guessing whether an `Agent` object came from restoration**: lookup policy is per-key, so all `agent`/`session` params share cold-resume behavior; the method must not assume live-vs-restored provenance.
+- **Treating `delivery-accepted` as persistence**: it asserts endpoint-level HTTP 2xx only — not SSE completion, not remote persistence.
+- **Collapsing `dsh_plugin_packages` by package name**: receivers must preserve distinct simultaneous versions and ignore array order.
+- **Reading generated `.d.ts` as ground truth for dispatch**: the strict contract (types/codecs) always comes from `lib/typert.remote-client.*`, never from a running source Host.
+
+## Code Examples
+```ts
+export class GoalService extends TypertRemoteService {
+  constructor(ctx: Context) { super(ctx, 'goals') }   // namespace 'goals'
+  @Remote('create')
+  createForClient(agent: Agent, request: CreateGoalRequest, signal: AbortSignal): CreateGoalResult {
+    signal.throwIfAborted(); return this.create(agent, request)
+  }
+  @RemoteScope('agent', 'current')                    // scoped: agentId → context → service
+  currentForClient(): CreateGoalResult { return { accepted: true } }
+}
+// Client — inject ['remote', 'remote.goals']; single lookup param collapses the wire field:
+await ctx.remote.goals.create(agentId, { objective: 'ship it' })
+await agentCtx.remote.goals.create({ objective: 'ship it' })
+```
+```jsonc
+// dsh_plugin_packages (version 1)
+{ "dsh_plugin_packages": { "version": 1, "packages": [ { "name": "@deepseek-ai/dsh-example", "version": "0.1.1-rc.2" } ] } }
+// dsh_session_log suffix (version 2)
+{ "dsh_session_log": { "version": 2, "sessionFormatVersion": 2,
+    "session": { "version": 2, "id": "session-id", "createdAt": 1780000000000, "isSeeded": false },
+    "afterSeq": -1, "throughSeq": 0,
+    "events": [ { "type": "turn/start", "seq": 0, "time": 1780000000001, "data": { "turn": 1 } } ] } }
+// watermark appended after 2xx
+{ "type": "session-log-deepseek/delivery-accepted", "seq": 8, "time": 1780000000002,
+  "data": { "sessionId": "session-id", "sessionFormatVersion": 2, "throughSeq": 7 } }
+```
+
+## Reference Tables
+
+**Request headers (`dsh-llm-deepseek`)**
+| Header | Presence | Value |
+|---|---|---|
+| `user-agent` | every provider HTTP request | `product/version (+url)`; default product `deepseek-harness` |
+| `x-deepseek-harness-user-id` | every authorized chat-completion | stable anonymous Harness-home UUID |
+| `x-deepseek-harness-session-id` | chat-completion with a Session id | exact `sessionId` string |
+| `x-deepseek-harness-compact` | purpose `compaction` | literal `1` |
+
+**Component responsibilities**
+| Package | Role |
+|---|---|
+| `dsh-typert-protocol` | decorators, Gateway bindings, invocation descriptors (no analysis/services) |
+| `dsh-typert-generator` | build-time strict signature/type/lookup/Context analysis → artifacts |
+| `dsh-typert-registry` + Loader | Host descriptors/schemas into `ctx.typert`, lookup+Context providers |
+| `dsh-api-session-controller` | Agent/Session identity policy; standard `agent`/`session` resolvers |
+| `dsh-api-gateway` | `ctx.typertGateway`; claims endpoints, resolves objects, invokes, validates |
+| `dsh-api-gateway/client` | `ctx.remote`; mounts descriptors, initiates/validates/cancels |
+| `dsh-api-remotes/client` | selects+mounts allowed `/remote` contributions |
+| `dsh-client-connection` | RPC carrier, correlation, trust boundary, cancellation, `/api` bridge |
+
+**Generated files per business package (`lib/`)**: `typert.host.js/.d.ts`, `typert.remote-client.js/.d.ts`, `typert.remote-client.d.ts.map`; entries exposed via `./typert` (Host) and `./remote` (Client).
+
+## Key Takeaways
+1. Gateway owns only the Remote data protocol + business dispatch; Connection owns transport, RPC ids, envelopes, cancellation — swap the carrier without touching descriptors.
+2. The trust fence runs in Connection **before** the HTTP bridge, then dispatches inside the shared FetchHandler.
+3. A strict endpoint withdrawn on the Host does **not** degrade to SRC inference — hot unload can't silently weaken validation.
+4. `session/not-found` and `session/agent-busy` `RemoteError` codes pass to the wire unchanged; only unclassified throws fold into `gateway/internal`.
+5. Extension fields are versioned independently per field; JSON member order is not protocol.
+
+## Connects To
+- **Ch06 architecture**: the `remotes → gateway → connection → webserver` layer stack and package split.
+- **Ch07 capability-seams**: Remote is the unary seam; streaming seams use a different registration model.
+- **Ch02 plugin-basics**: declaring `@Remote` methods and `inject`-ing `remote.<namespace>` is the plugin-author wiring.
+- **Ch08 internals-pipelines**: the `build:lib:host`/`client`/`web` order and `DSH_BUILD_FACE` split.
+- **Ch10 config-catalog**: `host-webserver.{host,port}`, `client-connection.trustedHosts`, `api-gateway.websocketHeartbeatIntervalMs` (default 2000 ms), `llm-deepseek.*`.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch10-config-catalog.md

@@ -0,0 +1,97 @@
+# Chapter 10: Config Catalog
+
+## Core Idea
+`config-catalog.md` is the **deployment-axis** reference: for every loadable harness package it pastes the verbatim `config:` block a `cordis.yml` entry can set, plus each plugin's `Requires:` injection line. It is **generated** from source (`scripts/gen-config-catalog.ts`), not a layering spec — the paste is the plugin's *full declared config type*, and any field the runtime schema deliberately excludes is a runtime-only seam that is **not settable from `cordis.yml`**.
+
+## Frameworks Introduced
+- **`config:` block (cordis.yml)**: the only settable surface catalogued here. The plugin's `apply`/service constructor receives the declared config type; referenced types are pasted (package-local) or linked.
+- **`Requires:` line**: lists the service keys the plugin `inject`s — its `cordis.yml` tree must also load providers for those services. Scope = harness tier (`packages/`); vendored cordis plugins (`hmr`, console logger) are pinned upstream and not catalogued.
+- **`static Config` / schemastery schema**: most plugins supply defaults statically and validate via a same-named schemastery schema; the generator cross-checks the schema against the pasted declaration so the paste cannot hide a loader-accepted field.
+- **Generated + verified**: `pnpm run gen-config-catalog` regenerates; `verify-config-catalog` (part of `doc-sync`) checks freshness. Do not hand-edit.
+- **Three package classes**: (1) **loadable** — with a `config:` block; (2) **loadable no-config** — a `cordis.yml` entry with no `config:`; (3) **seam** — abstract service classes (`AttachmentStore`, `SandboxProvider`, `SessionPersistence`, `CredentialProvider`, …) not directly loadable; (4) **library** — no plugin entry, cannot be loaded.
+
+## Key Concepts
+- **Home path convention**: `dshHome` (settings/credentials/shell-env/agent-instructions) defaults to `$DSH_HOME` then `~/.dsh`.
+- **Runtime-only seam**: a field the schema excludes by design — its JSDoc says so; not settable from `cordis.yml`.
+- **Preset-root precedence**: `agent-presets` `roots[]` scanned in precedence order (earlier wins a duplicate id); `includeShippedRoot` prepends the bundled `system` root, `includeUserRoot` appends the home `user` root.
+- **`SandboxMode` / `ApprovalPolicy`**: shared deployment knobs — `sandbox-policy.mode` default `read-only`; `user-approval.policy` = `ask` (fail-closed) or `never` (deterministic CI/unattended).
+- **Backend routing**: `storage-domain.backend` = default route, `routes` overrides per domain name; unknown backend fails `open` with `backend-not-found`.
+- **No-default `root`s**: `session-persistence-jsonl.root`, `storage-json.root` have no default on purpose — a `process.cwd()` fallback would scatter files as cwd changes (bash/subprocess).
+
+## Mental Models
+- **Read the config type as the wire surface, not the runtime object**: the paste is exactly what `cordis.yml` may set; anything else is a runtime-only seam.
+- **Think of each capability seam as "abstract service + concrete package"**: the *concrete* package (`dsh-bash-sandbox`, `dsh-storage-sqlite`, …) carries the config; the abstract seam package is never loaded directly.
+- **Think of sandbox policy vs runner as split**: `sandbox-policy` owns `mode`/`workspaceRoot` (per-session resolution); the runner choice is the `ctx.sandbox` provider's config, not the executor's.
+
+## Anti-patterns
+- **Setting a runtime-only seam from `cordis.yml`**: it is deliberately excluded from the schema and will not apply.
+- **Loading a seam or library package in `cordis.yml`**: seams are abstract (load a concrete impl), libraries have no plugin entry.
+- **Defaulting storage/session `root` to `process.cwd()`**: scatters unit files across whatever cwd the process is in — the doc forces an explicit `root` for exactly this reason.
+- **Assuming a full CLI>env>home>profile precedence chain lives in this doc**: it does not — this file documents the `config:` surface only; the layering/merge model is in ch01/ch02.
+
+## Reference Tables
+
+**Most-needed config keys** (`@deepseek-ai/` prefix omitted; type + default where declared)
+
+| Key (package) | Type | Default | Purpose |
+|---|---|---|---|
+| `agent-default-model.provider` / `.model` | string | required | default provider route + model id |
+| `agent-loop.agents[]` | array | required | agents created/resumed at startup (`id`, `sessionId`, `cwd`, `resumeSessionId`) |
+| `agent-loop.maxParallelToolCalls` | number | `DEFAULT_MAX_PARALLEL_TOOL_CALLS` | parallel-safe calls per agent step (1 = serial) |
+| `agent-presets.default` | string | required | preset id when caller names none (missing = loud fail) |
+| `agent-presets.roots[]` | array | required | preset scan roots in precedence order |
+| `agent-presets.includeShippedRoot` / `includeUserRoot` | bool | `true` | prepend bundled `system` / append home `user` root |
+| `agent-tool-presentation.mode` | `'native'\|'ptc'\|'both'` | required | model-visible tool form |
+| `agent-instructions.maxBytes` | number | required | UTF-8 byte cap per rendered baseline/dynamic batch |
+| `llm-deepseek.apiKeyEnv` | string | `DEEPSEEK_API_KEY` | credential env-var name, resolved per request |
+| `llm-deepseek.baseURL` | string | `$DEEPSEEK_BASE_URL` → public API | endpoint base |
+| `llm-deepseek.thinking` | `'enabled'\|'disabled'` | provider default | deployment thinking policy |
+| `llm-deepseek.reasoningEffort` | `'off'\|'low'\|'high'\|'max'` | `high` | default thinking effort |
+| `llm-deepseek.maxTokens` | number | `256000` | default per-request output cap |
+| `llm-deepseek.defaultContextWindow` | number | `1000000` | context capacity fallback |
+| `llm-deepseek.models[]` | `DeepSeekCatalogModel[]` | V4 Flash/Pro/Flash Vision Exp | advertised selector models |
+| `bash-local.cwd` | string | `process.cwd()` | default command working dir |
+| `bash-local.timeoutMs` / `maxTimeoutMs` | number | — | foreground timeout + per-call override cap |
+| `bash-local.maxOutputBytes` / `maxSpillBytes` | number | — | in-memory output / spill-file caps |
+| `host-webserver.host` | `'127.0.0.1'\|'0.0.0.0'` | — | listen host |
+| `host-webserver.port` | number | — | listen port (0 = OS-assigned) |
+| `host-webserver.compression` | `'none'\|'gzip'` | `none` | response compression |
+| `client-connection.trustedHosts` | string[] | — | non-loopback authorities for `/api` trust fence |
+| `client-connection.cookieMaxAgeDays` | number | `30` | browser-session lifetime |
+| `client-connection.maxRequestBodyBytes` | number | `300 MiB` | max buffered `/api` JSON body |
+| `sandbox-policy.mode` | `SandboxMode` | `read-only` | file-sandbox default (fail-safe) |
+| `sandbox-policy.workspaceRoot` | string | `process.cwd()` | fallback root (agentless / no-cwd) |
+| `user-approval.policy` | `'ask'\|'never'` | `ask` | approval default (never = CI/unattended) |
+| `permission-presets.presets` / `defaultPreset` | map / string | `workspace-write`,`danger-full-access` | preset knob table + new-session default |
+| `session-persistence-jsonl.root` | string | required | session files root |
+| `session-persistence-jsonl.compression` | `'zstd'\|'none'` | `zstd` | physical encoding |
+| `storage-domain.backend` / `routes` | string / map | required | default backend + per-domain overrides |
+| `storage-json.root` | string | required | `<unit>.json` file dir |
+| `storage-sqlite.path` / `journalMode` | string / `'wal'\|'delete'\|'truncate'\|'persist'` | `:memory:` / `wal` | DB file + journal pragma |
+| `mcp-client` (per server) | `StdioConfig`\|`StreamableHttpConfig` | — | `transport`, `serverName` (`mcp__<name>__<tool>`), `command`/`url`, `toolCallTimeoutMs` |
+| `web.searchProvider` / `fetchProvider` | string | auto-select | pin which provider wins per capability |
+| `web-app.openBrowser` / `printUrl` / `surfaceContext` / `trustedHosts` | bool/bool/bool/string[] | — | browser handoff, URL line, `app:web-surface` context, `--trusted-host` |
+| `settings-file.path` | string | `settings.yaml` under home | settings doc location |
+| `credentials-local.path` | string | `.credentials.yaml` under home | credentials doc location |
+| `compaction-basic.thresholdRatio` / `retainRatio` | number | `0.8` / `0.16` | compact-at / retain fractions of context window |
+| `persona.text` / `complete` | string / bool | — | persona prose; `complete` = whole system prompt |
+| `tool-web.search` / `fetch` / `fetchMaxOutputChars` | bool/bool/number | `true`/`true`/`200000` | tool registration + fetch output cap |
+| `tool-todo.allowParallelInProgress` | bool | required | allow multiple `in_progress` todos |
+| `api-gateway.websocketHeartbeatIntervalMs` | number | `2000` | WS ping interval (1…2147483647 ms) |
+
+**Where the rest lives**: the source doc's `## @deepseek-ai/dsh-*` sections (one per package, ~110 packages) carry the full verbatim declarations + JSDoc; its tail lists `Loadable plugins with no config`, `Seam packages`, and `Library packages`. For the runtime wire surface, see the generated Cordis API region on each `subsystems/core.md` page; model-facing tool schemas live in `tool-catalog.md`.
+
+## Key Takeaways
+1. Config is delivered through `cordis.yml` `config:` blocks — this catalog is the authoritative list of what each package accepts.
+2. Every key's default and validation come from the plugin's `static Config` + schemastery schema, not from a central registry.
+3. `Requires:` is load-critical: a config tree that omits an injected service fails to compose.
+4. Storage/session `root` paths are deliberately default-less — state them explicitly to avoid cwd-scatter.
+5. Deployment policy (sandbox mode, approval policy, trusted hosts, compaction thresholds) is spread across dedicated policy packages, not one global config.
+
+## Connects To
+- **Ch01 user-guide / Ch02 plugin-basics**: the `cordis.yml` layering and merge semantics (this doc covers only the per-package surface).
+- **Ch05 cordis-api**: the generated Cordis API region on subsystem pages that these declarations reference.
+- **Ch07 capability-seams**: the "seam packages" here are the abstract classes the seams chapter names.
+- **Ch09 api-gateway**: `host-webserver`, `client-connection.trustedHosts`, and `api-gateway.websocketHeartbeatIntervalMs` configure the gateway transport.
+- **Ch11 tool-catalog**: the model-facing tool schemas that `tool-web`, `tool-todo`, `tool-workflow`, `tool-bash` config keys shape.
+- **Ch12 persistence-catalog**: `session-persistence-jsonl`, `storage-*`, `session-query-sqlite`, `session-projection-cache` backends.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch11-tool-catalog.md

@@ -0,0 +1,121 @@
+# Chapter 11: Tool Catalog
+
+## Core Idea
+This is a GENERATED registry of every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` delivered via system-prompt assembly. It is produced by BOOTING each tool plugin on a real context and reading `ctx.tools.schemas()` — not a static AST pass — because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools).
+
+## Frameworks Introduced
+- **Tool contribution = `{ name, description, parameters }` into `ctx.tools`**: a tool is the model-facing projection of a plugin's execute logic; `ctx.tools.schemas(scope)` projects an allowlist (name/description/parameters only) so `output`/`execute`/callbacks never leak into model requests.
+  - When to use: every model-facing action. How: plugin contributes a `ToolDefinition`; the catalog generator boots it and reads the projected schema.
+- **Capability-seam stability**: a tool keeps its provider behind an abstract seam (`ctx.lsp`, `ctx.web`, `ctx.subagents`, `ctx.codeRuntime`, `ctx.shell`, `ctx.fs`, `ctx.terminals`) so the model-visible schema stays stable across backend swaps.
+  - When to use: any swappable backend (`lsp`, `web_search`/`web_fetch`, `subagent`).
+- **Load-time config names / shipped aliases**: a registered `name` may be a load-time config (e.g. `tool-subagent`'s `toolName` default `subagent`, shipped alias `subagent_fork`); a deployment may expose a package under a different or additional name.
+- **Reserved transport (`run_code`)**: owned by the tool registry outside filterable capability layers under `mode: ptc`/`mode: both`; under `ptc` it is the registry's only wire contribution — other capabilities are declared in a generated SDK section and re-enter the guarded tool pipeline via scheduled bindings (overlap up to `maxParallelSubCalls`).
+- **Boot-and-read verification**: `gen-tool-catalog` generator + `verify-tool-catalog` (part of `doc-sync`); a completeness guard globs `packages/*/tool-*` and fails if a package is missing from the boot manifest, so a new tool cannot be silently undocumented.
+
+## Key Concepts
+- **ctx.tools**: the single registry of model-facing tools (see Ch 15 for the dispatch pipeline behind it).
+- **Capability seam**: `ctx.shell`, `ctx.fs`, `ctx.subprocess`, `ctx.terminals`, `ctx.lsp`, `ctx.web`, `ctx.codeRuntime`, `ctx.subagents`, `ctx.workflowEngine`, `ctx.jobs` — abstract services a tool consumes; one provider per context.
+- **Requires / Writes-affects**: the package map's two metadata columns — which seams a tool needs, and which events/durable effects it produces.
+- **Shipped alias**: a second registered name for the same package (e.g. `subagent_fork` for a fixed-route delegation).
+- **Reserved transport**: `run_code` — excluded from filterable capability layers; registry-owned.
+- **Per-package deployment note**: records opt-in status, config branches, and defaults the generator had to choose (e.g. `todo_write`'s `allowParallelInProgress: true`).
+- **Read-before-write policy**: added by `@deepseek-ai/dsh-fs-observation-policy` (an `fs/*` event-gate plugin) — no schema change; a deployment loading the fs tools is expected to also load it.
+
+## Mental Models
+- Think of the tool catalog as the **system-prompt assembly's menu**: what the model is *offered*, not what the runtime can *execute* (the Cordis surface is the latter).
+- Think of a tool's schema as **runtime-spread**, never statically knowable — always boot to read it, never hand-transcribe.
+- Use a **seam** when a capability may swap backends; keep the tool thin and let the seam own the vocabulary.
+- Think of `run_code` as the **only non-filterable wire contribution** under `ptc` — everything else is reachable only through the code-runtime SDK.
+
+## Anti-patterns
+- **Hand-editing the generated catalog**: it is regenerated and re-verified by `doc-sync`; edits are overwritten.
+- **Guessing an Inspect/LSP provider name**: `cordis_inspect_list`/provider discovery must precede `cordis_inspect_query`/`lsp`; an Inspect method is read-only, not a business Service plugin code can call.
+- **Loading fs tools without the observation-policy plugin**: bare `write`/`edit` lose the read-before-write guard.
+- **Treating `subagent`'s discovery schema as fixed**: model-selection on/off, background mode, and the registration name are per-instance config (`modelSelectionSettings`, `backgroundMode`, `enableRunInBackground`, `toolName`).
+
+## Code Examples
+```jsonc
+// Tool schema shape every entry shares: { name, description, parameters }
+{ "name": "bash",
+  "description": "Execute a bash command (bash -c) and return stdout/stderr.",
+  "parameters": { "type": "object",
+    "properties": {
+      "command": {"type":"string"},
+      "description": {"type":"string"},
+      "timeoutMs": {"type":"number"},
+      "workdir": {"type":"string"},
+      "run_in_background": {"type":"boolean"}
+    }, "required": ["command","description"] } }
+```
+```ts
+// run_code bridge: each nested call re-enters the guarded tool pipeline
+// and links to the outer result via a tool/code-dispatch-start + tool/code-dispatch pair.
+// sub-call id = `<parent>:code:<n>` (submission order); tool/result vocabulary carries content + isError.
+```
+```ts
+type LspOperation = 'goToDefinition' | 'findReferences' | 'goToImplementation' | 'hover';
+// schedule selectors: after_seconds | at | every_seconds (>= 300) — exactly one.
+```
+
+## Reference Tables
+Full lookup table — name → one-line purpose, grouped by category. Per-tool JSON Schemas and exact field docs live in `src/docs/tool-catalog.md` (generated; ~90KB), package sections below its "Tool Package Map".
+
+| Tool | Package | Purpose |
+|---|---|---|
+| **Human interaction** |||
+| `ask_user_question` | dsh-tool-ask-user | Pause until the UI/provider returns a human answer (confirmation/choice/missing info). |
+| `exit_plan_mode` | dsh-plan-mode | Present a plan for review; reject outside plan mode, no schema churn on policy change. |
+| **Shell (one-shot, fresh process)** |||
+| `bash` | dsh-tool-bash | Run `bash -c`, return stdout/stderr; `run_in_background` → job id. |
+| `pwsh` | dsh-tool-pwsh | Windows `pwsh -Command` counterpart; mirrors bash minus sandbox controls. |
+| **Shell (persistent PTY)** |||
+| `bash` (persistent) | dsh-tool-bash-persistent | Owner-isolated persistent bash; cwd/env persist across calls. |
+| `pwsh` (persistent) | dsh-tool-pwsh-persistent | Owner-isolated persistent pwsh. |
+| **Filesystem** |||
+| `read` / `write` / `edit` | dsh-tool-fs | UTF-8 read (line-numbered) / create-or-replace / literal-replace edit. |
+| `read_image` | dsh-tool-fs | Read PNG/JPEG/WebP/GIF; refuses unless the routed model accepts image input. |
+| `glob` / `grep` | dsh-tool-fs-search | Path discovery / ripgrep content search (packaged `@vscode/ripgrep`, no host rg). |
+| `str_replace_editor` | dsh-tool-str-replace-editor | Standalone view/create/unique-literal-replace/insert editor. |
+| **Terminals (opt-in)** |||
+| `terminal_open`/`close`/`list`/`read`/`send`/`signal` | dsh-tool-terminal | Persistent terminal sessions; `send(run_in_background)` registers with `ctx.jobs`. |
+| **Code runtime** |||
+| `run_code` | dsh-tools | Execute a TypeScript program body against tools (PTC transport). |
+| **Delegation & control** |||
+| `subagent` / `list_subagent_models` | dsh-tool-subagent | Delegate a self-contained task / discover LLM routes. |
+| `send_message` / `interrupt_agent` / `list_agents` | dsh-tool-subagent-control | Steer, interrupt, list continuable background subagents (global names). |
+| `workflow` | dsh-tool-workflow | Orchestrate many subagents via a JS script (`agent`/`pipeline`/`parallel` hooks). |
+| `ralph` | dsh-tool-ralph | Foreground fresh-agent loop; one immutable objective + optional round cap. |
+| `spawn_teammate` | dsh-experimental-tool-agent-team | Create a named durable teammate (Team Lead only). |
+| `team_task_*`, `wait_agent`, team `send_message`/`interrupt_agent`/`list_agents` | dsh-experimental-tool-agent-team | Shared task board (create/get/list/update) + team mailbox/status wait. |
+| **Background jobs** |||
+| `job_list` / `job_output` / `job_kill` | dsh-tool-jobs | Kind-agnostic controller: bash, PTY sends, subagents all through the same three. |
+| **Goal (same-session)** |||
+| `create_goal` / `get_goal` / `update_goal` | dsh-tool-goal | Persisted long-running objective; direct-human root authority for mutations. |
+| **Schedule** |||
+| `schedule_create` / `schedule_delete` / `schedule_list` | dsh-schedule | Session-local reminders (after_seconds | at | every_seconds≥300). |
+| **Session query (opt-in)** |||
+| `session_search` / `session_trace` / `session_event_read` / `session_event_search` / `session_event_trace` | dsh-tool-session-query | Read-only search/trace over the durable event log, authorized by the calling agent. |
+| **Skill** |||
+| `skill` | dsh-tool-skill | Load full instructions for a named skill from the session catalog. |
+| **Web** |||
+| `web_search` / `web_fetch` | dsh-tool-web | Search (1–4 queries) / fetch a URL; provider behind `ctx.web`. |
+| **LSP** |||
+| `lsp` | dsh-tool-lsp | Code navigation (definition/references/implementation/hover); `LSP_UNAVAILABLE` without a provider. |
+| **Dynamic Cordis (opt-in)** |||
+| `cordis_define`/`inspect_list`/`inspect_query`/`inspect_self`/`run`/`stop`/`undefine` | dsh-tool-cordis | Define/inspect/run immutable Cordis packages in a vm sandbox (not in any shipped tree). |
+| **TODO** |||
+| `todo_write` | dsh-tool-todo | Session-owned checklist; whole-list replace (no partial updates). |
+
+## Key Takeaways
+1. The catalog is the *offered* tools (name/description/parameters), generated by booting each plugin and reading `ctx.tools.schemas()` — never a static AST pass.
+2. Every tool maps to a **package** + **seams** (`Requires`) + **durable effects** (`Writes/affects`); the package map is the primary index.
+3. Keep swappable capabilities behind a seam (`ctx.web`, `ctx.lsp`, `ctx.subagents`) so the schema does not change on backend swap.
+4. `run_code` is the registry's reserved transport — the only wire contribution under `ptc`; other capabilities reach it via scheduled bindings.
+5. Registration names can be config-driven and aliased (`subagent`/`subagent_fork`); deployment notes record shipped aliases and generator-chosen defaults.
+
+## Connects To
+- **Ch 15**: `ctx.tools` dispatch pipeline (ToolDefinition, guards, observation policy) behind these schemas.
+- **Ch 07**: capability seams — the Service/Provider/Consumer split each tool leans on.
+- **Ch 16**: `tool/call`, `tool/result`, `tool/code-dispatch*` are the durable session-log facts tools emit.
+- **Ch 10**: config keys that shape tools (`toolName`, `enableRunInBackground`, `sampleOverCapGlobResults`, preset tables).
+- **Ch 14**: the agent loop requests these tools and commits their call/result events.