better-dsh 0.2.4-a → 0.2.4-b

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

@@ -1,97 +0,0 @@
-# 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

@@ -1,111 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# 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

@@ -1,97 +0,0 @@
-# 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

@@ -1,121 +0,0 @@
-# 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.