@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/question-drafts.ts

@@ -0,0 +1,261 @@
+// The question-set draft store: where a member's in-progress
+// answers to a builtin.ask_questions pause live while they page through
+// the panel. OUTSIDE every component on purpose — the suspension pager
+// remounts the presented surface by decision identity, the transcript
+// remounts on every reconnect nonce, and the playground remounts its
+// whole transcript on send/retry — so a draft held in component state
+// dies at exactly the moments a member is most likely to be mid-answer.
+// Keyed by interrupt id (one pause = one question set) and question id
+// beneath it, so two sets can never bleed into each other and the pager
+// key's isolation guarantee survives without the key eating the draft.
+//
+// LIFETIME (ruled here, not inferred): created lazily on the first
+// mutation; kept across navigation, remount, reconnect and a failed
+// submit; cleared by the owner only on present-and-settled evidence (the
+// member's own successful submit or cancel, or a published card for the
+// same interrupt that reads answered/stale) — never on mere absence,
+// because a reconnect publishes an empty entry list before the replay
+// refills it; cleared wholesale on a thread switch. IN-MEMORY ONLY: a
+// page reload loses unsent drafts. That is a decision, not a gap — a
+// pause can be voided from another tab by a new message, and persisted
+// drafts would resurrect stale text against a superseded set.
+//
+// ACTIVE CHOICE is explicit: an option OR the custom row, never a hidden
+// "typed text wins" rule. Selecting an option keeps the custom text (the
+// member may come back to it); typing in the custom row makes it active.
+//
+// Deliberately import-free and React-free: every draft law (explicit
+// active choice, cursor in the draft, release only on explicit clear)
+// reads the same on every surface because there is one store — exported
+// on @teaflask/assistant/transcript for the playground.
+
+type ActiveChoice =
+  { kind: "option"; text: string } | { kind: "custom" } | null;
+
+export interface QuestionAnswerDraft {
+  active: ActiveChoice;
+  customText: string;
+}
+
+export interface QuestionSetDraft {
+  /** Which question the panel shows — kept here so paging, remounts and
+   *  reconnects all return the member to where they were. */
+  cursor: number;
+  answers: ReadonlyMap<string, QuestionAnswerDraft>;
+}
+
+export interface QuestionLike {
+  id: string;
+}
+
+/** The per-answer transport bound the server enforces (QuestionAnswer.text
+ *  maxLength on the serving contract — pinned equal by the monorepo's
+ *  contract-parity test). The panel says so beside the row instead of
+ *  clipping: no silent truncation. Measured here in UTF-16 units
+ *  (String.length) while the server counts code points — an astral
+ *  character costs two here and one there, so this side is the stricter
+ *  or equal one and a text that passes the panel never fails the door. */
+export const MAX_ANSWER_TEXT_CHARS = 1900;
+
+const EMPTY_ANSWER: QuestionAnswerDraft = { active: null, customText: "" };
+const EMPTY_SET: QuestionSetDraft = { cursor: 0, answers: new Map() };
+
+export class QuestionDraftStore {
+  private readonly drafts = new Map<string, QuestionSetDraft>();
+  private readonly listeners = new Set<() => void>();
+
+  // Arrow fields on purpose: get/subscribe travel unbound into
+  // useSyncExternalStore.
+  get = (interruptId: string): QuestionSetDraft => {
+    return this.drafts.get(interruptId) ?? EMPTY_SET;
+  };
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /** True when the member has entered anything for this set — what the
+   *  panel's Cancel consults before asking "Discard answers?". */
+  hasContent(interruptId: string): boolean {
+    const draft = this.drafts.get(interruptId);
+    if (draft === undefined) {
+      return false;
+    }
+    for (const answer of draft.answers.values()) {
+      if (answer.active !== null || answer.customText !== "") {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  selectOption(interruptId: string, questionId: string, text: string): void {
+    this.updateAnswer(interruptId, questionId, (answer) => ({
+      ...answer,
+      active: { kind: "option", text },
+    }));
+  }
+
+  selectCustom(interruptId: string, questionId: string): void {
+    this.updateAnswer(interruptId, questionId, (answer) => ({
+      ...answer,
+      active: { kind: "custom" },
+    }));
+  }
+
+  /** Typing makes the custom row the active choice — the one implicit
+   *  switch, and it is the member's own keystroke. The text is written
+   *  as the door will accept it: pasted control characters are
+   *  normalized here (see normalizeCustomText), so the panel's posture —
+   *  every per-answer rule the door enforces is kept in view before the
+   *  POST — holds for the control rule as it does for the length bound. */
+  setCustomText(interruptId: string, questionId: string, text: string): void {
+    this.updateAnswer(interruptId, questionId, (answer) => ({
+      ...answer,
+      active: { kind: "custom" },
+      customText: normalizeCustomText(text),
+    }));
+  }
+
+  setCursor(interruptId: string, cursor: number): void {
+    const current = this.get(interruptId);
+    if (current.cursor === cursor) {
+      return;
+    }
+    this.drafts.set(interruptId, { ...current, cursor });
+    this.notify();
+  }
+
+  clear(interruptId: string): void {
+    if (this.drafts.delete(interruptId)) {
+      this.notify();
+    }
+  }
+
+  clearAll(): void {
+    if (this.drafts.size === 0) {
+      return;
+    }
+    this.drafts.clear();
+    this.notify();
+  }
+
+  private updateAnswer(
+    interruptId: string,
+    questionId: string,
+    change: (answer: QuestionAnswerDraft) => QuestionAnswerDraft,
+  ): void {
+    const current = this.get(interruptId);
+    const before = current.answers.get(questionId) ?? EMPTY_ANSWER;
+    const after = change(before);
+    if (
+      before.customText === after.customText &&
+      sameChoice(before.active, after.active)
+    ) {
+      return;
+    }
+    const answers = new Map(current.answers);
+    answers.set(questionId, after);
+    this.drafts.set(interruptId, { cursor: current.cursor, answers });
+    this.notify();
+  }
+
+  private notify(): void {
+    for (const listener of [...this.listeners]) {
+      listener();
+    }
+  }
+}
+
+function sameChoice(a: ActiveChoice, b: ActiveChoice): boolean {
+  if (a === null || b === null) {
+    return a === b;
+  }
+  if (a.kind !== b.kind) {
+    return false;
+  }
+  return a.kind === "option" && b.kind === "option" ? a.text === b.text : true;
+}
+
+/** The text one question's draft answers with, or null while it has no
+ *  usable answer: an active option is its text; the custom row counts
+ *  only with non-blank text (submitted verbatim — trimming is for the
+ *  emptiness test alone, never the payload). */
+function answerTextOf(draft: QuestionAnswerDraft | undefined): string | null {
+  const active = draft?.active ?? null;
+  if (active === null || draft === undefined) {
+    return null;
+  }
+  if (active.kind === "option") {
+    return active.text;
+  }
+  return draft.customText.trim() === "" ? null : draft.customText;
+}
+
+/** The complete answer set in question order, or null while any
+ *  question is unanswered — the panel's Submit gate and its POST body. */
+export function answersOf(
+  questions: readonly QuestionLike[],
+  draft: QuestionSetDraft,
+): { id: string; text: string }[] | null {
+  const answers: { id: string; text: string }[] = [];
+  for (const question of questions) {
+    const text = answerTextOf(draft.answers.get(question.id));
+    if (text === null) {
+      return null;
+    }
+    answers.push({ id: question.id, text });
+  }
+  return answers;
+}
+
+/** The door refuses C0 control characters other than tab, newline and
+ *  carriage return (a transport rule that bounds the escaped worst case).
+ *  A textarea only normalizes CRLF, and real pastes carry the rest: Word
+ *  and Google Docs emit a vertical tab (U+000B) for a soft line break,
+ *  some PDF viewers a form feed (U+000C) for a page break. Those two ARE
+ *  line breaks to the member, so they become newlines — the break
+ *  survives unchanged in meaning; the others (NUL, BEL, BS, ESC, …) carry
+ *  no text and are dropped. Never a truncation: every printable character
+ *  stays exactly where it was. */
+function normalizeCustomText(text: string): string {
+  return text
+    .replace(/[\u000b\u000c]/g, "\n")
+    .replace(/[\u0000-\u0008\u000e-\u001f]/g, "");
+}
+
+/** The index of the first question still without a usable answer, or -1
+ *  when the set is complete — what the footer names when Submit is gated,
+ *  and where a continue from the last question jumps to. */
+export function firstUnansweredIndexOf(
+  questions: readonly QuestionLike[],
+  draft: QuestionSetDraft,
+): number {
+  return questions.findIndex(
+    (question) => answerTextOf(draft.answers.get(question.id)) === null,
+  );
+}
+
+/** The ids whose custom text exceeds the transport bound — the panel
+ *  says so beside the row instead of clipping (no silent truncation). */
+export function overLimitOf(
+  questions: readonly QuestionLike[],
+  draft: QuestionSetDraft,
+  maxChars: number,
+): string[] {
+  const over: string[] = [];
+  for (const question of questions) {
+    const answer = draft.answers.get(question.id);
+    if (
+      answer !== undefined &&
+      answer.active?.kind === "custom" &&
+      answer.customText.length > maxChars
+    ) {
+      over.push(question.id);
+    }
+  }
+  return over;
+}

package/src/core/question-receipt.ts

@@ -0,0 +1,97 @@
+import type { AnsweredQuestions } from "./elicitation-cards.js";
+import {
+  askQuestionsActionOf,
+  type QuestionModel,
+} from "./elicitation-pickers.js";
+
+/** A settled question set as the transcript states it: the questions
+ *  and the member's answers (verbatim, line breaks kept). A cancelled set
+ *  is NOT a receipt — nothing was answered, and the dismissed fact is
+ *  the panel footer's to state (the meta-receipt rule), never a
+ *  transcript row's. */
+export interface SettledQuestionsReceipt {
+  questions: readonly QuestionModel[];
+  answers: readonly { id: string; text: string }[];
+}
+
+/** The receipt for a card this tab saw settle: the member's own answers
+ *  when the store stamped them, else the plain answered fact per
+ *  question (a set another client answered — the text never reached this
+ *  tab; the row's tool result is the durable record). Null for a
+ *  cancelled set: no receipt renders for a dismissal. */
+export function settledQuestionsReceiptOfCard(
+  questions: readonly QuestionModel[],
+  answered: AnsweredQuestions | null,
+): SettledQuestionsReceipt | null {
+  if (answered !== null && answered.kind === "cancelled") {
+    return null;
+  }
+  return { questions, answers: answered === null ? [] : answered.answers };
+}
+
+/**
+ * Recover a settled question set from a durable ask_user tool row:
+ * the stored arguments must narrow to a question set AND the
+ * result must be the tool's ANSWERED return — `{answers: [{id, text}]}` —
+ * for the row to collapse into a receipt. A cancelled return
+ * (`{cancelled: true}`) is a settled decision with no answers: the row
+ * keeps its own state and no prose renders for it (the meta-receipt rule:
+ * the dismissed fact is the panel footer's, in shelf-less hosts). A failure
+ * envelope, the chat fallback, or an unrelated tool's questions-shaped
+ * arguments never become one. Tool identity is checked first; the
+ * projection routes, it never guesses.
+ */
+export function settledQuestionsReceiptOf(
+  toolName: string,
+  argsText: string,
+  resultText: string | undefined,
+): SettledQuestionsReceipt | null {
+  if (
+    toolName !== "ask_user" ||
+    resultText === undefined ||
+    resultText === ""
+  ) {
+    return null;
+  }
+  const args = _recordOf(argsText);
+  const set = args === null ? null : askQuestionsActionOf(args);
+  if (set === null) {
+    return null;
+  }
+  const result = _recordOf(resultText);
+  if (result === null) {
+    return null;
+  }
+  if (!Object.prototype.hasOwnProperty.call(result, "answers")) {
+    return null;
+  }
+  const raw = result.answers;
+  if (!Array.isArray(raw)) {
+    return null;
+  }
+  const answers: { id: string; text: string }[] = [];
+  for (const candidate of raw) {
+    if (typeof candidate !== "object" || candidate === null) {
+      return null;
+    }
+    const record = candidate as Record<string, unknown>;
+    if (typeof record.id !== "string" || typeof record.text !== "string") {
+      return null;
+    }
+    answers.push({ id: record.id, text: record.text });
+  }
+  return { questions: set.questions, answers };
+}
+
+function _recordOf(text: string): Record<string, unknown> | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return null;
+  }
+  return parsed as Record<string, unknown>;
+}

package/src/core/reasoning-copy.ts

@@ -0,0 +1,10 @@
+// The reasoning step's two state labels, in core so both consumers read
+// ONE spelling: components/reasoning-row.tsx renders them on the row,
+// and core/run-folds.ts's liveFoldHeadlineOf names a collapsed live
+// fold's latest step with them. Components import core, never the
+// reverse — hoisting the strings here is what lets the pure headline
+// derivation say exactly what the row says without a core→component
+// import.
+
+export const REASONING_STREAMING_LABEL = "Thinking…";
+export const REASONING_SETTLED_LABEL = "Thought about it";

package/src/core/receipt-anchors.ts

@@ -0,0 +1,190 @@
+// The string-receipt anchor family ({ receipt: string }, pinned per-marker by
+// tests/contract-parity): the marker and its run's terminal are written in
+// one commit, the receipt never becomes a message, and the row renders after
+// the run's last message. The package's one consumer is turn_failed (the
+// turn_voided row was deleted with the meta-receipts); the dashboard binds
+// turn_failed and turn_stopped through ./transcript, so ReceiptPayload pins
+// all three.
+
+import type { AgentSubscriber } from "@ag-ui/client";
+
+import type {
+  TurnFailedMarker,
+  TurnStoppedMarker,
+  TurnVoidedMarker,
+} from "../generated/models/index.js";
+import { WIRE_SENTENCE_MAX_CHARS } from "./wire-sentence-cap.js";
+
+// The compile-time pin to the wire schema: the UNION of the generated
+// markers this family narrows — a property read on a union requires the
+// field in every constituent, so renaming or dropping `receipt` in
+// either contract shape fails the build here rather than silently
+// null-ing every receipt row. (An intersection would only fail when
+// both shapes lost it; tests/contract-parity pins each schema's field
+// on the wire side as well.)
+type ReceiptPayload = TurnVoidedMarker | TurnFailedMarker | TurnStoppedMarker;
+
+export interface AnchoredReceipts {
+  before: string[];
+  after: string[];
+}
+
+/**
+ * Narrow a receipt-carrying CUSTOM event's wire value (any by contract).
+ * Malformed payloads return null and are ignored — the contract's
+ * "clients MUST ignore events and fields they do not recognize".
+ */
+export function receiptOf(value: unknown): string | null {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+  const payload = value as Partial<ReceiptPayload>;
+  if (typeof payload.receipt !== "string" || payload.receipt === "") {
+    return null;
+  }
+  return payload.receipt.slice(0, WIRE_SENTENCE_MAX_CHARS);
+}
+
+/**
+ * Idempotent anchor merge: every connection replays the stream from its
+ * boundary (and StrictMode aborts and reruns the first connection), so the
+ * same receipt can be anchored more than once per mount. Merging by content
+ * keeps replays from stuttering the rows.
+ */
+export function withReceiptAnchored(
+  previous: ReadonlyMap<string, AnchoredReceipts>,
+  messageId: string,
+  position: keyof AnchoredReceipts,
+  receipts: string[],
+): ReadonlyMap<string, AnchoredReceipts> {
+  const anchored = previous.get(messageId) ?? { before: [], after: [] };
+  // Unique within the batch too: a flush can carry the same receipt
+  // twice when two connections' deliveries pooled before it.
+  const fresh = [...new Set(receipts)].filter(
+    (receipt) => !anchored[position].includes(receipt),
+  );
+  if (fresh.length === 0) {
+    return previous;
+  }
+  const next = new Map(previous);
+  next.set(messageId, {
+    ...anchored,
+    [position]: [...anchored[position], ...fresh],
+  });
+  return next;
+}
+
+/**
+ * A defensive copy for seeding transcript state from the resume store:
+ * entries that do not hold well-formed receipts 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 wellFormedReceiptAnchorsOf(
+  stored: ReadonlyMap<string, AnchoredReceipts>,
+): ReadonlyMap<string, AnchoredReceipts> {
+  const seeded = new Map<string, AnchoredReceipts>();
+  // 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) {
+    const before = _wellFormedReceiptsAt(anchored, "before");
+    const after = _wellFormedReceiptsAt(anchored, "after");
+    if (before.length > 0 || after.length > 0) {
+      seeded.set(messageId, { before, after });
+    }
+  }
+  return seeded;
+}
+
+/**
+ * Anchors each of one marker's receipts: the marker and its run's
+ * terminal are written in one commit, so the terminal is always the very
+ * next event — the live RUN_ERROR for turn_failed, demoted to a quiet
+ * RUN_FINISHED on replay — and the receipt flushes to a row after that
+ * run's last message on either one.
+ */
+export function receiptMarkerRecorder(
+  eventName: string,
+  onReceiptAnchored: (
+    runId: string,
+    messageId: string,
+    position: keyof AnchoredReceipts,
+    receipts: string[],
+  ) => void,
+): AgentSubscriber {
+  let pendingReceipts: string[] = [];
+  let currentRunId: string | null = null;
+  let newestMessageId: string | null = null;
+
+  // One flush for both terminals: a failed run's live ending is
+  // RUN_ERROR, and replay demotes it to a quiet RUN_FINISHED — the
+  // turn_failed receipt must flush on either, or a live failure would
+  // anchor nothing until the next reload.
+  const flush = () => {
+    if (
+      pendingReceipts.length === 0 ||
+      newestMessageId === null ||
+      currentRunId === null
+    ) {
+      return;
+    }
+    onReceiptAnchored(currentRunId, newestMessageId, "after", pendingReceipts);
+    pendingReceipts = [];
+  };
+
+  return {
+    // One agent can be connected more than once (StrictMode detaches
+    // the first run terminal-free and starts over): receipts a dead
+    // connection collected but never flushed must not ride into the
+    // replacement's flush, or the replay's own copy doubles them.
+    onRunInitialized() {
+      pendingReceipts = [];
+      currentRunId = null;
+      newestMessageId = null;
+    },
+    onRunStartedEvent({ event }) {
+      // The server-named run id: the receipt's identity rides the run
+      // it marked, so re-deliveries anchor once no matter where each
+      // connection's message list has drifted to at flush time.
+      currentRunId = event.runId;
+    },
+    onCustomEvent({ event }) {
+      if (event.name !== eventName) {
+        return;
+      }
+      const receipt = receiptOf(event.value);
+      if (receipt !== null) {
+        pendingReceipts.push(receipt);
+      }
+    },
+    onMessagesChanged({ messages }) {
+      newestMessageId = messages.at(-1)?.id ?? null;
+    },
+    onRunFinishedEvent() {
+      flush();
+    },
+    onRunErrorEvent() {
+      flush();
+    },
+  };
+}
+
+function _wellFormedReceiptsAt(
+  anchored: unknown,
+  position: keyof AnchoredReceipts,
+): string[] {
+  if (typeof anchored !== "object" || anchored === null) {
+    return [];
+  }
+  const receipts = (anchored as Record<string, unknown>)[position];
+  if (!Array.isArray(receipts)) {
+    return [];
+  }
+  return receipts.filter(
+    (receipt): receipt is string =>
+      typeof receipt === "string" && receipt !== "",
+  );
+}