dshb-exec-ssh 0.0.1

package/lib/process-provider-CUgC5gyu.d.ts

@@ -0,0 +1,3328 @@
+import { i as Dict, n as Context, r as StandardSchemaV1, t as Service } from "./index-CDfaZYyK.js";
+import { SshExecutor } from "./executor.js";
+import { Readable, Writable } from "node:stream";
+//#region ../../node_modules/@deepseek-ai/cosmokit/lib/types/types.d.ts
+declare function isArrayBufferLike(value: any): value is ArrayBufferLike;
+declare function isArrayBufferSource(value: any): value is Binary.Source;
+/** Binary source detection and base64/hex conversion helpers. */
+declare namespace Binary {
+  type Source<T extends ArrayBufferLike = ArrayBufferLike> = T | ArrayBufferView<T>;
+  const is: typeof isArrayBufferLike;
+  const isSource: typeof isArrayBufferSource;
+  function fromSource<T extends ArrayBufferLike>(source: Source<T>): T;
+  function toBase64(source: Source): string;
+  function fromBase64(source: string): ArrayBuffer | Uint8Array<ArrayBuffer>;
+  function toHex(source: Source): string;
+  function fromHex(source: string): ArrayBuffer;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/schemastery/lib/types/index.d.ts
+declare const kSchema: unique symbol;
+declare global {
+  namespace Schemastery {
+    /** Convert primitive constructors, constants, and existing schemas into a schema type. */
+    type From<X> = X extends string | number | boolean ? Schema<X> : X extends Schema ? X : X extends typeof String ? Schema<string> : X extends typeof Number ? Schema<number> : X extends typeof Boolean ? Schema<boolean> : X extends typeof Function ? Schema<Function, (...args: any[]) => any> : X extends Constructor<infer S> ? Schema<S> : never;
+    type TypeS1<X> = X extends Schema<infer S, unknown> ? S : never;
+    type Inverse<X> = X extends Schema<any, infer Y> ? (arg: Y) => void : never;
+    /** Input type accepted by a schema-like value. */
+    type TypeS<X> = TypeS1<From<X>>;
+    /** Output type returned by a schema-like value after validation. */
+    type TypeT<X> = ReturnType<From<X>>;
+    /** Resolver callback used by custom schema types registered with `Schema.extend()`. */
+    type Resolve = (data: any, schema: Schema, options: Options, strict?: boolean) => [any, any?];
+    /** Input type accepted by one schema in an intersection. */
+    type IntersectS<X> = From<X> extends Schema<infer S, unknown> ? S : never;
+    /** Output type returned by one schema in an intersection. */
+    type IntersectT<X> = Inverse<From<X>> extends ((arg: infer T) => void) ? T : never;
+    type TupleS<X extends readonly any[]> = X extends readonly [infer L, ...infer R] ? [TypeS<L>?, ...TupleS<R>] : any[];
+    type TupleT<X extends readonly any[]> = X extends readonly [infer L, ...infer R] ? [TypeT<L>?, ...TupleT<R>] : any[];
+    type ObjectS<X extends Dict> = { [K in keyof X]?: TypeS<X[K]> | null; } & Dict;
+    type ObjectT<X extends Dict> = { [K in keyof X]: TypeT<X[K]>; } & Dict;
+    type Constructor<T = any> = new (...args: any[]) => T;
+    /** Static constructor and factory methods exposed by the default `Schema` export. */
+    interface Static {
+      <T = any>(options: Partial<Schema<T>>): Schema<T>;
+      new <T = any>(options: Partial<Schema<T>>): Schema<T>;
+      prototype: Schema;
+      /** Validate a value against a schema node and return `[output, adaptedInput?]`. */
+      resolve: Resolve;
+      /** Infer a schema from a primitive value, constructor, or existing schema. */
+      from<X = any>(source?: X): From<X>;
+      /** Register a resolver for a custom schema `type`. */
+      extend(type: string, resolve: Resolve): void;
+      /** Accept any value without validation. */
+      any<T = any>(): Schema<T>;
+      /** Accept only nullable input. */
+      never(): Schema<never>;
+      /** Accept exactly one constant value. */
+      const<const T>(value: T): Schema<T>;
+      /** Accept strings, with optional metadata constraints added by instance methods. */
+      string(): Schema<string>;
+      /** Accept numbers, with optional range and step constraints. */
+      number(): Schema<number>;
+      /** Accept non-negative integer numbers. */
+      natural(): Schema<number>;
+      /** Accept a number between 0 and 1 and mark it as a slider. */
+      percent(): Schema<number>;
+      /** Accept booleans. */
+      boolean(): Schema<boolean>;
+      /** Accept `Date` instances or parse datetime strings into `Date` objects. */
+      date(): Schema<string | Date, Date>;
+      /** Accept `RegExp` instances or parse strings into regular expressions. */
+      regExp(flag?: string): Schema<string | RegExp, RegExp>;
+      /** Accept binary sources and normalize them to `ArrayBufferLike`. */
+      arrayBuffer(): Schema<Binary.Source, ArrayBufferLike>;
+      arrayBuffer(encoding: 'hex' | 'base64'): Schema<Binary.Source | string, ArrayBufferLike>;
+      /** Accept a numeric bitset or string keys and normalize to a number. */
+      bitset<K extends string>(bits: Partial<Record<K, number>>): Schema<number | readonly K[], number>;
+      /** Accept functions. */
+      function(): Schema<Function, (...args: any[]) => any>;
+      /** Accept instances of a constructor or objects whose constructor name matches. */
+      is(constructor: string): Schema;
+      is<T>(constructor: Constructor<T>): Schema<T>;
+      /** Accept arrays whose elements match `inner`. */
+      array<X>(inner: X): Schema<TypeS<X>[], TypeT<X>[]>;
+      /** Accept plain objects with values matching `inner` and optional key schema. */
+      dict<X, Y extends Schema<any, string> = Schema<string>>(inner: X, sKey?: Y): Schema<Dict<TypeS<X>, TypeS<Y>>, Dict<TypeT<X>, TypeT<Y>>>;
+      /** Accept tuple arrays where each index matches the corresponding schema. */
+      tuple<const X extends readonly any[]>(list: X): Schema<TupleS<X>, TupleT<X>>;
+      /** Accept plain objects whose declared properties match the schema dictionary. */
+      object<X extends Dict>(dict: X): Schema<ObjectS<X>, ObjectT<X>>;
+      /** Accept values matching at least one schema in `list`. */
+      union<const X>(list: readonly X[]): Schema<TypeS<X>, TypeT<X>>;
+      /** Accept values matching every schema in `list`, merging object outputs. */
+      intersect<const X>(list: readonly X[]): Schema<IntersectS<X>, IntersectT<X>>;
+      /** Validate with `inner`, then convert the result with `callback`. */
+      transform<X, T>(inner: X, callback: (value: TypeS<X>, options: Schemastery.Options) => T, preserve?: boolean): Schema<TypeS<X>, T>;
+      /** Defer construction of a recursive schema until validation or serialization. */
+      lazy<X extends Schema>(callback: () => X): X;
+      ValidationError: typeof ValidationError;
+    }
+    /** Runtime validation options shared by all schema calls. */
+    interface Options {
+      /** Remove invalid object properties instead of throwing when possible. */
+      autofix?: boolean;
+      /** Skip validation for selected values and schema nodes. */
+      ignore?(data: any, schema: Schema): boolean;
+      /** Path used to format nested validation errors. */
+      path?: (keyof any)[];
+    }
+    /** UI and validation metadata attached by schema builder methods. */
+    interface Meta<T = any> {
+      default?: T extends {} ? Partial<T> : T;
+      required?: boolean;
+      disabled?: boolean;
+      collapse?: boolean;
+      badges?: {
+        text: string;
+        type: string;
+      }[];
+      hidden?: boolean;
+      loose?: boolean;
+      role?: string;
+      extra?: any;
+      link?: string;
+      description?: string | Dict<string>;
+      comment?: string;
+      pattern?: {
+        source: string;
+        flags?: string;
+      };
+      max?: number;
+      min?: number;
+      step?: number;
+    }
+  }
+  /** Callable schema instance that validates input and returns normalized output. */
+  interface Schemastery<S = any, T = S> {
+    (data?: S | null, options?: Schemastery.Options): T;
+    new (data?: S | null, options?: Schemastery.Options): T;
+    [kSchema]: true;
+    uid: number;
+    meta: Schemastery.Meta<T>;
+    type: string;
+    sKey?: Schema;
+    inner?: Schema;
+    list?: Schema[];
+    dict?: Dict<Schema>;
+    bits?: Dict<number>;
+    callback?: Function;
+    constructor?: string | Function;
+    builder?: Function;
+    value?: T;
+    refs?: Dict<Schema>;
+    preserve?: boolean;
+    '~standard': StandardSchemaV1.Props;
+    /** Format this schema as a compact TypeScript-like type string. */
+    toString(inline?: boolean): string;
+    /** Serialize this schema, preserving shared and recursive references. */
+    toJSON(): Schema<S, T>;
+    /** Mark nullable input as invalid unless a default supplies a fallback. */
+    required(value?: boolean): Schema<S, T>;
+    /** Hide this schema node from UI renderers. */
+    hidden(value?: boolean): Schema<S, T>;
+    /** Return the default value instead of throwing when validation fails. */
+    loose(value?: boolean): Schema<S, T>;
+    /** Attach a renderer role and optional role-specific metadata. */
+    role(text: string, extra?: any): Schema<S, T>;
+    /** Attach an external documentation link. */
+    link(link: string): Schema<S, T>;
+    /** Set the fallback value used for nullable input. */
+    default(value: T): Schema<S, T>;
+    /** Attach an auxiliary comment for documentation or form UIs. */
+    comment(text: string): Schema<S, T>;
+    /** Attach a localized or plain description for documentation or form UIs. */
+    description(text: string): Schema<S, T>;
+    /** Mark this schema node as disabled for form UIs. */
+    disabled(value?: boolean): Schema<S, T>;
+    /** Request collapsed rendering for nested form UIs. */
+    collapse(value?: boolean): Schema<S, T>;
+    /** Add a deprecated badge to this schema node. */
+    deprecated(): Schema<S, T>;
+    /** Add an experimental badge to this schema node. */
+    experimental(): Schema<S, T>;
+    /** Require strings to match a regular expression. */
+    pattern(regexp: RegExp): Schema<S, T>;
+    /** Set an inclusive maximum for numbers or collection lengths. */
+    max(value: number): Schema<S, T>;
+    /** Set an inclusive minimum for numbers or collection lengths. */
+    min(value: number): Schema<S, T>;
+    /** Set the numeric increment constraint. */
+    step(value: number): Schema<S, T>;
+    /** Add or replace an object property schema. */
+    set(key: string, value: Schema): Schema<S, T>;
+    /** Append a tuple, union, or intersection member schema. */
+    push(value: Schema): Schema<S, T>;
+    /** Remove values equal to schema defaults from normalized output. */
+    simplify(value?: any): any;
+    /** Return a schema clone with descriptions merged from locale messages. */
+    i18n(messages: Dict): Schema<S, T>;
+    /** Attach arbitrary metadata consumed by form renderers and downstream tools. */
+    extra<K extends keyof Schemastery.Meta>(key: K, value: Schemastery.Meta[K]): Schema<S, T>;
+  }
+}
+declare class ValidationError extends TypeError {
+  options: Schemastery.Options;
+  name: string;
+  constructor(message: string, options: Schemastery.Options);
+  static is(error: any): error is ValidationError;
+}
+type Schema<S = any, T = S> = Schemastery<S, T>;
+declare const Schema: Schemastery.Static;
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-settings/lib/types/redact.d.ts
+/** One schema-declared secret position inside a redacted value. */
+interface RedactedSecret {
+  /** Path from the section root to the removed field (concrete dict keys and array indexes included). */
+  path: string[];
+  /** Whether the field held a value before redaction. */
+  set: boolean;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-brand/lib/types/index.d.ts
+/**
+ * The `Branded<B>` nominal-typing primitive — a type-only utility (no runtime
+ * code, no harness-package dependency) shared by every package that owns a
+ * cross-boundary id.
+ *
+ * A brand makes structurally-identical strings non-interchangeable at the type
+ * level: a `SessionId` cannot be passed where a `CallId` is expected, even
+ * though both are plain strings at runtime. Construction goes through a per-id
+ * factory in the OWNING package (a plain cast inside — zero runtime cost);
+ * comparison, logging, and serialization all behave as ordinary strings.
+ *
+ * Policy: a package brands the ids it owns — `CallId` in dsh-llm (tool-call
+ * correlation), the shared agent/session `SessionId` in dsh-session, and
+ * `JobId` in dsh-jobs. Branding is for ids that cross package boundaries and
+ * could plausibly be confused; not every string needs a brand.
+ * This package owns ONLY the primitive — no concrete id, no runtime code beyond
+ * the (erased) type — so the brand vocabulary stays dependency-free and a
+ * package can brand its ids without depending on an unrelated capability
+ * package.
+ *
+ * @module @deepseek-ai/dsh-brand
+ */
+declare const BRAND: unique symbol;
+/** A string carrying a compile-time-only brand `B`. */
+type Branded<B extends string> = string & {
+  readonly [BRAND]: B;
+};
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-settings/lib/types/types.d.ts
+/** Nominal id of one registered settings namespace. */
+type SettingsNamespace = Branded<'SettingsNamespace'>;
+/** Origin of one committed settings change. */
+type SettingsUpdateSource = 'update' | 'provider';
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /**
+     * Committed change to one registered namespace's resolved value. Emitted
+     * after the provider persisted (for `update`) or published (`provider`)
+     * the change; never emitted when the resolved value is deep-equal.
+     * Listener failures are contained and logged — a sync throw and an async
+     * rejection alike — except `INVARIANT`-coded failures, which rethrow
+     * after every listener ran; that rethrow reaches the emitter only from
+     * synchronous listeners, so invariant checks on this event must not be
+     * async functions.
+     * @param ns - the namespace whose resolved value changed.
+     * @param next - the new resolved value.
+     * @param prev - the previous resolved value.
+     * @param source - whether the change entered through `update()` or the provider.
+     * @mode emit
+     */
+    'settings/updated'(ns: SettingsNamespace, next: unknown, prev: unknown, source: SettingsUpdateSource): void;
+    /**
+     * One registered namespace's RAW user section changed, whether or not the
+     * resolved value did. `settings/updated` is the consumer-facing event and
+     * stays deep-equal-gated; this one exists for configuration surfaces,
+     * which must learn that a field went from inherited to overridden (same
+     * resolved value, different meaning) and that their held revision is
+     * stale. Listener containment matches `settings/updated`.
+     * @param ns - the namespace whose stored section changed.
+     * @param revision - the namespace's new revision.
+     * @mode emit
+     */
+    'settings/document-updated'(ns: SettingsNamespace, revision: number): void;
+  }
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-settings/lib/types/index.d.ts
+/** When a namespace's changes take effect for its owner. */
+type SettingsApplies = 'live' | 'restart';
+/** Registration options beyond the namespace schema. */
+interface SettingsRegisterOptions<T> {
+  /** Composition-layer values resolved below the user layer (entry-config subset). */
+  base?: Partial<T>;
+  /** Owner's effect timing, surfaced to configuration UIs; defaults to `live`. */
+  applies?: SettingsApplies;
+  /**
+   * Reject a resolved section the owner could not act on, for constraints its
+   * schema cannot express — a cross-field requirement, or one field's validity
+   * depending on another's. Throwing here refuses the *write* that produced the
+   * value, so a caller learns at `update`/`replace`/`mutate` instead of storing
+   * something that would silently disable the owner.
+   *
+   * Kept separate from the schema because the schema is also what a
+   * configuration surface renders and what an absent section resolves through;
+   * folding a cross-field check into it would change both.
+   *
+   * Once the owner is registered, a stored section that fails this keeps the
+   * namespace's last good value and warns, exactly as a schema failure does,
+   * so an externally edited document cannot strand a running owner. At
+   * registration there is no last good value yet, so a stored section that
+   * already fails rejects the registration itself — again exactly as a schema
+   * failure does.
+   * @param value - the resolved section, schema-valid by construction.
+   */
+  validate?: (value: T) => void;
+}
+/** One registered namespace as surfaced to configuration UIs. */
+interface SettingsDescriptor {
+  /** The registered namespace. */
+  ns: SettingsNamespace;
+  /** Serialized schemastery schema (`schema.toJSON()`). */
+  schema: unknown;
+  /** Current resolved value. */
+  value: unknown;
+  /**
+   * Monotonic revision of the raw user section this descriptor was read at.
+   * Send it back as `expectedRevision` on a write to refuse a stale one.
+   */
+  revision: number;
+  /** Registrant's composition `base` layer (detached), when one was declared. */
+  base?: unknown;
+  /**
+   * Raw user section from the stored document (detached), when one exists and
+   * is well-formed; a field's presence here is what marks it user-overridden.
+   */
+  user?: unknown;
+  /** Owner's declared effect timing. */
+  applies: SettingsApplies;
+  /** Schema-declared secret positions; present only under `redactSecrets`. */
+  secrets?: RedactedSecret[];
+}
+/** Options for {@link SettingsProvider.describe}. */
+interface SettingsDescribeOptions {
+  /**
+   * Strip `role('secret')` fields from `value`/`base`/`user` and enumerate
+   * them in each descriptor's `secrets`. Every wire surface MUST pass this;
+   * the verbatim default exists for same-process configuration UIs only.
+   */
+  redactSecrets?: boolean;
+}
+/** Owner-facing handle for one registered namespace. */
+interface SettingsScope<T> {
+  /** Current resolved value: schema defaults, then `base`, then the user layer. */
+  get(): T;
+  /**
+   * Observe committed changes to this namespace's resolved value. Invocations
+   * of one callback run asynchronously, one at a time, in commit order; a
+   * rejection is contained and logged like a sync throw. After the disposer
+   * returns, no further invocation starts — one already queued is skipped;
+   * one already started still settles, and service disposal waits for it.
+   * @param callback - invoked after each commit with the next and previous values.
+   * @returns the disposer removing this observer.
+   */
+  watch(callback: (next: T, prev: T) => void | Promise<void>): () => void;
+  /**
+   * Merge a partial patch into this namespace's user layer and persist it.
+   * @param patch - plain-object patch over the user section; JSON-compatible data
+   * only (non-JSON values reject with their path before anything persists).
+   */
+  update(patch: object): Promise<void>;
+  /**
+   * Replace this namespace's user section wholesale; absent keys re-inherit
+   * the composition `base` and schema defaults (`replace({})` resets all).
+   * @param section - the complete next user section; JSON-compatible data only,
+   * as for {@link update}.
+   */
+  replace(section: object): Promise<void>;
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    settings: SettingsProvider;
+  }
+}
+/**
+ * One path-addressed edit to a namespace's user section. Path mutation exists
+ * for a caller holding an INCOMPLETE view of the section — a configuration UI
+ * reads the redacted descriptor, which by construction never received the
+ * `role('secret')` fields. Such a caller can name the field it means without
+ * restating the section: a wholesale `replace` rebuilt from a redacted
+ * document silently deletes every secret the wire never returned.
+ */
+type SettingsPathOp = {
+  op: 'set';
+  path: readonly string[];
+  value: unknown;
+} | {
+  op: 'unset';
+  path: readonly string[];
+};
+/**
+ * Abstract settings service. Providers implement raw-document storage
+ * (`load`/`persist`) and push external changes through {@link Settings.publish};
+ * the base class owns namespace registration, resolution, validation, change
+ * detection, and the `settings/updated` commit event.
+ */
+declare abstract class SettingsProvider extends Service {
+  private readonly registrations;
+  /** Latest published raw document; empty until the provider's first publish. */
+  private document;
+  /** Per-namespace write chains; settled tails, so a failure never poisons the queue. */
+  private readonly writeQueues;
+  /** In-flight watcher invocation segments, drained by the dispose teardown. */
+  private readonly pendingTails;
+  /** Set at service dispose: refuse new writes while queued ones drain. */
+  private stopped;
+  /** Opaque read of {@link stopped}: control flow cannot narrow it across awaits. */
+  private isStopped;
+  constructor(ctx: Context);
+  /**
+   * Load the provider's document once and publish it before the service
+   * becomes injectable, and register the write-drain teardown. Providers with
+   * their own init (watchers, connections) delegate here first via
+   * `yield* super[Service.init]()`; their disposers then run before the drain.
+   */
+  [Service.init](): AsyncGenerator<() => Promise<void> | void, void, void>;
+  /** Whether {@link update} may persist through this provider. */
+  abstract readonly writable: boolean;
+  /**
+   * Absolute path of the provider's user-editable document, when its storage
+   * is one local file. Configuration surfaces use this only as availability
+   * metadata; the guarded open operation resolves the path again Host-side.
+   * Non-file providers leave it undefined and expose no open-document affordance.
+   * @returns the absolute local document path, or undefined for non-file storage.
+   */
+  get documentPath(): string | undefined;
+  /**
+   * Prepare the provider's user-editable document for a native editor. File
+   * providers may materialize an absent document before returning its path;
+   * non-file providers return undefined.
+   * @returns the absolute local document path, or undefined for non-file storage.
+   */
+  prepareDocument(): Promise<string | undefined>;
+  /**
+   * Read the provider's current raw document (namespace to raw section).
+   * @returns the detached raw document.
+   */
+  protected abstract load(): Promise<Record<string, unknown>>;
+  /**
+   * Durably store one namespace's merged user section.
+   * @param ns - the namespace being written.
+   * @param section - the complete merged user section to store.
+   */
+  protected abstract persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void>;
+  /**
+   * Register a namespace schema and receive its owner scope. The registration
+   * is an effect on the calling plugin's fiber: disposing that fiber removes
+   * the namespace and its observers. An invalid stored section fails the
+   * registration itself — the earliest point where the schema can judge it.
+   * @param ns - unique namespace; duplicate registration fails loud.
+   * @param schema - schemastery schema resolving this namespace's value.
+   * @param options - composition `base` layer and effect timing.
+   * @returns the owner scope for reads, observation, and updates.
+   */
+  register<T>(ns: SettingsNamespace, schema: Schema<T>, options?: SettingsRegisterOptions<T>): SettingsScope<T>;
+  /**
+   * Describe every registered namespace for configuration surfaces, including
+   * the composition `base` and raw user layers so a form can mark which fields
+   * the user overrode (presence in `user`) and what a reset returns to.
+   * @param options - redaction switch; wire surfaces must redact.
+   * @returns one descriptor per registered namespace, in registration order.
+   */
+  describe(options?: SettingsDescribeOptions): SettingsDescriptor[];
+  /**
+   * Read one registered namespace's resolved value.
+   * @param ns - the namespace to read.
+   * @returns the resolved value, or `undefined` while unregistered.
+   */
+  get(ns: SettingsNamespace): unknown;
+  /**
+   * Merge a patch into one registered namespace's user layer, validate the
+   * resolved candidate, persist through the provider, then commit and emit.
+   * A validation failure rejects before anything is persisted. Writes to one
+   * namespace are serialized: concurrent updates apply in call order, each
+   * merging over the previous write's committed section.
+   * @param ns - the registered namespace to update.
+   * @param patch - plain-object patch over the user section.
+   * @param expectedRevision - the descriptor `revision` the caller read; a
+   *   namespace that moved past it rejects with {@link SettingsConflictError}.
+   */
+  update(ns: SettingsNamespace, patch: object, expectedRevision?: number): Promise<void>;
+  /**
+   * Replace one registered namespace's user section wholesale, validate,
+   * persist, then commit and emit. Keys absent from `section` fall back to the
+   * composition `base` and schema defaults — this is the removal/reset path a
+   * merge-only patch cannot express (`replace({})` re-inherits everything).
+   * @param ns - the registered namespace to replace.
+   * @param section - the complete next user section.
+   * @param expectedRevision - the descriptor `revision` the caller read; a
+   *   namespace that moved past it rejects with {@link SettingsConflictError}.
+   */
+  replace(ns: SettingsNamespace, section: object, expectedRevision?: number): Promise<void>;
+  /**
+   * Apply path-addressed edits to one registered namespace's user section,
+   * validate, persist, then commit and emit. The ops are applied to the
+   * section as it stands when the write reaches the front of the queue, so a
+   * caller never has to restate fields it did not touch — and, crucially,
+   * cannot delete fields it never saw. This is the write path for any caller
+   * holding a redacted view; `replace` remains the wholesale reset.
+   * @param ns - the registered namespace to edit.
+   * @param ops - ordered path edits; later ops observe earlier ones.
+   * @param expectedRevision - the descriptor `revision` the caller read; a
+   *   namespace that moved past it rejects with {@link SettingsConflictError}.
+   */
+  mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<void>;
+  /** Validate a write, then queue it on the namespace's serialized write chain. */
+  private write;
+  /**
+   * Provider hook: commit a complete raw document observed in storage. Each
+   * registered namespace re-resolves; an invalid section keeps that
+   * namespace's last good value and warns, other namespaces still commit.
+   * @param doc - the detached raw document (unregistered sections preserved).
+   * @param source - change origin; defaults to `provider`.
+   */
+  protected publish(doc: Record<string, unknown>, source?: SettingsUpdateSource): void;
+  /** Read one namespace's raw user section, rejecting non-object sections. */
+  private section;
+  /** Resolve one namespace value: schema defaults, then `base`, then the user layer. */
+  private resolve;
+  /**
+   * Advance a namespace's revision when its RAW section changed, and announce
+   * it. Deliberately independent of {@link commit}'s resolved-value equality:
+   * storing an override equal to the composition base leaves the resolved
+   * value alone but changes what the document says, which is exactly what a
+   * configuration surface must re-read.
+   */
+  private bumpRevision;
+  /** Contained fan-out of `settings/document-updated`, mirroring {@link commit}'s. */
+  private emitDocumentUpdated;
+  /** Commit a resolved value when changed: swap, notify watchers, emit the event. */
+  private commit;
+  /** Contained-watcher diagnostic shared by the sync and async failure paths. */
+  private warnWatcherFailure;
+  /** Contained-listener diagnostic shared by the sync and async failure paths. */
+  private warnListenerFailure;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-attachment/lib/types/brand.d.ts
+/** Opaque content-addressed identifier for one immutable attachment object. */
+type AttachmentId = Branded<'AttachmentId'>;
+/**
+ * Brand a validated storage identifier.
+ * @param value - backend-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+declare function AttachmentId(value: string): AttachmentId;
+/** Opaque deterministic identity for one request-image transformation. */
+type ImageVariantId = Branded<'ImageVariantId'>;
+/**
+ * Brand a validated request-image transformation identifier.
+ * @param value - attachment-provider-produced opaque identifier.
+ * @returns the branded identifier.
+ */
+declare function ImageVariantId(value: string): ImageVariantId;
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-attachment/lib/types/types.d.ts
+/** Raster image formats accepted by the version-one attachment path. */
+type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** Durable, serializable reference to one immutable normalized image. */
+interface ImageAttachmentRef {
+  /** Opaque storage identifier; never a filesystem path or bearer URL. */
+  attachmentId: AttachmentId;
+  /** Media type verified from the stored bytes. */
+  mediaType: ImageMediaType;
+  /** Exact encoded byte length. */
+  bytes: number;
+  /** Intrinsic encoded width in pixels. */
+  width: number;
+  /** Intrinsic encoded height in pixels. */
+  height: number;
+  /** Optional display name stripped of local path information. */
+  name?: string;
+  /**
+   * Input dimensions after applying EXIF orientation and before normalization
+   * scaling. Present only when normalization reduced the image.
+   */
+  originalDimensions?: {
+    width: number;
+    height: number;
+  };
+}
+/** Deployment-resolved limits used by upload admission and request buffering. */
+interface ImageAttachmentLimits {
+  maxImageBytes: number;
+  maxImagesPerMessage: number;
+  maxMessageImageBytes: number;
+  maxImagePixels: number;
+  /** Maximum intrinsic width and maximum intrinsic height in pixels for one image. */
+  maxImageDimension: number;
+  mediaTypes: readonly ImageMediaType[];
+}
+/** Request to validate and durably commit one image. */
+interface SaveImageAttachment {
+  data: Uint8Array;
+  /** Caller-declared media type, checked against fully decoded bytes. */
+  mediaType: ImageMediaType;
+  /** Optional browser/provider display name; it is never interpreted as a path. */
+  name?: string;
+}
+/** Stored image bytes returned after reference and digest verification. */
+interface StoredImageAttachment {
+  ref: ImageAttachmentRef;
+  data: Uint8Array;
+}
+/** Deterministic request-image policy selected by one exact model route. */
+interface ImageRequestPolicy {
+  /** Maximum width multiplied by height after aspect-preserving projection. */
+  maxPixels: number;
+  /** Encoded-byte cap before base64 expansion or Files API upload. */
+  maxBytes: number;
+}
+/** Cached request version derived from one provider-independent normalized attachment. */
+interface RequestImageAttachment {
+  /** Cache and upload-index key over the attachment id, policy, and fixed encoder parameters. */
+  variantId: ImageVariantId;
+  /** Durable normalized attachment from which this request version was derived. */
+  attachment: ImageAttachmentRef;
+  /** Encoded request bytes. */
+  data: Uint8Array;
+  mediaType: ImageMediaType;
+  bytes: number;
+  width: number;
+  height: number;
+  /** Provider-compatible sample depth proven after request encoding. */
+  depth: 'uchar';
+  /** Provider-compatible color space proven after request encoding. */
+  space: 'srgb';
+  /** Whether the encoded request version retains an alpha channel. */
+  hasAlpha: boolean;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-attachment/lib/types/index.d.ts
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    attachments: AttachmentStore;
+  }
+}
+/** Immutable binary attachment service. Implementations validate bytes before publishing a reference. */
+declare abstract class AttachmentStore extends Service {
+  constructor(ctx: Context);
+  /** Deployment-resolved image policy used by authoritative and fast-path validation. */
+  abstract readonly imageLimits: ImageAttachmentLimits;
+  /**
+   * Validate one image without persisting it.
+   * Batch callers validate every member before saving any member.
+   * @param input - encoded bytes, declared media type, and optional display name.
+   * @returns completion after the encoded raster has been fully decoded.
+   */
+  abstract validateImage(input: SaveImageAttachment): Promise<void>;
+  /**
+   * Validate one ordered image batch before committing any member.
+   * Validation failures start no writes; storage failures return no partial
+   * references, although already published content-addressed objects may stay
+   * unreachable until a future retention policy collects them.
+   * @param inputs - encoded images in their owning message order.
+   * @returns durable references in the exact input order.
+   */
+  protected validateImageBatch(inputs: readonly SaveImageAttachment[]): void;
+  /**
+   * Validate and durably commit one ordered image batch.
+   * @param inputs - encoded images in owning-message order.
+   * @returns durable normalized attachment references in the same order after every member succeeds.
+   */
+  saveImages(inputs: readonly SaveImageAttachment[]): Promise<readonly ImageAttachmentRef[]>;
+  /**
+   * Validate and durably commit one image before its owning session event is appended.
+   * The returned reference describes the persisted normalized image. When
+   * normalization reduces the raster, its `originalDimensions` records the
+   * orientation-applied input dimensions.
+   * @param input - encoded bytes, declared media type, and optional display name.
+   * @returns the durable content-addressed normalized image reference.
+   */
+  abstract saveImage(input: SaveImageAttachment): Promise<ImageAttachmentRef>;
+  /**
+   * Read one image and verify that bytes still match the recorded reference.
+   * @param ref - durable reference from the session log.
+   * @param signal - optional cancellation for backend read and verification work.
+   * @returns the verified bytes and normalized attachment reference.
+   * @throws the signal reason when aborted, or a storage error when verification fails.
+   */
+  abstract readImage(ref: ImageAttachmentRef, signal?: AbortSignal): Promise<StoredImageAttachment>;
+  /**
+   * Generate or read one deterministic model-request version from the stored normalized image.
+   * @param ref - durable provider-independent normalized attachment reference.
+   * @param policy - exact route pixel and encoded-byte budget.
+   * @param signal - optional cancellation.
+   * @returns request bytes and the cache/upload identity covering every transform input.
+   */
+  readImageRequest(ref: ImageAttachmentRef, policy: ImageRequestPolicy, signal?: AbortSignal): Promise<RequestImageAttachment>;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/brand.d.ts
+/** Stable identity carried by one message across inbox, log, and model-request boundaries. */
+type MessageId = Branded<'MessageId'>;
+/**
+ * Brand a message identifier.
+ * @param id - the opaque message identifier.
+ * @returns the same string, branded; no validation is performed.
+ */
+declare function MessageId(id: string): MessageId;
+/**
+ * Correlates a model-issued tool call with its result. Provider-issued for
+ * real adapters; synthesized by mocks/assembler fallbacks.
+ */
+type CallId = Branded<'CallId'>;
+/**
+ * Brand a string as a {@link CallId}.
+ * @param id - the provider-issued (or synthesized) call id.
+ * @returns the same string, branded; no validation is performed.
+ */
+declare function CallId(id: string): CallId;
+/** Provider-issued request identifier retained for diagnostics across package boundaries. */
+type ProviderRequestId = Branded<'ProviderRequestId'>;
+/**
+ * Brand a provider-issued request identifier.
+ * @param id - the opaque provider-issued string.
+ * @returns the same string, branded; no validation is performed.
+ */
+declare function ProviderRequestId(id: string): ProviderRequestId;
+/** Adapter-owned identifier for one model's selectable reasoning effort. */
+type ReasoningEffortId = Branded<'ReasoningEffortId'>;
+/**
+ * Brand an adapter-owned reasoning-effort identifier.
+ * @param id - the opaque identifier exposed by one model capability.
+ * @returns the same string, branded; no validation is performed.
+ */
+declare function ReasoningEffortId(id: string): ReasoningEffortId;
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/message.d.ts
+/** Provider/model identity and adapter-private replay data for an assistant message. */
+interface AssistantProvenance {
+  /** Provider route that produced the message. */
+  provider: string;
+  /** Provider model id that produced the message. */
+  model: string;
+  /**
+   * Lossless-JSON adapter state needed to replay the provider response.
+   * `LlmRuntime` exposes it to a target adapter only when that adapter instance
+   * currently owns both this historical provider and the target provider.
+   */
+  replayState?: unknown;
+}
+/** Required source of an assistant message produced by a routed model. */
+interface ModelMessageSource extends AssistantProvenance {
+  kind: 'model';
+}
+/** Required source of a user-role message carrying one tool result. */
+interface ToolMessageSource {
+  kind: 'tool';
+  callId: CallId;
+}
+/** One named contribution to a `snapshot`-form context, in assembly order. */
+interface ContextSnapshotSection {
+  /** The contributing subsystem's name. */
+  readonly name: string;
+  /** That contribution's model-facing text, exactly as assembled. */
+  readonly text: string;
+}
+/**
+ * Producer-declared {@link ContextForm} and the fields that form requires,
+ * mixed into the source types that carry one.
+ *
+ * Discriminated by `form` so a producer cannot select a form without the
+ * fields needed to present it: a `notice` must record its one-line
+ * account, a `snapshot` its sections. Omitting `form` stays valid — an
+ * undeclared context is the documented default.
+ */
+type ContextFormed = {
+  readonly form?: never;
+} | {
+  readonly form: 'instructions';
+} | {
+  readonly form: 'catalog';
+} | {
+  readonly form: 'snapshot';
+  /** The named contributions this snapshot assembled, in order. */
+  readonly sections: readonly ContextSnapshotSection[];
+} | {
+  readonly form: 'notice';
+  /** One-line account of what happened, shown without expanding the row. */
+  readonly summary: string;
+} | {
+  readonly form: 'relay';
+} | {
+  readonly form: 'recall';
+};
+/**
+ * Where a message (or injected content) came from.
+ * Merge-extensible sum type — plugins add their own `kind`s.
+ */
+interface MessageSourceMap {
+  user: {
+    kind: 'user';
+  };
+  plugin: {
+    kind: 'plugin';
+    plugin: string;
+  } & ContextFormed;
+  model: ModelMessageSource;
+  tool: ToolMessageSource;
+}
+/** Any known message source, derived from {@link MessageSourceMap}; switch on `kind` and fall through unknowns (merge-extensible). */
+type MessageSource = MessageSourceMap[keyof MessageSourceMap];
+/** One immutable message representation shared by delivery, durable history, and model requests. */
+interface Message {
+  /** Stable identity preserved across every representation boundary. */
+  readonly id: MessageId;
+  /** Provider-neutral conversation role. */
+  readonly role: 'system' | 'user' | 'assistant';
+  /** Exact model-facing blocks. */
+  readonly content: ContentBlock[];
+  /** Required source fields supplied by the producer. */
+  readonly source: MessageSource;
+}
+/** A user-role specialization of the one shared message representation. */
+interface UserMessage extends Message {
+  readonly role: 'user';
+}
+/** A model-produced assistant specialization of the shared message representation. */
+interface AssistantMessage extends Message {
+  readonly role: 'assistant';
+  readonly source: ModelMessageSource;
+}
+/** A tool-result specialization whose model-facing block retains call correlation. */
+interface ToolResultMessage extends Message {
+  readonly role: 'user';
+  readonly content: [ToolResultBlock];
+  readonly source: ToolMessageSource;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/types.d.ts
+declare module '@deepseek-ai/cordis' {
+  interface Events {
+    /**
+     * The provider topology changed: an adapter registered or unregistered
+     * routes, or the configurable-provider directory gained or lost entries.
+     * This payload-free registry notification fires at each commit point
+     * (including registration disposal); consumers re-read `listProviders()`,
+     * `listModels()`, or `listConfigurableProviders()` for the new state.
+     * Observer failures are contained and cannot veto the registry mutation.
+     * @mode emit
+     */
+    'llm/adapters-updated'(): void;
+  }
+}
+/** Serializable provider or transport failure facts; policy decides whether they are retryable. */
+interface LlmFailure {
+  /** Human-readable provider or transport failure. */
+  readonly message: string;
+  /** Stable provider-neutral machine-routing code. */
+  readonly code: string;
+  /** HTTP status returned by the provider, when available. */
+  readonly status?: number;
+  /** Provider-requested delay in milliseconds, when valid and available. */
+  readonly providerRetryAfterMs?: number;
+  /** Opaque provider-issued request identifier for diagnostics. */
+  readonly requestId?: ProviderRequestId;
+}
+/** Plain text visible to the end user. */
+interface TextBlock {
+  type: 'text';
+  text: string;
+}
+/** Reasoning / thinking content, distinct from visible text. */
+interface ReasoningBlock {
+  type: 'reasoning';
+  text: string;
+}
+/**
+ * A durable raster image reference, valid in user or assistant content. The
+ * block is deliberately role-neutral; assistant-side rendering is forward
+ * compatibility — the current production adapters declare text-only output,
+ * so only user content carries images today.
+ */
+interface ImageBlock {
+  type: 'image';
+  /** Immutable bytes and intrinsic display metadata owned by the attachment service. */
+  attachment: ImageAttachmentRef;
+}
+/** A tool invocation requested by the model. */
+interface ToolCallBlock {
+  type: 'tool-call';
+  /** Provider-issued call id; correlates with the matching tool result. */
+  id: CallId;
+  name: string;
+  /** Raw JSON string as produced by the model. */
+  arguments: string;
+}
+/** The result of a tool invocation, sent back to the model. */
+interface ToolResultBlock {
+  type: 'tool-result';
+  toolCallId: CallId;
+  content: ContentBlock[];
+  isError?: boolean;
+}
+/**
+ * Merge-extensible content blocks keyed by `type`. New core blocks must land
+ * with adapter, UI, and compaction support.
+ */
+interface ContentBlockMap {
+  'text': TextBlock;
+  'reasoning': ReasoningBlock;
+  'image': ImageBlock;
+  'tool-call': ToolCallBlock;
+  'tool-result': ToolResultBlock;
+}
+/** The block `type` tag vocabulary; widens as plugins add entries to {@link ContentBlockMap}. */
+type ContentBlockType = keyof ContentBlockMap;
+/** Any known content block, derived from {@link ContentBlockMap}; switch on `type` and fall through unknowns (merge-extensible). */
+type ContentBlock = ContentBlockMap[ContentBlockType];
+/**
+ * Why a model response stopped.
+ * Merge-extensible so adapters can surface provider-specific reasons.
+ */
+interface FinishReasonMap {
+  'stop': {
+    kind: 'stop';
+  };
+  'tool-calls': {
+    kind: 'tool-calls';
+  };
+  'max-tokens': {
+    kind: 'max-tokens';
+  };
+  'aborted': {
+    kind: 'aborted';
+    failure: LlmFailure;
+  };
+  'error': {
+    kind: 'error';
+    failure: LlmFailure;
+  };
+}
+/** Any known finish reason, derived from {@link FinishReasonMap}; switch on `kind` and fall through unknowns (merge-extensible). */
+type FinishReason = FinishReasonMap[keyof FinishReasonMap];
+/**
+ * Token accounting for one model call (cache fields are optional).
+ *
+ * Counts are DISJOINT: `inputTokens` is uncached input only; cached input is
+ * reported separately as `cacheReadTokens`/`cacheWriteTokens` (billed input =
+ * sum of the three). Adapters whose providers fold cache hits into a total
+ * prompt count (DeepSeek's `prompt_tokens`) subtract them out.
+ */
+interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  reasoningTokens?: number;
+}
+/** Display metadata for one registered provider route. */
+interface LlmProviderInfo {
+  /** Provider route key used by {@link GenerateOptions.provider}. */
+  id: string;
+  /** Human-readable provider name for selectors and diagnostics. */
+  name: string;
+}
+/** Merge-extensible provider model modality vocabulary. */
+interface ModelModalityMap {
+  text: 'text';
+  image: 'image';
+}
+/** Any declared provider model modality. */
+type ModelModality = ModelModalityMap[keyof ModelModalityMap];
+/**
+ * One provider route an adapter plugin can activate through configuration,
+ * whether or not the route is currently registered. Configuration surfaces
+ * merge this directory with `listProviders()` to offer every configurable
+ * provider alongside its live/dormant state.
+ */
+interface LlmConfigurableProvider {
+  /** Provider route key this entry activates when configured. */
+  provider: string;
+  /** Human-readable provider name for configuration surfaces. */
+  displayName: string;
+  /** User-settings namespace whose section configures this provider. */
+  settingsNs: string;
+  /**
+   * Path from that namespace's section root to this provider's profile
+   * object; empty when the whole section is the profile.
+   */
+  settingsPath: readonly string[];
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it — a gateway or self-hosted server it ships nothing about.
+   * Absent means the adapter draws no such distinction; false means it does
+   * and this route is one of its own. Only the adapter can answer: a stored
+   * profile is how a user-added route AND a corrected shipped one both look
+   * from outside.
+   */
+  declared?: boolean;
+}
+/**
+ * One interrogation of a provider endpoint that configuration has not stored
+ * yet. Configuration surfaces send the draft a user is still editing, so the
+ * request carries the endpoint and credential directly instead of naming a
+ * route: a provider being added has no route to name.
+ */
+interface LlmModelDiscoveryRequest {
+  /**
+   * Route the draft is editing, when it edits an existing one. A route whose
+   * adapter already knows its models answers from that knowledge instead of
+   * asking the endpoint — the adapter's own registry is the better answer, and
+   * it costs no network call.
+   */
+  provider?: string;
+  /**
+   * Endpoint to interrogate. Optional because a route the adapter already
+   * describes needs none; a route it does not must supply one.
+   */
+  baseURL?: string;
+  /** Wire protocol the endpoint speaks, when the draft names one. */
+  api?: string;
+  /** Credential for this interrogation alone; the harness never stores it. */
+  apiKey?: string;
+  /** Caller cancellation; implementations must settle promptly after it aborts. */
+  signal?: AbortSignal;
+}
+/**
+ * One model an endpoint reports about itself. Every field but the id is
+ * optional because most provider listings disclose an id and nothing else;
+ * a surface adopting one of these still owes the capacities its adapter needs.
+ */
+interface LlmDiscoveredModel {
+  /** Model id the endpoint accepts. */
+  id: string;
+  /** Human-readable name when the endpoint supplies one. */
+  name?: string;
+  /** Maximum combined request and response context, when disclosed. */
+  contextWindow?: number;
+  /** Maximum output tokens, when disclosed. */
+  maxTokens?: number;
+}
+/** One adapter-discovered model; catalog membership is advisory, not request validation. */
+interface LlmModelInfo {
+  /** Provider route that owns this model entry. */
+  provider: string;
+  /** Model id passed to {@link GenerateOptions.model}. */
+  id: string;
+  /** Human-readable model name for selectors. */
+  name: string;
+  /** Optional user-facing distinction from otherwise similar models. */
+  description?: string;
+  /** Accepted request modalities; absent means unknown, while an explicit omission is negative capability. */
+  inputModalities?: readonly ModelModality[];
+}
+/** Provider-owned context capacity for one exact provider/model route. */
+interface LlmModelContext {
+  /** Maximum combined request and response context in tokens. */
+  contextWindow: number;
+}
+/** Display metadata for one adapter-owned reasoning effort. */
+interface LlmReasoningEffortInfo {
+  /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */
+  id: ReasoningEffortId;
+  /** Human-readable effort name for selectors and diagnostics. */
+  name: string;
+  /** Optional user-facing distinction from otherwise similar efforts. */
+  description?: string;
+}
+/** Selectable reasoning efforts for one exact provider/model route. */
+interface LlmModelReasoningInfo {
+  /** Supported efforts in adapter-preferred display order. */
+  efforts: readonly LlmReasoningEffortInfo[];
+  /**
+   * Adapter-configured default materialized into requests when callers omit
+   * an effort. Absence preserves the provider's own default.
+   */
+  defaultEffort?: ReasoningEffortId;
+}
+/** Exact-route model metadata resolved by its owning adapter. */
+interface LlmResolvedModelInfo extends LlmModelInfo {
+  /** Provider-owned context capacity when known. */
+  context?: LlmModelContext;
+  /** Adapter-configured per-request output cap materialized when callers omit one. */
+  defaultMaxTokens?: number;
+  /** Adapter-owned selectable reasoning levels when exposed. */
+  reasoning?: LlmModelReasoningInfo;
+}
+/**
+ * Adapter-private lossless-JSON state for replaying a successful response,
+ * carried by a terminal `finish` chunk and stored on the assembled assistant
+ * message's model source. Both halves stay opaque to the harness; only the
+ * split is shared vocabulary, so assembly can keep stored metadata aligned
+ * with stored content without reading either half.
+ */
+interface ReplayEnvelope {
+  /** Response-level adapter-private metadata (ids, native stop reason). */
+  response: unknown;
+  /**
+   * Per-block adapter-private metadata, one entry per emitted block in
+   * first-seen stream order. When assembly drops a block it drops the entry at
+   * the same position; entries whose length does not match the emitted block
+   * count discard the whole envelope. An adapter whose metadata is independent
+   * of block structure omits this field and the envelope passes through
+   * assembly unchanged.
+   */
+  blocks?: readonly unknown[];
+}
+/**
+ * Raw streaming protocol emitted by adapters.
+ * Block indexes correlate interleaved deltas, and `block-end` carries the
+ * assembled block. Adapters emit usage before the terminal finish and nothing
+ * afterward; tool arguments remain raw JSON strings. An adapter implementation
+ * may throw, but `LlmRuntime.stream()` normalizes that failure to a terminal
+ * `error` or `aborted` finish before exposing it to consumers.
+ */
+type StreamChunk = {
+  type: 'block-start';
+  index: number;
+  blockType: ContentBlockType;
+} | {
+  type: 'text-delta';
+  index: number;
+  text: string;
+} | {
+  type: 'reasoning-delta';
+  index: number;
+  text: string;
+} | {
+  type: 'tool-call-delta';
+  index: number;
+  id: CallId;
+  name?: string;
+  argumentsDelta: string;
+} | {
+  type: 'block-end';
+  index: number;
+  block: ContentBlock;
+} | {
+  type: 'usage';
+  usage: TokenUsage;
+} | {
+  type: 'finish';
+  reason: FinishReason;
+  /** Replay metadata for a successful response; see {@link ReplayEnvelope}. */
+  replayState?: ReplayEnvelope;
+};
+/**
+ * JSON-schema description of a tool, as sent to the model.
+ *
+ * Declared here (not in dsh-tools) because it is part of {@link GenerateOptions};
+ * dsh-tools' ToolDefinition and dsh-system-prompt's PromptAssembly both import
+ * it from this package.
+ */
+interface ToolSchema {
+  name: string;
+  description: string;
+  /** JSON Schema object for the arguments. */
+  parameters: Record<string, unknown>;
+}
+/** A single model request, fully assembled. */
+interface GenerateOptions {
+  /** Registered provider route selecting the adapter instance. */
+  provider: string;
+  model: string;
+  /** Adapter-owned reasoning effort selected for this exact model. */
+  reasoningEffort?: ReasoningEffortId;
+  /**
+   * Ordered conversation messages, exactly as the provider sees them (after
+   * the `system` slot). A loop-built request assembles them as
+   * the derived history (dsh-agent-loop); a hand-built one-shot passes any list.
+   */
+  messages: Message[];
+  /** System prompt text (adapters map to the provider's system slot). */
+  system?: string;
+  /** Tool schemas (adapters map to the provider's `tools` field). */
+  tools?: ToolSchema[];
+  temperature?: number;
+  maxTokens?: number;
+  /**
+   * Stop sequences: generation halts as soon as the model produces any one of
+   * these strings (adapters map to the provider's stop field, e.g. OpenAI
+   * `stop`). The stop string itself is not included in the output.
+   */
+  stop?: string[];
+  signal?: AbortSignal;
+  /**
+   * Session identity stamped by the loop for request routing. Replay uses it
+   * to separate cursors; adapters may map it to model-hidden transport metadata.
+   */
+  sessionId?: Branded<'SessionId'>;
+  /**
+   * Provider-neutral classification for an auxiliary model call. Adapters may
+   * map the purpose to model-hidden transport metadata or purpose-specific
+   * generation policy. Ordinary conversation requests leave it unset.
+   */
+  purpose?: 'compaction' | 'session-title';
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/retry-policy.d.ts
+/** Fully resolved backoff shared by both retry modes. */
+interface ResolvedRetryBackoff {
+  readonly initialDelayMs: number;
+  readonly maxDelayMs: number;
+  readonly jitterRatio: number;
+}
+/** Fully resolved bounded transient retry policy. */
+interface ResolvedNormalRetryPolicy extends ResolvedRetryBackoff {
+  readonly mode: 'normal';
+  readonly maxRetries: number;
+  readonly retryableCodes: readonly string[];
+}
+/** Fully resolved unbounded retry policy. */
+interface ResolvedAlwaysRetryPolicy extends ResolvedRetryBackoff {
+  readonly mode: 'always';
+}
+/** Immutable provider policy captured when its adapter route is registered. */
+type ResolvedRetryPolicy = ResolvedNormalRetryPolicy | ResolvedAlwaysRetryPolicy;
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/call-config.d.ts
+/**
+ * Provider, model, reasoning effort, and sampling scalars of one conversation's
+ * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
+ * the loop builds requests from the logged header rather than accepting these
+ * per call.
+ */
+interface LlmCallConfig {
+  provider: string;
+  model: string;
+  reasoningEffort?: ReasoningEffortId;
+  temperature?: number;
+  maxTokens?: number;
+  stop?: string[];
+}
+/**
+ * Effective config fields supplied by exact-model adapter resolution rather
+ * than by the caller's request proposal.
+ */
+interface LlmCallConfigAdapterDefaults {
+  reasoningEffort?: true;
+  maxTokens?: true;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-llm/lib/types/index.d.ts
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    llm: LlmRuntime;
+  }
+  interface Events {
+    /**
+     * Waterfall around every streaming model call (retry, replay, routing).
+     * Bound to the {@link LlmRuntime}; call `next()` to reach the resolved
+     * adapter's stream, or yield your own chunks to short-circuit.
+     * @param options - the full request. A LOOP-built request carries the
+     *   process-local {@link markAgentLoopRequest} identity and arrives deep-frozen
+     *   (mutation throws): its content is a pure function of the session log (the
+     *   reconstructability Agent Note), so listeners read it, never rewrite it.
+     *   Hand-built calls do not carry that marker; their messages already obey
+     *   the immutable creation contract.
+     * @mode waterfall
+     */
+    'llm/stream'(this: LlmRuntime, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>;
+  }
+}
+/** One model call whose config and adapter registration were resolved together. */
+interface PreparedLlmCall {
+  /** Detached, deep-frozen config with any adapter-owned default materialized. */
+  readonly config: LlmCallConfig;
+  /** Immutable retry policy captured with the adapter registration. */
+  readonly retryPolicy: ResolvedRetryPolicy;
+  /** Detached context metadata resolved with the registration-bound call. */
+  readonly context?: LlmModelContext;
+  /** Exact model modalities captured with the adapter dispatch generation. */
+  readonly inputModalities?: readonly ModelModality[];
+  /** Config fields materialized by the captured adapter rather than proposed by the caller. */
+  readonly adapterDefaults: LlmCallConfigAdapterDefaults;
+  /**
+   * Dispatch this call once through the registration captured during
+   * preparation. The request's call-config fields must match {@link config};
+   * reuse or mismatch fails with `INVALID_PREPARED_CALL`.
+   * @param options - fully assembled request carrying the prepared config.
+   * @returns the chunk stream, including the `llm/stream` waterfall.
+   */
+  stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/** One adapter-owned model-resolution generation bound to its eventual stream call. */
+interface PreparedAdapterCall {
+  /** Exact model metadata from the same adapter generation as {@link stream}. */
+  readonly model: LlmResolvedModelInfo;
+  /** Dispatch through that generation without re-reading dynamic connection facts. */
+  stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/**
+ * Provider-wire adapter for the harness message and stream vocabulary. Register implementations
+ * with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
+ * `attributionHeaders()`; prove the headers are added in the wire request or library header hook. The direct-fetch
+ * DeepSeek and library-backed pi-ai adapters meet this contract through different internals.
+ */
+declare abstract class LlmAdapter {
+  /**
+   * Describe one provider route owned by this adapter.
+   * @param provider - a route passed to `registerAdapter()` for this instance.
+   * @returns detached display metadata whose id must equal `provider`.
+   */
+  providerInfo(provider: string): LlmProviderInfo;
+  /**
+   * Return the provider-owned retry policy captured with this route.
+   * @param _provider - a route passed to `registerAdapter()` for this instance.
+   * @returns a resolved policy, or `undefined` to use the normal defaults.
+   */
+  providerRetryPolicy(_provider: string): ResolvedRetryPolicy | undefined;
+  /**
+   * List models this adapter can currently advertise for one owned provider.
+   * The result is advisory: an adapter may accept unlisted model ids, and
+   * consumers must not turn absence into request rejection.
+   * @param _provider - one provider route owned by this adapter.
+   * @returns discoverable models in adapter-preferred order.
+   */
+  listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+  /**
+   * Resolve all metadata available for one exact model. This query is
+   * independent of the advisory catalog and does not validate request routing.
+   * @param provider - one provider route owned by this adapter.
+   * @param model - exact model id passed to {@link GenerateOptions.model}.
+   * @param _signal - cancellation for this exact-model lookup; asynchronous
+   *   implementations must settle promptly after it aborts.
+   * @returns provider/model identity plus any context, call-default, and reasoning metadata.
+   */
+  resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+  /**
+   * Bind exact model metadata and the eventual request dispatch to one adapter generation.
+   * Dynamic adapters override this so settings changes between preparation and
+   * dispatch cannot combine one generation's capabilities with another's endpoint.
+   * @param provider - registered provider route.
+   * @param model - exact model id.
+   * @param signal - cancellation for model resolution.
+   * @returns model metadata and a one-generation stream entry point.
+   */
+  prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+  /**
+   * Stream one model call as raw chunks. The only required method.
+   * @param options - the fully-assembled request; implementations must honor `options.signal`.
+   * @returns the chunk stream, obeying the adapter contract documented on `StreamChunk`.
+   */
+  abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/**
+ * What {@link LlmRuntime.registerAdapter} returns: the disposer, plus an
+ * atomic route replacement for the same adapter instance.
+ */
+interface AdapterRegistrationHandle {
+  /** Release every route this registration currently holds. */
+  (): void;
+  /**
+   * Replace this registration's routes with `providers`, keeping the same
+   * adapter instance. The candidate set is validated in full first — a
+   * conflict with another adapter, an invalid name, or bad provider metadata
+   * throws and leaves the current routes untouched — and the swap itself is
+   * one synchronous section, so no request can observe a gap. An empty array
+   * is legal here (a settings section that emptied holds zero routes while
+   * staying registered), unlike an empty initial registration.
+   *
+   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
+   * has been released: its routes are gone and its disposer has already run,
+   * so anything registered afterwards would have no owner left to release it.
+   * @param providers - the complete next route set for this registration.
+   */
+  replace(providers: string[]): void;
+}
+/**
+ * A live configurable-provider registration, disposable and atomically
+ * replaceable — the directory counterpart of {@link AdapterRegistrationHandle}.
+ */
+interface DirectoryRegistrationHandle {
+  /** Withdraw every entry this registration currently holds. */
+  (): void;
+  /**
+   * Replace this registration's entries with `entries`. The candidate set is
+   * validated in full first — an entry another registration already declares,
+   * a duplicate within the set, or invalid metadata throws and leaves the
+   * current entries untouched — and the swap is one synchronous section, so no
+   * reader observes a gap. An empty array is legal here, unlike an empty
+   * initial registration.
+   *
+   * Throws `LlmError` with code `REGISTRATION_DISPOSED` once the registration
+   * has been disposed.
+   */
+  replace(entries: readonly LlmConfigurableProvider[]): void;
+}
+/**
+ * The abstract `llm` service: an adapter registry plus a streaming model-call
+ * API, interceptable via the `llm/stream` waterfall.
+ */
+declare class LlmRuntime extends Service {
+  private adapters;
+  private directory;
+  private discoveries;
+  constructor(ctx: Context);
+  /** Notify topology observers without letting one broken listener veto the commit. */
+  private emitAdaptersUpdated;
+  /** Contained-listener diagnostic shared by the sync and async failure paths. */
+  private warnAdaptersListenerFailure;
+  /**
+   * Register an adapter for the given provider routes. Throws `LlmError` with code
+   * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
+   * Disposed with the fiber.
+   * @param providers - every provider route this adapter should serve.
+   * @param adapter - the adapter that streams calls for those providers.
+   * @returns the disposer, carrying {@link AdapterRegistrationHandle.replace}.
+   */
+  registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle;
+  /**
+   * Validate one candidate route set for `adapter`, treating routes this
+   * registration already holds as available. Nothing is mutated: a rejected
+   * candidate leaves the registry exactly as it was.
+   */
+  private prepareRoutes;
+  /**
+   * Swap this registration's routes for the prepared ones in one synchronous
+   * section, so no observer can see the registry between the release and the
+   * re-registration. The route set's one mutation point is also where
+   * `llm/adapters-updated` is published, so a `replace` announces itself
+   * exactly like a first registration.
+   */
+  private commitRoutes;
+  /**
+   * Describe provider routes with a registered adapter.
+   * @returns detached provider metadata in registration order.
+   */
+  listProviders(): LlmProviderInfo[];
+  /**
+   * Declare provider routes an adapter plugin can activate through
+   * configuration. Registration is all-or-nothing: an empty list, invalid
+   * entry, or a provider already declared by any registration throws
+   * `LlmError` without registering the rest. Disposed with the fiber.
+   * @param entries - every configurable provider this plugin owns.
+   * @returns a handle that withdraws all of them, and can atomically replace them.
+   */
+  registerConfigurableProviders(entries: readonly LlmConfigurableProvider[]): DirectoryRegistrationHandle;
+  /**
+   * List every declared configurable provider, registered or dormant.
+   * @returns detached directory entries in declaration order.
+   */
+  listConfigurableProviders(): LlmConfigurableProvider[];
+  /**
+   * Offer to interrogate provider endpoints on behalf of the settings
+   * namespace this plugin owns. The namespace is the key because that is what
+   * a configuration surface already holds from the configurable-provider
+   * directory, and because a provider being *added* has no route to name yet.
+   * Disposed with the fiber.
+   * @param settingsNs - the namespace whose profiles this discovery serves.
+   * @param discover - interrogates one endpoint; must honor `request.signal`.
+   * @returns the disposer that withdraws the offer.
+   */
+  registerModelDiscovery(settingsNs: string, discover: (request: LlmModelDiscoveryRequest) => Promise<readonly LlmDiscoveredModel[]>): () => void;
+  /**
+   * Interrogate one provider endpoint for the models it advertises. The
+   * request describes a draft, not a stored route, so nothing here reads or
+   * writes settings or credentials — the caller owns both, and the reply is
+   * candidate metadata a surface may offer for adoption.
+   * @param settingsNs - namespace whose registered discovery serves this draft.
+   * @param request - the endpoint, protocol, and one-shot credential to use.
+   * @returns the advertised models, deduplicated in endpoint order.
+   */
+  discoverModels(settingsNs: string, request: LlmModelDiscoveryRequest): Promise<LlmDiscoveredModel[]>;
+  /**
+   * Resolve the retry policy captured when one provider route was registered.
+   * @param provider - registered provider route to inspect.
+   * @returns the provider-owned policy, with normal defaults already resolved.
+   */
+  providerRetryPolicy(provider: string): ResolvedRetryPolicy;
+  /** Detach typed adapter-owned modality metadata. */
+  private detachedModalities;
+  /**
+   * Discover models advertised by one registered provider. Catalog membership
+   * is advisory and never changes routing or request validation.
+   * @param provider - registered provider route to inspect.
+   * @returns detached model metadata in adapter-preferred order.
+   */
+  listModels(provider: string): Promise<LlmModelInfo[]>;
+  /**
+   * Resolve and validate all metadata from the adapter that owns one exact
+   * route. The result is detached from adapter-owned objects; catalog
+   * membership remains advisory and does not control request routing.
+   * @param provider - registered provider route to inspect.
+   * @param model - exact model id passed to the adapter.
+   * @param signal - optional cancellation for adapter-owned asynchronous lookup.
+   * @returns exact model identity plus available context and reasoning metadata.
+   */
+  resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+  private resolveModelInfoFor;
+  /** Validate and detach one adapter-returned exact model result. */
+  private normalizeModelInfo;
+  /**
+   * Validate a conversation call config against its exact model capability and
+   * materialize adapter-configured defaults. Unsupported explicit efforts
+   * reject before provider I/O; no clamping or aliasing is performed. This
+   * standalone query does not bind a later dispatch; use {@link prepareCall}
+   * when logging and streaming must share one adapter registration.
+   * @param config - provider/model route and optional request controls.
+   * @param signal - optional cancellation for adapter-owned capability lookup.
+   * @returns a detached config only when a default must be materialized.
+   */
+  resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>;
+  private resolveCallFor;
+  /** Validate request controls against one already-bound exact model result. */
+  private resolveCallWithInfo;
+  /**
+   * Resolve one call under its current adapter registration. The returned
+   * one-shot handle keeps that registration across header logging and dispatch,
+   * so HMR cannot combine one adapter's capability result with another adapter.
+   * @param config - provider/model route and optional request controls.
+   * @param signal - optional cancellation for adapter-owned capability lookup.
+   * @returns a prepared config and its registration-bound stream entry point.
+   */
+  prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>;
+  private registration;
+  /** Remove replay state whose historical route is owned by another adapter. */
+  private forAdapter;
+  /**
+   * Final adapter boundary. Adapter selection, dispatch, iterator construction,
+   * and iteration failures become one terminal failure chunk. Middleware and
+   * downstream consumer failures remain thrown plugin or consumer errors.
+   */
+  private adapterStream;
+  /**
+   * Stream one model call as raw chunks (token-level deltas). Replay state is
+   * retained only when the same adapter instance owns its historical provider
+   * and the target provider. Final adapter selection remains fixed through
+   * asynchronous exact-model resolution and dispatch. Adapter selection,
+   * dispatch, and iteration failures become terminal `error` or `aborted`
+   * finish chunks; middleware, nested-call, cleanup, and consumer failures
+   * remain thrown.
+   * @param options - the full request; `options.provider` selects the adapter.
+   * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
+   */
+  stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+  private streamWithRegistration;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-scope/lib/types/index.d.ts
+declare const ScopedBrand: unique symbol;
+/**
+ * A routing-only event receiver built by {@link scopeTarget}. The type
+ * parameter records the subject type for dispatch checking; the carrier does
+ * not expose the subject's properties. Event payloads carry the real subject.
+ */
+type Scoped<T extends object> = object & {
+  readonly [ScopedBrand]: T;
+};
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-session/lib/types/json.d.ts
+/** Lossless-JSON validation and detached snapshots for durable session data. @module @deepseek-ai/dsh-session/json */
+/**
+ * A value that round-trips losslessly through JSON: `null`, a boolean, a finite
+ * number other than negative zero, a string, an array of such values, or a
+ * plain object whose values are such values. Arrays may carry only their dense
+ * indexed elements; extra own properties would be discarded by JSON. TypeScript
+ * cannot distinguish `-0` from `number`, so {@link isJsonValue} and
+ * {@link snapshotJsonValue} enforce these details at runtime. Use this type for
+ * a payload that must survive session-log persistence and replay byte-identically
+ * — e.g. a tool's private presentation `meta`.
+ */
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-session/lib/types/types.d.ts
+/** Identifies one session in the store (and its persistence artifacts). */
+type SessionId = Branded<'SessionId'>;
+/**
+ * Brand a string as a {@link SessionId}.
+ * @param id - the raw session id string.
+ * @returns the same string, branded (a compile-time cast — no runtime cost).
+ */
+declare function SessionId(id: string): SessionId;
+/**
+ * Immutable validated storage metadata, kept outside the conversation event log.
+ */
+interface SessionHeader {
+  /**
+   * On-disk format version, stamped from {@link SESSION_FORMAT_VERSION} when the
+   * session is created. A persistence backend rejects any other version on load
+   * (no migration — see the constant).
+   */
+  readonly version: number;
+  /** The session's id (mirrors the {@link Session}'s id). */
+  readonly id: SessionId;
+  /** Non-negative safe-integer Unix epoch milliseconds when the session was created. */
+  readonly createdAt: number;
+  /** Absolute working directory the session was created in (if any). */
+  readonly cwd?: string;
+  /** The session this one was forked from (seed lineage), if any. */
+  readonly parentSession?: SessionId;
+  /**
+   * How many leading events were inherited through a seed. Persisting this
+   * boundary lets resume and replay distinguish parent history from child work.
+   */
+  readonly seedLength?: number;
+  /**
+   * Coarse product classification for a session created as a subagent child.
+   * This is presentation metadata, not proof that the child is continuable.
+   */
+  readonly origin?: 'subagent';
+  /**
+   * Delegation depth: absent (zero) for a top-level session, parent depth + 1
+   * for a subagent child. Persisted so a recursion budget survives restart and
+   * resume — a runtime-only depth would reset a resumed child to top-level.
+   */
+  readonly delegationDepth?: number;
+  /**
+   * Id of the agent preset this session's agent was composed from, when the
+   * deployment composes per session. Durable because the preset decides the
+   * session's tools and prompt: a resume that restored a different composition
+   * would replay history the model can no longer act on.
+   */
+  readonly agentPreset?: string;
+}
+/**
+ * Options for creating a {@link Session} via the store. `seed` replays/forks
+ * an existing event log; `meta` carries the caller-supplied storage fields the
+ * store folds into a {@link SessionHeader}.
+ */
+interface CreateSessionOptions {
+  /** Initial replay or fork history supplied at construction. */
+  readonly seed?: readonly SessionEvent[];
+  /**
+   * Storage metadata read once before publication. `seedLength` is explicit
+   * because a resumed seed contains the full stored log, not only its inherited prefix.
+   */
+  readonly meta?: {
+    readonly cwd?: string;
+    readonly parentSession?: SessionId;
+    readonly createdAt?: number;
+    readonly seedLength?: number;
+    readonly origin?: 'subagent';
+    readonly delegationDepth?: number;
+    readonly agentPreset?: string;
+  };
+}
+/**
+ * Fresh storage values transferred to {@link SessionStore.prepare} without a
+ * second serialization copy. Callers retain no mutable aliases.
+ */
+interface RestoredSessionOptions {
+  /** Fresh detached storage events to validate and freeze in place. */
+  readonly seed: SessionEvent[];
+  /** Fresh detached storage metadata to validate and freeze in place. */
+  readonly meta: SessionHeader;
+  /** Select the persistence ownership-transfer path. */
+  readonly seedSource: 'persistence';
+}
+/** Inputs accepted while constructing an unpublished Session. */
+type PrepareSessionOptions = (CreateSessionOptions & {
+  readonly seedSource?: undefined;
+}) | RestoredSessionOptions;
+/** Why an active agent driver was cancelled. */
+type AgentCancelCause = {
+  readonly kind: 'user';
+} | {
+  readonly kind: 'parent';
+} | {
+  readonly kind: 'hook';
+  readonly reason: string;
+} | {
+  readonly kind: 'disposed';
+};
+/** Durable cancellation cause, including imports whose original coarse record carried no cause. */
+type TurnEndCancelCause = AgentCancelCause | {
+  readonly kind: 'legacy';
+};
+/**
+ * Why a turn ended. Merge-extensible sum type.
+ */
+interface TurnEndReasonMap {
+  completed: {
+    kind: 'completed';
+  };
+  /** A cancellation request interrupted the live turn. */
+  aborted: {
+    kind: 'aborted';
+    reason: TurnEndCancelCause;
+  };
+  blocked: {
+    kind: 'blocked';
+  };
+  /**
+   * The turn failed. `error` is always a structured failure: the `LlmError`
+   * facts verbatim, or `{ message: errorChain(error), code: 'UNKNOWN' }`
+   * flattened from any other error.
+   */
+  error: {
+    kind: 'error';
+    error: LlmFailure;
+  };
+  /** At least one step reached its output-token ceiling, even if a plugin continued the turn. */
+  'max-tokens': {
+    kind: 'max-tokens';
+  };
+  /**
+   * A persistence backend closed a crash-orphaned turn on reload. The loop never
+   * emits this marker, and the events recorded before the crash remain intact.
+   */
+  interrupted: {
+    kind: 'interrupted';
+  };
+}
+/** The union over {@link TurnEndReasonMap} — why a turn ended; plugins extend it by merging variants into the map. */
+type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];
+/**
+ * One entry in an agent's todo list — the unit of the `todo/write`
+ * {@link SessionEventMap} event's whole-list snapshot.
+ *
+ * Deliberately minimal: a human-readable `content` line and a three-state
+ * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
+ * on every write (last-write-wins), so entries need no stable identity. The
+ * three statuses describe the complete portable lifecycle needed by model and
+ * UI consumers.
+ */
+interface TodoItem {
+  /** What this task is — a short imperative line shown in the UI. */
+  content: string;
+  /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
+  status: 'pending' | 'in_progress' | 'completed';
+}
+/**
+ * Logged request state outside derived history: call config, system prompt, and
+ * tools. The latest full `request/header` snapshot reconstructs it; canonical
+ * empty optional fields are absent.
+ */
+interface EpochHeader {
+  /** The conversation's call configuration (provider, model, reasoning effort, and sampling scalars). */
+  config: LlmCallConfig;
+  /** Effective config fields materialized from the exact adapter rather than proposed by a caller. */
+  adapterDefaults?: LlmCallConfigAdapterDefaults;
+  /** Rendered system prompt text; absent for a system-less request. */
+  system?: string;
+  /** Assembled tool schemas; absent for a tool-less request. */
+  tools?: ToolSchema[];
+}
+/** Registration-bound metadata for one resolved model route. */
+interface RequestContext {
+  /** Registered provider route the metadata belongs to. */
+  provider: string;
+  /** Provider-owned model id the metadata belongs to. */
+  model: string;
+  /** Maximum combined request and response context in tokens, when advertised. */
+  contextWindow?: number;
+}
+/**
+ * Why a `request/header` snapshot was appended: `'initial'` — the log's first
+ * header (a new conversation); `'resume'` — a loop instance's first request
+ * over a log that already has header events (process restart, fork seed);
+ * `'change'` — a later request used a different header.
+ */
+type RequestHeaderReason = 'initial' | 'resume' | 'change';
+/**
+ * The merge-extensible, append-only source of truth for an agent interaction.
+ * Message history is derived from this log. Every event is lossless JSON and
+ * sequence numbers stay contiguous, including raw chunks, so persistence can
+ * store the canonical log verbatim.
+ */
+interface SessionEventMap {
+  /**
+   * Opens turn `turn` before the loop claims queued input or runs pre-step.
+   * Rejection, empty input, cancellation, or failure may close it with no
+   * step; otherwise the following identified `user/message` event or batch
+   * records the messages entering the step.
+   */
+  'turn/start': {
+    turn: number;
+  };
+  /**
+   * Closes turn `turn` with the {@link TurnEndReason} that ended it. A turn
+   * with no entered step has no `step/start` or `step/end`. The loop does not await a
+   * flush at turn boundaries: `dsh-session-checkpoint-policy` owns the
+   * per-request durability checkpoint, and consumers that read storage after
+   * `whenIdle()` flush themselves. Success commits the turn; rejection is
+   * reported live and does not prevent later work.
+   */
+  'turn/end': {
+    turn: number;
+    reason: TurnEndReason;
+  };
+  /** Opens step `step` of turn `turn` — one model call plus the tool executions it requested. */
+  'step/start': {
+    turn: number;
+    step: number;
+  };
+  /** Closes step `step` of turn `turn`. */
+  'step/end': {
+    turn: number;
+    step: number;
+  };
+  /**
+   * A user-role message on the model-visible surface: a direct human prompt
+   * (the queued message claimed for this turn), a synthetic `agent.inject()`
+   * context (file-change notices, subdir AGENTS.md, skill content, cron
+   * notifications, …), or an entered goal continuation round. All three
+   * project their `content` verbatim; `source` tells them apart.
+   */
+  'user/message': UserMessage;
+  /** Raw stream chunk — token-level replay fidelity. */
+  'assistant/chunk': {
+    turn: number;
+    step: number;
+    chunk: StreamChunk;
+  };
+  /**
+   * Assembled assistant message for one step (derived history uses this).
+   * Carries the step's `usage` when the adapter reported token accounting, so
+   * the model output and its accounting travel together (there is no separate
+   * usage record). `usage` is absent when the adapter reported none. A turn
+   * cancelled mid-stream finalizes its delivered text/reasoning prefix as this
+   * event with `interrupted: true`; undispatched tool calls are absent. The
+   * marker distinguishes that prefix without re-deriving interruption from turn
+   * boundaries. An aborted turn with no such event streamed no visible content.
+   */
+  'assistant/message': {
+    turn: number;
+    step: number;
+    message: AssistantMessage;
+    usage?: TokenUsage;
+    interrupted?: true;
+  };
+  /**
+   * The model requested one tool invocation: `name` with the raw `arguments`
+   * JSON string exactly as the model produced it (unparsed). `callId` pairs the
+   * call with its `tool/result`.
+   */
+  'tool/call': {
+    turn: number;
+    step: number;
+    callId: CallId;
+    name: string;
+    arguments: string;
+  };
+  /**
+   * A completed tool call's model-facing result, optional internal failure
+   * identity, and optional tool-private `meta` presentation payload. `meta` is
+   * opaque to the core (the producing tool owns its shape and reads it back in
+   * `presentResult`) but MUST be JSON-serializable: `Session.append`
+   * runtime-validates all event data with `isJsonValue`, so a non-serializable
+   * `meta` is rejected at the source, and the durable log reproduces the
+   * identical card on replay. Absent
+   * unless the tool attaches one (e.g. `dsh-tool-fs` carries its result-time
+   * contextual diff here).
+   */
+  'tool/result': {
+    turn: number;
+    step: number;
+    message: ToolResultMessage;
+    error?: {
+      name: string;
+      code: string;
+    };
+    meta?: JsonValue;
+  };
+  /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
+  'todo/write': {
+    todos: TodoItem[];
+  };
+  /**
+   * Full header for the next request, appended inside its step before dispatch.
+   * It is log-only; the latest snapshot reconstructs the request header.
+   */
+  'request/header': {
+    header: EpochHeader;
+    reason: RequestHeaderReason;
+  };
+  /**
+   * Route metadata for the next request, logged only when the route or capacity
+   * changes. It does not participate in request reconstruction or header equality.
+   */
+  'request/context': RequestContext;
+  /**
+   * Marks the end of a constructor seed. Events before it have smaller seq
+   * values and came from the seed (resume, fork, or replay); this lifecycle
+   * produced none of them. This log-only event is the durable projection of
+   * {@link Session.firstLiveSeq}. Its payload is empty — position and `time`
+   * carry the meaning.
+   *
+   * Locate the LAST one in stored history. A seed already ending in one is not
+   * re-marked, so reopening an untouched session does not grow its log per
+   * pickup and the event need not be at the current `firstLiveSeq`.
+   *
+   * `Session`'s constructor is the only legitimate writer. The invariant
+   * companion deliberately constrains nothing here, so a plugin appending one
+   * would silently classify every live bracket before it as seed history.
+   *
+   * An owner of a standalone open/close bracket (`compaction/start` …
+   * `compaction/end`) reads it because seed history and live work are otherwise
+   * byte-identical: an unmatched opening marker before this event belongs to
+   * an ended lifecycle, whatever ended it. NOT a liveness signal about other
+   * writers — a concurrently live session holds its own boundary elsewhere,
+   * so tolerating concurrent writers needs a signal beyond the log.
+   */
+  'session/end-seed': Record<string, never>;
+}
+/** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */
+type SessionEventType = keyof SessionEventMap;
+/**
+ * The subset of {@link SessionEventType} values whose events produce LLM
+ * messages and are eligible to appear on the ordered surface. Only these
+ * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
+ */
+type SurfaceEventType = 'user/message' | 'assistant/message' | 'tool/result';
+/**
+ * How a session event entered the ordered surface. Only valid on
+ * {@link SurfaceEventType} events.
+ *
+ * - `'append'`: added to the tail — normal path for user/assistant/tool
+ *   messages.
+ * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
+ *   (inclusive) through `end` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `start === end` replaces a single
+ *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
+ *   shadowed surface node. Used by compaction; any surface-replacing producer
+ *   may use it.
+ */
+type SurfaceOp = 'append' | {
+  op: 'replace';
+  start: number;
+  end: number;
+};
+/**
+ * Surface placement and cited source-event seqs for {@link Session.append}. Required on
+ * message-producing events and forbidden on log-only events.
+ */
+interface SurfaceIntent {
+  surfaceOp: SurfaceOp;
+  /**
+   * Complete set of known source-event seqs. `assistant/message` may use a
+   * present empty array for a known empty provider stream; when the field is
+   * absent, the event does not record which earlier events produced the message.
+   * Other surface events require a non-empty set when this field is present.
+   */
+  sourceEventSeqs?: number[];
+}
+/**
+ * One immutable entry in the session log.
+ *
+ * A proper discriminated union over `type` (not independent `type`/`data`
+ * unions), so `switch (event.type)` narrows `event.data` without casts.
+ *
+ * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
+ * they only exist on {@link SurfaceEventType} variants (`user/message`,
+ * `assistant/message`, `tool/result`).
+ * Non-surface events (boundary markers, chunks, usage, errors) never carry
+ * surface metadata — the compiler enforces this at `Session.append()`
+ * call sites.
+ */
+type SessionEvent<T extends SessionEventType = SessionEventType> = { [K in SessionEventType]: {
+  type: K;
+  /** Monotonic sequence number within the session. */
+  seq: number;
+  /** Unix epoch milliseconds. */
+  time: number;
+  data: SessionEventMap[K];
+  /**
+   * Marks an event a reader may safely skip when it does not recognize
+   * `type`. Absent means required: a reader meeting an unrecognized type
+   * without this marker MUST refuse to reconstruct the session instead of
+   * silently dropping the event, because an unrecognized required event may
+   * change how the rest of the log is interpreted. A writer sets `true` only
+   * on purely informational records whose loss cannot affect reconstruction;
+   * defaulting to required means a forgotten marker over-refuses (an
+   * inconvenience) rather than silently resuming a gutted session.
+   */
+  ignorable?: true;
+} & (K extends SurfaceEventType ? {
+  /**
+   * Seq numbers of earlier events that this event cites as sources
+   * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
+   * or the surface nodes shadowed by a compaction replace node). An
+   * `assistant/message` may carry a present empty array for a known empty
+   * provider stream; when the field is absent, the event does not record which
+   * earlier events produced the message.
+   */
+  sourceEventSeqs?: number[];
+  /** How this event entered the surface; absent for non-surface events. */
+  surfaceOp?: SurfaceOp;
+} : object); }[T];
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-typert-protocol/lib/types/types.d.ts
+declare const LOOKUP_HOST: unique symbol;
+declare const LOOKUP_WIRE: unique symbol;
+declare const CONTEXT_WIRE: unique symbol;
+/** Type-level association between a Host object and its wire identity. */
+interface TypertLookup<Host, Wire> {
+  readonly [LOOKUP_HOST]: Host;
+  readonly [LOOKUP_WIRE]: Wire;
+}
+/** Extract the Host object associated with one lookup declaration. */
+type TypertLookupHost<Lookup> = Lookup extends TypertLookup<infer Host, infer _Wire> ? Host : never;
+/** Extract the wire identity associated with one lookup declaration. */
+type TypertLookupWire<Lookup> = Lookup extends TypertLookup<infer _Host, infer Wire> ? Wire : never;
+/** Type-level association between a scoped Context kind and its wire identity. */
+interface TypertContext<Wire> {
+  readonly [CONTEXT_WIRE]: Wire;
+}
+/** Extract the wire identity associated with one scoped Context declaration. */
+type TypertContextWire<ContextType> = ContextType extends TypertContext<infer Wire> ? Wire : never;
+/** Merge-extensible Host object lookup declarations. */
+interface TypertLookupMap {}
+/** Merge-extensible scoped Context declarations. */
+interface TypertContextMap {}
+/** Awaitable disposer returned by Cordis-owned Typert registrations. */
+type TypertDisposer = () => Promise<void>;
+type StringKeyOf<Value> = Extract<keyof Value, string>;
+/** Minimal runtime-schema capability carried by strict generated codecs. */
+interface TypertSchema<Output = unknown> {
+  /**
+   * Parse and validate one boundary value.
+   * @param value - untrusted boundary value.
+   * @returns the validated value.
+   */
+  parse(value: unknown): Output;
+}
+/** Codec attached to one invocation parameter or result. */
+type TypertCodec = {
+  readonly mode: 'strict';
+  readonly typeSymbol: string;
+  readonly schema: TypertSchema;
+} | {
+  readonly mode: 'src-json';
+};
+/** One ordered business parameter in a Remote invocation. */
+interface InvocationParameterDescriptor {
+  /** Source-level parameter name. */
+  readonly name: string;
+  /** Required key in the wire `args` object. */
+  readonly wire: string;
+  /** Whether the value is JSON or requires a registered Host lookup. */
+  readonly source: 'json' | 'lookup';
+  /** Lookup key when `source` is `lookup`. */
+  readonly lookup?: string;
+  /** Boundary codec for the wire representation. */
+  readonly codec: TypertCodec;
+  /** Missing wire fields decode to `undefined` only for an explicitly declared `T | undefined`. */
+  readonly acceptsUndefined?: true;
+}
+/** Source position retained for diagnostics from generated definitions. */
+interface InvocationSourceLocation {
+  readonly file: string;
+  readonly line: number;
+  readonly column: number;
+}
+/** Carrier-independent description of one exported method invocation. */
+interface InvocationDescriptor {
+  /** Globally stable generated identity. */
+  readonly id: string;
+  /** Cordis service key owning the method. */
+  readonly service: string;
+  /** Wire namespace, defaulting to the service key. */
+  readonly namespace: string;
+  /** Public instance method name. */
+  readonly method: string;
+  /** Service member invoked when the exported method name is an alias. */
+  readonly implementation?: string;
+  /** Receiver selection mode. */
+  readonly invocation: {
+    readonly kind: 'direct';
+  } | {
+    readonly kind: 'context';
+    readonly context: string;
+    readonly wire: string;
+    readonly codec: TypertCodec;
+  };
+  /** Optional consuming-Context projection for one direct lookup parameter. */
+  readonly scope?: {
+    /** Context kind whose Client binder supplies the identity. */
+    readonly context: string;
+    /** Lookup parameter wire field replaced by the Context identity. */
+    readonly wire: string;
+  };
+  /** Ordered business parameters. */
+  readonly parameters: readonly InvocationParameterDescriptor[];
+  /** Transport cancellation injected after business parameters instead of entering wire args. */
+  readonly cancellation?: {
+    /** Reserved final Host method parameter. */
+    readonly parameter: 'signal';
+  };
+  /** Codec for the resolved method result. */
+  readonly result: TypertCodec;
+  /** Source declaration used only for diagnostics. */
+  readonly sourceLocation?: InvocationSourceLocation;
+}
+/** Generated Host contract selected explicitly by a Client assembly. */
+interface TypertRemoteContribution {
+  /** npm package that owns the Remote methods. */
+  readonly package: string;
+  /** Consumer-side invocation descriptors generated from that package. */
+  readonly descriptors: readonly InvocationDescriptor[];
+}
+/**
+ * Resolve one validated wire identity, synchronously or asynchronously.
+ * @param id - validated wire identity.
+ * @returns the Host object, or `undefined` when unavailable.
+ */
+type TypertLookupResolver<Host = unknown, Wire = unknown> = (id: Wire) => Host | undefined | Promise<Host | undefined>;
+/** Runtime provider for one declared Host object lookup. */
+interface TypertLookupProvider<Host = unknown, Wire = unknown> {
+  /** Source parameter name recognized by the SRC weak parser. */
+  readonly parameter: string;
+  /** Wire field replacing the Host object parameter. */
+  readonly wire: string;
+  /** Canonical Host type symbol used by strict generation. */
+  readonly hostTypeSymbol: string;
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string;
+  /**
+   * Resolve a wire identity through the provider's default policy.
+   * @param id - validated wire identity.
+   * @returns the object, `undefined` when unavailable, or either asynchronously.
+   */
+  resolve(id: Wire): Host | undefined | Promise<Host | undefined>;
+}
+/** Stable wire declaration retained after a lookup provider unloads. */
+interface TypertLookupDefinition {
+  /** Merge-declared lookup key. */
+  readonly key: string;
+  /** Source parameter name recognized by the SRC weak parser. */
+  readonly parameter: string;
+  /** Wire field replacing the Host object parameter. */
+  readonly wire: string;
+  /** Canonical Host type symbol used by strict generation. */
+  readonly hostTypeSymbol: string;
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string;
+}
+/** Host resolver for one scoped Remote kind. */
+interface TypertHostContextProvider<Wire = unknown> {
+  /** Wire field carrying the Context identity. */
+  readonly wire: string;
+  /** Canonical wire type symbol used by strict generation. */
+  readonly wireTypeSymbol: string;
+  /**
+   * Resolve a wire identity to its live scoped Context.
+   * @param id - validated wire identity.
+   * @returns the scoped Context, or `undefined` when unavailable.
+   */
+  resolve(id: Wire): Context | undefined | Promise<Context | undefined>;
+}
+/** Composition-owned resolver replacing one Host Context provider's default lookup policy. */
+type TypertHostContextResolver<Wire = unknown> = (id: Wire) => Context | undefined | Promise<Context | undefined>;
+/** Client resolver for the identity carried by the calling scoped Context. */
+interface TypertClientContextBinder<Wire = unknown> {
+  /**
+   * Read the Remote identity represented by a calling Context.
+   * @param ctx - Context rebound by the Cordis service tracker.
+   * @returns the wire identity, or `undefined` when the Context has the wrong scope.
+   */
+  identity(ctx: Context): Wire | undefined;
+}
+/** Notification emitted after a Typert runtime registry changes. */
+interface TypertRegistryChange {
+  readonly kind: 'local' | 'remote' | 'lookup' | 'host-context' | 'client-context';
+  readonly key: string;
+}
+/** Listener for one Typert runtime registry. */
+type TypertRegistryListener = (change: TypertRegistryChange) => void;
+/** Current-environment invocation definitions. */
+interface TypertLocalRegistry {
+  /**
+   * Look up one invocation by `<namespace>/<method>`.
+   * @param endpoint - canonical endpoint.
+   * @returns the live descriptor, or `undefined` when absent.
+   */
+  get(endpoint: string): InvocationDescriptor | undefined;
+  /**
+   * Report whether a strict definition has existed during this Typert Service lifetime.
+   * @param endpoint - canonical endpoint.
+   * @returns `true` after the endpoint has been registered at least once, even if withdrawn.
+   */
+  hasSeen(endpoint: string): boolean;
+  /** @returns a registration-order snapshot of local descriptors. */
+  list(): readonly InvocationDescriptor[];
+  /**
+   * Observe later local-definition changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypertRegistryListener): TypertDisposer;
+}
+/** Consumer-selected Remote contribution registry. */
+interface TypertRemoteRegistry {
+  /**
+   * Register one generated contribution for the calling Cordis fiber.
+   * @param contribution - generated Remote descriptors.
+   * @returns disposer withdrawing the exact contribution.
+   */
+  register(contribution: TypertRemoteContribution): TypertDisposer;
+  /**
+   * Look up one Remote descriptor by endpoint.
+   * @param endpoint - canonical endpoint.
+   * @returns the descriptor, or `undefined` when unmounted.
+   */
+  get(endpoint: string): InvocationDescriptor | undefined;
+  /** @returns a registration-order snapshot of Remote descriptors. */
+  list(): readonly InvocationDescriptor[];
+  /**
+   * Observe later Remote contribution changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypertRegistryListener): TypertDisposer;
+}
+/** Runtime registry for Host object lookup providers. */
+interface TypertLookupRegistry {
+  /**
+   * Register one provider under its merge-declared key.
+   * @param key - lookup key.
+   * @param provider - owning package's live resolver.
+   * @returns disposer withdrawing the exact provider.
+   */
+  register<K extends StringKeyOf<TypertLookupMap>>(key: K, provider: TypertLookupProvider<TypertLookupHost<TypertLookupMap[K]>, TypertLookupWire<TypertLookupMap[K]>>): TypertDisposer;
+  /**
+   * Replace one provider's default resolution policy while this contribution is active.
+   * Configuration may precede provider registration; without a live provider, `get()` remains unavailable.
+   * @param key - lookup key whose wire declaration remains provider-owned.
+   * @param resolver - composition-owned resolver used by every lookup of this key.
+   * @returns disposer restoring the provider's default resolver.
+   */
+  configure<K extends StringKeyOf<TypertLookupMap>>(key: K, resolver: TypertLookupResolver<TypertLookupHost<TypertLookupMap[K]>, TypertLookupWire<TypertLookupMap[K]>>): TypertDisposer;
+  /**
+   * Look up one provider by runtime key.
+   * @param key - descriptor lookup key.
+   * @returns the live provider, or `undefined` when absent.
+   */
+  get(key: string): TypertLookupProvider | undefined;
+  /** @returns lookup declarations observed during this Typert Service lifetime. */
+  definitions(): readonly TypertLookupDefinition[];
+  /** @returns a snapshot of registered provider keys. */
+  keys(): readonly string[];
+  /**
+   * Observe later lookup changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypertRegistryListener): TypertDisposer;
+}
+/** Runtime registry for Host Context resolvers and Client Context binders. */
+interface TypertContextRegistry {
+  /**
+   * Register a Host Context resolver.
+   * @param key - merge-declared Context key.
+   * @param provider - owning package's Host resolver.
+   * @returns disposer withdrawing the exact provider.
+   */
+  registerHost<K extends StringKeyOf<TypertContextMap>>(key: K, provider: TypertHostContextProvider<TypertContextWire<TypertContextMap[K]>>): TypertDisposer;
+  /**
+   * Override one Host Context key's identity policy for the calling fiber.
+   * Configuration may precede provider registration and restores the provider's default resolver on disposal.
+   * @param key - merge-declared Context key.
+   * @param resolver - composition-owned resolver used by every Host Context lookup of this key.
+   * @returns disposer restoring the provider's default resolver.
+   */
+  configureHost<K extends StringKeyOf<TypertContextMap>>(key: K, resolver: TypertHostContextResolver<TypertContextWire<TypertContextMap[K]>>): TypertDisposer;
+  /**
+   * Register a Client Context identity binder.
+   * @param key - merge-declared Context key.
+   * @param binder - Client scope identity resolver.
+   * @returns disposer withdrawing the exact binder.
+   */
+  registerClient<K extends StringKeyOf<TypertContextMap>>(key: K, binder: TypertClientContextBinder<TypertContextWire<TypertContextMap[K]>>): TypertDisposer;
+  /**
+   * Look up a Host Context resolver.
+   * @param key - descriptor Context key.
+   * @returns the provider, or `undefined` when absent.
+   */
+  getHost(key: string): TypertHostContextProvider | undefined;
+  /**
+   * Look up a Client Context binder.
+   * @param key - descriptor Context key.
+   * @returns the binder, or `undefined` when absent.
+   */
+  getClient(key: string): TypertClientContextBinder | undefined;
+  /**
+   * Observe later Context provider changes.
+   * @param listener - synchronous contained observer.
+   * @returns disposer for this subscription.
+   */
+  subscribe(listener: TypertRegistryListener): TypertDisposer;
+}
+/** Minimal Typert runtime consumed through dependency inversion. */
+interface TypertRegistryContract {
+  readonly local: TypertLocalRegistry;
+  readonly remotes: TypertRemoteRegistry;
+  readonly lookups: TypertLookupRegistry;
+  readonly contexts: TypertContextRegistry;
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    typert: TypertRegistryContract;
+  }
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-session/lib/types/surface.d.ts
+/** Readonly live projection of the message-producing session events. */
+interface SessionSurface {
+  /** Current surface event sequences in model-visible order. */
+  readonly nodes: readonly number[];
+  /** Monotonic count of committed positional replacements. */
+  readonly replaceGeneration: number;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-session/lib/types/index.d.ts
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    sessions: SessionStore;
+  }
+  interface Events {
+    /**
+     * Creation announcement during session publication. A synchronous throw vetoes and rolls
+     * back with a paired disposal; detach requested during dispatch is deferred.
+     * A returned-promise rejection is logged but cannot retroactively veto this
+     * synchronous boundary.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+     * receive only sessions entered through that agent's context.
+     * @param session - the session just entered and announced.
+     * @dshScopeScan unsupported
+     * @mode emit
+     */
+    'session/created'(this: Scoped<Session>, session: Session): void;
+    /**
+     * Emitted once when an announced session leaves the store, including
+     * publication rollback, but never for an entry whose creation announcement
+     * did not begin. Listener failures are logged and contained.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+     * @param session - the session that is no longer live in the store.
+     * @dshScopeScan unsupported
+     * @mode emit
+     */
+    'session/disposed'(this: Scoped<Session>, session: Session): void;
+    /**
+     * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+     * before the log push, but callbacks run after it; observer failures are
+     * logged and contained without making the committed append fail.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+     * receive only events from sessions entered through that agent's context.
+     * @param session - the session whose log grew.
+     * @param event - the appended event, exactly as recorded.
+     * @dshScopeScan unsupported
+     * @mode emit
+     */
+    'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void;
+    /**
+     * Awaited parallel durability checkpoint: every listener runs and the
+     * caller awaits all of them, with no waterfall veto. Scope-filtered dispatch
+     * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+     * @param session - the session whose buffered events must reach durable storage.
+     * @dshScopeScan unsupported
+     * @mode parallel
+     */
+    'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void;
+  }
+}
+declare module '@deepseek-ai/dsh-typert-protocol' {
+  interface TypertLookupMap {
+    session: TypertLookup<Session, SessionId>;
+  }
+}
+/**
+ * An event-sourced session: an append-only log of {@link SessionEvent}s.
+ *
+ * Plain class (not a Service) — create live instances via
+ * `ctx.sessions.create()` and detached instances via {@link create}.
+ * Seeding with an existing event log replays/forks a session.
+ * @typert object
+ */
+declare class Session {
+  private log;
+  /** Single incremental owner of surface acceptance and projection state. */
+  private readonly surfaceManager;
+  /** The ordered surface over this session's event log. */
+  get surface(): SessionSurface;
+  /**
+   * Detached, deep-frozen creation metadata (format version, cwd, lineage,
+   * seed boundary). Supplied by the store via `ctx.sessions.create()`. When a
+   * `Session` is created without a store-owned header, a minimal header is
+   * synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
+   * `session.header` is always present. Kept out of the event log — it is a
+   * storage concern, not replayable conversation state.
+   */
+  readonly header: SessionHeader;
+  /** The session identity, derived from its durable header's single copy. */
+  get id(): SessionId;
+  /**
+   * The first seq appended IN THIS PROCESS: the length of the constructor
+   * seed (0 without one). Events with smaller seq values entered through
+   * construction — replay, fork, or resume — and were never published on the
+   * `session/event` firehose (constructor seeds do not emit), so consumers
+   * that replay the log as a publication substitute (telemetry adoption)
+   * start here. Distinct from `header.seedLength`, the DURABLE fork-lineage
+   * boundary: a resumed session's constructor seed is its full stored log,
+   * while its header keeps the original fork value — this field is the
+   * in-process construction fact.
+   *
+   * Not persisted itself: a seeded session projects it into the log as the
+   * `session/end-seed` event, which is what a consumer reading STORED history
+   * reads. Locate the LAST such event, not necessarily one at this seq — a
+   * seed already ending in one is not re-marked, so reopening an untouched
+   * session leaves that event at a smaller seq than `firstLiveSeq`. Prefer
+   * this field in-process: it is exact before the marker reaches storage.
+   *
+   * When this lifecycle appends the marker, it occupies this seq before the
+   * store attaches and therefore does not publish either. Otherwise this seq
+   * holds an ordinary published write.
+   */
+  readonly firstLiveSeq: number;
+  /**
+   * Create a detached session by validating and snapshotting borrowed seed
+   * events and storage metadata.
+   * @param id - session identity.
+   * @param seed - optional borrowed replay or fork events.
+   * @param header - optional borrowed storage metadata.
+   * @returns a detached session.
+   */
+  static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;
+  /**
+   * Restore a detached session by taking ownership of fresh persistence values.
+   * The storage format, event envelopes, sequence continuity, surface transitions,
+   * and header fields are validated before the restored objects are frozen.
+   * @param id - restored session identity.
+   * @param seed - fresh detached events whose ownership is transferred.
+   * @param header - fresh detached metadata whose ownership is transferred.
+   * @returns a restored detached session.
+   */
+  static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;
+  private constructor();
+  /** Cached immutable public snapshot of the private append-only log. */
+  private eventsSnapshot;
+  /**
+   * An immutable snapshot of the append-only event log. The snapshot is reused
+   * until the next append; a previously returned array does not grow later.
+   * Events and their nested data are deep-frozen at acceptance, so neither a
+   * cast nor ordinary JavaScript can rewrite durable history.
+   */
+  get events(): readonly SessionEvent[];
+  /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
+  get seq(): number;
+  /**
+   * Append one typed event to the log and synchronously notify observers via
+   * the store-owned, module-private publication hooks. The hot path never blocks
+   * on I/O — persistence plugins buffer asynchronously. Once the event enters
+   * the log, the append is committed: observer failures are logged and
+   * contained per listener, so they do not change the return value or prevent
+   * later listeners from observing the same accepted event.
+   *
+   * @param type - The event type (key of {@link SessionEventMap}).
+   * @param data - The event payload; must be JSON-serializable.
+   * @param opts - Surface metadata: `surfaceOp` controls how the event enters
+   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
+   *   events this one derives from. REQUIRED for
+   *   {@link SurfaceEventType} events (every message-producing event must
+   *   declare how it joins the surface, the sole source of derived model
+   *   history) and
+   *   rejected by the compiler for non-surface types like `turn/start` or
+   *   `assistant/chunk`.
+   * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
+   *   `data` that entered the log, so reading `event.data` back sees the logged
+   *   value, never the caller's still-mutable input.
+   * @throws if `data` or surface metadata is not losslessly JSON-serializable
+   *   (BigInt, function, symbol, undefined, negative zero, non-finite number,
+   *   circular reference, sparse array, or an exotic object such as
+   *   Map/Set/Date/class instance), or when the candidate violates the
+   *   canonical surface contract (marker shape and eligibility, unique
+   *   earlier source-event references, positional replacement validity, and complete
+   *   shadowed-node coverage). One recursive pass reads, validates, and
+   *   copies each nested value once, so a stateful getter cannot supply one value
+   *   to validation and another to storage. The event log is the durable source
+   *   of truth, so a bad event fails at the append site rather than later during
+   *   a backend flush. A synchronous internal dispatch validation failure or an
+   *   append reentered while this acceptance/publication boundary is open also
+   *   rejects before the log changes.
+   */
+  append<T extends SessionEventType>(type: T, data: SessionEventMap[T], ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []): SessionEvent<T>;
+  /** Cached fold of the request-header events — see {@link requestHeader}. */
+  private headerFold;
+  /** Log position (events consumed) the header fold has reached. */
+  private headerFoldSeq;
+  /**
+   * The {@link EpochHeader} in force after the log's last header event — the
+   * header the NEXT request will be compared against — or undefined before
+   * the first `request/header` snapshot. The live, incrementally-maintained
+   * form of `foldRequestHeader(session.events)`: each header event is folded
+   * once, when first seen, so a per-step read costs O(new events).
+   * @returns the folded header, or undefined when no header event exists yet.
+   */
+  requestHeader(): EpochHeader | undefined;
+  /** Cached fold of `request/context` events. */
+  private contextFold;
+  private contextFoldSeq;
+  /**
+   * Return the latest resolved route metadata, or `undefined` before the first
+   * `request/context` event. Each event is folded once.
+   * @returns the latest immutable route metadata.
+   */
+  requestContext(): RequestContext | undefined;
+  /** The derived-message cache: frozen projections, extended per unseen node. */
+  private derived;
+  /** Surface position (nodes projected) the cache has reached. */
+  private derivedNodes;
+  /** {@link SurfaceManager.replaceGeneration} the cache was built under. */
+  private derivedGeneration;
+  /**
+   * Derive the LLM message history by walking the ordered sequences of
+   * message-producing events maintained by `surfaceOp` markers. The
+   * surface is the single source of derived history: every message-producing
+   * append records its `surfaceOp`, so a raw event with no marker (a chunk, a
+   * turn boundary) is correctly absent, and a compaction `replace` deletes the
+   * shadowed nodes from the derivation. The projection rules are
+   * {@link deriveEventMessage}, folded per node.
+   *
+   * CACHED: each surface node is projected exactly once, when first seen — a
+   * call costs O(new nodes), and a surface rewrite (a `replace`;
+   * {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
+   * a fresh snapshot per call (later appends never grow an array a caller
+   * already holds); the `Message` objects in it are SHARED and **deep-frozen**.
+   * Their content reuses the already frozen durable event data, so the cache
+   * needs no second deep clone and consumers still cannot mutate the log.
+   * @returns a fresh array of the shared, frozen derived history.
+   */
+  deriveMessages(): Message[];
+  /**
+   * Instance face of the pure per-node `deriveEventMessage` export from
+   * `surface.ts`.
+   * @param event - the event to project.
+   * @returns the derived message, or null when the event produces none.
+   */
+  deriveEventMessage(event: SessionEvent): Message | null;
+}
+/** A fork source: either the live session object or its live store id. */
+type SessionForkSource = Session | SessionId;
+/**
+ * In-memory session store (`ctx.sessions`).
+ *
+ * Persistence is intentionally not implemented here — persistence plugins
+ * subscribe to `session/event` and flush on `session/flush` / dispose.
+ */
+declare class SessionStore extends Service {
+  private store;
+  private counter;
+  constructor(ctx: Context);
+  /**
+   * Create a session owned by the calling fiber: disposing that fiber stops
+   * event notification and removes the session from the store. `options.seed`
+   * populates the session with a copy of those events (replay/fork);
+   * `options.meta` attaches creation metadata (validated absolute `cwd`, seed
+   * and parent lineage, and delegation depth) as the immutable
+   * {@link SessionHeader} (the store fills `version`/`id`/`createdAt`).
+   *
+   * For an agent whose session must be torn down IN ORDER with its loop (so the
+   * loop's final events are published before the store attachment ends), do NOT use this
+   * — fold the session lifecycle into the agent's own effect via
+   * {@link prepare} + {@link enter} + {@link announce} (see
+   * `dsh-agent-loop`'s creation transaction).
+   *
+   * @param id - the session id; omitted, the store mints `session-<n>`.
+   * @param options - seed events and/or creation metadata for the header.
+   * @returns the live session, already entered and announced.
+   * @throws if a session with `id` already exists, metadata is not a plain
+   *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+   *   non-absolute path (storage backends key directories off it).
+   */
+  create(id?: SessionId, options?: CreateSessionOptions): Session;
+  /**
+   * Build a session WITHOUT entering it into the store — validate the id/cwd and
+   * construct the {@link Session} (with its immutable {@link SessionHeader}).
+   * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
+   * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
+   * effect so a fiber unload tears the session + agent down as a single ORDERED
+   * chain rather than as racing sibling effects — which would remove the publication hooks
+   * before the driver's closing events commit, dropping them.
+   *
+   * @param id - the session id; omitted, the store mints `session-<n>`.
+   * @param options - seed events and/or creation metadata for the header. With
+   *   `seedSource: 'persistence'`, metadata and events must be fresh detached
+   *   graphs whose ownership transfers to this call: they are validated and
+   *   frozen in place through {@link Session.fromRestore}, so the caller must
+   *   retain no mutable aliases.
+   * @returns the constructed session, NOT yet in the store.
+   * @throws if a session with `id` already exists, metadata is not a plain
+   *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+   *   non-absolute path.
+   */
+  prepare(id?: SessionId, options?: PrepareSessionOptions): Session;
+  /**
+   * Enter a {@link prepare}d session into the store: install the module-private
+   * append publication hooks and add it to the store. Returns the DETACH
+   * disposer (hooks + store removal). Does NOT emit `session/created` —
+   * the caller yields this disposer inside its effect and THEN calls
+   * {@link announce}, so a throwing `session/created` listener rolls the attach
+   * back instead of leaking it.
+   *
+   * Re-checks the id for a duplicate: `prepare` and `enter` are public
+   * cross-package primitives and a caller may interleave arbitrary work (or
+   * another create) between them, so a stale prepared session must NOT overwrite
+   * a live store entry of the same id — its detach disposer would later delete
+   * the REAL session. The {@link create} convenience and the agent factory call
+   * the two back-to-back so they never trip this, but the public API cannot
+   * assume that.
+   *
+   * @param session - a {@link prepare}d session not yet in the store.
+   * @returns the detach disposer (publication hooks + store removal). When called from
+   *   a synchronous `session/created` listener, removal and disposal wait until
+   *   that creation dispatch unwinds.
+   * @throws if a session with this id is already in the store.
+   */
+  enter(session: Session): () => void;
+  /** Remove one exact entered session and emit its paired disposal when announced. */
+  private detachEntered;
+  /** Emit `session/created` exactly once for an {@link enter}ed session (with
+   * the carrier {@link enter} captured). Separate from {@link enter} so the
+   * caller can yield the detach disposer first (rollback safety — see
+   * {@link enter}).
+   * @param session - the entered session to announce to listeners.
+   * @throws if the session is not live or its announcement already began,
+   *   including a reentrant call from a creation listener. */
+  announce(session: Session): void;
+  /** Emit the paired teardown notification with per-listener containment. */
+  private emitDisposed;
+  /**
+   * Dispatch the awaited `session/flush` durability checkpoint for `session`,
+   * with the carrier captured at {@link enter}. THE flush entry point: the
+   * store owns the carrier, so callers (the checkpoint policy's per-request
+   * barrier, goal-round-driver's idle checkpoint, teardown drains, and consumers
+   * that flush themselves before reading storage) must come through here
+   * rather than dispatch a raw `ctx.parallel('session/flush', …)` — one owner,
+   * one spelling, and the scoped-dispatch invariant can pin it.
+   * @param session - the session whose buffered events must reach durable storage.
+   * @returns whether at least one durability listener participated, after every
+   *   listener has settled successfully.
+   * @throws the first registered listener failure after every listener settles.
+   */
+  flush(session: Session): Promise<boolean>;
+  /** Return the exact live entry; detached/prepared objects reject. */
+  private liveEntryFor;
+  /**
+   * Look up a live session.
+   * @param id - the session id to look up.
+   * @returns the session, or undefined when no live session has that id.
+   */
+  get(id: SessionId): Session | undefined;
+  /**
+   * All live sessions, in creation order.
+   * @returns a fresh array; mutating it does not affect the store.
+   */
+  list(): Session[];
+  /**
+   * Create a live child session from a stable prefix of a live source.
+   * `boundary` is an inclusive source event seq; omitted means the source's
+   * current last event. The selected slice may end with a between-turn event
+   * but must not end inside an open turn.
+   *
+   * @param source - Live source session object or id.
+   * @param boundary - Inclusive source event seq to fork through; omitted means
+   *   the source's current last event, and omitted on an empty source forks an
+   *   empty child.
+   * @param childSessionId - Optional child session id; omitted delegates to
+   *   `SessionStore`'s id policy.
+   * @returns The created live child session.
+   */
+  fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session;
+  private _forkSeed;
+  private _resolveForkSource;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-sandbox/lib/types/index.d.ts
+/**
+ * File-effect policy for confined processes. `read-only` permits only required
+ * sinks such as `/dev/null`; `workspace-write` also permits the workspace and a
+ * backend-defined temp area; `danger-full-access` bypasses confinement. Network
+ * and process visibility are outside this vocabulary.
+ */
+type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** A confining (non-`danger-full-access`) mode — the modes a {@link SandboxPolicy} can carry. */
+type ConfinedSandboxMode = Exclude<SandboxMode, 'danger-full-access'>;
+/**
+ * The complete file-effect policy resolved for one capability call. The root
+ * is carried even under modes that do not consume it so callers can resolve
+ * policy once before choosing the enforcement path.
+ */
+interface SandboxExecutionPolicy {
+  /** The file-effect mode this execution runs under. */
+  mode: SandboxMode;
+  /** Absolute root directory `workspace-write` may write under. */
+  workspaceRoot: string;
+  /**
+   * Opaque identity of the calling session (the branded `dsh-session`
+   * SessionId). Backends key per-session state off it (e.g. windows-acl gives
+   * each live session/workspace pair a random private temp directory and SID,
+   * while the workspace SID and standing grant remain per-workspace); absent
+   * for agentless calls, which fall back to per-call backend state.
+   */
+  sessionId?: SessionId;
+}
+/**
+ * Enforcement completeness for this host. `partial` means an active backend or
+ * older kernel ABI cannot govern every promised file effect; callers requiring
+ * an absolute boundary must not treat it as `full`.
+ */
+type SandboxEnforcement = 'full' | 'partial';
+/**
+ * What one confined execution is allowed to touch — carried PER CALL, not
+ * fixed on the provider: two consumers may confine under different policies
+ * at the same instant (bash under `read-only` while a confined child agent
+ * needs its state directory writable), and an approved escalated retry is a
+ * new call with a wider policy. Defaulting/resolution is an explicit step at
+ * the consumer boundary; the provider treats the policy as fully specified.
+ */
+interface SandboxPolicy extends SandboxExecutionPolicy {
+  /** The file-effect mode this execution runs under. */
+  mode: ConfinedSandboxMode;
+}
+/**
+ * Evidence that identifies a sandbox runner failing before it executes the
+ * wrapped command. A consumer first applies {@link allowedExitCodes} when
+ * present, removes {@link informationalLines} by case-insensitive exact line
+ * equality, then matches {@link fatalSignatures} case-insensitively within
+ * each remaining stderr line. Exit status alone never proves runner failure.
+ */
+interface RunnerFailureRule {
+  /** Nonzero process exit codes on which this rule may match; omitted permits any nonzero exit. */
+  allowedExitCodes?: readonly number[];
+  /** Non-empty substrings identifying a fatal runner diagnostic on one stderr line. */
+  fatalSignatures: readonly string[];
+  /** Benign stderr lines excluded by exact full-line equality before fatal matching. */
+  informationalLines?: readonly string[];
+}
+/**
+ * A {@link SandboxProvider.confine} result: the argv to spawn in place of
+ * the caller's own, plus the enforcement completeness the selected backend
+ * achieves for it.
+ */
+interface ConfinedArgv {
+  /** The wrapped argv (runner, profile, separator, then the caller's argv). */
+  argv: string[];
+  /** How completely the selected backend enforces the policy's file effects. */
+  enforcement: SandboxEnforcement;
+  /**
+   * The selected backend's denial DIALECT: the case-insensitive stderr
+   * substrings a file effect denied by THIS backend produces (EROFS text
+   * under bwrap's read-only binds, EACCES under Landlock, EPERM under
+   * Seatbelt). A consumer that infers denials from a failed run's stderr
+   * matches against exactly these rather than a cross-backend union — the
+   * union claims denials a given backend never produces.
+   */
+  denialSignatures: readonly string[];
+  /**
+   * Structured runner-failure evidence rules. Consumers require a matching
+   * fatal stderr line (after informational exclusions) and any rule-specific
+   * exit-code gate before checking denial signatures: runner failure means the
+   * command never ran, while denial means confinement worked and blocked it.
+   */
+  runnerFailureRules: readonly RunnerFailureRule[];
+}
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    sandbox: SandboxProvider;
+  }
+}
+/**
+ * Abstract process-sandbox service. {@link confine} must return enforcing argv
+ * or fail closed at wrap or runner-execution time; silent unconfined passthrough
+ * is forbidden. Functional probes arbitrate multi-runner chains and may be
+ * skipped for a sole candidate, whose own refusal remains the fail-closed end.
+ */
+declare abstract class SandboxProvider extends Service {
+  constructor(ctx: Context);
+  /**
+   * Wrap `argv` so it executes confined under `policy` on this host; the
+   * caller spawns the returned argv in place of its own.
+   * @param argv - the exact argv the caller is about to spawn (program plus
+   *   arguments), NOT a shell string — a shell-shaped consumer passes
+   *   `['bash', '-c', command]`.
+   * @param policy - the file-effect policy this execution runs under,
+   *   carried per call (see {@link SandboxPolicy}).
+   * @returns the argv to spawn instead, plus the enforcement completeness
+   *   the selected backend achieves for it.
+   */
+  abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-subprocess/lib/types/types.d.ts
+/** Namespace prefix reserved for DeepSeek Harness-managed child environment facts. */
+declare const DSH_ENV_PREFIX: "DSH_";
+/** One environment key inside the managed {@link DSH_ENV_PREFIX} namespace. */
+type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`;
+/** Trusted DeepSeek Harness variables for one child-process execution. */
+type DshEnvironment = Readonly<Record<DshEnvironmentKey, string>>;
+/** One captured stream: the (possibly truncated) text plus recovery info. */
+interface CollectedOutput {
+  /** Collected text — the TAIL of the stream when truncated. */
+  text: string;
+  /** True when bytes were dropped from `text`. */
+  truncated: boolean;
+  /** Path to a file holding the COMPLETE stream, when truncated and available. */
+  spillPath?: string;
+}
+/**
+ * stdin disposition. `'ignore'` leaves fd 0 on `/dev/null`; `'pipe'` exposes
+ * {@link SubprocessHandle.stdin} for the caller's ongoing protocol writes;
+ * `{ data }` writes the bytes and closes (the batch shape).
+ */
+type SubprocessStdinMode = 'ignore' | 'pipe' | {
+  readonly data: string;
+};
+/**
+ * Bounded in-memory collection for one output stream, with an optional
+ * full-stream spill file. Omitting `spill` keeps only the in-memory tail —
+ * the diagnostic-tail shape (a language server's stderr); including it makes
+ * the complete stream recoverable up to its cap (the bash tool shape).
+ */
+interface SubprocessCollect {
+  /** In-memory cap in bytes; overflow keeps the TAIL. */
+  maxBytes: number;
+  /** Full-stream spill file; absent disables spilling entirely. */
+  spill?: {
+    /** Whole-stream byte cap; a larger stream discards its now-incomplete spill. */
+    maxBytes: number;
+  };
+}
+/**
+ * stdout/stderr disposition. `'pipe'` exposes the raw `Readable` for the
+ * caller's protocol decoding; `'inherit'` passes the parent's descriptor
+ * through (child diagnostics land on the harness's own stream); a
+ * {@link SubprocessCollect} object buffers boundedly with offset-based reads.
+ */
+type SubprocessOutputMode = 'pipe' | 'inherit' | SubprocessCollect;
+/** Per-stream stdio dispositions, all explicit — this seam applies no defaults. */
+interface SubprocessStdio {
+  stdin: SubprocessStdinMode;
+  stdout: SubprocessOutputMode;
+  stderr: SubprocessOutputMode;
+}
+/**
+ * A fully-specified spawn request. This seam applies no defaults: every
+ * disposition, limit, and directory is explicit, so the caller's own config —
+ * not a hidden subprocess-service default — decides them (the `dsh-shell`
+ * request/spec split is the owning template).
+ */
+interface SubprocessSpawnSpec {
+  /** Executable and arguments; `argv[0]` is the program. Never shell-interpreted here. */
+  argv: readonly string[];
+  /** Working directory for the child. */
+  cwd: string;
+  /** Per-stream stdio dispositions. */
+  stdio: SubprocessStdio;
+  /**
+   * Positive finite grace period in milliseconds, no greater than
+   * `MAX_TIMER_DELAY_MS`, for the {@link SubprocessHandle.terminate} escalation
+   * and for draining still-open collected pipes after the process exits (an
+   * inherited descriptor held by a surviving descendant cannot hold the
+   * outcome open indefinitely).
+   */
+  graceMs: number;
+  /**
+   * Abort signal — starts the terminate escalation on the process tree when
+   * it fires. The caller owns deadlines and cause classification; this seam
+   * only reacts to the abort.
+   */
+  signal?: AbortSignal | undefined;
+  /**
+   * Explicit environment entries merged onto the implementation's scrubbed
+   * parent base (see `scrubbedParentEnv`), with no namespace validation. A
+   * string is a deliberate caller opt-in, so a forwarded credential-shaped
+   * entry or current `DSH_*` fact survives the scrub; `undefined` is a
+   * tombstone that removes an ordinary ambient entry from the child.
+   */
+  env?: NodeJS.ProcessEnv | undefined;
+}
+/**
+ * Exit facts of one closed process — Node's `close`-event vocabulary.
+ * Deliberately carries NO timeout or cancellation classification (the caller
+ * reads the signal it owns to classify causes) and NO output: collected
+ * streams stay readable through {@link SubprocessHandle.collected} after
+ * settlement, so batch and streaming callers share one access path.
+ */
+interface SubprocessOutcome {
+  /** Exit code; null when the process died from a signal. */
+  exitCode: number | null;
+  /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
+  signal: NodeJS.Signals | null;
+}
+/** One incremental {@link SubprocessOutputReader.readFrom} read. */
+interface SubprocessOutputRead {
+  /** Stream text from the requested offset (the whole retained tail when lossy). */
+  text: string;
+  /** Whole-stream offset to resume from on the next read. */
+  nextOffset: number;
+  /** True when the requested offset slid out of the in-memory tail window. */
+  lossy: boolean;
+  /** Path to the full-stream spill file, when one was created and remains intact. */
+  spillPath?: string;
+}
+/**
+ * Cursor-free incremental access to one collected output stream. Offsets are
+ * whole-stream byte coordinates owned by the caller, so independent readers
+ * cannot consume one another's output; `readFrom(0)` after settlement is the
+ * batch result (`lossy` then means the in-memory tail lost its head — the
+ * {@link CollectedOutput.truncated} fact).
+ */
+interface SubprocessOutputReader {
+  /**
+   * Read everything captured since `fromByte`. When that offset has slid out
+   * of the in-memory tail window the read is `lossy` — it returns the whole
+   * retained tail and the gap is only recoverable from the spill file.
+   * @param fromByte - whole-stream offset to resume from (a prior read's `nextOffset`; 0 for the first read).
+   * @returns the delta text, the next offset, the `lossy` flag, and the spill path when one exists.
+   */
+  readFrom(fromByte: number): SubprocessOutputRead;
+}
+/** Offset-based readers for the streams spawned in collect mode. */
+interface SubprocessCollectedOutputs {
+  /** Present iff stdout is a {@link SubprocessCollect}. */
+  readonly stdout?: SubprocessOutputReader;
+  /** Present iff stderr is a {@link SubprocessCollect}. */
+  readonly stderr?: SubprocessOutputReader;
+}
+/**
+ * A live child process rooted in its own process tree. Collected output
+ * remains readable after exit; piped streams belong to the caller.
+ *
+ * Termination is tree-scoped everywhere: POSIX signals the detached process
+ * group (falling back to the direct child when the group is gone), Windows
+ * terminates the tree via `taskkill /T`, so helper processes cannot outlive
+ * the handle unnoticed.
+ */
+interface SubprocessHandle {
+  /** Process id (tree root); -1 when the spawn itself failed. */
+  readonly pid: number;
+  /** The child's stdin, present iff spawned with `stdin: 'pipe'`. */
+  readonly stdin: Writable | undefined;
+  /** The child's raw stdout, present iff spawned with `stdout: 'pipe'`. */
+  readonly stdout: Readable | undefined;
+  /** The child's raw stderr, present iff spawned with `stderr: 'pipe'`. */
+  readonly stderr: Readable | undefined;
+  /** Offset-based readers for collect-mode streams (also readable after exit). */
+  readonly collected: SubprocessCollectedOutputs;
+  /** Resolves at process close with exit facts; rejects only for spawn-level failures. */
+  readonly done: Promise<SubprocessOutcome>;
+  /**
+   * Begin the SIGTERM → `graceMs` → SIGKILL escalation on the process tree
+   * (Windows force-terminates immediately) — the seam's only termination
+   * verb. Idempotent, a no-op once the tree is gone (the pid may be reused),
+   * and also triggered by the spec's abort signal.
+   */
+  terminate(): void;
+  /**
+   * Wait until the process tree has exited — the tree, not just the direct
+   * child, so a still-running helper is observable before teardown returns.
+   * @param signal - optional bound for the wait.
+   * @returns `true` when the tree exited, `false` when the signal aborted first.
+   */
+  waitForExit(signal?: AbortSignal): Promise<boolean>;
+}
+/**
+ * Signals supported by the terminal-process primitive. Kept member-identical
+ * to `TerminalSignal` in `@deepseek-ai/dsh-terminal` without a cross-seam dependency;
+ * change both together.
+ */
+type SubprocessTerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP';
+/** A fully specified terminal-process spawn. */
+interface SubprocessTerminalSpawnSpec {
+  /** Executable and arguments; `argv[0]` is the program. */
+  argv: readonly string[];
+  /** Working directory in this subprocess provider's execution world. */
+  cwd: string;
+  /** Explicit environment layered after the provider's ambient scrub. */
+  env?: Record<string, string> | undefined;
+  /** Initial terminal row count. */
+  rows: number;
+  /** Initial terminal column count. */
+  cols: number;
+  /** TERM-to-KILL cleanup grace for the complete terminal session. */
+  graceMs: number;
+  /** Cancellation of terminal allocation; a published handle owns its later lifetime. */
+  signal?: AbortSignal | undefined;
+}
+/** Current foreground process-group facts for one terminal. */
+interface SubprocessTerminalForeground {
+  /** Foreground process-group id published by the terminal driver. */
+  processGroupId: number;
+  /** Whether the provider can currently prove that group is waiting on terminal input. */
+  inputWaiting: boolean;
+}
+/**
+ * One live terminal process and its owned OS session. Terminal allocation,
+ * foreground-group inspection/signalling, and session-tree cleanup are one
+ * deep subprocess primitive because none can be reconstructed from ordinary
+ * piped stdio without substrate-specific process control.
+ */
+interface SubprocessTerminalHandle {
+  /** Top-level terminal process id. */
+  readonly pid: number;
+  /** UTF-8 terminal output bytes in delivery order; ends after queued output when the terminal exits. */
+  readonly output: Readable;
+  /** Resolves when the top-level process exits; rejects only for a live transport failure. */
+  readonly done: Promise<SubprocessOutcome>;
+  /**
+   * Write text to the terminal input.
+   * @param data - text to deliver without implicit newline conversion.
+   */
+  write(data: string): Promise<void>;
+  /**
+   * Inspect the current foreground process group.
+   * @returns its id and input-wait fact, or undefined when no foreground group can be resolved.
+   */
+  inspectForeground(): Promise<SubprocessTerminalForeground | undefined>;
+  /**
+   * Deliver a signal to the current foreground process group.
+   * @param signal - permitted terminal signal.
+   * @returns the exact group id that received it.
+   */
+  signalForeground(signal: SubprocessTerminalSignal): Promise<number>;
+  /**
+   * Idempotently terminate every terminal-session member the provider can still observe and await quiescence.
+   * After settlement, no write, inspection, or signal call remains in flight.
+   * Providers document substrate-specific observability limits.
+   */
+  terminate(): Promise<void>;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-subprocess/lib/types/index.d.ts
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    subprocess: SubprocessRuntime;
+  }
+}
+/**
+ * Abstract subprocess service. Subclass, implement {@link spawn}, and load the
+ * subclass as a plugin — it registers as `ctx.subprocess` (one implementation
+ * per context; loading a second throws, which is cordis' standard
+ * duplicate-service behavior).
+ *
+ * Implementations must honor these semantics:
+ * - Executable paths belong to one execution world shared with the mounted
+ *   filesystem provider.
+ * - {@link spawn} returns immediately with a live handle; `done` resolves at
+ *   process close with exit facts and rejects only for spawn-level failures.
+ * - Collect-mode readers are offset-based and non-consuming, so independent
+ *   readers never consume one another's output; lossy reads report truncation
+ *   and the spill file holding the complete stream when one exists. Piped
+ *   streams are handed to the caller raw and never buffered here.
+ * - {@link SubprocessHandle.terminate} (and the spec's abort signal) escalates
+ *   SIGTERM→grace→SIGKILL — the only termination verb — tree-scoped on every
+ *   platform. {@link SubprocessHandle.waitForExit} observes whole-tree
+ *   liveness, so a consumer-owned teardown ladder can hold each tier on real
+ *   quiescence.
+ * - Disposal of the service terminates all still-running managed processes
+ *   and awaits their exit.
+ * - {@link spawnTerminal} owns terminal allocation, text transport,
+ *   foreground groups, signalling, and whole-session quiescence behind one
+ *   awaited termination method; readiness and persistent-shell policy stay
+ *   in the PTY consumer. Its output stream ends after queued terminal output
+ *   when the top-level process exits.
+ */
+declare abstract class SubprocessRuntime extends Service {
+  constructor(ctx: Context);
+  /**
+   * Resolve one configured executable in this provider's execution world.
+   * Absolute paths are verified; bare names use the provider's scrubbed PATH
+   * plus explicit environment overrides. Relative paths containing separators
+   * are rejected: the resolution base is undefined, so providers fail loud
+   * instead of guessing.
+   * @param command - absolute executable path or bare PATH name.
+   * @param env - explicit environment entries used for lookup.
+   * @param signal - aborts remote or local lookup.
+   * @returns a canonical executable path.
+   */
+  abstract resolveExecutable(command: string, env?: Readonly<Record<string, string>>, signal?: AbortSignal): Promise<string>;
+  /**
+   * Start one managed child process from a fully-specified spec; this seam
+   * applies no defaults.
+   * @param spec - argv, directory, stdio dispositions, grace, cancellation, and environment.
+   * @returns the live process handle (streams/readers, signalling, outcome promise).
+   */
+  abstract spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+  /**
+   * Allocate a real terminal and start one owned process session. This is the
+   * only non-pipe process primitive: implementations own terminal byte I/O,
+   * foreground groups, signals, and complete session-tree cleanup.
+   * @param spec - fully specified argv, cwd, environment, dimensions, grace, and allocation cancellation.
+   * @returns the live terminal handle after allocation succeeds.
+   */
+  abstract spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-shell/lib/types/types.d.ts
+/**
+ * Sandbox facts for one run, present iff a sandboxing executor handled it.
+ * Facts are reported independently of process exit status so callers can
+ * distinguish command failures from policy denials and runner failures.
+ */
+interface ShellSandboxInfo {
+  /** The mode the command actually ran under. */
+  mode: SandboxMode;
+  /** Whether the sandbox denied a file operation. */
+  denied: boolean;
+  /** How completely the selected runner enforced the requested mode. */
+  enforcement?: SandboxEnforcement;
+  /** Whether the sandbox runner failed before the command could run. */
+  runnerFailed?: boolean;
+}
+/**
+ * A caller's execution REQUEST: `workdir` and `timeoutMs` are optional and
+ * filled by {@link ShellExecutor.resolve} from the implementation's config.
+ * This is the model-/plugin-facing shape; pass it to `resolve()` to obtain a
+ * fully-resolved {@link ShellExecSpec}.
+ */
+interface ShellExecRequest {
+  command: string;
+  /** Working directory override (default: implementation-configured). */
+  workdir?: string | undefined;
+  /** Timeout override in milliseconds (implementations cap it). */
+  timeoutMs?: number | undefined;
+  /**
+   * Foreground stdout capture budget in bytes. Absent uses the executor's
+   * default output cap. Trusted in-process consumers use this when they must
+   * parse complete stdout up to their own bounded limit; the model-facing bash
+   * tool does not expose it as a parameter.
+   */
+  stdoutMaxBytes?: number | undefined;
+  /** Abort signal — implementations kill the command when it fires. */
+  signal?: AbortSignal | undefined;
+  /**
+   * Bytes to write to the command's stdin, then close it. Absent leaves stdin
+   * closed/empty (the default for model-driven tool calls). Set by in-process
+   * plugins (e.g. the hooks bridges, which write a hook command's JSON payload
+   * to its stdin); the model-facing bash tool does not expose it as a parameter
+   * (a model that needs stdin uses shell syntax like a heredoc or a pipe).
+   */
+  stdin?: string | undefined;
+  /**
+   * Ordinary environment entries for the command, merged after the credential
+   * scrub. Managed facts belong in {@link dshEnv}, which merges after this
+   * map, so an entry here can never displace one. Set by in-process plugins
+   * (the hooks bridges set `CLAUDE_PROJECT_DIR`, `CLAUDE_PLUGIN_ROOT`, …); the
+   * model-facing bash tool does not expose it as a parameter.
+   */
+  env?: Record<string, string> | undefined;
+  /**
+   * Harness-owned `DSH_*` variables for this execution (typed to managed
+   * keys). Executors discard ambient `DSH_*` entries before merging this
+   * snapshot last, so an unavailable current fact cannot inherit a stale
+   * value from the harness process and a caller {@link env} entry cannot
+   * displace a managed one.
+   */
+  dshEnv?: DshEnvironment | undefined;
+  /** Fully resolved per-call sandbox policy; sandboxing executors default it. */
+  sandboxPolicy?: SandboxExecutionPolicy | undefined;
+}
+/**
+ * A resolved execution spec. {@link ShellExecutor.resolve} fills and caps the
+ * required fields; {@link ShellExecutor.start} ignores `timeoutMs` because
+ * background processes have no executor timeout.
+ */
+interface ShellExecSpec {
+  command: string;
+  workdir: string;
+  timeoutMs: number;
+  /**
+   * Resolved foreground stdout capture budget in bytes. `run()` uses it for
+   * stdout; background jobs and stderr keep the executor's own output cap.
+   */
+  stdoutMaxBytes: number;
+  /** Abort signal — implementations kill the command when it fires. */
+  signal?: AbortSignal | undefined;
+  /** Bytes to write to stdin before closing it; absent means no stdin. */
+  stdin?: string | undefined;
+  /**
+   * Ordinary environment entries carried through from
+   * {@link ShellExecRequest.env}; {@link dshEnv} still merges after them.
+   * OPTIONAL on the spec for the same reason as `stdin`: absent means no
+   * ordinary extra environment.
+   */
+  env?: Record<string, string> | undefined;
+  /** Managed `DSH_*` snapshot (typed to managed keys); merges after {@link env}. */
+  dshEnv?: DshEnvironment | undefined;
+  /** Resolved sandbox policy; ignored by executors that do not confine. */
+  sandboxPolicy: SandboxExecutionPolicy | undefined;
+}
+/** The outcome of one completed (or killed) foreground run. */
+interface ShellRunResult {
+  /** Exit code; null when the process died from a signal. */
+  exitCode: number | null;
+  /** Terminating signal (e.g. 'SIGTERM'); null on normal exit. */
+  signal: NodeJS.Signals | null;
+  /**
+   * True when the executor's own timeout was the FIRST cause to cut the command
+   * short. Mutually exclusive with {@link aborted}: one fused deadline drives
+   * both the timeout and the caller's cancellation, so a timeout and an abort
+   * racing before process close report the single first-abort cause, not both
+   * (see the [timeout-library Agent Note](../../../../.agents/notes/implemented/architecture/2026-07-06-timeout-deadline-library.md)).
+   */
+  timedOut: boolean;
+  /**
+   * True when the caller's `AbortSignal` was the FIRST cause to kill the command
+   * (and it was not the executor's own timeout). Mutually exclusive with
+   * {@link timedOut} — see there for the first-cause classification.
+   */
+  aborted: boolean;
+  /** The effective timeout applied to this run (after defaulting/capping). */
+  timeoutMs: number;
+  stdout: CollectedOutput;
+  stderr: CollectedOutput;
+  /** Sandbox execution facts, absent for an unsandboxed executor. */
+  sandbox?: ShellSandboxInfo;
+}
+/** Lifecycle of a background process. */
+type ShellProcessStatus = 'running' | 'completed' | 'killed';
+/** One incremental {@link ShellProcess.readOutput} read. */
+interface ShellProcessRead {
+  /** Output produced since the previous read (stderr in a marked section). */
+  delta: string;
+  /** True when truncation dropped unread bytes the delta cannot include. */
+  lossy: boolean;
+  /** Full stdout spill file, when stdout truncation occurred and a safe path is available. */
+  stdoutSpillPath?: string;
+  /** Full stderr spill file, when stderr truncation occurred and a safe path is available. */
+  stderrSpillPath?: string;
+}
+/**
+ * A background process handle returned by {@link ShellExecutor.start}. It is the
+ * only access path; buffered output remains readable after exit. Composition
+ * teardown (the subprocess service's disposal) kills running processes and
+ * awaits {@link done}; an executor-only reload leaves them running.
+ */
+interface ShellProcess {
+  /** Process lifecycle state (settled exactly once). */
+  status: ShellProcessStatus;
+  /** Exit code once finished (null = killed by signal / still running). */
+  exitCode: number | null;
+  /** Terminating signal name, when signal-killed. */
+  signal: NodeJS.Signals | null;
+  /** Resolves when the underlying process closes (never rejects — a spawn failure settles as `killed` with the error on stderr). */
+  readonly done: Promise<void>;
+  /** Sandbox facts, stamped once a confined process settles. */
+  sandbox?: ShellSandboxInfo;
+  /**
+   * Read output produced since the previous read (consuming — consecutive
+   * reads never re-deliver). Reads that lost data flag `lossy` and point at
+   * full-stream spill files when available.
+   */
+  readOutput(): ShellProcessRead;
+  /**
+   * Kill the process group. Returns false when it had already finished
+   * (no-op); idempotent.
+   */
+  kill(): boolean;
+}
+//#endregion
+//#region ../../node_modules/@deepseek-ai/dsh-shell/lib/types/index.d.ts
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    shell: ShellExecutor;
+  }
+}
+/**
+ * Abstract bash execution service. Subclass, implement the abstract methods,
+ * and load the subclass as a plugin — it registers as `ctx.shell` (one
+ * implementation per context; loading a second throws, which is cordis'
+ * standard duplicate-service behavior).
+ *
+ * Implementations must honor these semantics:
+ * - {@link run} rejects only for infrastructure failures. Nonzero exits,
+ *   timeout kills, and abort kills resolve with a {@link ShellRunResult}.
+ * - {@link start} returns immediately; no timeout applies to background
+ *   processes. `done` settles at process close and never rejects; spawn
+ *   failures settle as `killed` with the error on stderr.
+ * - {@link ShellProcess.readOutput} is incremental: consecutive reads never
+ *   repeat output. Lossy reads report truncation and available spill files.
+ * - A still-running background process is stopped and awaited when its
+ *   owning composition tears down. With the subprocess seam that
+ *   boundary is `ctx.subprocess` disposal, so a background process survives
+ *   an executor-only reload.
+ */
+declare abstract class ShellExecutor extends Service {
+  constructor(ctx: Context);
+  /**
+   * The sandbox mode this executor applies by default, or `undefined` when it
+   * does not sandbox commands.
+   * @returns the configured default sandbox mode, when supported.
+   */
+  get sandboxMode(): SandboxMode | undefined;
+  /**
+   * Apply implementation-owned defaults and caps to a request before execution.
+   * @param request - the caller's request; omitted fields get this
+   *   implementation's defaults, capped fields are clamped.
+   * @returns the fully-specified spec to hand to {@link run}/{@link start}.
+   */
+  abstract resolve(request: ShellExecRequest): ShellExecSpec;
+  /**
+   * Run a command in the foreground; resolves when it finishes.
+   * @param spec - a resolved spec from {@link resolve}, never a raw request.
+   * @returns the outcome; nonzero exits, timeout kills, and abort kills
+   *   resolve with a descriptive result rather than reject.
+   */
+  abstract run(spec: ShellExecSpec): Promise<ShellRunResult>;
+  /**
+   * Start a background process and return its handle immediately.
+   * @param spec - a resolved spec from {@link resolve}, never a raw request.
+   * @returns the live process handle (reads, kill, quiescence promise).
+   */
+  abstract start(spec: ShellExecSpec): ShellProcess;
+}
+//#endregion
+//#region src/process-provider.d.ts
+declare class SshShellExecutor {
+  private readonly executor;
+  constructor(executor: SshExecutor);
+  resolve(request: ShellExecRequest): ShellExecSpec;
+  run(spec: ShellExecSpec): Promise<ShellRunResult>;
+  start(spec: ShellExecSpec): ShellProcess;
+}
+declare class SshSubprocessRuntime {
+  private readonly executor;
+  constructor(executor: SshExecutor);
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle;
+  spawnTerminal(spec: SubprocessTerminalSpawnSpec): Promise<SubprocessTerminalHandle>;
+}
+//#endregion
+export { SshSubprocessRuntime as n, SshShellExecutor as t };
+//# sourceMappingURL=process-provider-CUgC5gyu.d.ts.map