@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/suspension-queue.ts

@@ -0,0 +1,95 @@
+// The suspension slot's queue, pure of React: which decisions
+// are suspended on the member, in what order. A decision — an approval or
+// an ask_user question — is IN the queue exactly while it is actionable or
+// its submit is in flight; answered, stale and withdrawn ones never enter
+// (the transcript's quiet settled lines went with the meta-receipt rows;
+// the card footer and the row's state pill are the settled record).
+
+import type { ApprovalCardModel } from "./approval-inbox.js";
+import type { ElicitationCardModel } from "./elicitation-cards.js";
+
+export type PendingDecision =
+  | { kind: "approval"; card: ApprovalCardModel }
+  | { kind: "elicitation"; card: ElicitationCardModel };
+
+/** The queue identity of one decision — interrupt ids are the contract's
+ *  opaque per-pause keys, unique across both families on the wire; the
+ *  kind prefix keeps the key total even against a degenerate stream. */
+export function decisionKeyOf(decision: PendingDecision): string {
+  return `${decision.kind}:${decision.card.interruptId}`;
+}
+
+// THE pending-decision predicate — the one spelling of which card statuses
+// count as "still waiting on the human", per family. Three consumers are
+// load-bearing in tandem: the row's "Needs input" pill, this queue, and
+// the FOLD's default openness (_groupAwaitsDecision, activity-rail.tsx) —
+// a fold holds itself open while a member awaits the decision and releases
+// when it settles. The ROW's placement hold is deliberately not a consumer:
+// it ends with the TURN, so it keys on the durable decision
+// anchor (the row's decisionBearing derivation, tool-call-rows.tsx), never
+// awaiting.
+
+export function approvalAwaitsMember(card: ApprovalCardModel): boolean {
+  return card.status.kind === "actionable" || card.status.kind === "submitting";
+}
+
+export function elicitationAwaitsMember(card: ElicitationCardModel): boolean {
+  return card.status === "actionable" || card.status === "submitting";
+}
+
+/**
+ * The deterministic queue: ordered by where each decision's operation
+ * arose in the transcript (the anchoring call's row index; orphans —
+ * decisions whose call never streamed — go last), then approvals before
+ * questions on an exact tie, then each family's own arrival order (the
+ * inboxes preserve stream order, and the sort is stable over it).
+ */
+export function suspensionQueueOf(
+  approvals: readonly ApprovalCardModel[],
+  elicitations: readonly ElicitationCardModel[],
+  rowIndexByToolCallId: ReadonlyMap<string, number>,
+): PendingDecision[] {
+  const pending: PendingDecision[] = [
+    ...approvals
+      .filter(approvalAwaitsMember)
+      .map((card): PendingDecision => ({ kind: "approval", card })),
+    ...elicitations
+      .filter(elicitationAwaitsMember)
+      .map((card): PendingDecision => ({ kind: "elicitation", card })),
+  ];
+  return pending
+    .map((decision, arrival) => ({ decision, arrival }))
+    .sort((a, b) => {
+      const rowA = _rowIndexOf(a.decision, rowIndexByToolCallId);
+      const rowB = _rowIndexOf(b.decision, rowIndexByToolCallId);
+      if (rowA !== rowB) {
+        return rowA - rowB;
+      }
+      if (a.decision.kind !== b.decision.kind) {
+        return a.decision.kind === "approval" ? -1 : 1;
+      }
+      return a.arrival - b.arrival;
+    })
+    .map((entry) => entry.decision);
+}
+
+/** The pager cursor, clamped into the live queue: resolving the current
+ *  decision keeps the position, so the next decision becomes current;
+ *  a shrunken queue never strands the cursor past its end. */
+export function clampedCursorOf(cursor: number, queueLength: number): number {
+  if (queueLength <= 0) {
+    return 0;
+  }
+  return Math.min(Math.max(cursor, 0), queueLength - 1);
+}
+
+function _rowIndexOf(
+  decision: PendingDecision,
+  rowIndexByToolCallId: ReadonlyMap<string, number>,
+): number {
+  const toolCallId = decision.card.toolCallId;
+  if (toolCallId === null) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return rowIndexByToolCallId.get(toolCallId) ?? Number.POSITIVE_INFINITY;
+}

package/src/core/tail-slot-pool.ts

@@ -0,0 +1,93 @@
+// The live-tail budget. This is the sole copy:
+// the dashboard's forked twin (and the parity test that held the two to
+// one semantics) retired with the plan-run surface, the only dashboard
+// host that ever tailed. Dependency-free on purpose: the widget's
+// drill-in panel instantiates it with capacity 1 (one child stream
+// beside the held-open parent stream and the dispatches poll).
+
+// Each live tail is a full replay-then-tail SSE stream held open until
+// the child settles, on the SAME API origin as the parent's own stream —
+// and browsers cap HTTP/1.1 at six connections per origin. Three tails
+// plus the parent stream leaves headroom for the dispatches poll and
+// every ordinary read, whatever transport terminates the edge.
+const MAX_LIVE_TAILS = 3;
+
+/**
+ * The live-tail budget. Consumers lease a slot by their OWN identity —
+ * on this side the drill-in panel leases by its useId, one lease per
+ * panel, never the child session id (two surfaces drilled into the same
+ * child are two streams, and a shared key would collapse them into one
+ * holder whose first release kills the survivor's tail) — idempotently,
+ * so StrictMode's double effect is safe; the lease is released when the
+ * stream ends or the panel closes. A consumer that finds the pool full
+ * waits in arrival order: release() promotes the oldest waiter BEFORE
+ * announcing, so a freed slot is genuinely handed on — a lease effect
+ * only runs once per want-lifetime, and the promoted consumer learns it
+ * holds through the store subscription, never through a re-run.
+ */
+export class TailSlotPool {
+  private readonly holders = new Set<string>();
+  // Denied leases, in arrival order. A waiter leaves the queue when its
+  // row stops wanting (release covers both roles).
+  private readonly waiters: string[] = [];
+  private readonly listeners = new Set<() => void>();
+
+  constructor(private readonly capacity: number = MAX_LIVE_TAILS) {}
+
+  /** An external-store subscription (useSyncExternalStore's shape), so a
+   *  row re-reads its lease when any acquire/release moves the pool. */
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  holds = (leaseId: string): boolean => this.holders.has(leaseId);
+
+  /** Whether this lease is queued behind a full pool — asked and DENIED,
+   *  never merely not-yet-asked: the distinction any waiting copy must
+   *  key on (an un-asked lease is not contention). */
+  waiting = (leaseId: string): boolean => this.waiters.includes(leaseId);
+
+  acquire(leaseId: string): boolean {
+    if (this.holders.has(leaseId)) {
+      return true;
+    }
+    if (this.holders.size >= this.capacity) {
+      if (!this.waiters.includes(leaseId)) {
+        this.waiters.push(leaseId);
+        // Announce the enqueue: a denied consumer's snapshot must be
+        // able to say "waiting", not just "not holding".
+        this._emit();
+      }
+      return false;
+    }
+    this.holders.add(leaseId);
+    this._emit();
+    return true;
+  }
+
+  release(leaseId: string): void {
+    const waiting = this.waiters.indexOf(leaseId);
+    if (waiting !== -1) {
+      this.waiters.splice(waiting, 1);
+    }
+    if (!this.holders.delete(leaseId)) {
+      return;
+    }
+    // Hand the freed slot on before announcing: by the time subscribers
+    // re-read their snapshots, the promoted row already holds.
+    const promoted = this.waiters.shift();
+    if (promoted !== undefined) {
+      this.holders.add(promoted);
+    }
+    this._emit();
+  }
+
+  private _emit(): void {
+    for (const listener of [...this.listeners]) {
+      listener();
+    }
+  }
+}

package/src/core/time-labels.ts

@@ -0,0 +1,91 @@
+// Clock-time labels for the conversation surface: a user bubble
+// carries its turn's created_at as "Monday 7:19 PM" inside the weekday
+// label window and as a dated form ("Sep 7, 7:19 PM"; the year added once
+// it differs from now's) outside it — a bare weekday re-read weeks later
+// reads as THIS past weekday. The recency rule is the thread list's own
+// (RECENT_WINDOW_DAYS and the DST-safe startOfLocalDayMs — one spelling,
+// never two); the weekday LABEL bound is one day tighter. A clock reading,
+// not a cost — distinct from segment-timing's DURATION register. Unparsable
+// → null (the caller renders nothing); a future stamp reads as recent.
+
+/** The thread list's recency window (calendar days), shared verbatim. */
+export const RECENT_WINDOW_DAYS = 7;
+
+/** The weekday LABEL's own bound: seven unique weekday names, so seven
+ *  calendar days — D-6 … D0. Deliberately NOT derived from
+ *  RECENT_WINDOW_DAYS: the bucket heading may widen, but a wider weekday
+ *  window would re-admit the D-7 collision (a week-old stamp, today's name). */
+const WEEKDAY_LABEL_DAYS_BACK = 6;
+
+/** A local midnight counted back in CALENDAR days, not 24-hour blocks: on
+ *  the two days a year the clocks move, yesterday is 23 or 25 hours long,
+ *  and fixed-day subtraction would slide every boundary. The Date
+ *  constructor normalises an out-of-range day across months and years. */
+export function startOfLocalDayMs(now: Date, daysBack: number): number {
+  return new Date(
+    now.getFullYear(),
+    now.getMonth(),
+    now.getDate() - daysBack,
+  ).getTime();
+}
+
+// Module-cached: Intl.DateTimeFormat construction is the expensive
+// half, and every bubble in a long transcript formats through these.
+let recentFormat: Intl.DateTimeFormat | null = null;
+let datedFormat: Intl.DateTimeFormat | null = null;
+let datedWithYearFormat: Intl.DateTimeFormat | null = null;
+let fullFormat: Intl.DateTimeFormat | null = null;
+
+export interface ConversationalTime {
+  /** "Monday 7:19 PM" inside the weekday label window; "Sep 7,
+   *  7:19 PM" outside it ("Sep 7, 2025, 7:19 PM" across a year
+   *  boundary). */
+  label: string;
+  /** "September 7, 2026 at 7:19 PM" (locale-shaped) — the <time>
+   *  title's full spelling. */
+  full: string;
+}
+
+export function conversationalTimeOf(
+  iso: string,
+  nowMs: number = Date.now(),
+): ConversationalTime | null {
+  const parsed = Date.parse(iso);
+  if (Number.isNaN(parsed)) {
+    return null;
+  }
+  const date = new Date(parsed);
+  const now = new Date(nowMs);
+  fullFormat ??= new Intl.DateTimeFormat(undefined, {
+    dateStyle: "long",
+    timeStyle: "short",
+  });
+  const full = fullFormat.format(date);
+  // Inside the weekday label window (future included — recent, honestly):
+  // the register's own cap, never arithmetic on the bucket constant (D-7).
+  if (parsed >= startOfLocalDayMs(now, WEEKDAY_LABEL_DAYS_BACK)) {
+    recentFormat ??= new Intl.DateTimeFormat(undefined, {
+      weekday: "long",
+      hour: "numeric",
+      minute: "2-digit",
+    });
+    return { label: recentFormat.format(date), full };
+  }
+  if (date.getFullYear() === now.getFullYear()) {
+    datedFormat ??= new Intl.DateTimeFormat(undefined, {
+      month: "short",
+      day: "numeric",
+      hour: "numeric",
+      minute: "2-digit",
+    });
+    return { label: datedFormat.format(date), full };
+  }
+  datedWithYearFormat ??= new Intl.DateTimeFormat(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+  return { label: datedWithYearFormat.format(date), full };
+}

package/src/core/tool-call-display-anchors.ts

@@ -0,0 +1,325 @@
+// The tool-call display anchor model, pure of React: the recorder maps
+// each tool_call_annotated CUSTOM marker to its toolCallId, the
+// transcript reads the map to headline the call with the backend's own
+// copy, and the resume store holds the map across remounts. The
+// indirection exists because a CUSTOM marker never becomes a message —
+// like the tool-error anchors, this map is the copy's only home on the
+// client, and it must outlive the epoch: a snapshot-seeded reconnect
+// replays only past the cursor, so historical rows keep their copy from
+// here alone.
+
+import type { AgentSubscriber } from "@ag-ui/client";
+
+import { TOOL_CALL_ANNOTATED_EVENT_NAME } from "../contract/events.js";
+import type { ToolCallDisplay } from "./tool-call-display.js";
+
+// The sentences are backend-authored (already clipped at the source),
+// but the narrower distrusts the wire by contract; a runaway sentence is
+// retained capped, never unbounded.
+const DISPLAY_TEXT_MAX_CHARS = 500;
+
+// Vocabulary tokens (icon) are single words by contract; a
+// runaway token is retained capped like a sentence, and an unknown
+// token resolves to its documented fallback downstream.
+const TOKEN_MAX_CHARS = 64;
+
+// A view key is an opaque registry handle (the tool-views contract);
+// one this long could never have been registered, so an over-cap key
+// drops the whole ref rather than clipping into a key that matches
+// nothing.
+const VIEW_KEY_MAX_CHARS = 128;
+
+export const EMPTY_TOOL_CALL_DISPLAY_ANCHORS: ReadonlyMap<
+  string,
+  ToolCallDisplay
+> = new Map();
+
+/**
+ * Narrow a tool_call_annotated marker's value. Null means ignore — the
+ * contract's "clients MUST ignore events and fields they do not
+ * recognize": a blank text is no sentence, and a display carrying no
+ * recognized field annotates nothing. `kind` left the wire and the
+ * client model: it is no longer a recognized field
+ * of this contract, so a present `kind` of any value is ignored like
+ * any other unrecognized field — never a display-blanking gate. A
+ * future display variant arrives as a new field or marker; views are
+ * the generative-UI door.
+ */
+export function toolCallDisplayAnchorOf(
+  value: unknown,
+): { toolCallId: string; display: ToolCallDisplay } | null {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const { tool_call_id: toolCallId, display } = value as {
+    tool_call_id?: unknown;
+    display?: unknown;
+  };
+  if (typeof toolCallId !== "string" || toolCallId === "") {
+    return null;
+  }
+  if (typeof display !== "object" || display === null) {
+    return null;
+  }
+  const { caption, progress_text, complete_text, error_text, icon, view } =
+    display as {
+      caption?: unknown;
+      progress_text?: unknown;
+      complete_text?: unknown;
+      error_text?: unknown;
+      icon?: unknown;
+      view?: unknown;
+    };
+  const narrowed: ToolCallDisplay = {};
+  const captionText = _displayTextOf(caption);
+  if (captionText !== undefined) {
+    narrowed.caption = captionText;
+  }
+  const progressText = _displayTextOf(progress_text);
+  if (progressText !== undefined) {
+    narrowed.progressText = progressText;
+  }
+  const completeText = _displayTextOf(complete_text);
+  if (completeText !== undefined) {
+    narrowed.completeText = completeText;
+  }
+  const errorText = _displayTextOf(error_text);
+  if (errorText !== undefined) {
+    narrowed.errorText = errorText;
+  }
+  const iconToken = _tokenOf(icon);
+  if (iconToken !== undefined) {
+    narrowed.icon = iconToken;
+  }
+  const viewRef = _viewRefOf(view);
+  if (viewRef !== undefined) {
+    narrowed.view = viewRef;
+  }
+  if (
+    narrowed.caption === undefined &&
+    narrowed.progressText === undefined &&
+    narrowed.completeText === undefined &&
+    narrowed.errorText === undefined &&
+    narrowed.icon === undefined &&
+    narrowed.view === undefined
+  ) {
+    return null;
+  }
+  return { toolCallId, display: narrowed };
+}
+
+/**
+ * Idempotent per-field merge: one call's copy legitimately arrives as
+ * more than one marker (the progress sentence at start-of-run, the
+ * completion sentence at finish, a tool body's richer completion first),
+ * and every replay re-delivers them all. First non-absent value per
+ * field wins — re-applying the same sequence changes nothing, and a
+ * no-op merge returns the map unchanged: identity is the publish gate.
+ */
+export function withToolCallDisplayAnchored(
+  previous: ReadonlyMap<string, ToolCallDisplay>,
+  toolCallId: string,
+  display: ToolCallDisplay,
+): ReadonlyMap<string, ToolCallDisplay> {
+  const existing = previous.get(toolCallId);
+  if (existing === undefined) {
+    const next = new Map(previous);
+    next.set(toolCallId, display);
+    return next;
+  }
+  if (
+    (existing.caption !== undefined || display.caption === undefined) &&
+    (existing.progressText !== undefined ||
+      display.progressText === undefined) &&
+    (existing.completeText !== undefined ||
+      display.completeText === undefined) &&
+    (existing.errorText !== undefined || display.errorText === undefined) &&
+    (existing.icon !== undefined || display.icon === undefined) &&
+    (existing.view !== undefined || display.view === undefined)
+  ) {
+    return previous;
+  }
+  const merged: ToolCallDisplay = {};
+  const caption = existing.caption ?? display.caption;
+  if (caption !== undefined) {
+    merged.caption = caption;
+  }
+  const progressText = existing.progressText ?? display.progressText;
+  if (progressText !== undefined) {
+    merged.progressText = progressText;
+  }
+  const completeText = existing.completeText ?? display.completeText;
+  if (completeText !== undefined) {
+    merged.completeText = completeText;
+  }
+  const errorText = existing.errorText ?? display.errorText;
+  if (errorText !== undefined) {
+    merged.errorText = errorText;
+  }
+  const icon = existing.icon ?? display.icon;
+  if (icon !== undefined) {
+    merged.icon = icon;
+  }
+  // The view ref merges ATOMICALLY: the first non-absent whole
+  // {key, version} wins — a key from one marker must never weld to a
+  // version from another.
+  const view = existing.view ?? display.view;
+  if (view !== undefined) {
+    merged.view = view;
+  }
+  const next = new Map(previous);
+  next.set(toolCallId, merged);
+  return next;
+}
+
+/**
+ * A defensive copy for seeding transcript state from the resume store:
+ * entries that are not a string keyed text display are dropped rather
+ * than rendered (or crashed on). The store is in-memory today, so every
+ * entry passed the narrower — this seam is where any future persisted
+ * form of the store must degrade gracefully: a dropped display falls
+ * back to the mechanical headline until the next full replay.
+ */
+export function wellFormedToolCallDisplayAnchorsOf(
+  stored: ReadonlyMap<string, ToolCallDisplay>,
+): ReadonlyMap<string, ToolCallDisplay> {
+  const seeded = new Map<string, ToolCallDisplay>();
+  // The narrowing deliberately distrusts the map's own types: this seam
+  // is what turns a stale shape into a missing display, never a crash.
+  const entries = stored as ReadonlyMap<unknown, unknown>;
+  for (const [toolCallId, display] of entries) {
+    if (typeof toolCallId !== "string" || !_isWellFormedDisplay(display)) {
+      continue;
+    }
+    seeded.set(toolCallId, display);
+  }
+  return seeded;
+}
+
+/**
+ * Narrow the turn record's `pending_approval_displays` map —
+ * the REST recovery read's display annotations, keyed by tool call id,
+ * the same `tool_call_annotated` content the stream replays. Distrusts
+ * the wire exactly as the stream recorder does by reusing its narrower
+ * (REST nulls become absent fields, so downstream `undefined` semantics
+ * — an absent icon resolves generic — stay sound); a malformed entry is
+ * dropped, never rendered or crashed on.
+ */
+export function restDisplayAnchorsOf(
+  value: unknown,
+): ReadonlyMap<string, ToolCallDisplay> {
+  const anchors = new Map<string, ToolCallDisplay>();
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return anchors;
+  }
+  for (const [toolCallId, display] of Object.entries(
+    value as Record<string, unknown>,
+  )) {
+    const anchor = toolCallDisplayAnchorOf({
+      tool_call_id: toolCallId,
+      display,
+    });
+    if (anchor !== null) {
+      anchors.set(anchor.toolCallId, anchor.display);
+    }
+  }
+  return anchors;
+}
+
+/** Records each annotated call's toolCallId → display envelope. */
+export function toolCallDisplayRecorder(
+  onDisplayAnchored: (toolCallId: string, display: ToolCallDisplay) => void,
+): AgentSubscriber {
+  return {
+    onCustomEvent({ event }) {
+      if (event.name !== TOOL_CALL_ANNOTATED_EVENT_NAME) {
+        return;
+      }
+      const anchor = toolCallDisplayAnchorOf(event.value);
+      if (anchor !== null) {
+        onDisplayAnchored(anchor.toolCallId, anchor.display);
+      }
+    },
+  };
+}
+
+function _displayTextOf(text: unknown): string | undefined {
+  if (typeof text !== "string" || text.trim() === "") {
+    return undefined;
+  }
+  return text.slice(0, DISPLAY_TEXT_MAX_CHARS);
+}
+
+/** A vocabulary token (icon): a non-blank string, retained capped.
+ *  Unknown tokens survive verbatim — the presentation resolver owns the
+ *  fallback, so an older build's store never destroys a newer wire
+ *  value. */
+function _tokenOf(token: unknown): string | undefined {
+  if (typeof token !== "string" || token.trim() === "") {
+    return undefined;
+  }
+  return token.slice(0, TOKEN_MAX_CHARS);
+}
+
+/** The view ref narrows whole or not at all — key and version are
+ *  meaningless apart, so any malformed half drops the entire ref (the
+ *  package default rendering takes over, never a mismatched pair). */
+function _viewRefOf(
+  view: unknown,
+): { key: string; version: number } | undefined {
+  if (typeof view !== "object" || view === null) {
+    return undefined;
+  }
+  const { key, version } = view as { key?: unknown; version?: unknown };
+  if (
+    typeof key !== "string" ||
+    key.trim() === "" ||
+    key.length > VIEW_KEY_MAX_CHARS
+  ) {
+    return undefined;
+  }
+  if (
+    typeof version !== "number" ||
+    !Number.isInteger(version) ||
+    version < 1
+  ) {
+    return undefined;
+  }
+  return { key, version };
+}
+
+function _isWellFormedDisplay(display: unknown): display is ToolCallDisplay {
+  if (typeof display !== "object" || display === null) {
+    return false;
+  }
+  // This predicate asserts the CLIENT model — every recognized field
+  // well-typed or absent, at least one present. Extra properties (a
+  // future persisted store's stale `kind`, say) are tolerated exactly
+  // as the wire narrower tolerates unrecognized fields; a malformed
+  // recognized field drops the entry fail-closed.
+  const { caption, progressText, completeText, errorText, icon, view } =
+    display as {
+      caption?: unknown;
+      progressText?: unknown;
+      completeText?: unknown;
+      errorText?: unknown;
+      icon?: unknown;
+      view?: unknown;
+    };
+  const fieldsAreWellTypedOrAbsent =
+    (caption === undefined || typeof caption === "string") &&
+    (progressText === undefined || typeof progressText === "string") &&
+    (completeText === undefined || typeof completeText === "string") &&
+    (errorText === undefined || typeof errorText === "string") &&
+    (icon === undefined || typeof icon === "string") &&
+    (view === undefined || _viewRefOf(view) !== undefined);
+  return (
+    fieldsAreWellTypedOrAbsent &&
+    (caption !== undefined ||
+      progressText !== undefined ||
+      completeText !== undefined ||
+      errorText !== undefined ||
+      icon !== undefined ||
+      view !== undefined)
+  );
+}