@teaflask/assistant 0.3.0 → 0.6.0

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

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

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

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

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

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

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