dsh-pause-session 0.0.0-stage → 0.2.0

package/lib/types/coldlog.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Reading one parked session's stored log through a bound, and the facts the
+ * morning list may claim from what it read.
+ *
+ * The decision list reads the same log the wake reads, but for the opposite
+ * reason: the wake has to reproduce the session, so it reads everything. The
+ * list only has to name where the session stopped, which tool call the log
+ * never heard back from, and whether an answer is still owed — all of them
+ * facts about the log's END. Reading from seq 0 to the end for every row, on
+ * every time the panel opens, would make a long
+ * session's cost grow with a log nobody is asking about.
+ *
+ * WHAT THE BOUND BUYS. A stored log is append-only, so the tail is stable: the
+ * read takes the last {@link TRIAGE_WINDOW_EVENTS} events, or the whole log when
+ * it is shorter, and the answer is derived from that. The window is complete
+ * whenever the log fits inside it, which is the common case; the fold the rest
+ * of this plugin reads history through is then the harness's own, over exactly
+ * the events the harness would fold.
+ *
+ * WHAT THE TAIL ALONE PROVES. A truncated window still answers the list's
+ * questions, for one reason the harness guarantees: a dangling tool call exists
+ * only inside the step that is still open, because a step's end is written
+ * after its results. So an unanswered call is always inside the final open
+ * span, and the tail that contains that span contains every one of them. What
+ * the window cannot prove — a log a replacement event rewrote from further back
+ * — is not guessed at: {@link logFacts} reports `undefined` and the row says
+ * `unreadable`, because a list that invents a stop position is worse than a
+ * list that says it could not read one.
+ * @module dsh-pause-session/coldlog
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import type { TriageTrace } from './shared.js';
+/**
+ * Events the read looks at before it gives up. Sized to hold a whole final
+ * step — the model exchange, its tool calls, and their results — with room to
+ * spare, at a cost that does not grow with the session.
+ */
+export declare const TRIAGE_WINDOW_EVENTS = 2000;
+/**
+ * The longest log the read will walk while locating where its tail starts.
+ *
+ * The window's start is found by probing for the log's length, so a log longer
+ * than this cannot be located from its end at a cost worth paying for a panel
+ * left open. Such a log — a million stored events — is reported unreadable
+ * rather than read from the front, which is the read this module exists to
+ * avoid.
+ */
+export declare const TRIAGE_LOG_MAX_EVENTS = 1000000;
+/** How one stored log was seen by the bounded read. */
+export type ColdLog =
+/** The events the read returned, and whether they are the whole stored log. */
+{
+    readonly kind: 'read';
+    readonly events: readonly SessionEvent[];
+    readonly complete: boolean;
+}
+/** The log could not be opened or read, or it is longer than this read will walk. */
+ | {
+    readonly kind: 'unreadable';
+};
+/** The facts the decision list claims, all of them read off the log's end. */
+export interface ColdFacts {
+    /** What the stored log's last event was, and the turn/step it belongs to. */
+    readonly last: SessionEvent | undefined;
+    /** Tool calls the stored events record and no stored result answers. */
+    readonly traces: readonly TriageTrace[];
+    /** Whether the stored log ends owing the model an answer. */
+    readonly owed: boolean;
+    /** Whether the log names the route a wake would be addressed to. */
+    readonly wakeable: boolean;
+}
+/**
+ * The turn and step an event belongs to, when it carries them.
+ * @param event - one stored event.
+ * @returns the position fields the event has, and nothing for the fields it does not.
+ */
+export declare function positionOf(event: SessionEvent): {
+    readonly turn?: number;
+    readonly step?: number;
+};
+/**
+ * The facts one bounded read of a stored log supports.
+ *
+ * A complete read is folded by the harness's own derivation, so the list and
+ * the wake answer the "does it still owe a reply" question through one rule.
+ * A truncated read answers from the tail, and only where the tail is proof: a
+ * replacement event that rewrote a surface range from outside the window is
+ * not visible here, so a log whose tail a later event could have rewritten is
+ * reported unreadable rather than guessed at.
+ * @param events - the stored events the read returned, in sequence order.
+ * @param complete - whether those events are the whole stored log.
+ * @param projections - this process's registered message projections.
+ * @returns the row's facts, or `undefined` when this read cannot support them.
+ */
+export declare function logFacts(events: readonly SessionEvent[], complete: boolean, projections: Context['sessions']['messageProjections']): ColdFacts | undefined;
+/**
+ * Read one session's stored log, bounded to the events the list's facts need.
+ *
+ * The window is the last `windowEvents` events, found by probing for the log's
+ * length and then reading exactly that slice. A short log is returned whole and
+ * marked complete; a log longer than {@link TRIAGE_LOG_MAX_EVENTS} is reported
+ * unreadable without being read at all.
+ * @param ctx - host context carrying the optional persistence service.
+ * @param sessionId - the stored session to read.
+ * @param windowEvents - how many events of the log's end one row may fold.
+ * @param signal - cancellation for the open, probe, and read.
+ * @returns the bounded read, or `unreadable` when no read seam exists, it refused, or the log is too long to walk.
+ * @throws the cancellation reason when `signal` aborts the read.
+ */
+export declare function coldRead(ctx: Context, sessionId: SessionId, windowEvents?: number, signal?: AbortSignal): Promise<ColdLog>;

package/lib/types/composition.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Rebuild the scoped Agent composition a parked Session ran under.
+ *
+ * Activation is not only a persisted Session: the Agent preset supplies the
+ * scoped tools, prompt sections, skills, and — for a subagent child — the
+ * delegation context, persona, and tool restriction that were in force before
+ * the park. A resume that loads the log without that setup starts a different
+ * Agent on the same history.
+ *
+ * The preset a Session runs is the `agentPreset` projection, never the
+ * creation-time header alone: a blank Session may select another preset before
+ * its first turn, and the projection records the selection that actually ran.
+ * A child with no independent selection joins its live parent's preset
+ * generation; one that selected independently mounts the projected preset.
+ * The durable child descriptor supplies the persona, tool filter, and route
+ * that are reapplied only on cold resume.
+ *
+ * Both services are optional. A profile without `agentPresets` has no scoped
+ * preset composition to restore, and this module leaves the resume unchanged.
+ * A profile that mounts one but cannot read the Session projection cannot
+ * prove what composition the Session ran, so it fails the resume instead of
+ * silently starting a different Agent.
+ * @module dsh-pause-session/composition
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentOptions, AgentSetup } from '@deepseek-ai/dsh-agent';
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+/** The setup and route options a resumed Agent receives from its stored composition. */
+export interface RestoredComposition {
+    /** The durable child route, when the descriptor recorded one. */
+    readonly agentOptions?: AgentOptions;
+    /** The scoped Agent world to mount before the Agent is published. */
+    readonly setup?: AgentSetup;
+}
+/**
+ * A stored subagent route that no resume may reactivate.
+ *
+ * A one-shot child is terminal by contract; activating it as a root Agent
+ * would turn a finished delegation into an ordinary conversation that happens
+ * to share its Session id.
+ */
+export declare class UnresumableSessionError extends Error {
+    constructor(sessionId: SessionId);
+}
+/**
+ * Whether the child's own log selected a preset before its descriptor.
+ *
+ * The creation-time selection precedes the first `subagent/descriptor`; a
+ * selection after the descriptor belongs to the child's own later history and
+ * does not decide which composition cold resume joins. This mirrors the
+ * subagent runtime's own cold-resume rule.
+ * @param events - the child's own log suffix, without the fork-inherited prefix.
+ * @returns whether the child carries an independent preset selection.
+ */
+export declare function hasIndependentPresetSelection(events: readonly SessionEvent[]): boolean;
+/**
+ * Whether a local Session may be parked under a promise of a later resume.
+ *
+ * A normal root Session has no child descriptor and is resumable. A local
+ * subagent child is resumable only when its own durable descriptor is
+ * `continuable`; a historical `one-shot` child is terminal and must never be
+ * registered as a park the morning path would later have to refuse. External
+ * executions have no local Session, so callers never reach this check.
+ *
+ * A profile without the optional Session-query service cannot prove the
+ * descriptor's mode; it keeps the previous permissive behavior rather than
+ * dropping every subagent. The web profile mounts the query service.
+ * @param ctx - host context carrying the optional Session-query service.
+ * @param sessionId - the local Session to inspect.
+ * @param signal - cancellation for the observation read.
+ * @returns whether a park of this Session may be resumed.
+ * @throws the cancellation reason when `signal` aborts the read.
+ */
+export declare function isResumableSession(ctx: Context, sessionId: SessionId, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Read one parked Session's stored composition and build the resume options.
+ *
+ * The returned `setup` belongs to the unpublished Agent scope, so all
+ * registrations exist before `agent/created`. For a root Session the setup
+ * mounts the Session's projected preset, or the profile's default when the
+ * Session never selected one. For a child under a live parent it applies the
+ * child composition: an independent preset mounts separately, while an
+ * inherited composition joins the parent's current generation; the historical
+ * descriptor's persona and tool filter are reapplied in both cases.
+ * @param ctx - host context carrying the optional preset and Session-query services.
+ * @param sessionId - the parked Session being resumed.
+ * @param parent - the live direct parent, when a child is resumed under it.
+ * @param signal - cancellation for the observation read.
+ * @returns the Agent options and setup to pass to `agents.resume`.
+ * @throws {UnresumableSessionError} when the stored child route is one-shot.
+ * @throws when a mounted preset roster cannot read the Session projection, or
+ * a recorded preset cannot be restored.
+ */
+export declare function restoreComposition(ctx: Context, sessionId: SessionId, parent: Agent | undefined, signal?: AbortSignal): Promise<RestoredComposition>;

package/lib/types/control.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The session control the browser half drives: the pause verb, the park state
+ * machine behind it, and the live state channel that accompanies both.
+ *
+ * The host exposes this control through the native Typert Remote namespace:
+ * `observe` streams snapshots and `act` / `triage` / `decide` drive the UI. No
+ * slash command is registered. Phase changes wake the Remote stream through a
+ * local listener set; the durable registry remains the source of truth for what
+ * the snapshot reports.
+ * @module dsh-pause-session/control
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { PauseGate } from './gate.js';
+import type { ParkWatch } from './park.js';
+import type { ParkRegistry } from './registry.js';
+import type { ReleaseTreeOutcome, ResumeAttempt, ResumeOptions } from './resume.js';
+import type { TriageAction } from './shared.js';
+import type { PauseSnapshot, TriageList } from './shared.js';
+import type { PauseAnswer } from './shared.js';
+/** What one tree-wide press registered, and what it could not. */
+export interface PressTreeOutcome {
+    /** How many sessions this press covered: the session plus its descendants. */
+    readonly members: number;
+    /** How many of them now have a durable park record behind them. */
+    readonly registered: number;
+    /** Whether the pressed session itself is one of them. */
+    readonly rootRegistered: boolean;
+    /** The members whose record could not be written; they are not paused. */
+    readonly unrecorded: readonly SessionId[];
+    /** Whether any branch was unread, so the subagent tree was not fully covered. */
+    readonly unread: boolean;
+    /** Tree members on a one-shot or unreadable route; they were not registered. */
+    readonly unresumable: readonly SessionId[];
+    /** Branch ids the tree walk could not read. */
+    readonly unreadBranches: readonly SessionId[];
+}
+/** What mounting the session control hands back to the plugin entry. */
+export interface SessionControl {
+    /**
+     * Hold every session the registry remembers and can read, and publish the
+     * marker for the ones that already have a live agent. Called once, right
+     * after mount.
+     */
+    adopt(): Promise<void>;
+    /**
+     * Read the whole app and every live paused session as one JSON-safe snapshot.
+     * The native snapshot serves this; it never enters a Session log.
+     * @param signal - cancellation for the tree reads this snapshot performs.
+     * @returns the whole-app verdict and the paused sessions this process holds.
+     */
+    readSnapshot(signal?: AbortSignal): Promise<PauseSnapshot>;
+    /** Wake a listener after any visible status change. */
+    subscribe(listener: () => void): () => void;
+    /** Press one Session tree. */
+    pressTree(sessionId: SessionId, signal?: AbortSignal): Promise<PressTreeOutcome>;
+    /** Release one Session's registered tree. */
+    releaseTree(sessionId: SessionId, signal?: AbortSignal): Promise<ReleaseTreeOutcome>;
+    /** Press every running Session tree. */
+    pauseAll(signal?: AbortSignal): Promise<PauseAnswer>;
+    /** Resume every cleanly paused Session. */
+    resumeAll(signal?: AbortSignal): Promise<PauseAnswer>;
+    /** Release every registered tree, cancelling a press that is still draining. */
+    cancelAll(signal?: AbortSignal): Promise<PauseAnswer>;
+    /** Flip one Session's goal re-arm opt-out. */
+    toggleGoal(sessionId: SessionId, signal?: AbortSignal): Promise<PauseAnswer>;
+    /** Read the morning list for one calling Session. */
+    readTriage(caller: SessionId, signal?: AbortSignal): Promise<TriageList>;
+    /** Take one listed decision for one calling Session. */
+    decideTriage(caller: SessionId, target: SessionId, action: TriageAction, signal?: AbortSignal): Promise<PauseAnswer>;
+}
+/** How resuming all parked sessions answers the caller. */
+export declare function summarizeResume(attempts: readonly ResumeAttempt[]): string;
+/**
+ * Everything the session control needs from the composition: the clean resume
+ * path's route knowledge, plus the bound the decision list reads each parked
+ * log under.
+ */
+export interface SessionControlOptions extends ResumeOptions {
+    /** Events of each stored log the decision list may fold per row; see `./coldlog.ts`. */
+    readonly maxListedLogEvents?: number;
+}
+/**
+ * Contribute the session control: the pause verb, the per-session status read,
+ * the global resume verb, and — for every paused session that has a live agent
+ * — the resume marker.
+ * @param ctx - host context carrying the agent store, the
+ * session store, and the projection registry.
+ * @param gate - the pause gate this control drives and reflects.
+ * @param watch - the per-session activity fold the park predicate reads.
+ * @param registry - the durable pause list every phase change is written to.
+ * @param options - route knowledge the clean resume path needs, and the decision list's read bound.
+ * @returns the mount-time adoption step and the morning resume path.
+ */
+export declare function installSessionControl(ctx: Context, gate: PauseGate, watch: ParkWatch, registry: ParkRegistry, options: SessionControlOptions): SessionControl;

package/lib/types/gate.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The pause gate: one session's hold at the model-request waterfall.
+ *
+ * The hold sits on the `llm/stream` waterfall, which is the only point that
+ * satisfies all four conditions at once: the previous step's tool calls have
+ * drained, the request is already built, the session's pending input is
+ * committed, and — because nothing pulls the adapter — no timer is armed
+ * anywhere. Machine sleep, network loss, and the adapter's stream-idle
+ * watchdog therefore cannot touch a parked request.
+ * @module dsh-pause-session/gate
+ */
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** Message of the failure a held request ends with when its plugin unloads first. */
+export declare const PLUGIN_UNLOADED = "pause: plugin lifetime ended while a request was held";
+/** Options of {@link PauseGate}. */
+export interface PauseGateOptions {
+    /** Aborted when the owning plugin unloads; a held request must never delegate after that. */
+    readonly lifetime: AbortSignal;
+}
+/** Per-session pause state and the waterfall listener that enforces it. */
+export declare class PauseGate {
+    private readonly options;
+    /** Paused sessions; membership IS the pause state. */
+    private readonly paused;
+    private readonly listeners;
+    private readonly heldListeners;
+    /**
+     * @param options - the plugin-lifetime signal every held request races.
+     */
+    constructor(options: PauseGateOptions);
+    /**
+     * Subscribe to pause-state changes.
+     * @param listener - called with the session whose state changed and its new state.
+     * @returns the unsubscribe function.
+     */
+    onChange(listener: (sessionId: SessionId, paused: boolean) => void): () => void;
+    /**
+     * Subscribe to "a request arrived at / left the gate" for a paused session.
+     *
+     * This is the moment a session can become parked, so it is also the moment a
+     * park observer has to look. Listeners run synchronously inside the request
+     * path: they must only record that a look is owed.
+     * @param listener - called with the session and whether it now holds a request.
+     * @returns the unsubscribe function.
+     */
+    onHeld(listener: (sessionId: SessionId, held: boolean) => void): () => void;
+    /**
+     * @param sessionId - session to inspect.
+     * @returns whether the session is currently paused.
+     */
+    isPaused(sessionId: SessionId): boolean;
+    /**
+     * @param sessionId - session to inspect.
+     * @returns whether a model request of that session is waiting at the gate
+     * right now. False for a session that is paused but whose loop has not built
+     * its next request yet — a running tool, for instance, is still draining.
+     */
+    isHeld(sessionId: SessionId): boolean;
+    /**
+     * Enter one request that is about to wait. The count rises synchronously with
+     * {@link hold}, so an observer notified at that moment reads `isHeld` as true.
+     * @param pause - the session's pause record.
+     * @returns the exit that lowers the count again.
+     */
+    private enter;
+    /**
+     * Pause one session: its next model request is held until {@link resume}. A
+     * request already past the waterfall keeps running — pausing never
+     * interrupts a model call or a tool call that has started.
+     * @param sessionId - session to pause.
+     * @returns whether this call changed the state.
+     */
+    pause(sessionId: SessionId): boolean;
+    /**
+     * Resume one session: release everything it holds and stop holding what
+     * follows. The requests sent from then on are the ones built before the
+     * hold, so a resumed session continues from the point it stopped.
+     * @param sessionId - session to resume.
+     * @returns whether this call changed the state.
+     */
+    resume(sessionId: SessionId): boolean;
+    /**
+     * The wait one model request must finish before it may delegate, and the exit
+     * that reports the request as no longer waiting.
+     * @param request - the request reaching the waterfall.
+     * @returns the wait plus its release, or `undefined` when this gate does not
+     * hold that request.
+     */
+    hold(request: GenerateOptions): {
+        readonly wait: Promise<void>;
+        readonly left: () => void;
+    } | undefined;
+    /**
+     * The `llm/stream` listener.
+     *
+     * `ctx.waterfall` composes listeners synchronously, so this returns an async
+     * iterator synchronously — an `async` listener would hand the loop a promise
+     * where it iterates a stream. One generator body reaches `next()` at most
+     * once, which is what makes delegation single-shot per HELD request; a flag
+     * shared across requests would also short-circuit everything issued after
+     * the release.
+     * @param request - the full request, already built and frozen by the loop.
+     * @param next - the downstream waterfall chain.
+     * @returns the stream, delayed until this request may delegate.
+     */
+    readonly stream: (request: GenerateOptions, next: () => AsyncIterable<StreamChunk>) => AsyncIterable<StreamChunk>;
+    private notify;
+    private notifyHeld;
+}

package/lib/types/global.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The whole-app park: one action that registers every running session tree,
+ * and the aggregate answer to "can I close the lid?".
+ *
+ * The per-session control owns one session's park; this module owns the set.
+ * It reads three real sources and never infers what they can say themselves:
+ *
+ * - `ctx.agents.list()` plus the park activity fold decide which sessions are
+ *   running. A session with no live agent is not running, and a session with
+ *   nothing unfinished — no tool in flight, no turn open, no delivery the loop
+ *   has not claimed — is left alone.
+ * - The subagent runtime's descendant rows decide the tree and the one-shot
+ *   fact. A row's `mode` is the harness's own durable record of whether that
+ *   child can be resumed after a restart; a branch the walk could not read is
+ *   reported as unread rather than assumed clean.
+ * - The job registry decides which background jobs belong to the registered
+ *   trees. Those run outside the agent loop: this plugin cannot stop them, so
+ *   it names them.
+ *
+ * The aggregate is derived in one place so the host's answer and the browser's
+ * reading of it cannot disagree, and it is a promise about the durable
+ * registry: a session is `safe` only when its recorded phase says so.
+ * @module dsh-pause-session/global
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { ParkWatch } from './park.js';
+import type { ParkRegistry } from './registry.js';
+import type { GlobalStatus, ParkPhase } from './shared.js';
+import type { TreeWalk } from './tree.js';
+import type { PauseAnswer } from './shared.js';
+/** One session's live park state, as the per-session control sees it. */
+export interface LivePark {
+    readonly phase: ParkPhase;
+    /** Whether this process can still walk the session to a flushed park. */
+    readonly moving: boolean;
+}
+/** What one press of the per-session control did. */
+export type PressResult = 'registered' | 'unrecordable' | 'not-live' | 'not-resumable' | 'already-paused';
+/** What the whole-app control needs from the per-session control. */
+export interface GlobalPauseDeps {
+    /**
+     * @param sessionId - session to inspect.
+     * @returns whether a press already owns this session.
+     */
+    isPaused(sessionId: SessionId): boolean;
+    /**
+     * Press one session's pause and make it durable.
+     * @param sessionId - session to register.
+     * @param signal - cancellation for the resumability and registry reads.
+     * @returns what the press did; only `registered` created a new park.
+     */
+    press(sessionId: SessionId, signal?: AbortSignal): Promise<PressResult>;
+    /**
+     * Look at one session's mark now that it is paused.
+     * @param sessionId - the session that was just pressed.
+     */
+    look(sessionId: SessionId): void;
+    /**
+     * @returns every session a live mark owns, with the phase it reports now.
+     */
+    live(): ReadonlyMap<SessionId, LivePark>;
+    /**
+     * @returns every registered session this process could not hold again — a
+     * record whose session cannot be read here, so nothing in this process can
+     * park it, release it, or act on it.
+     */
+    unheld(): ReadonlySet<SessionId>;
+}
+/** The whole-app park, as the plugin entry drives it. */
+export interface GlobalPause {
+    /**
+     * Register and park every running session tree in one action. Sessions this
+     * pause already owns are left where they are; an idle session is not touched.
+     * @param signal - cancellation for the tree reads this action performs.
+     * @returns the aggregate as of this action's end.
+     */
+    pressAll(signal?: AbortSignal): Promise<PauseAnswer>;
+    /**
+     * The aggregate as structured data for the native Remote stream.
+     * @param signal - cancellation for the tree reads this read performs.
+     * @returns the aggregate as of this read.
+     */
+    readState(signal?: AbortSignal, walks?: ReadonlyMap<SessionId, TreeWalk>): Promise<GlobalStatus>;
+    /**
+     * Report one session a press could not register, so the aggregate names it.
+     * The whole-app action records that fact for its own targets; a press of a
+     * session's tree reports the members the registry refused through here.
+     * @param sessionId - the session a press tried and failed to register.
+     * @param unrecorded - whether it is now known to be unparked for that reason.
+     */
+    markUnrecorded(sessionId: SessionId, unrecorded: boolean): void;
+}
+/**
+ * Mount the whole-app park.
+ * @param ctx - host context carrying the agent store and the optional subagent
+ * and job services.
+ * @param watch - the activity fold that says whether a session has unfinished work.
+ * @param registry - the durable list this aggregate is a promise about.
+ * @param deps - the per-session press and the live phase of every mark.
+ * @returns the one-press action and the aggregate read.
+ */
+export declare function mountGlobalPause(ctx: Context, watch: ParkWatch, registry: ParkRegistry, deps: GlobalPauseDeps): GlobalPause;

package/lib/types/history.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The message history a session's log derives to, and the one rule that reads
+ * whether it still owes the model an answer.
+ *
+ * That question is asked twice and must have one answer: the clean wake asks it
+ * before it hands a session an input (an input nobody owes an answer to would
+ * open a turn of its own), and the decision list publishes it as the row's
+ * `wake` field. A published promise that the wake then declines to keep is the
+ * report lying, so both read the same derivation and the same rule.
+ *
+ * The derivation is the harness's own: the surface fold the loop reads its
+ * history through, with the same message projections this process has
+ * registered, and an interrupted tail closed exactly as the harness closes it
+ * on the next read. `resume.ts` reads the live form of it
+ * (`Session.deriveMessages()`); {@link derivedHistory} is the cold form over a
+ * stored log, which is all the decision list may claim — it opens a log to read
+ * it and never activates a session.
+ * @module dsh-pause-session/history
+ */
+import type { Message } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent, SessionMessageProjection } from '@deepseek-ai/dsh-session';
+/**
+ * Whether one derived history ends owing the model an answer: the last thing
+ * said on the model-visible surface is not an assistant message.
+ * @param messages - a derived history, in model-visible order.
+ * @returns whether a model still owes that history a reply.
+ */
+export declare function owesReply(messages: readonly Message[]): boolean;
+/**
+ * The messages one stored log derives to, as the harness would read them on the
+ * session's next activation: the open tail turn is closed with the harness's
+ * own synthetic results first, then the log is folded into its surface.
+ * @param events - the stored events, exactly as they are stored and in sequence order.
+ * @param projections - this process's registered message projections.
+ * @returns the derived history, in model-visible order.
+ * @throws when the log cannot be folded — an event this build has no interpreter
+ * for, or surface metadata that does not apply to this history.
+ */
+export declare function derivedHistory(events: readonly SessionEvent[], projections: readonly SessionMessageProjection[]): Message[];
+/**
+ * Whether one stored log names the route a wake would be addressed to. The wake
+ * needs a provider and a model to build a request at all, and the request
+ * header the session itself persisted is the only place that names them.
+ * @param events - the stored events, in sequence order.
+ * @returns whether the log's last request header carries both route fields.
+ */
+export declare function routeNamed(events: readonly SessionEvent[]): boolean;

package/lib/types/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Host half of dsh-pause-session.
+ *
+ * Mounts the pause gate — the per-session hold at the model-request waterfall —
+ * the activity fold the park predicate reads, the durable park registry, the
+ * session control the browser half drives, and the clean resume path that
+ * answers the input a parked session left pending.
+ *
+ * The registry is read before anything is gated, so a session a previous
+ * process left parked is held again by this one without any user action; a
+ * registry this build cannot read fails the mount loudly rather than silently
+ * resuming every session it named.
+ * @module dsh-pause-session
+ */
+import { z } from 'zod';
+import type { Context } from '@deepseek-ai/cordis';
+export { PauseRemote } from './remote.js';
+/** Plugin name; the Loader row and the bundle patch both use it. */
+export declare const name = "dsh-pause-session";
+/**
+ * Required host services: the model runtime to gate, the stores the control
+ * needs, the projection registry the park predicate reads turn state from, and
+ * the profile's storage, which holds the pause registry.
+ */
+export declare const inject: string[];
+/**
+ * Provider routes whose request conversion drops an empty user message, so the
+ * clean resume path's wake input never reaches the model on them.
+ *
+ * The list is deployment knowledge, not a constant this plugin may assume:
+ * whether an empty user message survives is decided by the adapter (and, for
+ * the pi-ai family, by the provider API that adapter is configured for), and a
+ * plugin cannot introspect an adapter. The default names the routes the shipped
+ * DeepSeek adapter registers; a profile that routes a session elsewhere gets
+ * the visible marker instead of a silent empty turn until it declares that
+ * route here.
+ */
+export declare const DEFAULT_SILENT_WAKE_ROUTES: readonly ["deepseek-official", "deepseek-account"];
+/** Validated plugin configuration. */
+declare const ConfigShape: z.ZodObject<{
+    silentWakeRoutes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    maxListedLogEvents: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** Validated plugin configuration. */
+export type Config = z.infer<typeof ConfigShape>;
+/**
+ * The Loader hands a row's config through this schema, and an empty row config
+ * arrives as `undefined`; folding it to `{}` first is what lets the field
+ * defaults above apply instead of failing the mount.
+ */
+export declare const Config: z.ZodPreprocess<z.ZodObject<{
+    silentWakeRoutes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    maxListedLogEvents: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+/**
+ * Mount the durable pause registry, the pause gate, the activity fold, their
+ * session control, and the clean resume path.
+ *
+ * The registry opens first on purpose: if it cannot be read, nothing else is
+ * registered, so a failed mount leaves no half-installed control behind.
+ * @param ctx - the plugin's host context.
+ * @param config - validated route knowledge for the resume path's wake content.
+ */
+export declare function apply(ctx: Context, config?: Config): Promise<void>;