Merge remote-tracking branch 'origin/master' into codex/truncated-design

# Conflicts:
#	docs/capability-seams.md
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	docs/rfc/INDEX.md
#	docs/tool-catalog.md
#	examples/acp-agent/README.md
#	packages/README.md
#	packages/bash/bash/README.md
#	packages/core/tools/tests/gen-tool-catalog.spec.ts
#	packages/support/acp-snapshot/src/harness.ts
#	pnpm-lock.yaml
#	scripts/gen-doc-graphs.ts
#	scripts/gen-tool-catalog.ts
#	scripts/type-equiv.manifest.json

packages/cordis/tool-cordis/src/fiber-state.ts

@@ -0,0 +1,39 @@
+/**
+ * Runtime mirror of the cordis `FiberState` const enum plus human-readable
+ * labels, shared by the mount lifecycle (state reporting) and the inspect
+ * renderers (plugin-list and mount-table labels).
+ *
+ * Cordis exposes `FiberState` as a `const enum`: there is no runtime object for
+ * Node's type-stripping runner to import, so the members are mirrored here as
+ * values — each typed (via the type-only import) as the cordis enum member it
+ * mirrors, so enum-typed reads like `fiber.state` compare against them under a
+ * shared enum type. Source of truth: vendor/cordis/src/fiber.ts (pinned; drift
+ * only happens through a deliberate vendor sync).
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/fiber-state
+ */
+
+import type { FiberState as FiberStateEnum } from 'cordis'
+
+/** Value mirror of the cordis `FiberState` const enum (see the module doc for why a mirror exists). */
+export const FiberState = {
+  PENDING: 0 as FiberStateEnum.PENDING,
+  LOADING: 1 as FiberStateEnum.LOADING,
+  ACTIVE: 2 as FiberStateEnum.ACTIVE,
+  FAILED: 3 as FiberStateEnum.FAILED,
+  DISPOSED: 4 as FiberStateEnum.DISPOSED,
+  UNLOADING: 5 as FiberStateEnum.UNLOADING,
+} as const
+
+/** The cordis `FiberState` enum type, re-exported so mirror consumers need one import. */
+export type FiberState = FiberStateEnum
+
+/** Human-readable label for each {@link FiberState}, keyed by member (inlining-safe — no reverse mapping). */
+export const STATE_LABELS: Record<FiberState, string> = {
+  [FiberState.PENDING]: 'pending',
+  [FiberState.LOADING]: 'loading',
+  [FiberState.ACTIVE]: 'active',
+  [FiberState.FAILED]: 'failed',
+  [FiberState.DISPOSED]: 'disposed',
+  [FiberState.UNLOADING]: 'unloading',
+}

packages/cordis/tool-cordis/src/guard.ts

@@ -0,0 +1,447 @@
+/**
+ * The registration boundary between sandboxed mount code and the real runtime:
+ * SchemaSpec normalization + validation with teaching errors, the
+ * marker-guarded `harness.defineTool` / `harness.registerTool` pair, the
+ * SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives in place of the
+ * real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox
+ * return values with.
+ *
+ * The façade is a WHITELIST, not a pass-through proxy. Mount code needs to do
+ * exactly four things — register a tool, listen to an event, provide a service,
+ * call an injected service (timers included) — so the façade exposes only those
+ * verbs and the injected services, each object-valued service individually
+ * wrapped (a primitive provided value passes through as-is — see
+ * {@link sandboxContext}). Every framework plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`,
+ * `events`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) is
+ * DENIED with a teaching error rather than passed through. This closes an
+ * entire escape class at once: a pass-through proxy that only special-cased
+ * `ctx.tools` still handed back the raw context through `ctx.root`,
+ * `ctx.extend()`, or a service instance's `.ctx`, and mount code could then
+ * `ctx.root.tools.register({…})` to bypass the marker check and host-realm
+ * normalization — a raw vm-realm result then errors a real agent turn at the
+ * session-log plainness check. The whitelist has no such hole: there is no
+ * context-valued member to reach, and any injected-service method that returns
+ * a `Context` is rejected (harness services never do — see {@link denyContext}).
+ *
+ * Two realm facts drive the tool path. Objects built inside the vm carry the vm
+ * realm's `Object.prototype`, and the session log's append-time plainness check
+ * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects
+ * foreign-realm data — so every dynamic tool's `execute` return is JSON
+ * round-tripped into the host realm and shape-checked against the two
+ * `ToolExecuteReturn` forms before it reaches the registry (the registry
+ * trusts the shape blindly — it spreads `result.content`, so an unvalidated
+ * `{ content: 'ok' }` would enter the session log as `['o','k']` and silently
+ * corrupt the next model request), and the schema itself is rebuilt as fresh
+ * host-realm objects. And a malformed tool
+ * schema must fail at REGISTRATION, not when a later request assembles it — so
+ * dynamic tool registration accepts only definitions produced by the sandbox's
+ * `harness.defineTool`, which normalizes `parameters` up front.
+ *
+ * Normalize, don't lecture, where the input has exactly one meaning: models
+ * write the JSON-Schema dialect by strong prior (the `{ type: 'object',
+ * properties, required: […] }` wrapper, `type: 'integer'`, `required: false`),
+ * and each rejection costs a model turn — so those convert to the SchemaSpec
+ * DSL silently, and only genuinely meaningless input (an unknown type, a
+ * non-boolean `required`) is rejected, with the error enumerating the valid
+ * vocabulary.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/guard
+ */
+
+import { Context } from 'cordis'
+import type { Plugin } from 'cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools'
+
+const DYNAMIC_TOOL = Symbol('tool-cordis.dynamic-tool')
+const SCHEMA_TYPES = new Set<unknown>(['string', 'number', 'boolean', 'object', 'array'])
+const VALID_TYPES = '\'string\' | \'number\' | \'boolean\' | \'object\' | \'array\''
+
+type DynamicToolDefinition = ToolDefinition & { [DYNAMIC_TOOL]: true }
+type DynamicToolMarker = { [DYNAMIC_TOOL]?: unknown }
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Object.prototype.toString.call(value) === '[object Object]'
+}
+
+/**
+ * Normalize a sandbox-provided `parameters` value into a fresh host-realm
+ * SchemaSpec. Accepts the DSL directly, or the JSON-Schema-style
+ * `{ type: 'object', properties, required: […] }` wrapper models write by
+ * prior — the wrapper unwraps and its `required` array becomes per-property
+ * flags (see the module doc).
+ */
+function normalizeSchemaSpec(value: unknown, path = 'parameters'): Record<string, unknown> {
+  if (!isPlainRecord(value)) {
+    throw new Error(`harness.defineTool ${path} must be a SchemaSpec object`)
+  }
+  let entries = value
+  const requiredNames = new Set<unknown>()
+  if (value.type === 'object' && isPlainRecord(value.properties)) {
+    if (Array.isArray(value.required)) {
+      for (const name of value.required) requiredNames.add(name)
+    }
+    entries = value.properties
+  }
+  const spec: Record<string, unknown> = {}
+  for (const [key, prop] of Object.entries(entries)) {
+    spec[key] = normalizeSchemaProp(prop, `${path}.${key}`, requiredNames.has(key))
+  }
+  return spec
+}
+
+/** Normalize one property: `integer` → `number`, `required: false` → absent, nested wrappers unwrapped recursively. */
+function normalizeSchemaProp(value: unknown, path: string, forceRequired = false): Record<string, unknown> {
+  if (!isPlainRecord(value)) {
+    throw new Error(`harness.defineTool ${path} must be a SchemaSpec property object`)
+  }
+  const type = value.type === 'integer' ? 'number' : value.type
+  if (!SCHEMA_TYPES.has(type)) {
+    throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES} (got ${JSON.stringify(value.type)})`)
+  }
+  // On an object property a JSON-Schema-style `required` ARRAY names required
+  // children (handled by the nested unwrap below); everywhere else `required`
+  // must be a boolean, and `false` simply reads as optional.
+  const nestedRequiredArray = type === 'object' && Array.isArray(value.required)
+  if (value.required !== undefined && typeof value.required !== 'boolean' && !nestedRequiredArray) {
+    throw new Error(`harness.defineTool ${path}.required must be a boolean when present`)
+  }
+  const prop: Record<string, unknown> = { type }
+  if (forceRequired || value.required === true) prop.required = true
+  if (typeof value.description === 'string') prop.description = value.description
+  if (Array.isArray(value.enum)) prop.enum = [...value.enum as unknown[]]
+  if (value.default !== undefined) prop.default = value.default
+  if (value.properties !== undefined) {
+    if (type !== 'object') {
+      throw new Error(`harness.defineTool ${path}.properties is only valid for type "object"`)
+    }
+    // Re-wrap so the nested unwrap applies a nested `required` array too.
+    prop.properties = normalizeSchemaSpec(
+      { type: 'object', properties: value.properties, required: value.required },
+      `${path}.properties`,
+    )
+  }
+  if (value.items !== undefined) {
+    if (type !== 'array') {
+      throw new Error(`harness.defineTool ${path}.items is only valid for type "array"`)
+    }
+    prop.items = normalizeSchemaProp(value.items, `${path}.items`)
+  }
+  return prop
+}
+
+function markDynamicTool(tool: ToolDefinition): DynamicToolDefinition {
+  Object.defineProperty(tool, DYNAMIC_TOOL, { value: true })
+  return tool as DynamicToolDefinition
+}
+
+function assertDynamicTool(tool: unknown): asserts tool is DynamicToolDefinition {
+  if (!isPlainRecord(tool) || (tool as DynamicToolMarker)[DYNAMIC_TOOL] !== true) {
+    throw new Error('dynamic tool registration must use a tool returned by harness.defineTool(...)')
+  }
+}
+
+/**
+ * Structurally a content block, checked AFTER the JSON round-trip: a plain
+ * object carrying a string `type` tag. Deliberately nothing deeper — the
+ * ContentBlock union is merge-extensible (an unknown tag must pass), and every
+ * downstream consumer dispatches on `type` and falls through unknowns.
+ */
+function isContentBlockShape(value: unknown): boolean {
+  return isPlainRecord(value) && typeof value.type === 'string'
+}
+
+/**
+ * How much of an invalid execute return the teaching error echoes back — a
+ * huge blob would burn the model turn the error is trying to save.
+ */
+const RETURN_PREVIEW_LIMIT = 120
+
+/**
+ * Compact JSON preview of an invalid execute return for the teaching error
+ * (`String(…)` for the un-stringifiable undefined case), truncated to
+ * {@link RETURN_PREVIEW_LIMIT}.
+ */
+function describeReturn(value: unknown): string {
+  // JSON.stringify is TYPED as always returning string, but it yields
+  // undefined for an undefined input (the routed forgot-return case) — the
+  // assertion widens the type back to the runtime truth.
+  const json = JSON.stringify(value) as string | undefined
+  if (json === undefined) return String(value)
+  return json.length > RETURN_PREVIEW_LIMIT ? `${json.slice(0, RETURN_PREVIEW_LIMIT)}…` : json
+}
+
+/**
+ * Validate a round-tripped `execute` return against the two shapes
+ * {@link ToolExecuteReturn} allows: an ARRAY of content blocks, or
+ * `{ content: blocks, meta? }`. The registry trusts the shape blindly — it
+ * spreads `result.content`, so an unvalidated `{ content: 'ok' }` would enter
+ * the session log as `['o','k']` and silently corrupt the next model request —
+ * so a wrong shape fails THIS call with a teaching error instead.
+ */
+function assertExecuteReturn(value: unknown): ToolExecuteReturn {
+  if (Array.isArray(value) && value.every(isContentBlockShape)) {
+    return value as ToolExecuteReturn
+  }
+  if (isPlainRecord(value) && Array.isArray(value.content) && value.content.every(isContentBlockShape)) {
+    return value as ToolExecuteReturn
+  }
+  throw new Error(
+    `execute returned ${describeReturn(value)} — a tool's execute must return an ARRAY of content blocks, never a bare string:\n`
+    + '  ✓ return [{ type: \'text\', text: someString }]\n'
+    + '  ✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }',
+  )
+}
+
+/**
+ * The `harness.defineTool` handed into the sandbox: the real DSL, with
+ * `parameters` normalized into a fresh host-realm SchemaSpec (JSON-Schema
+ * wrapper unwrapped, `integer` mapped, `required: false` dropped) and the
+ * tool's `execute` return normalized into the host realm via a JSON round-trip
+ * (see the module doc). The round-trip projects the return onto exactly what
+ * the log would durably store, and {@link assertExecuteReturn} then vets that
+ * projection — so a non-JSON-serializable OR wrong-shape return surfaces as
+ * that one call's teaching error instead of poisoning the turn.
+ * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper.
+ * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts.
+ */
+export function sandboxDefineTool(options: Parameters<typeof defineTool>[0]): ToolDefinition {
+  const parameters = normalizeSchemaSpec((options as { parameters?: unknown }).parameters)
+  const tool = defineTool({ ...options, parameters } as Parameters<typeof defineTool>[0])
+  const execute = tool.execute.bind(tool)
+  return markDynamicTool({
+    ...tool,
+    async execute(args, exec) {
+      // JSON.stringify yields NO JSON for an undefined (or function/symbol)
+      // return despite its string-typed signature — route that into
+      // assertExecuteReturn's teaching error rather than letting JSON.parse
+      // throw its cryptic '"undefined" is not valid JSON'.
+      const json = JSON.stringify(await execute(args, exec)) as string | undefined
+      return assertExecuteReturn(json === undefined ? undefined : JSON.parse(json) as unknown)
+    },
+  })
+}
+
+/**
+ * The `harness.registerTool` handed into the sandbox: registers a
+ * marker-verified dynamic tool on the given context's registry.
+ * @param ctx - the (guarded) context whose `tools` service receives the tool.
+ * @param tool - a definition produced by {@link sandboxDefineTool}; anything else is rejected.
+ * @returns the registry disposer for the registration.
+ */
+export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void {
+  assertDynamicTool(tool)
+  return ctx.tools.register(tool)
+}
+
+/**
+ * The verbs a mounted plugin may reach through the sandbox `ctx` façade,
+ * beyond its injected services. `on`/`once` observe events, `provide` exposes
+ * a service to other mounts, and the timer helpers schedule work — each a
+ * fiber effect that unwinds on unmount. Everything else on a real cordis `ctx`
+ * is framework plumbing and is denied. Forwarded LAZILY: the timer helpers are
+ * mixin accessors that throw `without inject` when read on a plugin that did
+ * not inject `timer`, so the façade reads `ctx[verb]` only at call time — the
+ * plugin that never touches a timer never trips that, and one that does gets
+ * cordis's own inject error at the call site.
+ */
+const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce'])
+
+/**
+ * The tool-registry façade: `register` (marker-guarded) plus READ-ONLY
+ * metadata (`schemas`, and `get` returning a schema view, never the live
+ * `ToolDefinition`). Exposing the raw definition would hand mount code the
+ * tool's `execute` function, letting it call another tool directly and bypass
+ * `ToolRegistry.execute` — the pre/post-execute waterfall (permission gates,
+ * accounting) and result normalization. So `get` returns the same
+ * name/description/parameters view as `schemas()`, and nothing invocable.
+ */
+function sandboxTools(ctx: Context): Record<string, unknown> {
+  return {
+    register: (tool: unknown): (() => void) => sandboxRegisterTool(ctx, tool),
+    schemas: () => ctx.tools.schemas(),
+    get: (name: string) => ctx.tools.schemas().find(schema => schema.name === name),
+  }
+}
+
+/**
+ * Reject any injected-service return that is a cordis `Context`. Harness
+ * services return data, never a context; a value that is one would be a
+ * fresh, unguarded handle back into the runtime — the exact escape the façade
+ * exists to close — so it fails loud instead of reaching sandbox code.
+ */
+function denyContext(value: unknown, service: string): unknown {
+  if (value instanceof Context) {
+    throw new Error(
+      `service "${service}" returned a cordis Context, which the sandbox does not expose. `
+      + 'Operate through your own plugin ctx (ctx.on / ctx.provide / ctx.tools.register) '
+      + 'and the services you inject — never another context.',
+    )
+  }
+  return value
+}
+
+/**
+ * Wrap an injected service so its methods forward to the real instance but
+ * their return values pass through {@link denyContext}. Non-function members
+ * (plain data) pass through as-is; a returned Promise is guarded on resolve.
+ */
+function guardedService(service: object, name: string): unknown {
+  return new Proxy(service, {
+    get(target, prop) {
+      const value = Reflect.get(target, prop, target) as unknown
+      if (typeof value !== 'function') return denyContext(value, name)
+      return (...args: unknown[]): unknown => {
+        const result = Reflect.apply(value, target, args) as unknown
+        if (result instanceof Promise) return result.then(v => denyContext(v, name))
+        return denyContext(result, name)
+      }
+    },
+  })
+}
+
+/**
+ * The service names a plugin declared in `inject`, as a lookup set. Whatever
+ * declaration style the plugin used — an `inject: ['bash', 'tools']` array or
+ * the `{ required, optional }` object form — cordis resolves it into a single
+ * name-keyed map on the fiber before `apply` runs (`{ bash: null, tools: null }`),
+ * so the gate just reads that map's keys. A mount may reach only the services
+ * it declared — that is what lets cordis park the mount when a declared
+ * provider unmounts.
+ */
+function declaredInjects(ctx: Context): Set<string> {
+  return new Set(Object.keys(ctx.fiber.inject))
+}
+
+/**
+ * The sandbox context façade handed to a mounted plugin's `apply` in place of
+ * the real `ctx`. A whitelist (see the module doc): the registration/eventing
+ * verbs, the timer helpers, a guarded `tools`, and injected services resolved
+ * through a guarded `get` / property access. A service is reachable only if the
+ * plugin DECLARED it in `inject` — an undeclared service is denied even when a
+ * global provider exists, so cordis's activation/unload semantics (park the
+ * mount when a declared provider goes away) actually bind. Every
+ * framework-plumbing member is denied with a teaching error; there is no
+ * context-valued member to reach.
+ */
+function sandboxContext(ctx: Context): Context {
+  const tools = sandboxTools(ctx)
+  const declared = declaredInjects(ctx)
+  // A framework member or an undeclared service — distinguish the two so the
+  // error teaches the right fix (declare it in inject vs it is withheld).
+  const denyRead = (prop: string): never => {
+    if (ctx.get(prop) !== undefined) {
+      throw new Error(
+        `service "${prop}" is not injected. Declare it: inject: ['${prop}', …] on your plugin, `
+        + 'so cordis parks this mount if the provider is later unmounted.',
+      )
+    }
+    throw new Error(
+      `sandbox ctx does not expose "${prop}". Available: ctx.tools.register / ctx.on / ctx.provide / `
+      + 'the timer helpers (ctx.setTimeout, ctx.interval, …) and any service you declared in inject. '
+      + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.',
+    )
+  }
+  // Read a service for either access path (property or `get`). `tools` is the
+  // façade's own surface. An UNDECLARED name is denied with the teaching
+  // error; a DECLARED one resolves to the guarded service. A declared inject
+  // is required in cordis (the fiber only activates once every declared
+  // service is live), so at `apply`/`execute` time `ctx.get(name)` is present
+  // for a declared name — no undefined case to handle here. `provide()`
+  // accepts ANY value though (cross-mount composition advertises
+  // `ctx.provide('name', value)`), so a primitive or null value passes
+  // through unwrapped: Proxy throws on a non-object target, and only an
+  // object can carry a method that hands back a Context.
+  const readService = (name: string): unknown => {
+    if (name === 'tools') return tools
+    if (!declared.has(name)) return denyRead(name)
+    const service = denyContext(ctx.get(name), name)
+    if (service === null || (typeof service !== 'object' && typeof service !== 'function')) return service
+    return guardedService(service, name)
+  }
+  const get = (name: string): unknown => readService(name)
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (prop === 'tools') return tools
+      if (prop === 'get') return get
+      if (typeof prop !== 'string') return undefined
+      // Lazy verb forwarder — reads `ctx[verb]` only when called, so a plugin
+      // that never uses a timer never triggers the timer mixin's inject check
+      // (cordis raises its own "without inject" error there for undeclared timer use).
+      if (CTX_VERBS.has(prop)) {
+        return (...args: unknown[]): unknown => {
+          const method = ctx[prop as keyof Context]
+          return Reflect.apply(method as (...a: unknown[]) => unknown, ctx, args)
+        }
+      }
+      return readService(prop)
+    },
+    // A façade is not the real ctx; block writes rather than let mount code
+    // stash state on a throwaway object and think it persisted.
+    set(_target, prop) {
+      throw new Error(`sandbox ctx is read-only; cannot assign "${String(prop)}"`)
+    },
+    // `in` reflects reachability: the façade surface plus DECLARED services
+    // (whether or not currently live). Does not resolve/wrap — no throw.
+    has: (_target, prop) => prop === 'tools' || prop === 'get'
+      || (typeof prop === 'string' && (CTX_VERBS.has(prop) || declared.has(prop))),
+  }) as unknown as Context
+}
+
+/**
+ * Narrow an arbitrary sandbox return value to a mountable cordis plugin: a
+ * function, or an object with an `apply` function. (A bare function passes the
+ * first arm, so the object arm never sees `Function.prototype.apply`.)
+ * @param value - whatever the mount code returned.
+ * @returns whether the value is mountable via `ctx.plugin`.
+ */
+export function isPlugin(value: unknown): value is Plugin {
+  if (typeof value === 'function') return true
+  return typeof value === 'object' && value !== null
+    && typeof (value as { apply?: unknown }).apply === 'function'
+}
+
+/**
+ * Wrap a plugin so its `apply` receives the sandbox context façade instead of
+ * the real `ctx` (see {@link sandboxContext} and the module doc). Both
+ * function-form and object-form plugins go through the same wrap; the plugin's
+ * own `inject` declaration is preserved (cordis reads it from the plugin
+ * object, and pending/active gating happens on the real fiber before `apply`
+ * runs), so cross-mount provide/inject works unmodified.
+ *
+ * `ctx.effect(customCleanup)` is deliberately absent from the façade for now —
+ * `on` / `provide` / `tools.register` cover every mount seen so far, and each
+ * is already a fiber effect. FIXME(sandbox-effect): expose a guarded `effect`
+ * once a real mount needs a bespoke disposer.
+ * @param plugin - the plugin the mount code returned.
+ * @returns an equivalent plugin whose `apply` sees the sandbox context façade.
+ */
+export function guardedPlugin(plugin: Plugin): Plugin {
+  if (typeof plugin === 'function') {
+    const functionPlugin = plugin as (ctx: Context, config?: unknown) => unknown
+    return {
+      name: pluginName(plugin),
+      apply(ctx: Context, config?: unknown) {
+        return functionPlugin(sandboxContext(ctx), config)
+      },
+    }
+  }
+  const objectPlugin = plugin as { apply(ctx: Context, config?: unknown): unknown }
+  return {
+    ...plugin,
+    apply(ctx: Context, config?: unknown) {
+      return objectPlugin.apply(sandboxContext(ctx), config)
+    },
+  }
+}
+
+/**
+ * Display name for a mounted plugin: its `name` property, else anonymous.
+ * @param plugin - the plugin the mount code returned.
+ * @returns the human-readable name used in mount results and inspect output.
+ */
+export function pluginName(plugin: Plugin): string {
+  const named = (plugin as { name?: unknown }).name
+  if (typeof named === 'string' && named.length > 0) return named
+  return '<anonymous>'
+}

packages/cordis/tool-cordis/src/index.ts

@@ -0,0 +1,236 @@
+/**
+ * The self-referential cordis toolset: three model-facing tools that let the
+ * agent inspect and MODIFY the live cordis runtime it is running inside.
+ *
+ * - `cordis_inspect` — read-only: provided services, the flat plugin list
+ *   with lifecycle states, registered tools, the dynamic mounts, and the
+ *   catalog-backed `api` / `events` references.
+ * - `cordis_mount` — evaluate model-written code in a `node:vm` sandbox; the
+ *   code returns a cordis plugin, which is mounted as a child of a dedicated
+ *   `cordis-dynamic` group fiber and tracked under an id (`dyn-1`, `dyn-2`, …).
+ * - `cordis_unmount` — dispose one dynamic mount by id, awaiting quiescence.
+ *
+ * Everything the model's plugin registers (listeners via `ctx.on`, tools via
+ * `harness.registerTool`, services via `ctx.provide`) is an effect on the
+ * dynamic fiber, so unmounting — or disposing this plugin itself (HMR) — cleans
+ * it all up through the ordinary cordis lifecycle. The group fiber exists
+ * exactly so the dynamic mounts form ONE subtree, disposed as a unit with
+ * this plugin. Design home:
+ * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
+ *
+ * The vm sandbox guards against ACCIDENTAL global pollution only, and the `ctx`
+ * a mounted plugin's `apply` receives is a WHITELIST façade (register a tool,
+ * observe events, provide/consume services, use timers — framework internals
+ * withheld; see the guard module). Neither is a security boundary: the verbs
+ * the façade DOES expose reach the real runtime unsandboxed (a mounted tool can
+ * shell out through `ctx.bash`), so a deployment loads this plugin as
+ * deliberately as it grants a bash tool. Design home:
+ * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md.
+ *
+ * Plugin export shape: named exports, NO default. The cordis Loader's
+ * `unwrapExports` does `exports.default ?? exports`, so a stray default would
+ * collapse the module to the bare `apply` and drop `inject`, crashing at load
+ * (see docs/postmortem/0001).
+ *
+ * @module @deepseek-ai/dsh-tool-cordis
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { STATE_LABELS } from './fiber-state.ts'
+import { isPlugin, pluginName } from './guard.ts'
+import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools } from './inspect.ts'
+import { missingServices, mountDynamic } from './mount.ts'
+import type { DynamicMount } from './mount.ts'
+import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts'
+import { createSandbox, evaluateMountCode } from './sandbox.ts'
+
+export const name = 'tool-cordis'
+export const inject = ['tools']
+
+/** Config for the tool-cordis plugin: the sandbox evaluation bound. */
+export interface Config {
+  /**
+   * Milliseconds the SYNCHRONOUS portion of mount code may run in the vm
+   * before evaluation is aborted (default 5000). An async body escapes this
+   * bound — see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance.
+   */
+  vmTimeoutMs?: number
+}
+
+/** Schemastery validator for {@link Config}: `vmTimeoutMs` must be at least 1 (defaults to 5000). */
+export const Config: z<Config> = z.object({
+  vmTimeoutMs: z.number().min(1).default(5000),
+})
+
+/** {@link Config} with every defaulted field present, as schemastery resolves it at load. */
+type ResolvedConfig = Required<Config>
+
+/**
+ * Mount the three cordis tools on `ctx.tools` and create the `cordis-dynamic`
+ * group fiber every dynamic mount hangs under.
+ * @param ctx - the plugin context (`tools` injected).
+ * @param config - the schemastery-resolved {@link Config}.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const { vmTimeoutMs } = config as ResolvedConfig
+  // The one group fiber every dynamic mount hangs under. Mounted here (a child
+  // of this plugin's fiber) so disposing tool-cordis cascades over the whole
+  // dynamic subtree — the ordinary parent→child fiber lifecycle, nothing extra.
+  const group = ctx.plugin({ name: 'cordis-dynamic', apply: () => {} })
+
+  const mounts = new Map<string, DynamicMount>()
+  let nextId = 1
+
+  ctx.tools.register(defineTool({
+    name: 'cordis_inspect',
+    description:
+      'Inspect the live cordis runtime that is running THIS agent. Read-only. '
+      + 'Sections: `services` (every provided ctx service and the plugin fiber that owns it), '
+      + '`plugins` (a flat list of the loaded plugins with their lifecycle states), '
+      + '`tools` (the model-facing tools currently registered, i.e. what you can call), '
+      + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), '
+      + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), '
+      + '`events` (every harness event with its dispatch mode and exact signature — pick listener targets here). '
+      + 'Omit `what` to get all six sections.',
+    parameters: {
+      what: {
+        type: 'string',
+        enum: ['services', 'plugins', 'tools', 'dynamic', 'api', 'events'],
+        description: 'Limit the report to one section. Omit for all sections.',
+      },
+    },
+    execute(args): Promise<{ type: 'text'; text: string }[]> {
+      const sections: [heading: string, body: () => string[]][] = [
+        ['services', () => describeServices(ctx)],
+        ['plugins', () => describePlugins(ctx)],
+        ['tools', () => describeTools(ctx)],
+        ['dynamic', () => describeDynamic(ctx, mounts)],
+        ['api', () => describeApi(ctx)],
+        ['events', () => describeEvents()],
+      ]
+      const selected = sections.filter(([heading]) => args.what === undefined || args.what === heading)
+      const text = selected
+        .map(([heading, body]) => `## ${heading}\n${body().join('\n')}`)
+        .join('\n\n')
+      return Promise.resolve([{ type: 'text', text }])
+    },
+    presentCall: presentInspectCall,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'cordis_mount',
+    description:
+      'Mount a NEW cordis plugin into the live runtime that is running THIS agent '
+      + '(self-modification). `code` runs as the body of an async JavaScript function '
+      + 'in an isolated sandbox and MUST `return` a plugin. Two forms: '
+      + 'FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register '
+      + 'tools, listen to events, and provide services, but reaching ANY service (e.g. '
+      + 'ctx.bash) throws; use it only when you need no services. '
+      + 'OBJECT form `return { name?, inject: [\'bash\', \'llm\', …], apply(ctx) { … } }` '
+      + '— declares dependencies, and cordis activates the plugin only after the '
+      + 'services exist; PREFER this form. You may reach ONLY the services you list in '
+      + 'inject: an undeclared service throws even if it exists, because an undeclared '
+      + 'dependency would not be cleaned up if its provider is unmounted. '
+      + 'BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists '
+      + 'method signatures AND the type shapes of their arguments/returns (do not guess a '
+      + 'field\'s type; e.g. a bash run\'s stdout is an object, not a string). '
+      + 'Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe '
+      + 'events (see cordis_inspect what:"events"), or call '
+      + '`harness.registerTool(ctx, harness.defineTool({ name, description, parameters: '
+      + '{ text: { type: \'string\', required: true } }, async execute(args) { … } }))` '
+      + 'to give yourself a new tool — it becomes callable on your NEXT step. '
+      + 'Tool parameters: each key IS a property — { type: \'string\'|\'number\'|\'boolean\'|\'object\'|\'array\', '
+      + 'required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style '
+      + '{ type: \'object\', properties, required: […] } wrapper and type \'integer\' are also accepted and normalized. A '
+      + 'tool\'s `execute` MUST return an ARRAY of content blocks, e.g. `return '
+      + '[{ type: \'text\', text: someString }]` — never a bare string. '
+      + 'Mounts can COMPOSE: one plugin may `ctx.provide(\'name\', value)` a service and '
+      + 'another may declare `inject: [\'name\']` to consume it — the consumer stays pending '
+      + 'until the provider exists and returns to pending when the provider is unmounted. '
+      + 'Everything registered inside `apply` is cleaned up automatically on unmount. '
+      + 'Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness '
+      + 'terminal), `harness.defineTool`, `harness.registerTool`, '
+      + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`. '
+      + 'Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, '
+      + 'never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect '
+      + 'errors; `process` and `Buffer` are undefined. Instead use inject: [\'fs\'] + ctx.fs for '
+      + 'files, inject: [\'web\'] + ctx.web for HTTP, inject: [\'bash\'] + ctx.bash for processes, '
+      + 'and inject: [\'timer\'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, '
+      + 'auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. '
+      + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). '
+      + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a '
+      + 'trailing `next` callback which MUST be called — returning without `next()` '
+      + 'VETOES the call; prefer plain notification events unless you intend to '
+      + 'intercept. (2) Never await something that only resolves after the current '
+      + 'turn (your code runs INSIDE a tool call of that turn — it would deadlock). '
+      + '(3) Your `ctx` is a restricted façade: you can register tools, observe '
+      + 'events, provide/consume services, and use timers, but framework internals '
+      + '(ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a '
+      + 'security boundary though — the services you inject (e.g. ctx.bash) reach the '
+      + 'real runtime.',
+    parameters: {
+      code: {
+        type: 'string',
+        required: true,
+        description: 'Body of an async JS function; must `return` the plugin to mount.',
+      },
+    },
+    async execute(args) {
+      const id = `dyn-${nextId++}`
+      const sandbox = createSandbox(id)
+      const evaluated = await evaluateMountCode(sandbox, args.code, id, vmTimeoutMs)
+      if (!isPlugin(evaluated)) {
+        if (evaluated === undefined) {
+          throw new Error(
+            'mount code returned `undefined` — did you forget `return`?\n'
+            + '  ✓ return (ctx) => { … }\n'
+            + '  ✓ return { name: \'…\', inject: […], apply(ctx) { … } }',
+          )
+        }
+        throw new Error(
+          'mount code must `return` a plugin: a function, or an object with an `apply(ctx)` method',
+        )
+      }
+      const fiber = await mountDynamic(group, evaluated)
+      mounts.set(id, { fiber, pluginName: pluginName(evaluated) })
+      // A settled fiber that is not ACTIVE is waiting on unsatisfied inject —
+      // legal cordis semantics (it activates when the service appears), so keep
+      // it mounted but tell the model what it is waiting for.
+      const missing = missingServices(ctx, fiber)
+      const state = STATE_LABELS[fiber.state]
+      const note = missing.length > 0
+        ? ` — waiting for service(s): ${missing.join(', ')} (activates when provided)`
+        : ''
+      return [{ type: 'text', text: `mounted ${id} (plugin "${pluginName(evaluated)}", state: ${state}${note})` }]
+    },
+    presentCall: presentMountCall,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'cordis_unmount',
+    description:
+      'Dispose a plugin previously mounted with cordis_mount, by id. All its '
+      + 'registrations (event listeners, tools, services) are cleaned up through '
+      + 'the cordis effect lifecycle. Returns only after disposal has fully '
+      + 'completed (quiescence, not just a request to stop).',
+    parameters: {
+      id: {
+        type: 'string',
+        required: true,
+        description: 'The dynamic mount id returned by cordis_mount (e.g. "dyn-1").',
+      },
+    },
+    async execute(args) {
+      const mount = mounts.get(args.id)
+      if (!mount) {
+        throw new Error(`no dynamic plugin with id "${args.id}" (list mounts with cordis_inspect what:"dynamic")`)
+      }
+      await mount.fiber.dispose()
+      mounts.delete(args.id)
+      return [{ type: 'text', text: `unmounted ${args.id} (plugin "${mount.pluginName}")` }]
+    },
+    presentCall: presentUnmountCall,
+  }))
+}

packages/cordis/tool-cordis/src/inspect.ts

@@ -0,0 +1,191 @@
+/**
+ * Read-only renderers over the live runtime for `cordis_inspect`: the service
+ * list, the flat plugin list, the registered tools, the dynamic-mount
+ * table (with per-mount provides/waits), and the catalog-backed `api` /
+ * `events` sections. Every renderer is a pure function of the runtime handles
+ * it receives — no session state, no clock — so inspect output is exactly the
+ * runtime it describes.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/inspect
+ */
+
+import type { Context, Fiber } from 'cordis'
+import { EVENT_API, INHERITED_CTX_API, SERVICE_API, TYPE_API } from './api-catalog.ts'
+import type { EventApiEntry, InheritedApiEntry, ServiceApiEntry, TypeApiEntry } from './api-catalog.ts'
+import { FiberState, STATE_LABELS } from './fiber-state.ts'
+import { missingServices } from './mount.ts'
+import type { DynamicMount } from './mount.ts'
+
+/** The live service registrations from `ctx.reflect.store` (map + filter keeps the possibly-undefined index read branch-free). */
+function liveImpls(ctx: Context): { name: string; fiber: Fiber }[] {
+  const store = ctx.reflect.store
+  return Object.getOwnPropertySymbols(store)
+    .map(key => store[key])
+    .filter((impl): impl is NonNullable<typeof impl> => impl !== undefined)
+}
+
+/** Whether `fiber` is `root` itself or mounted anywhere inside `root`'s subtree. */
+function withinFiber(fiber: Fiber, root: Fiber): boolean {
+  let current = fiber
+  while (true) {
+    if (current === root) return true
+    const parent = current.parent.fiber
+    if (parent === current) return false
+    current = parent
+  }
+}
+
+/** The service names provided by a mount's fiber subtree, sorted. */
+function providedBy(ctx: Context, fiber: Fiber): string[] {
+  return liveImpls(ctx)
+    .filter(impl => withinFiber(impl.fiber, fiber))
+    .map(impl => impl.name)
+    .sort()
+}
+
+/**
+ * The `services` section: every provided ctx service with its owning fiber,
+ * annotating non-active owners with their lifecycle state.
+ * @param ctx - the runtime to enumerate.
+ * @returns one line per service, or a single placeholder line when none are provided.
+ */
+export function describeServices(ctx: Context): string[] {
+  const lines = liveImpls(ctx).map((impl) => {
+    const active = impl.fiber.state === FiberState.ACTIVE
+    return `- ${impl.name} (provided by ${impl.fiber.name}${active ? '' : `, ${STATE_LABELS[impl.fiber.state]}`})`
+  })
+  return lines.length > 0 ? lines : ['(no services provided)']
+}
+
+/**
+ * The `plugins` section: a flat list of every fiber the registry knows, one
+ * line per fiber with its lifecycle state, sorted by plugin name (a plugin
+ * mounted more than once repeats — one line per instance). Dynamic mounts are
+ * listed like any other plugin; their ids live in the `dynamic` section.
+ * @param ctx - the runtime whose registry is enumerated.
+ * @returns one line per loaded plugin fiber.
+ */
+export function describePlugins(ctx: Context): string[] {
+  const fibers: Fiber[] = []
+  for (const runtime of ctx.registry.values()) {
+    for (const fiber of runtime.fibers) fibers.push(fiber)
+  }
+  return fibers
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map(fiber => `- ${fiber.name} [${STATE_LABELS[fiber.state]}]`)
+}
+
+/**
+ * The `tools` section: the model-facing tool names currently registered.
+ * @param ctx - the runtime whose tool registry is read.
+ * @returns one line per registered tool.
+ */
+export function describeTools(ctx: Context): string[] {
+  return ctx.tools.schemas().map(schema => `- ${schema.name}`)
+}
+
+/**
+ * The `dynamic` section: one line per mount with id, plugin name, lifecycle
+ * state, the services its subtree provides, and — for a pending mount — the
+ * services it waits for.
+ * @param ctx - the runtime the mounts live in.
+ * @param mounts - the tracked mounts, in mount order.
+ * @returns one line per mount, or a single placeholder line when none exist.
+ */
+export function describeDynamic(ctx: Context, mounts: ReadonlyMap<string, DynamicMount>): string[] {
+  if (mounts.size === 0) return ['(no dynamic plugins mounted)']
+  return [...mounts].map(([id, mount]) => {
+    const provides = providedBy(ctx, mount.fiber)
+    const waiting = missingServices(ctx, mount.fiber)
+    const providesNote = provides.length > 0 ? ` — provides: ${provides.join(', ')}` : ''
+    const waitingNote = waiting.length > 0 ? ` — waiting for: ${waiting.join(', ')}` : ''
+    return `- ${id}: ${mount.pluginName} [${STATE_LABELS[mount.fiber.state]}]${providesNote}${waitingNote}`
+  })
+}
+
+/**
+ * The transitive closure of catalogued type shapes referenced (word-bounded)
+ * by the seed texts — the runtime scoping that keeps the `api` section to the
+ * shapes the LIVE signatures actually mention.
+ */
+function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEntry[] {
+  const included = new Map<string, TypeApiEntry>()
+  let frontier = seeds
+  while (frontier.length > 0) {
+    const next: string[] = []
+    for (const entry of types) {
+      if (included.has(entry.name)) continue
+      const pattern = new RegExp(`\\b${entry.name}\\b`)
+      if (frontier.some(text => pattern.test(text))) {
+        included.set(entry.name, entry)
+        next.push(entry.declaration)
+      }
+    }
+    frontier = next
+  }
+  return [...included.values()].sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * The `api` section: the generated service catalog intersected with the LIVE
+ * runtime — catalogued live services render summary + method signatures, live
+ * services without a catalog entry (e.g. ones another mount provides) render
+ * name + owning fiber, catalog services that are not running are listed
+ * tersely, the type shapes the live signatures reference follow, and the
+ * inherited `ctx` surface closes the section.
+ * @param ctx - the runtime to intersect the catalog with.
+ * @param api - the service catalog (the generated one by default; injectable for tests).
+ * @param inherited - the inherited `ctx` surface lines (generated by default; injectable for tests).
+ * @param types - the type-shape catalog (generated by default; injectable for tests).
+ * @returns the section lines.
+ */
+export function describeApi(
+  ctx: Context,
+  api: readonly ServiceApiEntry[] = SERVICE_API,
+  inherited: readonly InheritedApiEntry[] = INHERITED_CTX_API,
+  types: readonly TypeApiEntry[] = TYPE_API,
+): string[] {
+  const live = new Map<string, string>()
+  for (const impl of liveImpls(ctx)) live.set(impl.name, impl.fiber.name)
+  const lines: string[] = []
+  const liveMethodTexts: string[] = []
+  for (const entry of api) {
+    if (!live.has(entry.key)) continue
+    lines.push(`- ${entry.key} — ${entry.summary}`)
+    for (const method of entry.methods) {
+      lines.push(`    ${method}`)
+      liveMethodTexts.push(method)
+    }
+  }
+  const catalogued = new Set(api.map(entry => entry.key))
+  for (const [name, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) {
+    if (!catalogued.has(name)) lines.push(`- ${name} (provided by ${fiber}, no catalog entry)`)
+  }
+  const notRunning = api.filter(entry => !live.has(entry.key)).map(entry => entry.key)
+  if (notRunning.length > 0) lines.push(`not running (loadable services with no live provider): ${notRunning.join(', ')}`)
+  const shapes = typeClosure(liveMethodTexts, types)
+  if (shapes.length > 0) {
+    lines.push('type shapes (referenced by the signatures above — read these before assuming a field is a string):')
+    for (const shape of shapes) {
+      for (const declLine of shape.declaration.split('\n')) lines.push(`    ${declLine}`)
+    }
+  }
+  lines.push('inherited ctx API:')
+  for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`)
+  return lines
+}
+
+/**
+ * The `events` section: every harness event with its dispatch mode, one-line
+ * summary, and exact signature, closed by the waterfall caution.
+ * @param events - the event catalog (the generated one by default; injectable for tests).
+ * @returns the section lines.
+ */
+export function describeEvents(events: readonly EventApiEntry[] = EVENT_API): string[] {
+  const lines = events.flatMap(event => [
+    `- ${event.name} [${event.mode}] — ${event.summary}`,
+    `    ${event.signature}`,
+  ])
+  lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.')
+  return lines
+}

packages/cordis/tool-cordis/src/mount.ts

@@ -0,0 +1,64 @@
+/**
+ * Dynamic-mount lifecycle over the `cordis-dynamic` group fiber: settle a
+ * sandbox-produced plugin as a child fiber (never leaving a failed fiber
+ * mounted), and report the services a settled-but-pending fiber still waits
+ * for. Disposal needs no helper — a mount unwinds through an ordinary awaited
+ * `fiber.dispose()`, because everything the plugin registered is an effect on
+ * its fiber.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/mount
+ */
+
+import type { Context, Fiber, Plugin } from 'cordis'
+import { guardedPlugin } from './guard.ts'
+
+/** One tracked dynamic mount: the fiber plus the display name captured at mount time. */
+export interface DynamicMount {
+  /** The child fiber under the `cordis-dynamic` group. */
+  fiber: Fiber
+  /** The plugin's display name at mount time (its `name`, else `<anonymous>`). */
+  pluginName: string
+}
+
+/**
+ * Mount a plugin under the group fiber and settle it. The group fiber loads
+ * asynchronously right after the owning plugin's `apply`, so it is awaited
+ * before hanging a child off its context. The child fiber's `await()` settles
+ * its lifecycle work and rethrows a startup error (e.g. a throwing `apply`);
+ * on error the fiber is disposed first — a failed mount never lingers.
+ * @param group - the `cordis-dynamic` group fiber every mount hangs under.
+ * @param plugin - the plugin the sandbox returned; wrapped with the registration guard before mounting.
+ * @returns the settled child fiber (possibly pending on unsatisfied `inject`).
+ */
+export async function mountDynamic(group: Fiber, plugin: Plugin): Promise<Fiber> {
+  await group.await()
+  const fiber = group.ctx.plugin(guardedPlugin(plugin))
+  try {
+    await fiber.await()
+  } catch (error) {
+    await fiber.dispose()
+    const message = error instanceof Error ? error.message : String(error)
+    // The commonest startup collision is remounting a NEW version of a tool
+    // while the old mount still holds the name — teach the replace recipe.
+    if (message.includes('already registered')) {
+      throw new Error(
+        `${message} — to REPLACE something an earlier mount registered, first cordis_unmount that mount's id `
+        + '(find it with cordis_inspect what:"dynamic"), then mount the new version.',
+      )
+    }
+    throw error instanceof Error ? error : new Error(message)
+  }
+  return fiber
+}
+
+/**
+ * The services a fiber declared in `inject` that do not exist yet — a settled
+ * fiber that is not active is waiting on exactly these (legal cordis
+ * semantics: it activates when the service appears).
+ * @param ctx - the context to resolve service existence against.
+ * @param fiber - the mount fiber whose `inject` declarations are checked.
+ * @returns the missing service names, in declaration order.
+ */
+export function missingServices(ctx: Context, fiber: Fiber): string[] {
+  return Object.keys(fiber.inject).filter(service => ctx.get(service) === undefined)
+}

packages/cordis/tool-cordis/src/present.ts

@@ -0,0 +1,51 @@
+/**
+ * ACP render intents for the three cordis tools — all `generic` cards, decided
+ * up front as part of the tool design. Presenters are pure functions of the
+ * call arguments (they run on replay too): no I/O, no session state, no clock.
+ * No `presentResult` overrides exist — the tools' text results are their
+ * correct completed rendering.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/present
+ */
+
+import type { GenericCallView } from '@deepseek-ai/dsh-tools'
+
+/**
+ * The `cordis_inspect` call card: a read, titled with the requested section.
+ * @param args - the validated call arguments.
+ * @returns the generic card the ACP bridge renders.
+ */
+export function presentInspectCall(args: { what?: string }): GenericCallView {
+  return {
+    card: 'generic',
+    kind: 'read',
+    title: args.what === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${args.what}`,
+  }
+}
+
+/**
+ * The `cordis_mount` call card: an execute carrying the mount code as raw input.
+ * @param args - the validated call arguments.
+ * @returns the generic card the ACP bridge renders.
+ */
+export function presentMountCall(args: { code: string }): GenericCallView {
+  return {
+    card: 'generic',
+    kind: 'execute',
+    title: 'Mount plugin into live cordis runtime',
+    rawInput: { code: args.code },
+  }
+}
+
+/**
+ * The `cordis_unmount` call card: a delete, titled with the mount id.
+ * @param args - the validated call arguments.
+ * @returns the generic card the ACP bridge renders.
+ */
+export function presentUnmountCall(args: { id: string }): GenericCallView {
+  return {
+    card: 'generic',
+    kind: 'delete',
+    title: `Unmount ${args.id}`,
+  }
+}

packages/cordis/tool-cordis/src/sandbox.ts

@@ -0,0 +1,201 @@
+/**
+ * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose
+ * globals are a tagged write-through console, the `harness` registration
+ * helpers, the encoding primitives a bare vm context lacks, and callable traps
+ * over the Node APIs the sandbox deliberately withholds. Capability access is
+ * routed through cordis services, never Node built-ins: filesystem work goes
+ * through `ctx.fs`, network through `ctx.web`, processes through `ctx.bash`,
+ * timers through the `ctx.timer` helpers (fiber effects, unwound on unmount)
+ * — so a well-behaved mount stays inspectable and disposable. That routing is
+ * STEERING toward the cordis services, not containment: the sandbox guards
+ * against ACCIDENTAL global pollution, and it is not a security boundary. The
+ * host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are
+ * reachable functions, so a mount that goes looking — e.g. through such a
+ * helper's `.constructor` — can still reach the host realm; that is accepted,
+ * because the `ctx` a mounted plugin's `apply` later receives is the real,
+ * fully privileged runtime handle, and that is the point of the toolset.
+ *
+ * @module @deepseek-ai/dsh-tool-cordis/sandbox
+ */
+
+import { createContext, runInContext } from 'node:vm'
+import { sandboxDefineTool, sandboxRegisterTool } from './guard.ts'
+
+/**
+ * A write-through console for one sandbox, tagging every line with the mount
+ * id. Write-through (host stdout/stderr), NOT buffered into the tool result:
+ * a mounted listener fires long after the mount call returned, and its output
+ * must land somewhere the user can see — for the stdio demo, the terminal.
+ */
+function taggedConsole(id: string): Record<'log' | 'info' | 'warn' | 'error' | 'debug', (...args: unknown[]) => void> {
+  const tag = `[cordis:${id}]`
+  const log = (...args: unknown[]): void => { console.log(tag, ...args) }
+  const error = (...args: unknown[]): void => { console.error(tag, ...args) }
+  return { log, info: log, warn: log, debug: log, error }
+}
+
+/**
+ * Per-sandbox prelude: give the vm realm's own constructors a
+ * `Symbol.hasInstance` that checks BOTH realms. Model code runs against a
+ * fresh vm realm, but most objects it touches are HOST-realm (the `args` a
+ * tool's `execute` receives, event payloads a listener observes, service
+ * return values), so a plain `x instanceof Array` / `instanceof Object` in
+ * sandbox code would silently be false. The patch replaces each vm
+ * constructor's own `[Symbol.hasInstance]` with "ordinary check against the
+ * vm constructor OR the host counterpart" — the ordinary algorithm is a pure
+ * prototype-chain walk, so calling it with the host constructor as receiver
+ * needs no host-side change. ONLY vm-realm globals are modified; host
+ * intrinsics are passed in as values and never touched.
+ */
+const DUAL_REALM_INSTANCEOF_PRELUDE = `
+(hostIntrinsics) => {
+  'use strict'
+  const ordinary = Function.prototype[Symbol.hasInstance]
+  for (const name of Object.keys(hostIntrinsics)) {
+    const VmCtor = globalThis[name]
+    const HostCtor = hostIntrinsics[name]
+    if (typeof VmCtor !== 'function' || typeof HostCtor !== 'function') continue
+    Object.defineProperty(VmCtor, Symbol.hasInstance, {
+      value: (instance) => ordinary.call(VmCtor, instance) || ordinary.call(HostCtor, instance),
+      configurable: true,
+    })
+  }
+}
+`
+
+/** Run {@link DUAL_REALM_INSTANCEOF_PRELUDE} in a freshly created sandbox, handing it the host intrinsics to pair up. */
+function patchDualRealmInstanceof(sandbox: object): void {
+  const patch = runInContext(DUAL_REALM_INSTANCEOF_PRELUDE, sandbox) as (intrinsics: Record<string, unknown>) => void
+  patch({ Object, Array, Function, Error, TypeError, RangeError, SyntaxError, Promise, RegExp, Date, Map, Set })
+}
+
+const TIMER_REDIRECT
+  = 'Node timers are unavailable. Use the cordis timer service instead: declare inject: [\'timer\'] on your plugin '
+    + 'and call ctx.setTimeout / ctx.setInterval — those are fiber effects, cleaned up automatically on unmount.'
+
+/**
+ * The callable Node APIs the sandbox deliberately disables, each mapped to the
+ * cordis alternative its trap error names. Only FUNCTION-shaped globals are
+ * trapped — a data-shaped global like `process` stays `undefined`, because a
+ * throwing accessor would detonate the common `typeof process` feature probe
+ * at resolution time.
+ */
+const NODE_API_REDIRECTS: Record<string, string> = {
+  require:
+    'Node modules are unavailable. Use the cordis services on ctx instead — e.g. inject: [\'fs\'] for files, '
+    + '[\'web\'] for HTTP, [\'bash\'] for processes; cordis_inspect what:"api" lists what THIS runtime provides.',
+  setTimeout: TIMER_REDIRECT,
+  setInterval: TIMER_REDIRECT,
+  setImmediate: TIMER_REDIRECT,
+  clearTimeout: TIMER_REDIRECT,
+  clearInterval: TIMER_REDIRECT,
+  fetch:
+    'Network access goes through the cordis web service: declare inject: [\'web\'] and call ctx.web '
+    + '(see cordis_inspect what:"api" for its methods).',
+}
+
+/** Build the trap functions for {@link NODE_API_REDIRECTS}: calling one throws the redirect. */
+function nodeApiTraps(): Record<string, () => never> {
+  const traps: Record<string, () => never> = {}
+  for (const [name, redirect] of Object.entries(NODE_API_REDIRECTS)) {
+    traps[name] = () => {
+      throw new Error(`${name} is not available in the mount sandbox — ${redirect}`)
+    }
+  }
+  return traps
+}
+
+/**
+ * Build the vm context one `cordis_mount` call evaluates in: the tagged
+ * console, the `harness` registration helpers, the encoding primitives, the
+ * Node-API traps, and the dual-realm `instanceof` patch, already
+ * `createContext`-ed.
+ * @param id - the mount id (`dyn-<n>`), used as the console tag and filename stem.
+ * @returns the contextified sandbox object to pass to {@link evaluateMountCode}.
+ */
+export function createSandbox(id: string): object {
+  const sandbox = {
+    ...nodeApiTraps(),
+    console: taggedConsole(id),
+    harness: { defineTool: sandboxDefineTool, registerTool: sandboxRegisterTool },
+    // Web APIs absent from fresh vm contexts — made available so the model
+    // can encode/decode base64 without Buffer (which is also absent). Host
+    // closures over Buffer, never Buffer itself.
+    btoa: (s: string) => Buffer.from(s, 'utf-8').toString('base64'),
+    atob: (s: string) => Buffer.from(s, 'base64').toString('utf-8'),
+    TextEncoder,
+    TextDecoder,
+  }
+  createContext(sandbox)
+  patchDualRealmInstanceof(sandbox)
+  return sandbox
+}
+
+/**
+ * Cross-realm SyntaxError detection: a compile failure inside `runInContext`
+ * constructs its error in the SANDBOX realm, so a host `instanceof
+ * SyntaxError` is silently false — the `name` property is the realm-safe tag.
+ */
+function isSyntaxError(error: unknown): error is Error {
+  return typeof error === 'object' && error !== null && (error as { name?: unknown }).name === 'SyntaxError'
+}
+
+/**
+ * The parse-failure context a vm `SyntaxError` carries: the vm prints the
+ * offending source line and a caret before the message, which is exactly what
+ * a model needs to self-correct — surface it instead of the bare message.
+ * Falls back to `String(error)` when the stack carries no such prelude.
+ * @param error - the `SyntaxError` (host- or sandbox-realm) thrown while compiling mount code.
+ * @returns the stack prefix up to and including the `SyntaxError: …` line.
+ */
+export function syntaxErrorContext(error: Error): string {
+  const lines = (error.stack ?? '').split('\n')
+  const messageIndex = lines.findIndex(line => line.startsWith('SyntaxError'))
+  if (messageIndex === -1) return String(error)
+  return lines.slice(0, messageIndex + 1).join('\n')
+}
+
+/**
+ * Evaluate mount code as the body of an async function inside the sandbox.
+ * `vmTimeoutMs` only bounds the SYNCHRONOUS portion; an async body escapes it
+ * — acceptable under the module's trust stance. A parse failure is answered
+ * with the offending line + caret and a teaching hint: TypeScript syntax on
+ * the failing line gets the remove-annotations fix, anything else gets the
+ * function-body/bracket-balance reminder (models habitually close the returned
+ * plugin object with `});` as if it were a callback argument).
+ * @param sandbox - the contextified object from {@link createSandbox}.
+ * @param code - the model-written function body; must `return` a plugin.
+ * @param id - the mount id, used as the vm filename (`cordis-mount-<id>.js`).
+ * @param vmTimeoutMs - the synchronous evaluation bound in milliseconds.
+ * @returns whatever the code returned, still un-narrowed (the mount lifecycle checks plugin shape).
+ */
+export async function evaluateMountCode(sandbox: object, code: string, id: string, vmTimeoutMs: number): Promise<unknown> {
+  try {
+    return await runInContext(
+      `(async () => {\n${code}\n})()`,
+      sandbox,
+      { filename: `cordis-mount-${id}.js`, timeout: vmTimeoutMs },
+    )
+  } catch (error) {
+    if (!isSyntaxError(error)) throw error
+    const context = syntaxErrorContext(error)
+    // Scope the TypeScript heuristic to the OFFENDING line, not the whole
+    // code: an ` as ` inside an ordinary description string must not turn a
+    // plain syntax error into a misleading remove-annotations message.
+    const offendingLine = context.split('\n')[1] ?? ''
+    if (/\bas\b/.test(offendingLine)) {
+      throw new Error(
+        `mount code failed to parse:\n${context}\n`
+        + 'The sandbox runs plain JavaScript, not TypeScript. Remove type annotations:\n'
+        + '  ✗ { type: \'text\' as const, text: x }\n'
+        + '  ✓ { type: \'text\', text: x }',
+      )
+    }
+    throw new Error(
+      `mount code failed to parse:\n${context}\n`
+      + 'Note: `code` runs as the BODY of an async function (line numbers are offset by the 1-line wrapper). '
+      + 'Check bracket balance — ending the returned plugin object with `});` closes a call that was never opened; '
+      + 'a plain `return { … }` ends with `}` (an optional `;`), never `)`.',
+    )
+  }
+}