@astralform/js 9.4.1 → 9.6.0

package/dist/index.cjs

@@ -1545,13 +1545,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,
@@ -1602,21 +1618,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 {
@@ -1866,6 +1894,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) {
     /**
@@ -2176,6 +2209,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;
@@ -2313,18 +2377,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;
         }
@@ -2553,11 +2613,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();
@@ -2757,6 +2825,48 @@ var ChatSession = class {
     if (!fresh.length) return;
     this.setMessages([...fresh, ...this.messages]);
   }
+  /**
+   * Re-fetch the NEWEST page of the conversation list and merge it in.
+   *
+   * The list the sidebar renders is seeded once at `connect()` and then only
+   * changed by this client's own actions (create, delete, rename) — so a row's
+   * `activeJobId` is as fresh as that seed, and a job started in ANOTHER tab or
+   * on another device never appears, while one that ended elsewhere stays lit
+   * forever. A caller that refreshes on a trigger (the tab becoming visible, or
+   * a bounded interval while any job is live) keeps the rows honest without a
+   * socket per conversation.
+   *
+   * Merge rules, and why each is what it is:
+   *
+   *  - the server's ORDER wins for the rows it returns: an updated conversation
+   *    moves to its new place, which is the whole point of the call;
+   *  - rows paged in EARLIER (`loadMoreConversations`) are kept — this reads page
+   *    1 only, and dropping the tail would make a refresh silently truncate a
+   *    list the reader has already scrolled;
+   *  - a row the caller MINTED locally and the server does not know yet is kept
+   *    too (it has no server row to be refreshed by);
+   *  - `conversationsGeneration` is bumped, for the same reason `connect()`
+   *    bumps it: a page request already in flight was cut against the old head
+   *    and its offset no longer means what it did.
+   */
+  async refreshConversations() {
+    const page = await this.client.getConversations(CONVERSATION_PAGE_SIZE, 0);
+    const pageIds = new Set(page.map((c) => c.id));
+    const known = new Set(this.conversations.map((c) => c.id));
+    this.conversationsGeneration++;
+    this.conversations = [
+      ...page,
+      // Everything the page did not mention: older pages, and rows that exist
+      // only on this client (a minted conversation the server has not been told
+      // about yet).
+      ...this.conversations.filter((c) => !pageIds.has(c.id))
+    ];
+    for (const c of page) {
+      this.serverConversationIds.add(c.id);
+      known.delete(c.id);
+    }
+    return page;
+  }
   async loadMoreConversations() {
     if (this.isLoadingConversations || !this.hasMoreConversations) return [];
     this.isLoadingConversations = true;
@@ -2848,7 +2958,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
@@ -3127,7 +3240,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;
@@ -3345,7 +3458,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;
@@ -3372,7 +3488,8 @@ var StreamManager = class _StreamManager {
       gen,
       activeJobId,
       turn,
-      jobsRequest
+      jobsRequest,
+      haveByJobId
     ))
       return;
     if (activeJobId) {
@@ -3569,7 +3686,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 {
@@ -3577,7 +3694,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"
@@ -3611,6 +3728,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