@teaflask/assistant 0.3.0 → 0.7.0

package/src/core/question-drafts.ts

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

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

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

@@ -1,190 +0,0 @@
-// 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 !== "",
-  );
-}