dsh-pause-session 0.0.0-stage → 0.2.0

package/lib/types/client/control.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Browser-side reading and driving of the host's park state for one session.
+ *
+ * The browser reads the native `pauseSession` stream; actions travel through
+ * the same Remote namespace. No slash command is involved. The stream is
+ * host-authoritative, so this module never derives a state from its own press.
+ * The snapshot also carries the record's goal opt-out, so the switch beside the
+ * pause button can show it without a second host round-trip.
+ *
+ * The stream is the change feed. A pushed snapshot triggers one cached read per
+ * shown header; a press or goal switch reads the host's answer once after the
+ * action.
+ * @module dsh-pause-session/client/control
+ */
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { PauseTransport } from './remote.js';
+/**
+ * What the Session-header control knows about one session: what the host
+ * reported, or that no answer has arrived (`undefined`) or the last read
+ * failed. Neither of the latter claims a state the host never reported.
+ *
+ * `draining` and `parking` are the host's own two answers on the way to
+ * `safe`; the control shows them rather than rounding them up, because only
+ * `safe` means the pending input is durably stored.
+ */
+export type PausePhase = 'active' | 'draining' | 'parking' | 'safe' | 'flush-failed' | 'unavailable';
+/** One host answer about one session. */
+export interface PauseReading {
+    readonly phase: PausePhase;
+    /** Tools the host reported in flight; empty unless the phase is `draining`. */
+    readonly runningTools: readonly string[];
+    /**
+     * Whether the host's own record lets the next resume re-open this session's
+     * goal. Absent — not `true` — when the host did not say: the control shows no
+     * switch rather than the product default, because a default here would tell
+     * the user their rounds are safe when nobody has answered.
+     */
+    readonly rearmGoal?: boolean;
+}
+/** Per-session control state, keyed by Session id so a slot selector can watch one session. */
+export interface PauseState {
+    /** Reading per Session id; absent means no host answer yet. Writable: the store updates through a draft. */
+    bySession: Record<string, PauseReading | undefined>;
+}
+/** Owns the published reading per session; nothing else writes that state. */
+export declare class PauseControl {
+    private readonly transport;
+    private readonly lifetime;
+    /** State source the Session-header contribution binds its selector hook to. */
+    readonly store: SnapshotStore<PauseState>;
+    /** Sessions this control has shown; a pushed snapshot applies to every one. */
+    private readonly shown;
+    /** Highest read sequence requested per session: an answer older than it is dropped. */
+    private readonly latest;
+    private reads;
+    /**
+     * @param transport - the native namespace source and actions.
+     * @param lifetime - aborts in-flight reads when the plugin unloads.
+     */
+    constructor(transport: PauseTransport, lifetime: AbortSignal);
+    /**
+     * Read the host's state for one session.
+     * @param sessionId - session whose control was rendered.
+     * @returns after this read's answer is published or superseded by a newer one.
+     */
+    refresh(sessionId: SessionId): Promise<void>;
+    /** Apply one pushed snapshot without spending a read per shown header. */
+    apply(snapshot: {
+        readonly sessions: Readonly<Record<string, {
+            readonly phase: PausePhase;
+            readonly runningTools: readonly string[];
+            readonly rearmGoal?: boolean;
+        }>>;
+    } | undefined): void;
+    /** A new pushed snapshot may have moved every header; read them once. */
+    refreshAll(): void;
+    private readAll;
+    /** One session's read, published unless a newer read of that session supersedes it. */
+    private readOne;
+    /**
+     * Press the control: pause an active session, or take back a pause that is
+     * still on its way in (or already settled). The phase shown afterwards is the
+     * host's answer, never an assumed flip.
+     * @param sessionId - session whose control was pressed.
+     * @returns after the control re-reads the host.
+     */
+    toggle(sessionId: SessionId): Promise<void>;
+    /**
+     * Flip this session's goal opt-out. The verb belongs to the session it
+     * changes; the switch shows the host's next answer, never a local flip.
+     * @param sessionId - session whose switch was pressed.
+     * @returns after the control re-reads the host.
+     */
+    toggleGoal(sessionId: SessionId): Promise<void>;
+    /** Ask the native stream what this session's park state is. */
+    private read;
+    private publish;
+}

package/lib/types/client/global.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Browser-side reading and driving of the host's whole-app park state.
+ *
+ * The aggregate arrives from the native `pauseSession` stream. The stream is
+ * process-wide and writes nothing into any Session; actions travel through the
+ * same Remote namespace. A pushed snapshot is applied directly; a settled park
+ * costs nothing while its last answer stays on screen.
+ * @module dsh-pause-session/client/global
+ */
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { GlobalStatus, TriageAction, TriageRow } from '../shared.js';
+import type { PauseTransport } from './remote.js';
+/** What the whole-app control knows: the host's answer, or that it could not ask. */
+export type GlobalReading = {
+    readonly kind: 'reported';
+    readonly status: GlobalStatus;
+} | {
+    readonly kind: 'unavailable';
+};
+/** What the decision-list panel knows: the host's rows, or that it could not ask. */
+export type TriageReading = {
+    readonly kind: 'reported';
+    readonly rows: readonly TriageRow[];
+} | {
+    readonly kind: 'unavailable';
+};
+/** Whole-app control state. */
+export interface GlobalPauseState {
+    /** The host's answer; absent until one arrives. Writable: the store updates through a draft. */
+    global: GlobalReading | undefined;
+    /** Whether the user asked for the decision list; the panel reads only when it is open. */
+    panelOpen: boolean;
+    /** The host's decision list; absent until the panel asks for it. */
+    triage: TriageReading | undefined;
+    /** The last action or read refusal, shown verbatim in the panel. */
+    error?: string;
+    /** The last snapshot's per-session details, for the draining progress copy. */
+    sessions?: Readonly<Record<string, {
+        readonly runningTools: readonly string[];
+    }>>;
+}
+/**
+ * The session a whole-app action is addressed to.
+ *
+ * A subagent's own session is never addressed: its agent belongs to a parent
+ * and is not the host's business to drive from the shell. Among the rest, the
+ * one on screen is the best address (its agent is live by construction), then
+ * any session the host reports as running, then any at all.
+ * @param state - the session list snapshot the shell provides.
+ * @returns the address, or `undefined` when the app has no session to ask through.
+ */
+export declare function addressingSession(state: {
+    readonly ids: readonly SessionId[];
+    readonly byId: Readonly<Record<string, {
+        readonly running?: boolean;
+        readonly origin?: string;
+        readonly parentId?: unknown;
+        readonly retainedBy?: {
+            readonly mainView?: number;
+        };
+    } | undefined>>;
+}): SessionId | undefined;
+/** Owns the published whole-app reading; nothing else writes that state. */
+export declare class PauseGlobalControl {
+    private readonly transport;
+    private readonly lifetime;
+    /** State source the whole-app contribution binds its selector hook to. */
+    readonly store: SnapshotStore<GlobalPauseState>;
+    /** The session the shell asked this control through; list reads use it. */
+    private address;
+    /** Highest decision-list read requested: an answer older than it is dropped. */
+    private latestTriage;
+    /**
+     * @param transport - the native namespace source and actions.
+     * @param lifetime - aborts in-flight reads when the plugin unloads.
+     */
+    constructor(transport: PauseTransport, lifetime: AbortSignal);
+    /**
+     * The shell handed this control a session. The first call reads the aggregate;
+     * later calls only move where list reads and actions are addressed.
+     * @param sessionId - the session the shell asks through.
+     */
+    refresh(sessionId: SessionId): Promise<void>;
+    /** Apply one pushed snapshot directly. */
+    apply(snapshot: {
+        readonly global: GlobalStatus;
+        readonly sessions: Readonly<Record<string, {
+            readonly runningTools: readonly string[];
+        }>>;
+    } | undefined): void;
+    /** A pushed snapshot may have moved the aggregate and the open list. */
+    refreshAll(): void;
+    /**
+     * Open or close the decision list. Opening asks for the rows; there is no
+     * state to show without that answer.
+     * @param open - whether the panel should be showing.
+     */
+    setPanel(open: boolean): void;
+    /** Ask the host for the decision list for the session the user is on. */
+    refreshTriage(): Promise<void>;
+    /**
+     * Take one listed verb on one listed session, addressed through the session
+     * the user is on. A refusal is published verbatim rather than silently
+     * leaving the previous rows in place.
+     * @param sessionId - the listed session to act on.
+     * @param action - which listed verb was taken.
+     */
+    decide(sessionId: string, action: TriageAction): Promise<void>;
+    /**
+     * Press the pill: park everything, or release everything the park owns.
+     * Which one it is comes from the host's own last answer, never from a local
+     * flip; the state shown afterwards is the host's answer again.
+     * @param sessionId - the session to address the verb to.
+     */
+    toggle(sessionId: SessionId): Promise<void>;
+    /** Read the aggregate once and publish it. */
+    private readAggregate;
+    private reread;
+    /** One decision-list read, addressed at the session the user is on. */
+    private readTriage;
+    /** Ask the native namespace for the decision list. */
+    private readTriageRows;
+    private publish;
+}

package/lib/types/client/icons.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The glyphs both pause controls are drawn with, so the session-header
+ * control and the whole-app pill cannot drift apart.
+ * @module dsh-pause-session/client/icons
+ */
+import type { ReactNode } from 'react';
+/** 16px stroke icon (currentColor): the two bars of a pause. */
+export declare function PauseIcon(): ReactNode;
+/** 16px stroke icon (currentColor): the triangle of a resume. */
+export declare function ResumeIcon(): ReactNode;
+/**
+ * 16px stroke icon (currentColor): the rings of a target, for the goal switch
+ * on the session header. Drawn at 16px like the pause and resume glyphs it sits
+ * beside rather than the 14px marks the two reports use.
+ */
+export declare function GoalIcon(): ReactNode;
+/**
+ * 14px stroke icon (currentColor): the mark that a report carries a caveat.
+ * A glyph rather than copy, so the facts it stands for stay in the locale
+ * dictionaries beside everything else the user reads.
+ */
+export declare function CaveatIcon(): ReactNode;
+/** 14px stroke icon (currentColor): the chevron that opens the decision list. */
+export declare function ChevronIcon(): ReactNode;

package/lib/types/client/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Browser half of dsh-pause-session.
+ *
+ * Registers two controls: one in the session header's title-adjacent action
+ * group (`conversation.session.header.actions`), which pauses or resumes the
+ * session it sits on, and one in the header's right-aligned utilities row
+ * (`conversation.session.header.utilities`), which answers for the whole app.
+ * Both seats are session-scoped and their props carry `sessionId`, so every
+ * open session header renders its own pair and switching sessions follows
+ * automatically; the whole-app control speaks for every session from the
+ * header of the one on screen.
+ *
+ * The whole-app control sits inside the conversation column rather than in the
+ * frame-wide overlay layer: it is read while looking at one conversation, and
+ * a sidebar or drawer that covers that area covers the control with it.
+ *
+ * Both controls are host-authoritative. On a browser Host they read the
+ * native `pauseSession` stream, which keeps status reads out of the Session
+ * log. The same path serves Web and Desktop.
+ * User actions and status both use the generated native Remote namespace;
+ * no slash command is involved. Each control stays inert wherever no
+ * round-trip is available rather than rendering a state it cannot support. The
+ * header control also reads the whole-app answer the whole-app control
+ * publishes, so a park that holds nothing does not cost a host round-trip per
+ * header.
+ * @module dsh-pause-session/client
+ */
+import type { ReactNode } from 'react';
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PauseState } from './control.js';
+import { type PauseKey } from './locales.js';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The pause control's copy. */
+        'pause': PauseKey;
+    }
+}
+/** Required services: the slot registry, the locale registry, and the host round-trip. */
+export declare const inject: string[];
+/** Browser state and operations injected into the Session-header contribution. */
+export interface PauseInjected {
+    hooks: {
+        pause: ObservableSnapshot<PauseState>;
+    };
+    /** Read the host's state for one session (the control calls this once per mount). */
+    refresh: (sessionId: SessionId) => void;
+    /** Press the control for one session. */
+    toggle: (sessionId: SessionId) => void;
+    /** Flip one session's own goal opt-out. */
+    toggleGoal: (sessionId: SessionId) => void;
+}
+/** Full props of the Session-header pause control. */
+export type PauseButtonProps = PropsRuntime<'conversation.session.header.actions'> & InjectFace<PauseInjected> & PropsLocale<'pause'>;
+/**
+ * The session's pause control: pause the session and its subagents before
+ * their next model request, or resume them, with the host's own state on screen.
+ * Once the host reports the park's goal opt-out, a second switch sits beside it
+ * — the only place a session that stopped CLEANLY can be told not to re-open its
+ * goal on the next resume, because the decision list shows only the sessions
+ * that did not stop cleanly.
+ *
+ * A subagent session renders nothing: its work is its parent's, the parent's
+ * control already covers it, and a button here would offer to pause "a session"
+ * from inside a child.
+ * @param props - session runtime, host operations, and localized copy.
+ * @returns the header action, or nothing on a subagent session.
+ */
+export declare function PauseButton(props: PauseButtonProps): ReactNode;
+/**
+ * Client plugin body: register the locale dictionaries, own both controllers,
+ * follow the host's registry changes, and contribute the per-session control
+ * and the whole-app control into the session header.
+ * @param ctx - client context carrying slots, locale, and the Remote face.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,67 @@
+/** `pause` namespace dictionaries. */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'pause.aria': string;
+    'resume.tip': string;
+    'draining.aria': string;
+    'parking.aria': string;
+    'safe.aria': string;
+    'flushFailed.aria': string;
+    'state.draining': string;
+    'state.parking': string;
+    'state.safe': string;
+    'state.flushFailed': string;
+    'goal.aria': string;
+    'goal.on.tip': string;
+    'goal.off.tip': string;
+    'checking.aria': string;
+    'checking.tip': string;
+    'unavailable.aria': string;
+    'unavailable.tip': string;
+    'all.pause.aria': string;
+    'all.resume.aria': string;
+    'all.idle': string;
+    'all.finishing': string;
+    'all.cancel': string;
+    'all.cancel.aria': string;
+    'all.unclean': string;
+    'all.unclean.aria': string;
+    'all.safe': string;
+    'all.checking.aria': string;
+    'all.caveat.jobs': string;
+    'all.caveat.unresumable': string;
+    'all.caveat.stalled': string;
+    'all.caveat.unread': string;
+    'all.caveat.blindTrees': string;
+    'all.caveat.blindJobs': string;
+    'triage.open.aria': string;
+    'triage.title': string;
+    'triage.empty': string;
+    'triage.reading': string;
+    'triage.unavailable': string;
+    'triage.refresh.aria': string;
+    'triage.session.aria': string;
+    'triage.stopped': string;
+    'triage.stoppedUnknown': string;
+    'triage.tools': string;
+    'triage.toolsNone': string;
+    'triage.noWake': string;
+    'triage.phase.draining': string;
+    'triage.phase.parking': string;
+    'triage.phase.flushFailed': string;
+    'triage.continue': string;
+    'triage.continue.aria': string;
+    'triage.note': string;
+    'triage.note.aria': string;
+    'triage.review': string;
+    'triage.review.aria': string;
+    'triage.leave': string;
+    'triage.leave.aria': string;
+    'triage.goal': string;
+    'triage.goal.aria': string;
+    'all.triage': string;
+};
+/** The pause namespace key union. */
+export type PauseKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: Record<PauseKey, string>;

package/lib/types/client/pill.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The whole-app control: one pill in the conversation header's utilities row
+ * that answers "can I close the lid?", presses the park or the release, and —
+ * when something did not stop cleanly — opens the morning decision list.
+ *
+ * The header's right-aligned utilities row is inside the conversation column,
+ * which is where this control belongs: it answers for every session tree, but
+ * it is read while looking at one, and a surface inside the layout is covered
+ * by whatever covers that column — a sidebar or a drawer — instead of floating
+ * above the whole frame. The decision list hangs from the control into the
+ * conversation area below.
+ *
+ * The pill reads the native status stream through `./global.ts`. With no
+ * answer, or with no session to address an action through, it renders nothing
+ * rather than a state it would have to invent. The decision list is
+ * deliberately NOT part of that first read; the panel asks for its own rows
+ * when it opens.
+ * @module dsh-pause-session/client/pill
+ */
+import type { ReactNode } from 'react';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { TriageAction } from '../shared.js';
+import type { GlobalPauseState } from './global.js';
+/** Browser state and operations injected into the whole-app pill. */
+export interface PausePillInjected {
+    hooks: {
+        pauseGlobal: ObservableSnapshot<GlobalPauseState>;
+    };
+    /** Hand the control the session the shell is on; it reads there until it has an answer. */
+    refresh: (sessionId: SessionId) => void;
+    /** Press the pill for one session. */
+    toggle: (sessionId: SessionId) => void;
+    /** Show or hide the decision list; opening it also reads its rows. */
+    setPanel: (open: boolean) => void;
+    /** Take one of the four decisions on one listed session. */
+    decide: (sessionId: string, action: TriageAction) => void;
+}
+/** Full props of the whole-app pause control. */
+export type PausePillProps = PropsRuntime<'conversation.session.header.utilities'> & InjectFace<PausePillInjected> & PropsLocale<'pause'>;
+/**
+ * The whole-app control: what the host says about the whole park, the one
+ * press that parks or releases all of it, and the decision list for whatever
+ * did not stop cleanly.
+ * @param props - session-header runtime, host operations, and localized copy.
+ * @returns the control and its panel, or nothing while the host has not answered.
+ */
+export declare function PausePill(props: PausePillProps): ReactNode;

package/lib/types/client/remote.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Client-side bridge from the generated `pauseSession` Remote namespace to the
+ * control state machines.
+ *
+ * The native namespace is the only transport: the stream supplies snapshots and
+ * the action methods drive every button. No slash command is involved.
+ * @module dsh-pause-session/client/remote
+ */
+import type { PauseActionResultWire, PauseDecisionRequest, PauseSnapshotWire, TriageRowWire } from '../remote.js';
+import type { GlobalStatus, ParkStatus } from '../shared.js';
+/** The generated namespace shape this bridge needs. */
+export interface RemotePauseNamespace {
+    observe(signal?: AbortSignal): AsyncIterable<PauseSnapshotWire>;
+    act(request: {
+        readonly action: 'pause' | 'resume' | 'pause-all' | 'resume-all' | 'cancel-all' | 'goal';
+        readonly sessionId: string;
+    }, signal?: AbortSignal): Promise<{
+        readonly ok: boolean;
+        readonly value?: PauseActionResultWire;
+        readonly error?: {
+            readonly code: string;
+        };
+    }>;
+    triage(request: {
+        readonly caller: string;
+    }, signal?: AbortSignal): Promise<{
+        readonly ok: boolean;
+        readonly value?: readonly TriageRowWire[];
+    }>;
+    decide(request: PauseDecisionRequest, signal?: AbortSignal): Promise<{
+        readonly ok: boolean;
+        readonly value?: PauseActionResultWire;
+    }>;
+}
+/** The status shape shared by the controls, with branded ids erased at this boundary. */
+export interface PauseSnapshotLike {
+    readonly global: GlobalStatus;
+    readonly sessions: Readonly<Record<string, ParkStatus>>;
+}
+/** A remote-backed status source with a change subscription. */
+export interface RemoteStatusSource {
+    /** Read the latest host snapshot; undefined before the first answer or after failure. */
+    read(signal?: AbortSignal): Promise<PauseSnapshotLike | undefined>;
+    onChange(listener: () => void): () => void;
+    /** Receive each pushed snapshot directly; `undefined` means the stream failed. */
+    onSnapshot(listener: (snapshot: PauseSnapshotLike | undefined) => void): () => void;
+}
+/**
+ * Open the native status stream and expose its latest snapshot to both controls.
+ * @param remote - the generated Remote namespace.
+ * @param lifetime - client lifetime; aborting it releases the stream.
+ * @returns the cached source and its change subscription.
+ */
+export declare function openRemoteSource(remote: RemotePauseNamespace, lifetime: AbortSignal): RemoteStatusSource;
+/** Direct browser transport over the generated namespace. */
+export interface PauseTransport {
+    readonly source: RemoteStatusSource;
+    act(request: {
+        readonly action: 'pause' | 'resume' | 'pause-all' | 'resume-all' | 'cancel-all' | 'goal';
+        readonly sessionId: string;
+    }, signal?: AbortSignal): Promise<PauseActionResultWire>;
+    triage(caller: string, signal?: AbortSignal): Promise<readonly TriageRowWire[] | undefined>;
+    decide(caller: string, target: string, decision: 'continue' | 'note' | 'review' | 'leave' | 'goal', signal?: AbortSignal): Promise<PauseActionResultWire>;
+}
+/**
+ * Build the direct transport over one mounted Remote namespace.
+ * @param remote - the generated `pauseSession` namespace.
+ * @param lifetime - client lifetime.
+ * @returns the source and action methods the controls use.
+ */
+export declare function remoteTransport(remote: RemotePauseNamespace, lifetime: AbortSignal): PauseTransport;

package/lib/types/client/view.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The controls' phase → view mapping.
+ *
+ * Kept pure functions of the published reading so the rendering decision — what
+ * the button says, whether it accepts a press, and which state label is visible
+ * — is asserted without a browser renderer. Labels are KEYS, not copy: the
+ * visible sentence is localized, and the host's own names join it as data.
+ * @module dsh-pause-session/client/view
+ */
+import type { GlobalReading, TriageReading } from './global.js';
+import type { PauseReading } from './control.js';
+import type { PauseKey } from './locales.js';
+import type { TriageAction } from '../shared.js';
+/** What one reading renders as. */
+export interface PauseView {
+    /** Whether the host reported this session paused. */
+    readonly paused: boolean;
+    /** Whether the control accepts a press; an unknown or failed reading does not. */
+    readonly enabled: boolean;
+    /** Accessible name of the button. */
+    readonly ariaKey: PauseKey;
+    /** Label shown beside the button while the control has something to say. */
+    readonly labelKey?: PauseKey;
+    /** Tools in flight, taken verbatim from the host; rendered only with `labelKey`. */
+    readonly runningTools: readonly string[];
+    /**
+     * The host-reported goal opt-out, or `undefined` when the host did not answer
+     * it. Absent means the goal switch is not rendered at all: a switch has to
+     * state a fact, and the only fact available is the one the record holds.
+     */
+    readonly rearmGoal?: boolean;
+}
+/**
+ * Whether the pause control renders on one session at all.
+ *
+ * The control is the user's button for a session's work, and that work includes
+ * the subagents under it — which is why the press covers the tree and why the
+ * button does not belong inside the tree. The client can tell: a Session
+ * snapshot carries a `subagent` field, the same signal the read-only composer
+ * reads. A subagent's service is not the user's to pause: its parent's control
+ * already speaks for it, and a second button here would offer to stop "a
+ * session" from inside a child.
+ * @param subagent - the session snapshot's own subagent fact, absent when unknown.
+ * @returns whether this session's header renders the control.
+ */
+export declare function showsPauseControl(subagent: {
+    readonly address: unknown;
+} | null | undefined): boolean;
+/**
+ * Map one reading to its view.
+ * @param reading - the host-reported reading, or `undefined` before the first answer.
+ * @returns the view for that reading.
+ */
+export declare function pauseView(reading: PauseReading | undefined, running?: boolean): PauseView;
+/** One named fact from the whole-app report, with the copy key that introduces it. */
+export interface GlobalCaveat {
+    /** What this list of names is. */
+    readonly key: PauseKey;
+    /** Host names, rendered verbatim. */
+    readonly names: readonly string[];
+}
+/** Which verb a whole-app press runs. */
+export type GlobalAction = 'pause-all' | 'resume-all' | 'cancel-all' | 'none';
+/** One decision as the list renders it. */
+export interface TriageActionView {
+    /** The decision this button takes. */
+    readonly action: TriageAction;
+    /** Visible label. */
+    readonly labelKey: PauseKey;
+    /** What it does, for the accessible name. */
+    readonly ariaKey: PauseKey;
+}
+/** The four decisions, in the order a user reads them: least to most cautious. */
+export declare const TRIAGE_ACTION_VIEWS: readonly TriageActionView[];
+/**
+ * The decisions one row may offer. Continue and note both deliver the owed
+ * request, so they are absent when the log is unreadable or the host says it
+ * cannot wake the entry; the remaining decisions still give the user a way out.
+ * @param row - the rendered row.
+ * @returns the actions that can be taken on it.
+ */
+export declare function triageActionsFor(row: TriageRowView): readonly TriageActionView[];
+/**
+ * The fifth listed verb, rendered apart from the four decisions: it is a
+ * switch on what the NEXT resume may spend, not a way to decide this row.
+ */
+export declare const TRIAGE_GOAL_VIEW: TriageActionView;
+/** One listed session, as the panel renders it. */
+export interface TriageRowView {
+    /** Host data, rendered verbatim. */
+    readonly sessionId: string;
+    /** The durable outcome, as a word. */
+    readonly phaseKey: PauseKey;
+    /** Stop position: the event the log ends on and the step it belongs to. */
+    readonly stopped?: string;
+    /** The tools whose outcomes were never recorded. */
+    readonly unknownTools: readonly string[];
+    /** Whether the host said it can hand this session the request it owes. */
+    readonly wakeable: boolean;
+    /** Whether the log could be read at all. */
+    readonly readable: boolean;
+    /** Whether resuming this session may re-open its goal and spend its rounds. */
+    readonly rearmGoal: boolean;
+}
+/** What the decision-list panel renders. */
+export interface TriageView {
+    /** Whether the host answered the list read at all. */
+    readonly visible: boolean;
+    /** Whether the last list read failed rather than returning rows. */
+    readonly unavailable: boolean;
+    /** The rows the host reported. */
+    readonly rows: readonly TriageRowView[];
+}
+/**
+ * Map one decision-list reading to its view.
+ * @param reading - the host-reported list, or `undefined` before the panel asked.
+ * @returns the rows as the panel renders them.
+ */
+export declare function triageView(reading: TriageReading | undefined): TriageView;
+/** What the whole-app reading renders as. */
+export interface GlobalPauseView {
+    /** Whether the control renders at all; a control with no host answer claims nothing. */
+    readonly visible: boolean;
+    /** Whether the control accepts a press. */
+    readonly enabled: boolean;
+    /** Accessible name of the button. */
+    readonly ariaKey: PauseKey;
+    /**
+     * Headline shown beside the button. Absent while there is nothing to report:
+     * an untouched park renders the bare affordance, not a sentence about itself.
+     */
+    readonly labelKey?: PauseKey;
+    /** Verb the press runs. */
+    readonly action: GlobalAction;
+    /** Host numbers, rendered verbatim beside the label. */
+    readonly detail: string;
+    /** How many decisions are waiting; shown on the panel's own entry point. */
+    readonly unclean: number;
+    /** Named facts the user must not miss; rendered on the tooltip. */
+    readonly caveats: readonly GlobalCaveat[];
+    /** Draining sessions and what each is running, when the host still has work. */
+    readonly running?: string;
+}
+/**
+ * Map one whole-app reading to its view.
+ * @param reading - the host-reported reading, or `undefined` before the first answer.
+ * @returns the view for that reading.
+ */
+export declare function globalPauseView(reading: GlobalReading | undefined, sessions?: Readonly<Record<string, {
+    readonly runningTools: readonly string[];
+}>>): GlobalPauseView;