@kortix/sdk 0.13.4 → 0.13.7

package/dist/core/session/wake-escalation.js

@@ -0,0 +1,241 @@
+/**
+ * The wake escalation ladder — what a session view does when bringing a
+ * runtime up takes longer than it should.
+ *
+ * ## The failure this replaces
+ *
+ * Opening a stopped session starts a wake. The old model gave that wake a FIXED
+ * budget: the server's own `RUNTIME_WAKE_LEASE_MS` (240s,
+ * `apps/api/src/projects/session-lifecycle/runtime-wake-fence.ts:10`), after
+ * which maintenance stamps `stopReason: 'runtime_wake_failed'` and every
+ * subsequent `/start` short-circuits to a terminal payload
+ * (`apps/api/src/projects/routes/shared.ts:672-694`)
+ *
+ *     "Couldn't start session <id> — The session runtime did not become
+ *      reachable. Restart the session to try again."
+ *
+ * Measured on Essentia (2026-08-26, box `inqwpv4a1cc1kynlg46k8`): that card
+ * painted while the box was SECONDS from ready — its daemon logged
+ * `opencode ready` at 06:10:02, right after the budget expired. The card is a
+ * dead end with no auto-recovery, and the human's fix is always the same one
+ * click: "clicking restart made it work instantly". Two more recurrences
+ * followed, both during a post-deploy image rebuild — i.e. this class recurs on
+ * every ops event that slows a provider resume.
+ *
+ * ## The two rules that fix it
+ *
+ * 1. **A budget measures SILENCE, not elapsed time.** A wake that is visibly
+ *    advancing — provider state moving, daemon boot phases changing, health
+ *    improving — has not failed, however long it takes. Only a bounded window
+ *    with ZERO observable change is evidence of a wedge. So the clock here is
+ *    reset by any change to {@link WakeObservation.progress} and the elapsed
+ *    total is never consulted.
+ *
+ * 2. **Escalate through the ladder the human uses, and only then give up.**
+ *    A quiet `/start` retry first (free, and it heals a row that recovered on
+ *    its own), then the RESTART the user would have clicked — bounded to
+ *    {@link WAKE_MAX_RESTARTS}. The terminal card is what remains after the
+ *    ladder is exhausted, and it then has to name what was tried
+ *    ({@link wakeEscalationAttemptSummary}).
+ *
+ * A blanket "just restart it by default" was considered and REJECTED: it
+ * destroys fast warm resumes (a Platinum CoW resume reaches `running` in ~1.9s)
+ * by throwing away a box that was about to answer.
+ *
+ * ## Why `runtimeReachable` is a separate input from `waking`
+ *
+ * The session row is NOT proof the runtime is up. Observed on Essentia the same
+ * day: `POST …/start` answered 202 and the row stayed `running` for 5+ minutes
+ * while the E2B resume had silently failed — the provider reported the sandbox
+ * `stopped` and the daemon proxy answered `503 sandbox_not_ready`. A ladder that
+ * treated `stage: 'ready'` as the end of the wake would sit there forever. So
+ * the wake ends when the RUNTIME ANSWERS (`/kortix/health`), not when the
+ * control plane says it should have.
+ *
+ * That reachability is also a LATCH: once a runtime has answered, this machine
+ * is done for the life of the session view. A box that drops mid-session is
+ * `useRuntimeReconnect`'s problem, and auto-restarting it would destroy the
+ * turn the user is watching.
+ *
+ * Pure and clock-free: every decision is a function of the passed state plus one
+ * observation. The React glue lives in `react/use-wake-escalation.ts`.
+ */
+/**
+ * How long a wake may show ZERO observable change before the ladder escalates.
+ *
+ * Sized against the measured wake profile rather than a guess: a cold resume is
+ * 18.9s (Daytona) / 24.5s (Platinum) end to end, and each phase of it produces
+ * an observable change, so a healthy wake never accumulates more than a few
+ * seconds of silence. 75s is comfortably past the slowest legitimate single
+ * phase (the server's own provider-confirmation grace is 90s but it emits
+ * `runtime_waking` throughout) while still being three times faster to react
+ * than the 240s lease that produced the incident.
+ */
+export const WAKE_NO_PROGRESS_MS = 75_000;
+/**
+ * Automatic restarts the ladder may perform. Two, because the human fix that
+ * always works is one restart, and a second covers the case where the first
+ * landed during the same ops event (an image rebuild) that wedged the wake.
+ * Unbounded retries would be a restart loop against a genuinely dead provider.
+ */
+export const WAKE_MAX_RESTARTS = 2;
+/**
+ * Minimum gap between two ladder actions.
+ *
+ * A server-declared wake failure short-circuits the no-progress window (there is
+ * nothing left to wait for), so without a floor the ladder would spend its whole
+ * budget inside one second. `POST /restart` plus its first `/start` take ~2.6s
+ * measured; 20s leaves the new attempt room to produce its first signal.
+ */
+export const WAKE_ESCALATION_COOLDOWN_MS = 20_000;
+export function initialWakeEscalationState() {
+    return {
+        status: 'idle',
+        dispatch: 'none',
+        fingerprint: null,
+        lastProgressAtMs: null,
+        lastDispatchAtMs: null,
+        attempts: [],
+        msSinceProgress: 0,
+        settled: false,
+    };
+}
+/**
+ * Join the observable wake signals into one comparable value, dropping the ones
+ * that are not known yet.
+ *
+ * `null`/`undefined` are DROPPED rather than stringified so that a signal
+ * arriving for the first time (a sandbox row appearing, a health body parsing)
+ * reads as the progress it is, while a signal that is simply absent contributes
+ * nothing and cannot manufacture a change on its own.
+ */
+export function wakeProgressFingerprint(parts) {
+    return parts.filter((part) => part !== null && part !== undefined).join('|');
+}
+/** The next rung, or null when the ladder is spent. */
+function nextStep(attempts, maxRestarts) {
+    if (attempts.length === 0)
+        return 'retry-start';
+    const restarts = attempts.filter((attempt) => attempt.step === 'restart').length;
+    return restarts < maxRestarts ? 'restart' : null;
+}
+/**
+ * Fold one observation into the ladder's state. Pure — same inputs, same output,
+ * no clock and no I/O.
+ */
+export function advanceWakeEscalation(state, observation, limits = {}) {
+    const noProgressMs = limits.noProgressMs ?? WAKE_NO_PROGRESS_MS;
+    const maxRestarts = limits.maxRestarts ?? WAKE_MAX_RESTARTS;
+    const cooldownMs = limits.cooldownMs ?? WAKE_ESCALATION_COOLDOWN_MS;
+    // The runtime answered. The wake is over, and nothing about it may leak into
+    // the next one. `settled` survives the reset: within one session view, a
+    // runtime that has answered is never woken again by this machine.
+    if (observation.runtimeReachable) {
+        return { ...initialWakeEscalationState(), settled: true };
+    }
+    // The host cannot classify the wake right now — PAUSE, do not forget.
+    //
+    // This is not hypothetical tidiness. `useRestartProjectSession` seeds the
+    // `/start` cache with `{stage: 'provisioning', sandbox: null}` the instant a
+    // restart is dispatched, and a null sandbox is exactly "cannot classify". If
+    // that cleared `attempts`, every rung the ladder fired would reset its own
+    // budget and `WAKE_MAX_RESTARTS` would bound nothing — a restart loop, which
+    // is strictly worse than the dead-end card this replaces.
+    //
+    // The silence clock IS cleared, so resuming re-baselines rather than
+    // escalating on the strength of a window the ladder never actually watched.
+    // The dispatch cooldown is deliberately kept: a pause must not become a way
+    // to fire two rungs back to back.
+    if (!observation.waking) {
+        return { ...state, dispatch: 'none', fingerprint: null, lastProgressAtMs: null, msSinceProgress: 0 };
+    }
+    // A runtime that already answered and later dropped is a mid-session
+    // reconnect, not a wake. Restarting it would destroy the live turn.
+    if (state.settled)
+        return { ...initialWakeEscalationState(), settled: true };
+    const previousProgressAtMs = state.lastProgressAtMs;
+    const first = previousProgressAtMs === null;
+    const changed = observation.progress !== state.fingerprint;
+    const lastProgressAtMs = previousProgressAtMs === null || changed ? observation.nowMs : previousProgressAtMs;
+    const msSinceProgress = Math.max(0, observation.nowMs - lastProgressAtMs);
+    const base = {
+        ...state,
+        dispatch: 'none',
+        fingerprint: observation.progress,
+        lastProgressAtMs,
+        msSinceProgress,
+        status: state.attempts.length > 0 ? 'escalating' : 'waking',
+    };
+    if (state.status === 'exhausted')
+        return { ...base, status: 'exhausted' };
+    // A server-declared failure needs no window: the wake is over, only the
+    // ladder is left. Everything else waits out the silence.
+    const stalled = !first && !changed && msSinceProgress >= noProgressMs;
+    if (!observation.serverGaveUp && !stalled)
+        return base;
+    // One action per cooldown, whatever triggered it.
+    if (state.lastDispatchAtMs !== null &&
+        observation.nowMs - state.lastDispatchAtMs < cooldownMs) {
+        return base;
+    }
+    const step = nextStep(state.attempts, maxRestarts);
+    if (!step)
+        return { ...base, status: 'exhausted' };
+    return {
+        ...base,
+        status: 'escalating',
+        dispatch: step,
+        attempts: [...state.attempts, { step, atMs: observation.nowMs }],
+        lastDispatchAtMs: observation.nowMs,
+        // The new attempt gets its own window: it has not been silent yet.
+        lastProgressAtMs: observation.nowMs,
+        msSinceProgress: 0,
+    };
+}
+const STEP_VERB = {
+    'retry-start': 'retrying',
+    restart: 'restarting',
+};
+/**
+ * The honest one-line status while the ladder is working, in the same voice as
+ * the boot-phase pill ("Waking the agent", "Connecting").
+ *
+ * Null while the first, ordinary wake is running — that wake already has honest
+ * copy and does not need a second component talking over it — and null once
+ * exhausted, where the terminal card takes over.
+ */
+export function wakeEscalationNote(state) {
+    if (state.status !== 'escalating')
+        return null;
+    const last = state.attempts[state.attempts.length - 1];
+    if (!last)
+        return null;
+    // The original wake is attempt 1, so the Nth ladder action is attempt N+1.
+    return `Still waking — ${STEP_VERB[last.step]} the runtime (attempt ${state.attempts.length + 1})`;
+}
+function countWord(count) {
+    if (count === 1)
+        return 'once';
+    if (count === 2)
+        return 'twice';
+    return `${count} times`;
+}
+/**
+ * What the ladder tried, for the terminal card. A dead end that cannot say what
+ * was already attempted invites the user to repeat it by hand.
+ */
+export function wakeEscalationAttemptSummary(state) {
+    if (state.status !== 'exhausted')
+        return null;
+    const restarts = state.attempts.filter((attempt) => attempt.step === 'restart').length;
+    const retried = state.attempts.some((attempt) => attempt.step === 'retry-start');
+    if (!retried && restarts === 0)
+        return null;
+    const parts = [];
+    if (retried)
+        parts.push('re-issuing the wake');
+    if (restarts > 0)
+        parts.push(`restarting the session ${countWord(restarts)}`);
+    return `Tried: ${parts.join(', then ')}.`;
+}
+//# sourceMappingURL=wake-escalation.js.map

package/dist/core/session/wake-escalation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wake-escalation.js","sourceRoot":"","sources":["../../../src/core/session/wake-escalation.ts"],"names":[],"mappings":"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"}

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

@@ -92,6 +92,30 @@ export declare const STREAM_OBSERVATION_MAX_MS = 45000;
  * Stop with its reply on screen for up to 45s.
  */
 export declare const INBOX_OBSERVATION_MAX_MS = 10000;
+/**
+ * How long a runtime `idle` frame may outrank the control plane's turn row.
+ *
+ * The ledger is closed by a SEPARATE daemon relay (`POST .../turn-stream`
+ * `kind:"end"`), so for a moment after the runtime goes idle the row is still
+ * open and a `/turn` read taken in that window honestly reports a turn that has
+ * finished. MEASURED 2026-08-21 on a healthy stack: the relay POST itself took
+ * 1765ms, while the idle frame reaches the tab immediately and triggers its own
+ * refetch that lands ~186ms later — squarely inside the gap. Without this the
+ * composer's Stop button and the turn shimmer came back ~200ms after the reply
+ * and stayed for the whole poll interval.
+ *
+ * BOUNDED, and this is the important half. An idle frame is NOT proof the turn
+ * ended: `session.error` is relayed as `idle` too ("errors terminate the
+ * response"), and OpenCode emits it while it is RETRYING a provider — a 429
+ * backoff, a transient upstream 5xx — with the turn still very much live. An
+ * unbounded rule therefore un-busied the composer mid-turn on every retry and
+ * held it that way until the next `busy` frame, which is a worse flicker than
+ * the one it fixes. Past this window the ledger is believed again, so a retry
+ * blip self-heals in seconds instead of lasting the stream's whole 45s life.
+ *
+ * Comfortably above the measured relay, far below a provider backoff.
+ */
+export declare const TURN_END_LEDGER_LAG_MS = 3000;
 /**
  * How long a stop this tab issued may bar a server read from reporting the
  * turn it is ending.
@@ -105,9 +129,17 @@ export declare const INBOX_OBSERVATION_MAX_MS = 10000;
 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. */
+    /** The submission's tab-local name — never sent anywhere. */
     messageId: string;
+    /**
+     * The user-message turn that owns the working indicator while this receipt
+     * is live. A direct idle send names itself. A send made during an existing
+     * response names that existing turn, so its new bubble remains pending.
+     *
+     * `undefined` preserves the original contract and falls back to
+     * `messageId`. `null` explicitly means the caller cannot identify the turn.
+     */
+    turnId?: string | null;
     /** ms epoch at which the send left this tab. */
     atMs: number;
     /**
@@ -157,14 +189,85 @@ export interface WorkingServerInput {
 /** One observed runtime status frame, stamped when this tab observed it. */
 export interface WorkingStreamInput {
     type: 'busy' | 'retry' | 'idle';
+    /**
+     * WHO minted the frame. `'wire'` (or absent — the field is additive) means
+     * the runtime's own SSE frame reached this tab. `'local'` means the tab
+     * synthesized it: `reconcileMissingBusySessions` reading absence out of a
+     * status snapshot, `markSessionAbortedLocally` on `server.instance.disposed`,
+     * `clearSession` on a cache-ownership handoff.
+     *
+     * The distinction exists for exactly one rule: only the runtime's own idle
+     * frame may CONTRADICT the lifecycle authority (`endedByRuntime`, and the
+     * "fresher frame knows more" ordering over an open row). A local frame is an
+     * inference, and the veto it inherited is unbounded on purpose — so one
+     * fabricated idle discarded every fresh `/turn` read for the rest of a quiet
+     * turn: the busy indicator left, the composer swapped Stop for Send, and
+     * both came back only when the reply finally streamed (dev, 2026-08-24). A
+     * local frame may still ANSWER when nothing fresher exists — the repair for
+     * a missed terminal frame stays a repair — it just cannot overrule a source
+     * that can actually know.
+     */
+    origin?: 'wire' | 'local';
+    atMs: number;
+}
+/**
+ * The last moment the RUNTIME'S OWN OUTPUT reached this tab for this session —
+ * a streamed part, a message. Stamped on observation, like every other input.
+ *
+ * Every other input here is an OBSERVER of the runtime: a `/turn` poll, a
+ * status frame, a health probe, an inbox read. Each can be dropped, throttled
+ * or aged out, and when one is, the projection has historically had to guess.
+ * This one is not an observer. Content arriving is not a report that the
+ * runtime is working — it IS the runtime working, and no report outranks it.
+ *
+ * Reported with a screen recording (essentia, 2026-08-23): a tool row with a
+ * live spinner and text growing on screen, and a composer showing its send
+ * arrow. Every observer had gone quiet; the only thing still speaking was the
+ * content, and nothing was listening to it.
+ *
+ * Content reaches the tab two ways, and both stamp this: pushed (a streamed
+ * part off the SSE wire) and PULLED (a liveness-poll tail read whose hydrate
+ * shows the transcript moved with its tail still open — `sync-store.hydrate`).
+ * The pull path is what answers when the wire itself is the thing that died
+ * (essentia, 2026-08-26: stream black-holed mid-turn, stale idle frame vetoing
+ * the open turn row, transcript minutes behind).
+ */
+export interface WorkingActivityInput {
     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;
+    /** This tab's clock at ISSUE or RECEIVE time. The AGE stamp: it only ever
+     *  meets `nowMs` — the same clock — in `INBOX_OBSERVATION_MAX_MS`. */
     atMs: number;
+    /**
+     * The SERVER's clock at the observation — `observed_at` captured before the
+     * read (GET, bundle, stream frame) or after the write (`POST .../prompts`).
+     * The ORDERING stamp: it only ever meets another `serverAtMs`. Absent when
+     * the server did not supply one.
+     *
+     * Two stamps because one field served both jobs and the jobs need different
+     * clocks. Ranked against a browser stamp, an API clock ±10 minutes off
+     * either rejected every later direct read (skew ahead) or aged the
+     * observation out on arrival (skew behind) — both reproduced in PR #6957's
+     * review as a stale empty snapshot hiding a backend-confirmed queue row.
+     */
+    serverAtMs?: number;
 }
+/**
+ * May `candidate` replace `current` as the session's inbox observation?
+ *
+ * ONE clock per comparison. When both observations carry the server's stamp,
+ * the server clock decides — it is the only pair drawn from one clock, and it
+ * orders a read against a write exactly (a read issued before a POST carries an
+ * older `observed_at` than the POST's response, so it can never erase it).
+ * Otherwise the browser stamps decide, as before. Ties stand aside for the
+ * candidate: two reads of the same instant agree, and the newer arrival may
+ * carry a corrected list.
+ */
+export declare function inboxObservationSupersedes(candidate: WorkingInboxInput, current: WorkingInboxInput | null | undefined): boolean;
 export interface WorkingInputs {
     optimistic: SendReceipt | null;
     /** This tab's pending stop. `null`/absent means it is not stopping. */
@@ -173,6 +276,8 @@ export interface WorkingInputs {
     inbox?: WorkingInboxInput | null;
     server: WorkingServerInput | null;
     stream: WorkingStreamInput | null;
+    /** The runtime's own output, last seen. See `WorkingActivityInput`. */
+    activity?: WorkingActivityInput | null;
     nowMs: number;
 }
 /**

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

@@ -1 +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"}
+{"version":3,"file":"working.d.ts","sourceRoot":"","sources":["../../../src/core/session/working.ts"],"names":[],"mappings":"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"}