@kortix/sdk 0.12.8 → 0.13.0

package/dist/core/session/rewind.d.ts

@@ -1,18 +1,84 @@
-export declare function messagesBeforeRewind<T extends {
-    info: {
-        id: string;
-    };
-}>(messages: T[], messageId: string | null): T[];
+/**
+ * Client-side projection of a staged/committed session rewind.
+ *
+ * `session.revert` is a STAGED pointer server-side — OpenCode never deletes
+ * anything until the next prompt COMMITS it (and `unrevert` restores it while
+ * staged). Nothing here talks to the network; this module is the pure math
+ * the sync store and `useSession` share for two questions:
+ *
+ *   1. Which locally-known messages does a staged rewind hide?
+ *   2. When is a message id inside the range a committed rewind must delete?
+ *
+ * `watermark` exists to fix a real bug: hiding used to be "everything at-or-
+ * after the boundary id", recomputed on every render off the CURRENT message
+ * list. A message minted AFTER staging — the user's replacement prompt, its
+ * answer — sorts above the boundary by id exactly like every OTHER later
+ * message, so it fell inside "everything after the boundary" too and never
+ * rendered until an unrelated remount flooded the whole transcript back,
+ * interleaved. `watermark` freezes the upper edge of the hide window at the
+ * newest message id known AT STAGE TIME, so only messages that were already
+ * part of the abandoned trajectory are ever hidden — anything newer always
+ * renders.
+ */
 export interface SessionRewindState {
+    /** The message the rewind pointer sits at — hidden along with everything
+     *  up to `watermark`. */
     messageId: string;
+    /**
+     * The newest message id known locally at the moment this rewind was staged
+     * (or first observed). The upper bound of the hide window — fixed once,
+     * never recomputed against a later, larger message list.
+     */
+    watermark: string;
+    /**
+     * False once the replacement prompt has been sent (or a
+     * `session.next.revert.committed` wire event says the server has). The
+     * hide window still applies while this is false — what stops being offered
+     * is Restore (`unrevert`), not the hiding. A committed rewind's window is
+     * deleted outright once the store observes it, not merely hidden — see
+     * `applyCommittedRevert` on the sync store.
+     */
     staged: boolean;
 }
-/** Mark the rewind as committed while its removed path remains hidden locally. */
-export declare function commitSessionRewind(rewind: SessionRewindState | null): SessionRewindState | null;
-/** Drop the local boundary after runtime synchronization confirms cleanup. */
-export declare function reconcileCommittedSessionRewind<T extends {
+/** Whether `id` falls inside the [messageId, watermark] hide range — both
+ *  bounds inclusive: the boundary message itself is part of what an edit
+ *  replaces, and the watermark is the last message known at stage time. */
+export declare function isWithinRewindWindow(id: string, rewind: SessionRewindState): boolean;
+/**
+ * The newest (highest sort-order) message id in `messages`, or `null` for an
+ * empty list. Deliberately a max-scan, not "the last element" — most callers
+ * pass an ascending-sorted list, but an optimistic entry appended out of
+ * order must never win the max by position alone.
+ */
+export declare function newestMessageId<T extends {
     info: {
         id: string;
     };
-}>(messages: T[], rewind: SessionRewindState | null): SessionRewindState | null;
+}>(messages: T[]): string | null;
+/**
+ * Build the state for a freshly staged (or freshly discovered) rewind.
+ * `watermark` is captured HERE, from the message list at this exact moment —
+ * never recomputed later. Falls back to `messageId` itself when nothing is
+ * known locally yet (a cross-tab or reload discovery with no synced messages
+ * for this session), which hides only the boundary message and nothing
+ * else — the narrowest correct answer with no other information available.
+ */
+export declare function stageSessionRewind<T extends {
+    info: {
+        id: string;
+    };
+}>(messages: T[], messageId: string): SessionRewindState;
+/** Hide the target message and every message up to the staged watermark.
+ *  Returns the SAME array reference when nothing is actually hidden — a
+ *  fresh array on every call would defeat memoization in every consumer. */
+export declare function messagesBeforeRewind<T extends {
+    info: {
+        id: string;
+    };
+}>(messages: T[], rewind: SessionRewindState | null): T[];
+/** Mark the rewind as committed while its removed path remains hidden
+ *  locally (the actual deletion is a separate, explicit store action driven
+ *  by the wire's `.committed` event — see `applyCommittedRevert`). Returns
+ *  the SAME reference when already committed or when `rewind` is `null`. */
+export declare function commitSessionRewind(rewind: SessionRewindState | null): SessionRewindState | null;
 //# sourceMappingURL=rewind.d.ts.map

package/dist/core/session/rewind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rewind.d.ts","sourceRoot":"","sources":["../../../src/core/session/rewind.ts"],"names":[],"mappings":"AAAA,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EACrE,QAAQ,EAAE,CAAC,EAAE,EACb,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,CAAC,EAAE,CAIL;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,kBAAkB,GAAG,IAAI,GAChC,kBAAkB,GAAG,IAAI,CAE3B;AAED,8EAA8E;AAC9E,wBAAgB,+BAA+B,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAChF,QAAQ,EAAE,CAAC,EAAE,EACb,MAAM,EAAE,kBAAkB,GAAG,IAAI,GAChC,kBAAkB,GAAG,IAAI,CAG3B"}
+{"version":3,"file":"rewind.d.ts","sourceRoot":"","sources":["../../../src/core/session/rewind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,WAAW,kBAAkB;IACjC;6BACyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;2EAE2E;AAC3E,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAEpF;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAChE,QAAQ,EAAE,CAAC,EAAE,GACZ,MAAM,GAAG,IAAI,CAMf;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EACnE,QAAQ,EAAE,CAAC,EAAE,EACb,SAAS,EAAE,MAAM,GAChB,kBAAkB,CAMpB;AAED;;4EAE4E;AAC5E,wBAAgB,oBAAoB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EACrE,QAAQ,EAAE,CAAC,EAAE,EACb,MAAM,EAAE,kBAAkB,GAAG,IAAI,GAChC,CAAC,EAAE,CAIL;AAED;;;4EAG4E;AAC5E,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,kBAAkB,GAAG,IAAI,GAChC,kBAAkB,GAAG,IAAI,CAE3B"}

package/dist/core/session/rewind.js

@@ -1,17 +1,74 @@
-export function messagesBeforeRewind(messages, messageId) {
-    if (!messageId)
+/**
+ * Client-side projection of a staged/committed session rewind.
+ *
+ * `session.revert` is a STAGED pointer server-side — OpenCode never deletes
+ * anything until the next prompt COMMITS it (and `unrevert` restores it while
+ * staged). Nothing here talks to the network; this module is the pure math
+ * the sync store and `useSession` share for two questions:
+ *
+ *   1. Which locally-known messages does a staged rewind hide?
+ *   2. When is a message id inside the range a committed rewind must delete?
+ *
+ * `watermark` exists to fix a real bug: hiding used to be "everything at-or-
+ * after the boundary id", recomputed on every render off the CURRENT message
+ * list. A message minted AFTER staging — the user's replacement prompt, its
+ * answer — sorts above the boundary by id exactly like every OTHER later
+ * message, so it fell inside "everything after the boundary" too and never
+ * rendered until an unrelated remount flooded the whole transcript back,
+ * interleaved. `watermark` freezes the upper edge of the hide window at the
+ * newest message id known AT STAGE TIME, so only messages that were already
+ * part of the abandoned trajectory are ever hidden — anything newer always
+ * renders.
+ */
+/** Whether `id` falls inside the [messageId, watermark] hide range — both
+ *  bounds inclusive: the boundary message itself is part of what an edit
+ *  replaces, and the watermark is the last message known at stage time. */
+export function isWithinRewindWindow(id, rewind) {
+    return id >= rewind.messageId && id <= rewind.watermark;
+}
+/**
+ * The newest (highest sort-order) message id in `messages`, or `null` for an
+ * empty list. Deliberately a max-scan, not "the last element" — most callers
+ * pass an ascending-sorted list, but an optimistic entry appended out of
+ * order must never win the max by position alone.
+ */
+export function newestMessageId(messages) {
+    let max = null;
+    for (const message of messages) {
+        if (max === null || message.info.id > max)
+            max = message.info.id;
+    }
+    return max;
+}
+/**
+ * Build the state for a freshly staged (or freshly discovered) rewind.
+ * `watermark` is captured HERE, from the message list at this exact moment —
+ * never recomputed later. Falls back to `messageId` itself when nothing is
+ * known locally yet (a cross-tab or reload discovery with no synced messages
+ * for this session), which hides only the boundary message and nothing
+ * else — the narrowest correct answer with no other information available.
+ */
+export function stageSessionRewind(messages, messageId) {
+    return {
+        messageId,
+        watermark: newestMessageId(messages) ?? messageId,
+        staged: true,
+    };
+}
+/** Hide the target message and every message up to the staged watermark.
+ *  Returns the SAME array reference when nothing is actually hidden — a
+ *  fresh array on every call would defeat memoization in every consumer. */
+export function messagesBeforeRewind(messages, rewind) {
+    if (!rewind)
         return messages;
-    const boundary = messages.findIndex((message) => message.info.id === messageId);
-    return boundary < 0 ? messages : messages.slice(0, boundary);
+    const kept = messages.filter((message) => !isWithinRewindWindow(message.info.id, rewind));
+    return kept.length === messages.length ? messages : kept;
 }
-/** Mark the rewind as committed while its removed path remains hidden locally. */
+/** Mark the rewind as committed while its removed path remains hidden
+ *  locally (the actual deletion is a separate, explicit store action driven
+ *  by the wire's `.committed` event — see `applyCommittedRevert`). Returns
+ *  the SAME reference when already committed or when `rewind` is `null`. */
 export function commitSessionRewind(rewind) {
     return rewind?.staged ? { ...rewind, staged: false } : rewind;
 }
-/** Drop the local boundary after runtime synchronization confirms cleanup. */
-export function reconcileCommittedSessionRewind(messages, rewind) {
-    if (!rewind || rewind.staged)
-        return rewind;
-    return messages.some((message) => message.info.id === rewind.messageId) ? rewind : null;
-}
 //# sourceMappingURL=rewind.js.map

package/dist/core/session/rewind.js.map

@@ -1 +1 @@
-{"version":3,"file":"rewind.js","sourceRoot":"","sources":["../../../src/core/session/rewind.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,oBAAoB,CAClC,QAAa,EACb,SAAwB;IAExB,IAAI,CAAC,SAAS;QAAE,OAAO,QAAQ,CAAC;IAChC,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC;IAChF,OAAO,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AAC/D,CAAC;AAOD,kFAAkF;AAClF,MAAM,UAAU,mBAAmB,CACjC,MAAiC;IAEjC,OAAO,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,+BAA+B,CAC7C,QAAa,EACb,MAAiC;IAEjC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC;IAC5C,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1F,CAAC"}
+{"version":3,"file":"rewind.js","sourceRoot":"","sources":["../../../src/core/session/rewind.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAuBH;;2EAE2E;AAC3E,MAAM,UAAU,oBAAoB,CAAC,EAAU,EAAE,MAA0B;IACzE,OAAO,EAAE,IAAI,MAAM,CAAC,SAAS,IAAI,EAAE,IAAI,MAAM,CAAC,SAAS,CAAC;AAC1D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,QAAa;IAEb,IAAI,GAAG,GAAkB,IAAI,CAAC;IAC9B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,GAAG;YAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAa,EACb,SAAiB;IAEjB,OAAO;QACL,SAAS;QACT,SAAS,EAAE,eAAe,CAAC,QAAQ,CAAC,IAAI,SAAS;QACjD,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC;AAED;;4EAE4E;AAC5E,MAAM,UAAU,oBAAoB,CAClC,QAAa,EACb,MAAiC;IAEjC,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC;IAC7B,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IAC1F,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3D,CAAC;AAED;;;4EAG4E;AAC5E,MAAM,UAAU,mBAAmB,CACjC,MAAiC;IAEjC,OAAO,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC"}

package/dist/core/session/working.d.ts

@@ -0,0 +1,241 @@
+import type { SessionPrompt, SessionTurn, SessionTurnEnded } from '../rest/projects-client/sessions.js';
+/**
+ * WHICH observation decided the state.
+ *
+ * `server` — `GET .../turn`, the control plane's lifecycle authority, or the
+ * session's durable prompt inbox. Both are rows the server owns.
+ * `stream` — a `session.status` / `session.idle` frame off the live SSE stream.
+ * `optimistic` — this tab's own send receipt, which no server source has
+ * answered yet.
+ *
+ * Provenance is part of the answer because the failure this replaces was a
+ * projection nobody could attribute: three machines wrote "busy" into one
+ * slot — a stall timer, a 30s safety timeout, a status latch — and when the
+ * session stayed busy forever, no one could say which of them was lying.
+ */
+export type WorkingSource = 'server' | 'stream' | 'optimistic';
+export interface WorkingProjection {
+    state: 'idle' | 'working';
+    /** WHICH observation decided this. Never inferred, never fabricated. */
+    source: WorkingSource;
+    /** The wire message id (server) or the optimistic receipt id. */
+    turnId: string | null;
+    /** ms epoch at which THIS state began, from the deciding observation. */
+    since: number;
+    /**
+     * The `turn_token` of the turn the control plane is holding open in the
+     * freshest read we have, EVEN WHEN something newer outranked it above.
+     *
+     * `state` is the answer; this is the raw fact behind one of its inputs, and
+     * the two are deliberately separable. A caller that must not act while the
+     * server still holds authority — a `/` command, which goes straight at
+     * OpenCode with no admission gate in front of it — needs to see that
+     * authority even in the window where a fresher status frame is (correctly)
+     * deciding `idle`. `null` when no fresh read reports one, so a read too old
+     * to decide cannot latch it.
+     *
+     * The TOKEN, never `message_id`. `message_id` is the WIRE id of the prompt
+     * that opened the turn, and most producers send none: `postPrompt` omits
+     * `messageID` for triggers, Slack/Teams/Telegram, approval-resume and email,
+     * and `buildSessionCommandInput` omits it for every `/` command. `GET
+     * .../turn` answers `message_id: null` for all of them (the field is
+     * `z.string().nullable()`), so an authority check keyed on it read "the
+     * server holds nothing" over turns that were streaming. `turn_token` is
+     * minted by the control plane for every turn and is never null.
+     */
+    serverOpenTurnToken: string | null;
+}
+/**
+ * How long an unanswered optimistic receipt may claim `working` on its own.
+ *
+ * Bounded because a send whose response never arrives must not latch the UI —
+ * the failure this whole phase exists to end. Released the moment a server
+ * source that CAN know about the send answers; the cap only covers the case
+ * where none ever does.
+ */
+export declare const OPTIMISTIC_RECEIPT_MAX_MS = 60000;
+/**
+ * How long a server observation keeps deciding anything.
+ *
+ * `useSessionWorking` polls `GET .../turn` every 5s while working and every
+ * 15s while idle, and react-query hands back the last SUCCESSFUL read for as
+ * long as the ones after it fail. Without this bound, one successful read of an
+ * open turn followed by a dev-api 503, an expired JWT, or a closed laptop lid
+ * pinned the composer on "working" for the lifetime of the tab — literally the
+ * reported bug. Three idle cadences is long enough that an ordinary retry or a
+ * backgrounded tab never trips it, and short enough that a dead poll stops
+ * being believed.
+ */
+export declare const SERVER_OBSERVATION_MAX_MS = 45000;
+/**
+ * How long a status frame keeps deciding anything.
+ *
+ * The stream needs its own bound for the same reason the server read does, and
+ * the failure it covers is the SAME one: the SSE stream reaches this tab
+ * through the API that serves `/turn`, so when that API drains they stop
+ * together. The stream does not go `null` when it stops — the last `busy`
+ * frame this tab ever observed stays in the store — so bounding only the
+ * server read moved the latch one source over instead of ending it.
+ *
+ * Equal to the server bound on purpose: while the API answers at all, a fresh
+ * `/turn` read decides and this bound is never reached; once it stops
+ * answering, both observations are equally blind and neither may stand.
+ */
+export declare const STREAM_OBSERVATION_MAX_MS = 45000;
+/**
+ * How long ONE reading of the durable inbox keeps deciding.
+ *
+ * Three cadences of the prompt list's own poll (3s), not of `/turn`'s. A
+ * reading says "the server still intends to run N rows", and that claim decays
+ * fast: the row it counted may already have been delivered, run, and finished.
+ * Held for the server bound instead, a finished prompt left the composer on
+ * Stop with its reply on screen for up to 45s.
+ */
+export declare const INBOX_OBSERVATION_MAX_MS = 10000;
+/**
+ * How long a stop this tab issued may bar a server read from reporting the
+ * turn it is ending.
+ *
+ * Bounded for the same reason the send receipt is, in the other direction: an
+ * abort whose acknowledgement never comes must not pin the composer on `idle`
+ * over a turn that is genuinely still running. Generous next to the ~1.6s a
+ * cancel takes to reach the daemon, and far below the send receipt's cap
+ * because the evidence arrives sooner.
+ */
+export declare const OPTIMISTIC_ABORT_MAX_MS = 15000;
+/** This tab's own record that a prompt went out. */
+export interface SendReceipt {
+    /** The submission's tab-local name — never sent anywhere. It exists so a
+     *  `working` state can say WHICH send it is standing on. */
+    messageId: string;
+    /** ms epoch at which the send left this tab. */
+    atMs: number;
+    /**
+     * ms epoch at which the SERVER durably accepted the send (`POST .../prompts`
+     * returned, or the REST prompt was acknowledged), or null while the request
+     * is still on the wire.
+     *
+     * This is the instant from which a server read can speak for the send AT ALL.
+     * A `/turn` read issued while the POST is still in flight is stamped after
+     * the receipt and honestly answers "no turns" — because there is nothing for
+     * it to see yet. Believing it swapped the composer's Stop back to Send in the
+     * middle of the send and opened the queue drain into the turn about to start.
+     */
+    acceptedAtMs?: number | null;
+}
+/**
+ * This tab's own record that it asked the running turn to END.
+ *
+ * The mirror of `SendReceipt`, and it exists for the mirror-image failure. Stop
+ * paints the session idle and issues the cancel; the cancel needs a round trip
+ * through the control plane and the daemon (~1.6s measured) before the turn
+ * authority is actually released. Every `/turn` read issued inside that window
+ * still reports the doomed turn — including the one the optimistic idle FRAME
+ * itself triggers — so the composer swapped Send back to Stop about 120ms
+ * after the click and stayed there for the whole abort.
+ */
+export interface AbortReceipt {
+    /** ms epoch at which the cancel left this tab. */
+    atMs: number;
+    /**
+     * ms epoch at which the server acknowledged the cancel, or null while it is
+     * still on the wire.
+     *
+     * This is the instant from which a server read can see the abort's EFFECT.
+     * A read issued before it is honest and out of date, exactly like a `/turn`
+     * read issued before `POST .../prompts` returns.
+     */
+    settledAtMs?: number | null;
+}
+/** One read of `GET .../turn`, stamped with the instant the read was ISSUED —
+ *  not when it landed. An answer is only as fresh as the moment it was asked. */
+export interface WorkingServerInput {
+    turns: SessionTurn[];
+    lastEnded?: SessionTurnEnded;
+    atMs: number;
+}
+/** One observed runtime status frame, stamped when this tab observed it. */
+export interface WorkingStreamInput {
+    type: 'busy' | 'retry' | 'idle';
+    atMs: number;
+}
+/** One read of the session's durable prompt inbox: how many rows the server is
+ *  still going to run, and when that list was read. */
+export interface WorkingInboxInput {
+    pending: number;
+    atMs: number;
+}
+export interface WorkingInputs {
+    optimistic: SendReceipt | null;
+    /** This tab's pending stop. `null`/absent means it is not stopping. */
+    abort?: AbortReceipt | null;
+    /** The durable inbox. `null`/absent means it has never been read here. */
+    inbox?: WorkingInboxInput | null;
+    server: WorkingServerInput | null;
+    stream: WorkingStreamInput | null;
+    nowMs: number;
+}
+/**
+ * How many inbox rows are work the server still intends to run.
+ *
+ * `held` is excluded on purpose: it is the Stop button's own state — the row
+ * stays, deliberately not due, until the user sends something or presses "send
+ * now". Counting it would leave the composer on Stop with nothing running.
+ * `failed` is excluded for the same reason in the other direction: it is over.
+ */
+export declare function countLiveInboxPrompts(prompts: readonly SessionPrompt[]): number;
+/**
+ * The one place a session's working state is decided.
+ *
+ * Pure, so every rule below is asserted rather than observed by hand. No
+ * timers, no latch, no fabricated `SessionStatus` write — a caller that wants
+ * to re-evaluate simply calls again with a newer `nowMs`.
+ *
+ * Precedence:
+ *
+ *  1. The server is holding a turn open, and no NEWER stream frame contradicts
+ *     it → working. `GET .../turn` reads the lifecycle authority rather than the
+ *     ledger, so it is the strongest answer there is — but it is still a read
+ *     taken at an instant, and an SSE frame from after that instant knows more.
+ *  2. The server holds durable inbox rows for this session → working. A prompt
+ *     is accepted long before it is a turn: the row has to be drained, the box
+ *     may have to resume (18.9s Daytona / 24.5s Platinum, measured), and only
+ *     then does `beginSandboxTurn` run. "No turn is running" and "nothing of
+ *     yours is in flight" stopped being the same statement when the inbox
+ *     landed.
+ *  3. The server says no turns, and its read is at least as new as the stream's
+ *     last frame → idle. (A dropped end-of-turn frame is exactly why the server
+ *     has to be able to outrank a stale stream busy.)
+ *  4. The stream's own frame decides.
+ *  5. A live optimistic receipt → working.
+ *  6. Nothing observed → idle.
+ *
+ * With TWO cross-cutting freshness rules:
+ *
+ *  * An observation that could not yet know about a live LOCAL action cannot
+ *    answer for it — the send's floors (`SendReceipt.acceptedAtMs`) and the
+ *    stop's (`AbortReceipt.settledAtMs`), all built the same way.
+ *  * EVERY observation has a maximum age, and past it decides nothing at all in
+ *    either direction: `SERVER_OBSERVATION_MAX_MS`, `STREAM_OBSERVATION_MAX_MS`,
+ *    `INBOX_OBSERVATION_MAX_MS`. An observation the poll has failed to refresh
+ *    for that long is not evidence, and standing on one is the latch. Callers
+ *    must re-evaluate at those instants — see `workingExpiryAtMs`.
+ */
+export declare function projectWorking(inputs: WorkingInputs): WorkingProjection;
+/**
+ * The next instant at which `projectWorking` could answer differently on its
+ * own — i.e. when the OLDEST-lived input ages past its bound.
+ *
+ * The projection is pure and moves with `nowMs`, which means something has to
+ * ask it again at that instant or the bound is never applied. Nothing did: the
+ * hook re-renders when react-query hands it new `data`, and a run of failed
+ * reads hands back the SAME retained `data` — the observer does not even
+ * notify. `SERVER_OBSERVATION_MAX_MS` was therefore evaluated only on renders
+ * that happened for some unrelated reason, and in the exact outage it was
+ * written for (one success, then a run of 503s) there are none.
+ *
+ * `null` when nothing is left to expire. Deadlines already in the past are
+ * skipped, so re-arming from the timer this returns terminates.
+ */
+export declare function workingExpiryAtMs(inputs: WorkingInputs): number | null;
+//# sourceMappingURL=working.d.ts.map

package/dist/core/session/working.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"working.d.ts","sourceRoot":"","sources":["../../../src/core/session/working.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,gBAAgB,EACjB,MAAM,kCAAkC,CAAC;AAE1C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,CAAC;AAE/D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,wEAAwE;IACxE,MAAM,EAAE,aAAa,CAAC;IACtB,iEAAiE;IACjE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B;gEAC4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;iFACiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;uDACuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B,uEAAuE;IACvE,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC5B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAO/E;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,aAAa,GAAG,iBAAiB,CAmHvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAetE"}