@teaflask/assistant 0.3.0 → 0.7.0

package/src/core/conversation-contract.ts

@@ -1,164 +0,0 @@
-// The conversation store's contract surface: the names a host or chrome
-// component uses to talk to AssistantConversationStore.
-
-import type { ServedThinkingEffort } from "../contract/assistant-config.js";
-import type { AssistantTelemetryEvent } from "../contract/telemetry.js";
-import type {
-  ServingAssistantThread,
-  ServingAssistantTurn,
-  TurnAttachment,
-} from "../contract/threads.js";
-import type { ServingReplayStreamAgent } from "../transport/replay-stream-agent.js";
-import type { ServingApiError } from "../transport/serving-error.js";
-import type { StreamResumeStore } from "../transport/stream-resume.js";
-import type { TokenSession } from "../transport/token-session.js";
-import type { ApprovalInbox } from "./approval-inbox.js";
-import type { AttachmentDraft } from "./composer-policy.js";
-import type {
-  ExecuteActionIntent,
-  HostNavigate,
-} from "./execution-handlers.js";
-import type { ReadonlyCell } from "./observable-cell.js";
-import type { PendingDecisionGap } from "./pending-decision-gap.js";
-import type { UserTurnLedger } from "./user-turn-ledger.js";
-
-export interface ActiveConversation {
-  thread: ServingAssistantThread;
-  ledger: UserTurnLedger;
-  // Above the Transcript remount boundary on purpose: reconnect works by
-  // remounting a fresh agent, and the resume snapshot must survive it.
-  resume: StreamResumeStore;
-  // Thread-lived too: an epoch swap must keep the cards rendered.
-  approvalInbox: ApprovalInbox;
-  // The turns window a fresh epoch's execution inbox seeds its coworker
-  // requests from — a member so it has the conversation's
-  // lifetime; the send empties it (tests/epoch-seed-census.test.ts).
-  coworkerRequestTurns: readonly ServingAssistantTurn[];
-}
-
-/** The composer's contract with the page, travelling by context (it renders
- *  standalone and inside the transcript) as one snapshot of its own inputs. */
-export interface ComposerContract {
-  busy: boolean;
-  // Set and cleared only in sendMessage, which EVERY surface's send goes
-  // through; the stop affordance keys off this field, never a local mirror.
-  pendingSend: boolean;
-  // True when the optimistic message landed; false → restore the draft (scope-guarded).
-  sendMessage: (
-    message: string,
-    attachmentIds?: string[],
-    optimisticAttachments?: TurnAttachment[],
-  ) => Promise<boolean>;
-  // The optimistic user message: shown on submit, adopts the turn-derived
-  // id when the POST lands, gone once replay injects that same message.
-  pendingEcho: {
-    messageId: string;
-    text: string;
-    attachments: TurnAttachment[];
-  } | null;
-  // True from a landed send until the composer re-enables and takes the
-  // caret back; store-held because every send remounts the composer.
-  composerRefocusPending: boolean;
-  markComposerRefocusHandled: () => void;
-  // True from the stop POST until busy flips false; never raises the banner.
-  stopping: boolean;
-  stopTurn: () => Promise<void>;
-  // The thread's stored model pick, overlaid by a chip selection not yet
-  // carried by a send; null means the configured model answers.
-  modelPick: ComposerModelPick | null;
-  setModelPick: (pick: ComposerModelPick) => void;
-  // The unsaved draft lives in the STORE, on its own cell, so no
-  // remount can eat it (lifetime ruled in docs/connection-lifecycle.md).
-  composerInput: ReadonlyCell<ComposerInput>;
-  setDraft: (next: string | ((current: string) => string)) => void;
-  setAttachments: (
-    next:
-      | readonly AttachmentDraft[]
-      | ((current: readonly AttachmentDraft[]) => readonly AttachmentDraft[]),
-  ) => void;
-  // Focus bookkeeping for involuntary remounts: the owner-stamped
-  // one-shot caret return, taken at mount (docs/connection-lifecycle.md).
-  noteComposerFocus: (owner: string | null) => void;
-  takeComposerCaretReturn: (surface: string) => boolean;
-}
-
-/** The composer's unsaved input, the composer-only cell's snapshot. */
-export interface ComposerInput {
-  // An opaque scope token: "t:<thread id>", or a freshly MINTED "u:<n>" per
-  // conversation-less state. INVARIANT: every write of _active re-scopes it,
-  // and the send-refusal restore compares against it (the lifecycle doc).
-  scope: string;
-  draft: string;
-  attachments: readonly AttachmentDraft[];
-}
-
-/** One chip selection. A null modelId is a real state — no model pin: the
- *  configured model answers under the picked effort (the way back). */
-export interface ComposerModelPick {
-  modelId: string | null;
-  effort: ServedThinkingEffort | null;
-}
-
-// Owned by the composer policy leaf; re-exported beside the draft it rides.
-export type { AttachmentDraft } from "./composer-policy.js";
-
-// The inbox's (its public submit seam); re-exported for the store's consumers.
-export type { ApprovalDecisionInput } from "./approval-inbox.js";
-
-export interface ConversationSnapshot {
-  active: ActiveConversation | null;
-  // The identified visitor's history: page chrome the palette never renders.
-  threads: ServingAssistantThread[];
-  // True when this browser is identified or the host wired identity (the
-  // sidebar's story); false is the anonymous page's plain new-conversation.
-  historyExpected: boolean;
-  // A thread detail fetch is in flight and will replace the view; the
-  // chrome fills the gap with a skeleton instead of a flash of another state.
-  threadOpening: boolean;
-  reconnectNonce: number;
-  sendError: string | null;
-  turnFailure: string | null;
-  // A dead connection mid-turn is worth a banner; a stream that ended
-  // because the turn settled failed is the failure notice's story.
-  showInterruptionBanner: boolean;
-  // The server names pending interrupts this client holds nothing for;
-  // rendered as an explicit recoverable alert, never silence.
-  pendingDecisionGap: PendingDecisionGap | null;
-}
-
-export interface HostCapabilities {
-  navigate: HostNavigate | null;
-  executeActionIntent: ExecuteActionIntent | null;
-}
-
-export interface ConversationStoreDeps {
-  session: TokenSession;
-  publishableKey: string;
-  // Whether the host wired getEndUserToken: identified history loads eagerly.
-  identityProvided: boolean;
-  // Read fresh at each use: hosts re-wire navigation/actions across renders.
-  hostCapabilitiesOf: () => HostCapabilities;
-  reportError: (error: Error) => void;
-  // The approval submit path's self-narration; a no-op unwired.
-  onTelemetry: (event: AssistantTelemetryEvent) => void;
-  // Rung when a send refuses with a gate-shaped code: the session entry
-  // adopts it as the conversation gate so the takeover renders immediately.
-  onGateRefusal: (error: ServingApiError) => void;
-  // Rung when a run settles (debounced with the settle re-read): the session
-  // entry re-reads the pre-flight projection (taster budget, plan window).
-  onTurnSettled: () => void;
-}
-
-/** What a mounted transcript needs from the live connection epoch. */
-export interface ConnectionSnapshot {
-  epochId: number;
-  agent: ServingReplayStreamAgent;
-  threadId: string;
-  streamThreadId: string;
-}
-
-/** A presigned display URL and the moment it stops being safe for an <img>. */
-export interface MintedDownloadUrl {
-  url: string;
-  expiresAtMs: number;
-}

package/src/core/conversation-publish.ts

@@ -1,223 +0,0 @@
-// Publishing: the one place snapshots rebuild and cells emit — a cell's
-// identity changes iff its content did (the useSyncExternalStore
-// contract), the epoch/connection/idle syncs key off the same pass, and
-// the pending-decision gap re-judges on every publish. The re-entrancy
-// latch (_inPublish) stays a store field — the gap gate's judge-driven
-// transitions fire inside publishStore.
-
-import type {
-  ComposerContract,
-  ConversationSnapshot,
-} from "./conversation-contract.js";
-import { syncConnection } from "./connection-driver.js";
-import { historyExpected, sameModelPick } from "./conversation-adoption.js";
-import type { AssistantConversationStore } from "./conversation-store.js";
-import {
-  publishActivity,
-  syncEpoch,
-  theAnswerablePause,
-} from "./epoch-sync.js";
-import { syncIdleRecheck } from "./idle-recheck.js";
-import { pendingDecisionGapOf } from "./pending-decision-gap.js";
-import { bannerFailureSentenceOf } from "./turn-failure-copy.js";
-
-// Rebuilds both snapshots and emits only the ones that actually moved,
-// so a cell's identity changes iff its content did — the contract
-// useSyncExternalStore's cached-snapshot semantics depend on. The
-// connection epoch keys off the same state, so it syncs here too.
-export function publishStore(store: AssistantConversationStore): void {
-  // The re-entrancy latch is the gap gate's: a judge-driven transition
-  // fires inside this function (below), where writing _pendingDecisionGap
-  // suffices — the snapshot build reads it. Only the gate's timer-driven
-  // transitions, firing outside any publish, trigger their own.
-  store._inPublish = true;
-  try {
-    syncEpoch(store);
-    _updatePendingDecisionGap(store);
-    _publishTurnMeta(store);
-    const conversation = conversationSnapshotOf(store);
-    if (
-      !_sameConversationSnapshot(conversation, store._conversationCell.get())
-    ) {
-      store._conversationCell.set(conversation);
-    }
-    const composer = composerSnapshotOf(store);
-    if (!_sameComposerSnapshot(composer, store._composerCell.get())) {
-      store._composerCell.set(composer);
-    }
-    publishActivity(store);
-    scheduleConnectionSync(store);
-    syncIdleRecheck(store);
-  } finally {
-    store._inPublish = false;
-  }
-}
-
-// The connect decision is deferred to a coalesced microtask so a
-// presence transition that resolves within the same synchronous tick —
-// a keyed transcript REMOUNT releases then re-acquires back-to-back —
-// is seen settled before the store acts. The check re-reads live at
-// fire time.
-export function scheduleConnectionSync(
-  store: AssistantConversationStore,
-): void {
-  if (store._connectionSyncQueued || store._disposed) {
-    return;
-  }
-  store._connectionSyncQueued = true;
-  queueMicrotask(() => {
-    store._connectionSyncQueued = false;
-    syncConnection(store);
-  });
-}
-
-export function conversationSnapshotOf(
-  store: AssistantConversationStore,
-): ConversationSnapshot {
-  return {
-    active: store._active,
-    threads: store._threads,
-    historyExpected: historyExpected(store),
-    threadOpening: store._threadOpening,
-    reconnectNonce: store._reconnectNonce,
-    sendError: store._sendError,
-    turnFailure: bannerFailureSentenceOf(
-      store._turnFailure,
-      store._active?.resume.turnFailedAnchors,
-    ),
-    // Never during a stop: a member who pressed stop did the
-    // interrupting themselves, and any interruption recorded inside the
-    // ~2s stop window (the dying stream's own error path) is that stop's
-    // mechanics, not connection trouble worth a banner.
-    showInterruptionBanner:
-      store._streamInterrupted && busyOf(store) && !store._stopping,
-    pendingDecisionGap: store._pendingDecisionGap,
-  };
-}
-
-// Re-judges the pending-decision gap against the current
-// truth: the turn's server-named interrupt ids vs every holder this
-// client has — approval cards (hydrate-before-reconcile already ran on
-// any REST adoption), elicitation cards, and the execution inbox's
-// entries. Runs on every publish so any path that moves cards, entries
-// or the turn re-judges; the derivation itself is pure and cheap. The
-// quiet→loud grace, the once-per-signature probe, and the loud
-// tracking all live in the shared PendingDecisionGapGate (its docblock
-// enumerates the transitions); this store's premises for the gate's
-// three deps are recorded at the _gapGate field.
-function _updatePendingDecisionGap(store: AssistantConversationStore): void {
-  if (store._disposed) {
-    return;
-  }
-  // The gap watchdog judges the PAUSE (the queuing class): with a
-  // message queued newer than the pause, the newest row reads
-  // "queued" and the derivation would go quiet in exactly the
-  // missing-card state it exists to alarm on. Falls back to the
-  // newest row so the no-pause shapes keep their null verdict.
-  const pause = theAnswerablePause(store) ?? store._newestTurn;
-  store._gapGate.judge(
-    pendingDecisionGapOf(
-      pause,
-      store._active?.approvalInbox.cards() ?? [],
-      store._elicitationsCell.get(),
-      store._epoch?.executionInbox.entries() ?? [],
-      store._consumedInterrupts.idsOf(pause?.run_id, pause?.awaiting_round),
-    ),
-  );
-}
-
-export function noteInterruptAnswerConsumed(
-  store: AssistantConversationStore,
-  runId: string,
-  interruptId: string,
-  round: number,
-): void {
-  if (store._consumedInterrupts.note(runId, interruptId, round)) {
-    publishStore(store);
-  }
-}
-
-export function composerSnapshotOf(
-  store: AssistantConversationStore,
-): ComposerContract {
-  return {
-    busy: busyOf(store),
-    pendingSend: store._pendingSend,
-    sendMessage: store.sendMessage,
-    pendingEcho: store._pendingEcho,
-    composerRefocusPending: store._composerRefocusPending,
-    markComposerRefocusHandled: store.markComposerRefocusHandled,
-    stopping: store._stopping,
-    stopTurn: store.stopTurn,
-    modelPick: store._modelPick,
-    setModelPick: store.setModelPick,
-    composerInput: store._composerInput,
-    setDraft: store.setComposerDraft,
-    setAttachments: store.setComposerAttachments,
-    noteComposerFocus: store.noteComposerFocus,
-    takeComposerCaretReturn: store.takeComposerCaretReturn,
-  };
-}
-
-export function busyOf(store: AssistantConversationStore): boolean {
-  // The composer lock, Stop button and interruption banner follow the
-  // turn record: a parked turn is never busy, whatever a
-  // stale thread.busy says — there is no run to stop, and the visitor's
-  // next message is the designed withdraw path.
-  return (
-    ((store._active?.thread.busy ?? false) &&
-      store._newestTurn?.status !== "parked") ||
-    store._pendingSend
-  );
-}
-function _publishTurnMeta(store: AssistantConversationStore): void {
-  const ledger = store._active?.ledger ?? null;
-  const version = ledger?.version ?? -1;
-  if (
-    ledger === store._publishedMetaLedger &&
-    version === store._publishedMetaVersion
-  ) {
-    return;
-  }
-  store._publishedMetaLedger = ledger;
-  store._publishedMetaVersion = version;
-  store._turnMetaCell.set(
-    ledger !== null ? ledger.metaByMessageId() : new Map(),
-  );
-}
-
-function _sameConversationSnapshot(
-  a: ConversationSnapshot,
-  b: ConversationSnapshot,
-): boolean {
-  return (
-    a.active === b.active &&
-    a.threads === b.threads &&
-    a.historyExpected === b.historyExpected &&
-    a.threadOpening === b.threadOpening &&
-    a.reconnectNonce === b.reconnectNonce &&
-    a.sendError === b.sendError &&
-    a.turnFailure === b.turnFailure &&
-    a.showInterruptionBanner === b.showInterruptionBanner &&
-    // Reference identity is sound: the store keeps the published gap
-    // reference-stable while its signature holds.
-    a.pendingDecisionGap === b.pendingDecisionGap
-  );
-}
-
-function _sameComposerSnapshot(
-  a: ComposerContract,
-  b: ComposerContract,
-): boolean {
-  return (
-    a.busy === b.busy &&
-    a.pendingSend === b.pendingSend &&
-    a.pendingEcho === b.pendingEcho &&
-    a.composerRefocusPending === b.composerRefocusPending &&
-    a.stopping === b.stopping &&
-    // composerInput is deliberately absent: it is the same cell object
-    // on every snapshot — its VALUE moves per keystroke, and only the
-    // composer's own useCell subscription pays for that.
-    sameModelPick(a.modelPick, b.modelPick)
-  );
-}

package/src/core/conversation-refresh.ts

@@ -1,128 +0,0 @@
-// Keeping the REST truth fresh: the conversation re-read every settle
-// signal funnels through (ticket-ordered so a stale read never overwrites
-// fresher truth), and the delivery-claim probe after a dispatch settle.
-
-import { getAssistantThread } from "../transport/serving-api.js";
-import { turnHoldsAStream } from "./connection-driver.js";
-import { adoptRefreshedDetail } from "./conversation-adoption.js";
-import type { AssistantConversationStore } from "./conversation-store.js";
-
-// The delivery-claim probe: a
-// dispatch settle only WAKES the thread's conversation entity — the
-// backend commits the delivery turn row asynchronously afterward, and may
-// decline outright. So the settle's re-read probes briefly for the opened
-// turn and goes quiet on a no-show; the idle re-read is the backstop. Its
-// own constants (the STOP_SETTLE_PROBES convention): retunable alone.
-const DELIVERY_CLAIM_PROBES = 8;
-const DELIVERY_CLAIM_PROBE_MS = 1_000;
-
-export async function refreshConversationFromStore(
-  store: AssistantConversationStore,
-): Promise<void> {
-  const active = store._active;
-  if (active === null) {
-    return;
-  }
-  store._refreshTicket += 1;
-  const ticket = store._refreshTicket;
-  try {
-    const detail = await getAssistantThread(
-      store.deps.session,
-      active.thread.id,
-    );
-    if (ticket <= store._refreshAdoptedThrough) {
-      // A later-issued refresh already adopted fresher truth (the
-      // monotonic-adoption premise at _refreshTicket).
-      return;
-    }
-    store._refreshAdoptedThrough = ticket;
-    adoptRefreshedDetail(store, detail);
-  } catch {
-    // A blip here self-heals: the next settled run refreshes again.
-  }
-}
-
-/** A surface's roster poll observed a dispatch settle — the
- *  one frontend-visible signal that a delivery turn may be about to
- *  open on this thread. Re-reads the conversation in a bounded burst
- *  until the claim shows up (a queued/working newest turn; adoption's
- *  publish attaches the stream through the ordinary connect sync), the
- *  thread changes, or the window exhausts QUIETLY — the entity may
- *  have declined the wake, and a no-show is not an error. Coalescing: a
- *  second settle mid-burst restarts the probe budget instead of
- *  stacking a burst. */
-export function noteDispatchSettledFromStore(
-  store: AssistantConversationStore,
-): void {
-  if (store._deliveryProbeRunning) {
-    store._deliveryProbeRearm = true;
-    return;
-  }
-  store._deliveryProbeRunning = true;
-  void _probeForDeliveryClaim(store).finally(() => {
-    store._deliveryProbeRunning = false;
-    store._deliveryProbeRearm = false;
-  });
-}
-
-async function _probeForDeliveryClaim(
-  store: AssistantConversationStore,
-): Promise<void> {
-  const threadId = store._active?.thread.id;
-  if (store._disposed || threadId === undefined) {
-    return;
-  }
-  if (turnHoldsAStream(store)) {
-    // The turn is live: the settle's consequences arrive on the stream
-    // (or the connect sync is already attaching) — nothing to probe.
-    return;
-  }
-  // THE LATCH'S CLOCK IS THE BEAT TIMER ALONE: the reads are fired
-  // single-flight and never awaited, so a stalled GET can never latch
-  // _deliveryProbeRunning (the premise: docs/connection-lifecycle.md).
-  let refreshInFlight = false;
-  const refreshOnce = () => {
-    if (refreshInFlight) {
-      return;
-    }
-    refreshInFlight = true;
-    // refreshConversation never rejects (its catch is the self-heal).
-    void store.refreshConversation().finally(() => {
-      refreshInFlight = false;
-    });
-  };
-  refreshOnce();
-  let probesLeft = DELIVERY_CLAIM_PROBES;
-  while (probesLeft > 0 || store._deliveryProbeRearm) {
-    if (store._deliveryProbeRearm) {
-      // Another settle landed mid-burst: its claim gets a full window.
-      store._deliveryProbeRearm = false;
-      probesLeft = DELIVERY_CLAIM_PROBES;
-    }
-    if (_deliveryProbeMoot(store, threadId) || turnHoldsAStream(store)) {
-      // Disposed or switched: this probe's thread is gone. Holds a
-      // stream: adopted — the publish's connect sync attached (or is
-      // attaching) and the stream owns the story from here.
-      return;
-    }
-    await settlesFor(DELIVERY_CLAIM_PROBE_MS);
-    probesLeft -= 1;
-    if (_deliveryProbeMoot(store, threadId)) {
-      return;
-    }
-    refreshOnce();
-  }
-}
-
-/** Whether the delivery-claim probe's thread is no longer this store's
- *  story — re-read behind every await (the stopTurn posture). */
-function _deliveryProbeMoot(
-  store: AssistantConversationStore,
-  threadId: string,
-): boolean {
-  return store._disposed || store._active?.thread.id !== threadId;
-}
-
-export function settlesFor(delayMs: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, delayMs));
-}