@teaflask/assistant 0.3.0 → 0.6.0

package/src/core/stream-trouble.ts

@@ -1,154 +0,0 @@
-// 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

@@ -1,71 +0,0 @@
-// 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

@@ -1,176 +0,0 @@
-// 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

@@ -1,130 +0,0 @@
-// 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 });
-}