@teaflask/assistant 0.3.0 → 0.7.0

package/src/core/epoch-sync.ts

@@ -1,480 +0,0 @@
-// The connection epoch: one epoch per (thread, stream id, reconnect
-// nonce, background-attach nonce, resume store) — minting it, retiring
-// it, and the durable-turn machinery that rides its publishes (the
-// newest-turn note, approval-card reconcile and hydration, execution
-// entries, the activity feed). The epoch-confined callbacks keep
-// dropping a retired epoch's late writes exactly as the comments below
-// rule.
-
-import { APPROVAL_REQUESTED_EVENT_NAME } from "../contract/events.js";
-import type { ServingAssistantTurn } from "../contract/threads.js";
-import {
-  activitySnapshotOf,
-  IDLE_ACTIVITY,
-  sameActivitySnapshot,
-  settledResultOf,
-} from "./activity.js";
-import type { ApprovalCardModel } from "./approval-inbox.js";
-import {
-  beginConnectionEpoch,
-  markerAnchorsOf,
-  type ConnectionEpochDeps,
-} from "./connection-epoch.js";
-import {
-  busyOf,
-  noteInterruptAnswerConsumed,
-  publishStore,
-} from "./conversation-publish.js";
-import type { ActiveConversation } from "./conversation-contract.js";
-import type { AssistantConversationStore } from "./conversation-store.js";
-import {
-  coworkerExecutionWorkOf,
-  sameCoworkerExecutionWork,
-} from "./coworker-execution-work.js";
-import {
-  elicitationCardsOf,
-  sameElicitationCards,
-} from "./elicitation-cards.js";
-import {
-  executionHandlersFor,
-  type ExecutionHandler,
-} from "./execution-handlers.js";
-import type { ExecutionEntryModel } from "./execution-inbox.js";
-import { restDisplayAnchorsOf } from "./tool-call-display-anchors.js";
-import { toolDenialMarkerOf } from "./tool-denial-anchors.js";
-import { approvalCardSchemasOf } from "./tool-schema-anchors.js";
-
-// One epoch per (thread, stream id, reconnect nonce, background-attach
-// nonce, resume store): the first three are exactly the old remount
-// key, so a send, a retry, a thread switch, or a restart reclaim
-// begins a fresh epoch — a fresh agent seeded from the resume store, a
-// fresh execution inbox (the approval inbox is thread-lived and rides
-// through), a fresh driver. The background-attach nonce
-// begins a fresh epoch WITHOUT moving the remount key — see
-// the no-remount premise at syncConnection's remint branch.
-export function syncEpoch(store: AssistantConversationStore): void {
-  const active = store._active;
-  if (active === null || store._disposed) {
-    retireEpoch(store);
-    // No conversation, no cards — guarded so an idle publish loop
-    // never re-sets the cell (it notifies on reference change).
-    if (store._approvalsCell.get().length > 0) {
-      publishApprovalCards(store, []);
-    }
-    // The coworker rows' work line dies with the conversation too
-    // — same guard, same reason.
-    if (store._coworkerWorkCell.get().size > 0) {
-      store._coworkerWorkCell.set(new Map());
-    }
-    return;
-  }
-  const signature = `${active.thread.id}|${active.thread.stream_thread_id}|${String(store._reconnectNonce)}|${String(store._backgroundAttachNonce)}`;
-  if (
-    store._epoch !== null &&
-    store._epochSignature === signature &&
-    store._epochResume === active.resume
-  ) {
-    return;
-  }
-  retireEpoch(store);
-  const epochId = store._nextEpochId;
-  store._nextEpochId += 1;
-  store._epoch = beginConnectionEpoch(_mintEpochDeps(store, active, epochId));
-
-  store._epochSignature = signature;
-  store._epochResume = active.resume;
-  store._epochConnectedOnce = false;
-  // The pending approval asks are thread-lived: seed the cell
-  // from the carried inbox synchronously — the reconnect's replay
-  // re-delivers into it idempotently — exactly like the message list
-  // seeds from the resume snapshot below, so a remount paints the cards
-  // instantly instead of flashing them away mid-decision.
-  publishApprovalCards(store, active.approvalInbox.cards());
-  store._elicitationErrors.clear();
-  store._questionAnswers.clear();
-  // questionDrafts is deliberately NOT cleared here: an epoch
-  // reset is a transport event — a reconnect, a workflow restart — and
-  // the member's half-typed answers must survive it. Draft lifetime is
-  // ruled in question-drafts.ts: cleared on present-and-settled
-  // evidence (publishExecutionEntries) or a thread switch.
-  publishExecutionEntries(store, []);
-  // The coworker requests are conversation-lived: the fresh
-  // inbox is seeded from the ACTIVE conversation's turns window, the way
-  // the approval cards seed from its carried inbox above — a stream reset
-  // must not drop an ask nothing on the stream re-delivers, and nothing
-  // outliving the conversation may seed an epoch (the send empties the
-  // window, a switch or abandon drops it; tests/epoch-seed-census).
-  store._epoch.withExecutionInbox((inbox) =>
-    inbox.adoptCoworkerRequests(active.coworkerRequestTurns),
-  );
-  store._messagesCell.set([...store._epoch.agent.messages]);
-  store._markerAnchorsCell.set(markerAnchorsOf(active.resume));
-  store._connectionCell.set({
-    epochId,
-    agent: store._epoch.agent,
-    threadId: active.thread.id,
-    streamThreadId: active.thread.stream_thread_id,
-  });
-}
-
-// The epoch's ~25-key deps object: every store callback the epoch may
-// ring, each publish confined to its own epoch id so a retired epoch's
-// late writes drop (the in-flight execution pass runs to completion
-// after dispose — at-most-once delivery).
-function _mintEpochDeps(
-  store: AssistantConversationStore,
-  active: ActiveConversation,
-  epochId: number,
-): ConnectionEpochDeps {
-  return {
-    epochId,
-    session: store.deps.session,
-    threadId: active.thread.id,
-    streamThreadId: active.thread.stream_thread_id,
-    ledger: active.ledger,
-    resume: active.resume,
-    approvalInbox: active.approvalInbox,
-    handlersOf: () => _executionHandlers(store, active.thread.id),
-    // Every epoch publish is confined to its own epoch. Recorders
-    // unsubscribe on retireEpoch, but the execution driver's in-flight
-    // pass runs to completion AFTER dispose (at-most-once delivery), so
-    // an epoch swap mid-pass would otherwise let a retired epoch stamp
-    // the previous thread's entries onto the now-active thread's shared
-    // cells. The id check drops those late writes.
-    publishApprovalCards: (cards) => {
-      if (store._epoch?.epochId === epochId) {
-        publishApprovalCards(store, cards);
-      }
-    },
-    publishExecutionEntries: (entries) => {
-      if (store._epoch?.epochId === epochId) {
-        publishExecutionEntries(store, entries);
-      }
-    },
-    publishMarkerAnchors: () => {
-      if (store._epoch?.epochId === epochId) {
-        store._markerAnchorsCell.set(markerAnchorsOf(active.resume));
-        // A freshly anchored turn_failed receipt changes what the
-        // failure banner should say (bannerFailureSentenceOf yields to
-        // the in-transcript record), and the banner rides the
-        // conversation snapshot, not the anchors cell.
-        publishStore(store);
-      }
-    },
-    publishMessages: (messages) => {
-      if (store._epoch?.epochId === epochId) {
-        store._messagesCell.set(messages);
-      }
-    },
-    noteInterruptAnswerConsumed: (runId, interruptId, round) => {
-      if (store._epoch?.epochId === epochId) {
-        noteInterruptAnswerConsumed(store, runId, interruptId, round);
-      }
-    },
-    onStreamError: store.handleStreamError,
-    refreshLedger: store.refreshConversation,
-    onUserMessageInjected: store.handleUserMessageInjected,
-    onRunSettled: store.handleRunSettled,
-    onQuietClose: store.handleStreamClosedQuietly,
-    onWorkflowRestarted: store.handleWorkflowRestarted,
-  };
-}
-
-export function retireEpoch(store: AssistantConversationStore): void {
-  if (store._epoch === null) {
-    return;
-  }
-  store._epoch.dispose();
-  store._epoch = null;
-  store._epochSignature = null;
-  store._epochResume = null;
-  store._connectionCell.set(null);
-}
-
-export function noteNewestTurn(
-  store: AssistantConversationStore,
-  turn: ServingAssistantTurn | null,
-  switchedThread = false,
-): void {
-  if (turn?.id !== store._newestTurn?.id) {
-    // A different turn is a different story: the automatic-reconnect
-    // budget guards one stuck turn, not the conversation.
-    store._automaticReconnects = 0;
-  }
-  if (switchedThread) {
-    // A new thread's activity must not inherit the old thread's last
-    // result: settledResultOf only WRITES on a terminal turn, so
-    // switching to a still-running thread would otherwise leave the
-    // feed pointing at the previous conversation's outcome. Clear
-    // first; the line below re-sets it iff the new newest already
-    // settled. The answerable-pause snapshot is the old thread's too
-    // (the full-detail adopters re-derive it right after this call).
-    store._lastResult = null;
-    store._awaitingTurn = null;
-  }
-  store._newestTurn = turn;
-  const settled = turn === null ? null : settledResultOf(turn);
-  if (settled !== null) {
-    store._lastResult = settled;
-  }
-}
-
-export function publishApprovalCards(
-  store: AssistantConversationStore,
-  cards: readonly ApprovalCardModel[],
-): void {
-  // The cards' schemas feed the schema anchors first: every
-  // card path — the stream marker, the REST pending_approvals rebuild,
-  // the submit republish — funnels through here, so an anchored call's
-  // argsSchema is resolvable by the time the paint the cards trigger
-  // reads the anchors. The card model is the wire's single narrowed
-  // home for these fields; this consumes it rather than re-deriving.
-  _recordApprovalCardSchemas(store, cards);
-  store._approvalsCell.set(cards);
-  _publishCoworkerWork(store);
-  // Pending-approval count rides the feed, and a card arriving or
-  // closing re-judges the pending-decision gap — the full
-  // publish covers both and dedupes unchanged snapshots itself.
-  publishStore(store);
-}
-
-function _recordApprovalCardSchemas(
-  store: AssistantConversationStore,
-  cards: readonly ApprovalCardModel[],
-): void {
-  const active = store._active;
-  if (active === null) {
-    return;
-  }
-  const before = active.resume.toolSchemaAnchors;
-  for (const card of cards) {
-    if (card.toolCallId === null) {
-      continue;
-    }
-    const schemas = approvalCardSchemasOf(card);
-    if (schemas !== null) {
-      active.resume.recordToolSchemas(card.toolCallId, schemas);
-    }
-  }
-  // The anchors map's first-wins merge makes the re-record of an
-  // already-anchored card a no-op — identity is the publish gate, the
-  // same pattern as the display hydration below.
-  if (active.resume.toolSchemaAnchors !== before) {
-    store._markerAnchorsCell.set(markerAnchorsOf(active.resume));
-  }
-}
-
-// The durable turn record re-judges the pending cards on every REST
-// read: the parked flag, a superseded ask, a settled turn —
-// all rendered from truth instead of stream inference. Hydration runs
-// first: the record's pending_approvals snapshot rebuilds any
-// card the stream never delivered, so a pending id can never publish
-// as "needs input" with an empty approval surface — then reconcile
-// judges the whole set, hydrated cards included. The window is required:
-// the settled-runs arm is the close a finished run's cards
-// get when the stream's own evidence closed none, and a caller cannot
-// leave it out by construction.
-export function reconcileApprovals(
-  store: AssistantConversationStore,
-  turns: readonly ServingAssistantTurn[],
-): void {
-  const inbox = store._active?.approvalInbox;
-  if (inbox === undefined) {
-    return;
-  }
-  // The pause is hydrated from the ANSWERABLE turn, not the newest
-  // row (a queued message can sit newer than the pause, and
-  // hydrating from the queued row would silently disable the REST
-  // card rebuild exactly when the member must answer to unblock the
-  // queue). reconcileWithTurn deliberately keeps the NEWEST row (a
-  // terminal newest turn removes the conversation's cards), and the
-  // settled-runs arm closes any window turn's settled run behind it —
-  // a RUN_FINISHED closes nothing, so a card the stream's own evidence
-  // did not close dies on this read.
-  const pause = theAnswerablePause(store);
-  // Display annotations land BEFORE the cards hydrate: a
-  // recovered call's annotation must already be resolvable when its
-  // ROW first paints, never annotation-less-then-annotated. (The
-  // banner reads none of it — the row is the
-  // annotation's one rendered home.)
-  _hydratePendingApprovalDisplays(store, pause);
-  _hydratePendingApprovalAsks(store, pause);
-  const hydrated = inbox.hydratePendingApprovals(pause);
-  const reconciled = inbox.reconcileWithTurn(store._newestTurn);
-  const settled = inbox.reconcileWithTurns(turns);
-  if (hydrated || reconciled || settled) {
-    publishApprovalCards(store, inbox.cards());
-  }
-}
-
-/** The turn holding the answerable pause, if any: the newest row when
- *  it pauses itself, else the newest ANSWERABLE row off the last full
- *  refresh (see _awaitingTurn's caveat: partial
- *  adopters don't maintain it, so between a send and the next full
- *  refresh this can lag one snapshot; every consumer is re-run at
- *  adoption, and the inbox's own guards absorb a stale read). */
-export function theAnswerablePause(
-  store: AssistantConversationStore,
-): ServingAssistantTurn | null {
-  const newest = store._newestTurn;
-  if (
-    newest !== null &&
-    (newest.status === "awaiting_input" || newest.status === "parked")
-  ) {
-    return newest;
-  }
-  return store._awaitingTurn;
-}
-
-/**
- * The recovery read's display annotations: the turn
- * record's pending_approval_displays carries the same
- * tool_call_annotated content the stream replays, so a REST-recovered
- * call's ROW resolves its annotation — authored copy, icon, and the
- * view contract's key — even when no stream ever delivered the call.
- * (The approval banner reads no annotations; a call that never
- * reaches the transcript at all has no reader for
- * its hydrated display until it does — kept, because the channel is
- * the row's, not the banner's.) Recorded
- * into the resume store's anchors map, the display's single client
- * home: the merge is the map's own first-wins fold, so a later stream
- * replay of the same markers is a no-op, and the same gate as
- * hydratePendingApprovals keeps a stale read from resurrecting
- * superseded copy (an absent field is an older server, never an
- * unannotated pause).
- */
-function _hydratePendingApprovalDisplays(
-  store: AssistantConversationStore,
-  turn: ServingAssistantTurn | null,
-): void {
-  const active = store._active;
-  if (
-    active === null ||
-    turn === null ||
-    (turn.status !== "awaiting_input" && turn.status !== "parked") ||
-    turn.run_id === null
-  ) {
-    return;
-  }
-  const anchors = restDisplayAnchorsOf(turn.pending_approval_displays);
-  if (anchors.size === 0) {
-    return;
-  }
-  const before = active.resume.toolCallDisplayAnchors;
-  for (const [toolCallId, display] of anchors) {
-    active.resume.recordToolCallDisplay(toolCallId, display);
-  }
-  if (active.resume.toolCallDisplayAnchors !== before) {
-    store._markerAnchorsCell.set(markerAnchorsOf(active.resume));
-  }
-}
-
-/**
- * The recovery read's half of the denial join: the paused
- * turn's pending_approvals carry the same interrupt_id → tool_call_id
- * pairs the stream's approval_requested markers do, so a client whose
- * stream never delivered the ask (a REST-recovered pause) still holds
- * it in the ledger's ask map when the resumed stream's
- * approval_resolved lands. Same gate as hydratePendingApprovals — a
- * live pause only; a settled turn's asks arrive by full replay. Asks
- * never publish: only the DENIED half is presentation, and it can only
- * move on the durable approval_resolved marker — never on the submit
- * path's own answer — so live and replay derive the row identically
- * (Law 9).
- */
-function _hydratePendingApprovalAsks(
-  store: AssistantConversationStore,
-  turn: ServingAssistantTurn | null,
-): void {
-  const active = store._active;
-  if (
-    active === null ||
-    turn === null ||
-    (turn.status !== "awaiting_input" && turn.status !== "parked") ||
-    turn.run_id === null ||
-    !Array.isArray(turn.pending_approvals)
-  ) {
-    return;
-  }
-  for (const value of turn.pending_approvals) {
-    const marker = toolDenialMarkerOf(APPROVAL_REQUESTED_EVENT_NAME, value);
-    if (marker !== null) {
-      active.resume.recordToolDenialMarker(marker);
-    }
-  }
-}
-
-export function publishExecutionEntries(
-  store: AssistantConversationStore,
-  entries: readonly ExecutionEntryModel[],
-): void {
-  // Entries publish for EVERY execution kind's lifecycle; the cell
-  // notifies on reference change, so an unchanged derivation (usually
-  // the empty list) must never re-set it — the cell contract's
-  // "publishers set only when state actually changed".
-  const cards = elicitationCardsOf(
-    entries,
-    store._elicitationErrors,
-    store._questionAnswers,
-  );
-  if (!sameElicitationCards(cards, store._elicitationsCell.get())) {
-    store._elicitationsCell.set(cards);
-  }
-  _publishCoworkerWork(store);
-  // A question set's draft is released only on PRESENT-and-settled
-  // evidence — a published card for that very interrupt reading
-  // answered or stale — never on absence: the reconnect publishes an
-  // empty entry list before the replay refills it.
-  for (const card of cards) {
-    if (card.status === "answered" || card.status === "stale") {
-      store.questionDrafts.clear(card.interruptId);
-    }
-  }
-  // Entries can move without the member-answerable cards moving (a
-  // driver-claimed navigate, a reported execution) and each of those
-  // re-judges the pending-decision gap.
-  publishStore(store);
-}
-
-export function publishActivity(store: AssistantConversationStore): void {
-  const snapshot =
-    store._active === null
-      ? IDLE_ACTIVITY
-      : activitySnapshotOf({
-          busy: busyOf(store),
-          newestTurn: store._newestTurn,
-          approvalCards: store._approvalsCell.get(),
-          pendingDecisionGap: store._pendingDecisionGap,
-          lastResult: store._lastResult,
-        });
-  if (!sameActivitySnapshot(snapshot, store._activityCell.get())) {
-    store._activityCell.set(snapshot);
-  }
-}
-
-function _executionHandlers(
-  store: AssistantConversationStore,
-  threadId: string,
-): ReadonlyMap<string, ExecutionHandler> {
-  const capabilities = store.deps.hostCapabilitiesOf();
-  return executionHandlersFor(
-    capabilities.navigate,
-    capabilities.executeActionIntent,
-    threadId,
-  );
-}
-
-// The coworker rows' work line: folded from the LIVE
-// epoch's execution entries and the carried approval cards, on either
-// publish, with the set-only-on-change discipline. The entries are read
-// off the epoch's own inbox, never cached on the store: a fresh epoch's
-// first publish then folds nothing of the conversation it replaced.
-function _publishCoworkerWork(store: AssistantConversationStore): void {
-  const coworkerWork = coworkerExecutionWorkOf(
-    store._epoch?.executionInbox.entries() ?? [],
-    store._approvalsCell.get(),
-  );
-  if (!sameCoworkerExecutionWork(coworkerWork, store._coworkerWorkCell.get())) {
-    store._coworkerWorkCell.set(coworkerWork);
-  }
-}

package/src/core/error-copy.ts

@@ -1,102 +0,0 @@
-import { ServingApiError } from "../transport/serving-error.js";
-import { STOP_NOT_DELIVERED_SENTENCE } from "./stop-copy.js";
-
-// The honest error taxonomy: one user-facing sentence per contract code
-// the surface can hit. Unknown codes fall back to the server's message,
-// which the contract guarantees is a human sentence safe to show.
-
-const GENERIC_FAILURE_SENTENCE =
-  "Something went wrong sending that. Please try again.";
-
-export function userSentenceFor(error: unknown): string {
-  if (!(error instanceof ServingApiError)) {
-    return GENERIC_FAILURE_SENTENCE;
-  }
-  switch (error.code) {
-    // Retired producer (sends queue instead) — kept for older deploys.
-    case "ASSISTANT_THREAD_BUSY":
-      return (
-        "The assistant is already answering — possibly in another tab. " +
-        "Wait for it to finish."
-      );
-    case "RATE_LIMITED":
-      return _rateLimitedSentence(error.retryAfterSeconds);
-    case "SUBSCRIPTION_CANNOT_PAY":
-      return _subscriptionCannotPaySentence(error);
-    case "SUBSCRIPTION_CONNECT_REQUIRED":
-      // The server sentence is the visitor copy; the connect panel (which
-      // opens on this code) owns the richer affordance.
-      return error.message;
-    case "ORCHESTRATION_UNAVAILABLE":
-      return "The assistant couldn't be started right now. Please try again in a moment.";
-    case "NOT_FOUND":
-      return "That conversation doesn't exist anymore.";
-    case "VALIDATION_ERROR":
-      return "That message couldn't be sent. Shorten it and try again.";
-    default:
-      return error.message;
-  }
-}
-
-// The stop door's failure vocabulary: a failed stop must never
-// read as a failed send ("couldn't be started", "went wrong sending
-// that" — both lies about a turn that is still running). The door's own
-// sentences are written for this surface — its 503 ships "The stop
-// couldn't be delivered right now. Please try again in a moment." — so
-// every contract sentence passes through, and the generic line (the
-// stop-copy leaf's, shared with the dashboard playground) covers only
-// transport deaths that never reached the door.
-
-export function stopFailureSentenceFor(error: unknown): string {
-  if (error instanceof ServingApiError && error.message !== "") {
-    return error.message;
-  }
-  return STOP_NOT_DELIVERED_SENTENCE;
-}
-
-function _rateLimitedSentence(retryAfterSeconds: number | null): string {
-  if (retryAfterSeconds !== null && retryAfterSeconds > 0) {
-    return `You're sending messages too quickly. Try again in ${String(retryAfterSeconds)} seconds.`;
-  }
-  return "You're sending messages too quickly. Wait a moment and try again.";
-}
-
-function _subscriptionCannotPaySentence(error: ServingApiError): string {
-  // The wait is rendered exactly when the server sent Retry-After — it
-  // does so only for a reset still ahead (no closeness threshold
-  // exists) — in the largest sensible unit: plan windows run daily to
-  // weekly, so raw minutes would read "about 10080 minutes". Without
-  // the header the server's own sentence stands: the plain quota copy,
-  // or the re-checking copy for a stale bounce whose re-probe the door
-  // just kicked.
-  const retryAfterSeconds = error.retryAfterSeconds;
-  if (retryAfterSeconds !== null && retryAfterSeconds > 0) {
-    return (
-      "Your ChatGPT plan's included usage is used up for this period. " +
-      `The conversation can continue in about ${humanizedWait(retryAfterSeconds)}.`
-    );
-  }
-  return error.message;
-}
-
-const _HOUR_SECONDS = 3600;
-const _DAY_SECONDS = 24 * _HOUR_SECONDS;
-
-/** A wait in the largest sensible unit — plan windows run daily to
- *  weekly, so raw minutes would read "about 10080 minutes". Each unit is
- *  ceiled, so the promise is never early. Shared with the gate card and
- *  the standing sentences (one spelling of every wait). */
-export function humanizedWait(seconds: number): string {
-  // Minutes under two hours, hours under two days, days beyond.
-  if (seconds < 2 * _HOUR_SECONDS) {
-    return _counted(Math.max(1, Math.ceil(seconds / 60)), "minute");
-  }
-  if (seconds < 2 * _DAY_SECONDS) {
-    return _counted(Math.ceil(seconds / _HOUR_SECONDS), "hour");
-  }
-  return _counted(Math.ceil(seconds / _DAY_SECONDS), "day");
-}
-
-function _counted(count: number, unit: string): string {
-  return `${String(count)} ${unit}${count === 1 ? "" : "s"}`;
-}