npm - shraga - Versions diffs - 0.1.68 → 0.1.70 - Mend

shraga 0.1.68 → 0.1.70

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/client/assets/{index-6SI-XJ2-.js → index-BHcdo8Ga.js} +195 -195
package/dist/client/index.html +1 -1
package/package.json +1 -1
package/src/client/components/MachineStats.tsx +20 -4
package/src/server/claude-usage.ts +36 -1
package/src/server/para/feature.ts +17 -6
package/src/server/para/streamer.ts +182 -16

package/dist/client/index.html CHANGED Viewed

@@ -13,7 +13,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-6SI-XJ2-.js"></script>
+    <script type="module" crossorigin src="/assets/index-BHcdo8Ga.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-uvYJNXVj.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.68",
+  "version": "0.1.70",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/client/components/MachineStats.tsx CHANGED Viewed

@@ -16,7 +16,10 @@ export interface UsageLimit {
 export interface Usage { subscriptionType: string | null; limits: UsageLimit[] }
 const WINDOW = 120;
-const USAGE_POLL_MS = 60_000;
+// The upstream usage endpoint rate-limits hard and the numbers move slowly, so poll lazily: every
+// 5 min, and ONLY while this tab is visible. A wall of forgotten tabs was what kept the server in a
+// permanent 429 penalty box.
+const USAGE_POLL_MS = 300_000;
 interface Props {
   socket: AgentSocket | null;
@@ -69,10 +72,12 @@ function ClaudeUsageMetric({ getToken }: { getToken: () => Promise<string | null
   useEffect(() => {
     let alive = true;
+    let last = 0;
     const poll = async () => {
       try {
         const t = await getToken();
         if (!t) return;
+        last = Date.now();
         const r = await fetch('/api/claude-usage', { headers: { Authorization: `Bearer ${t}` } });
         if (!alive) return;
         // 204 = not a subscription deployment. Anything non-OK = fail closed, same outcome.
@@ -85,9 +90,20 @@ function ClaudeUsageMetric({ getToken }: { getToken: () => Promise<string | null
         if (alive) setUsage(null);
       }
     };
-    void poll();
-    const id = setInterval(poll, USAGE_POLL_MS);
-    return () => { alive = false; clearInterval(id); };
+    // A hidden tab is nobody watching: skip the tick entirely rather than paying an upstream call.
+    const tick = () => { if (document.visibilityState === 'visible') void poll(); };
+    // Coming back to the tab shows a stale gauge otherwise — refresh only if the interval was missed.
+    const onVisible = () => {
+      if (document.visibilityState === 'visible' && Date.now() - last >= USAGE_POLL_MS) void poll();
+    };
+    tick();
+    const id = setInterval(tick, USAGE_POLL_MS);
+    document.addEventListener('visibilitychange', onVisible);
+    return () => {
+      alive = false;
+      clearInterval(id);
+      document.removeEventListener('visibilitychange', onVisible);
+    };
   }, [getToken]);
   return <UsageMetric usage={usage} />;

package/src/server/claude-usage.ts CHANGED Viewed

@@ -41,8 +41,12 @@ export class ClaudeUsageOptions {
    *  deduped separately onto one in-flight request, so a reload storm or a wall of open tabs costs at
    *  most one upstream call per window — this endpoint answers 429 aggressively. Failures are cached
    *  on the same terms, so a 403/API-key box does not retry on every client poll. */
-  ttlMs = 60_000;
+  ttlMs = 300_000;
   timeoutMs = 8_000;
+  /** A 429 is not a transient blip here: retrying it on the ordinary TTL is what keeps a box wedged in
+   *  the penalty box all day (25 straight 429s on prod). Each consecutive 429 climbs this ladder and a
+   *  success drops back to the first rung; a `Retry-After` header wins over the rung when it is longer. */
+  rateLimitBackoffMs = [60_000, 300_000, 900_000, 1_800_000];
   /** macOS stores Claude Code's OAuth credentials in the login Keychain and writes NO credentials
    *  file, so on darwin an absent file is not proof of an API-key deployment — we look there second.
    *  Linux keeps the file as the only source; we never shell out there. */
@@ -79,6 +83,9 @@ export class ClaudeUsageReader {
    *  Without this the TTL is useless against a stampede: the cache is only written once the request
    *  RESOLVES, so N simultaneous callers all miss and all hit upstream. */
   private inflight: Promise<ClaudeUsage | null> | null = null;
+  /** While set in the future, `get()` answers null WITHOUT touching upstream — see rateLimitBackoffMs. */
+  private cooldownUntil = 0;
+  private rateLimitStreak = 0;
   public constructor(options?: Partial<ClaudeUsageOptions>) {
     this.options = { ...new ClaudeUsageOptions(), ...options };
@@ -87,6 +94,7 @@ export class ClaudeUsageReader {
   /** null => this box is not on a Claude subscription, or we could not prove that it is. */
   async get(): Promise<ClaudeUsage | null> {
     const now = Date.now();
+    if (now < this.cooldownUntil) return null;
     if (this.cache && now - this.cache.at < this.options.ttlMs) return this.cache.value;
     if (this.inflight) return this.inflight;
     // Clear inflight before the value is handed out, so a rejection can never wedge the reader:
@@ -113,6 +121,10 @@ export class ClaudeUsageReader {
         },
         signal: AbortSignal.timeout(this.options.timeoutMs),
       });
+      if (res.status === 429) {
+        this.enterCooldown(res.headers.get('retry-after'));
+        return null;
+      }
       if (!res.ok) {
         console.warn(`${TAG} usage endpoint returned ${res.status}; hiding widget`);
         return null;
@@ -123,6 +135,7 @@ export class ClaudeUsageReader {
         console.warn(`${TAG} usage response carried no limits[]; hiding widget`);
         return null;
       }
+      this.rateLimitStreak = 0;
       return { subscriptionType: creds.subscriptionType, limits };
     } catch (err) {
       console.warn(`${TAG} usage lookup failed:`, (err as Error).message);
@@ -130,6 +143,18 @@ export class ClaudeUsageReader {
     }
   }
+  /** Climb the backoff ladder one rung per consecutive 429, capped at the last rung. `Retry-After`
+   *  (seconds, or an HTTP-date) only ever EXTENDS the wait — never shortens the rung we earned. */
+  private enterCooldown(retryAfter: string | null) {
+    const ladder = this.options.rateLimitBackoffMs;
+    const rung = ladder[Math.min(this.rateLimitStreak, ladder.length - 1)] ?? 60_000;
+    this.rateLimitStreak++;
+    const hinted = parseRetryAfter(retryAfter);
+    const waitMs = Math.max(rung, hinted ?? 0);
+    this.cooldownUntil = Date.now() + waitMs;
+    console.warn(`${TAG} usage endpoint returned 429; hiding widget and backing off ${Math.round(waitMs / 1000)}s`);
+  }
   /** Re-read per poll from whichever source holds them — the token lives ~8h and Claude Code
    *  refreshes it in place, so nothing here may be cached in a field. File first, Keychain second. */
   private async readCredentials(): Promise<{ accessToken: string; subscriptionType: string | null } | null> {
@@ -183,6 +208,16 @@ function parseCredentials(raw: string, source: string): { accessToken: string; s
   return { accessToken: oauth.accessToken, subscriptionType: oauth.subscriptionType ?? null };
 }
+/** `Retry-After` is either delta-seconds or an HTTP-date. Anything unparseable => no hint. */
+function parseRetryAfter(raw: string | null): number | null {
+  if (!raw) return null;
+  const secs = Number(raw.trim());
+  if (Number.isFinite(secs) && secs >= 0) return secs * 1000;
+  const at = Date.parse(raw);
+  if (!Number.isNaN(at)) return Math.max(0, at - Date.now());
+  return null;
+}
 function toLimit(l: any): ClaudeUsageLimit | null {
   if (!l || typeof l.percent !== 'number' || !Number.isFinite(l.percent)) return null;
   return {

package/src/server/para/feature.ts CHANGED Viewed

@@ -86,10 +86,10 @@ function rememberLink(link: Link): void {
  *  be left watching a "typing…" placeholder that will never resolve. */
 async function runParaTurn(args: {
   callback: ParaCallback; convId: string; msgId: string; sessionId: string; prompt: string;
-  uid: string; userEmail: string;
+  uid: string; userEmail: string; sendSegments: boolean;
 }): Promise<void> {
-  const { callback, convId, msgId, sessionId, prompt, uid, userEmail } = args;
-  const streamer = new ParaStreamer({ callback, convId, msgId });
+  const { callback, convId, msgId, sessionId, prompt, uid, userEmail, sendSegments } = args;
+  const streamer = new ParaStreamer({ callback, convId, msgId, sendSegments });
   const abortController = new AbortController();
   // Lock origin is 'api': the union in sessions.ts is a closed set ('web'|'slack'|'scheduler'|
@@ -119,9 +119,14 @@ async function runParaTurn(args: {
       else if (ev.type === 'tool_use') {
         if (text) { blocks.push({ type: 'text', text }); text = ''; }
         blocks.push({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
-        streamer.feed({ type: 'tool_use', tool: ev.tool });
+        streamer.feed({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
+      }
+      else if (ev.type === 'tool_result') {
+        blocks.push({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output });
+        // The `running` → `completed`/`error` transition. Fed unconditionally; the streamer ignores
+        // it unless the receiver negotiated segments.
+        streamer.feed({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output, isError: ev.isError });
       }
-      else if (ev.type === 'tool_result') blocks.push({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output });
       else if (ev.type === 'done') break;
       else if (ev.type === 'error') {
         if (text) { blocks.push({ type: 'text', text }); text = ''; }
@@ -188,9 +193,14 @@ export const paraFeature: ServerFeature = {
       const caller = bearer ? validateApiKey(bearer) : null;
       if (!caller) return void res.status(401).json({ error: 'unauthorized' });
-      const { connId, convId, sessionId, msgId, prompt, callback } = req.body as {
+      const { connId, convId, sessionId, msgId, prompt, callback, accepts } = req.body as {
         connId?: string; convId?: string; sessionId?: string; msgId?: string; prompt?: string;
         callback?: { url?: string; secret?: string };
+        /** Receiver capability negotiation. `'segments'` means "I can store and render structured
+         *  tool segments" — see `ParaStreamerOptions.sendSegments`. ABSENT means no: a para-li that
+         *  predates this field, and a lane (groups) that deliberately declines, both fall back to
+         *  the flattened `_🔧 Tool_` markers in the text. */
+        accepts?: unknown;
       };
       if (!connId || !convId || !msgId || !prompt) return void res.status(400).json({ error: 'connId, convId, msgId and prompt are required' });
       if (!callback?.url || !callback?.secret) return void res.status(400).json({ error: 'callback.url and callback.secret are required' });
@@ -210,6 +220,7 @@ export const paraFeature: ServerFeature = {
       void runParaTurn({
         callback: cb, convId, msgId, sessionId: sessionId || convId, prompt,
         uid: caller.uid, userEmail: caller.email,
+        sendSegments: Array.isArray(accepts) && accepts.includes('segments'),
       });
     });

package/src/server/para/streamer.ts CHANGED Viewed

@@ -34,8 +34,24 @@ export interface ParaStreamerOptions {
   msgId?: string;
   flushInterval?: number;
   flushThreshold?: number;
-  /** Show a transient inline marker per tool call, as the Slack streamer does. Default on. */
+  /** Show a transient inline marker per tool call, as the Slack streamer does. Default on.
+   *  Ignored when `sendSegments` is on — see `ParaStreamerOptions.sendSegments`. */
   toolMarkers?: boolean;
+  /**
+   * Emit STRUCTURED segments (`text` + `tool`) alongside the accumulated text.
+   *
+   * OFF BY DEFAULT, AND THAT IS THE POINT. This is a negotiated capability, not a preference: the
+   * receiver tells us per turn (`accepts: ['segments']` on the turn request) whether it can store
+   * and render them. A receiver that cannot gets the flattened `_🔧 Tool_` markers in the text, as
+   * it always did. So the fallback is EXPLICIT — one flag, decided by the receiver — instead of
+   * "the field is there, hopefully they ignore it".
+   *
+   * The two representations are mutually exclusive on purpose. Sending both would double-render on
+   * a receiver that shows segments AND falls back to text for a preview.
+   */
+  sendSegments?: boolean;
+  /** Per-POST wall clock. See `POST_TIMEOUT_MS`. Overridable for tests. */
+  postTimeout?: number;
 }
 /** Signature contract, mirrored byte-for-byte in para-li's `lib/agent-conn.ts#signPayload`.
@@ -58,17 +74,101 @@ export function signPara(secret: string, connId: string, deliveryId: string, ts:
   return 'v1=' + createHmac('sha256', secret).update(`${connId}.${deliveryId}.${ts}.${rawBody}`).digest('hex');
 }
-/** One signed POST. Returns false on any non-2xx or network error, having logged it — the caller
- *  keeps streaming rather than aborting the agent's turn over a transport hiccup. */
-export async function postPara(cb: ParaCallback, payload: object): Promise<boolean> {
+// ── Structured segments ──────────────────────────────────────────────────────
+//
+// SHAPE-COMPATIBLE WITH para-li's OWN `MessageSegment`/`ToolCallInfo` (`lib/para-relay.ts`), which
+// its `ConversationChannel` already renders as collapsible tool pills. This is a deliberate reuse:
+// the external-agent lane emits the SAME shape the Para's own turns do, so no second renderer, no
+// second row field, and no second thing to keep in sync. Duplicated here rather than imported for
+// the same reason `signPara` is — the two repos publish separately.
+export interface ToolCallInfo {
+  id: string;
+  tool: string;
+  status: 'running' | 'completed' | 'error';
+  args?: Record<string, unknown>;
+  result?: string;
+}
+export type MessageSegment =
+  | { type: 'text'; content: string }
+  | { type: 'tool'; tool: ToolCallInfo };
+/**
+ * SIZE DISCIPLINE. A `Read` of a big file or a chatty `Bash` produces tool input/output measured in
+ * hundreds of KB, and every flush re-sends the WHOLE accumulated state (see ACCUMULATE, DON'T
+ * APPEND at the top). Unclamped, one such call would be re-uploaded on every subsequent delta for
+ * the rest of the turn and then parked in a database row forever.
+ *
+ * The caps are chosen against what the pill actually shows: para-li's `ToolPill` renders args as
+ * one JSON line and slices the result at 500 chars, so anything past a few KB is invisible detail
+ * that still costs bandwidth and storage. Truncation is MARKED with the true length — a silently
+ * shortened `Bash` output is a lie the reader cannot detect.
+ *
+ * These are the SENDER's caps. para-li re-clamps on ingest (`parseSegments`) because a cap that
+ * only exists on the sender is not a cap.
+ */
+export const MAX_TOOL_ARGS_CHARS = 2_000;
+export const MAX_TOOL_RESULT_CHARS = 4_000;
+/** Beyond this many tool calls in one turn, later calls stop being recorded as segments (the text
+ *  reply is unaffected). A 100-call turn is already unreadable as pills; the cap is what stops a
+ *  runaway loop from growing the row without bound. */
+export const MAX_TOOL_SEGMENTS = 100;
+/** Truncate with an honest marker naming the TRUE length. */
+export function clampText(s: string, cap: number): string {
+  return s.length <= cap ? s : `${s.slice(0, cap)}… [truncated, ${s.length} chars total]`;
+}
+/** Clamp a tool's input to `MAX_TOOL_ARGS_CHARS` across all its values, preserving the key
+ *  structure (that is what makes the pill readable) and marking every truncation. */
+export function clampArgs(input: unknown): Record<string, unknown> | undefined {
+  if (input === undefined || input === null) return undefined;
+  if (typeof input !== 'object' || Array.isArray(input)) {
+    return { value: clampText(String(input), MAX_TOOL_ARGS_CHARS) };
+  }
+  const out: Record<string, unknown> = {};
+  let budget = MAX_TOOL_ARGS_CHARS;
+  for (const [k, v] of Object.entries(input as Record<string, unknown>)) {
+    if (budget <= 0) { out['…'] = 'more arguments omitted'; break; }
+    const s = typeof v === 'string' ? v : (JSON.stringify(v) ?? String(v));
+    if (s.length > budget) out[k] = clampText(s, budget);
+    else out[k] = v;
+    budget -= Math.min(s.length, budget);
+  }
+  return out;
+}
+/**
+ * Wall clock on ONE delivery. Mirrors the 20s AbortController on para-li's own `dispatchAgentTurn`,
+ * which is the other half of this lane.
+ *
+ * WHY A TIMEOUT IS LOAD-BEARING HERE AND NOT A NICETY: flushes are serialized through `flushChain`,
+ * and `finish()` awaits that chain. `fetch` has no default timeout, so ONE POST that connects and
+ * then never answers (a stalled proxy, a receiver wedged mid-handler, a half-open socket a dead NAT
+ * entry never RSTs) blocks every later delta AND the `final` — for the process's lifetime. The
+ * visible symptom is not an error: the reply freezes mid-sentence, no `final` ever lands, and
+ * nothing is logged, because the failure never returns. A bounded POST turns that permanent wedge
+ * into one logged, skipped delta and a `final` that still arrives.
+ */
+export const POST_TIMEOUT_MS = 20_000;
+/** One signed POST. Returns false on any non-2xx, timeout, or network error, having logged it — the
+ *  caller keeps streaming rather than aborting the agent's turn over a transport hiccup. */
+export async function postPara(cb: ParaCallback, payload: object, timeoutMs: number = POST_TIMEOUT_MS): Promise<boolean> {
   const raw = JSON.stringify(payload);
   const ts = Date.now();
   // Per-DELIVERY id, not per-turn: para-li's replay guard dedupes on this, so a shared id across
   // the deltas of one turn would drop every delta after the first. Minted here so the exact same
   // value goes into the header AND the signature — they must not be able to diverge.
   const delivery = randomUUID();
+  // Abort on a timer rather than `AbortSignal.timeout`: the same shape para-li uses, and the timer
+  // is cleared in `finally` so a fast POST leaves nothing pending on the event loop.
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
   try {
     const res = await fetch(cb.url, {
+      signal: ac.signal,
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
@@ -85,8 +185,11 @@ export async function postPara(cb: ParaCallback, payload: object): Promise<boole
     }
     return true;
   } catch (err) {
-    console.warn('[para-streamer] delivery failed:', (err as Error).message);
+    const e = err as Error;
+    console.warn('[para-streamer] delivery failed:', e.name === 'AbortError' ? `no response within ${timeoutMs}ms` : e.message);
     return false;
+  } finally {
+    clearTimeout(timer);
   }
 }
@@ -97,35 +200,90 @@ export class ParaStreamer {
   private flushChain: Promise<void> = Promise.resolve();
   private aborted = false;
   private afterTool = false;
+  /** Structured mirror of the turn. Empty unless `sendSegments`. */
+  private segments: MessageSegment[] = [];
+  /** toolUseId → the live `ToolCallInfo` inside `segments`, so a `tool_result` can flip the status
+   *  of the call it belongs to rather than of whichever ran last. */
+  private readonly toolById = new Map<string, ToolCallInfo>();
+  private toolCount = 0;
   private readonly flushInterval: number;
   private readonly flushThreshold: number;
   private readonly toolMarkers: boolean;
+  private readonly sendSegments: boolean;
+  private readonly postTimeout: number;
   constructor(private readonly opts: ParaStreamerOptions) {
     this.flushInterval = opts.flushInterval ?? 300;
     this.flushThreshold = opts.flushThreshold ?? 30;
-    this.toolMarkers = opts.toolMarkers ?? true;
+    this.sendSegments = opts.sendSegments ?? false;
+    // The marker is the FALLBACK, so it is off exactly when segments are on. Not "both, harmless" —
+    // a receiver that renders segments and also derives a preview from the text would show the
+    // markers in the preview of a reply whose body has real pills.
+    this.toolMarkers = this.sendSegments ? false : (opts.toolMarkers ?? true);
+    this.postTimeout = opts.postTimeout ?? POST_TIMEOUT_MS;
   }
-  feed(ev: { type: string; text?: string; tool?: string }): void {
+  feed(ev: { type: string; text?: string; tool?: string; toolUseId?: string; input?: unknown; output?: string; isError?: boolean }): void {
     if (this.aborted || !this.opts.msgId) return;
     if (ev.type === 'text_delta' && ev.text) {
       if (this.afterTool) { this.fullText += '\n'; this.afterTool = false; }
       this.buffer += ev.text;
       this.fullText += ev.text;
+      this.appendSegmentText(ev.text);
       if (this.buffer.length >= this.flushThreshold) this.enqueueFlush();
       else this.scheduleTimer();
-    } else if (ev.type === 'tool_use' && ev.tool && this.toolMarkers) {
-      // In-band, transient: `finish()` sends the clean final text, which replaces the row wholesale
-      // (para-li writes the whole row), so the marker disappears on its own.
-      this.afterTool = true;
-      this.fullText += `\n\n_🔧 ${ev.tool.slice(0, 200)}_\n\n`;
+    } else if (ev.type === 'tool_use' && ev.tool) {
+      if (this.sendSegments) {
+        // A tool call is progress the reader wants IMMEDIATELY, at `running` — that is the whole
+        // point of the pill. So it flushes rather than waiting for the text threshold.
+        if (this.toolCount < MAX_TOOL_SEGMENTS) {
+          const id = ev.toolUseId || `tool_${this.toolCount}`;
+          const info: ToolCallInfo = { id, tool: ev.tool.slice(0, 200), status: 'running', ...(clampArgs(ev.input) ? { args: clampArgs(ev.input) } : {}) };
+          this.toolById.set(id, info);
+          this.segments.push({ type: 'tool', tool: info });
+        }
+        this.toolCount++;
+        this.enqueueFlush();
+      } else if (this.toolMarkers) {
+        // In-band, transient: `finish()` sends the clean final text, which replaces the row wholesale
+        // (para-li writes the whole row), so the marker disappears on its own.
+        this.afterTool = true;
+        this.fullText += `\n\n_🔧 ${ev.tool.slice(0, 200)}_\n\n`;
+        this.enqueueFlush();
+      }
+    } else if (ev.type === 'tool_result' && this.sendSegments && ev.toolUseId) {
+      const info = this.toolById.get(ev.toolUseId);
+      // A result for a call past MAX_TOOL_SEGMENTS (or for one we never saw) has nothing to settle;
+      // dropping it is correct — inventing a segment for it would put the pill out of order.
+      if (!info) return;
+      info.status = ev.isError ? 'error' : 'completed';
+      if (ev.output) info.result = clampText(ev.output, MAX_TOOL_RESULT_CHARS);
       this.enqueueFlush();
     }
   }
+  /** Grow the trailing text segment, or start one. Mirrors `buildSegmentHost` in para-li's own
+   *  `lib/para-agent.ts` — consecutive text stays ONE segment, so the pills sit between paragraphs
+   *  instead of shredding the answer into a segment per delta. */
+  private appendSegmentText(text: string): void {
+    if (!this.sendSegments) return;
+    const last = this.segments[this.segments.length - 1];
+    if (last && last.type === 'text') last.content += text;
+    else this.segments.push({ type: 'text', content: text });
+  }
+  /** A deep copy with empty text segments dropped. Deep because `toolById` holds live references
+   *  into `segments`: a flush snapshot that shared them would be MUTATED by a later `tool_result`
+   *  while its POST was still in flight, so an in-order pair of deltas could show the same call as
+   *  `completed` and then `running`. */
+  private segmentSnapshot(): MessageSegment[] {
+    return this.segments
+      .filter((s) => s.type === 'tool' || s.content.trim().length > 0)
+      .map((s) => (s.type === 'tool' ? { type: 'tool' as const, tool: { ...s.tool } } : { type: 'text' as const, content: s.content }));
+  }
   /** Settle the row with the final text. Returns the text actually sent. */
   async finish(): Promise<string> {
     this.clearTimer();
@@ -133,7 +291,10 @@ export class ParaStreamer {
     await this.flushChain;
     if (this.aborted || !this.opts.msgId) return this.fullText;
     const text = this.fullText.trim() || '(no output)';
-    await postPara(this.opts.callback, { type: 'final', convId: this.opts.convId, msgId: this.opts.msgId, text });
+    await postPara(this.opts.callback, {
+      type: 'final', convId: this.opts.convId, msgId: this.opts.msgId, text,
+      ...(this.sendSegments ? { segments: this.segmentSnapshot() } : {}),
+    }, this.postTimeout);
     return text;
   }
@@ -143,18 +304,23 @@ export class ParaStreamer {
     this.clearTimer();
     await this.flushChain;
     if (!this.opts.msgId) return;
-    await postPara(this.opts.callback, { type: 'error', convId: this.opts.convId, msgId: this.opts.msgId, message });
+    await postPara(this.opts.callback, { type: 'error', convId: this.opts.convId, msgId: this.opts.msgId, message }, this.postTimeout);
   }
   private enqueueFlush(): void {
     this.clearTimer();
-    if (!this.fullText) return;
+    // `segments` matters here too: a turn that opens with a tool call has produced NO text yet, and
+    // the old guard would have swallowed that flush — so the first pill would not appear until the
+    // model started talking, and, worse, the delta that bumps para-li's stall watchdog
+    // (`lastActivityAt`) would never be sent for a long tool-only stretch.
+    if (!this.fullText && !this.segments.length) return;
     this.buffer = '';
     const snapshot = this.fullText;
+    const segs = this.sendSegments ? this.segmentSnapshot() : null;
     // Serialized: a later, longer snapshot must never be overtaken by an earlier one, or the row
     // visibly rewinds mid-stream.
     this.flushChain = this.flushChain
-      .then(async () => { await postPara(this.opts.callback, { type: 'delta', convId: this.opts.convId, msgId: this.opts.msgId, text: snapshot }); })
+      .then(async () => { await postPara(this.opts.callback, { type: 'delta', convId: this.opts.convId, msgId: this.opts.msgId, text: snapshot, ...(segs ? { segments: segs } : {}) }, this.postTimeout); })
       .catch((err) => console.warn('[para-streamer] flush error:', (err as Error).message));
   }