@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/messages-cell.ts

@@ -0,0 +1,99 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+import type { Message } from "@ag-ui/core";
+
+// The owned message list's wire tap: the AbstractAgent maintains
+// `agent.messages` itself; this recorder mirrors every change into the cell.
+// onMessagesChanged fires per APPLIED event (deltas included) plus
+// initialize/finalize/error and setMessages. The pipeline REUSES its array
+// and mutates in place: publish shallow copies; never memo on message identity.
+
+export function messagesRecorder(
+  publish: (messages: readonly Message[]) => void,
+): AgentSubscriber {
+  return {
+    onMessagesChanged({ messages }) {
+      publish([...messages]);
+    },
+  };
+}
+
+// The connection's error tap: only a transport death reaches onRunFailed (a
+// dead fetch, a non-2xx, a protocol refusal, a body that errored mid-read);
+// a served RUN_ERROR surfaces as onRunErrorEvent, which the surfaces
+// subscribe themselves. Aborts are OUR OWN doing and never paint the banner.
+export function streamErrorRecorder(
+  onStreamError: (error: Error) => void,
+): AgentSubscriber {
+  return {
+    onRunFailed({ error }) {
+      if (isAbortShaped(error)) {
+        return;
+      }
+      onStreamError(error);
+    },
+  };
+}
+
+/** Whether an error is our own abort wearing one of the runtime's spellings
+ *  — the DOMException name, or a message saying so. Matches the message on
+ *  purpose: the chassis rejects with plain Errors carrying those sentences. */
+export function isAbortShaped(error: Error): boolean {
+  return error.name === "AbortError" || /\baborted?\b/i.test(error.message);
+}
+
+// --- the store-less surface's taps ---------------------------------
+// AssistantTranscript's agent mode owns its own connection and has no store
+// to hold `running`, so its taps differ from the recorders above in exactly
+// two ways: the snapshot recorder publishes {messages, running}, and the
+// error tap also reads onRunErrorEvent. The originals stay untouched.
+
+export interface MessagesSnapshot {
+  messages: readonly Message[];
+  /** True while a run streams — drives the streaming-markdown repair and
+   *  the still-pending tool read. */
+  running: boolean;
+}
+
+// messagesRecorder's wire tap plus the run bit. isRunning flips outside
+// message changes too (a run can start or settle without a delta), so the
+// three run-edge hooks mirror those edges and the pending read and repair
+// windows track the run, not the last delta.
+export function messagesSnapshotRecorder(
+  publish: (snapshot: MessagesSnapshot) => void,
+): AgentSubscriber {
+  return {
+    onMessagesChanged({ agent, messages }) {
+      publish({ messages: [...messages], running: agent.isRunning });
+    },
+    onRunStartedEvent({ agent }) {
+      publish({ messages: [...agent.messages], running: agent.isRunning });
+    },
+    onRunFinishedEvent({ agent }) {
+      publish({ messages: [...agent.messages], running: false });
+    },
+    onRunErrorEvent({ agent }) {
+      publish({ messages: [...agent.messages], running: false });
+    },
+  };
+}
+
+// The connection-owning surface's error tap: a pre-stream failure or an
+// event-verify error arrives as onRunFailed; a mid-stream transport death is
+// SYNTHESIZED by @ag-ui/client into a RUN_ERROR event (onRunFailed never
+// fires for it), so onRunErrorEvent carries it, along with genuine and
+// replayed failed-run terminals, which the hosts absorb. Aborts paint no banner.
+export function connectionErrorRecorder(
+  onStreamError: (error: Error) => void,
+): AgentSubscriber {
+  return {
+    onRunFailed({ error }) {
+      if (isAbortShaped(error)) {
+        return;
+      }
+      onStreamError(error);
+    },
+    onRunErrorEvent({ event }) {
+      onStreamError(new Error(event.message));
+    },
+  };
+}

package/src/core/observable-cell.ts

@@ -0,0 +1,46 @@
+// The store's observation primitive: a cached snapshot plus change
+// notification, the exact contract `useSyncExternalStore` binds to. The
+// snapshot's identity changes only when a new value is set, so React (or
+// any other subscriber) can compare by reference; publishers must set a
+// cell only when state actually changed — the inbox classes' did-change
+// booleans are what gate those writes.
+
+export interface ReadonlyCell<T> {
+  // Function-typed properties, not methods: get/subscribe travel unbound
+  // (into useSyncExternalStore and other subscriber wiring), so
+  // implementations must not depend on call-site `this`.
+  get: () => T;
+  subscribe: (listener: () => void) => () => void;
+}
+
+export class ObservableCell<T> implements ReadonlyCell<T> {
+  private value: T;
+  private readonly listeners = new Set<() => void>();
+
+  constructor(initial: T) {
+    this.value = initial;
+  }
+
+  // Arrow fields on purpose: get/subscribe travel unbound into
+  // useSyncExternalStore and any other subscriber wiring.
+  get = (): T => {
+    return this.value;
+  };
+
+  set(next: T): void {
+    if (Object.is(this.value, next)) {
+      return;
+    }
+    this.value = next;
+    for (const listener of [...this.listeners]) {
+      listener();
+    }
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+}

package/src/core/pending-decision-gap.ts

@@ -0,0 +1,203 @@
+// The pending-decision gap: the server says the turn waits on
+// named interrupts and this client holds NOTHING that answers for one —
+// no card, no execution-inbox entry — so the gap must be loud. The premise
+// and the two server-asserted non-gap subsets: docs/decision-anchors.md.
+
+import type { AssistantTurnStatus } from "../generated/models/assistantTurnStatus.js";
+
+/** The five turn fields the derivation reads — structural on purpose,
+ *  so both callers assign with zero casts: the widget store
+ *  passes the widget's generated ServingAssistantTurn (pause fields
+ *  required), the dashboard playground its own generated
+ *  AssistantTurnResponse (pause fields generated optional, though the
+ *  server always supplies them). The optional array makes the type tell
+ *  the truth the runtime tolerance below already pins. `status` keeps
+ *  the generated union, not string: the two literal
+ *  comparisons below stay compile-checked, both generated status types
+ *  are the identical union so assignability costs nothing, and the day
+ *  the dashboard's union drifts from this one the playground call site
+ *  fails to compile — the loud drift signal, not a silent never-fires. */
+export interface GapJudgeableTurn {
+  id: string;
+  status: AssistantTurnStatus;
+  run_id: string | null;
+  pending_interrupt_ids?: readonly string[];
+  unservable_interrupt_ids?: readonly string[];
+}
+
+/** Representation is by interruptId, any holder — structural so the
+ *  playground's refusal entries (not the widget's ExecutionEntryModel)
+ *  count as holders without a cast that would break silently the day
+ *  the derivation read a second field. */
+interface InterruptHolder {
+  interruptId: string;
+}
+
+export interface PendingDecisionGap {
+  turnId: string;
+  /** The pending interrupt ids nothing on this client answers for. */
+  missingInterruptIds: readonly string[];
+}
+
+const EMPTY_CONSUMED_IDS: ReadonlySet<string> = new Set();
+
+export function pendingDecisionGapOf(
+  turn: GapJudgeableTurn | null,
+  approvalCards: readonly InterruptHolder[],
+  elicitationCards: readonly InterruptHolder[],
+  executionEntries: readonly InterruptHolder[],
+  consumedInterruptIds: ReadonlySet<string> = EMPTY_CONSUMED_IDS,
+): PendingDecisionGap | null {
+  if (turn === null) {
+    return null;
+  }
+  if (turn.status !== "awaiting_input" && turn.status !== "parked") {
+    return null;
+  }
+  if (turn.run_id === null || !Array.isArray(turn.pending_interrupt_ids)) {
+    return null;
+  }
+  // Representation by id, whatever the holder's status: a held card —
+  // even answered or stale — renders its own truthful state, and a
+  // claimed execution entry is the driver's to answer.
+  const represented = new Set<string>();
+  for (const card of approvalCards) {
+    represented.add(card.interruptId);
+  }
+  for (const card of elicitationCards) {
+    represented.add(card.interruptId);
+  }
+  for (const entry of executionEntries) {
+    represented.add(entry.interruptId);
+  }
+  // The server's own non-gap assertion: no card can ever be served for
+  // these ids, so a wait must not be presented. Tolerates any non-array
+  // shape (an older server omits the field) — never a false subtraction.
+  const unservable = new Set<string>(
+    Array.isArray(turn.unservable_interrupt_ids)
+      ? turn.unservable_interrupt_ids.filter(
+          (id): id is string => typeof id === "string",
+        )
+      : [],
+  );
+  // The per-element string guard mirrors the unservable filter's (and
+  // regains the narrowing Array.isArray cannot give a readonly array):
+  // a non-string element is wire garbage, never a missing id.
+  const missing = turn.pending_interrupt_ids.filter(
+    (id): id is string =>
+      typeof id === "string" &&
+      !represented.has(id) &&
+      !consumedInterruptIds.has(id) &&
+      !unservable.has(id),
+  );
+  if (missing.length === 0) {
+    return null;
+  }
+  return { turnId: turn.id, missingInterruptIds: missing };
+}
+
+/** Content identity for publish dedupe and the grace probe's scope: one
+ *  gap per (turn, missing set), order-insensitive. */
+export function gapSignatureOf(gap: PendingDecisionGap): string {
+  return `${gap.turnId}:${[...gap.missingInterruptIds].sort().join(",")}`;
+}
+
+// The gap's settle window: how long the evidence channel gets to
+// land its recorded interrupts (execution entries, elicitations) before a
+// gap the best-effort re-read could not close goes loud. A hard timer,
+// deliberately not a wait on any stream OR network event — boundedness is
+// the alert's liveness guarantee, and neither door's transport aborts a
+// stalled request.
+export const GAP_PROBE_SETTLE_MS = 2_000;
+
+export interface PendingDecisionGapGateDeps {
+  /** Receives the loud gap, or null when the gap clears. */
+  publish: (gap: PendingDecisionGap | null) => void;
+  /** One best-effort re-read per signature — never a gate on the timer,
+   *  which is the alert's only liveness driver. */
+  probe: () => void;
+  /** Whether the evidence channel has had its chance — read at elapse,
+   *  never latched here, because the two owners' evidence differs in
+   *  shape: the widget store's epoch-connected-once record resets per
+   *  connection epoch, while the playground transcript's replay-finalized
+   *  latch is monotonic for the mount. Until it answers true, an elapsed
+   *  window re-arms as a quiet heartbeat instead of alarming. */
+  evidenceSettled: () => boolean;
+}
+
+/**
+ * The per-signature grace window over the evidence predicate. States:
+ * quiet | armed(sig) | loud(sig), crossed with `evidenceSettled` read at
+ * elapse; every transition is enumerated in docs/decision-anchors.md.
+ */
+export class PendingDecisionGapGate {
+  private readonly deps: PendingDecisionGapGateDeps;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  /** The signature the armed window judges, or null when quiet. */
+  private armedSignature: string | null = null;
+  /** The last judged gap — what the window publishes if it elapses. */
+  private judged: PendingDecisionGap | null = null;
+  private loudSignature: string | null = null;
+
+  constructor(deps: PendingDecisionGapGateDeps) {
+    this.deps = deps;
+  }
+
+  judge(gap: PendingDecisionGap | null): void {
+    this.judged = gap;
+    if (gap === null) {
+      this._disarm();
+      if (this.loudSignature !== null) {
+        this.loudSignature = null;
+        this.deps.publish(null);
+      }
+      return;
+    }
+    const signature = gapSignatureOf(gap);
+    if (this.loudSignature !== null) {
+      this._disarm();
+      if (signature !== this.loudSignature) {
+        this.loudSignature = signature;
+        this.deps.publish(gap);
+      }
+      return;
+    }
+    if (signature === this.armedSignature) {
+      return;
+    }
+    this._disarm();
+    this.armedSignature = signature;
+    this.deps.probe();
+    this._armWindow(signature);
+  }
+
+  dispose(): void {
+    this._disarm();
+  }
+
+  private _armWindow(signature: string): void {
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      const survivor = this.judged;
+      if (survivor === null || gapSignatureOf(survivor) !== signature) {
+        this.armedSignature = null;
+        return;
+      }
+      if (!this.deps.evidenceSettled()) {
+        this._armWindow(signature);
+        return;
+      }
+      this.armedSignature = null;
+      this.loudSignature = signature;
+      this.deps.publish(survivor);
+    }, GAP_PROBE_SETTLE_MS);
+  }
+
+  private _disarm(): void {
+    if (this.timer !== null) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    this.armedSignature = null;
+  }
+}

package/src/core/perch-clearance.ts

@@ -0,0 +1,104 @@
+// The dock's collision awareness: a
+// fixed corner perch dropped onto a page that already owns that corner —
+// a composer's send button, a copy control — steals the host's clicks.
+// The cure is a lift: the widget probes what the page stacks under the
+// perch's hit box and raises the dock in fixed steps until nothing
+// interactive sits beneath. This module is the pure half — the
+// geometry and the verdict — so the decision is exhaustively testable;
+// the widget owns the DOM probing (document.elementsFromPoint) and the
+// re-measure clocks (resize, scroll, mutations).
+
+export interface ClearancePoint {
+  x: number;
+  y: number;
+}
+
+export interface ClearanceRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** The lifts tried, in order — 0 first, so an unobstructed corner never
+ *  moves. Steps of roughly a control's height; capped so a page that is
+ *  interactive everywhere gets the corner back instead of a perch chasing
+ *  clearance up the viewport. */
+export const PERCH_LIFT_STEPS_PX: readonly number[] = [0, 56, 112, 168];
+
+/** How far probe points pull in from a rect's edges, so a rounded corner
+ *  or a hairline neighbour never reads as an obstruction. */
+const PROBE_EDGE_INSET_PX = 3;
+
+/** The corners and center of a rect — five probes decide a rect. */
+export function probePointsOf(rect: ClearanceRect): ClearancePoint[] {
+  const left = rect.left + PROBE_EDGE_INSET_PX;
+  const right = rect.left + rect.width - PROBE_EDGE_INSET_PX;
+  const top = rect.top + PROBE_EDGE_INSET_PX;
+  const bottom = rect.top + rect.height - PROBE_EDGE_INSET_PX;
+  const centerX = rect.left + rect.width / 2;
+  const centerY = rect.top + rect.height / 2;
+  return [
+    { x: left, y: top },
+    { x: right, y: top },
+    { x: left, y: bottom },
+    { x: right, y: bottom },
+    { x: centerX, y: centerY },
+  ];
+}
+
+export function liftedBy(rect: ClearanceRect, liftPx: number): ClearanceRect {
+  return { ...rect, top: rect.top - liftPx };
+}
+
+/**
+ * The verdict: the smallest lift step at which no probe point over the
+ * perch's hit box hits an obstruction. Falls back to 0 — never a partial
+ * lift — when every step is obstructed or a step would push the box off
+ * the top of the viewport: on a page that gives the corner no clearance
+ * anywhere, a perch parked where the user expects it beats one that
+ * wandered.
+ */
+export function firstClearLiftFor(options: {
+  /** The perch's hit box at lift 0 (its natural position). */
+  rect: ClearanceRect;
+  /** Whether the page stacks an interactive obstruction at a viewport
+   *  point, with the dock's own elements already excluded by the caller. */
+  probe: (point: ClearancePoint) => boolean;
+  liftSteps?: readonly number[];
+}): number {
+  const { rect, probe } = options;
+  const liftSteps = options.liftSteps ?? PERCH_LIFT_STEPS_PX;
+  for (const lift of liftSteps) {
+    const lifted = liftedBy(rect, lift);
+    if (lifted.top < 0) {
+      break;
+    }
+    if (!probePointsOf(lifted).some(probe)) {
+      return lift;
+    }
+  }
+  return 0;
+}
+
+/** What counts as the host's interactive surface under a probe point.
+ *  Anything a click would activate; label pulls in its control. */
+export const INTERACTIVE_OBSTRUCTION_SELECTOR = [
+  "a[href]",
+  "button",
+  "input",
+  "label",
+  "select",
+  "summary",
+  "textarea",
+  '[contenteditable="true"]',
+  '[role="button"]',
+  '[role="checkbox"]',
+  '[role="link"]',
+  '[role="menuitem"]',
+  '[role="option"]',
+  '[role="radio"]',
+  '[role="switch"]',
+  '[role="tab"]',
+  '[role="textbox"]',
+].join(", ");