@teaflask/assistant 0.3.0 → 0.6.0

package/src/core/execution-request-narrowing.ts

@@ -1,112 +0,0 @@
-// The execution wire's narrowers: a
-// tool_execution_requested marker's value and a turn snapshot's coworker
-// request item, both `any` by contract. Malformed values return null and
-// are ignored — the contract's "clients MUST ignore events and fields they
-// do not recognize". A dependency-free leaf, so the ./transcript entry
-// exports the coworker narrowing without dragging the inbox along.
-
-import type { ToolExecutionRequestedPayload } from "../contract/events.js";
-
-/** One coworker request as the turn snapshot lists it, narrowed. */
-export interface CoworkerExecutionRequest {
-  ordinal: number;
-  label: string;
-  childSessionId: string;
-  card: ToolExecutionRequestedPayload;
-}
-
-/** The turn fields the coworker adoption reads — the serving and the
- *  dashboard turn shapes both satisfy it. */
-export interface CoworkerRequestTurn {
-  id: string;
-  run_id: string | null;
-  pending_coworker_executions?: readonly unknown[] | null;
-}
-
-/**
- * Narrow one pending_coworker_executions item (any by contract): the
- * asker's identity plus the card in the marker's own shape, so the
- * marker narrowing above serves both askers. Malformed → null.
- */
-export function coworkerExecutionRequestOf(
-  value: unknown,
-): CoworkerExecutionRequest | null {
-  if (typeof value !== "object" || value === null) {
-    return null;
-  }
-  const record = value as Record<string, unknown>;
-  if (
-    typeof record.ordinal !== "number" ||
-    typeof record.label !== "string" ||
-    typeof record.child_session_id !== "string"
-  ) {
-    return null;
-  }
-  const card = executionRequestedPayloadOf(record.card);
-  if (card === null) {
-    return null;
-  }
-  return {
-    ordinal: record.ordinal,
-    label: record.label,
-    childSessionId: record.child_session_id,
-    card,
-  };
-}
-
-/**
- * Narrow a tool_execution_requested CUSTOM event's wire value (any by
- * contract). Malformed payloads return null and are ignored — the
- * contract's "clients MUST ignore events and fields they do not
- * recognize".
- */
-export function executionRequestedPayloadOf(
-  value: unknown,
-): ToolExecutionRequestedPayload | null {
-  if (typeof value !== "object" || value === null) {
-    return null;
-  }
-  const record = value as Record<string, unknown>;
-  if (typeof record.interrupt_id !== "string" || record.interrupt_id === "") {
-    return null;
-  }
-  if (typeof record.tool_name !== "string") {
-    return null;
-  }
-  const request = _requestOf(record.request);
-  if (request === null) {
-    return null;
-  }
-  return {
-    interrupt_id: record.interrupt_id,
-    tool_name: record.tool_name,
-    tool_call_id:
-      typeof record.tool_call_id === "string" ? record.tool_call_id : null,
-    round: typeof record.round === "number" ? record.round : 0,
-    request,
-  };
-}
-
-function _requestOf(
-  value: unknown,
-): ToolExecutionRequestedPayload["request"] | null {
-  if (typeof value !== "object" || value === null) {
-    return null;
-  }
-  const record = value as Record<string, unknown>;
-  if (typeof record.kind !== "string" || record.kind === "") {
-    return null;
-  }
-  return {
-    kind: record.kind,
-    intent: recordOrNull(record.intent),
-    action: recordOrNull(record.action),
-  };
-}
-
-export function recordOrNull(value: unknown): Record<string, unknown> | null {
-  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
-    return value as Record<string, unknown>;
-  }
-  return null;
-}

package/src/core/host-fill.ts

@@ -1,10 +0,0 @@
-// The fall-through rule for every host-provided node slot in the package:
-// a fill declines exactly when it is a value React renders as nothing
-// REGARDLESS of content — null, undefined, and both booleans, so the
-// idiomatic `cond && <X/>` falls through on its false arm to the package
-// default. Renderable emptiness ("", 0, []) is the host's deliberate
-// content and counts as filled. One predicate, so no slot can gate on
-// `!= null` and hand a `false` to the screen as a blank.
-export function hostFillDeclines(fill: unknown): boolean {
-  return fill === null || fill === undefined || typeof fill === "boolean";
-}

package/src/core/hotkey.ts

@@ -1,148 +0,0 @@
-// The batteries-root's hotkey grammar: parsing "mod+k"-style specs and
-// matching them against keyboard events. Pure over an event-shaped input
-// on purpose — no DOM or window imports — so the script-tag distribution
-// can reuse the exact same binding semantics outside React.
-//
-// Matching is by event.key, the repo-wide idiom. Known limitation: on
-// macOS the Option key rewrites event.key ("alt+k" arrives as key "˚"),
-// so alt chords are not reliably bindable — none of our defaults use alt,
-// and a host that needs one owns the trigger via <AssistantPalette/>.
-
-export const DEFAULT_ASSISTANT_HOTKEY = "mod+k";
-
-/** The subset of KeyboardEvent the matcher reads — pure and constructible
- *  in any test or non-DOM host. */
-export interface HotkeyEventLike {
-  key: string;
-  metaKey: boolean;
-  ctrlKey: boolean;
-  altKey: boolean;
-  shiftKey: boolean;
-}
-
-export interface HotkeyBinding {
-  /** event.key, lowercased ("k", "j", "escape"). */
-  key: string;
-  /** The portable primary modifier: satisfied by meta OR ctrl. */
-  mod: boolean;
-  ctrl: boolean;
-  meta: boolean;
-  alt: boolean;
-  shift: boolean;
-}
-
-const MODIFIER_TOKENS = ["mod", "ctrl", "meta", "alt", "shift"] as const;
-type ModifierToken = (typeof MODIFIER_TOKENS)[number];
-
-/**
- * Parses a "mod+k"-style spec: "+"-separated tokens in any order, exactly
- * one non-modifier token (the key), at least one modifier drawn from
- * mod|ctrl|meta|alt|shift, case-insensitive. Exactly these five names —
- * no cmd/command/option aliases; a rejected alias warns loudly at the
- * call site, which beats two spellings of the same chord. A modifier-less
- * spec ("/", "k") is rejected too: the palette opens from anywhere, so a
- * bare key would swallow that character in every input on the page — and
- * for the same reason shift alone only pairs with a non-printable key
- * ("shift+f1" yes, "shift+k" no: Shift+letter is just typing a capital).
- * Returns null on anything else — the caller decides what a bad binding
- * means.
- */
-export function parseHotkey(spec: string): HotkeyBinding | null {
-  const binding: HotkeyBinding = {
-    key: "",
-    mod: false,
-    ctrl: false,
-    meta: false,
-    alt: false,
-    shift: false,
-  };
-  for (const token of spec.toLowerCase().split("+")) {
-    if (_isModifierToken(token)) {
-      if (binding[token]) {
-        return null;
-      }
-      binding[token] = true;
-    } else if (_isKeyToken(token)) {
-      if (binding.key !== "") {
-        return null;
-      }
-      binding.key = token;
-    } else {
-      return null;
-    }
-  }
-  if (binding.key === "" || !_hasAnyModifier(binding)) {
-    return null;
-  }
-  if (_shiftIsTheOnlyModifier(binding) && _isPrintableKey(binding.key)) {
-    return null;
-  }
-  return binding;
-}
-
-/**
- * Exact-chord match: named modifiers must be down and unnamed ones up
- * ("mod+k" does not match mod+shift+k — ⌘⇧K is someone else's chord).
- * `mod` is satisfied by meta or ctrl and absorbs exactly one of them, so
- * "mod+k" accepts ⌘K and Ctrl+K but rejects ⌘Ctrl+K.
- */
-export function hotkeyMatches(
-  binding: HotkeyBinding,
-  event: HotkeyEventLike,
-): boolean {
-  if (event.key.toLowerCase() !== binding.key) {
-    return false;
-  }
-  if (event.altKey !== binding.alt || event.shiftKey !== binding.shift) {
-    return false;
-  }
-  if (_explicitlyNamedPrimaryIsUp(binding, event)) {
-    return false;
-  }
-  // Primaries held down beyond the explicitly named ones: mod claims
-  // exactly one of them; without mod there must be none.
-  const unclaimedPrimariesDown =
-    Number(event.metaKey && !binding.meta) +
-    Number(event.ctrlKey && !binding.ctrl);
-  return unclaimedPrimariesDown === (binding.mod ? 1 : 0);
-}
-
-function _isModifierToken(token: string): token is ModifierToken {
-  return (MODIFIER_TOKENS as readonly string[]).includes(token);
-}
-
-// A key token is any single non-empty word that isn't a modifier — one
-// event.key value ("k", "escape", "/"). Whitespace or an empty token
-// (a stray "+") is a malformed spec, not a key.
-function _isKeyToken(token: string): boolean {
-  return token !== "" && !/\s/.test(token);
-}
-
-function _hasAnyModifier(binding: HotkeyBinding): boolean {
-  return (
-    binding.mod || binding.ctrl || binding.meta || binding.alt || binding.shift
-  );
-}
-
-function _shiftIsTheOnlyModifier(binding: HotkeyBinding): boolean {
-  return (
-    binding.shift &&
-    !binding.mod &&
-    !binding.ctrl &&
-    !binding.meta &&
-    !binding.alt
-  );
-}
-
-// A single-character event.key is a character the press would have typed
-// ("k", "/", "?"); multi-character names ("f1", "escape") are actions.
-function _isPrintableKey(key: string): boolean {
-  return key.length === 1;
-}
-
-function _explicitlyNamedPrimaryIsUp(
-  binding: HotkeyBinding,
-  event: HotkeyEventLike,
-): boolean {
-  return (binding.meta && !event.metaKey) || (binding.ctrl && !event.ctrlKey);
-}

package/src/core/idle-recheck.ts

@@ -1,68 +0,0 @@
-// The leased idle re-read: while a surface is mounted over a
-// conversation whose newest known turn holds no stream, a bounded
-// single-flight interval GET is the only way a background-initiated
-// delivery turn becomes visible.
-
-import { turnHoldsAStream } from "./connection-driver.js";
-import type { AssistantConversationStore } from "./conversation-store.js";
-
-// The leased idle re-read: while a surface is MOUNTED and the
-// newest known turn holds no stream, the thread snapshot is the only
-// place a background-initiated delivery turn becomes visible — the
-// entity's settle-wake and janitor-re-wake openers have no push signal
-// the client can hold (the parent stream emits nothing until the delivery
-// run's first event, and the server's 60s handoff hold only pushes to a
-// socket that is already open). One lightweight GET per interval per
-// open conversation; ≤60s of added latency against the janitor's own
-// 15-minute sweep. Leased only: a headless embed must not poll for the
-// life of the page — its attach happens at the next mount through the
-// first-connect arm of the truth table.
-const IDLE_RECHECK_INTERVAL_MS = 60_000;
-
-// Armed while a surface is mounted over a conversation whose newest
-// known turn holds no stream — parked, awaiting_input, terminal, or
-// none: settle wakes and the janitor's re-wakes grow delivery turns
-// on terminal threads too, so gating on "parked" would miss them. The
-// re-read only calls refreshConversation(). An UNCHANGED read notifies
-// no subscriber: adoption keeps the _active reference when the thread
-// record did not move (the guard and its premise live in
-// adoptRefreshedDetail) and every cell publisher compares before it
-// sets — so an idle tick costs one GET and nothing renders. A read
-// that DID move still publishes, which is what flips the connect gate
-// on a landed queued/working turn and disarms this interval on that
-// same publish.
-export function syncIdleRecheck(store: AssistantConversationStore): void {
-  const wanted =
-    !store._disposed &&
-    store._leaseHolders.length > 0 &&
-    store._active !== null &&
-    !turnHoldsAStream(store);
-  if (!wanted) {
-    clearIdleRecheck(store);
-    return;
-  }
-  store._idleRecheckTimer ??= setInterval(() => {
-    // Single-flight (the delivery probe's own refreshOnce posture):
-    // this transport aborts nothing, so a tick that stacked a new
-    // GET behind an accepted-then-stalled one would add a wedged
-    // connection per minute for the life of the page — on HTTP/1.1
-    // exhausting the per-host budget and starving the SSE stream
-    // itself. One read in flight at a time; a wedged read quiets the
-    // interval instead of multiplying, and the flag clears the
-    // moment the read settles.
-    if (store._idleRecheckInFlight) {
-      return;
-    }
-    store._idleRecheckInFlight = true;
-    void store.refreshConversation().finally(() => {
-      store._idleRecheckInFlight = false;
-    });
-  }, IDLE_RECHECK_INTERVAL_MS);
-}
-
-export function clearIdleRecheck(store: AssistantConversationStore): void {
-  if (store._idleRecheckTimer !== null) {
-    clearInterval(store._idleRecheckTimer);
-    store._idleRecheckTimer = null;
-  }
-}

package/src/core/memory-provenance-anchors.ts

@@ -1,312 +0,0 @@
-// The memory-provenance anchor model, pure of React: the recorder maps
-// each memory_updated CUSTOM marker to its durable memory id, consumers
-// read the map to show quiet "saved a memory" provenance rows, and the
-// resume store holds the map across remounts (the marker never becomes a
-// message, and a snapshot-seeded reconnect replays only past the
-// cursor). The memory id is the reconcile key — a replayed or delayed
-// re-delivery updates nothing and appends nothing, so one write is ever
-// one row. The payload is end-user safe by wire contract (a canned
-// sentence, a scope token, an id — never the memory's content), and the
-// narrower distrusts it anyway.
-//
-// ATTRIBUTION rides beside the provenance records: which
-// assistant prose message each write's footer renders under. The marker
-// deliberately carries no tool_call_id or message id (the store seam
-// sits below the tool layer), so the recorder anchors by stream
-// position — the receipt-family idiom: writes buffered during a run
-// flush to that run's newest assistant prose at the terminal, and a
-// marker arriving after the terminal attributes immediately. First
-// attribution wins, keyed by the durable memory id, so re-deliveries
-// against a drifted message list reconcile instead of moving the footer
-// (the anchor family's drifted-message arbitration law). A history whose markers were
-// recorded without attribution simply renders no footer — attribution
-// is evidence, never synthesized.
-
-import type { AgentSubscriber } from "@ag-ui/client";
-
-import { MEMORY_UPDATED_EVENT_NAME } from "../contract/events.js";
-import { newestAssistantProseIdOf } from "./assistant-prose.js";
-
-// The summary is a backend-authored canned sentence; a runaway one is
-// retained capped, never unbounded (the display-text posture).
-const SUMMARY_MAX_CHARS = 500;
-
-// Scope is an open single-word vocabulary ("org", "user"); unknown
-// tokens survive verbatim capped — the renderer owns the fallback.
-const TOKEN_MAX_CHARS = 64;
-
-export interface MemoryUpdated {
-  memoryId: string;
-  /** Open vocabulary: "org" | "user" today; render unknowns generically. */
-  scope: string;
-  /** The canned human sentence — never the memory's content. */
-  summary: string;
-}
-
-export const EMPTY_MEMORY_PROVENANCE_ANCHORS: ReadonlyMap<
-  string,
-  MemoryUpdated
-> = new Map();
-
-/**
- * Narrow a memory_updated marker's value. Null means ignore — the
- * contract's "clients MUST ignore events and fields they do not
- * recognize": without its durable id the row has no reconcile key, and
- * without a sentence there is nothing safe to show.
- */
-export function memoryUpdatedAnchorOf(value: unknown): MemoryUpdated | null {
-  if (typeof value !== "object" || value === null) {
-    return null;
-  }
-  const {
-    memory_id: memoryId,
-    scope,
-    summary,
-  } = value as {
-    memory_id?: unknown;
-    scope?: unknown;
-    summary?: unknown;
-  };
-  if (typeof memoryId !== "string" || memoryId === "") {
-    return null;
-  }
-  if (typeof scope !== "string" || scope.trim() === "") {
-    return null;
-  }
-  if (typeof summary !== "string" || summary.trim() === "") {
-    return null;
-  }
-  return {
-    memoryId,
-    scope: scope.slice(0, TOKEN_MAX_CHARS),
-    summary: summary.slice(0, SUMMARY_MAX_CHARS),
-  };
-}
-
-/**
- * Reconcile-by-id, never append: the first anchor for a memory id wins,
- * so every replay re-delivery — and any delayed duplicate — is a no-op.
- * Insertion order is stream order, which is how consumers list the rows.
- */
-export function withMemoryUpdateAnchored(
-  previous: ReadonlyMap<string, MemoryUpdated>,
-  update: MemoryUpdated,
-): ReadonlyMap<string, MemoryUpdated> {
-  if (previous.has(update.memoryId)) {
-    return previous;
-  }
-  const next = new Map(previous);
-  next.set(update.memoryId, update);
-  return next;
-}
-
-/**
- * A defensive copy for seeding from the resume store: entries that are
- * not a well-formed provenance record are dropped rather than rendered —
- * a dropped entry becomes a missing row until the next full replay,
- * never a crash.
- */
-export function wellFormedMemoryProvenanceAnchorsOf(
-  stored: ReadonlyMap<string, MemoryUpdated>,
-): ReadonlyMap<string, MemoryUpdated> {
-  const seeded = new Map<string, MemoryUpdated>();
-  const entries = stored as ReadonlyMap<unknown, unknown>;
-  for (const [memoryId, update] of entries) {
-    if (typeof memoryId !== "string" || !_isWellFormedUpdate(update)) {
-      continue;
-    }
-    seeded.set(memoryId, update);
-  }
-  return seeded;
-}
-
-export const EMPTY_MEMORY_ATTRIBUTION_ANCHORS: ReadonlyMap<string, string> =
-  new Map();
-
-/**
- * Reconcile-by-id, never move: the first message a memory id attributes
- * to wins, so a re-delivery flushing against a drifted message list is a
- * no-op — identical map identity, the anchor family's arbitration law.
- */
-export function withMemoryAttributed(
-  previous: ReadonlyMap<string, string>,
-  memoryId: string,
-  messageId: string,
-): ReadonlyMap<string, string> {
-  if (previous.has(memoryId)) {
-    return previous;
-  }
-  const next = new Map(previous);
-  next.set(memoryId, messageId);
-  return next;
-}
-
-/**
- * A defensive copy for seeding from the resume store: pairs that are not
- * two non-empty strings are dropped rather than rendered — a dropped
- * pair becomes a missing footer until the next full replay, never a
- * crash.
- */
-export function wellFormedMemoryAttributionAnchorsOf(
-  stored: ReadonlyMap<string, string>,
-): ReadonlyMap<string, string> {
-  const seeded = new Map<string, string>();
-  const entries = stored as ReadonlyMap<unknown, unknown>;
-  for (const [memoryId, messageId] of entries) {
-    if (
-      typeof memoryId !== "string" ||
-      memoryId === "" ||
-      typeof messageId !== "string" ||
-      messageId === ""
-    ) {
-      continue;
-    }
-    seeded.set(memoryId, messageId);
-  }
-  return seeded;
-}
-
-/**
- * The footer projection: provenance records grouped under the message
- * each one attributed to, in stream order (the provenance map's
- * insertion order). A record without attribution is skipped — an old
- * history renders no footer rather than a synthesized one.
- */
-export function memoryFootersOf(
-  provenance: ReadonlyMap<string, MemoryUpdated>,
-  attribution: ReadonlyMap<string, string>,
-): ReadonlyMap<string, MemoryUpdated[]> {
-  const footers = new Map<string, MemoryUpdated[]>();
-  for (const [memoryId, update] of provenance) {
-    const messageId = attribution.get(memoryId);
-    if (messageId === undefined) {
-      continue;
-    }
-    const grouped = footers.get(messageId);
-    if (grouped === undefined) {
-      footers.set(messageId, [update]);
-    } else {
-      grouped.push(update);
-    }
-  }
-  return footers;
-}
-
-/** The recorder's two write channels: the provenance record itself, and
- *  the message id its footer renders under. */
-export interface MemoryUpdatedRecorderSink {
-  onMemoryAnchored: (update: MemoryUpdated) => void;
-  onMemoryAttributed: (memoryId: string, messageId: string) => void;
-}
-
-/**
- * Records each memory_updated marker's memory id → narrowed payload, and
- * attributes each write to the assistant prose message whose run caused
- * it. Attribution follows the receipt-family stream-position idiom
- * (core/receipt-anchors.ts): writes observed while the run is live
- * buffer and flush at the terminal against the run's own newest prose;
- * a run that authored no prose drops its buffer honestly (the annotated
- * tool row still tells the story, and an earlier turn's prose must never
- * adopt this turn's write). A marker arriving AFTER the terminal — the
- * settled-then-provenance arrival a reconnect tail produces — attributes
- * immediately, so the footer engages without waiting for another event.
- */
-export function memoryUpdatedRecorder(
-  sink: MemoryUpdatedRecorderSink,
-): AgentSubscriber {
-  let runLive = false;
-  // The newest assistant prose id, and whether it changed since the
-  // current run started — the "this run authored prose" evidence the
-  // flush needs. The BASELINE is taken at RUN_STARTED from the params'
-  // own message list (AgentSubscriberParams.messages — the pre-run
-  // list; the pipeline appends nothing before that callback and its
-  // verifier requires RUN_STARTED to be a run's first event), because a
-  // fresh epoch's agent is SEEDED with history rather than replaying
-  // it: no onMessagesChanged fires between onRunInitialized and
-  // RUN_STARTED, so a null baseline would make the run's first message
-  // change read the seeded history's old prose as "authored this run"
-  // and hand the previous turn's message this run's writes — sticky
-  // across replays, since attribution is first-wins. Deliberately NOT
-  // reset at the terminal: the post-settle arrival arm still needs to
-  // know the settled run's prose was fresh.
-  let newestProseId: string | null = null;
-  let proseThisRun = false;
-  let pending: string[] = [];
-
-  const flush = () => {
-    if (newestProseId !== null && proseThisRun) {
-      for (const memoryId of pending) {
-        sink.onMemoryAttributed(memoryId, newestProseId);
-      }
-    }
-    pending = [];
-  };
-
-  return {
-    // One agent can be connected more than once (StrictMode detaches the
-    // first run terminal-free and starts over): writes a dead connection
-    // buffered but never flushed must not ride into the replacement's
-    // flush — the receipt recorders' same guard.
-    onRunInitialized() {
-      runLive = false;
-      newestProseId = null;
-      proseThisRun = false;
-      pending = [];
-    },
-    onRunStartedEvent({ messages }) {
-      runLive = true;
-      newestProseId = newestAssistantProseIdOf(messages);
-      proseThisRun = false;
-    },
-    onMessagesChanged({ messages }) {
-      const proseId = newestAssistantProseIdOf(messages);
-      if (proseId !== null && proseId !== newestProseId) {
-        newestProseId = proseId;
-        proseThisRun = true;
-      }
-    },
-    onCustomEvent({ event }) {
-      if (event.name !== MEMORY_UPDATED_EVENT_NAME) {
-        return;
-      }
-      const update = memoryUpdatedAnchorOf(event.value);
-      if (update === null) {
-        return;
-      }
-      sink.onMemoryAnchored(update);
-      if (runLive) {
-        pending.push(update.memoryId);
-      } else if (newestProseId !== null && proseThisRun) {
-        // Post-settle arrival: no further event will flush for us.
-        sink.onMemoryAttributed(update.memoryId, newestProseId);
-      }
-    },
-    onRunFinishedEvent() {
-      runLive = false;
-      flush();
-    },
-    onRunErrorEvent() {
-      runLive = false;
-      flush();
-    },
-  };
-}
-
-function _isWellFormedUpdate(update: unknown): update is MemoryUpdated {
-  if (typeof update !== "object" || update === null) {
-    return false;
-  }
-  const { memoryId, scope, summary } = update as {
-    memoryId?: unknown;
-    scope?: unknown;
-    summary?: unknown;
-  };
-  return (
-    typeof memoryId === "string" &&
-    memoryId !== "" &&
-    typeof scope === "string" &&
-    scope !== "" &&
-    typeof summary === "string" &&
-    summary !== ""
-  );
-}