@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/disposable-subscriber.ts

@@ -0,0 +1,45 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+
+/** A subscriber with an off switch: `dispose()` mutes every handler for
+ *  good, so a run that snapshotted the subscriber list before the
+ *  unsubscribe can say nothing more through it. */
+export interface DisposableAgentSubscriber {
+  subscriber: AgentSubscriber;
+  dispose: () => void;
+}
+
+/**
+ * Wrap a subscriber so it can be silenced. `AbstractAgent.connectAgent`
+ * snapshots the subscriber list per run, so an effect cleanup's
+ * `unsubscribe()` cannot reach the run already in flight — its teardown
+ * would still call the old subscriber's `onRunFinalized`, and on a live
+ * pause that reads as a quiet close. Every handler on the returned
+ * subscriber checks the flag first; after `dispose()` the old run
+ * reaches nothing.
+ *
+ * A Proxy, so the wrapper keeps the inner subscriber's exact member set
+ * and every handler's own signature: a handler that is absent stays
+ * absent (the agent's optional calls skip it), a present one forwards
+ * its parameters and its return until disposed, then returns undefined.
+ */
+export function disposableSubscriber(
+  inner: AgentSubscriber,
+): DisposableAgentSubscriber {
+  let disposed = false;
+  const subscriber = new Proxy(inner, {
+    get(target, property, receiver): unknown {
+      const member: unknown = Reflect.get(target, property, receiver);
+      if (typeof member !== "function") {
+        return member;
+      }
+      return (...args: unknown[]): unknown =>
+        disposed ? undefined : Reflect.apply(member, target, args);
+    },
+  });
+  return {
+    subscriber,
+    dispose: () => {
+      disposed = true;
+    },
+  };
+}

package/src/core/dock-reflow.ts

@@ -0,0 +1,120 @@
+// The sidebar's host reflow: the docked panel is a top-layer popover that
+// can never join the host's flow, so the page is pushed out from under it
+// — a margin-right on documentElement equal to the panel's width, with an
+// inline transition on the panel's own clock so push and slide-in read as
+// one motion. The host's inline values are saved on the first push of a
+// cycle and restored on release, asymmetrically: the margin goes back at
+// once (that IS the un-push) while our transition outlives the slide back,
+// paced by a timer, not transitionend (the host may transition nothing).
+// Known Intercom-class limitations, documented rather than fixed: 100vw
+// host elements overflow by the pushed width; right-anchored fixed UI stays.
+
+// The floating panel's motion clock (styles.css), restated here because
+// an inline style can't read the stylesheet's literal.
+const DOCK_REFLOW_TRANSITION =
+  "margin-right 220ms cubic-bezier(0.22, 1, 0.36, 1)";
+// Matches the stylesheet's reduced-motion collapse: 1ms, never 0 — a
+// zero-duration transition fires no events and some engines skip it.
+const DOCK_REFLOW_REDUCED_TRANSITION = "margin-right 1ms";
+// Outlasts the 220ms slide-back before the host's transition is
+// restored, with room for a busy main thread to start the slide late.
+const REFLOW_SETTLE_FALLBACK_MS = 400;
+
+export interface DockReflowController {
+  /** Pushes the page by the given width. Idempotent: a repeat push re-writes
+   * the width without re-saving — the saved values must stay the HOST's.
+   * Cancels a pending settle, so a re-dock inside the un-dock's settle window
+   * keeps our transition. Reduced motion is the caller's per-call verdict:
+   * the controller outlives the panel, and a mid-session flip must govern. */
+  push(widthPx: number, reduceMotion: boolean): void;
+  /** The animated un-push: restores the saved margin now, keeps our
+   * transition inline until the slide lands, then restores the saved
+   * transition. No-op when not pushed. */
+  release(): void;
+}
+
+interface SavedRootStyle {
+  marginRight: string;
+  transition: string;
+}
+
+// One controller per root, for the root's lifetime. The panel that
+// drives it unmounts instantly on minimize, so the controller must
+// outlive it to animate the un-push — and a remount inside the settle
+// window must find the SAME bookkeeping, or the new instance would save
+// our own still-inline transition as host state.
+const _controllers = new WeakMap<HTMLElement, DockReflowController>();
+
+export function dockReflowFor(root: HTMLElement): DockReflowController {
+  const existing = _controllers.get(root);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const controller = _createDockReflow(root);
+  _controllers.set(root, controller);
+  return controller;
+}
+
+function _createDockReflow(root: HTMLElement): DockReflowController {
+  // `saved` lives from the first push until a release's settle finishes —
+  // NOT until release: a re-push inside the settle window (the park→
+  // re-show path) would otherwise find it empty and save our own
+  // still-inline transition as host state. `pushed` alone says whether a
+  // release has work to do.
+  let saved: SavedRootStyle | null = null;
+  let pushed = false;
+  let settleTimer: number | null = null;
+
+  const cancelPendingSettle = () => {
+    if (settleTimer !== null) {
+      root.ownerDocument.defaultView?.clearTimeout(settleTimer);
+      settleTimer = null;
+    }
+  };
+
+  const restoreProperty = (name: string, value: string) => {
+    if (value === "") {
+      root.style.removeProperty(name);
+    } else {
+      root.style.setProperty(name, value);
+    }
+  };
+
+  const restoreTransitionAndForget = () => {
+    if (saved !== null) {
+      restoreProperty("transition", saved.transition);
+      saved = null;
+    }
+  };
+
+  return {
+    push(widthPx: number, reduceMotion: boolean): void {
+      cancelPendingSettle();
+      saved ??= {
+        marginRight: root.style.marginRight,
+        transition: root.style.transition,
+      };
+      pushed = true;
+      root.style.transition = reduceMotion
+        ? DOCK_REFLOW_REDUCED_TRANSITION
+        : DOCK_REFLOW_TRANSITION;
+      root.style.marginRight = `${String(widthPx)}px`;
+    },
+    release(): void {
+      if (!pushed || saved === null) {
+        return;
+      }
+      pushed = false;
+      restoreProperty("margin-right", saved.marginRight);
+      const view = root.ownerDocument.defaultView;
+      if (view === null) {
+        restoreTransitionAndForget();
+        return;
+      }
+      settleTimer = view.setTimeout(() => {
+        settleTimer = null;
+        restoreTransitionAndForget();
+      }, REFLOW_SETTLE_FALLBACK_MS);
+    },
+  };
+}

package/src/core/elicitation-answers.ts

@@ -0,0 +1,165 @@
+// Answering question sets: the ONE POST for a whole pending
+// set — answers or a distinct cancellation — with the same lock, turn
+// lookup, delivery and failure arms as the approval submit. The
+// `{ kind: "answers" }` / `{ kind: "cancelled" }` literals below are this
+// package's one allowed tool-call state site outside the driver — the
+// ledger in tests/tool-call-state-sites.test.ts names this file.
+
+import { resolveTurnToolResults } from "../transport/serving-api.js";
+import { ServingApiError } from "../transport/serving-error.js";
+import { ANSWER_NOT_SENT_SENTENCE } from "./approval-inbox.js";
+import { turnIdAnsweredBy } from "./approval-decision.js";
+import type { AssistantConversationStore } from "./conversation-store.js";
+import type {
+  AnsweredQuestions,
+  QuestionSetCardModel,
+} from "./elicitation-cards.js";
+import { publishExecutionEntries } from "./epoch-sync.js";
+import { userSentenceFor } from "./error-copy.js";
+
+/**
+ * Submit the member's answers to one pending question set — the ONE
+ * POST for the whole set, after the panel's local navigation. Same
+ * lock, turn lookup, delivery and failure arms as the approval submit;
+ * the draft is released on success and KEPT on any failure, so a retry
+ * never starts from an empty panel.
+ */
+export async function submitQuestionAnswersFromStore(
+  store: AssistantConversationStore,
+  card: QuestionSetCardModel,
+  answers: readonly { id: string; text: string }[],
+): Promise<void> {
+  await _deliverQuestionSetReport(
+    store,
+    card,
+    { answers: answers.map((answer) => ({ ...answer })) },
+    { kind: "answers", answers },
+  );
+}
+
+/**
+ * Dismiss one pending question set whole: no partial answers, and the
+ * model hears a distinct cancellation — never the kind-unsupported
+ * failure that would tell it to ask the same questions in chat.
+ */
+export async function cancelQuestionSetFromStore(
+  store: AssistantConversationStore,
+  card: QuestionSetCardModel,
+): Promise<void> {
+  await _deliverQuestionSetReport(
+    store,
+    card,
+    { cancelled: true },
+    { kind: "cancelled" },
+  );
+}
+
+async function _deliverQuestionSetReport(
+  store: AssistantConversationStore,
+  card: QuestionSetCardModel,
+  result: Record<string, unknown>,
+  answered: AnsweredQuestions,
+): Promise<void> {
+  const epoch = store._epoch;
+  const active = store._active;
+  if (epoch === null || active === null) {
+    return;
+  }
+  const inbox = epoch.executionInbox;
+  if (!inbox.beginExecution(card.interruptId)) {
+    return;
+  }
+  store._elicitationErrors.delete(card.interruptId);
+  const publishIfCurrent = () => {
+    if (store._epoch === epoch) {
+      publishExecutionEntries(store, inbox.entries());
+    }
+  };
+  publishIfCurrent();
+  try {
+    const turnId = await turnIdAnsweredBy(store, active, card);
+    if (turnId === null) {
+      store._elicitationErrors.set(card.interruptId, ANSWER_NOT_SENT_SENTENCE);
+      inbox.settlePostFailed(card.interruptId);
+      return;
+    }
+    const resolution = await resolveTurnToolResults(
+      store.deps.session,
+      active.thread.id,
+      turnId,
+      { results: [{ interrupt_id: card.interruptId, ok: true, result }] },
+    );
+    store._questionAnswers.set(card.interruptId, answered);
+    inbox.settleReported(card.interruptId, true);
+    // Released on success only — a failed POST keeps the member's
+    // staged answers for the retry.
+    store.questionDrafts.clear(card.interruptId);
+    // The delivery field alone decides the reconnect (the approval
+    // submit's law): a notice can accompany a DELIVERED restart too (the
+    // oversize drop), and skipping the reconnect there would freeze the
+    // transcript on the dead run.
+    if (resolution.delivery === "workflow_restarted") {
+      store.handleWorkflowRestarted();
+    }
+  } catch (error) {
+    if (_turnNoLongerAwaitingToolResults(error)) {
+      // Voided, settled, or answered in another tab: the set is over,
+      // and so is its draft.
+      inbox.markRunStale(card.runId);
+      store.questionDrafts.clear(card.interruptId);
+      void store.refreshConversation();
+    } else {
+      store._elicitationErrors.set(
+        card.interruptId,
+        _questionSetFailureSentenceOf(error),
+      );
+      inbox.settlePostFailed(card.interruptId);
+    }
+  } finally {
+    publishIfCurrent();
+  }
+}
+
+function _turnNoLongerAwaitingToolResults(error: unknown): boolean {
+  return (
+    error instanceof ServingApiError &&
+    error.code === "ASSISTANT_TURN_NOT_AWAITING_TOOL_RESULTS"
+  );
+}
+
+// THE RULES THE DOOR CAN REFUSE A QUESTION SET ON, AND WHAT THE MEMBER
+// SEES — the client prevents each one it can:
+//   - per-answer length ≤ 1,900 (prevented: overLimitOf gates Submit and
+//     names the question; if reached anyway, the door's sentence: "One
+//     answer is longer than 1,900 characters. Shorten it and submit
+//     again.")
+//   - C0 control characters other than tab/newline/CR (prevented:
+//     normalizeCustomText at the draft write; if reached anyway — a
+//     non-panel client — the door's sentence names the rule)
+//   - every question answered exactly once (prevented: answersOf gates
+//     Submit and builds the body from the set itself; if reached anyway,
+//     the door names the unanswered / repeated / unasked ids)
+//   - the answers-or-cancelled shape (prevented by construction; the door
+//     would say the answers could not be read)
+//   - the whole-report size cap (cannot be reached from a set the client
+//     admits: 5 × 2 × 1,900 plus the envelope sits under it — a degrade
+//     to the too-large failure, never a 422, if a foreign client did)
+//   - 409 not awaiting (stale: the panel leaves and the settled line says
+//     the set was already answered or expired)
+//   - anything else (the generic sentence: "That answer couldn't be sent.
+//     Please try again.")
+// The playground's question-submit.ts passes the door's sentence through
+// (describeError), the same words. The composer's own VALIDATION_ERROR
+// copy ("Shorten it and try again") is about the message field and is
+// deliberately NOT reused here — a member who pasted a control character
+// cannot act on "shorten".
+function _questionSetFailureSentenceOf(error: unknown): string {
+  if (
+    error instanceof ServingApiError &&
+    error.code === "VALIDATION_ERROR" &&
+    error.message !== ""
+  ) {
+    return error.message;
+  }
+  return userSentenceFor(error);
+}

package/src/core/elicitation-cards.ts

@@ -0,0 +1,165 @@
+// The elicitation cards: a pure
+// derivation from the execution inbox's entries to the member-facing models.
+// Member-answerable entries live in the SAME inbox as every execution
+// request, but their executor is the member, so they surface as cards
+// answered through the store's submit actions. React-free: no clocks, no
+// locale. One shape: a bounded set of questions answered as
+// text in one submission, or dismissed whole; its shared fields and the one
+// pending-decision predicate are what the queue, the row pill, the
+// decision-live fact and the pending-decision gap consume.
+//
+// THE PREMISE: MEMBER_ANSWERABLE_KINDS holds exactly
+// ASK_QUESTIONS_REQUEST_KIND, so "not the question-set kind" and "not
+// member-answerable" are one test, and the model carries NO discriminant (a
+// one-member union needs none). A second member-answerable kind would be
+// skipped by the driver and mint no card here — an invisible wait;
+// elicitation-cards.test.ts pins the set, so adding a kind goes red until
+// its card arm exists, where a discriminant returns with its second reader.
+
+import { ASK_QUESTIONS_REQUEST_KIND } from "./execution-handlers.js";
+import type { ExecutionEntryModel } from "./execution-inbox.js";
+import {
+  askQuestionsActionOf,
+  type QuestionModel,
+} from "./elicitation-pickers.js";
+
+export type ElicitationCardStatus =
+  "actionable" | "submitting" | "answered" | "stale";
+
+interface ElicitationCardBase {
+  /** The contract's opaque interrupt id — the card key and the report id. */
+  interruptId: string;
+  /** The server run that paused — what the answer's turn lookup keys on. */
+  runId: string;
+  toolCallId: string | null;
+  /** True once the ask's own tool row streamed on this connection. Anchoring
+   *  decides queue ORDER (the row's transcript position) and lets the row
+   *  projection settle the ask on its own row — never placement. */
+  anchored: boolean;
+  round: number;
+  status: ElicitationCardStatus;
+  /** The submit failure the member should read, when the last submit
+   *  failed — the store stamps it; null otherwise. */
+  errorSentence: string | null;
+}
+
+/** The question set: answered as text in one submission. */
+export interface QuestionSetCardModel extends ElicitationCardBase {
+  /** The set, verbatim from the (narrowed) wire; one object per entry
+   *  for its whole life, so `same*` compares it by reference. */
+  questions: readonly QuestionModel[];
+  /** What this member's own submit posted, for the settled receipt —
+   *  the store stamps it on success; null before then and on replayed
+   *  history, where the tool result row is the durable receipt. */
+  answered: AnsweredQuestions | null;
+}
+
+export type AnsweredQuestions =
+  | { kind: "answers"; answers: readonly { id: string; text: string }[] }
+  | { kind: "cancelled" };
+
+/** The member-facing card model — one shape. */
+export type ElicitationCardModel = QuestionSetCardModel;
+
+const NO_QUESTION_ANSWERS: ReadonlyMap<string, AnsweredQuestions> = new Map();
+
+// One narrowing per wire object: the action rides one entry for its
+// whole life, so caching by it keeps `questions` reference-stable across
+// publishes — which is what lets sameElicitationCards compare it by
+// reference and the publish gate stay quiet through every unrelated
+// execution-lifecycle event.
+const NARROWED_SETS = new WeakMap<
+  Record<string, unknown>,
+  { questions: QuestionModel[] } | null
+>();
+
+function narrowedQuestionSetOf(
+  action: Record<string, unknown> | null,
+): { questions: QuestionModel[] } | null {
+  if (action === null) {
+    return null;
+  }
+  const cached = NARROWED_SETS.get(action);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const narrowed = askQuestionsActionOf(action);
+  NARROWED_SETS.set(action, narrowed);
+  return narrowed;
+}
+
+/** The member-answerable entries as cards, entry order preserved. An entry
+ *  whose action does not carry its kind's shape is skipped — "ignore what
+ *  you don't recognize"; the pending-decision gap then names the pause. An
+ *  entry of a kind that is not member-answerable is the driver's to serve. */
+export function elicitationCardsOf(
+  entries: readonly ExecutionEntryModel[],
+  errorSentences: ReadonlyMap<string, string>,
+  questionAnswers: ReadonlyMap<string, AnsweredQuestions> = NO_QUESTION_ANSWERS,
+): ElicitationCardModel[] {
+  const cards: ElicitationCardModel[] = [];
+  for (const entry of entries) {
+    if (entry.kind !== ASK_QUESTIONS_REQUEST_KIND) {
+      continue;
+    }
+    const set = narrowedQuestionSetOf(entry.action);
+    if (set === null) {
+      continue;
+    }
+    cards.push({
+      interruptId: entry.interruptId,
+      runId: entry.runId,
+      toolCallId: entry.toolCallId,
+      anchored: entry.anchored,
+      round: entry.round,
+      status: _statusOf(entry),
+      errorSentence: errorSentences.get(entry.interruptId) ?? null,
+      questions: set.questions,
+      answered: questionAnswers.get(entry.interruptId) ?? null,
+    });
+  }
+  return cards;
+}
+
+/** Whether two derivations describe the same cards — the publish gate's
+ *  structural half. The cell compares snapshots by reference and
+ *  elicitationCardsOf builds a fresh array per call, while the entries feed
+ *  publishes for EVERY execution kind's lifecycle. questions and answered
+ *  compare by reference: one wire object per entry, one answered per settle. */
+export function sameElicitationCards(
+  a: readonly ElicitationCardModel[],
+  b: readonly ElicitationCardModel[],
+): boolean {
+  if (a.length !== b.length) {
+    return false;
+  }
+  return a.every((card, index) => {
+    const other = b[index];
+    return (
+      card.interruptId === other.interruptId &&
+      card.runId === other.runId &&
+      card.toolCallId === other.toolCallId &&
+      card.anchored === other.anchored &&
+      card.round === other.round &&
+      card.status === other.status &&
+      card.errorSentence === other.errorSentence &&
+      card.questions === other.questions &&
+      card.answered === other.answered
+    );
+  });
+}
+
+function _statusOf(entry: ExecutionEntryModel): ElicitationCardStatus {
+  switch (entry.status.kind) {
+    case "pending":
+      return "actionable";
+    case "executing":
+      // The inbox's claim doubles as the submit lock: the member's
+      // answer is in flight.
+      return "submitting";
+    case "reported":
+      return "answered";
+    case "stale":
+      return "stale";
+  }
+}

package/src/core/elicitation-pickers.ts

@@ -0,0 +1,120 @@
+// The ask's wire narrowing: from a builtin.ask_questions
+// request's distrusted action payload to the question set the panel
+// renders, or null. Like the other transcript narrowers, this module is
+// React-free and deterministic (no clocks, no locale, question and
+// option order preserved), own-key reads over the distrusted wire — the
+// action arrives verbatim on the execution request and is narrowed here
+// even though the server's questions/v1 door already refused malformed
+// shapes, because the client never assumes server-side validation holds
+// across versions. Public via ./transcript: the dashboard imports this
+// module rather than keeping a fork.
+
+export interface QuestionOptionModel {
+  text: string;
+  description: string | null;
+}
+
+export interface QuestionModel {
+  id: string;
+  heading: string;
+  prompt: string;
+  options: readonly QuestionOptionModel[];
+}
+
+/**
+ * Narrow a builtin.ask_questions request's action payload —
+ * the wire is distrusted. Own-key checks, never `in`. Strict about the
+ * whole set: one malformed question returns null for the set, because
+ * a panel that silently dropped a question would post an incomplete
+ * answer set the door refuses; the pending-decision gap then speaks for
+ * the unrenderable pause instead.
+ */
+export function askQuestionsActionOf(
+  action: Record<string, unknown> | null,
+): { questions: QuestionModel[] } | null {
+  if (action === null) {
+    return null;
+  }
+  const raw = _hasOwn(action, "questions") ? action.questions : null;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    return null;
+  }
+  const questions: QuestionModel[] = [];
+  const seen = new Set<string>();
+  for (const candidate of raw) {
+    if (!_isRecord(candidate)) {
+      return null;
+    }
+    const id = _hasOwn(candidate, "id") ? candidate.id : null;
+    const heading = _hasOwn(candidate, "heading") ? candidate.heading : null;
+    const prompt = _hasOwn(candidate, "prompt") ? candidate.prompt : null;
+    if (
+      typeof id !== "string" ||
+      id === "" ||
+      seen.has(id) ||
+      typeof heading !== "string" ||
+      heading.trim() === "" ||
+      typeof prompt !== "string" ||
+      prompt.trim() === ""
+    ) {
+      return null;
+    }
+    seen.add(id);
+    const rawOptions = _hasOwn(candidate, "options") ? candidate.options : [];
+    if (!Array.isArray(rawOptions)) {
+      return null;
+    }
+    const options: QuestionOptionModel[] = [];
+    // Suggestion texts are the rows' React keys and the answer itself:
+    // distinct within a question by the server's law, re-checked here
+    // because the wire is distrusted (case-insensitively, as the server).
+    const seenTexts = new Set<string>();
+    for (const option of rawOptions) {
+      if (!_isRecord(option)) {
+        return null;
+      }
+      const text = _hasOwn(option, "text") ? option.text : null;
+      if (typeof text !== "string" || text.trim() === "") {
+        return null;
+      }
+      const folded = text.toLowerCase();
+      if (seenTexts.has(folded)) {
+        return null;
+      }
+      seenTexts.add(folded);
+      const description = _hasOwn(option, "description")
+        ? option.description
+        : null;
+      // Every model-authored display string of the set takes the same
+      // escaped-quote normalization: heading, prompt, suggestion text
+      // AND description — the suggestion's text is also the answer that
+      // posts back, so it must read clean in the panel, in the receipt
+      // and to the model alike.
+      options.push({
+        text: text.replace(/\\"/g, '"'),
+        description:
+          typeof description === "string" && description.trim() !== ""
+            ? description.replace(/\\"/g, '"')
+            : null,
+      });
+    }
+    questions.push({
+      id,
+      heading: heading.replace(/\\"/g, '"'),
+      prompt: prompt.replace(/\\"/g, '"'),
+      options,
+    });
+  }
+  return { questions };
+}
+
+function _hasOwn(record: Record<string, unknown>, key: string): boolean {
+  // An own-key read spelled to compile under lib es6 — the constraint
+  // the deleted dashboard fork imposed; the spelling stays
+  // because changing it buys nothing.
+  return Object.prototype.hasOwnProperty.call(record, key);
+}
+
+function _isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}