better-dsh 0.0.0 → 0.2.3

package/lib/index.d.ts

@@ -0,0 +1,736 @@
+import { t as DASHRSdkSchema } from "./py-sdk-BCaOGYz7.js";
+import { Context, Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { ToolDefinition, ToolExecutionInput, ToolRunContext, ToolRuntime } from "@deepseek-ai/dsh-tools";
+import { ContentBlock, HarnessError } from "@deepseek-ai/dsh-llm";
+import { ScopeKey, Scoped } from "@deepseek-ai/dsh-scope";
+import { Agent } from "@deepseek-ai/dsh-agent";
+
+//#region src/vendored/types.d.ts
+
+/**
+ * Vocabulary types for the code-execution seam: what a caller hands a
+ * {@link ./repl-runtime.ts | ReplRuntime} and what it gets back. Pure types — no
+ * runtime code lives here.
+ *
+ * Vendored from `@deepseek-ai/dsh-code-runtime@0.1.0-rc.6` (`src/types.ts`)
+ * per blueprint v0.5 §7.6: type shapes are the interop contract our
+ * presentation/SDK work builds against, so they are carried unchanged apart
+ * from the recorded deltas:
+ *
+ * 1. the module header and the two `../index.ts` doc links were rewritten for
+ *    this location;
+ * 2. `CodeRunRequest.principal` is a DASHR-OWNED field (M3-A, blueprint §6
+ *    "kernel per-session 键控"): upstream's seam deliberately has no session
+ *    concept, but a stateful backend must key its persistent substrate by the
+ *    calling session or every session sharing one service instance would
+ *    share one namespace. Optional so upstream-shaped requests stay valid —
+ *    an absent principal addresses the provider's shared default key.
+ * 3. `CodeBindingNamespace.callable` is a DASHR-OWNED field (M3-B, blueprint
+ *    §9, introduced for the rlm() bare-callable binding family — deleted in
+ *    v0.1.8, kept for shape compatibility): upstream's object-holder model
+ *    (a global whose MEMBERS are callable) cannot express a bare callable
+ *    global. `callable: true` declares the global itself is a
+ *    function; `functions` then carries exactly one entry — the single host
+ *    function the global call dispatches. Optional so upstream-shaped
+ *    namespaces stay valid.
+ *
+ * @module dashr/vendored/types
+ */
+/**
+ * One host-side function exposed to the program as an async callable. The
+ * runtime bridges calls to it (possibly across a serialization boundary), so
+ * `args` and the resolution value MUST be lossless JSON. A runtime rejects a
+ * lossy or non-cloneable value with a descriptive error rather than corrupting
+ * the run. No seam-level byte cap applies to a binding resolution. A rejection
+ * of this function surfaces inside the program as a rejection of the
+ * corresponding call.
+ */
+type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>;
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
+type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | {
+  [key: string]: CodeJsonValue;
+};
+/**
+ * Program-visible typed rejection for one binding namespace. The runtime
+ * injects a real error constructor under `name`; rejected member calls become
+ * its instances and expose the exact member name through
+ * `memberNameProperty`. Both strings are runtime data rather than knowledge
+ * of a particular consumer such as Code Mode.
+ */
+interface CodeBindingErrorClass {
+  /** Constructor global and resulting `Error.name`; same portable identifier rule as {@link CodeBindingNamespace.global}. */
+  name: string;
+  /**
+   * Non-empty own property for the member name. The portable exclusion set is
+   * `RESERVED_ERROR_MEMBERS` plus dunder-form names (`__x__`, non-empty
+   * middle), enforced identically by every backend; any other name —
+   * identifiers or not — is accepted everywhere.
+   */
+  memberNameProperty: string;
+}
+/**
+ * A named group of {@link CodeBindingFunction}s the runtime exposes to the
+ * program as one global object (e.g. `tools`). Function names are arbitrary
+ * strings — a runtime must treat names like `__proto__` or `constructor` as
+ * ordinary own properties (null-prototype construction), never as prototype
+ * collisions.
+ */
+interface CodeBindingNamespace {
+  /**
+   * The global identifier the program sees. Must match the LANGUAGE-PORTABLE
+   * identifier subset `[A-Za-z_][A-Za-z0-9_]*` and no language's reserved
+   * words, so the same namespace list works against every backend regardless
+   * of `language` — a JS-only spelling like `$tools` is rejected by design,
+   * not just by the Python backend. Names that satisfy the identifier rule but
+   * name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`,
+   * `__dsh_main__`) are also refused everywhere; see its declaration for the
+   * exact set and why each entry is reserved.
+   */
+  global: string;
+  /** The callable members, keyed by the exact name the program calls. */
+  functions: Record<string, CodeBindingFunction>;
+  /**
+   * Materialize the global itself as a callable function rather than an
+   * object whose members are callable. When true, `functions` must contain
+   * EXACTLY ONE entry — the single host function the bare global call
+   * dispatches (its key is a transport detail, not a program-visible member).
+   * DASHR-owned delta (M3-B, blueprint §9): introduced for the rlm()
+   * bare-callable family (deleted in v0.1.8; the flat per-tool bindings
+   * succeeded it under the object-holder model).
+   */
+  callable?: true;
+  /** Optional program-visible typed rejection contract for this namespace. */
+  errorClass?: CodeBindingErrorClass;
+}
+/**
+ * One run: the program source plus everything the runtime acts on. Per the
+ * explicit-over-implicit convention, defaulting (time budgets, output caps)
+ * is the implementation's validated config — a request carries no optional
+ * tuning knobs for a hidden `??` to fill in.
+ */
+interface CodeRunRequest {
+  /**
+   * The program source, in the runtime's {@link ./repl-runtime.ts | language}. It
+   * runs as the body of an async function: top-level `await` and `return`
+   * are available, and the completion value becomes
+   * {@link CodeRunResult.value}.
+   */
+  program: string;
+  /** Host functions exposed to the program, one global object per namespace. */
+  bindings: CodeBindingNamespace[];
+  /**
+   * Abort the run: the runtime stops the program (hard, even mid-loop) and
+   * resolves with a {@link CodeRunFailure} of kind `'abort'`. In-flight
+   * binding calls are the CALLER's to settle — the runtime only stops asking.
+   */
+  signal?: AbortSignal;
+  /**
+   * The calling session/agent identity the run's state belongs to — a
+   * STATEFUL backend keys its persistent substrate by this (one namespace per
+   * principal) so sessions sharing one service instance never share state.
+   * DASHR-owned delta on the upstream seam (which is session-less); see the
+   * module header. The presentation layer passes the calling `Agent`'s id; an
+   * absent or empty principal addresses the provider's shared default key
+   * (upstream-shaped requests keep their M1 meaning).
+   */
+  principal?: string;
+  /**
+   * The kernel's working directory: the calling SESSION's workspace
+   * (`agent.session.header.cwd`), threaded by the presentation layer. Never
+   * the daemon's `process.cwd()`: a kernel is per-session state, so its cwd
+   * is per-session state, and inheriting the host cwd leaked the systemd
+   * unit's WorkingDirectory into every kernel regardless of the workspace the
+   * session was opened in. Absent (older caller, agentless run) → spawn-time
+   * inherit. Resolved ONLY on first spawn of a principal; a reused kernel
+   * keeps the cwd it booted with (a session's workspace is fixed in its
+   * header).
+   */
+  cwd?: string;
+  /**
+   * Per-run wall budget override, in milliseconds. Absent → the runtime's
+   * configured `runTimeoutMs`. DASHR-owned delta: upstream's one-shot seam
+   * fixes the budget in config alone; a stateful REPL wants a cell to be
+   * able to say "this one is slow" without reconfiguring the whole mount.
+   */
+  timeoutMs?: number;
+  /**
+   * Reset the persistent namespace to empty BEFORE this run. The runtime
+   * disposes the principal's kernel and clears its on-disk snapshot, so the
+   * next spawn restores nothing and starts a fresh, empty namespace.
+   * DASHR-owned delta: the M3-B snapshot/restore chain owns state revival;
+   * a model must be able to abandon that state deliberately.
+   */
+  reset?: boolean;
+}
+/**
+ * Why a run failed. The kinds are orthogonal outcomes reported independently
+ * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
+ * abort is not a timeout, and a substrate death is neither.
+ *
+ * - `'exception'` — the program threw or failed to parse/transform.
+ * - `'timeout'` — an implementation-owned budget expired; the message says which.
+ * - `'abort'` — {@link CodeRunRequest.signal} fired.
+ * - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
+ * - `'invalid-output'` — the completion value was not lossless JSON.
+ * - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
+ */
+interface CodeRunFailure {
+  /** The failure class (see the interface doc for each kind's meaning). */
+  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit';
+  /** Human-readable detail, suitable for feeding back to a model to self-correct. */
+  message: string;
+}
+/**
+ * The outcome of one run. An error is a FIELD on a resolved result, never a
+ * rejection of `run()` — reporting a failed program is the caller's job, not
+ * an exception path.
+ */
+interface CodeRunResult {
+  /**
+   * The program's completion value (its top-level `return`), when it ran to
+   * completion and the value crossed the runtime's lossless-JSON boundary.
+   * Invalid or over-limit completions fail the run instead of substituting a
+   * rendered string; a failed or value-less run leaves this absent.
+   */
+  value?: CodeJsonValue;
+  /** Text the program emitted, in order, bounded only as part of the outer result. */
+  logs: string[];
+  /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
+  error?: CodeRunFailure;
+}
+//#endregion
+//#region src/vendored/repl-runtime.d.ts
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    replRuntime: ReplRuntime;
+  }
+}
+/**
+ * Registers one `ctx.replRuntime` implementation. Program, budget, abort, and substrate
+ * failures resolve in {@link CodeRunResult}; only Service Definition contract misuse rejects. Implementations bridge
+ * structured-cloneable bindings, materialize each declared namespace rejection
+ * class, treat programs as hostile peers — budget, interrupt, and substrate
+ * semantics apply per program and are unchanged by this seam's statefulness —
+ * share one persistent per-session user namespace across runs (state
+ * codification across runs IS the product; this replaces upstream's
+ * isolate-runs-from-one-another clause), and terminate and await in-flight
+ * runs during disposal.
+ */
+declare abstract class ReplRuntime extends Service {
+  /**
+   * The source language {@link run} expects `program` to be written in, as a
+   * lowercase identifier. Informational, not gating — a consumer that
+   * generates language-specific presentation (typed SDK stubs, usage
+   * instructions) switches on it and fails loud on a language it cannot
+   * present. Well-known values: `'typescript'` and `'python'`, those
+   * `dsh-tools` presents; only `'typescript'` has a published backend.
+   */
+  abstract readonly language: string;
+  /**
+   * The execution substrate, as a lowercase identifier. Informational, not
+   * gating — a descriptor so deployments and diagnostics can tell backends
+   * apart, not a security claim. Well-known values: `'worker-thread'`,
+   * `'process'`, `'container'`.
+   */
+  abstract readonly isolation: string;
+  constructor(ctx: Context);
+  /**
+   * Execute one program against the request's bindings and capture what it
+   * emitted. See the class doc for the resolution contract (error is a result
+   * field; rejection means Service Definition contract misuse only).
+   * @param request - the program, its bindings, and the abort signal; the
+   *   request carries everything the runtime acts on, with no hidden defaults.
+   * @returns the run's outcome: completion value (when transferable), the
+   * ordered log capture, and the failure (if any).
+   */
+  abstract run(request: CodeRunRequest): Promise<CodeRunResult>;
+}
+//#endregion
+//#region src/runtime-surface.d.ts
+/**
+ * The `replRuntime` seam surface, as the presentation half of this plugin
+ * consumes it — a STRUCTURAL MIRROR of the vendored Service Definition
+ * (`src/vendored/repl-runtime.ts`, itself vendored verbatim from
+ * `@deepseek-ai/dsh-code-runtime@0.1.0-rc.6` `src/types.ts`).
+ *
+ * Why a mirror instead of a direct import, even inside one package: the
+ * presentation programs against a NARROW view of the runtime contract
+ * (bindings, dispatch logs, results) — the same shape a third-party
+ * `ctx.replRuntime` implementation would expose. Structural typing is what
+ * the Cordis service boundary is built on (contexts resolve implementations
+ * by key, not by class identity), so depending on the shape — not on our own
+ * `DashrRuntime` class — keeps the presentation implementation-agnostic.
+ *
+ * Drift control: `test/compat.spec.ts` statically asserts this surface is
+ * exactly compatible with the vendored types — a contract change there
+ * fails this package's typecheck.
+ * @module dashr-repl/runtime-surface
+ */
+/** One host-side function exposed to the program as an async callable; args and resolution must be lossless JSON. */
+type ReplBindingFunction = (args: unknown) => Promise<ReplJsonValue>;
+/** A lossless JSON value transferable through the dependency-light Service Definition. */
+type ReplJsonValue = null | boolean | number | string | ReplJsonValue[] | {
+  [key: string]: ReplJsonValue;
+};
+/** Program-visible typed rejection for one binding namespace (constructor name + member carrying the called name). */
+interface ReplBindingErrorClass {
+  /** Constructor global and resulting `Error.name`. */
+  name: string;
+  /** Non-empty own property for the member name. */
+  memberNameProperty: string;
+}
+/** A named group of binding functions exposed as one global object (e.g. `tools`). */
+interface ReplBindingNamespace {
+  /** The global identifier the program sees (portable identifier subset, no reserved words). */
+  global: string;
+  /** The callable members, keyed by the exact name the program calls. */
+  functions: Record<string, ReplBindingFunction>;
+  /**
+   * Materialize the global itself as a callable function rather than an
+   * object whose members are callable. When true, `functions` must contain
+   * EXACTLY ONE entry — the single host function the bare global call
+   * dispatches. Mirrors the vendored seam's DASHR-owned `callable` field
+   * (M3-B: the bridge callables and the v0.1.5 flat per-tool bindings).
+   */
+  callable?: true;
+  /** Optional program-visible typed rejection contract for this namespace. */
+  errorClass?: ReplBindingErrorClass;
+}
+/** One run: the program source plus everything the runtime acts on. */
+interface ReplRunRequest {
+  /** The program source; runs as one cell with top-level `await`/`return` available. */
+  program: string;
+  /** Host functions exposed to the program, one global object per namespace. */
+  bindings: ReplBindingNamespace[];
+  /** Abort the run; resolves with a failure of kind `'abort'`. */
+  signal?: AbortSignal;
+  /**
+   * The calling session/agent identity (the `Agent` id): a stateful backend
+   * keys its persistent namespace by this, so sessions sharing one service
+   * instance never share state (kernel-per-session, M3-A). DASHR-owned delta
+   * on the upstream seam — see the vendored Service Definition's types.
+  principal?: string
+  /** Per-run wall budget override in milliseconds; absent → the runtime's configured default. */
+  timeoutMs?: number;
+  /** Reset the persistent namespace to empty before this run. */
+  reset?: boolean;
+}
+/** Why a run failed; an error is a FIELD on the resolved result, never a rejection of `run()`. */
+interface ReplRunFailure {
+  /** The failure class. */
+  kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit';
+  /** Human-readable detail, suitable for feeding back to a model to self-correct. */
+  message: string;
+}
+/** The outcome of one run. */
+interface ReplRunResult {
+  /** The program's completion value, when it crossed the lossless-JSON boundary. */
+  value?: ReplJsonValue;
+  /** Text the program emitted, in order. */
+  logs: string[];
+  /** Present iff the run failed. */
+  error?: ReplRunFailure;
+}
+/** How one user-namespace variable query resolved. */
+type ReplVarQuery = /** The value crossed the lossless-JSON boundary; `text` is its JSON text. */
+{
+  kind: 'json';
+  text: string;
+}
+/** The value is not JSON-serializable; `text` is its `repr` text (annotate it as repr). */ | {
+  kind: 'repr';
+  text: string;
+}
+/** A bare/empty name: `names` lists the user-namespace variable names. */ | {
+  kind: 'names';
+  names: string[];
+}
+/** No such variable in the namespace (or no live kernel holds state). */ | {
+  kind: 'missing';
+};
+/**
+ * The `ctx.replRuntime` service as this plugin reads it. The language check
+ * belongs to the presentation: only `'python'` has an SDK renderer here.
+ */
+interface ReplRuntimeSurface {
+  /** The source language {@link run} expects `program` to be written in (lowercase identifier). */
+  readonly language: string;
+  /** Execute one program against the request's bindings and capture what it emitted. */
+  run(request: ReplRunRequest): Promise<ReplRunResult>;
+  /**
+   * Read one user-namespace variable by name on the session's kernel. A
+   * bare/empty `name` lists the namespace's variable names; a JSON-serializable
+   * value resolves to its JSON text, any other value to its `repr` text, and a
+   * missing name to `{ kind: 'missing' }`. `principal` selects the session
+   * kernel (absent → the shared default), mirroring {@link ReplRunRequest.principal}.
+   * Optional so a third-party `ctx.replRuntime` provider without this DASHR
+   * channel stays structurally valid.
+   */
+  queryVar?(name: string, principal?: string): Promise<ReplVarQuery>;
+  /**
+   * Assign one lossless-JSON value into the user namespace under `name` on the
+   * session's kernel. `name` must be a usable identifier; `value` must be
+   * lossless JSON. Optional for the same reason as {@link queryVar}.
+   */
+  setVar?(name: string, value: unknown, principal?: string): Promise<void>;
+}
+//#endregion
+//#region src/runtime.d.ts
+/** Plugin config: every tunable, changeable from `cordis.yml` (no hardcoded tunables). */
+interface Config$1 {
+  /** Python interpreter with `ipykernel` installed. The bare sentinel `python3` (or absent) selects a managed venv under {@link Config.kernelEnvDir}. */
+  python?: string;
+  /** Budget for kernel spawn → ready, in milliseconds. */
+  startupTimeoutMs?: number;
+  /** Wall budget per run; expiry interrupts the kernel then force-settles. */
+  runTimeoutMs?: number;
+  /** Grace between a timeout/abort interrupt and the force-settle, in milliseconds. */
+  interruptGraceMs?: number;
+  /**
+   * Confirm window between the control-channel interrupt and the SIGALRM
+   * escalation, in milliseconds; must stay below {@link Config.interruptGraceMs}.
+   * See the bridge's two-phase interrupt for why the escalation is deferred.
+   */
+  interruptConfirmMs?: number;
+  /** Budget for graceful kernel teardown (shutdown_request → SIGKILL), in milliseconds. */
+  disposeTimeoutMs?: number;
+  /** Budget for internal snapshot/restore cells (dill dump/load), in milliseconds. */
+  snapshotTimeoutMs?: number;
+  /** Hard cap for serialized log-array, completion-value, and failure-message payloads. */
+  maxOutputBytes?: number;
+  /** Directory for per-session namespace snapshots (`state.dill` + `manifest.json`); none when absent. */
+  snapshotDir?: string;
+  /** Serialized-size cap for a turn-end snapshot, in bytes; over-cap snapshots are skipped with a one-time model warning. */
+  snapshotSizeCapBytes?: number;
+  /** Managed venv directory (used when `python` is absent/`python3`); defaults to `<package>/.venv-kernel`. */
+  kernelEnvDir?: string;
+  /** Preferred CPython version for a managed venv. */
+  kernelPythonVersion?: string;
+  /** Provision the managed venv (ipykernel + dill) on first use; default true. */
+  kernelAutoInstall?: boolean;
+  username?: string;
+}
+/**
+ * The {@link ReplRuntime} backend this package registers (`ctx.replRuntime`)
+ * — the standing-mount layer of the v0.1.5 architecture, the de facto daemon
+ * while the profile-level DashrDaemon stays an empty shell. One service
+ * instance per mount holds one lazily-spawned kernel per session principal;
+ * each kernel's lifecycle — snapshot and shutdown on session end, snapshot
+ * and shutdown of every key on plugin disposal — is effect-owned.
+ */
+declare class DashrRuntime extends ReplRuntime {
+  static Config: z<Config$1>;
+  readonly language = "python";
+  readonly isolation = "process";
+  private readonly config;
+  private readonly logger;
+  /** One entry per session principal that has run code (lazy — never pre-seeded). */
+  private readonly kernels;
+  private disposed;
+  /** Lazily-resolved (and, when managed, provisioned) kernel interpreter. */
+  private kernelEnvPromise;
+  constructor(ctx: Context, config: Config$1);
+  /**
+   * The agentless-default kernel's pid, for lifecycle diagnostics; absent
+   * before the first agentless run. Per-session pids: {@link kernelPids}.
+   */
+  get kernelPid(): number | undefined;
+  /** Every live kernel subprocess pid, one per session that has run code. */
+  get kernelPids(): number[];
+  /**
+   * Execute one program as one cell on the persistent kernel. Program
+   * outcomes — including kernel startup failure — resolve with
+   * `result.error`; the method rejects only for Service Definition contract
+   * misuse (a disposed runtime, an invalid binding namespace).
+   * @param request - the program, its bindings, and the abort signal.
+   * @returns the run's outcome per the seam contract.
+   */
+  run(request: CodeRunRequest): Promise<CodeRunResult>;
+  /**
+   * Read one user-namespace variable by name on the session's kernel. A
+   * bare/empty name lists the namespace's user-variable names; a
+   * JSON-serializable value resolves to its JSON text, any other value to its
+   * `repr` text, and a missing name to `{ kind: 'missing' }`. When no live
+   * kernel holds state for the key the namespace is empty (no spawn — this
+   * channel never creates a kernel). Pure additive: the run/execute/snapshot
+   * lifecycle is untouched.
+   * @param name - the variable name, or empty to list namespace names.
+   * @param principal - the session key (absent → the shared default).
+   */
+  queryVar(name: string, principal?: string): Promise<ReplVarQuery>;
+  /**
+   * Assign one lossless-JSON value into the user namespace under `name` on
+   * the session's kernel. `name` must be a usable identifier (and not a
+   * kernel-shim name); `value` must be lossless JSON. Requires a live kernel
+   * for the key — the channel never spawns one, so a session that has not yet
+   * run a cell must `run` first. Pure additive to the existing lifecycle.
+   * @param name - the identifier to assign under.
+   * @param value - the lossless-JSON value to bind.
+   * @param principal - the session key (absent → the shared default).
+   */
+  setVar(name: string, value: unknown, principal?: string): Promise<void>;
+  /** Map one cell outcome onto the seam's result shape under the output ledger. */
+  private assembleResult;
+  /** Reject malformed binding globals or typed-error declarations as contract misuse. */
+  private validateBindings;
+  /** Dispatch one kernel-side host request; unknown types and bad payloads become error replies. */
+  private dispatchHostRequest;
+  /** Resolve (and provision, when managed) the kernel interpreter once per runtime. */
+  private resolveKernelPython;
+  /**
+   * Spawn-or-reuse the kernel for one key. The lazy map guarantees one
+   * entry is created here and nowhere else, so a key that never runs never
+   * holds a subprocess — the subagent fan-out guarantee (blueprint §6:
+   * subagent ×N spawns nothing until a child actually executes code).
+   * @param key - the run principal (or the agentless default).
+   */
+  private ensureKernel;
+  /**
+   * Restore a key's on-disk snapshot into a freshly booted kernel, when one
+   * exists and its manifest is plausible. Called once per entry boot. The
+   * kernel-side restore cell performs the authoritative environment checks
+   * (python version, interpreter identity, skills); this method only gates on
+   * the manifest the host can read cheaply, then records the turn so the
+   * first-run notice and the revive chain can name it.
+   */
+  private restoreEntry;
+  /** Read the per-key manifest's host-relevant fields; absent when unreadable/missing. */
+  private readSnapshotManifest;
+  /**
+   * Revive one session's kernel after death: respawn a fresh kernel, restore
+   * the nearest replayable snapshot onto it (the normal restore path), and
+   * return the death-observing run's explicit error naming the turn. When no
+   * replayable snapshot exists the message falls back to M3-A's fresh-empty
+   * contract. The run itself does NOT execute — an error that lies about a
+   * NameError costs the model more than one dropped cell (blueprint §8.3).
+   * @param key - the run principal.
+   * @param dead - the entry that died (its `turn` is the last completed turn).
+   */
+  private reviveAfterDeath;
+  /**
+   * Write one key's turn-end snapshot, when a snapshot directory is
+   * configured. A size-cap skip is reported (so the run can warn the model
+   * once); other failures log without disturbing the run.
+   */
+  private snapshotTurnEnd;
+  /**
+   * Dispose to quiescence: snapshot every live key's namespace when a
+   * snapshot directory is configured (each under its own per-key
+   * subdirectory), then shut the subprocesses down. Registered as the
+   * plugin's `ctx.effect` disposer.
+   */
+  private teardown;
+  /**
+   * Tear one session's kernel down (session end via the `agent/disposed`
+   * listener). A no-op for keys that never ran code through this instance —
+   * which is what makes hearing every agent's disposal safe.
+   */
+  private destroyKey;
+  /**
+   * Reset one session's kernel to a fresh, empty namespace: dispose the live
+   * subprocess WITHOUT a turn-end snapshot and clear its on-disk snapshot, so
+   * the next ensureKernel spawns empty (restore finds nothing to replay).
+   */
+  private resetKey;
+  /** Snapshot (when configured) then dispose one key's kernel; failures log, never throw into a listener. */
+  private teardownKernel;
+}
+//#endregion
+//#region src/tool-call-id.d.ts
+/** The host's tool-call id brand, as carried by `ToolExecutionInput.callId`. */
+type ToolCallId = ToolExecutionInput['callId'];
+//#endregion
+//#region src/web-trust.d.ts
+/** Page-authority + mobile config slice of the plugin config. */
+interface WebTrustConfig {
+  /** Hostnames this operator declares their own devices' pages run on. */
+  trustedPageAuthorities?: readonly string[];
+  /** Mobile responsiveness knobs (client half consumes via page global). */
+  mobile?: {
+    enabled?: boolean;
+    breakpoint?: number;
+    swipeDistancePx?: number;
+    dominanceRatio?: number;
+    leftEdgeBandPx?: number;
+    rightZoneRatio?: number;
+    swipeVelocityPxPerMs?: number;
+  };
+}
+//#endregion
+//#region src/index.d.ts
+/** Cordis plugin name. */
+declare const name = "dashr-repl";
+/**
+ * Required services. `replRuntime` is NOT listed: see the module doc — the
+ * mode-dependent wait is declared inside {@link apply} instead, and the
+ * execution path re-reads the service at use time with an actionable error.
+ */
+declare const inject: string[];
+/** Plugin config. */
+interface Config extends Config$1 {
+  maxParallelSubCalls?: number;
+  /** Page hostnames this operator declares their own (web-trust boot script). */
+  trustedPageAuthorities?: string[];
+  /** Mobile responsiveness knobs (delivered to the client half as a page global). */
+  mobile?: WebTrustConfig['mobile'];
+}
+/** Runtime schema. */
+declare const Config: z<Config>;
+/** The model-facing name of the DASHR cell transport. */
+declare const EVAL_NAME = "eval";
+/**
+ * The wire-mask deny list (design D1): the upstream delegation and
+ * guidance tools DASHR displaces from the model's surface. The list feeds
+ * ONE registry-level mechanism — `tools.restrict({deny})` on the agent's
+ * own scope layer at session-start — which removes every name from ALL
+ * registry projections at once (wire schemas, catalog, SDK, REPL bindings,
+ * by-name dispatch): the restricted-away names are gone for the model on
+ * every surface, not hidden per-presentation. Two exemptions are registry
+ * facts, not list policy: a name the host never registered is skipped (a
+ * restriction may only name inherited tools), and a name registered on the
+ * agent's OWN layer (the child-scoped native `report`, this composition's
+ * bridges below, never through the masked name. `subagent` is deliberately
+ * NOT in this list (v0.2.1b): its standard-preset registration
+ * (`modelSelectionSettings: true`) lands on the agent's OWN layer, outside
+ * registry restriction reach, so it stays visible on every surface and the
+ * control prompt annotates it as an alias of the `agent` delegation tool.
+ * own URL wrappers) is exempt from restrictions by construction — the
+ * capability it carries stays reachable through the captured-definition
+ * bridges below, never through the masked name.
+ */
+declare const MASKED_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * The effective deny list the session-start wiring restricts. An alias of
+ * {@link MASKED_TOOL_NAMES} today; a config override (a deployment naming
+ * its own mask) slots in HERE and nowhere else — the constant is the single
+ * source, so the mask never drifts between capture, restrict, and the
+ * bridges that read captured definitions.
+ */
+declare const WIRE_MASKED_NAMES: ReadonlySet<string>;
+/** The `dashr:control-prompt` section order: the FIRST section in the 100–199 tool-guidance band, so the cell paradigm is taught before the Tool Catalog renders its signatures. */
+declare const CONTROL_SECTION_ORDER = 100;
+/** The `dashr:tool-catalog` section order: the 100–199 tool-guidance band's SDK position, matching upstream `tools:sdk`. */
+declare const SDK_SECTION_ORDER = 150;
+/**
+ * The `dashr:escalation-guidance` CONTEXT order: sits inside the runtime-context snapshot
+ * band between upstream `approval:policy` (115) and `subagent:delegation` (120) — the
+ * sandbox policy statement is order 110, the approval policy 115. Re-check if upstream
+ * adds context entries in this band (dsh-system-prompt CONTEXT_ORDERS).
+ */
+declare const ESCALATION_GUIDANCE_ORDER = 116;
+/**
+ * Thrown by `eval` when the cell itself failed — a program exception, a
+ * budget expiry, an abort, or kernel death. Extends {@link HarnessError} with
+ * the same `code: 'CODE_RUN_FAILED'` as upstream `CodeRunFailedError`, so
+ * registry-side error taxonomy and session-log consumers see the shape they
+ * already know; the registry's execution pipeline converts it into a
+ * structured `isError` result whose text carries the failure kind plus the
+ * captured logs, so the model can self-correct.
+ */
+declare class DASHRRunFailedError extends HarnessError {
+  constructor(message: string);
+}
+/** Resolve the eval overlap cap at the config boundary (schemastery already validated the range; direct construction in tests bypasses it). */
+declare function resolveMaxParallelSubCalls(value: number | undefined): number;
+/**
+ * One settled `eval` sub-dispatch about to be logged, as seen by the
+ * `dashr/repl-dispatch-log` waterfall — dashr's OWN dispatch-log event,
+ * self-registered via the cordis Events merge below. Decoupled from
+ * upstream's `tools/ptc-dispatch-log` (PTC `run_code` sub-dispatches): `eval`
+ * is a broader session-persistent REPL (IPython kernel) than upstream's
+ * `run_code` TS-worker tool, so its durable-log reshape extension point is
+ * dashr-owned and version-independent — no coupling to upstream's
+ * `CodeDispatchLog`/`PtcDispatchLog` rename or the PTC tool's event name.
+ */
+interface ReplDispatchLog {
+  /** The outer `eval` execution. */
+  readonly exec: ToolRunContext;
+  /** The calling agent (scope routing key + spill owner), when present. */
+  readonly agent?: Agent;
+  /** Deterministic sub-call id (`<parent>:code:<n>`). */
+  readonly subCallId: ToolCallId;
+  /** The dispatched sub-tool name. */
+  readonly name: string;
+  /** Whether the sub-call settled as an error. */
+  readonly isError: boolean;
+  /** The sub-call's complete model-facing content (the settle event's default payload). */
+  readonly content: ContentBlock[];
+}
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /**
+     * Allow a listener to replace content in the DURABLE LOG COPY of one
+     * `eval` sub-dispatch outcome before the bridge appends its
+     * `tool/code-dispatch` event. `next()` keeps the content unchanged; a
+     * listener may return replacement blocks (e.g. the spill policy's preview
+     * + locator for an oversized text result). Scope-filtered dispatch
+     * (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that
+     * agent's dispatches.
+     * @param dispatch - the parent execution, sub-call identity, and settled content to log.
+     * @mode waterfall
+     */
+    'dashr/repl-dispatch-log'(this: Scoped<ToolRuntime>, dispatch: ReplDispatchLog, next: () => Promise<ContentBlock[]>): Promise<ContentBlock[]>;
+  }
+}
+/**
+ * Capabilities the `eval` bridge closes over, mirroring upstream's
+ * `RunCodeBridgeOptions` (the `requireRuntime` idiom): the registry-private
+ * staged scheduler travels through the exported `TOOL_RUNTIME_SCHEDULER`
+ * symbol-keyed property rather than a closure, because — unlike upstream —
+ * the registry does not mint this tool for us.
+ */
+interface RunCellBridgeOptions {
+  /** Resolves `ctx.replRuntime` or throws the loud misconfiguration error (use-time read). */
+  requireRuntime: () => ReplRuntimeSurface;
+  /** The run's overlap cap for parallel-classified sub-calls (validated config). */
+  maxParallel: number;
+  /**
+   * Runs the `dashr/repl-dispatch-log` waterfall over one settled
+   * sub-dispatch and returns the content the bridge should log — dashr's own
+   * dispatch-log reshape extension point (self-registered, decoupled from
+   * upstream's PTC `tools/ptc-dispatch-log`). Built in {@link apply}.
+   */
+  shapeDispatchLog: (dispatch: ReplDispatchLog) => Promise<ContentBlock[]>;
+  /**
+   * Named logger warn from the mounting context, used for lane-failure
+   * warnings (v0.2.1c drive() backstop) — the lane must log-and-settle,
+   * never rethrow.
+   */
+  warn: (message: string) => void;
+}
+/**
+ * Build the `eval` {@link ToolDefinition}: required `cell` and
+ * `description` parameters, executed through the dispatch bridge described
+ * in the module doc. Sub-calls ride the registry's exported staged scheduler
+ * (`prepare`/`dispatch`/`finalize`/`finish`) under the native concurrency
+ * contract; each sub-dispatch is logged for reconstruction
+ * (`tool/code-dispatch-start` / `tool/code-dispatch`) while only the outer
+ * curated result enters model history.
+ * @param registry - the host tool registry (sub-calls go through its staged
+ *   scheduler, bindings cover its registered tools).
+ * @param options - the bridge capabilities described above.
+ * @returns the registry-ready definition.
+ */
+declare function createRunCellTool(registry: ToolRuntime, options: RunCellBridgeOptions): ToolDefinition;
+/**
+ * Collect one calling scope's bridge-declaration schemas through the
+ * registry's public projection APIs: `schemas(scope)` for the model-facing
+ * view (scoped tools join, restrictions apply — the wire mask is a
+ * registry-level restriction installed at session-start, so every masked
+ * name is ALREADY absent from this projection; no second name filter
+ * exists to drift), `get(name, scope)` for the canonical output schema,
+ * snapshotted so a live definition cannot mutate under the render. `eval`
+ * itself is excluded — it is the transport, not a binding.
+ */
+declare function collectSdkSchemas(registry: ToolRuntime, scope?: ScopeKey): DASHRSdkSchema[];
+declare function apply(ctx: Context, config: Config): void;
+declare const _default: {
+  name: string;
+  inject: string[];
+  Config: z<Config>;
+  apply: typeof apply;
+};
+//#endregion
+export { CONTROL_SECTION_ORDER, Config, DASHRRunFailedError, DashrRuntime, ESCALATION_GUIDANCE_ORDER, EVAL_NAME, MASKED_TOOL_NAMES, ReplDispatchLog, ReplRuntime, RunCellBridgeOptions, type Config$1 as RuntimeConfig, SDK_SECTION_ORDER, WIRE_MASKED_NAMES, apply, collectSdkSchemas, createRunCellTool, _default as default, inject, name, resolveMaxParallelSubCalls };