dsh-pause-session 0.0.0-stage → 0.1.0

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';
+/** 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>;
+export {};

package/lib/types/park.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What a session is doing between "pause was asked for" and "its next model
+ * request is standing still at the gate".
+ *
+ * Two facts decide that, and each has its own owner:
+ *
+ * - Whether a turn is open is derived state the harness already maintains:
+ *   the agent registry owns the `turnBoundary` session projection, which folds
+ *   `turn/start`, `turn/end`, `step/start`, and `step/end` into
+ *   `openTurnStartSeq`. Reading it through `ctx.agents` is a synchronous
+ *   projection read, not a scan of the event log (synchronous history reads are
+ *   prohibited for new code).
+ * - Which tool is in flight is a log-derived per-session fact, so it is a
+ *   session projection too. The projection folds each committed
+ *   `tool/call` → `tool/result` pairing and keeps the calls in order; the
+ *   framework owns replay, caching, and disposal. This module listens only to
+ *   committed events so it can wake the control, never to keep a second copy
+ *   of the state itself.
+ * @module dsh-pause-session/park
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** One session's current activity, as the control reports it. */
+export interface ParkActivity {
+    /** Whether the session is inside a turn — including one waiting for this very park. */
+    readonly turnOpen: boolean;
+    /** Names of the calls currently in flight, in call order; empty when no tool is running. */
+    readonly runningTools: readonly string[];
+}
+/** Both halves of the activity question for one session. */
+export interface ParkWatch {
+    /**
+     * @param sessionId - session to inspect.
+     * @returns the session's current turn and tool activity.
+     */
+    activity(sessionId: SessionId): ParkActivity;
+    /**
+     * Subscribe to activity changes.
+     * @param listener - called with the session whose activity changed; it must
+     * only record that a look is owed, never re-enter the session.
+     * @returns the unsubscribe function.
+     */
+    onChange(listener: (sessionId: SessionId) => void): () => void;
+}
+/**
+ * Mount the per-session activity projection and its notification edge.
+ * @param ctx - host context carrying the session store and the projection registry.
+ * @returns the watch the park state is derived from.
+ */
+export declare function mountParkWatch(ctx: Context): Promise<ParkWatch>;

package/lib/types/registry.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The durable park registry: which sessions are paused, and how cleanly each
+ * one stopped.
+ *
+ * The registry lives in the profile's storage — `ctx.storageDomain`, the
+ * schema-validated domain data form over whichever backend the composition
+ * routes it to — and never in the session log: a pause is not part of a
+ * session's history, and the list has to be readable by a process that has not
+ * opened any session yet. The domain's own backend route is configuration, so
+ * this module names no path and performs no IO of its own.
+ *
+ * The domain keeps the DEFAULT whole-unit layout on purpose. The per-record
+ * layout reads a malformed or stale record document as an absent record, which
+ * here would silently drop one paused session; a whole-unit file turns any
+ * corruption into a failed `open`, and a failed open fails the plugin's mount
+ * loudly instead of resuming everything.
+ * @module dsh-pause-session/registry
+ */
+import { z } from 'zod';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { ParkPhase } from './shared.js';
+/** Domain and backend-unit name; one document per profile under the storage root. */
+export declare const PARK_REGISTRY_DOMAIN = "pause_registry";
+/** One session's stored park outcome. */
+export declare const parkRecord: z.ZodObject<{
+    phase: z.ZodEnum<{
+        draining: "draining";
+        parking: "parking";
+        safe: "safe";
+        "flush-failed": "flush-failed";
+    }>;
+    updatedAt: z.ZodNumber;
+    rearmGoal: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/** One session's stored park outcome. */
+export type ParkRecord = z.infer<typeof parkRecord>;
+/**
+ * The registry declaration. `version: 1` and no `compatibleVersions`: the
+ * domain layer rejects a stored unit stamped with any other version rather than
+ * migrating it, so an unrecognized registry fails loud at open. Validation is
+ * the rejecting default for the same reason — a record this build cannot read
+ * must stop the mount, not disappear from the list.
+ */
+export declare const parkRegistryDomain: {
+    name: string;
+    version: number;
+    tables: {
+        sessions: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<SessionId, {
+            phase: "draining" | "parking" | "safe" | "flush-failed";
+            updatedAt: number;
+            rearmGoal: boolean;
+        }>;
+    };
+};
+/** One session the registry remembers. */
+export interface ParkedSession {
+    readonly sessionId: SessionId;
+    readonly phase: ParkPhase;
+    /** When the phase was written. */
+    readonly updatedAt: number;
+    /** Whether resuming this session may re-arm its goal; see {@link parkRecord}. */
+    readonly rearmGoal: boolean;
+}
+/** The durable pause list, opened over the profile's storage. */
+export interface ParkRegistry {
+    /**
+     * @returns every remembered session, in insertion order.
+     */
+    list(): readonly ParkedSession[];
+    /**
+     * The same list as {@link list}, as a lazily kept read-only view.
+     *
+     * The whole-app aggregate and the decision list read this once per status
+     * read, and a status read can happen on every command-registry change; the
+     * view is rebuilt only when the stored entries actually changed, so a read
+     * that changes nothing does not build a second copy of the list to look at.
+     * A caller must not mutate it.
+     */
+    readonly parked: ReadonlyMap<SessionId, ParkedSession>;
+    /**
+     * @param sessionId - session to look up.
+     * @returns the remembered session, or `undefined` when nothing is parked under that id.
+     */
+    get(sessionId: SessionId): ParkedSession | undefined;
+    /**
+     * Write one session's outcome; resolves once it is durable. The goal opt-out
+     * already recorded for that session survives a phase change — the phases of
+     * one park episode all describe the same parked session.
+     * @param sessionId - the session being parked.
+     * @param phase - how far the park has got.
+     */
+    record(sessionId: SessionId, phase: ParkPhase): Promise<void>;
+    /**
+     * Set one session's goal opt-out; resolves once it is durable.
+     * @param sessionId - the parked session to change.
+     * @param rearmGoal - whether the clean resume path may re-arm its goal.
+     * @throws when no record exists for that session — the flag describes a
+     * parked session, and inventing a record would invent a park.
+     */
+    setRearmGoal(sessionId: SessionId, rearmGoal: boolean): Promise<void>;
+    /**
+     * Drop one session from the list, so a later process does not re-hold it.
+     * @param sessionId - the session being released.
+     */
+    forget(sessionId: SessionId): Promise<void>;
+}
+/**
+ * Open the registry over the mounted storage. The caller owns the handle's
+ * lifetime; this registers the close as an effect on `ctx`, so the unit is
+ * released with the plugin.
+ * @param ctx - plugin context carrying `storageDomain`.
+ * @returns the open registry.
+ * @throws whatever `open` rejects with — a `StorageError` for an unreadable
+ * unit, a `DomainError('invalid-record')` for a record this build cannot read.
+ */
+export declare function openParkRegistry(ctx: Context): Promise<ParkRegistry>;

package/lib/types/resume.d.ts

@@ -0,0 +1,221 @@
+/**
+ * The clean resume path: bring back a session a previous process parked, and
+ * let it answer the input that was already pending when it stopped.
+ *
+ * A resume invents no turn. At the park point the loop had claimed the
+ * session's pending input onto the surface and built the request the gate then
+ * held; after a restart that input is still the last thing the session says and
+ * the model still owes it an answer. What is missing is only a reason for the
+ * loop to build a request again, and the documented way to ask for one is a
+ * wake input — a user message the loop claims.
+ *
+ * The wake is invisible only on the routes the composition declares in
+ * `silentWakeRoutes`, whose conversion drops an empty user message. On every
+ * other route the loop's request carries one visible marker instead, and the
+ * marker reaches the model; that is an accepted cost of resuming at all.
+ * Whether an empty user message survives is a property of the route's
+ * conversion rather than of the loop, so the route is resolved per session —
+ * from the request header the session itself persisted.
+ *
+ * The wake message is attributed to this plugin, never to the user: it is text
+ * this module synthesized on the session's behalf, in the session's own log and
+ * in front of the model, and a downstream consumer has to be able to tell it
+ * apart from something the human typed.
+ *
+ * Only a cleanly parked session takes this path. A record that never reached
+ * the park point, or whose flush did not finish, describes work whose durable
+ * state nobody knows; waking it would spend its owner's money on a guess, and
+ * deciding those sessions is the morning list's job, not this path's. That
+ * holds whether or not the recorded session happens to be live in this process:
+ * liveness is not the park outcome, and a session can be live without ever
+ * having stopped.
+ * @module dsh-pause-session/resume
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { CommandResult } from '@deepseek-ai/dsh-commands';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { PauseGate } from './gate.js';
+import type { ParkRegistry } from './registry.js';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /**
+         * Text dsh-pause-session synthesized on the session's behalf: the wake this
+         * path delivers and the unknown-outcome note a decision adds. Declared so
+         * the log, and anything reading it, can tell plugin-authored input from the
+         * user's own.
+         */
+        'pause': {
+            kind: 'pause';
+        };
+    }
+}
+/**
+ * The one wake content a route that keeps an empty user message is given. It
+ * names its producer, because it lands in the same user turn as the input the
+ * model owes an answer to and must not read as part of it.
+ */
+export declare const WAKE_MARKER = "[pause: resumed from a pause]";
+/**
+ * How one resume asks the loop for the request it owes the session:
+ *
+ * - `silent`: the clean path's wake — an empty input on a route the
+ *   composition declared silent, and the visible marker on any other route.
+ * - `message`: the decision list's "continue, and say the tool outcome is
+ *   unknown" — user-visible text on the wire by construction, and the only
+ *   resume that is not invisible.
+ * - `none`: no wake at all. This is what "leave it for me to read" costs: the
+ *   session is not activated, nothing is asked of the model, and the park is
+ *   exactly as it was.
+ */
+export type WakeRequest = {
+    readonly kind: 'silent';
+} | {
+    readonly kind: 'message';
+    readonly text: string;
+} | {
+    readonly kind: 'none';
+};
+/** Result copy for a resumed session; the model never sees it. */
+export declare const RESUMED_TEXT = "This session resumed from where it paused.";
+/**
+ * Result copy for a registered session this path refuses: its durable state is
+ * not the outcome of a completed park, so waking it would be a guess.
+ */
+export declare const UNCLEAN_TEXT: string;
+/** Result copy when nothing is parked under that session. */
+export declare const NOT_PARKED_TEXT = "pause has no pause recorded for this session.";
+/** Result copy for a session that is parked but could not be loaded back. */
+export declare const ACTIVATION_FAILED_TEXT = "pause could not reopen this session, so it stayed paused.";
+/** Result copy for a one-shot subagent route: its Session exists, but no resume may reactivate it. */
+export declare const UNRESUMABLE_TEXT = "pause did not resume this session: it is a one-shot subagent route and cannot be resumed.";
+/**
+ * Result copy for the review decision. It is the one answer that promises
+ * nothing happened, because opening a session to read it is the user's own
+ * action in their session list — and activating its agent here would start a
+ * session they asked only to look at.
+ */
+export declare const REVIEW_TEXT: string;
+/** Result copy for a change the durable registry refused to record. */
+export declare const UNRECORDED_TEXT = "pause could not write the pause registry, so it did not change the pause state.";
+/** Copy for one goal opt-out change. */
+export declare const REARM_GOAL_ON_TEXT = "pause will re-open this session's goal when it resumes it.";
+export declare const REARM_GOAL_OFF_TEXT = "pause will leave this session's goal closed when it resumes it.";
+/** Why one record did not produce a running session. */
+export type ResumeRefusal = 'not-parked' | 'not-clean' | 'activation-failed' | 'unrecorded' | 'not-activated' | 'unresumable';
+/** What one resume attempt did. */
+export interface ResumeOutcome {
+    readonly sessionId: SessionId;
+    /** Whether the session is now running from the point it stopped. */
+    readonly resumed: boolean;
+    /** Present exactly when `resumed` is false. */
+    readonly refusal?: ResumeRefusal;
+}
+/** One resume attempt plus the answer the command that asked for it receives. */
+export interface ResumeAttempt extends ResumeOutcome {
+    readonly answer: CommandResult;
+}
+/** How this path is wired into the session control that owns the pause state. */
+export interface ResumeDeps {
+    /**
+     * Take a live session's pause back: the durable record goes first, then the
+     * gate. Owned by the session control so there is one release order.
+     */
+    release(sessionId: SessionId, text: string): Promise<CommandResult>;
+    /**
+     * Whether the pause this process holds was adopted from the registry rather
+     * than pressed here. Only an adopted pause is a restart: a press this process
+     * made and took back must never wake a model.
+     */
+    adopted(sessionId: SessionId): boolean;
+}
+/** Route knowledge this path needs from the composition. */
+export interface ResumeOptions {
+    /**
+     * Provider routes whose request conversion drops an empty user message, so an
+     * empty wake never reaches the model. Deployment-owned because it is a
+     * property of the adapter behind each route, and a third-party plugin cannot
+     * introspect an adapter.
+     */
+    readonly silentWakeRoutes: readonly string[];
+}
+/** The clean resume path, as the session control drives it. */
+export interface ResumePath {
+    /**
+     * Resume one session the registry remembers.
+     * @param sessionId - the session to resume.
+     * @param request - which wake this resume delivers; see {@link WakeRequest}.
+     * @param parentId - the direct parent a batch release already brought back, when there is one.
+     * @param signal - cancellation for the cold load and setup.
+     * @returns what happened, and the copy for whoever asked.
+     */
+    resumeSession(sessionId: SessionId, request: WakeRequest, parentId?: SessionId, signal?: AbortSignal): Promise<ResumeAttempt>;
+    /**
+     * Resume one session the decision list officially owns — a record that is
+     * known NOT to be clean, which the clean path above must refuse and this entry
+     * exists to carry out. Same release order, same wake vocabulary.
+     * @param sessionId - the listed session to bring back.
+     * @param request - which wake the decision delivers; see {@link WakeRequest}.
+     * @param finalize - whether the decision continues the session (`'release'`)
+     * or only answers it (`'review'`). A review activates nothing and writes
+     * nothing: opening a session to read it is the user's own action, not this
+     * plugin's.
+     * @param parentId - the direct parent a batch release already brought back, when there is one.
+     * @param signal - cancellation for the cold load and setup.
+     * @returns what happened, and the copy for whoever asked.
+     */
+    decideUnclean(sessionId: SessionId, request: WakeRequest, finalize: 'release' | 'review', parentId?: SessionId, signal?: AbortSignal): Promise<ResumeAttempt>;
+    /**
+     * Resume every session the registry remembers, clean ones only. One session's
+     * failure never stops the others.
+     * @param signal - cancellation checked between release levels and forwarded to each load.
+     * @returns one attempt per recorded session, in registry order.
+     */
+    resumeParked(signal?: AbortSignal): Promise<readonly ResumeAttempt[]>;
+    /**
+     * Record or clear one session's goal opt-out.
+     * @param sessionId - the parked session to change.
+     * @param rearmGoal - whether the clean resume path may re-arm its goal.
+     * @returns the copy for whoever asked.
+     */
+    setRearmGoal(sessionId: SessionId, rearmGoal: boolean): Promise<CommandResult>;
+    /**
+     * Release one parked session and the registered members of its tree: the
+     * counterpart of a press that registered a whole tree.
+     * @param sessionId - the session whose tree the user released.
+     * @param signal - cancellation for the tree read and each member's load.
+     * @returns what happened to the tree, and the copy for whoever asked.
+     */
+    releaseTree(sessionId: SessionId, signal?: AbortSignal): Promise<ReleaseTreeOutcome>;
+}
+/** What releasing one session's registered tree did. */
+export interface ReleaseTreeOutcome {
+    /** How many sessions this release covered: the session plus its registered descendants. */
+    readonly members: number;
+    /** How many of them are running again. */
+    readonly resumed: number;
+    /** How many could not be resumed, and why the release did not take them back. */
+    readonly refusals: readonly {
+        readonly sessionId: SessionId;
+        readonly refusal: ResumeRefusal;
+    }[];
+    /** The copy for whoever pressed the release. */
+    readonly answer: CommandResult;
+}
+/**
+ * How one tree-wide release answers the person who pressed it. One release, one
+ * sentence about all of it: what came back, and — by name, because those rows
+ * are what the morning list is for — what did not.
+ * @param released - the sessions this release covered, in release order.
+ * @returns the result text, e.g. `pause resumed 2 sessions from where they stopped; "child" did not pause completely`.
+ */
+export declare function summarizeTreeRelease(released: readonly ResumeAttempt[]): string;
+/**
+ * Build the clean resume path.
+ * @param ctx - host context carrying the agent store, the session store, and the goal service when one is mounted.
+ * @param gate - the pause gate the resume releases.
+ * @param registry - the durable list this path reads and forgets from.
+ * @param options - the route knowledge the wake content depends on.
+ * @param deps - the control-owned release order and the adopted-pause fact.
+ * @returns the path the session control exposes.
+ */
+export declare function installResumePath(ctx: Context, gate: PauseGate, registry: ParkRegistry, options: ResumeOptions, deps: ResumeDeps): ResumePath;