@teaflask/assistant 0.0.0 → 0.3.0

package/src/headless.ts

@@ -0,0 +1,189 @@
+// The bring-your-own-frontend entry: the provider and the
+// live-session hooks, with none of the package chrome. A host mounts
+// <TeaflaskAssistantProvider> alone, DRIVES the conversation through
+// useAssistantConversation()'s contract, the composer contract, and the
+// approval/elicitation surfaces, and RENDERS the replies through
+// useTranscript()'s read surface — bindings over the shared
+// store, never the machinery. The read surface lives here, not on
+// ./transcript, because binding to a live store needs the transport the
+// provider constructs; the anchor RECORDERS stay on ./transcript for
+// own-wire hosts. The serving session internals stay private on purpose;
+// tests/bundle-closure.test.ts holds this entry's static closure chrome-free.
+
+export {
+  TeaflaskAssistantProvider,
+  type TeaflaskAssistantProviderProps,
+} from "./components/teaflask-assistant-provider.js";
+// The provider props' own field types (the nameability law: tests/headless-
+// nameability walks every export's public fields and fails on any
+// src-declared type a host cannot name from this entry).
+// AssistantSuggestionInput lives in conversation-view.tsx, a chrome module —
+// type-only, so the closure stays chrome-free.
+export type {
+  AssistantTheme,
+  AssistantThemeDarkTokens,
+  AssistantThemeMode,
+  AssistantThemeTokens,
+} from "./appearance/theme.js";
+export type {
+  ActionsAdapter,
+  ActionIntent,
+  ActionIntentAction,
+  CookiesActionsAdapter,
+  HeadersActionsAdapter,
+  RequestActionsAdapter,
+} from "./contract/actions-adapter.js";
+export type {
+  ApprovalSubmitTelemetryEvent,
+  AssistantTelemetryEvent,
+  StreamFailedTelemetryEvent,
+} from "./contract/telemetry.js";
+export type {
+  AssistantSuggestion,
+  AssistantSuggestionInput,
+  AssistantSuggestionKind,
+} from "./components/conversation-view.js";
+export type {
+  IconAdapter,
+  // JsonSchema (ToolViewCall.argsSchema) is demanded by the nameability law;
+  // exported here exactly as the root exports it.
+  JsonSchema,
+  ToolViewAdapter,
+  ToolViewCall,
+  ToolViewInstance,
+  ToolViewProps,
+  ToolViewRegistration,
+  ToolViewRegistry,
+} from "./core/tool-view.js";
+export {
+  useAssistantConversation,
+  type AssistantConversation,
+} from "./components/use-assistant-conversation.js";
+export {
+  useConversation,
+  type ComposerContract,
+} from "./components/conversation-context.js";
+export {
+  useApprovals,
+  type ApprovalSurface,
+} from "./components/approval-context.js";
+export {
+  useElicitations,
+  type ElicitationSurface,
+} from "./components/elicitation-context.js";
+// The composer contract's per-keystroke half rides its own cell
+// (composerInput) so reading it never re-renders the coarse contract —
+// useCell is the one React seam onto a cell, exported so a host's own
+// composer reads it the way the package chrome does.
+export { useCell } from "./components/use-store-cell.js";
+export type { ReadonlyCell } from "./core/observable-cell.js";
+// The types the hooks' return values are made of — a public field's type
+// must be nameable by the host reading it. Type-only where the backing
+// module is machinery (the store class itself is never exported).
+export type { ApprovalCardModel } from "./core/approval-inbox.js";
+export type {
+  ActiveConversation,
+  ApprovalDecisionInput,
+  AttachmentDraft,
+  ComposerInput,
+  ComposerModelPick,
+} from "./core/conversation-store.js";
+// The composer contract's remaining field types (the
+// ServingErrorCodeOnTheWire rule again): sendMessage's attachments,
+// setModelPick's pick and its effort — a host writing
+// useState<ComposerModelPick | null> or a helper over the attachment
+// list must be able to name them.
+export type {
+  ServingAttachment,
+  ThreadModelPick,
+  TurnAttachment,
+} from "./contract/threads.js";
+export type { ServedThinkingEffort } from "./contract/assistant-config.js";
+export type {
+  ElicitationCardModel,
+  QuestionSetCardModel,
+} from "./core/elicitation-cards.js";
+export type {
+  QuestionModel,
+  QuestionOptionModel,
+} from "./core/elicitation-pickers.js";
+export type {
+  QuestionAnswerDraft,
+  QuestionDraftStore,
+  QuestionSetDraft,
+} from "./core/question-drafts.js";
+export type { PendingDecisionGap } from "./core/pending-decision-gap.js";
+export type { ServingAssistantThread } from "./contract/threads.js";
+export { ServingApiError } from "./transport/serving-error.js";
+// ServingApiError.code's type — a public field's type must be nameable
+// by the host reading it.
+export type { ServingErrorCodeOnTheWire } from "./contract/errors.js";
+// The transcript read surface: rendering the assistant's
+// replies from this entry. Mounting the hook registers transcript
+// presence with the store — presence is what GUARANTEES the epoch
+// connects (once, so history paints by full replay), and what arms the
+// idle re-read. A lease-less store connects only while the newest turn
+// is queued/working (bounded budget — the connection truth table in
+// core/connection-driver.ts), and that connect is the same full replay; what it
+// never gets is a connect while no turn is live, so a reopened settled
+// thread's messages stay empty without the hook.
+export {
+  useTranscript,
+  type TranscriptSurface,
+} from "./components/use-transcript.js";
+// The projection and its row types, re-exported from their core modules.
+// Where a name is also on ./transcript (transcriptRowsOf, TranscriptRow,
+// Message, MarkerAnchorsSnapshot, ToolCallDisplay, SubagentGroupRow,
+// SubagentGroupEntry, DispatchReceipt) it is the SAME symbol, so a host may
+// mix imports freely; the rest are public here (several row members also
+// ride ./transcript-ui). transcriptRowsOf and
+// withPendingUserEcho ride as values so a host projecting the raw reads
+// never needs a second entry; Message is re-exported so a host never takes
+// its own dependency on the @ag-ui packages.
+export {
+  transcriptRowsOf,
+  withPendingUserEcho,
+  type AssistantTextRow,
+  type PendingUserEcho,
+  type ReasoningRow,
+  type SubagentDeliveryRow,
+  type ToolCallRow,
+  type TranscriptRow,
+  type TurnFailedReceiptsRow,
+  type UserMessageRow,
+} from "./core/transcript-rows.js";
+export type { Message } from "@ag-ui/core";
+export type { MarkerAnchorsSnapshot } from "./core/connection-epoch.js";
+// The row types' own field types (the nameability law again): every
+// named src-declared type a host can observe one level down from the
+// surface must be nameable from this entry.
+export type {
+  DispatchReceipt,
+  SubagentGroupEntry,
+  SubagentGroupRow,
+} from "./core/subagent-rows.js";
+export type { AnchoredTurnFailReceipts } from "./core/turn-failed-anchors.js";
+// AnchoredTurnFailReceipts is an alias of AnchoredReceipts, and the
+// checker records the interface behind the alias — both are nameable.
+export type { AnchoredReceipts } from "./core/receipt-anchors.js";
+export type { DeliveredResult } from "./core/subagent-delivery-anchors.js";
+export type { MemoryUpdated } from "./core/memory-provenance-anchors.js";
+export type { BlockTiming } from "./core/segment-timing.js";
+export type {
+  ToolCallDisplay,
+  ToolCallState,
+} from "./core/tool-call-display.js";
+export type { ToolCallSchemas } from "./core/tool-schema-anchors.js";
+export type { TurnUsage } from "./core/turn-usage-anchors.js";
+export type {
+  AssistantActivityResult,
+  AssistantActivitySnapshot,
+} from "./core/activity.js";
+export type { TurnStatus } from "./contract/threads.js";
+export type { UserTurnMeta } from "./core/user-turn-ledger.js";
+// Sign-out belongs to a bring-your-own-frontend host too: without this,
+// the README's sign-out instruction pulls the ROOT barrel (transcript,
+// markdown and all) into a headless bundle for one localStorage helper.
+// Zero closure cost — persistence/stored-thread already rides this
+// entry via the conversation store.
+export { resetAssistant } from "./persistence/stored-thread.js";

package/src/index.ts

@@ -0,0 +1,218 @@
+// The package's root public API. The exports map exposes only this
+// entry, ./activity, ./headless, ./markdown, ./scroll, ./transcript,
+// ./styles.css and ./package.json — deep imports are structurally
+// impossible.
+
+export type {
+  AssistantTheme,
+  AssistantThemeDarkTokens,
+  AssistantThemeMode,
+  AssistantThemeTokens,
+} from "./appearance/theme.js";
+export {
+  TeaflaskAssistantProvider,
+  type TeaflaskAssistantProviderProps,
+} from "./components/teaflask-assistant-provider.js";
+// The batteries-included root: provider + companion + palette
+// + the ⌘K trigger in one mount. The granular pieces below stay public
+// for hosts that want to own the composition.
+export {
+  TeaflaskAssistant,
+  type TeaflaskAssistantHandle,
+  type TeaflaskAssistantProps,
+} from "./components/teaflask-assistant.js";
+export {
+  AssistantPage,
+  type AssistantChrome,
+  type AssistantPageProps,
+} from "./components/assistant-page.js";
+export type {
+  AssistantSuggestion,
+  AssistantSuggestionInput,
+  AssistantSuggestionKind,
+} from "./components/conversation-view.js";
+export {
+  AssistantPalette,
+  type AssistantPaletteProps,
+} from "./components/assistant-palette.js";
+// The read-only activity feed: presence without a transcript.
+// Deliberately minimal — the store itself stays internal.
+export { useAssistantActivity } from "./components/use-assistant-activity.js";
+export type {
+  AssistantActivityResult,
+  AssistantActivitySnapshot,
+} from "./core/activity.js";
+// Named by AssistantActivitySnapshot.pendingDecisionGap: a
+// public field's type must be nameable by the host reading it.
+export type { PendingDecisionGap } from "./core/pending-decision-gap.js";
+export { resetAssistant } from "./persistence/stored-thread.js";
+export { ServingApiError } from "./transport/serving-error.js";
+
+// The contract mirror — the executable half of the serving contract
+// (on any disagreement, the markdown wins).
+export type {
+  ActionIntent,
+  ActionIntentAction,
+  ActionsAdapter,
+  CookiesActionsAdapter,
+  HeadersActionsAdapter,
+  RequestActionsAdapter,
+} from "./contract/actions-adapter.js";
+export type {
+  ServingErrorBody,
+  ServingErrorCode,
+  ServingErrorCodeOnTheWire,
+  ServingErrorEnvelope,
+} from "./contract/errors.js";
+export type {
+  EndUserIdentity,
+  MintVisitorTokenRequest,
+  MintVisitorTokenResponse,
+  PublishableKeyMode,
+  VisitorTier,
+  WhoamiResponse,
+} from "./contract/identity.js";
+export type {
+  SubscriptionCredentialState,
+  SubscriptionDeviceAuthorization,
+  SubscriptionDeviceAuthorizationPoll,
+  SubscriptionProvider,
+  SubscriptionStatus,
+} from "./contract/subscriptions.js";
+export {
+  ASSISTANT_MESSAGE_MAX_CHARS,
+  type ApprovalDelivery,
+  type AssistantThreadDetailResponse,
+  type ResolveTurnApprovalRequest,
+  type ResolveTurnApprovalResponse,
+  type SendAssistantMessageRequest,
+  type SendAssistantMessageResponse,
+  type ServingAssistantThread,
+  type ServingAssistantTurn,
+  type TurnApprovalDecision,
+  type TurnStatus,
+} from "./contract/threads.js";
+export {
+  APPROVAL_REQUESTED_EVENT_NAME,
+  MEMORY_UPDATED_EVENT_NAME,
+  RUN_RESUMED_EVENT_NAME,
+  TURN_USAGE_RECORDED_EVENT_NAME,
+  type ApprovalRequestedPayload,
+  type AssistantStreamEventType,
+  type RunResumedPayload,
+} from "./contract/events.js";
+
+// The replay-stable metadata contract: per-event server
+// timestamps reduced into per-fold durations (the typed unknown-vs-
+// sub-second law the transcript's fold rows render from), honest turn usage,
+// and memory provenance. See docs/replay-metadata-contract.md
+// for the decision record.
+export {
+  activeFoldElapsedOf,
+  settledFoldDurationOf,
+  type BlockTiming,
+  type SegmentDuration,
+} from "./core/segment-timing.js";
+export { usageIsFinal, type TurnUsage } from "./core/turn-usage-anchors.js";
+export type { MemoryUpdated } from "./core/memory-provenance-anchors.js";
+export type {
+  ApprovalSubmitDropReason,
+  ApprovalSubmitTelemetryEvent,
+  AssistantTelemetryEvent,
+  StreamFailedTelemetryEvent,
+  StreamFailureClass,
+} from "./contract/telemetry.js";
+
+// The presentation contract: the tool-call display envelope
+// and the one-presenter-many-consumers resolver every transcript
+// surface reads its slots from. See docs/presentation-architecture.md
+// for the decision record.
+export type {
+  ToolCallDisplay,
+  ToolCallState,
+  ToolCallViewModel,
+} from "./core/tool-call-display.js";
+export {
+  TOOL_CALL_ICONS,
+  toolCallPresentationOf,
+  type ToolCallIcon,
+  type ToolCallPresentation,
+} from "./core/tool-call-presentation.js";
+// The tool-view contract (tool-views.md): one view per tool call,
+// resolved by the presenter over four rungs — host registry by wire
+// {key, version}, host registry by exact tool name, package built-ins
+// under the reserved teaflask.* namespace, and the package default. The
+// imperative adapter is the canonical authoring form; reactToolView is
+// the React sugar over the same lifecycle. Registration is `toolViews`
+// — the provider prop in React, the same-named JS property on the
+// script-tag elements — trusted host code only, code never
+// rides the wire.
+export {
+  actionToolName,
+  actionToolViews,
+  resolvedToolViewsOf,
+  type IconAdapter,
+  type JsonSchema,
+  type ResolvedToolView,
+  type ResolvedToolViewIcon,
+  type ToolViewAdapter,
+  type ToolViewCall,
+  type ToolViewInstance,
+  type ToolViewProps,
+  type ToolViewRegistration,
+  type ToolViewRegistry,
+  type ToolViewResolution,
+  type ToolViewThemeMode,
+} from "./core/tool-view.js";
+export { reactToolView } from "./components/react-tool-view.js";
+// The tool-view parts (tool-views/parts.tsx): the React spelling of the
+// card, row, facts, caption, body, badge, note and skeleton vocabulary
+// the built-ins paint with — a host view composes these and reads as one
+// system with ours.
+export {
+  ToolViewBadge,
+  ToolViewBody,
+  ToolViewBones,
+  ToolViewScroll,
+  ToolViewTitle,
+  ToolViewCaption,
+  ToolViewCard,
+  ToolViewFacts,
+  ToolViewNote,
+  ToolViewRow,
+} from "./components/tool-views/parts.js";
+// The built-ins' own vocabulary (tool-views/view-dom.ts), exported so a
+// host view speaks it by re-use rather than by copy: the settled-outcome
+// sentence, the vanilla card parts, the labeled pane and quiet note, the
+// action envelope and failure readers (the HTTP status lives only in
+// resultText), and recordOf — the plain-object narrower a view's parser
+// leans on, which the dashboard's views once respelled.
+export {
+  actionEnvelopeOf,
+  actionFailureOf,
+  boneRows,
+  captionRow,
+  card,
+  factRows,
+  humanFailureSentenceOf,
+  listRow,
+  note,
+  pane,
+  recordOf,
+  scrollRegion,
+  terminal,
+  settledOutcomeNoteOf,
+  settledOutcomeNotesOf,
+  settledWithResult,
+  type ActionEnvelope,
+  type ActionFailure,
+} from "./components/tool-views/view-dom.js";
+
+// The companion: the presence surface — the bare mark in the
+// corner that expands into the chat drawer, follows a tool navigation
+// with the drawer open, and yields to any mounted full surface. The mark
+// is the provider's `companionMark` (default: the TeaFlask flask).
+export {
+  AssistantCompanion,
+  type AssistantCompanionProps,
+} from "./components/assistant-companion.js";

package/src/markdown.ts

@@ -0,0 +1,13 @@
+// The transcript's markdown/reveal leaves (fork the composition, share
+// the leaves). Its dashboard importer today is the doc tool views'
+// document body (AssistantMarkdown), earned in the dashboard's
+// architecture law's allowlist. Public for tarball hosts too:
+// typography, code blocks, the streaming repair and the paced reveal are
+// wire-agnostic and exist once, here.
+// Public API like "." — additions are cheap until the package publishes,
+// breaking changes are a customer conversation after.
+
+export { AssistantMarkdown } from "./components/markdown/assistant-markdown.js";
+export { PacedAssistantMarkdown } from "./components/markdown/paced-assistant-markdown.js";
+export { repairedStreamingMarkdown } from "./components/markdown/streaming-repair.js";
+export { usePacedReveal } from "./components/markdown/use-paced-reveal.js";

package/src/persistence/execution-ledger.ts

@@ -0,0 +1,146 @@
+// The browser's memory of what it already executed: one sessionStorage
+// entry per thread, holding the interrupt ids this tab claimed and the
+// outcomes their handlers produced. The at-most-once backstop of the
+// execution loop — the stream's own replayed evidence closes stale
+// entries first, but only this record survives the remount a navigation
+// causes, and "re-POST the stored outcome" is the contract's designed
+// recovery where re-execution never is.
+//
+// Session-scoped on purpose: the record guards THIS tab's re-execution;
+// cross-tab arbitration is the server's (first-wins recording); a
+// cross-tab residual is accepted.
+
+import type { ExecutionOutcome } from "../core/execution-handlers.js";
+
+// A claim with no outcome is a tab that died mid-handler: the action may
+// or may not have happened, so the record reads as this honest failure —
+// never as a license to re-execute.
+export const UNKNOWN_OUTCOME: Extract<ExecutionOutcome, { ok: false }> = {
+  ok: false,
+  error: {
+    code: "execution_failed",
+    message:
+      "The page was interrupted while performing this action, so its " +
+      "outcome is unknown. Tell the user what was being attempted and ask " +
+      "them to check whether it happened before anything is retried.",
+  },
+};
+
+// Executions are rare per thread (one per pause round); the cap only
+// bounds a pathological session.
+const MAX_RECORDED_EXECUTIONS = 40;
+
+interface LedgerRecord {
+  interruptId: string;
+  outcome: ExecutionOutcome | null;
+}
+
+// Module memory is the always-written layer (authoritative for this
+// page's lifetime, immune to quota trouble); sessionStorage is the
+// persistence layer a reload reads back. Where storage is unavailable
+// (SSR, sandboxed embeds), the ledger simply doesn't survive reloads.
+const memoryLedgers = new Map<string, LedgerRecord[]>();
+
+/**
+ * The outcome this tab already produced for an interrupt, the canned
+ * unknown-outcome failure for a claim that never settled, or null when
+ * the interrupt was never claimed here (executing is allowed).
+ */
+export function readExecutedOutcome(
+  threadId: string,
+  interruptId: string,
+): ExecutionOutcome | null {
+  const record = _recordsFor(threadId).find(
+    (known) => known.interruptId === interruptId,
+  );
+  if (record === undefined) {
+    return null;
+  }
+  return record.outcome ?? UNKNOWN_OUTCOME;
+}
+
+/** Written the instant an entry is claimed, before its handler runs. */
+export function recordExecutionClaimed(
+  threadId: string,
+  interruptId: string,
+): void {
+  const records = _recordsFor(threadId);
+  if (records.some((known) => known.interruptId === interruptId)) {
+    return;
+  }
+  records.push({ interruptId, outcome: null });
+  _writeRecords(threadId, records.slice(-MAX_RECORDED_EXECUTIONS));
+}
+
+export function recordExecutedOutcome(
+  threadId: string,
+  interruptId: string,
+  outcome: ExecutionOutcome,
+): void {
+  const records = _recordsFor(threadId);
+  const known = records.find((record) => record.interruptId === interruptId);
+  if (known !== undefined) {
+    known.outcome = outcome;
+  } else {
+    records.push({ interruptId, outcome });
+  }
+  _writeRecords(threadId, records.slice(-MAX_RECORDED_EXECUTIONS));
+}
+
+function _storageKeyFor(threadId: string): string {
+  return `tf-assistant:executions:${threadId}`;
+}
+
+function _recordsFor(threadId: string): LedgerRecord[] {
+  const remembered = memoryLedgers.get(threadId);
+  if (remembered !== undefined) {
+    return remembered;
+  }
+  const raw = _storage()?.getItem(_storageKeyFor(threadId)) ?? null;
+  return raw === null ? [] : _decodeRecords(raw);
+}
+
+function _writeRecords(threadId: string, records: LedgerRecord[]): void {
+  memoryLedgers.set(threadId, records);
+  try {
+    _storage()?.setItem(_storageKeyFor(threadId), JSON.stringify(records));
+  } catch {
+    // Quota trouble costs reload persistence, never the in-page record —
+    // module memory above already holds the at-most-once claim.
+  }
+}
+
+function _storage(): Storage | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  try {
+    return window.sessionStorage;
+  } catch {
+    // Some embeds (sandboxed iframes, blocked third-party storage) throw
+    // on access; the ledger then lives in module memory.
+    return null;
+  }
+}
+
+function _decodeRecords(raw: string): LedgerRecord[] {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      return parsed.filter(_isLedgerRecord);
+    }
+  } catch {
+    // A corrupt entry reads as no entries.
+  }
+  return [];
+}
+
+function _isLedgerRecord(value: unknown): value is LedgerRecord {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "interruptId" in value &&
+    typeof value.interruptId === "string" &&
+    "outcome" in value
+  );
+}

package/src/persistence/panel-mode.ts

@@ -0,0 +1,75 @@
+// The drawer's dock preference, one localStorage value per publishable
+// key: "sidebar" opts into the pushed-aside page, anything else is the
+// floating default — intrusiveness is opt-in, so the read trusts nothing
+// but the exact opt-in string. Deliberately NOT cleared by
+// resetAssistant(): where the panel lives is a device preference and
+// must survive a sign-out. A host-facing `panel-mode`
+// attribute (default/override) was considered and deliberately not
+// shipped — the mode is the end user's, not the host's.
+
+export type PanelDock = "floating" | "sidebar";
+
+type PanelModeListener = () => void;
+
+const _listeners = new Set<PanelModeListener>();
+
+export function readPanelMode(publishableKey: string): PanelDock {
+  try {
+    return _storage()?.getItem(_storageKeyFor(publishableKey)) === "sidebar"
+      ? "sidebar"
+      : "floating";
+  } catch {
+    return "floating";
+  }
+}
+
+export function writePanelMode(publishableKey: string, mode: PanelDock): void {
+  try {
+    if (mode === "sidebar") {
+      _storage()?.setItem(_storageKeyFor(publishableKey), "sidebar");
+    } else {
+      // The default needs no record; an absent key reads as floating.
+      _storage()?.removeItem(_storageKeyFor(publishableKey));
+    }
+  } catch {
+    // Quota or privacy-mode failures cost persistence, never the widget.
+  }
+  _notifyPanelModeChanged();
+}
+
+/**
+ * Same-tab change signal, so every mounted reader agrees with the
+ * switcher without a re-mount. Cross-tab sync is deliberately out of
+ * scope: the mode is read fresh on every load.
+ */
+export function subscribePanelMode(listener: PanelModeListener): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+function _notifyPanelModeChanged(): void {
+  // Notify a copy: a listener that unsubscribes mid-notify must not
+  // starve the rest of this round's delivery.
+  for (const listener of [..._listeners]) {
+    listener();
+  }
+}
+
+function _storageKeyFor(publishableKey: string): string {
+  return `tf-assistant:${publishableKey}:panel-mode`;
+}
+
+function _storage(): Storage | null {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  try {
+    return window.localStorage;
+  } catch {
+    // Some embeds (sandboxed iframes, blocked third-party storage) throw
+    // on access; the widget then simply doesn't persist.
+    return null;
+  }
+}