@teaflask/assistant 0.3.0 → 0.6.0

package/src/core/disposable-subscriber.ts

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

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

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

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

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