@astralform/js 9.4.1 → 9.5.0

package/dist/index.d.cts

@@ -506,10 +506,23 @@ type ChatEvent = {
     type: "subagent_start";
     agent: AgentIdentity;
     taskCallId?: string | null;
+    /** The run's id, when the frame carries one (`agent_start`). */
+    runId?: string;
 } | {
     type: "subagent_stop";
     agent: AgentIdentity;
     taskCallId?: string | null;
+    /** The run's id, when the frame carries one (`agent_stop`). */
+    runId?: string;
+    /**
+     * The child's OWN outcome and spend, surfaced separately from the turn
+     * totals (`message_stop.usage` still folds them in). Absent on the older
+     * `subagent_stop` frames, which carried only the identity.
+     */
+    stopReason?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    durationMs?: number;
 } | {
     type: "context_warning";
     /** Known values: "info" | "warning" | "critical". Typed as string for forward compat. */
@@ -644,6 +657,19 @@ interface Conversation {
      * null) from an Astralform older than 0.69.46.
      */
     repository?: string | null;
+    /**
+     * The live job for this conversation, or `null`/absent when nothing is
+     * running. The sidebar's per-row liveness signal: without it a client cannot
+     * know that a conversation it has never opened is running, because its only
+     * other liveness signals are the per-conversation streams it is attached to.
+     *
+     * A JOB ID rather than a state string, deliberately: the backend can cheaply
+     * say "a job is live here", while "waiting for the user" lives in the
+     * worker's in-memory state and reaches only the open conversation's stream.
+     * `null` from a server that projects the field; `undefined` from one older
+     * than it (same convention as `repository`), so treat both as "not running".
+     */
+    activeJobId?: string | null;
     /**
      * The code group this task is filed under, or `null`/absent when it is not in
      * one. MUTABLE — unlike `repository`, which is written once on the first turn:
@@ -1970,12 +1996,6 @@ type ChatEventHandler = (event: ChatEvent) => void;
  * would leave the second page's offset pointing at the wrong row.
  */
 declare const CONVERSATION_PAGE_SIZE = 50;
-/**
- * ChatSession — translates the backend wire protocol into typed ChatEvents
- * for consumers. Owns HTTP + SSE plumbing, conversation state, and the
- * client-tool round-trip. Does NOT own block construction — consumers
- * build their own block state from the typed events.
- */
 declare class ChatSession {
     readonly client: AstralformClient;
     readonly toolRegistry: ToolRegistry;
@@ -2115,6 +2135,33 @@ declare class ChatSession {
     private processStream;
     /** Last received sequence number for resumable reconnection */
     private lastSeq;
+    /**
+     * Advance the resume cursor from a frame's `seq` — the position the next
+     * reconnect asks the backend to replay after (`?after=`).
+     *
+     * Two guards, because getting this wrong is silent and expensive: the whole
+     * turn replays over blocks the consumer is already rendering.
+     *
+     *  - **A keepalive is not an event.** The backend sends it as an ordinary
+     *    `data:` frame with `seq: 0` BY DESIGN (``WireKeepalive(seq=0, ts=0.0)``
+     *    — an idle tick, not a position), and it arrives exactly when a turn has
+     *    been quiet for 45 s: the long-tool-run case. Harvesting it rewound the
+     *    cursor to 0, so a reconnect after a blip replayed the turn from its
+     *    start — deltas and all.
+     *  - **The cursor only advances.** `send` and `reconnectToJob` reset it to
+     *    -1 per job, so a new job's `seq: 0` still moves it forward; a frame
+     *    carrying an older (or zero) position cannot move it back.
+     *
+     * The one other frame on the wire with a non-position `seq` is the
+     * subscriber's SYNTHETIC terminal — a back-filled `error` for a job whose
+     * worker died, built without a `seq` so Pydantic's default `0` reaches the
+     * wire. Deliberately not named here: the advance-only rule already ignores it
+     * whenever the client has drained anything (0 never exceeds a real cursor),
+     * and when it is the FIRST frame the pump ends on `sawTerminal` before any
+     * reconnect could use the cursor. Naming it would add a rule that no
+     * reachable input exercises.
+     */
+    private harvestResumeCursor;
     /**
      * Client-tool call_ids whose result was already submitted this turn. On a
      * reconnect the resumed stream can replay a tool request we already handled;
@@ -2182,7 +2229,15 @@ declare class ChatSession {
      * Reconnect to a running job's SSE stream (e.g. after page reload).
      * Replays all events from the beginning and continues live.
      */
-    reconnectToJob(jobId: string): Promise<void>;
+    /**
+     * @param afterSeq Resume the job's event stream AFTER this sequence number.
+     *   Omitted (the reconnect default) replays the job from the beginning. A
+     *   caller that holds the job's events up to `afterSeq` — the transcript
+     *   cache — passes it so the backend replays only the delta and then goes
+     *   live; the backend's `?after=` handles a job that already ended by
+     *   back-filling its terminal event.
+     */
+    reconnectToJob(jobId: string, afterSeq?: number): Promise<void>;
     /** Detach from the SSE stream without cancelling the job. */
     detach(): void;
     /**
@@ -2605,6 +2660,35 @@ declare class StreamManager {
      */
     switchTo(conversationId: string, opts?: {
         skipHistoryReplay?: boolean;
+        /**
+         * Jobs whose events the caller ALREADY holds — the transcript-cache
+         * resume. A COMPLETED job named here is neither fetched nor replayed: its
+         * blocks are in the caller's store, and replaying them would draw a
+         * second copy.
+         *
+         * Two limits, both deliberate and both stating what a review proved the
+         * wider contract could not:
+         *
+         *  - **The newest turn page only.** The marks are matched against the page
+         *    of jobs this restore walks, so a mark for a turn OLDER than that page
+         *    is not consulted. The message window (40 rows) and the turn page (10)
+         *    are independent spans, so a cache deeper than one page would need its
+         *    own cursor design — a prompt whose turn is not on the page cannot be
+         *    recognized as held, and would come back as a steer bubble.
+         *  - **Completed jobs only.** A mark for the RUNNING job is ignored (its
+         *    stream starts from the beginning, as it always did). Resuming a live
+         *    turn's stream from a mark would deliver the delta but NOT the prompt
+         *    — a prompt is a message-table row, not a stream event — so the plan
+         *    would still draw a bubble the caller's cache already renders.
+         *
+         * Absent → today's behaviour exactly. A job NOT named is fetched whole, as
+         * now, so a stale mark loses at most one completed turn's skip, never a
+         * turn.
+         */
+        have?: ReadonlyArray<{
+            jobId: string;
+            lastSeq: number;
+        }>;
     }): Promise<void>;
     /**
      * Re-attach to whatever the server says is live for the ACTIVE conversation.

package/dist/index.d.ts

@@ -506,10 +506,23 @@ type ChatEvent = {
     type: "subagent_start";
     agent: AgentIdentity;
     taskCallId?: string | null;
+    /** The run's id, when the frame carries one (`agent_start`). */
+    runId?: string;
 } | {
     type: "subagent_stop";
     agent: AgentIdentity;
     taskCallId?: string | null;
+    /** The run's id, when the frame carries one (`agent_stop`). */
+    runId?: string;
+    /**
+     * The child's OWN outcome and spend, surfaced separately from the turn
+     * totals (`message_stop.usage` still folds them in). Absent on the older
+     * `subagent_stop` frames, which carried only the identity.
+     */
+    stopReason?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    durationMs?: number;
 } | {
     type: "context_warning";
     /** Known values: "info" | "warning" | "critical". Typed as string for forward compat. */
@@ -644,6 +657,19 @@ interface Conversation {
      * null) from an Astralform older than 0.69.46.
      */
     repository?: string | null;
+    /**
+     * The live job for this conversation, or `null`/absent when nothing is
+     * running. The sidebar's per-row liveness signal: without it a client cannot
+     * know that a conversation it has never opened is running, because its only
+     * other liveness signals are the per-conversation streams it is attached to.
+     *
+     * A JOB ID rather than a state string, deliberately: the backend can cheaply
+     * say "a job is live here", while "waiting for the user" lives in the
+     * worker's in-memory state and reaches only the open conversation's stream.
+     * `null` from a server that projects the field; `undefined` from one older
+     * than it (same convention as `repository`), so treat both as "not running".
+     */
+    activeJobId?: string | null;
     /**
      * The code group this task is filed under, or `null`/absent when it is not in
      * one. MUTABLE — unlike `repository`, which is written once on the first turn:
@@ -1970,12 +1996,6 @@ type ChatEventHandler = (event: ChatEvent) => void;
  * would leave the second page's offset pointing at the wrong row.
  */
 declare const CONVERSATION_PAGE_SIZE = 50;
-/**
- * ChatSession — translates the backend wire protocol into typed ChatEvents
- * for consumers. Owns HTTP + SSE plumbing, conversation state, and the
- * client-tool round-trip. Does NOT own block construction — consumers
- * build their own block state from the typed events.
- */
 declare class ChatSession {
     readonly client: AstralformClient;
     readonly toolRegistry: ToolRegistry;
@@ -2115,6 +2135,33 @@ declare class ChatSession {
     private processStream;
     /** Last received sequence number for resumable reconnection */
     private lastSeq;
+    /**
+     * Advance the resume cursor from a frame's `seq` — the position the next
+     * reconnect asks the backend to replay after (`?after=`).
+     *
+     * Two guards, because getting this wrong is silent and expensive: the whole
+     * turn replays over blocks the consumer is already rendering.
+     *
+     *  - **A keepalive is not an event.** The backend sends it as an ordinary
+     *    `data:` frame with `seq: 0` BY DESIGN (``WireKeepalive(seq=0, ts=0.0)``
+     *    — an idle tick, not a position), and it arrives exactly when a turn has
+     *    been quiet for 45 s: the long-tool-run case. Harvesting it rewound the
+     *    cursor to 0, so a reconnect after a blip replayed the turn from its
+     *    start — deltas and all.
+     *  - **The cursor only advances.** `send` and `reconnectToJob` reset it to
+     *    -1 per job, so a new job's `seq: 0` still moves it forward; a frame
+     *    carrying an older (or zero) position cannot move it back.
+     *
+     * The one other frame on the wire with a non-position `seq` is the
+     * subscriber's SYNTHETIC terminal — a back-filled `error` for a job whose
+     * worker died, built without a `seq` so Pydantic's default `0` reaches the
+     * wire. Deliberately not named here: the advance-only rule already ignores it
+     * whenever the client has drained anything (0 never exceeds a real cursor),
+     * and when it is the FIRST frame the pump ends on `sawTerminal` before any
+     * reconnect could use the cursor. Naming it would add a rule that no
+     * reachable input exercises.
+     */
+    private harvestResumeCursor;
     /**
      * Client-tool call_ids whose result was already submitted this turn. On a
      * reconnect the resumed stream can replay a tool request we already handled;
@@ -2182,7 +2229,15 @@ declare class ChatSession {
      * Reconnect to a running job's SSE stream (e.g. after page reload).
      * Replays all events from the beginning and continues live.
      */
-    reconnectToJob(jobId: string): Promise<void>;
+    /**
+     * @param afterSeq Resume the job's event stream AFTER this sequence number.
+     *   Omitted (the reconnect default) replays the job from the beginning. A
+     *   caller that holds the job's events up to `afterSeq` — the transcript
+     *   cache — passes it so the backend replays only the delta and then goes
+     *   live; the backend's `?after=` handles a job that already ended by
+     *   back-filling its terminal event.
+     */
+    reconnectToJob(jobId: string, afterSeq?: number): Promise<void>;
     /** Detach from the SSE stream without cancelling the job. */
     detach(): void;
     /**
@@ -2605,6 +2660,35 @@ declare class StreamManager {
      */
     switchTo(conversationId: string, opts?: {
         skipHistoryReplay?: boolean;
+        /**
+         * Jobs whose events the caller ALREADY holds — the transcript-cache
+         * resume. A COMPLETED job named here is neither fetched nor replayed: its
+         * blocks are in the caller's store, and replaying them would draw a
+         * second copy.
+         *
+         * Two limits, both deliberate and both stating what a review proved the
+         * wider contract could not:
+         *
+         *  - **The newest turn page only.** The marks are matched against the page
+         *    of jobs this restore walks, so a mark for a turn OLDER than that page
+         *    is not consulted. The message window (40 rows) and the turn page (10)
+         *    are independent spans, so a cache deeper than one page would need its
+         *    own cursor design — a prompt whose turn is not on the page cannot be
+         *    recognized as held, and would come back as a steer bubble.
+         *  - **Completed jobs only.** A mark for the RUNNING job is ignored (its
+         *    stream starts from the beginning, as it always did). Resuming a live
+         *    turn's stream from a mark would deliver the delta but NOT the prompt
+         *    — a prompt is a message-table row, not a stream event — so the plan
+         *    would still draw a bubble the caller's cache already renders.
+         *
+         * Absent → today's behaviour exactly. A job NOT named is fetched whole, as
+         * now, so a stale mark loses at most one completed turn's skip, never a
+         * turn.
+         */
+        have?: ReadonlyArray<{
+            jobId: string;
+            lastSeq: number;
+        }>;
     }): Promise<void>;
     /**
      * Re-attach to whatever the server says is live for the ACTIVE conversation.

package/dist/index.js

@@ -1492,13 +1492,29 @@ function translateDelta(wire) {
   }
 }
 function translateAgentIdentity(raw) {
+  const source = raw !== null && typeof raw === "object" ? { ...raw } : {};
+  const read = (key) => source[key];
   return {
-    name: raw.name ?? "",
-    displayName: raw.display_name ?? null,
-    avatarUrl: raw.avatar_url ?? null,
-    description: raw.description ?? null
+    name: read("name") ?? "",
+    displayName: read("display_name") ?? null,
+    avatarUrl: read("avatar_url") ?? null,
+    description: read("description") ?? null
   };
 }
+function agentIdentityFromEvent(data) {
+  if ("agent" in data) return translateAgentIdentity(data.agent);
+  return translateAgentIdentity({
+    name: data.agent_name,
+    display_name: data.agent_display_name,
+    avatar_url: data.agent_avatar_url
+  });
+}
+function optionalString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function optionalNumber(value) {
+  return typeof value === "number" ? value : void 0;
+}
 function translateTodoItem(raw) {
   return {
     id: raw.id ?? 0,
@@ -1549,21 +1565,33 @@ function translateCustomEvent(name, data) {
         phase: data.phase ?? null,
         updatedAt: data.updated_at ?? null
       };
+    // Two names for one event: the backend renamed these to `agent_*` (a nested
+    // run is not necessarily a "subagent" in the product's vocabulary) while
+    // older servers still emit `subagent_*`. Both are translated, so a client
+    // works across the rename.
+    case "agent_start":
     case "subagent_start":
       return {
         type: "subagent_start",
-        agent: translateAgentIdentity(
-          data.agent ?? {}
-        ),
-        taskCallId: data.task_call_id ?? null
+        runId: optionalString(data.run_id),
+        agent: agentIdentityFromEvent(data),
+        // `parent_call_id` is the spawn block's call_id — the same key a client
+        // uses to find the tool block whose subtree is this child's work.
+        taskCallId: optionalString(data.parent_call_id) ?? optionalString(data.task_call_id) ?? null
       };
+    case "agent_stop":
     case "subagent_stop":
       return {
         type: "subagent_stop",
-        agent: translateAgentIdentity(
-          data.agent ?? {}
-        ),
-        taskCallId: data.task_call_id ?? null
+        runId: optionalString(data.run_id),
+        agent: agentIdentityFromEvent(data),
+        taskCallId: optionalString(data.parent_call_id) ?? optionalString(data.task_call_id) ?? null,
+        // The child's OWN spend and outcome, which the wire surfaces separately
+        // from the turn totals (`message_stop.usage` folds them in too).
+        stopReason: optionalString(data.stop_reason),
+        inputTokens: optionalNumber(data.input_tokens),
+        outputTokens: optionalNumber(data.output_tokens),
+        durationMs: optionalNumber(data.duration_ms)
       };
     case "context_warning":
       return {
@@ -1813,6 +1841,11 @@ function pathEquals(a, b) {
   }
   return true;
 }
+function frameSeq(frame) {
+  if (typeof frame !== "object" || frame === null) return void 0;
+  if (!("seq" in frame)) return void 0;
+  return frame.seq;
+}
 var ChatSession = class {
   constructor(config, storage) {
     /**
@@ -2123,6 +2156,37 @@ var ChatSession = class {
       }
     }
   }
+  /**
+   * Advance the resume cursor from a frame's `seq` — the position the next
+   * reconnect asks the backend to replay after (`?after=`).
+   *
+   * Two guards, because getting this wrong is silent and expensive: the whole
+   * turn replays over blocks the consumer is already rendering.
+   *
+   *  - **A keepalive is not an event.** The backend sends it as an ordinary
+   *    `data:` frame with `seq: 0` BY DESIGN (``WireKeepalive(seq=0, ts=0.0)``
+   *    — an idle tick, not a position), and it arrives exactly when a turn has
+   *    been quiet for 45 s: the long-tool-run case. Harvesting it rewound the
+   *    cursor to 0, so a reconnect after a blip replayed the turn from its
+   *    start — deltas and all.
+   *  - **The cursor only advances.** `send` and `reconnectToJob` reset it to
+   *    -1 per job, so a new job's `seq: 0` still moves it forward; a frame
+   *    carrying an older (or zero) position cannot move it back.
+   *
+   * The one other frame on the wire with a non-position `seq` is the
+   * subscriber's SYNTHETIC terminal — a back-filled `error` for a job whose
+   * worker died, built without a `seq` so Pydantic's default `0` reaches the
+   * wire. Deliberately not named here: the advance-only rule already ignores it
+   * whenever the client has drained anything (0 never exceeds a real cursor),
+   * and when it is the FIRST frame the pump ends on `sawTerminal` before any
+   * reconnect could use the cursor. Naming it would add a rule that no
+   * reachable input exercises.
+   */
+  harvestResumeCursor(seq, type) {
+    if (type === "keepalive") return;
+    if (typeof seq !== "number") return;
+    if (seq > this.lastSeq) this.lastSeq = seq;
+  }
   async consumeJobStream(request, wire) {
     const job = await this.client.createJob(request);
     if (wire) wire.reached = true;
@@ -2260,18 +2324,14 @@ var ChatSession = class {
         try {
           const data = JSON.parse(raw.data);
           if (typeof data !== "object" || data === null || typeof data.type !== "string") {
-            if (typeof data?.seq === "number") {
-              this.lastSeq = data.seq;
-            }
+            this.harvestResumeCursor(frameSeq(data), void 0);
             if (typeof data === "object" && data !== null && "data" in data && data.data === "[DONE]") {
               sawTerminal = true;
             }
             continue;
           }
           parsed = data;
-          if (typeof data.seq === "number") {
-            this.lastSeq = data.seq;
-          }
+          this.harvestResumeCursor(frameSeq(data), parsed.type);
         } catch {
           continue;
         }
@@ -2500,11 +2560,19 @@ var ChatSession = class {
    * Reconnect to a running job's SSE stream (e.g. after page reload).
    * Replays all events from the beginning and continues live.
    */
-  async reconnectToJob(jobId) {
+  /**
+   * @param afterSeq Resume the job's event stream AFTER this sequence number.
+   *   Omitted (the reconnect default) replays the job from the beginning. A
+   *   caller that holds the job's events up to `afterSeq` — the transcript
+   *   cache — passes it so the backend replays only the delta and then goes
+   *   live; the backend's `?after=` handles a job that already ended by
+   *   back-filling its terminal event.
+   */
+  async reconnectToJob(jobId, afterSeq) {
     if (this.isStreaming) return;
     this.isStreaming = true;
     this.currentJobId = jobId;
-    this.lastSeq = -1;
+    this.lastSeq = afterSeq ?? -1;
     this.submittedToolCallIds.clear();
     this.resetStreamingState();
     const controller = new AbortController();
@@ -2795,7 +2863,10 @@ function planRestore(args) {
     messageId: msgs[i]?.id
   }));
   if (jobs.length === 0) {
-    return userMessages.map((m) => ({
+    const held = new Set(
+      (args.heldMessageIds ?? []).filter((id) => !!id)
+    );
+    return userMessages.filter((m) => !(m.id && held.has(m.id))).map((m) => ({
       kind: "steer",
       content: m.content,
       messageId: m.id
@@ -3074,7 +3145,7 @@ var StreamManager = class _StreamManager {
     }
     let tookOver = false;
     try {
-      await this.restore(conversationId, gen);
+      await this.restore(conversationId, gen, opts?.have);
       tookOver = gen === this.generation;
     } finally {
       const supersededOntoSame = gen !== this.generation && this._activeConversationId === conversationId;
@@ -3292,7 +3363,10 @@ var StreamManager = class _StreamManager {
       ...before ? { before } : {}
     });
   }
-  async restore(conversationId, gen) {
+  async restore(conversationId, gen, have) {
+    const haveByJobId = new Map(
+      (have ?? []).map((h) => [h.jobId, h.lastSeq])
+    );
     const superseded = () => gen !== this.generation;
     if (superseded()) return;
     const turn = this.turnCounter;
@@ -3319,7 +3393,8 @@ var StreamManager = class _StreamManager {
       gen,
       activeJobId,
       turn,
-      jobsRequest
+      jobsRequest,
+      haveByJobId
     ))
       return;
     if (activeJobId) {
@@ -3516,7 +3591,7 @@ var StreamManager = class _StreamManager {
       session.isLoadingEarlierTurns = false;
     }
   }
-  async replayHistory(conversationId, gen, activeJobId, turn, jobsRequest) {
+  async replayHistory(conversationId, gen, activeJobId, turn, jobsRequest, haveByJobId) {
     const stopReplay = () => gen !== this.generation || this.viewTakenOverByLiveTurn() || this.turnStarted(turn);
     let complete = false;
     try {
@@ -3524,7 +3599,7 @@ var StreamManager = class _StreamManager {
       const jobs = page.jobs;
       if (stopReplay()) return false;
       const replayableJobs = jobs.filter(
-        (j) => j.job_id !== activeJobId
+        (j) => j.job_id !== activeJobId && !haveByJobId.has(j.job_id)
       );
       const userMessages = this.session.messages.filter(
         (m) => m.role === "user"
@@ -3558,6 +3633,12 @@ var StreamManager = class _StreamManager {
         // them, silently. Deriving both from `jobs` makes that impossible to
         // get half-right.
         claimedMessageIds: jobs.map((j) => j.message_id),
+        // The prompts whose turn the CALLER holds (see `switchTo`'s `have`).
+        // The walk below is empty for exactly those jobs — which is the
+        // primary cache scenario, a SETTLED conversation whose turns are all
+        // held — and the empty-walk rescue would otherwise re-emit every one of
+        // them as a steer bubble.
+        heldMessageIds: jobs.filter((j) => haveByJobId.has(j.job_id)).map((j) => j.message_id),
         userMessages: userMessages.map((m) => ({
           id: m.id,
           content: m.content