@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/stream-trouble.ts

@@ -0,0 +1,154 @@
+// Stream trouble: what the store does when the live stream misbehaves —
+// a wire error, a terminal-free quiet close, the member's retry, and the
+// post-restart reconnect that waits for a restarted workflow to reclaim
+// its parked turn.
+
+import { streamFailureClassOf } from "../contract/telemetry.js";
+import type { ServingAssistantTurn } from "../contract/threads.js";
+import { getAssistantThread } from "../transport/serving-api.js";
+import {
+  adoptRefreshedDetail,
+  refreshThreads,
+} from "./conversation-adoption.js";
+import { settlesFor } from "./conversation-refresh.js";
+import { publishStore } from "./conversation-publish.js";
+import type { AssistantConversationStore } from "./conversation-store.js";
+import { SETTLE_REFRESH_DELAY_MS } from "./settle-refresh.js";
+
+// How many SETTLE_REFRESH_DELAY_MS beats the post-restart reconnect will
+// wait for the restarted workflow to reclaim its parked turn before
+// reconnecting regardless.
+const RESTART_RECLAIM_PROBES = 10;
+
+export function handleStreamErrorFromStore(
+  store: AssistantConversationStore,
+  error: Error,
+): void {
+  store._streamInterrupted = true;
+  publishStore(store);
+  // The failure, classified for the host's analytics: where the
+  // wire died and the cursors that locate it. Deliberately no run content.
+  // sawBodyBytes' premise: the scanner sets it on the first SSE body chunk
+  // of a connection — keepalive comments included, so a live-but-idle
+  // resumed stream still reads as mid-stream when the edge cuts it — and
+  // headers alone never set it. The store connects ONCE per epoch (a fresh
+  // scanner per connection), so the flag is a fact about THIS connection.
+  store.deps.onTelemetry({
+    name: "assistant_stream_failed",
+    properties: {
+      failure_class: streamFailureClassOf(error, {
+        sawBodyBytes: store._epoch?.agent.sawBodyBytes ?? false,
+      }),
+      status: _httpStatusOf(error),
+      thread_id: store._active?.thread.id ?? null,
+      resume_cursor: store._active?.resume.snapshot?.afterId ?? null,
+      last_committed_sse_id: store._epoch?.agent.resumeCursor ?? null,
+    },
+  });
+  // Re-read the truth: a RUN_ERROR that settled the turn failed shows
+  // up as busy=false + the turn's failure sentence, which suppresses
+  // the interruption banner in favor of the honest failure notice.
+  store._scheduleSettleRefresh();
+  store.deps.reportError(error);
+}
+
+// A stream that ends without a terminal event is either a parked turn
+// (the designed quiet close) or a dropped connection wearing the
+// same wire shape — REST is the authority. The re-read alone is most of
+// the answer: it unlocks the composer after a live park (busy rides
+// thread.busy, and parking released the thread pointer) and renders any
+// settled outcome honestly (turnFailure for failed; superseded stays
+// banner-free — its receipt row is the honest rendering). Only a turn
+// the workflow still owns means the connection died under us.
+export function handleStreamClosedQuietlyFromStore(
+  store: AssistantConversationStore,
+  stillStreaming: () => boolean,
+): void {
+  const active = store._active;
+  if (active === null) {
+    return;
+  }
+  getAssistantThread(store.deps.session, active.thread.id)
+    .then((detail) => {
+      adoptRefreshedDetail(store, detail);
+      // The detail is stale once the visitor moves to another thread
+      // mid-flight — its verdict must not raise a banner over the new
+      // one. stillStreaming is read after the round-trip on purpose: a
+      // detach-and-reconnect (StrictMode's double connect) ends the
+      // first run terminal-free, but by now the replacement is
+      // running and no banner belongs.
+      if (
+        store._active?.thread.id === detail.thread.id &&
+        _workflowStillOwnsTurn(detail.turns.at(-1)?.status) &&
+        !stillStreaming()
+      ) {
+        store._streamInterrupted = true;
+        publishStore(store);
+      }
+      void refreshThreads(store);
+    })
+    .catch(() => {
+      // A blip here self-heals like every other refresh: the
+      // visitor's next action re-reads the thread.
+    });
+}
+
+export function retryStreamFromStore(store: AssistantConversationStore): void {
+  store._streamInterrupted = false;
+  store._automaticReconnects = 0;
+  store._reconnectNonce += 1;
+  publishStore(store);
+}
+
+// Answering a parked card restarts its workflow, and only a fresh
+// connection can tail the restarted run — but the reconnect must not race
+// the workflow's reclaim (parked → working is a worker pickup after the
+// endpoint returns): a stream connected while the turn still reads parked
+// closes quietly again and freezes on the stale pause. So wait for REST to
+// show the turn moving, bounded — the restart is durably started, and on
+// exhaustion the reconnect happens anyway (full replay is always correct).
+export function handleWorkflowRestartedFromStore(
+  store: AssistantConversationStore,
+): void {
+  const active = store._active;
+  if (active === null) {
+    return;
+  }
+  const threadId = active.thread.id;
+  void (async () => {
+    for (let probe = 0; probe < RESTART_RECLAIM_PROBES; probe += 1) {
+      await settlesFor(SETTLE_REFRESH_DELAY_MS);
+      if (store._disposed || store._active?.thread.id !== threadId) {
+        return;
+      }
+      try {
+        const detail = await getAssistantThread(store.deps.session, threadId);
+        if (detail.turns.at(-1)?.status !== "parked") {
+          break;
+        }
+      } catch {
+        // Keep probing; the reconnect below is the recovery either way.
+      }
+    }
+    if (!store._disposed && store._active?.thread.id === threadId) {
+      store.retryStream();
+    }
+  })();
+}
+
+// The statuses a live workflow still owns; parked is deliberately not one
+// of them (the workflow exited, the turn waits for its late answer).
+function _workflowStillOwnsTurn(
+  status: ServingAssistantTurn["status"] | undefined,
+): boolean {
+  return (
+    status === "queued" || status === "working" || status === "awaiting_input"
+  );
+}
+
+// runHttpRequest stamps the response status on a non-2xx error; a
+// pre-response failure carries none.
+function _httpStatusOf(error: Error): number | null {
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" ? status : null;
+}

package/src/core/subagent-brief.ts

@@ -0,0 +1,71 @@
+// A child's opening brief as its transcript's first user row. The child's
+// log carries only the assistant's side (the parent's user side comes
+// from turn rows); the brief's full text lives on the parent's
+// dispatch_subagent call, joined to the child by its receipt.
+
+import type { Message } from "@ag-ui/core";
+
+import {
+  DISPATCH_SUBAGENT_TOOL_NAME,
+  dispatchedTaskOf,
+  dispatchReceiptOf,
+} from "./subagent-rows.js";
+
+/** The task the parent dispatched to this child, or null while the
+ *  parent's call or its receipt has not landed. */
+export function openingBriefOf(
+  parentMessages: readonly Message[],
+  childSessionId: string,
+): string | null {
+  const results = _toolResultsByCallIdOf(parentMessages);
+  for (const message of parentMessages) {
+    if (message.role !== "assistant") {
+      continue;
+    }
+    for (const call of message.toolCalls ?? []) {
+      if (_isDispatchOfChild(call, results.get(call.id), childSessionId)) {
+        const task = dispatchedTaskOf(call.function.arguments);
+        return task === null || task.trim() === "" ? null : task;
+      }
+    }
+  }
+  return null;
+}
+
+/** The child's messages led by its brief, when there is one. */
+export function withOpeningBrief(
+  childMessages: readonly Message[],
+  brief: string | null,
+  childSessionId: string,
+): readonly Message[] {
+  if (brief === null) {
+    return childMessages;
+  }
+  return [
+    { id: `brief:${childSessionId}`, role: "user", content: brief },
+    ...childMessages,
+  ];
+}
+
+function _toolResultsByCallIdOf(
+  messages: readonly Message[],
+): ReadonlyMap<string, string> {
+  const results = new Map<string, string>();
+  for (const message of messages) {
+    if (message.role === "tool" && typeof message.content === "string") {
+      results.set(message.toolCallId, message.content);
+    }
+  }
+  return results;
+}
+
+function _isDispatchOfChild(
+  call: { function: { name: string } },
+  result: string | undefined,
+  childSessionId: string,
+): boolean {
+  return (
+    call.function.name === DISPATCH_SUBAGENT_TOOL_NAME &&
+    dispatchReceiptOf(result)?.childSessionId === childSessionId
+  );
+}

package/src/core/subagent-delivery-anchors.ts

@@ -0,0 +1,176 @@
+// The delivery-receipt anchor model, pure of React: a
+// machine-started delivery turn opens its run with a
+// subagent_results_delivered marker naming the settled dispatches it
+// pushes. The recorder anchors each marker to the run's first message,
+// the transcript renders a quiet divider before it, and the resume
+// store holds the anchors across remounts (a snapshot-seeded reconnect
+// replays only past the cursor, so historical receipts never re-arrive
+// on the wire).
+
+import type { AgentSubscriber } from "@ag-ui/client";
+
+import {
+  SUBAGENT_RESULTS_DELIVERED_EVENT_NAME,
+  type SubagentResultsDeliveredPayload,
+} from "../contract/events.js";
+
+// The label is the dispatch's bounded excerpt today, but the narrower
+// distrusts the wire by contract; a runaway string is retained capped,
+// never unbounded.
+const LABEL_MAX_CHARS = 200;
+
+export interface DeliveredResult {
+  ordinal: number;
+  label: string;
+  succeeded: boolean;
+}
+
+export const EMPTY_SUBAGENT_DELIVERY_ANCHORS: ReadonlyMap<
+  string,
+  DeliveredResult[]
+> = new Map();
+
+/**
+ * Narrow a subagent_results_delivered CUSTOM event's wire value (any by
+ * contract). Entries without a numeric ordinal are dropped; a missing
+ * label degrades to "" and a missing succeeded to true (the wire's own
+ * default). Null when nothing valid survives — the contract's "clients
+ * MUST ignore events and fields they do not recognize".
+ */
+export function deliveredResultsOf(value: unknown): DeliveredResult[] | null {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const payload = value as Partial<SubagentResultsDeliveredPayload>;
+  if (!Array.isArray(payload.results)) {
+    return null;
+  }
+  const results: DeliveredResult[] = [];
+  for (const entry of payload.results as unknown[]) {
+    if (typeof entry !== "object" || entry === null) {
+      continue;
+    }
+    const result = entry as Record<string, unknown>;
+    if (typeof result.ordinal !== "number") {
+      continue;
+    }
+    results.push({
+      ordinal: result.ordinal,
+      label:
+        typeof result.label === "string"
+          ? result.label.slice(0, LABEL_MAX_CHARS)
+          : "",
+      succeeded: result.succeeded !== false,
+    });
+  }
+  return results.length > 0 ? results : null;
+}
+
+/**
+ * First anchor wins, ever: the marker is emitted at most once per
+ * delivery run, so a second anchoring under the same message id is a
+ * replay's re-delivery, never new information.
+ */
+export function withSubagentDeliveryAnchored(
+  previous: ReadonlyMap<string, DeliveredResult[]>,
+  messageId: string,
+  results: DeliveredResult[],
+): ReadonlyMap<string, DeliveredResult[]> {
+  if (previous.has(messageId)) {
+    return previous;
+  }
+  const next = new Map(previous);
+  next.set(messageId, results);
+  return next;
+}
+
+/**
+ * A defensive copy for seeding transcript state from the resume store:
+ * entries that do not hold well-formed results are dropped rather than
+ * rendered (or crashed on). The store is in-memory today, so every entry
+ * it holds passed the payload narrower — this seam is where any future
+ * persisted form of the store must degrade gracefully instead of wedging
+ * the resume path: a dropped receipt reappears on the next full replay.
+ */
+export function wellFormedDeliveryAnchorsOf(
+  stored: ReadonlyMap<string, DeliveredResult[]>,
+): ReadonlyMap<string, DeliveredResult[]> {
+  const seeded = new Map<string, DeliveredResult[]>();
+  // The narrowing deliberately distrusts the map's own types: this seam
+  // is what turns a stale shape into missing rows instead of a crash.
+  const entries = stored as ReadonlyMap<string, unknown>;
+  for (const [messageId, anchored] of entries) {
+    if (!Array.isArray(anchored)) {
+      continue;
+    }
+    const results = anchored.filter(
+      (entry): entry is DeliveredResult =>
+        typeof entry === "object" &&
+        entry !== null &&
+        typeof (entry as Record<string, unknown>).ordinal === "number" &&
+        typeof (entry as Record<string, unknown>).label === "string" &&
+        typeof (entry as Record<string, unknown>).succeeded === "boolean",
+    );
+    if (results.length > 0) {
+      seeded.set(messageId, results);
+    }
+  }
+  return seeded;
+}
+
+/**
+ * Anchors each subagent_results_delivered marker to the first message
+ * that appears after it — the delivery run's first assistant message,
+ * since the marker is the run's first stored row and a delivery turn
+ * has no user bubble. Run-bounded: a pending marker never leaks onto a
+ * later run's first message, and the run id rides to the caller so the
+ * store can anchor once per delivery run no matter where each
+ * connection's message list has drifted to at flush time.
+ */
+export function subagentDeliveryMarkerRecorder(
+  onDeliveryAnchored: (
+    deliveryRunId: string,
+    messageId: string,
+    results: DeliveredResult[],
+  ) => void,
+): AgentSubscriber {
+  let pending: { runId: string; results: DeliveredResult[] } | null = null;
+  let currentRunId: string | null = null;
+
+  return {
+    // One agent can be connected more than once (StrictMode detaches
+    // the first run terminal-free and starts over): a marker a dead
+    // connection collected but never flushed must not ride into the
+    // replacement's flush.
+    onRunInitialized() {
+      pending = null;
+      currentRunId = null;
+    },
+    onRunStartedEvent({ event }) {
+      currentRunId = event.runId;
+    },
+    onCustomEvent({ event }) {
+      if (event.name !== SUBAGENT_RESULTS_DELIVERED_EVENT_NAME) {
+        return;
+      }
+      const results = deliveredResultsOf(event.value);
+      if (results !== null && currentRunId !== null) {
+        pending = { runId: currentRunId, results };
+      }
+    },
+    onMessagesChanged({ messages }) {
+      const newestMessage = messages.at(-1);
+      if (pending === null || newestMessage === undefined) {
+        return;
+      }
+      const marker = pending;
+      pending = null;
+      onDeliveryAnchored(marker.runId, newestMessage.id, marker.results);
+    },
+    // A pathological message-less delivery run must not carry its
+    // divider into the next run's first message.
+    onRunFinishedEvent() {
+      pending = null;
+    },
+  };
+}

package/src/core/subagent-presence.ts

@@ -0,0 +1,130 @@
+// Subagent presence derivations: the pure reads behind the
+// agent-identity variants, the inline current-work line and the roster's
+// settled-duration copy. Kept OUTSIDE subagent-roster.ts — these pull in
+// run-folds and tool-call-display; the roster imports from here, never back.
+
+import { settledFoldHeadlineOf } from "./run-folds.js";
+import type { ToolCallViewModel } from "./tool-call-display.js";
+import type { TranscriptRow } from "./transcript-rows.js";
+
+/** The deterministic per-coworker palette index (law 10): distinct children
+ *  wear distinct colors, and the SAME child keeps the SAME color across the
+ *  inline group, the roster, the child transcript, a reconnect and a full
+ *  replay. Replay-stable by construction: coworkers rank by their FIRST
+ *  ask's ordinal — a durable wire fact — so arrival and settle order can
+ *  never permute it, and a resume chain keeps one index. 1-based. */
+export function coworkerIndicesOf(
+  dispatches: Iterable<{ ordinal: number; child_session_id: string }>,
+): ReadonlyMap<string, number> {
+  const firstOrdinalBySession = new Map<string, number>();
+  for (const dispatch of dispatches) {
+    const held = firstOrdinalBySession.get(dispatch.child_session_id);
+    if (held === undefined || dispatch.ordinal < held) {
+      firstOrdinalBySession.set(dispatch.child_session_id, dispatch.ordinal);
+    }
+  }
+  const ranked = [...firstOrdinalBySession.entries()].sort(
+    (a, b) => a[1] - b[1],
+  );
+  const indices = new Map<string, number>();
+  ranked.forEach(([childSessionId], position) => {
+    indices.set(childSessionId, position + 1);
+  });
+  return indices;
+}
+
+/** A child transcript's newest LIVE tool call, as the presenter's view shape
+ *  — the evidence behind the inline current-work line (TVC-072). Rows sit in
+ *  TOOL_CALL_START order while results land in COMPLETION order, and every
+ *  result-less call is input-available while the run streams (bar the
+ *  retry-severed), so several live calls at once are normal: the
+ *  scan walks past settled rows to the newest LIVE one, null when none is.
+ *  Only `input-available` counts — `input-streaming` is never live here. */
+export function newestToolCallViewOf(
+  rows: readonly TranscriptRow[],
+): ToolCallViewModel | null {
+  for (let rowIndex = rows.length - 1; rowIndex >= 0; rowIndex -= 1) {
+    const row = rows[rowIndex];
+    if (row.kind === "tool-call") {
+      const view = _liveViewOf(row);
+      if (view !== null) {
+        return view;
+      }
+    }
+  }
+  return null;
+}
+
+/** Whether two published live views carry the same current-work EVIDENCE —
+ *  the fields the running-arm headline reads: the model's `caption`, else
+ *  the authored `progressText` when the wire annotated the call, else the
+ *  tool name. The publish path
+ *  may treat equal-evidence views as one fact; a consumer reading payload
+ *  fields off the map must extend this comparison first. */
+export function sameCurrentWorkView(
+  a: ToolCallViewModel,
+  b: ToolCallViewModel,
+): boolean {
+  return (
+    a.toolName === b.toolName &&
+    a.state === b.state &&
+    a.display?.caption === b.display?.caption &&
+    a.display?.progressText === b.display?.progressText
+  );
+}
+
+function _liveViewOf(row: {
+  toolName: string;
+  state: ToolCallViewModel["state"];
+  argsText: string;
+  errorText?: string;
+  display?: ToolCallViewModel["display"];
+}): ToolCallViewModel | null {
+  if (row.state !== "input-available") {
+    return null;
+  }
+  // The label-bearing fields only: currentWorkLabel derives from the
+  // headline ladder (display text → humanized tool name), never from the
+  // payload panes, so output stays off this narrow view.
+  return {
+    toolName: row.toolName,
+    state: row.state,
+    input: row.argsText,
+    errorText: row.errorText,
+    display: row.display,
+  };
+}
+
+/** A settled dispatch's span in milliseconds — the ONE timestamp read behind
+ *  both duration registers: null while the child runs and on unparseable
+ *  timestamps (hidden, never invented); clock skew clamps to a measured
+ *  zero, which the ladder renders "<1s" (TVC-073). */
+export function settledSpanMsOf(
+  startedAt: string,
+  settledAt: string | null,
+): number | null {
+  if (settledAt === null) {
+    return null;
+  }
+  const started = new Date(startedAt).getTime();
+  const ended = new Date(settledAt).getTime();
+  if (!Number.isFinite(started) || !Number.isFinite(ended)) {
+    return null;
+  }
+  return Math.max(0, ended - started);
+}
+
+/** A settled dispatch's duration in the settled-fold register (law 2):
+ *  "Worked for 12s" / "Worked for <1s" — sentence AND ladder come from
+ *  settledFoldHeadlineOf, so "Worked for 0s" is unrenderable (TVC-073).
+ *  Null while the child runs and on unparseable timestamps — never invents. */
+export function settledWorkedLabelOf(
+  startedAt: string,
+  settledAt: string | null,
+): string | null {
+  const durationMs = settledSpanMsOf(startedAt, settledAt);
+  if (durationMs === null) {
+    return null;
+  }
+  return settledFoldHeadlineOf({ kind: "measured", durationMs });
+}