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

package/lib/types/driver-core/hosted-tool-vocabulary.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Projection of a hosted engine's tool vocabulary onto dsh's, plus the plan
+ * snapshot a hosted plan tool carries.
+ *
+ * The durable `tool/call` event is what the Web client's tool rows
+ * (`@deepseek-ai/dsh-client-ui-chat`'s tool Definition), the produced-files row
+ * and inline file links (`@deepseek-ai/dsh-client-ui-deliverables`'
+ * `mutationPath`), and the trajectory view read. Those consumers recognize only
+ * dsh's own tool names and argument shapes, while a hosted engine names its
+ * tools differently: Claude's `Write`/`Edit`/`Read`/`Bash`, Codex's
+ * `apply_patch`/`command_execution`, Kimi's title-cased `Bash`, Pi's
+ * `path`-keyed arguments. This module projects a hosted call onto dsh's
+ * vocabulary, and each driver feeds the projected values to BOTH writers — the
+ * durable `tool/call` event and the matching `tool-call` block in the assistant
+ * message that advertised it. Session V4 pairs the two by `id` and rejects a
+ * log whose block and event disagree on `name` or `arguments`, so the two sides
+ * must be byte-identical and both carry dsh's spelling. That spelling also lets
+ * an assistant message replayed into an in-process turn name a tool dsh's
+ * registry actually has (`bash`, not `Bash`).
+ *
+ * Only lossless projections are applied. A call whose arguments do not carry
+ * the dsh fields is passed through unchanged and simply renders as a generic
+ * row, so a new engine-side tool degrades instead of mis-rendering.
+ *
+ * Plan extraction is separate: dsh's todo panel is driven by the `todo/write`
+ * session event, not by the tool row, so a driver appends that event for the
+ * plan tool it recognizes.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/hosted-tool-vocabulary
+ */
+/** A hosted loop engine id — the settings engine union without `in-process`. */
+export type { HostedEngineId } from '../engine-registry.ts';
+import type { HostedEngineId } from '../engine-registry.ts';
+/** One tool call projected into dsh's vocabulary for the durable `tool/call` event. */
+export interface NormalizedHostedToolCall {
+    /** dsh tool name when the projection recognizes the call, else the engine's own spelling. */
+    readonly name: string;
+    /** dsh-shaped arguments JSON when the projection rewrites them, else the engine's own string. */
+    readonly arguments: string;
+}
+/** One plan entry in the shape the `todo/write` event and the todo panel consume. */
+export interface HostedPlanTodo {
+    /** The task line, verbatim. */
+    readonly content: string;
+    /** Lifecycle state, restricted to dsh's three-state union. */
+    readonly status: 'pending' | 'in_progress' | 'completed';
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        'todo/write': {
+            todos: {
+                content: string;
+                status: 'pending' | 'in_progress' | 'completed';
+            }[];
+        };
+    }
+}
+/**
+ * Project one hosted tool call onto dsh's `tool/call` vocabulary. A driver
+ * calls this once per call and writes the SAME name and arguments to both the
+ * assistant message's `tool-call` block and the durable `tool/call` event, so
+ * Session V4's id-and-payload pairing holds.
+ * @param engine - the hosted engine the call came from.
+ * @param name - the engine's own tool name.
+ * @param argumentsJson - the engine's arguments JSON, verbatim.
+ * @returns the dsh name and (when reshaped) dsh-shaped arguments.
+ */
+export declare function normalizeHostedToolCall(engine: HostedEngineId, name: string, argumentsJson: string): NormalizedHostedToolCall;
+/**
+ * Read the whole todo list a hosted plan tool wrote, in the shape the
+ * `todo/write` session event carries.
+ * @param engine - the hosted engine the call came from.
+ * @param name - the engine's own tool name.
+ * @param argumentsJson - the engine's arguments JSON, verbatim.
+ * @returns the plan entries (possibly empty) when the call is a plan write, else `undefined`.
+ */
+export declare function planTodosOfHostedTool(engine: HostedEngineId, name: string, argumentsJson: string): readonly HostedPlanTodo[] | undefined;
+//# sourceMappingURL=hosted-tool-vocabulary.d.ts.map

package/lib/types/driver-core/idle-child.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Idle shutdown for a driver's persistent child process.
+ *
+ * Two engines keep one child alive per session so a step never pays a spawn:
+ * Kimi's `kimi acp` and Codex's app-server. Nothing in the harness releases an
+ * agent when a turn ends — an agent lives as long as its session's scope — so
+ * that child outlives the work that needed it and an idle session keeps
+ * costing what its child costs (tens to hundreds of MB for a Node CLI). The
+ * closer arms a countdown whenever its owner goes idle and runs the owner's
+ * close when the countdown expires, so the next step's own lazy accessor
+ * spawns a fresh child.
+ *
+ * The closer is inert unless `idleMs` is positive: a deployment that does not
+ * configure idle shutdown keeps every child for the process's lifetime, which
+ * is the behaviour that predates this reasoner.
+ *
+ * This is deliberately NOT an agent release: disposing the agent emits
+ * `session/disposed`, which the browser half reads as "this session is gone"
+ * with no way back in that page's lifetime (`router-loop.ts` `move`). Closing
+ * the child leaves the agent, the session, and the page exactly where they are.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/idle-child
+ */
+/** An armed-on-idle countdown that closes one child process. */
+export interface IdleChildCloser {
+    /**
+     * (Re)start the countdown. Called when the owner settles into an idle phase;
+     * a no-op while idle shutdown is disabled.
+     */
+    arm(): void;
+    /**
+     * Cancel a pending countdown, for the moment the child is needed again.
+     * Cancelling a countdown that never armed is a no-op.
+     */
+    cancel(): void;
+    /**
+     * Cancel the countdown and drop the timer. Called from the owner's teardown,
+     * so a disposed agent never closes a child through a stale callback.
+     */
+    dispose(): void;
+}
+/** Input of {@link createIdleChildCloser}. */
+export interface IdleChildCloserOptions {
+    /** Idle window in milliseconds; zero or less leaves the child alone forever. */
+    readonly idleMs: number;
+    /** Close the child; the owner's next accessor call spawns a fresh one. */
+    readonly close: () => void;
+    /** Report a failing close without letting it escape the countdown. */
+    readonly warn: (message: string) => void;
+}
+/**
+ * Build one owner's idle countdown.
+ * @param options - the idle window, the close to run, and a diagnostic sink.
+ * @returns the closer, inert while the idle window is not positive.
+ */
+export declare function createIdleChildCloser(options: IdleChildCloserOptions): IdleChildCloser;
+//# sourceMappingURL=idle-child.d.ts.map

package/lib/types/driver-core/image-access.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Image access for the hosted transcript. The transcript is text, so an image
+ * block of the durable log reaches an engine through it only as placeholder
+ * text — engines whose own protocol takes image bytes receive those bytes
+ * separately. The host's attachment service owns the normalized bytes and can
+ * name the read-only path they live at; this module turns that service into the
+ * resolver the transcript renders placeholders with.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/image-access
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ImageAttachmentAccessResolver } from '@deepseek-ai/dsh-llm';
+/**
+ * Build the resolver a hosted agent hands to `serializeHistory`, so a
+ * transcript can name the file behind each image the log carries.
+ *
+ * The service is read on every call — the pattern this plugin uses for every
+ * optional host service — so a resolver built before the attachment service
+ * mounts still answers once it has, and no path is ever cached across steps:
+ * the transcript stays a pure function of the durable log.
+ * @param ctx - the loop context whose host may compose the attachment service.
+ * @returns a resolver answering `{ readonlyPath }`, or `undefined` when the service or the path is absent.
+ */
+export declare function createImageAccessResolver(ctx: Context): ImageAttachmentAccessResolver;
+//# sourceMappingURL=image-access.d.ts.map

package/lib/types/driver-core/inbox.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Driver-owned durable inbox for the hosted engines.
+ *
+ * Harness 0.1.5 turned `Inbox` from a concrete class into an interface the
+ * driver owns, so this module carries the projection the plugin used to
+ * construct from `dsh-agent`: pending input is folded from the session's own
+ * `agent/inbox/spliced` events and every mutation commits a normalized splice
+ * back into that log before the live lists change. The durable event stream is
+ * what the web client's conversation reducer and session resume both read, so
+ * the semantics match the removed class exactly.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/inbox
+ */
+import type { Inbox, InboxTarget } from '@deepseek-ai/dsh-agent';
+import type { MessageId } from '@deepseek-ai/dsh-llm';
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session';
+/** Live notifications committed by inbox mutations. */
+export interface InboxNotifications {
+    /** Publish one inserted message. */
+    inserted(message: UserMessage): void;
+    /** Publish one discarded message. */
+    discarded(message: UserMessage): void;
+    /** Publish one claimed message inside its owning turn. */
+    claimed(message: UserMessage, turn: number): void;
+}
+/**
+ * A replay-once projection of the session's durable inbox splices. Unlike the
+ * harness's driver inbox, this one keeps its own fold instead of registering a
+ * session projection, because the hosted engines drive sessions whose preset
+ * context is not the agent-loop's.
+ */
+export declare class DriverInbox implements Inbox {
+    private readonly session;
+    private readonly notifications;
+    private readonly state;
+    constructor(session: Session, notifications: InboxNotifications);
+    /** Prompts awaiting individual turns. */
+    get nextTurn(): readonly UserMessage[];
+    /** Input awaiting the next step boundary. */
+    get nextStep(): readonly UserMessage[];
+    /** Whether either pending-message list contains work. */
+    get hasPending(): boolean;
+    /** Durably cancel all pending input, clearing next-step before next-turn. */
+    clear(): void;
+    /**
+     * Remove and return the complete batch proposed for one step, publishing
+     * each claimed message. The durable splices are pure deletions.
+     * @param target - whether this boundary also consumes one queued turn.
+     * @param turn - turn that will own the claimed batch.
+     * @returns next-step input followed by the queued turn, when requested.
+     */
+    claim(target: InboxTarget, turn: number): UserMessage[];
+    /**
+     * Append one message to a pending list and durably record the insertion.
+     * @param target - pending list to extend.
+     * @param message - message to append.
+     * @throws if the message identity is already pending.
+     */
+    append(target: InboxTarget, message: UserMessage): void;
+    /**
+     * Prepend one message to a pending list and durably record the insertion.
+     * @param target - pending list to extend.
+     * @param message - message to prepend.
+     * @throws if the message identity is already pending.
+     */
+    prepend(target: InboxTarget, message: UserMessage): void;
+    /**
+     * Replace one pending message in place, possibly changing its identity. A
+     * successful replacement publishes the old message as discarded and the new
+     * message as inserted.
+     * @param messageId - identity of the pending message to replace.
+     * @param newMessage - replacement message.
+     * @returns whether the message was still pending.
+     * @throws if the replacement duplicates another pending message identity.
+     */
+    replace(messageId: MessageId, newMessage: UserMessage): boolean;
+    /**
+     * Remove one pending message and durably record its cancellation.
+     * @param messageId - identity of the pending message to remove.
+     * @returns whether the message was still pending.
+     */
+    remove(messageId: MessageId): boolean;
+    /**
+     * Apply standard splice semantics and durably record the normalized result.
+     * The durable event commits before the live projection mutates, so
+     * synchronous `session/event` observers see the pre-splice lists and can
+     * reconstruct the removed messages from the normalized coordinates.
+     * @param target - pending list to mutate.
+     * @param start - splice position.
+     * @param deleteCount - maximum number of messages to remove.
+     * @param inserted - messages to insert at the resolved position.
+     * @returns messages removed by the splice.
+     */
+    splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];
+    /** Locate one pending identity across both owned lists. */
+    private locate;
+    /** Commit one normalized mutation and publish its live notifications. */
+    private mutate;
+    /** Apply one normalized durable splice to the projection. */
+    private apply;
+    /** Validate one normalized splice against the current projection. */
+    private validate;
+}
+//# sourceMappingURL=inbox.d.ts.map

package/lib/types/driver-core/model-handover.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The dsh endpoint, protocol, and credential a hosted engine is handed when a
+ * session selects a REAL dsh model — the second half of the model handover
+ * whose first half (`session-model.ts`) only carries the model name.
+ *
+ * A hosted engine owns its model natively, and today it also owns the endpoint
+ * and the credential: each CLI keeps its own provider table. That is why
+ * "handing over a dsh model" used to mean "the engine can find that model name
+ * in its own configuration". This module answers the other question — what
+ * `baseURL`, wire protocol, and credential does the session's selection name in
+ * dsh's own settings — so each driver can point its engine at dsh's endpoint.
+ *
+ * The two reads are the host's own seams, deliberately:
+ *
+ *  - the provider → settings address mapping comes from the llm registry's
+ *    configurable-provider directory (`LlmRuntime.listConfigurableProviders`,
+ *    `packages/llm/llm/src/types.ts` `LlmConfigurableProvider`). That directory
+ *    is the authoritative answer to "which namespace, at which path, configures
+ *    provider X": `llm-pi-ai` maps a route to `['providers', route]` under
+ *    `llm-pi-ai`, `llm-deepseek` maps its one route to the whole `llm-deepseek`
+ *    section. Reading the directory rather than hardcoding namespaces is what
+ *    keeps this plugin from inventing a mapping the deployment did not make.
+ *  - the credential is resolved through the credentials seam, because the
+ *    profile stores an `apiKeyEnv` NAME and its value lives in the harness's
+ *    credential store, never in the process environment
+ *    (`packages/bundle/base/cordis.patch.yml`).
+ *
+ * Both reads are reads of ANOTHER plugin's private namespace, and no contract in
+ * the harness guarantees their shape. Every step is therefore defensive: a shape
+ * this module does not recognize resolves to `undefined` (the engine keeps its
+ * own configuration, exactly today's behavior) and one warning, never a throw
+ * and never a guess. The warning names the provider and the model, never a
+ * credential.
+ *
+ * What counts as "recognized" is deliberately narrow: a non-empty `baseURL` and
+ * a resolvable credential. The wire protocol is handed over when the deployment
+ * declares one, but its absence does NOT refuse the handover — see
+ * {@link resolveModelHandover} and {@link SHIPPED_ROUTE_APIS}.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/model-handover
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionModelOverride } from './session-model.ts';
+/**
+ * The endpoint facts one hosted engine needs to speak to the dsh model a session
+ * selected: the model id, the base URL, dsh's wire protocol name for it, and the
+ * resolved credential value.
+ *
+ * The protocol is carried verbatim (`llm-pi-ai` values such as
+ * `anthropic-messages`, `openai-completions`, `openai-responses`), because each
+ * engine translates it into its own vocabulary — and an engine whose protocol
+ * the endpoint does not speak is left to fail loud on its own request rather
+ * than being silently given a different endpoint.
+ */
+export interface DshModelHandover {
+    /** Provider route the selection named (the engine's provider key). */
+    readonly provider: string;
+    /** Provider-owned model id the selection named. */
+    readonly model: string;
+    /** Endpoint base as dsh configured it. */
+    readonly baseURL: string;
+    /**
+     * dsh's wire protocol name for this endpoint, when the deployment declares
+     * one (or {@link SHIPPED_ROUTE_APIS} knows it for a shipped route). `undefined`
+     * is a normal answer, not a failure: engines that need a protocol degrade the
+     * way each one documents, and engines that do not (`claude-code`) ignore it.
+     */
+    readonly api: string | undefined;
+    /** The resolved credential value; never logged, never evented. */
+    readonly apiKey: string;
+}
+/**
+ * One entry of the host llm registry's configurable-provider directory
+ * (`LlmConfigurableProvider`), narrowed to the address fields this module reads.
+ */
+export interface ConfigurableProviderAddress {
+    /** Provider route key the entry activates when configured. */
+    readonly provider: string;
+    /** User-settings namespace whose section configures this provider. */
+    readonly settingsNs: string;
+    /** Path from that section root to this provider's profile; empty when the section IS the profile. */
+    readonly settingsPath: readonly string[];
+}
+/**
+ * The host llm registry (`ctx.llm`), as this module uses it.
+ *
+ * `listConfigurableProviders` is optional: a minimal profile may serve the
+ * registry without the directory, and an older harness may predate it. A
+ * missing directory is "cannot map", not an error — the engine keeps its own
+ * configuration.
+ */
+export interface LlmDirectoryService {
+    /** Every provider route an adapter can activate through configuration. */
+    listConfigurableProviders?(): readonly ConfigurableProviderAddress[];
+}
+/** The host settings service (`ctx.settings`), as this module uses it. */
+export interface SettingsReader {
+    /** Read one registered namespace's resolved value. */
+    get?(ns: string): unknown;
+}
+/** The host credentials seam (`ctx.credentials`), as this module uses it. */
+export interface CredentialsService {
+    /** Resolve one reference (an environment-variable NAME) to its current value. */
+    resolve(ref: string): Promise<{
+        readonly value: string;
+    } | undefined>;
+}
+/**
+ * Resolve the session's own model selection into the endpoint triple a hosted
+ * engine can dial, or `undefined` to leave the engine to its own configuration.
+ *
+ * `undefined` is the answer in exactly two situations: the selection names no
+ * real dsh model ({@link SessionModelOverride} is already `undefined` for the
+ * hosted seat), or a real model whose endpoint/credential dsh does not disclose
+ * to this read — no `baseURL`, or no credential. Both warn once: they are
+ * deployment-shape gaps the operator can see and fix, not a silent downgrade.
+ *
+ * The wire protocol is NOT such a gate. A profile that names no `api` still
+ * hands over its endpoint (with `api: undefined`), because refusing would let
+ * the engine send dsh's model id to the engine's OWN endpoint — a failure that
+ * reads like an auth or model problem while the real one is "wrong endpoint".
+ * Shipped routes whose adapter owns the wire are named in
+ * {@link SHIPPED_ROUTE_APIS} so they hand over a real protocol; anything still
+ * unknown degrades per engine, which is the engine's call to make.
+ *
+ * Called fresh on every step by each driver, so a model or provider picked
+ * mid-conversation reaches the engine's next request rather than being frozen
+ * when the agent was built.
+ * @param ctx - the driver's context, carrying the llm/settings/credentials seams.
+ * @param override - the session's dsh model selection, already judged by `sessionModelOverrideOf`.
+ * @returns the resolvable endpoint triple, or undefined to inject nothing.
+ */
+export declare function resolveModelHandover(ctx: Context, override: SessionModelOverride | undefined): Promise<DshModelHandover | undefined>;
+//# sourceMappingURL=model-handover.d.ts.map

package/lib/types/driver-core/ownership.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared engine ownership and abort-race machinery for the hosted engines.
+ * All four loop drivers (Claude Code, Codex, Pi, Kimi Code) run the same
+ * lifecycle: one runtime per engine owns that engine's live agents, every
+ * live agent's teardown is tracked until it settles, and setup awaits are
+ * raced against a fused abort signal. The process-wide AgentFactory slot is
+ * the router's, not any engine's; these helpers are engine-free — they only
+ * touch the fiber state, the session id type, and an AbortController — so the
+ * engine modules share them verbatim.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/ownership
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** Fiber states that cannot own or serve a new lifecycle. */
+export declare const INACTIVE_STATES: ReadonlySet<number>;
+/** Factory-level ownership: live agent teardowns plus load-time tracking. */
+export declare class FactoryOwnership {
+    private readonly fiber;
+    private accepting;
+    private readonly teardown;
+    private readonly inactive;
+    private readonly liveAgents;
+    private startupTasks;
+    constructor(fiber: Context['fiber']);
+    /** Aborts (reason: `agent loop is not active` error) when factory teardown begins. */
+    get signal(): AbortSignal;
+    isActive(): boolean;
+    /** Track one live agent's shared teardown until it has run. */
+    track(dispose: () => Promise<void>): () => void;
+    /** Join config startup work that begins before an agent exists. */
+    trackStartup(job: Promise<void>): void;
+    /** Join one public create/resume continuation; factory dispose awaits its settlement. */
+    trackWrapper(job: Promise<unknown>): void;
+    dispose(): Promise<void>;
+}
+/** Await `operation`, or throw the signal's reason as soon as it aborts. */
+export declare function raceAbort<T>(operation: PromiseLike<T> | T, signal: AbortSignal, id: SessionId): Promise<T>;
+/** Start an abortable operation and release a value that arrives after cancellation. */
+export declare function raceAbortCall<T>(operation: () => PromiseLike<T> | T, signal: AbortSignal, id: SessionId, releaseAbandoned?: (value: T) => void): Promise<T>;
+//# sourceMappingURL=ownership.d.ts.map

package/lib/types/driver-core/permission-knobs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reading the dsh session's durable permission knobs from the session log.
+ * Every hosted driver folds the same `sandbox/mode` and
+ * `approval/policy` events (pinned at creation, re-recorded on every switch)
+ * into per-query permission decisions; the knob readers are engine-free.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/permission-knobs
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/**
+ * Minimal structural shape of one session log event. The base `SessionEvent`
+ * union in this compilation does not carry the sandbox/approval packages'
+ * augmentation keys, so the fold reads the wire shape directly.
+ */
+export type PermissionEvent = Pick<SessionEvent, 'data'> & {
+    readonly type: string;
+};
+/** dsh sandbox modes, mirrored inline to avoid a peer dep on @deepseek-ai/dsh-sandbox-policy. */
+export type DshSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** dsh approval policies, mirrored inline to avoid a peer dep on @deepseek-ai/dsh-user-approval. */
+export type DshApprovalPolicy = 'ask' | 'never';
+/** The session's sandbox-mode override: the last `sandbox/mode` event, if any. */
+export declare function sessionSandboxMode(events: readonly PermissionEvent[]): DshSandboxMode | undefined;
+/** The session's approval-policy override: the last `approval/policy` event, if any. */
+export declare function sessionApprovalPolicy(events: readonly PermissionEvent[]): DshApprovalPolicy | undefined;
+//# sourceMappingURL=permission-knobs.d.ts.map

package/lib/types/driver-core/prompt.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Serialization of the durable session history into the prompt text of one
+ * hosted-engine query. Every hosted driver builds its
+ * per-step input from the durable session log: the transcript is the log's
+ * exact projection, so a later replay of the same log derives the identical
+ * prompt (Model-visible ⟺ logged bridge).
+ *
+ * A step whose live request is an engine slash command is the one exception to
+ * the transcript framing: {@link engineSlashPrompt} sends that command line
+ * verbatim, because the engines only recognize their own commands at the head
+ * of the prompt. It is still derived from the log alone, so the guarantee
+ * holds.
+ *
+ * An image block has no bytes in this output — the transcript is text — so it
+ * renders as placeholder text naming the image and the read-only path
+ * {@link createImageAccessResolver} resolves for it. The reference is the
+ * log's own, so the placeholder keeps the replay guarantee too, and it stays
+ * the invariant every engine keeps even when the engine's own protocol also
+ * receives the bytes ({@link stepImages}).
+ *
+ * @module dsh-loop-engine-allinone/driver-core/prompt
+ */
+import type { ImageAttachmentAccessResolver, Message } from '@deepseek-ai/dsh-llm';
+/** The one fact every omitted image placeholder states: a hosted engine takes text, never image bytes. */
+export declare const OMITTED_IMAGE_TEXT = "this engine receives text, not image bytes";
+/**
+ * The engine's own slash-command line to send as this step's entire prompt, or
+ * `undefined` when the step is an ordinary conversational step.
+ *
+ * Every hosted engine expands a slash command only when the text handed to it
+ * *starts* with `/` — Kimi's ACP adapter parses the first prompt block, Claude
+ * Code's local-command dispatch and Pi's input expansion both test the leading
+ * character of the message string. The serialized transcript never satisfies
+ * that (it opens with `<user>`), so a forwarded `/status` reaches the model as
+ * prose instead of the engine's own command surface. This helper lets a driver
+ * recognize the case and send the command line verbatim, with no transcript
+ * framing and no replay history: a slash command is a control line for the
+ * engine, not conversation for the model.
+ *
+ * The live request is the last derived message, so a step whose trailing
+ * message is a bare command line is a command step. A trailing skill-injection
+ * message (the `/name` skill gesture the drivers materialize as its own user
+ * message) displaces it and keeps the step on the transcript path.
+ *
+ * The returned line is a pure function of the log prefix, so the step stays
+ * replayable: the same log derives the same prompt.
+ * @param messages - derived history, oldest first, as returned by
+ *   `Session.deriveMessages()` at step time.
+ * @returns the raw command line, or `undefined` for an ordinary step.
+ */
+export declare function engineSlashPrompt(messages: readonly Message[]): string | undefined;
+/**
+ * Serialize a derived conversation history into the prompt text of one hosted
+ * query. The last message is the live user request that triggered the step;
+ * every earlier message is durable replay context. The output is a pure
+ * function of the log prefix.
+ * @param messages - derived history, oldest first, as returned by
+ *   `Session.deriveMessages()` at step time.
+ * @param imageAccess - resolves the read-only path of an image block's
+ *   attachment; without one, an image renders as the no-path placeholder.
+ * @returns the prompt text to pass to the engine.
+ */
+export declare function serializeHistory(messages: readonly Message[], imageAccess?: ImageAttachmentAccessResolver): string;
+//# sourceMappingURL=prompt.d.ts.map

package/lib/types/driver-core/session-lifetime.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The session-scoped half of one published hosted transaction: the session's
+ * entry in the store, and the write handle that stores its events.
+ *
+ * Ownership is ONE object rather than two closure variables because an engine
+ * swap MOVES it. A hot swap replaces a session's agent while the session itself
+ * stays live: the retiring machine hands its lifetime to the successor instead
+ * of releasing it, and the successor releases it later exactly as the agent that
+ * entered the session would have. Releasing it at the handover point would emit
+ * `session/disposed`, which the browser half reads as the session being gone —
+ * its session list drops the row, its composer renders "session unavailable",
+ * and the conversation view falls back to the workspace picker — so a live
+ * session would be torn out from under the page attached to it.
+ *
+ * The two release steps are separate operations because their ORDER around the
+ * agent registry's own release is load-bearing: `agent/disposed` is published
+ * after driver quiescence and BEFORE the session is detached (the event's
+ * contract in `@deepseek-ai/dsh-agent`), and the write handle closes before the
+ * store attachment is released so its buffered closing events are drained
+ * durably. Users of this type therefore close the handle, detach the agent, then
+ * leave the store.
+ *
+ * Neither step needs a memo of its own: `SessionHandle.close()` is idempotent by
+ * contract, and the detacher `SessionsService.enter` returns is single-shot.
+ *
+ * @module dsh-loop-engine-allinone/driver-core/session-lifetime
+ */
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { SessionHandle } from '@deepseek-ai/dsh-session-persistence';
+/**
+ * One live session's lifetime resources, owned by whichever agent drives it.
+ */
+export declare class SessionLifetime {
+    /** The live session these resources belong to. */
+    readonly session: Session;
+    /** The write handle this lifetime owns, or `undefined` when no persistence backend is mounted. */
+    private readonly handle;
+    /** The store's detacher; `undefined` until the entry is bound by the transaction that entered the session. */
+    private detach;
+    /**
+     * @param session - the live session whose entry and write handle these are.
+     * @param handle - the write handle the transaction acquired, if a backend is mounted.
+     */
+    constructor(session: Session, handle: SessionHandle | undefined);
+    /**
+     * Whether the session's store entry is already held: true for a lifetime a
+     * retiring machine handed over, false for one whose transaction still has to
+     * enter the session it prepared.
+     */
+    get entered(): boolean;
+    /**
+     * Bind the store entry this lifetime owns. Called once, by the transaction
+     * that enters the session; a joined session's entry is already bound.
+     * @param detach - the detacher the session's own `enter` returned.
+     */
+    bind(detach: () => void): void;
+    /** Drain and close the write handle — the durability barrier that precedes leaving the store. */
+    closeHandle(): Promise<void>;
+    /** Remove the session from the store, publishing its paired disposal exactly once. */
+    leaveStore(): void;
+}
+//# sourceMappingURL=session-lifetime.d.ts.map