super-dsh 0.3.0-c → 0.3.0-d

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

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

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

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

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

@@ -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.