dsh-loop-engine-allinone 0.0.0-stage → 0.4.0

package/lib/types/driver-cli/text.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The plain-text protocol skeleton.
+ *
+ * The simplest family, and a real one rather than a fallback: an engine invoked
+ * as `engine -p "prompt"` prints its finished answer on stdout and exits. There
+ * are no frames, no tool events and no usage — just text.
+ *
+ * Two consequences the driver has to state rather than hide:
+ *
+ *  - **No streaming.** The answer exists only once the child is done (or once
+ *    stdout stops growing), so `capabilities.streaming` is `false` for such an
+ *    engine and the settings page/UI must not promise token-by-token output.
+ *  - **No tool events.** A text engine may run tools internally, but it reports
+ *    none of them, so nothing lands in the tool rows. That is a faithful
+ *    transcript, not a gap: the plugin reports what the engine said.
+ *
+ * Exit status is part of the answer. A non-zero exit with empty stdout is a
+ * failed run with the child's own stderr as the message; a non-zero exit WITH
+ * output is still reported as a failure, because an engine that dies mid-answer
+ * has not answered.
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/text
+ */
+import type { CliTransport } from './transport.ts';
+/** What one text run produced. */
+export interface TextRunResult {
+    /** The child's stdout, verbatim. */
+    readonly stdout: string;
+    /** The child's stderr, truncated to the last {@link STDERR_LIMIT} characters. */
+    readonly stderr: string;
+    /** Exit code, or null when the child died from a signal. */
+    readonly exitCode: number | null;
+}
+/** What one text run needs. */
+export interface TextRunSpec {
+    /** The spawned child. */
+    readonly transport: CliTransport;
+    /**
+     * A payload to write to the child's stdin, when the prompt travels that way.
+     * Closing stdin is what lets an engine that reads to EOF start working.
+     */
+    readonly stdin?: string;
+}
+/**
+ * Run one plain-text query to completion.
+ * @param spec - the run's transport and optional stdin payload.
+ * @returns the child's output and exit facts.
+ */
+export declare function runText(spec: TextRunSpec): Promise<TextRunResult>;
+/**
+ * Turn a finished text run into the answer, or the reason there is none.
+ *
+ * Kept separate from {@link runText} so the decision is testable without
+ * spawning anything: it is where the "did the engine actually answer?"
+ * judgement lives.
+ * @param result - the finished run.
+ * @returns the answer text, or the failure message to report.
+ */
+export declare function textRunOutcome(result: TextRunResult): {
+    readonly kind: 'answered';
+    readonly text: string;
+} | {
+    readonly kind: 'failed';
+    readonly message: string;
+};
+//# sourceMappingURL=text.d.ts.map

package/lib/types/driver-cli/transport.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The subprocess transport every CLI driver spawns through.
+ *
+ * One thin layer over the harness's subprocess seam, for two reasons. First, the
+ * seam is where the sandbox lives: a spawned CLI is under the deployment's
+ * privilege policy, which is the only boundary available for an engine that has
+ * no permission system of its own. Second, every driver needs the same four
+ * things from a child — write its stdin, read its stdout as lines, know when it
+ * exited, and kill it — and doing that four times is how the drivers drift.
+ *
+ * The transport deliberately knows nothing about any protocol. It hands back
+ * streams; deciding what a line MEANS is the adapter's job
+ * (`./ndjson.ts`, `./text.ts`).
+ *
+ * @module dsh-loop-engine-allinone/driver-cli/transport
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** What one driver asks the transport to spawn. */
+export interface CliSpawnRequest {
+    /** Executable and arguments; `argv[0]` is the program. */
+    readonly argv: readonly string[];
+    /** Working directory for the child. */
+    readonly cwd: string;
+    /** Explicit environment entries layered over the scrubbed parent environment. */
+    readonly env: Record<string, string>;
+    /** Cancellation: the seam escalates process-tree termination when it fires. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * A spawned CLI child, as a protocol adapter needs it.
+ *
+ * `stdin` may be absent when the prompt travels in argv instead (`agy --print=…`,
+ * `hermes -z …`, `qoderclicn -p …`): an engine that takes its prompt as an
+ * argument has no use for a stdin pipe, and asking for one would leave a pipe
+ * the child waits on.
+ */
+export interface CliTransport {
+    /** The child's stdin, or undefined when the spawn did not request a pipe. */
+    readonly stdin: Writable | undefined;
+    /** The child's stdout, or undefined when the spawn did not request a pipe. */
+    readonly stdout: Readable | undefined;
+    /** The child's stderr, or undefined when the spawn did not request a pipe. */
+    readonly stderr: Readable | undefined;
+    /** Resolves when the child closes. */
+    readonly done: Promise<unknown>;
+    /** Request process-tree termination. */
+    terminate(): void;
+}
+/** Spawns one CLI child over the given request (a driver's spawn capability). */
+export type CliSpawnCapability = (request: CliSpawnRequest) => CliTransport;
+/**
+ * Build a {@link CliSpawnRequest} from a subprocess spawn spec.
+ *
+ * The two shapes are structurally the same; this exists so a driver can state
+ * its request in its own vocabulary and the projection lives in one place.
+ * @param request - the driver's spawn request.
+ * @param graceMs - grace period for the provider's termination procedure.
+ * @param pipeStdin - whether the child reads its prompt from stdin.
+ * @returns the seam's spawn spec.
+ */
+export declare function cliSubprocessSpec(request: CliSpawnRequest, graceMs: number, pipeStdin: boolean): SubprocessSpawnSpec;
+/**
+ * Project a subprocess handle onto the transport.
+ *
+ * A missing stream after a successful spawn is a wiring hole rather than a
+ * runtime condition — the spec above always asks for the pipes it needs — so it
+ * throws rather than degrading to an empty stream that would look like a silent
+ * engine.
+ * @param handle - the spawned handle.
+ * @param engine - the engine name, for the diagnostic.
+ * @returns the transport.
+ */
+export declare function transportOf(handle: SubprocessHandle, engine: string): CliTransport;
+/**
+ * Wrap a spawn capability so a driver never has to remember the grace period or
+ * the stdin decision at each call site.
+ * @param spawn - the raw seam projection.
+ * @param graceMs - grace period for termination.
+ * @param pipeStdin - whether this engine reads its prompt from stdin.
+ * @returns a capability taking the driver's own request shape.
+ */
+export declare function cliSpawner(spawn: (spec: SubprocessSpawnSpec) => SubprocessHandle, graceMs: number, pipeStdin: boolean): CliSpawnCapability;
+//# sourceMappingURL=transport.d.ts.map

package/lib/types/driver-core/agents-md-skill-provider.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Data-driven skill provider for the hosted engines whose discovery surface is
+ * "per-directory instruction files plus a skills catalog".
+ *
+ * Codex, Pi, and Kimi Code each expose the same two things through the dsh
+ * skill-injection seam: an `agents-md` candidate merging the per-directory
+ * instruction files found between the session cwd and the git root, and one
+ * candidate per `SKILL.md` catalog entry. Only the *locations*, *names*, and
+ * *precedence ranks* differ — never the algorithm — so those are the entire
+ * configuration surface here, and each engine module supplies one
+ * {@link AgentsMdProviderSpec} and a thin subclass.
+ *
+ * `.agents/skills` roots are deliberately absent from every engine's spec:
+ * dsh's own `skill-filesystem` provider already serves them through the same
+ * registry in the web profile.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/agents-md-skill-provider
+ */
+import { type ContextFilePolicy } from './context-files.ts';
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions, SkillProvider, SkillProviderControl } from '../skills.ts';
+/** A skills catalog: a per-ancestor project directory plus one user-level directory. */
+export interface SkillCatalogSpec {
+    /** Directory path, relative to each ancestor of the session cwd. */
+    readonly project: readonly string[];
+    /** Rank of project catalog entries — project instructions beat project skills. */
+    readonly projectRank: number;
+    /** Directory name under the user install root. */
+    readonly userDir: string;
+    /** Rank of user catalog entries — project files win duplicate names. */
+    readonly userRank: number;
+}
+/** Everything that varies between the codex, pi, and kimi discovery surfaces. */
+export interface AgentsMdProviderSpec {
+    /** Provider identity registered against the host skills service. */
+    readonly name: string;
+    /** Description of the merged `agents-md` candidate. */
+    readonly agentsMdDescription: string;
+    /** Per-directory instruction files this engine reads, and its override. */
+    readonly contextPolicy: ContextFilePolicy;
+    /** The engine's user-level install root. */
+    readonly userDir: () => string;
+    /** Rank of the project `agents-md` candidate. */
+    readonly projectRank: number;
+    /** User-level instruction file inside {@link userDir}, when the engine reads one. */
+    readonly userContext?: {
+        readonly file: string;
+        readonly rank: number;
+    };
+    /** Skill catalogs, when the engine has any. */
+    readonly skills?: SkillCatalogSpec;
+}
+/**
+ * Skill provider that discovers an engine's per-directory instruction files and
+ * `SKILL.md` catalogs from the locations its spec names.
+ */
+export declare class AgentsMdSkillProvider implements SkillProvider {
+    private readonly spec;
+    private readonly control;
+    readonly name: string;
+    constructor(spec: AgentsMdProviderSpec, control: SkillProviderControl);
+    list(options: SkillLookupOptions): Promise<readonly SkillCandidate[]>;
+    get(candidate: SkillCandidate, _options: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+    /** One merged `agents-md` candidate for a ranked file set. */
+    private agentsCandidate;
+    /** Collect every skill in one skills directory, both nesting layouts. */
+    private collectSkillsDir;
+    /** One parsed skill as a ranked candidate. */
+    private skillCandidate;
+    /** Parse one SKILL.md file, or `undefined` when it is unreadable or invalid. */
+    private tryParse;
+}
+//# sourceMappingURL=agents-md-skill-provider.d.ts.map

package/lib/types/driver-core/assistant-stream.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Live assistant-stream framing for the hosted engines.
+ *
+ * Harness 0.1.5 made the model stream the durable record of an assistant
+ * attempt: `assistant/message` embeds its exact timed stream and may no longer
+ * cite `sourceEventSeqs`, and the transient per-chunk log events the plugin
+ * used to append (`assistant/chunk`) no longer exist. Live partials now travel
+ * through the process-local `agent/assistant-stream` notification instead, and
+ * the compact records are handed to the durable message.
+ *
+ * This is the driver-side equivalent of the loop's `AssistantStreamAttempt`,
+ * minus the block assembly: a hosted engine keeps assembling its own
+ * authoritative transcript from its own protocol, and this class only frames
+ * the attempt and compacts its stream for replay fidelity.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/assistant-stream
+ */
+import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
+import { LlmAttemptId, type AssistantStreamRecord, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { SessionId, SessionSeq } from '@deepseek-ai/dsh-session';
+/**
+ * One model attempt on a hosted engine: ordered live frames plus the compact
+ * stream the durable `assistant/message` carries.
+ */
+export declare class DriverAssistantStream {
+    private readonly turn;
+    private readonly step;
+    private readonly emit;
+    private accumulator;
+    private index;
+    private revision;
+    private terminal;
+    /** Attempt identity unique within this agent lifecycle. */
+    readonly attemptId: LlmAttemptId;
+    /**
+     * @param sessionId - identity embedded only in the agent-lifecycle-local attempt id.
+     * @param attempt - agent-local attempt counter.
+     * @param turn - durable turn owning the request.
+     * @param step - durable step owning the request.
+     * @param emit - agent-scoped notification publisher.
+     */
+    constructor(sessionId: SessionId, attempt: number, turn: number, step: number, emit: (frame: AssistantStreamFrame) => void);
+    /** Whether this attempt has already published its terminal frame. */
+    get ended(): boolean;
+    /** Publish the opening marker before the first delivered chunk. */
+    start(): void;
+    /** Snapshot one chunk once, then feed durable compaction and live publication. */
+    push(chunk: StreamChunk): void;
+    /** Exact compact stream for the durable assistant message. */
+    get stream(): AssistantStreamRecord[];
+    /**
+     * Close the current record run and return it, leaving later chunks in a
+     * fresh run. An engine whose protocol reports content segments (rather than
+     * one stream per message) cuts at each segment boundary, so every durable
+     * message embeds exactly the chunks its own content produced even though the
+     * live frames keep flowing through one attempt.
+     * @returns the compact records accumulated since the previous cut.
+     */
+    takeStream(): AssistantStreamRecord[];
+    /**
+     * Publish terminal settlement after the matching durable event commits.
+     * @param append - synchronous durable append returning its committed seq.
+     */
+    settle(append: () => SessionSeq): void;
+    /** Publish abandonment when no durable settlement can be committed. */
+    abandon(): void;
+}
+//# sourceMappingURL=assistant-stream.d.ts.map

package/lib/types/driver-core/context-files.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Context-file collection and body loading shared by the hosted engine
+ * drivers.
+ *
+ * Codex and Pi read per-directory instruction files (`AGENTS.md`; pi also
+ * accepts `CLAUDE.md` and prefers `AGENTS.override.md` inside any directory
+ * that has one) while walking from the session cwd up to the git root. The
+ * skill providers surface each collected set as one merged skill candidate so
+ * the dsh skill-injection seam (`/name` gestures) can carry it into the
+ * prompt; the body-loading helpers below feed both providers' list/get paths.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/context-files
+ */
+/** Per-directory context-file resolution policy for one engine. */
+export interface ContextFilePolicy {
+    /** Per-directory override file that replaces the primary files when present. */
+    readonly override?: string;
+    /** Per-directory primary files, tried in order until one exists. */
+    readonly primary: readonly string[];
+}
+/**
+ * The directory chain from `cwd` up to the git root, nearest first. Without a
+ * repository the chain is just the resolved `cwd` itself, matching
+ * {@link findProjectRoot}'s fallback so the walk stays bounded.
+ * @param cwd - the session working directory.
+ * @returns the chain of directories to inspect.
+ */
+export declare function projectAncestors(cwd: string): Promise<string[]>;
+/**
+ * Collect every directory's context file per the policy, from the session cwd
+ * up to the git root.
+ * @param cwd - the session working directory.
+ * @param policy - per-directory resolution policy.
+ * @returns existing context files, nearest directory first.
+ */
+export declare function collectProjectContextFiles(cwd: string, policy: ContextFilePolicy): Promise<string[]>;
+/**
+ * Read one file, or `undefined` when it is unreadable.
+ * @param path - the file to read.
+ * @returns the file body, or `undefined` on any failure.
+ */
+export declare function readOptionalFile(path: string): Promise<string | undefined>;
+/**
+ * Whether any of the given sources carries non-whitespace content.
+ * @param paths - candidate file paths.
+ * @returns whether at least one readable source is non-empty.
+ */
+export declare function anySourceNonEmpty(paths: readonly string[]): Promise<boolean>;
+/**
+ * Whether one file exists and carries non-whitespace content.
+ * @param path - the file to inspect.
+ * @returns whether the file is readable and non-empty.
+ */
+export declare function fileNonEmpty(path: string): Promise<boolean>;
+/**
+ * Concatenate every non-empty readable source body in order, or `undefined`
+ * when none are readable.
+ * @param paths - candidate file paths, nearest directory first.
+ * @returns the joined bodies, or `undefined` when nothing could be read.
+ */
+export declare function readSources(paths: readonly string[]): Promise<string | undefined>;
+//# sourceMappingURL=context-files.d.ts.map

package/lib/types/driver-core/host-servers.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Minimal structural shapes of the optional host registries the plugin
+ * extends.
+ *
+ * Declared locally rather than imported from their packages: the plugin
+ * depends on the SERVICE CONTRACTS it consumes only where the harness exposes
+ * one (`dsh-agent`, `dsh-session`, …), and the command/skill registries are
+ * read through `ctx.get` and may legitimately be absent in a minimal profile.
+ * Keeping the shapes here means one definition shared by every consumer and no
+ * peer dependency that a headless composition does not need.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/host-servers
+ */
+import type { CommandDefinition } from '../commands.ts';
+import type { SkillProvider, SkillProviderControl } from '../skills.ts';
+import type { SettingsNamespace, SettingsPathOp } from '@deepseek-ai/dsh-settings';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { HostedEngineRouteAdapter } from '../provider-route.ts';
+/** The host command registry (`ctx.commands`), as this plugin uses it. */
+export interface CommandsService {
+    /** Register one definition in the calling context's scope layer. */
+    register(def: CommandDefinition): () => void;
+}
+/** The host skill registry (`ctx.skills`), as this plugin uses it. */
+export interface SkillsService {
+    /** Register a provider in the calling context's scope layer. */
+    registerProvider(create: (control: SkillProviderControl) => SkillProvider): () => void;
+}
+/** The host preset roster (`ctx.agentPresets`), as this plugin uses it. */
+export interface AgentPresetsService {
+    /** The effective default preset id. */
+    readonly defaultId: string;
+    /**
+     * The presets this roster serves, when it can enumerate them. Authoring a
+     * preset can report success while the roster still serves nothing (each
+     * generation reads presets out of a different carrier), so a caller that is
+     * about to NAME one of them asks the roster itself rather than the disk.
+     */
+    list?(): Promise<readonly {
+        readonly id: string;
+    }[]>;
+    /** 0.1.5 line: read one preset's composition text directly. */
+    read?(id: string): Promise<string>;
+    /** 0.1.7 line: read one preset's document; its `content` is the composition text. */
+    readDocument?(id: string): Promise<{
+        readonly content: string;
+    }>;
+}
+/** The host settings service's mutation seam, as this plugin uses it. */
+export interface SettingsMutator {
+    /** Apply ops to one namespace. */
+    mutate(ns: SettingsNamespace, ops: readonly SettingsPathOp[]): Promise<void>;
+    /** Registered namespaces, when the provider can enumerate them. */
+    describe?(): SettingsDescriptorLike[];
+}
+/**
+ * One registered settings namespace, as the host describes it
+ * (`@deepseek-ai/dsh-settings` `SettingsDescriptor`). Only the two fields this
+ * plugin reads are declared.
+ */
+export interface SettingsDescriptorLike {
+    /** Namespace name. */
+    readonly ns: string;
+    /**
+     * The composition's own value for this namespace, before the user layer. It is
+     * what a saved user-layer value overrode, which is why `model-selection-reset.ts`
+     * reads it: the deployment's own configured default model is a real model it
+     * can name when the saved default does not.
+     */
+    readonly base?: unknown;
+}
+/** The host llm registry (`ctx.llm`), as this plugin uses it. */
+export interface LlmRegistry {
+    /** Register a placeholder adapter for one or more provider labels. */
+    registerAdapter(providers: string[], adapter: HostedEngineRouteAdapter): () => void;
+}
+/** The host session-projection registry (`ctx.sessionProjections`), as this plugin uses it. */
+export interface SessionProjectionsService {
+    /** Folded projection state of one session, or undefined when it never advanced. */
+    stateOf(session: Session, key: 'turnBoundary'): TurnBoundaryFacts | undefined;
+    /** The same fold for the durable model selection (`model-selection-reset.ts`). */
+    stateOf(session: Session, key: 'modelSelection'): ModelSelectionFacts | undefined;
+}
+/**
+ * One complete model selection as the host's `model/selection` event and its
+ * projection carry it (`packages/api/session-controller/src/types.ts`,
+ * `ModelSelection`).
+ */
+export interface SessionModelSelection {
+    /** Registered provider route. */
+    readonly provider: string;
+    /** Provider-owned model id. */
+    readonly model: string;
+    /** Adapter-owned reasoning effort, or provider/default behavior when absent. */
+    readonly reasoningEffort?: string;
+}
+/**
+ * The slice of the host's `modelSelection` projection state this plugin reads.
+ * `lastUsed` is deliberately not declared: it is that fold's view of the newest
+ * `request/header`, which the plugin reads from the session itself
+ * (`Session.requestHeader()`) with the same result.
+ */
+export interface ModelSelectionFacts {
+    /** Later selection not yet consumed by a matching recorded request, or null. */
+    readonly pending: SessionModelSelection | null;
+}
+/**
+ * The turn-boundary facts this plugin reads. Mirrors `TurnBoundaryProjection`
+ * in `@deepseek-ai/dsh-agent` without depending on that module's projection
+ * registry augmentation, which a non-plugin consumer has no other reason to
+ * pull into its program.
+ */
+export interface TurnBoundaryFacts {
+    /** Seq of the open turn's `turn/start`, or null between turns. */
+    readonly openTurnStartSeq: number | null;
+    /** Turn number of the latest `turn/start`; 0 before the first turn. */
+    readonly lastTurn: number;
+}
+//# sourceMappingURL=host-servers.d.ts.map

package/lib/types/driver-core/hosted-engine-runtime.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Shared AgentFactory transaction machinery for the hosted loop engines.
+ *
+ * Every hosted engine (Claude Code, Codex, Pi, Kimi Code, Antigravity, ZCode, Qoder CN, Hermes, Grok Build, MiniMax Code) implements the harness's
+ * AgentFactory contract the same way: prepare a driver, scope, and one memoized
+ * reverse teardown for a session; run the caller's setup under a fused abort
+ * signal; publish through both registries and announce; and on resume, own a
+ * session's write handle across the cold read, crash repair, and
+ * re-publication. None of that touches an engine protocol — the whole
+ * engine-specific surface is one call, {@link HostedEngineRuntime.buildAgent}.
+ *
+ * One move has no counterpart in the harness's own factory contract and is what
+ * makes an in-place engine swap possible: a LIVE session changes drivers without
+ * being released. {@link HostedAgentHandle.retire} stops the outgoing machine
+ * while leaving the session entered, and {@link HostedEngineRuntime.swap} builds
+ * the incoming engine's machine onto that same Session. The session's store
+ * entry and write handle travel across the handover in a
+ * {@link SessionLifetime} — the one object that owns them.
+ *
+ * This body mirrors the default in-process `agent-loop` factory. It is a plain
+ * class, not a Cordis plugin: the process-wide AgentFactory slot is owned by
+ * the router (`router-loop.ts`, which subclasses the harness `AgentLoop`), and
+ * every hosted engine is one runtime instance the router delegates to. That is
+ * what lets several engines serve different sessions concurrently — the
+ * harness admits exactly one factory, so the factory itself must dispatch.
+ *
+ * Subclasses supply:
+ *   - the effect label prefix (`<label>.transactions()`,
+ *     `<label>.lifecycle(id)`, `<label>.resume-load(id)`) — the lifecycle label
+ *     is asserted by tests, so it must stay `<label>.lifecycle(...)`;
+ *   - their own configuration resolution;
+ *   - {@link HostedEngineRuntime.buildAgent}.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/hosted-engine-runtime
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentFactory, AgentHandle, AgentOptions, AgentSetup, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import { SessionLifetime } from './session-lifetime.ts';
+/**
+ * What the transaction machinery needs of a driver beyond the harness `Agent`
+ * contract: a teardown entry point that also unwinds the driver's own scope.
+ * The concrete engines declare these; the base only spells them out so the
+ * shared body can call them generically.
+ */
+export interface HostedAgent extends Agent {
+    /** Stop the machine with the given cause, without waiting for it to settle. */
+    cancel(cause: Parameters<Agent['cancel']>[0]): void;
+    /** Resolves when the machine has no work in flight. */
+    whenIdle(): Promise<void>;
+    /** The driver's own resource scope, unwound after the machine settles. */
+    readonly scope: Scope;
+}
+/**
+ * The plugin's own handle for one published hosted agent: the harness contract
+ * plus the two facts an in-place engine swap needs.
+ *
+ * A swap is two moves by two different runtimes: the outgoing engine retires its
+ * machine and hands the session over, and the incoming engine builds onto that
+ * session. The router is the only caller and it tracks the handle already, so
+ * the harness's own `AgentHandle` — which carries neither fact — is widened
+ * here rather than reaching back into a transaction that has ended.
+ */
+export interface HostedAgentHandle extends AgentHandle {
+    /** The live session's lifetime resources, owned by this agent until it is disposed. */
+    readonly lifetime: SessionLifetime;
+    /**
+     * Retire this machine for good while LEAVING the session alive: stop it,
+     * unwind its scope, and leave the agent registry — the session's entry and
+     * write handle pass to {@link SessionLifetime}'s next owner instead of being
+     * released here. Only valid while this agent still owns the session: the
+     * router calls it for the session's live, idle agent only.
+     */
+    retire(): Promise<void>;
+}
+/** Options for {@link HostedEngineRuntime.swap}. */
+export interface SwapAgentOptions {
+    /** The live session's lifetime resources, handed over by the outgoing engine. */
+    readonly lifetime: SessionLifetime;
+    /** Loop options for the successor; the router replays the outgoing agent's own. */
+    readonly agentOptions?: AgentOptions | undefined;
+    /** The composition callback the session was built with, replayed onto the successor. */
+    readonly setup?: AgentSetup | undefined;
+    /** The outgoing agent's runtime owner, for a child session's inherited ownership. */
+    readonly parentAgent?: Agent | undefined;
+}
+/**
+ * Concrete creation/resume machinery for one hosted engine.
+ *
+ * Creation and resume follow the registry factory contract and the shared
+ * publication transaction: prepare, run setup, then publish through both
+ * registries and await the serial `agent/created` announcement. {@link swap}
+ * follows the same transaction onto a session another agent entered, which is
+ * the only difference between taking a session over and owning it from birth.
+ */
+export declare abstract class HostedEngineRuntime<TConfig, TAgent extends HostedAgent> implements AgentFactory {
+    /** Validated configuration owned by this engine instance. */
+    readonly config: TConfig;
+    /** Effect-label prefix; also identifies the engine in diagnostics. */
+    readonly label: string;
+    /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
+    protected readonly runtime: {
+        ctx: Context;
+    };
+    private readonly ownership;
+    /**
+     * @param ctx - the owning context; its fiber's unload tears every live agent down.
+     * @param label - effect-label prefix, e.g. `agentLoopKimi`.
+     * @param config - already-resolved engine configuration.
+     */
+    constructor(ctx: Context, label: string, config: TConfig);
+    /**
+     * Construct this engine's driver for one prepared session. Called once per
+     * create, resume, or swap, after the session exists and before setup runs; the
+     * hook is the engine's entire protocol surface.
+     */
+    protected abstract buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): TAgent;
+    /**
+     * Construct the driver, scope, and one memoized reverse teardown for a new
+     * agent. The teardown is registered with the factory and the owner fiber
+     * BEFORE publication, so a mid-setup unload rolls everything back; `signal`
+     * fuses caller cancellation with lifecycle teardown for setup awaits.
+     *
+     * `lifetime` carries the session's store entry and write handle rather than
+     * this body owning them: a fresh transaction binds them when it publishes,
+     * while a swap publishes a session whose entry another machine already bound
+     * and whose write handle another machine already opened.
+     */
+    private prepare;
+    /** Prepare one Agent around an acquired Session, run setup, and publish it. */
+    private setupAndPublish;
+    /**
+     * Create an agent and session under one caller-supplied identity, owned by
+     * the accessing fiber. When a persistence backend is mounted, the session's
+     * durable identity is stored before publication.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - identities, optional live parent, session seed/metadata, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<HostedAgentHandle>;
+    /**
+     * Take a fresh session's write ownership when persistence is mounted.
+     * Nothing is appended here: the constructor seed (which never re-emits
+     * through `session/event`) is stored by {@link appendUnstoredSuffix} at the
+     * publication commit point, so a failed or cancelled setup closes an
+     * unmaterialized handle and leaves no stored residue — the same id can be
+     * created again.
+     * @param session - the unpublished session to store.
+     * @param signal - optional cancellation forwarded to the backend create.
+     * @returns the owned handle and stored cursor, or `undefined` without a backend.
+     */
+    private createStoredSession;
+    /**
+     * Durably store the session events appended since the last stored cursor.
+     * Pre-publication appends (constructor seed markers, setup-window events)
+     * never re-emit through `session/event`, so publication must flush them
+     * through the handle before live events start routing into it.
+     * @param stored - the session's owned handle and stored cursor, if any.
+     * @param session - the unpublished session whose suffix is stored.
+     */
+    private appendUnstoredSuffix;
+    /**
+     * Resume an owned agent from the configured persistence service.
+     * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+     * @param options - persisted identity, optional live parent, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<HostedAgentHandle>;
+    /**
+     * Build this engine's agent onto a LIVE session another engine's agent left,
+     * taking the session's lifetime over.
+     *
+     * The counterpart of {@link HostedAgentHandle.retire}: together they are an
+     * in-place engine swap, and the harness's own factory contract has neither.
+     * Nothing is read from persistence and nothing is created in the store — the
+     * successor drives the Session object that is already live and already
+     * entered, so a browser half attached to that session sees no lifecycle edge
+     * at all. The lifetime carries the still-open write handle, so the session
+     * keeps being stored through the same channel it was already using.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - the live session's lifetime, loop options, setup, and parent.
+     * @returns the published handle, which owns the session from here on.
+     */
+    swap(ownerCtx: Context, options: SwapAgentOptions): Promise<HostedAgentHandle>;
+    /** Resume through an explicit persistence service. */
+    private resumeWith;
+}
+//# sourceMappingURL=hosted-engine-runtime.d.ts.map