@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/block-timing-anchors.ts

@@ -0,0 +1,168 @@
+// The block-timing anchor model, pure of React: the recorder reads the
+// per-event server timestamp off every raw event that names a
+// block (a messageId or a toolCallId), folds it into that block's
+// earliest-start/latest-settle pair, and the resume store holds the map
+// across remounts. The indirection exists because the client carries no
+// per-event timestamp onto the messages it builds — this map is the
+// timing's only home on the client, and a snapshot-seeded reconnect
+// replays only past the cursor, so historical blocks keep their timing
+// from here alone. Absent timestamps
+// (old histories, synthesized frames) record nothing: to every consumer,
+// absence means unknown, never zero.
+
+import type { AgentSubscriber } from "@ag-ui/client";
+import { EventType } from "@ag-ui/core";
+
+import type { BlockTiming } from "./segment-timing.js";
+
+/**
+ * One observed instant folded into a block's pair, IN PLACE: the
+ * earliest observed value is the start, the latest the settle. True when
+ * the map moved — the caller's change signal. Deliberately NOT the
+ * neighbouring anchors' copy-on-write idiom: timing is the one
+ * high-frequency map (every block boundary moves it), and an immutable
+ * copy per fold is O(N) per write — O(N²) over an N-block replay — so
+ * this map mutates and the resume store's REVISION counter replaces
+ * identity as the change signal. ENTRIES stay immutable (a fold sets a
+ * fresh pair object, never mutates one), so a snapshot that copied the
+ * map never sees its held pairs change; re-applying a replayed sequence
+ * changes nothing (min/max are idempotent) and answers false.
+ */
+export function foldBlockTimingObserved(
+  timings: Map<string, BlockTiming>,
+  blockId: string,
+  observedAtMs: number,
+): boolean {
+  const existing = timings.get(blockId);
+  if (existing === undefined) {
+    timings.set(blockId, {
+      startedAtMs: observedAtMs,
+      settledAtMs: observedAtMs,
+    });
+    return true;
+  }
+  const startedAtMs =
+    existing.startedAtMs === null
+      ? observedAtMs
+      : Math.min(existing.startedAtMs, observedAtMs);
+  const settledAtMs =
+    existing.settledAtMs === null
+      ? observedAtMs
+      : Math.max(existing.settledAtMs, observedAtMs);
+  if (
+    startedAtMs === existing.startedAtMs &&
+    settledAtMs === existing.settledAtMs
+  ) {
+    return false;
+  }
+  timings.set(blockId, { startedAtMs, settledAtMs });
+  return true;
+}
+
+/**
+ * A defensive copy for seeding transcript state from the resume store:
+ * entries that are not a well-formed pair are dropped rather than
+ * rendered (or crashed on) — a dropped pair degrades that block's
+ * duration to unknown until the next full replay, never a crash.
+ */
+export function wellFormedBlockTimingAnchorsOf(
+  stored: ReadonlyMap<string, BlockTiming>,
+): ReadonlyMap<string, BlockTiming> {
+  const seeded = new Map<string, BlockTiming>();
+  const entries = stored as ReadonlyMap<unknown, unknown>;
+  for (const [blockId, timing] of entries) {
+    if (typeof blockId !== "string" || !_isWellFormedTiming(timing)) {
+      continue;
+    }
+    seeded.set(blockId, timing);
+  }
+  return seeded;
+}
+
+// Only block BOUNDARIES contribute: a delta's timestamp can only land
+// between its block's start and end, so recording it would tighten
+// nothing while republishing the anchors snapshot on every batch. Built
+// from the shipped EventType enum, never raw strings, so a typo or an
+// upstream rename fails the build instead of silently degrading a
+// block's duration to unknown.
+const BLOCK_BOUNDARY_EVENT_TYPES: ReadonlySet<string> = new Set([
+  EventType.TEXT_MESSAGE_START,
+  EventType.TEXT_MESSAGE_END,
+  EventType.REASONING_START,
+  EventType.REASONING_END,
+  EventType.REASONING_MESSAGE_START,
+  EventType.REASONING_MESSAGE_END,
+  EventType.TOOL_CALL_START,
+  EventType.TOOL_CALL_END,
+  EventType.TOOL_CALL_RESULT,
+]);
+
+/**
+ * Records each timestamped block-boundary event against the block it
+ * names. The block id is the durable join — the event's own messageId
+ * or toolCallId — never adjacency; an event naming no block (lifecycle
+ * frames, thread markers) contributes nothing here.
+ */
+export function blockTimingRecorder(
+  onTimingObserved: (blockId: string, observedAtMs: number) => void,
+): AgentSubscriber {
+  return {
+    onEvent({ event }) {
+      if (!BLOCK_BOUNDARY_EVENT_TYPES.has(event.type)) {
+        return;
+      }
+      const observedAtMs = _timestampOf(event);
+      if (observedAtMs === undefined) {
+        return;
+      }
+      const blockId = _blockIdOf(event);
+      if (blockId !== undefined) {
+        onTimingObserved(blockId, observedAtMs);
+      }
+    },
+  };
+}
+
+function _timestampOf(event: unknown): number | undefined {
+  if (typeof event !== "object" || event === null) {
+    return undefined;
+  }
+  const { timestamp } = event as { timestamp?: unknown };
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) {
+    return undefined;
+  }
+  return timestamp;
+}
+
+/** The durable block id an event names: its toolCallId when it is a
+ *  tool-family event, else its messageId (text and reasoning families).
+ *  Narrowed from unknown — the wire is distrusted by contract. */
+function _blockIdOf(event: unknown): string | undefined {
+  if (typeof event !== "object" || event === null) {
+    return undefined;
+  }
+  const { toolCallId, messageId } = event as {
+    toolCallId?: unknown;
+    messageId?: unknown;
+  };
+  if (typeof toolCallId === "string" && toolCallId !== "") {
+    return toolCallId;
+  }
+  if (typeof messageId === "string" && messageId !== "") {
+    return messageId;
+  }
+  return undefined;
+}
+
+function _isWellFormedTiming(timing: unknown): timing is BlockTiming {
+  if (typeof timing !== "object" || timing === null) {
+    return false;
+  }
+  const { startedAtMs, settledAtMs } = timing as {
+    startedAtMs?: unknown;
+    settledAtMs?: unknown;
+  };
+  const halfIsWellTyped = (half: unknown): boolean =>
+    half === null || (typeof half === "number" && Number.isFinite(half));
+  return halfIsWellTyped(startedAtMs) && halfIsWellTyped(settledAtMs);
+}

package/src/core/companion-drawer-flag.ts

@@ -0,0 +1,22 @@
+import { ObservableCell, type ReadonlyCell } from "./observable-cell.js";
+
+// The companion drawer's open flag, as page-level state rather than a
+// component's: the host may remount the whole assistant tree between
+// routes (the dashboard's route shells differ), and the drawer must land
+// on the destination exactly as the last writer left it. Three writers:
+// the mark and the drawer's own controls, the navigate handler (a tool
+// navigation opens it), and a full surface taking the floor (closes it).
+// Module-scoped like the surface registry — the handler runs outside any
+// React tree — and in memory only: a full page load starts closed.
+
+const _openCell = new ObservableCell<boolean>(false);
+
+export const companionDrawerOpen: ReadonlyCell<boolean> = _openCell;
+
+export function openCompanionDrawer(): void {
+  _openCell.set(true);
+}
+
+export function closeCompanionDrawer(): void {
+  _openCell.set(false);
+}

package/src/core/companion-presence.ts

@@ -0,0 +1,32 @@
+import type { AssistantSurfacePresence } from "./surface-registry.js";
+
+// The companion's presence rule, as a pure derivation: which chrome the
+// widget shows, answered from inputs it already holds. The drawer flag's
+// writers live in core/companion-drawer-flag; this module only reads it.
+
+export type CompanionChrome = "companion" | "drawer" | "none";
+
+export interface CompanionChromeInput {
+  surfaces: AssistantSurfacePresence;
+  /** The corner drawer is open (widget state). */
+  expanded: boolean;
+}
+
+export function companionChromeOf(
+  input: CompanionChromeInput,
+): CompanionChrome {
+  if (_yieldsToAnotherSurface(input.surfaces)) {
+    return "none";
+  }
+  return input.expanded ? "drawer" : "companion";
+}
+
+/** A full-surface chrome anywhere hides everything: that surface is the
+ *  assistant now. The open palette hides the whole cluster too, drawer
+ *  included: the widget keeps its expanded flag, so the drawer returns the
+ *  moment the palette closes — but while the palette holds the transcript
+ *  lease the drawer would render as a hollow shell behind the modal, and
+ *  two gutted twins of one surface read as broken. */
+function _yieldsToAnotherSurface(surfaces: AssistantSurfacePresence): boolean {
+  return surfaces.fullSurfaceMounted || surfaces.transientOpen;
+}

package/src/core/composer-input-state.ts

@@ -0,0 +1,94 @@
+// The composer's input plane: the model pick, the unsaved draft and its
+// staged attachments, the focus/caret bookkeeping, and the reset that
+// re-scopes them — the store-side half of the composer's contract.
+
+import type {
+  AttachmentDraft,
+  ComposerModelPick,
+} from "./conversation-contract.js";
+import { publishStore } from "./conversation-publish.js";
+import type { AssistantConversationStore } from "./conversation-store.js";
+
+export function setModelPickFromStore(
+  store: AssistantConversationStore,
+  pick: ComposerModelPick,
+): void {
+  store._modelPick = pick;
+  store._modelPickDirty = true;
+  publishStore(store);
+}
+
+// Value-or-updater on purpose (the useState contract): the upload
+// continuations and the send-refusal restore are read-modify-write over
+// truth that may have moved, and as the STORE's stable arrows they stay
+// correct across any composer remount. They write the input cell directly,
+// never publishStore: a keystroke moves no conversation-plane state. Only
+// adoption, abandon and a landed send move the scope; it rides through here.
+export function setComposerDraftFromStore(
+  store: AssistantConversationStore,
+  next: string | ((current: string) => string),
+): void {
+  const current = store._composerInput.get();
+  store._composerInput.set({
+    ...current,
+    draft: typeof next === "function" ? next(current.draft) : next,
+  });
+}
+
+export function setComposerAttachmentsFromStore(
+  store: AssistantConversationStore,
+  next:
+    | readonly AttachmentDraft[]
+    | ((current: readonly AttachmentDraft[]) => readonly AttachmentDraft[]),
+): void {
+  const current = store._composerInput.get();
+  store._composerInput.set({
+    ...current,
+    attachments: typeof next === "function" ? next(current.attachments) : next,
+  });
+}
+
+// Clearing is (re)scoping: every reset names the conversation-context the
+// fresh, empty input belongs to — the identity the send-refusal guard
+// compares against. Both arms set UNCONDITIONALLY: a conversation-less
+// reset MINTS a fresh token even over an empty input (a null hole here let
+// an abandon no-op and leave the old scope alive for the refusal restore).
+// A caret owed to the departed conversation dies with it; the DOM-plane
+// focus record is NOT touched — it tracks the element, not the conversation.
+export function resetComposerInput(
+  store: AssistantConversationStore,
+  threadId: string | null,
+): void {
+  store._composerCaretReturnPending = null;
+  store._composerInput.set({
+    scope:
+      threadId !== null
+        ? `t:${threadId}`
+        : `u:${String(store._nextUnboundScope++)}`,
+    draft: "",
+    attachments: [],
+  });
+}
+
+export function noteComposerFocusFromStore(
+  store: AssistantConversationStore,
+  owner: string | null,
+): void {
+  store._composerFocusOwned = owner;
+}
+
+// Take-semantics scoped to the OWNER: every keyed transcript remounts on
+// one nonce bump and every fresh composer takes at mount, in tree order —
+// an unscoped take let a bystander surface consume the one-shot without
+// using it. Only the owner's take consumes; the owner then delivers or
+// forfeits its return in the same breath, which is the right lifetime.
+export function takeComposerCaretReturnFromStore(
+  store: AssistantConversationStore,
+  surface: string,
+): boolean {
+  if (store._composerCaretReturnPending !== surface) {
+    return false;
+  }
+  store._composerCaretReturnPending = null;
+  return true;
+}

package/src/core/composer-policy.ts

@@ -0,0 +1,144 @@
+// The composer's pure policy leaf, React-free and transport-free: the
+// members both composers — the package's slab and the dashboard
+// playground's — apply to a draft before anything is sent. One home
+// so the fork ledger has nothing to pin: the per-message
+// bounds are felt while typing, the cap slots count only drafts that
+// could still ride, the pick-time size check speaks the served kind's
+// cap, and Escape/Enter mean the same thing in every composer.
+
+import {
+  ASSISTANT_MESSAGE_MAX_CHARS,
+  type ServingAttachment,
+} from "../contract/threads.js";
+import type { AttachmentKind } from "../generated/models/index.js";
+
+// Show the countdown only once it starts to matter.
+export const CHARACTER_COUNT_VISIBLE_FROM = ASSISTANT_MESSAGE_MAX_CHARS - 400;
+
+// One attached file's composer-side life: uploading (declare → PUT →
+// finalize in flight), ready (sendable), or failed (blocks the send until
+// removed — a silent drop would send less than the author believes). The
+// settled attachment is the door's own shape: the serving attachment for
+// the package, the dashboard's response for the playground.
+export interface AttachmentDraft<A = ServingAttachment> {
+  localId: number;
+  filename: string;
+  byteSize: number;
+  status: "uploading" | "ready" | "failed";
+  attachment?: A;
+  error?: string;
+}
+
+// Chip ids are minted here, module-scoped, so they survive any composer
+// remount and never collide across the composers one page may mount.
+let nextDraftId = 1;
+
+export function mintAttachmentDraftId(): number {
+  return nextDraftId++;
+}
+
+// The one reading of a draft's failed state: a refused pick or a failed
+// upload. Every surface asks this rather than comparing the word — the
+// dashboard's collapse-layer law keeps status literals out of its
+// components, and one predicate keeps the two composers agreeing on
+// what "failed" means.
+export function attachmentDraftFailed(item: {
+  status: AttachmentDraft["status"];
+}): boolean {
+  return item.status === "failed";
+}
+
+// What counts against the per-message cap: only drafts that could still
+// ride the message. A failed chip never sends, so it never spends a
+// slot — it holds visible ground until removed, nothing more.
+export function capSlotsSpentBy(
+  attachments: readonly { status: AttachmentDraft["status"] }[],
+): number {
+  return attachments.filter((item) => !attachmentDraftFailed(item)).length;
+}
+
+// The pick-time size cap: the kind's own ceiling when the browser's
+// MIME type names one confidently and the caps serve that kind, else the
+// widest cap served — the pre-check must never be stricter than the
+// server's sniffed truth.
+export function pickCapOf(
+  file: File,
+  caps: Readonly<Partial<Record<AttachmentKind, number>>>,
+): { bytes: number; label: string } {
+  const type = file.type;
+  if (type.startsWith("image/") && caps.image !== undefined) {
+    return { bytes: caps.image, label: "an image" };
+  }
+  if (
+    (type === "application/pdf" || type.startsWith("text/")) &&
+    caps.document !== undefined
+  ) {
+    return { bytes: caps.document, label: "a document" };
+  }
+  if (type.startsWith("video/") && caps.video !== undefined) {
+    return { bytes: caps.video, label: "a video" };
+  }
+  if (type.startsWith("audio/") && caps.audio !== undefined) {
+    return { bytes: caps.audio, label: "an audio file" };
+  }
+  return {
+    bytes: Math.max(...Object.values(caps)),
+    label: "a file",
+  };
+}
+
+// The slice of a keyboard event the handlers read — React's
+// KeyboardEvent satisfies it structurally, so this leaf never imports
+// React.
+export interface ComposerKeyEvent {
+  key: string;
+  shiftKey: boolean;
+  preventDefault: () => void;
+  stopPropagation: () => void;
+}
+
+/**
+ * The composer's two keyboard verbs, bound as composerKeys on the textarea
+ * and stopOnEscape on the stop button. Enter submits (Shift+Enter is a
+ * newline). Escape while the assistant is answering is the stop shortcut,
+ * claimed ONLY when stopTurn can actually act: the two windows
+ * where it no-ops pass through unclaimed — the message POST (pendingSend,
+ * the store's truth, not a component's sending mirror; no turn exists to
+ * stop yet) and the "Stopping…" beat itself (the re-entry guard refuses a
+ * second stop) — because a swallowed no-op Escape is how a palette,
+ * drawer or pane gets wedged. Bound on the textarea and the stop button,
+ * the two focus homes of a busy composer.
+ */
+export function composerKeyHandlersOf(input: {
+  busy: boolean;
+  pendingSend: boolean;
+  stopping: boolean;
+  stopTurn: () => void | Promise<void>;
+  submit: () => void | Promise<void>;
+}): {
+  stopOnEscape: (event: ComposerKeyEvent) => void;
+  composerKeys: (event: ComposerKeyEvent) => void;
+} {
+  const { busy, pendingSend, stopping, stopTurn, submit } = input;
+  function submitOnEnter(event: ComposerKeyEvent): void {
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault();
+      void submit();
+    }
+  }
+  function stopOnEscape(event: ComposerKeyEvent): void {
+    if (event.key !== "Escape" || !busy || pendingSend || stopping) {
+      return;
+    }
+    event.preventDefault();
+    event.stopPropagation();
+    void stopTurn();
+  }
+  return {
+    stopOnEscape,
+    composerKeys(event) {
+      stopOnEscape(event);
+      submitOnEnter(event);
+    },
+  };
+}

package/src/core/connect-gate.ts

@@ -0,0 +1,149 @@
+// The conversation gate: what stands between this visitor
+// and their next send, as one client-side shape with two producers — the
+// assistant-config read's pre-flight projection (the gate is known before
+// anyone types) and a send refusal (the race window where the projection
+// was stale). ConversationView renders it in the composer's place; the
+// provider chip and the gate card are its readers.
+
+import type {
+  ConnectProjectionResponse,
+  SubscriptionProvider,
+} from "../generated/models/index.js";
+import { ServingApiError } from "../transport/serving-error.js";
+
+/** Why a connect gate is asking: the free preview ran out (a first
+ *  connect) or a connected plan's credential died (a reconnect). The
+ *  contract grows reasons additively; unknown values read as
+ *  auth_bounced — the conservative ask. */
+type ConnectGateReason = "taster_exhausted" | "auth_bounced";
+
+export type ConversationGate =
+  | { kind: "none" }
+  | { kind: "sign_in" }
+  | {
+      kind: "connect";
+      reason: ConnectGateReason;
+      providers: SubscriptionProvider[];
+    }
+  | { kind: "wait"; retryAtMs: number | null }
+  | { kind: "verifying" };
+
+export const NO_GATE: ConversationGate = { kind: "none" };
+
+/** Whether two gates say the same thing. The projection mints a fresh
+ *  object every read, so the registry dedupes on substance before
+ *  writing its cell — an unchanged gate must not notify (each notify
+ *  re-renders every gate consumer, and a re-render storm under a
+ *  4s re-read chain is how a bounded poll turns unbounded). */
+export function gatesEqual(a: ConversationGate, b: ConversationGate): boolean {
+  if (a.kind !== b.kind) {
+    return false;
+  }
+  if (a.kind === "connect" && b.kind === "connect") {
+    // Joined, not compared elementwise: the provider union has one
+    // member today, and TS narrows an element comparison to
+    // always-true (the vocabulary grows additively).
+    return (
+      a.reason === b.reason && a.providers.join(" ") === b.providers.join(" ")
+    );
+  }
+  if (a.kind === "wait" && b.kind === "wait") {
+    return a.retryAtMs === b.retryAtMs;
+  }
+  return true;
+}
+
+/** The projection's gate, client-shaped. An unknown gate value reads as
+ *  none — the contract's growth rule; the send door stays the truth. */
+export function gateOfProjection(
+  connect: ConnectProjectionResponse | undefined,
+): ConversationGate {
+  if (connect === undefined) {
+    return NO_GATE;
+  }
+  switch (connect.gate) {
+    case "sign_in":
+      return { kind: "sign_in" };
+    case "connect":
+      return {
+        kind: "connect",
+        reason: _reasonOf(connect.reason),
+        providers: connect.providers,
+      };
+    case "wait":
+      return { kind: "wait", retryAtMs: _retryAtMsOf(connect) };
+    case "verifying":
+      return { kind: "verifying" };
+    default:
+      return NO_GATE;
+  }
+}
+
+/** A send refusal's gate, or null when the refusal is not a gate (a rate
+ *  limit, a busy thread — the banner's story, not the composer's). */
+export function gateOfRefusal(error: unknown): ConversationGate | null {
+  if (!(error instanceof ServingApiError)) {
+    return null;
+  }
+  if (error.code === "ASSISTANT_SIGN_IN_REQUIRED") {
+    return { kind: "sign_in" };
+  }
+  if (error.code === "SUBSCRIPTION_CONNECT_REQUIRED") {
+    const details = _connectDetailsOf(error);
+    return {
+      kind: "connect",
+      reason: _reasonOf(details.reason),
+      providers: details.providers,
+    };
+  }
+  if (error.code === "SUBSCRIPTION_CANNOT_PAY") {
+    if (error.retryAfterSeconds !== null) {
+      return {
+        kind: "wait",
+        retryAtMs: Date.now() + error.retryAfterSeconds * 1000,
+      };
+    }
+    return { kind: "verifying" };
+  }
+  return null;
+}
+
+// --- the details reader --------------------------------------------------------
+
+interface ConnectRefusalDetails {
+  reason: string | null;
+  providers: SubscriptionProvider[];
+}
+
+/** The refusal envelope's structured half, read leniently: details is
+ *  `unknown` on the wire by design, and a malformed shape must degrade
+ *  to an empty ask, never throw under an error handler. */
+function _connectDetailsOf(error: ServingApiError): ConnectRefusalDetails {
+  const details = error.details;
+  if (typeof details !== "object" || details === null) {
+    return { reason: null, providers: [] };
+  }
+  const reason = "reason" in details ? details.reason : null;
+  const named = "providers" in details ? details.providers : null;
+  const providers = Array.isArray(named)
+    ? named.filter((value): value is SubscriptionProvider =>
+        _isAKnownProvider(value),
+      )
+    : [];
+  return { reason: typeof reason === "string" ? reason : null, providers };
+}
+
+function _isAKnownProvider(value: unknown): boolean {
+  return value === "openai_chatgpt";
+}
+
+function _reasonOf(reason: string | null): ConnectGateReason {
+  return reason === "taster_exhausted" ? "taster_exhausted" : "auth_bounced";
+}
+
+function _retryAtMsOf(connect: ConnectProjectionResponse): number | null {
+  if (connect.retry_after_seconds === null) {
+    return null;
+  }
+  return Date.now() + connect.retry_after_seconds * 1000;
+}