super-dsh 0.1.12 → 0.3.0

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch03-plugin-framework-practice.md

@@ -0,0 +1,120 @@
+# Chapter 3: Plugin Framework & Practice
+
+## Core Idea
+Cordis runs each plugin in a Fiber whose dependency-driven lifecycle makes every registration self-cleaning; on that runtime, dsh's extension architecture is two contracts — the three-role capability split (Definition / Provider / Consumer) and the `LlmAdapter` streaming protocol.
+
+## Frameworks Introduced
+- **Fiber state machine**: `PENDING → LOADING → ACTIVE` (or `FAILED`); `ACTIVE → UNLOADING → DISPOSED`. `inject` gates PENDING→LOADING; `apply` throwing → FAILED; a required service disappearing unloads the plugin automatically and reloads it when the service returns.
+  - When to use: reasoning about any plugin's load, HMR, or teardown behavior.
+  - How: declare `export const inject = ['tools', 'llm']`; inside `apply` every injected service is ready.
+- **Service extension**: `class MetricsService extends Service { static inject = ['llm']; constructor(ctx) { super(ctx, 'metrics') } }` mounts `ctx.metrics`; typed via `declare module '@deepseek-ai/cordis' { interface Context { metrics: MetricsService } }`.
+  - When to use: exposing a capability to other plugins; required deps via `inject`, optional via `const m = ctx.get('metrics'); m?.record(...)`.
+- **Event modes**: `emit` (synchronous broadcast, return values ignored) · `bail` (first result other than `null`/`false`/`undefined` wins) · `serial` (registration order, async awaited, first non-null stops) · `waterfall` (each listener wraps the downstream result; must call `next()`).
+  - When to use: notification → emit; veto/policy check → bail; ordered setup → serial; middleware/interception → waterfall.
+- **Three-role capability design**: Service Definition (abstract class + Request/Result types) / Service Provider (subclass, `apply(ctx) { ctx.plugin(MyCapLocal) }`) / Consumer (`inject: ['tools', 'myCap']`). The complete capability is its seam; no individual role is.
+  - When to use: only when roles need independent evolution or provider replacement — Bash = `dsh-shell` / `dsh-bash-local` / `dsh-tool-bash`.
+  - How: swap providers by replacing one `cordis.yml` row; Provider and Consumer never depend on each other, only on the Definition.
+- **`LlmAdapter` contract**: extend `LlmAdapter` from `@deepseek-ai/dsh-llm`, implement `async *stream(options: GenerateOptions): AsyncIterable<StreamChunk>`, register with `ctx.llm.registerAdapter(providerNames, adapter)` under `inject = ['llm']`; optionally override `resolveModel()` and `listModels()`.
+- **Dynamic Cordis** (`@deepseek-ai/dsh-tool-cordis`): agent tool that inspects the live Cordis process and mounts/unmounts model-authored plugins in memory — temporary (gone on unmount or exit), and may affect other sessions in the same process.
+
+## Key Concepts
+- **Disposer semantics**: unload invokes disposers in reverse registration order, but multiple async disposers run concurrently with no serial guarantee — put order-dependent cleanup in a single `ctx.effect()` and await its steps serially.
+- **`ctx.plugin(child)`**: nested Fiber inheriting the parent context with an independent lifecycle; `await fiber.dispose()` guarantees (1) registrations removed, (2) child plugins recursively unloaded, (3) promise resolves after all async cleanup.
+- **Declaration merging**: `interface Events` (payload types) and `interface Context` (service types) — the type-safe extension mechanism for both events and services.
+- **Cordis events vs session events**: `agent/pre-step`, `agent/request`, `agent/request-error`, `tools/result`, `session/event` are Cordis events (`namespace/action`); `turn/*`, `step/*`, `tool/call`, `tool/result`, `compaction/*` are durable session-event types — observe them by listening to `session/event` and inspecting `event.type`.
+- **Service isolation**: `cordis-plugin-group` rows with `group: true` + `isolate: { shell: true }` + nested `config` list give separate plugin groups private instances of the same service.
+- **`resolve(request): Spec`**: explicit default-resolution step in a capability — prefer it over hiding `?? default` expressions inside `run()`.
+- **StreamChunk protocol**: `block-start` / `text-delta` / `tool-call-delta` / `block-end` / `usage` / `finish`; every `block-start` has a matching `block-end`; `index` increases from 0; `usage` before `finish`; `finish` is last (`reason.kind: 'stop' | 'tool-calls'`).
+- **`LlmError`**: stable-code error type for transport/protocol failures; the agent loop preserves message and code — it does not convert ordinary `Error`.
+- **`attributionHeaders()` / `options.signal`**: merged into / forwarded on every provider HTTP request an adapter makes.
+- **`brandString<ToolCallId>`**: branded id type carried by tool-call deltas and blocks.
+
+## Mental Models
+- Think of `inject` as a dataflow dependency: readiness gates loading, loss triggers disposal, return triggers reload — never hand-guard service access.
+- Think of an adapter as a translator: `GenerateOptions` (provider-neutral: model, reasoning-effort id, history, system prompt, tool schemas, params, stop sequences, abort signal) → provider request; provider stream → `StreamChunk`s. A field the provider can't honor throws `LlmError`, never a silent drop.
+- Treat the three-role split as an option, not a rule: a simple tool plugin is one package; split only for real replaceability.
+- Think of `resolveModel` as capability advertisement: it returns identity + `context` + `reasoning` metadata (ordered opaque ids, display names, optional default); the service validates the aggregate and rejects unsupported explicit efforts before `stream()`.
+
+## Anti-patterns
+- **Listening on `tool/call` or `compaction/*` as Cordis events**: they are session-log record types; only `session/event` fires.
+- **Waterfall listener omitting `next()` by accident**: short-circuits the pipeline by design — interception is the feature, not an error path.
+- **Splitting the three roles preemptively**: separate packages only when independent evolution or provider replacement is real.
+- **Throwing plain `Error` from an adapter**: the loop won't map it; diagnostics and policy lose the stable code.
+- **Promoting reasoning-effort ids into a core enum**: preserve the adapter's authoritative opaque selectable list, including `off` when the upstream capability API returns it.
+- **Counting on cross-effect disposal ordering**: concurrent async disposers have no serial completion guarantee.
+
+## Code Examples
+Adapter skeleton (registration + chunk protocol + error contract):
+```ts
+import { LlmAdapter, LlmError, attributionHeaders,
+         type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+class MyAdapter extends LlmAdapter {
+  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const res = await fetch(this.endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...attributionHeaders() },
+      body: JSON.stringify({ model: options.model, messages: options.messages }),
+      ...options.signal ? { signal: options.signal } : {},
+    })
+    if (!res.ok) throw new LlmError(`Provider API error: ${res.status}`, 'PROVIDER_HTTP_ERROR')
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    yield { type: 'text-delta', index: 0, text: 'Hello world' }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text: 'Hello world' } }
+    yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
+    yield { type: 'finish', reason: { kind: 'stop' } }   // or 'tool-calls'
+  }
+}
+export const inject = ['llm']
+export function apply(ctx: Context, config: Config) {
+  ctx.llm.registerAdapter(config.providers, new MyAdapter(config.apiKey))
+}
+```
+Tool-call chunk (arguments stream as raw JSON text):
+```ts
+yield { type: 'tool-call-delta', index: 1, id: brandString<ToolCallId>('call-123'),
+        name: 'bash', argumentsDelta: '{"command":"ls"}' }
+```
+Typed events:
+```ts
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    'my-plugin/ready': (payload: { id: string }) => void
+    'my-plugin/transform': (input: string, next: () => Promise<string>) => Promise<string>
+  }
+}
+```
+Three-role wiring — Definition: `export abstract class MyCapService extends Service` + `interface Context { myCap: MyCapService }` + `abstract execute(request): Promise<MyCapResult>`; Provider: `class MyCapLocal extends MyCapService` registered via `ctx.plugin(MyCapLocal)`; Consumer: tool with `inject: ['tools', 'myCap']` calling `await ctx.myCap.execute({ input })`. Compose: one `cordis.yml` row per package; replace the provider row to swap implementations.
+
+## Reference Tables
+| Fiber state | Meaning |
+|---|---|
+| PENDING | declared; required dependencies not ready |
+| LOADING | dependencies ready; `apply` running |
+| ACTIVE | running |
+| FAILED | `apply` threw an error |
+| UNLOADING / DISPOSED | disposing resources / fully unloaded |
+
+| Mode | Order | Stops when | Result |
+|---|---|---|---|
+| emit | all, sync | never | ignored |
+| bail | registration | first non-null/false/undefined | that value |
+| serial | registration, awaited | first non-null/false/undefined | that value |
+| waterfall | chain via `next()` | a listener omits `next()` | wrapped downstream value |
+
+Adapter facts: `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is an adapter-owned id with no lifecycle registration; `listModels()` advertises choices to selectors; `resolveModel(provider, model, signal?)` honors the optional signal so cancellation and disposal reach quiescence; omitting `reasoning` metadata means the model has no selectable reasoning-effort capability.
+
+## Key Takeaways
+1. All `ctx.*` registrations are effects — HMR, dependency loss, and `fiber.dispose()` clean up without manual teardown; use `ctx.effect` only for untracked resources.
+2. Pick the event mode by contract: notification (emit), veto (bail), ordered setup (serial), wrapping/interception (waterfall).
+3. The Service Definition owns Request/Result types; Providers and Consumers depend only on it — swapping providers is a one-row `cordis.yml` change.
+4. Reference implementations: `packages/llm/llm-deepseek/` (OpenAI-compatible format) and `packages/llm/llm-pi-ai/` — the same harness contract over different provider SDKs.
+5. The generated `cordis-surface` regions on subsystem pages record complete event signatures and modes — consult them and the service's TypeScript interface instead of maintaining a second static list.
+6. Dynamic Cordis plugins are in-memory and process-wide: ephemeral by design, so never rely on them for durable composition.
+
+## Connects To
+- **Ch 4 / Ch 5**: Cordis fundamentals and the full API beneath the lifecycle/events/services summarized here.
+- **Ch 7**: capability seams — the built-in three-role families and package links.
+- **Ch 14**: the agent loop consumes `LlmError` codes and reasoning metadata.
+- **Ch 17**: LLM streaming subsystem owns the complete chunk/adapter pipeline.
+- **Ch 11**: tool-authoring reference (nested schemas, policy hooks, UI cards) for the consumer role.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch04-cordis-fundamentals.md

@@ -0,0 +1,129 @@
+# Chapter 4: Cordis Fundamentals (Primer + Tutorial)
+
+## Core Idea
+Cordis is the vendored plugin framework underneath dsh: every capability — tools, LLM adapters, the agent loop itself — is a plugin mounted into a shared `Context`, composed by a `cordis.yml` file. A plugin describes what it contributes (services, events, effects); the config file composes the application.
+
+## Frameworks Introduced
+- **Plugin = `{ name?, inject?, Config?, apply(ctx, config) }`**: three accepted shapes — function plugin (most common), object plugin with `apply` method, class plugin (`Service` subclass).
+  - When to use: function form until you need to expose a service; then `extends Service` with `super(ctx, 'name')`.
+  - How: module exports `apply` (plus optional `name` display metadata); the Loader resolves it from a `cordis.yml` entry `name:` field (module specifier: relative path or npm package).
+- **Service provide/consume**: a named capability one plugin provides (`ctx.<key>`) and others consume via `inject`.
+  - When to use: any shared capability — harness's `ctx.tools`, `ctx.llm`, `ctx.agents` are services.
+  - How: provider mounts a `Service` subclass (`super(ctx, 'greeter')` registers as `ctx.greeter`); consumer declares `export const inject = ['greeter']` — Cordis holds it PENDING until the service exists, so `apply` sees it ready. Load order comes from `inject`, never YAML position.
+- **Typed events via declaration merging**: `declare module '@deepseek-ai/cordis' { interface Events { 'ns/action'(args): void } }` declares name + listener signature; generates no runtime code.
+  - When to use: announce something without knowing listeners (tool results, model requests, approval decisions).
+  - How: `ctx.emit(name, ...args)`; listen with `ctx.on(name, listener)` (an effect — auto-removed on unload). Event names use `namespace/action` convention.
+- **Effect/disposer cleanup model**: every registration is a reversible effect, undone when the owning plugin unloads.
+  - When to use: any resource — Cordis-managed APIs (`ctx.on`, `ctx.plugin`, service/harness registrations like `ctx.tools.register`) are already effects; wrap unmanaged resources (timers, connections, watchers) in `ctx.effect(() => { ...acquire; return () => release })`.
+  - How: disposers run in reverse registration order; async disposers run concurrently — if teardown order matters, keep steps in one disposer and await them there.
+- **Config schema + static declarations**: exported `Config` is both a TS interface and a runtime schema; validated before `apply` runs.
+  - When to use: any `cordis.yml` entry `config:` block.
+  - How: Schemastery `Schema.object({...})` with `.default()`s — `apply` always receives complete, validated config; invalid config → fiber FAILED, loud `ValidationError` (never half-started).
+- **Composition & HMR**: `cordis.yml` entries carry `{id, name, config, inject, disabled}`; HMR = unload + reload a plugin on file save.
+  - When to use: editing plugins or the config file at dev time; `@deepseek-ai/cordis-plugin-hmr` (needs `logger-console` + `timer` plugins, runs under tsx).
+  - How: give entries explicit `id`s — the loader diffs by `id`; an id-less entry gets a fresh generated id each read, so any config edit remounts it as removed-plus-added. `disabled: true` unmounts without deleting the entry. Groups nest entries that load/unload as one unit; `isolate` gives a group its own instance of a service name.
+- **Loader `!!js` expressions**: `@deepseek-ai/cordis-plugin-include` parses `!!js` into expression nodes.
+  - When to use: config values computed at load time (e.g. `greeting: !!js process.env.DEMO_GREETING ?? 'Hello'`) or gating rows by environment.
+  - How: works only inside `config` (evaluated after declared injections activate, against that plugin's context) and in `disabled` (evaluated against loader context at every mount decision). Other metadata stays literal.
+
+## Key Concepts
+- **Context (`ctx`)**: the object `apply` receives; the repository of services through which the plugin registers everything it contributes.
+- **Fiber**: the runtime handle for one loaded plugin instance; `ctx.plugin(fn)` returns it, `fiber.dispose()` resolves after all cleanup.
+- **`inject`**: hard service requirements; re-checked live — if a required service disappears, dependents unload and reload when it returns (this is how service replacement works in config).
+- **PENDING**: legitimate wait state — plugin's `inject` names a service nobody provides; prints nothing, keeps no event loop alive (app exits 0 silently).
+- **Dispatch mode**: part of an event's public contract (`@mode` tag); decides awaitedness, order, and return semantics.
+- **Waterfall veto**: a listener returning without calling `next()` short-circuits the chain (innermost default never runs).
+- **Declaration merging**: TS `declare module` blocks add to `Context`/`Events` interfaces for typechecking only; consumers pull them in via `import type {} from './provider.ts'`.
+- **`ctx.get('name')`**: optional-dependency probe — `undefined` when no provider; the plugin still runs (vs `inject` for hard requirements).
+- **Service namespace**: one flat namespace per application; harness claims plain names (`tools`, `llm`) — prefix your own distinctively.
+
+## Mental Models
+- Think of `cordis.yml` as the application: there is no framework bootstrap code in your file; the dsh base profile is just a longer plugin composition that deployment overlays patch.
+- Use `inject` (not list position) when plugins must start in an order — entries start concurrently; dependencies, not file order, decide startup.
+- Think of a waterfall as around-middleware: each listener wraps the rest of the chain; the value propagates through `next()`'s return.
+- Use `fiber.state` inspection when a plugin "does nothing": iterate `ctx.registry.values()` → `runtime.fibers`, filter `FiberState.PENDING`.
+
+## Anti-patterns
+- **Forgetting `next()` in an observe/annotate waterfall listener**: silently swallows default behavior for everyone downstream — deliberate short-circuit only.
+- **Managing resources outside `ctx.effect()`**: leaks on unload/hot-reload; the pending callback fires on a dead app.
+- **Trusting YAML entry order**: guarantees nothing; unsatisfied `inject` = eternal silent PENDING.
+- **Relying on boot-time crash for unresolvable entries**: a typo'd module specifier is reported through the Cordis logger service — lost before a console exporter watches; check spelling first when a new entry does nothing.
+- **Plain-object `Config` export**: Cordis accepts any Standard Schema validator, but a plain object is not one — validation silently skipped/failed shape.
+- **Separate async disposers needing sequence**: they run concurrently; sequence must live inside one disposer.
+
+## Code Examples
+```ts
+// Three plugin shapes
+export function apply(ctx: Context) {}                       // 1. function
+export const objectPlugin = { name, apply(ctx) {} }          // 2. object
+export class MyService extends Service {                    // 3. class (Service)
+  constructor(ctx: Context) { super(ctx, 'myTutorialService') }
+}
+
+// Service + declaration merging + consumer
+declare module '@deepseek-ai/cordis' {
+  interface Context { greeter: GreeterService }
+  interface Events { 'stats/report'(name: string, count: number): void }
+}
+export const inject = ['greeter']
+export function apply(ctx: Context) { ctx.greeter.greet('world') }
+
+// Optional dependency
+const greeter = ctx.get('greeter')  // undefined-safe probe
+
+// Effect with disposer
+ctx.effect(() => {
+  const timer = setInterval(tick, 200)
+  return () => clearInterval(timer)
+})
+
+// Waterfall listener discipline
+ctx.on('demo/transform', async (input, next) => {
+  if (input.includes('blocked')) return '** blocked **'  // veto
+  return (await next()).toUpperCase()                     // wrap
+})
+
+// Config schema
+export interface Config { greeting: string; targets: string[] }
+export const Config: Schema<Config> = Schema.object({
+  greeting: Schema.string().default('Hello'),
+  targets: Schema.array(String).default(['world']),
+})
+
+// Diagnosing silent plugins
+for (const runtime of ctx.registry.values())
+  for (const fiber of runtime.fibers)
+    if (fiber.state === FiberState.PENDING)
+      console.log(`${fiber.name} is PENDING — a required service is missing`)
+```
+
+## Reference Tables
+Dispatch modes (event's contract, checked by `@mode` in generated catalogs):
+
+| Mode | Call | Awaited? | Order | Return |
+|---|---|---|---|---|
+| `emit` | `ctx.emit(name, ...args)` | No | registration order | none |
+| `parallel` | `await ctx.parallel(...)` | Yes | all concurrent | none |
+| `serial` | `await ctx.serial(...)` | Yes | registration order | first non-null/false/undefined wins, stops rest |
+| `bail` | `ctx.bail(...)` | No | registration order | first bail value |
+| `waterfall` | `ctx.waterfall(name, ...args, next)` | — | around-middleware | outermost listener's return |
+
+Fiber state machine: `PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED`, `LOADING → FAILED` (apply or config validation threw).
+
+Config entry fields: `id` (stable identity for diffing), `name` (module specifier), `config` (validated; `!!js` allowed), `inject`, `disabled` (`!!js` allowed, evaluated per mount decision), groups + `isolate`.
+
+## Key Takeaways
+1. Encapsulate behavior into plugins by domain: tool pipeline events belong to `ctx.tools`, model streaming to `ctx.llm`, agent coordination to `ctx.agents`.
+2. Prefer events for interception and policy; prefer service methods for direct capability calls.
+3. Every registration should have a disposer — return one from `ctx.effect()` or use a Cordis helper that does it for you (`ctx.on`, `ctx.plugin`, `ctx.tools.register`).
+4. `fiber.dispose()` recursively unloads child plugins mounted via `ctx.plugin`; mount-from-code and YAML loading are the same operation.
+5. Silent plugin = check fiber state first; PENDING is the usual answer.
+6. `inject` is live-tracked after load: hot-swapping a provider cleanly restarts all dependents.
+7. `apply` receives `(ctx, config)` — config always complete and validated; reject schema-valid-but-unresolvable references (e.g. missing provider) as early as you can detect them.
+
+## Connects To
+- **Ch 2**: plugin packaging and loading of these Cordis shapes into dsh profiles.
+- **Ch 3**: framework practice — how real dsh plugins use services/events/config composition.
+- **Ch 5**: exact API signatures for every `ctx` member introduced here.
+- **Ch 6**: the architecture map these plugins compose into.
+- **Ch 7**: capability seams — which harness events/waterfalls (e.g. `agent/request`, `approval/request`) to hook.

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch05-cordis-api.md

@@ -0,0 +1,115 @@
+# Chapter 5: Cordis API Reference
+
+## Core Idea
+The exact generated API surface of Cordis core: `Context` is a proxy over the service store whose `extend()/isolate()/intercept()` create scoped child contexts; plugins are loaded as fibers through the registry; events dispatch in five fixed modes. Master the member table and the inherited-vs-isolated visibility rules and you can read any dsh subsystem page's `cordis-surface` regions.
+
+## Frameworks Introduced
+- **Context scoping trio**: `extend(meta?)`, `isolate(name, label?)`, `intercept(name, config)` — all return child contexts without mutating the parent.
+  - When to use: `extend` for extra metadata; `isolate` when two subtrees need different implementations of one service name; `intercept` to merge service-specific config for plugins started below a context.
+  - How: `isolate` joins scopes when passed the same `label` (default: fresh unique symbol); `intercept` config merges ancestor-entries-first via `Service[symbols.resolveConfig]`.
+- **Event dispatch API**: five modes, each with an exact method; mode is fixed per event.
+  - When to use: never pick a mode — the event's declaration owns it; call the matching method.
+  - How: `emit` (sync, returns ignored), `parallel` (await all), `serial` (await in order, first truthy bail wins), `bail` (sync serial), `waterfall` (last arg is innermost `next`; not calling it vetoes). `ctx.on(name, listener, options?)` registers; disposer returns `true` if the listener was still registered.
+- **Fiber lifecycle API**: `ctx.plugin()` returns `Fiber & PromiseLike<Fiber>` — awaiting it settles loading and rethrows config/startup errors.
+  - When to use: `fiber.update(config, noSave?)` for live reconfig; `fiber.restart()` for reload with current config; `fiber.await()` to surface startup errors; `fiber.getEffects()` for diagnostics.
+  - How: `update` runs the `internal/update` waterfall first — update hooks and HMR can veto or replace the restart.
+- **Registry injection**: `ctx.inject(deps, callback)` — shorthand for `ctx.plugin({ inject, apply: callback })`.
+  - When to use: run-once-available logic without a named plugin.
+  - How: callback is unloaded and re-run whenever a required service changes; `deps` is an array (no intercept config) or name→config map (per-service intercept config, normalized by `Inject.resolve`).
+- **Service store primitives**: `get`/`set`/`provide`/`accessor`/`mixin` on the reflect layer backing the proxy.
+  - When to use: `provide` to register a plain value (not a `Service` subclass); `get(name, strict?)` for optional reads; `mixin` to expose service members directly on `ctx`.
+  - How: all are fiber-owned — `provide`/`accessor`/`mixin` unwind with the owning fiber.
+
+## Key Concepts
+- **Context proxy**: normal property reads go through the service resolver; scoping methods never mutate the parent.
+- **`ctx.root`**: the root context every child shares (`@experimental`).
+- **`fiber.uid`**: unique id within the registry; `0` for the root fiber, `null` once disposed.
+- **`fiber.inertia`**: the in-flight load/unload transition promise, if one is running.
+- **`fiber.store`**: snapshot of required service implementations while loaded; `undefined` otherwise.
+- **`Runtime`**: mutable registry record shared by all fibers of one plugin callback — `{name, fibers, callback, Config}`; `callback` is the registry identity key.
+- **`Effect`**: disposer, promise of one, or async iterable yielding several (generator effects register each yielded disposer as produced).
+- **`EffectMeta`**: `{label, children}` tree exposing nested effect labels for diagnostics (e.g. `ctx.on("event")`).
+- **`CordisError`**: framework error with stable code (`INACTIVE_EFFECT`); `ValidationError extends TypeError` aggregates standard-schema issues.
+- **Strict get**: `ctx.get` by default only returns implementations whose providing fiber is currently active.
+
+## Mental Models
+- Think of the scope tree as: parent → `extend`/`isolate`/`intercept` children; service reads/writes below an `isolate(name)` resolve against the new label, so siblings never see each other's overrides.
+- Use `Plugin.Base` metadata (`name`, `Config`, `inject`, `provide`, `intercept`) when authoring any plugin shape — the registry and loaders (including HMR) read it uniformly.
+- Think of `ctx.events`/`ctx.registry`/`ctx.reflect` as ambient handles whose methods are mixed onto `ctx` itself (`ctx.on` → `ctx.events.on`, `ctx.plugin` → registry, `ctx.get` → reflect).
+- Use symbol-keyed static members (`Context.effect/filter/isolate/intercept`, `Service.init/check/config/invoke/extend/tracker/resolveConfig`) as the framework's extension sockets — e.g. `Context.filter` is consulted on every event dispatch, `Service.invoke` makes a service callable like `ctx.logger(name)`.
+
+## Anti-patterns
+- **`instanceof Context` checks**: fails across realms and duplicate cordis copies — use `Context.is(value)` (global-symbol brand).
+- **`ctx.set` on a name you don't provide**: only the providing fiber may set; unprovided name throws. Duplicate `provide` in the same scope also throws (no sibling shadowing).
+- **Registering effects after dispose**: throws `CordisError('INACTIVE_EFFECT')`; invalid effect return shape throws `TypeError`.
+- **Ignoring `EventOptions.global`**: context listener filters apply on every dispatch — a scoped-out listener silently never fires unless `global: true`.
+- **Awaiting `fiber` but expecting config**: the awaited value is the fiber; read validated config from `fiber.config` (updated by `update()`).
+
+## Code Examples
+```ts
+// Scoping
+const child = ctx.extend({ locale: 'en' })            // prototypal inherit, meta shadows
+const scoped = ctx.isolate('shell', myLabel)          // join scopes via same label
+const patched = ctx.intercept('tools', { timeout: 5e3 }) // merged into service config below
+
+// Service store
+ctx.provide('greeter', value): () => void             // returns disposer
+ctx.get('greeter')                                     // strict by default (active fibers only)
+ctx.get('greeter', false)                              // include inactive providers
+ctx.accessor('token', { get, set })                    // computed ctx property
+ctx.mixin('events', ['on', 'emit'])                    // forward members onto ctx
+
+// Events
+ctx.on(name, listener, { prepend: true, global: true })
+ctx.once(name, listener)                               // self-disposes after first call
+await ctx.parallel(name, ...args)                      // Promise<void>, all settled
+await ctx.serial(name, ...args)                        // first truthy bail wins
+ctx.waterfall(name, ...args, innermostNext)            // returns outermost listener's value
+
+// Fibers
+const fiber = ctx.plugin(MyPlugin, config)             // Fiber & PromiseLike<Fiber>
+await fiber                                            // rethrows startup/config errors
+fiber.update(newConfig, true)                          // internal/update waterfall, noSave hint
+fiber.restart()                                        // dispose + reload current config
+
+// Plugin.Base metadata (any shape)
+{ name?: string; Config?: StandardSchemaV1; inject?: Inject;
+  provide?: string | string[]; intercept?: Dict<boolean> }
+```
+
+## Reference Tables
+Context members:
+
+| Member | Kind | Purpose |
+|---|---|---|
+| `ctx.root` | prop | root context (experimental) |
+| `ctx.baseUrl` | prop | resolve relative module specifiers |
+| `ctx.events` / `ctx.registry` / `ctx.reflect` | prop | event bus / plugin registry / service-resolver backing |
+| `ctx.logger` | prop | call `ctx.logger(name)` for named logger |
+| `ctx.fiber` | prop | the fiber owning this context |
+| `ctx.on/once` | method | disposable listener (opts: `prepend`, `global`) |
+| `ctx.emit/parallel/serial/bail/waterfall` | method | the five dispatch modes |
+| `ctx.plugin/inject` | method | load plugin / deps+callback shorthand |
+| `ctx.effect(body, label?)` | method | cleanup-aware effect on current fiber |
+| `ctx.get/set/provide/accessor/mixin` | method | service-store primitives |
+| `ctx.extend/isolate/intercept` | method | child-context scoping |
+| `ctx.timer` (+ `interval/timeout/throttle/debounce`) | mixed | disposable timer helpers (vendor timer) |
+| `ctx.loader` / `ctx.hmr` | service | present under loader / hmr plugins |
+
+Fiber members: `uid`, `ctx`, `config`, `state` (transitions emit `internal/status`), `dispose`, `store`, `inertia`, `name` (nearest named ancestor, else `'root'`); methods `assertActive()`, `effect()`, `getEffects()`, `await()`, `restart()`, `update()`.
+
+Inherited internal events (cordis core + loader/hmr/timer): `internal/plugin` (fiber created), `internal/status` (state change), `internal/service` (binding interception hook, no core producer), `internal/update` (config-update waterfall), `internal/get` / `internal/set` (store read/write waterfalls), `internal/listener`, `internal/dispatch`; `hmr/change`, `hmr/reload`; `exit`; `loader/config-update`, `loader/entry-init`, `loader/partial-dispose`, `loader/patch-context`.
+
+## Key Takeaways
+1. Dispatch mode is per-event and fixed: call the method that matches the declaration — `serial`'s "first truthy wins" is a bail, `waterfall`'s veto is skipping `next()`.
+2. Isolation is label-joinable: two `isolate('name', label)` calls with the same label share one scope; visibility is ancestor/isolate shadowing only.
+3. `provide` is duplicate-hostile within a scope and wakes dependents on unregister — service hot-swap is `dispose` + `provide` under the same name.
+4. `intercept` config merges ancestor-first; declare consumption via `Plugin.Base.intercept` or the object form of `inject` so the context carries the entry.
+5. Dispose semantics: reverse registration order, async disposers awaited but concurrent, double-dispose a no-op.
+6. Diagnostics path: `fiber.getEffects()` → `EffectMeta` label tree; fiber state via `internal/status`; registry enumeration via `ctx.registry.values()` → `runtime.fibers`.
+
+## Connects To
+- **Ch 4**: the conceptual primer for every API listed here.
+- **Ch 7**: which harness events/waterfalls to target with these APIs.
+- **Ch 13**: session-core subsystem services mounted through this registry.
+- **Ch 20**: regenerating/verifying the generated catalog (`gen-cordis-catalog`, `verify-cordis-catalog`).

package/node_modules/better-dsh/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch06-architecture.md

@@ -0,0 +1,109 @@
+# Chapter 6: Architecture & Agent Lifecycle
+
+## Core Idea
+A running dsh is a Cordis plugin tree composed at boot from ordered layers — bundles, then profile/home/CLI patches — with no privileged core: the model adapter, tool registry, session log, and agent loop itself are all replaceable plugins. The agent lifecycle is a durable session-event log projected into model history (`deriveMessages()`), driven by live waterfall events.
+
+## Frameworks Introduced
+- **Profile**: a named composition stored in the Harness home; lists stacked bundles, holds out-of-tree plugins, keeps the user's `cordis.patch.yml`. Ships as templates: `web`, `headless`, `sdk`, `sdk-minimal`, `acp`.
+  - When to use: selecting or composing an application shape without writing a new executable.
+  - How: `dsh --profile <name>`; the profile's `package.json` `dsh.profile` field lists its bundles.
+- **Bundle**: a distribution format for Cordis config rows plus the code they mount — whatever it inserts stays patchable by layers above. `dsh-base` is the shared first layer of `web`/`headless`/`sdk`/`acp` (model adapters, tools, persistence, sandbox and approval policy, settings, credentials, telemetry); `dsh-web-app`, `dsh-headless` (one-shot, no server), `dsh-sdk-app` (SDK JSON-RPC), `dsh-acp-app` (automation-only ACP) add app shells; `dsh-sdk-minimal` is the deliberate exception owning a complete explicit SDK tree without `dsh-base`.
+  - When to use: shipping a stackable layer of plugins + config.
+  - How: `dsh.bundle` in `package.json` points at the bundle's patch file.
+- **Layer order**: empty entry list ← each bundle in listed order ← profile `cordis.patch.yml` ← home-level patch ← `--patch` overlay. A patch targets a row by id, replaces its whole config, or inserts new rows.
+- **Turn/Step model**: a **step** = one model request plus the tools it calls; a **turn** = zero or more steps, opening before its first input is claimed and closing once nothing is owed.
+- **Vendor rescope**: upstream Cordis-family packages vendored under `vendor/` and published as `@deepseek-ai/*`, because every harness package declares the framework as a peer — publishing under upstream names would squat them on the registry.
+
+## Key Concepts
+- **Live patch reload**: custom profiles and `web` reload patches live; `headless`/`sdk`/`sdk-minimal`/`acp` apply all layers once at startup — swapping a one-shot or stdio app's dependencies after it owns work would invalidate that lifecycle.
+- **Launcher invariant**: every supported Node app starts at the `dsh` CLI with a named profile (`dsh web` = the alias for `--profile web`); `verify-application-entrypoints` rejects Node app paths that bypass `dsh`. The TS SDK resolves its same-version `dsh` dependency and selects `sdk`.
+- **Python SDK runtime**: wheel packages the CLI as `deepseek-harness-sdk-runtime-<platform>-<arch>`; client launches `dsh --profile sdk` with an explicit home; minimal example uses `sdk-minimal`; plugins install via `dsh plugin`.
+- **Event domains**: Session events = durable facts on `session/event` (survive reload); Agent events (`agent/*`) = live control/observation carrying an `Agent`; Capability events (`fs/*`, `tools/*`, `telemetry/*`) = policy and adapters at a seam, without importing the loop.
+- **Waterfall vs serial**: `agent/pre-step`, `agent/request`, `llm/stream`, and the three `tools/*` events are waterfalls — listeners must call `next()` to delegate; `agent/turn-stopping` is serial with no `next()`.
+- **Durable vs live streaming**: `agent/assistant-stream` frames are process-local; the loop commits the complete compact timed stream as `assistant/message` or log-only `assistant/attempt` before the committed end frame. Replay reads durable settlements only; process loss before settlement leaves no durable attempt stream.
+- **Model-visible means logged**: anything reaching a model request must be reconstructable from the log (runtime invariant) — new model-visible input ⇒ new session event via `SessionEventMap`, rendered from the log.
+- **Session format generations**: v0 `session.jsonl[.zstd]`; v1+ lowercase `session.vN.jsonl[.zstd]`; committed generation paths are never renamed, replaced, or deleted. `open` picks the highest canonical generation, refuses future versions, or composes the adjacent migration chain in memory, validates, and exclusively publishes the version-named successor beside the unchanged source; each migration package owns exactly one `vN -> vN+1` step.
+- **Projection seam**: `ctx.sessionProjections` — registered units fold committed events; hosts read typed `stateOf()`, carriers batch cropped `snapshot()` views; a host reader requires the service at activation or fails explicitly. The loop registers shared `turnBoundary` state.
+
+## Mental Models
+- Use `--dump-config` as the map of what your machine boots: any row it prints can be replaced by a patch — later layers restate whole rows by id, never merge fields.
+- Think of the turn as a claims loop: one inbox, wake-on-message; next-step input is claimed per step, and injected context waits in the inbox until another message wakes the driver.
+- Treat the session log as the only source of model context: fork, resume, transcripts, telemetry, and persistence all derive from durable settlements; live UI incrementality comes from `agent/assistant-stream`.
+
+## Anti-patterns
+- **Patching a privileged core**: there is none — mount a plugin beside the others; registrations are effects that unwind when their plugin unloads.
+- **Adding a second executable or inline application tree**: not an application launcher; the entrypoint verification gate rejects it.
+- **New model-visible input without a session event**: breaks the log-reconstructability invariant.
+- **Rebuilding a pre-step decision instead of spreading it**: `{ ...decision, messages }` — otherwise a downstream `startsRequestSeries` declaration is lost. A rejected or empty first claim still closes a durable turn that spent no step, so the log records the attempt.
+- **Renaming vendored imports by hand**: `scripts/rescope-vendor.ts` owns the mapping; hand edits drift from it.
+
+## Code Examples
+```sh
+dsh --profile web --dump-config   # print the booted plugin tree; every row is patchable
+```
+Turn-flow spine (D = durable session event, L = live):
+```text
+turn/start(D) → claim next-step input + one queued message →
+agent/pre-step(L; reject | enter(messages, startsRequestSeries?)) →
+step/start(D) → user/message(D) → agent/request(L) → llm/stream(L) →
+agent/assistant-stream start/chunk*/end(L) →
+assistant/message(D) | assistant/attempt(D) →
+tool/call*(D) → tools/pre-execute → tools/execute → tools/post-execute → tool/result*(D) →
+step/end(D) → agent/turn-stopping(L; serial, no next()) → turn/end(D)
+```
+Rescope tooling:
+```sh
+pnpm run rescope-vendor            # report what would change
+pnpm run rescope-vendor --apply    # rewrite every reference
+pnpm run rescope-vendor:check      # assert post-state; runs in the hygiene gate
+pnpm run rescope-vendor --apply --reverse   # return to upstream names
+```
+Import rename: `import { Context } from 'cordis'` → `'@deepseek-ai/cordis'`; `declare module 'cordis'` → `declare module '@deepseek-ai/cordis'`. After upstream sync: re-apply rescope, then `pnpm install`, `pnpm run gen-third-party-notices`, `pnpm run verify-translation-pairing --write`.
+
+## Reference Tables
+Core packages:
+| Package | Owns | `ctx` key |
+|---|---|---|
+| `core/session` | append-only `SessionEvent` log + store | `ctx.sessions` |
+| `core/system-prompt` | prompt-section + tool-schema assembly | `ctx.systemPrompt` |
+| `core/tools` | tool registry + guarded execution | `ctx.tools` |
+| `core/agent` | `Agent` interface, registry, `agent/*` events | `ctx.agents` |
+| `core/agent-loop` | default driver | `ctx.agentLoop` |
+| `core/scope` | per-agent scoped registration | library, no key |
+| `llm/llm` | stream vocabulary + adapter seam | `ctx.llm` |
+| `webhook/webhook` | authenticated dispatch + Session creation | `ctx.webhookRuntime` |
+
+Where new behavior goes (selected):
+| Goal | Mechanism |
+|---|---|
+| Model provider | adapter on `ctx.llm` |
+| Model-facing capability | register on `ctx.tools`; schema joins prompt assembly |
+| Per-session capability set | agent preset; a service row there needs an `isolate` realm |
+| Shell execution | `ctx.shell` backend; local one spawns through `ctx.subprocess` |
+| Intercept request/tool/turn | `agent/*` or `tools/*` event; `agent/turn-stopping` stops a turn |
+| Model-facing context | `agent.inject()`; lands in the next admitted request |
+| Durable session state | extend `SessionEventMap`; render and replay from the log |
+| Fork at turn boundary | `ctx.agents.create({ sessionId, seed, meta: { parentSession, seedLength } })` — only agent-loop-published sessions persist |
+| New session backend | implement `SessionPersistence` (`create`/`open`/`stat`/`list`/`export`) |
+| Scope to one agent | that agent's `agent.ctx` |
+
+Vendored name mapping (subpath exports keep their path): `cordis` → `@deepseek-ai/cordis` (4.0.0-rc.7) · `cosmokit` (1.8.1) · `schemastery` (3.18.0) · `@cordisjs/plugin-loader` → `@deepseek-ai/cordis-plugin-loader` (1.0.0-rc.5) · plugin-include/group/timer/hmr/logger-console (1.0.4/1.0.0/1.1.2/1.0.15/1.0.0) → `@deepseek-ai/cordis-plugin-*`. Never touched: dependency ranges (key changes, range stays), the `cordis:` builtin prefix, the `cordis.yml` family, upstream runtime identifiers (`Symbol.for('schemastery')`, `vendor:`), prose outside `docs/`.
+
+Doc graph atlas (relationships the catalogs don't show; exact signatures live in subsystem pages): module-graph and tool-catalog (`generated`); capability-seams, dsh-base composition, event-producer-consumer (`hybrid generated`); agent-lifecycle and tool-execution-pipeline (`curated`). Regenerate `pnpm run gen-doc-graphs`; verify `pnpm run verify-doc-graphs`.
+
+## Key Takeaways
+1. Extend by mounting plugins and patching rows by id — never by forking a core; later layers restate whole rows.
+2. Inspect before composing: `--dump-config` prints every replaceable row your machine boots.
+3. Route facts by domain: durable facts → session events; live control → `agent/*`; capability policy → capability events.
+4. Waterfall listeners must call `next()`; pre-step decisions are authoritative — spread them, don't rebuild them.
+5. Anything model-visible must be logged: extend `SessionEventMap` and render from the log; live streams are transient.
+6. Don't rely on patch reload under one-shot profiles (`headless`/`sdk`/`sdk-minimal`/`acp` apply layers once).
+7. After a vendor sync, rescope via script and run the regenerations it prints.
+
+## Connects To
+- **Ch 4**: Cordis primitives (Context, Service, events) the plugin tree is built from.
+- **Ch 7**: the full seam catalog behind "where new behavior goes".
+- **Ch 8**: tool-execution pipeline and turn-flow internals.
+- **Ch 13/14**: session and agent-loop subsystems in depth.
+- **Ch 2**: plugin-basics mechanics of bundles and patch rows.
+- **Ch 20**: dev gates (`verify-application-entrypoints`, `rescope-vendor:check`).

package/node_modules/better-dsh/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.