@teaflask/assistant 0.0.0 → 0.3.0

package/src/core/execution-inbox.ts

@@ -0,0 +1,527 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+
+import {
+  TOOL_EXECUTION_REQUESTED_EVENT_NAME,
+  TOOL_RESULT_RECORDED_EVENT_NAME,
+  type ToolExecutionRequestedPayload,
+} from "../contract/events.js";
+import type { TurnStatus } from "../contract/threads.js";
+import { isTerminalTurnStatus } from "./activity.js";
+import { MEMBER_ANSWERABLE_KINDS } from "./execution-kinds.js";
+import {
+  coworkerExecutionRequestOf,
+  executionRequestedPayloadOf,
+  recordOrNull,
+  type CoworkerRequestTurn,
+} from "./execution-request-narrowing.js";
+
+export {
+  coworkerExecutionRequestOf,
+  executionRequestedPayloadOf,
+  type CoworkerRequestTurn,
+} from "./execution-request-narrowing.js";
+
+// A paused turn's pending client executions, distilled from the stream —
+// the execution twin of the approval inbox, and its posture: the stream
+// is the fast path for an entry's lifetime and the durable turn record
+// its authority. A tool_execution_requested marker opens work, and the
+// evidence that follows — the tool_result_recorded receipt, the gated
+// call's TOOL_CALL_RESULT, RUN_ERROR, a later pause round, the settled
+// turn's word — reports or closes it. Full replay (the frozen resume
+// semantic) then needs no special casing: a reload mid-pause replays the
+// marker with nothing after it and the entry comes back pending; a
+// reload after the delivery replays the marker AND its receipt in the
+// same burst, so the entry lands reported before the driver's deferred
+// pass could ever act on it.
+//
+// Where the approval inbox waits for a human, this one is drained by an
+// automatic driver — so the claim (beginExecution) is the at-most-once
+// gate, and a failed POST returns the entry to pending because the
+// designed recovery is a re-POST of the stored outcome, never a second
+// execution.
+//
+// Entries of ANY kind are held (they close on the same evidence as the
+// rest); only the driver's handler registry decides what executes, and a
+// kind this client cannot serve is answered with a canned unsupported
+// error rather than parked — inside a single mount there is no other
+// handler to defer to.
+//
+// The inbox is deliberately React-free so the lifecycle is unit-testable;
+// every mutator answers "did visible state change" so the recorder only
+// publishes snapshots that matter.
+
+export type ExecutionEntryStatus =
+  | { kind: "pending" }
+  | { kind: "executing" }
+  | { kind: "reported"; ok: boolean }
+  | { kind: "stale" };
+
+/** Who asked: the assistant's own request rides the stream's
+ *  marker; a coworker's rides its DISPATCHING turn's REST snapshot
+ *  (pending_coworker_executions) and is answered at that turn's door. */
+type ExecutionAsker =
+  { kind: "assistant" } | { kind: "coworker"; ordinal: number };
+
+export interface ExecutionEntryModel {
+  /** The contract's opaque interrupt id — the entry key and the report id. */
+  interruptId: string;
+  toolName: string;
+  toolCallId: string | null;
+  /** True when the request's own tool row already streamed. An anchored
+   *  ask is ordered in the suspension queue by its row and settled on it
+   *  by the row projection (the approval cards' anchored/orphan split;
+   *  only member-answerable kinds render cards, but the fact is stream
+   *  evidence and lives here with the rest). */
+  anchored: boolean;
+  /** The request's open, additive kind vocabulary (e.g. builtin.navigate). */
+  kind: string;
+  /** The request's action payload, verbatim from the wire. */
+  action: Record<string, unknown> | null;
+  /** The request's server-built intent payload, verbatim from the wire. */
+  intent: Record<string, unknown> | null;
+  round: number;
+  /** The server run that paused, stamped from the enclosing RUN_STARTED —
+   *  for a coworker's request, the dispatching turn's run. */
+  runId: string;
+  status: ExecutionEntryStatus;
+  asker: ExecutionAsker;
+  /** The dispatching turn a coworker's result is posted to; null for the
+   *  assistant's own requests, which the driver resolves by run. */
+  turnId: string | null;
+}
+
+const PENDING: ExecutionEntryStatus = { kind: "pending" };
+
+/** The turn fields the settled-run reconcile reads. The status is the
+ *  generated union, never bare string: a renamed status word in the spec
+ *  must fail the compile here, not silently stop closing that run's
+ *  entries (contract/dispatches.ts states the rule for the ledger). */
+export interface SettledRunView {
+  run_id: string | null;
+  status: TurnStatus;
+}
+
+interface CoworkerAsk {
+  asker: ExecutionAsker;
+  turnId: string;
+  runId: string;
+}
+
+/** Narrow a tool_result_recorded CUSTOM event's wire value. */
+export function toolResultRecordedPayloadOf(
+  value: unknown,
+): { interruptId: string; ok: boolean } | 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;
+  }
+  return {
+    interruptId: record.interrupt_id,
+    ok: typeof record.ok === "boolean" ? record.ok : true,
+  };
+}
+
+export class ExecutionInbox {
+  private currentRunId: string | null = null;
+  private readonly seenRunIds = new Set<string>();
+  private readonly seenToolCallIds = new Set<string>();
+  // The coworker requests REST has named, by interrupt id — what a
+  // stream marker for one of them is re-labelled from.
+  private readonly coworkerAsks = new Map<string, CoworkerAsk>();
+  private entryList: ExecutionEntryModel[] = [];
+
+  // --- the stream side -------------------------------------------------
+
+  noteRunStarted(runId: string): boolean {
+    this.currentRunId = runId;
+    if (this.seenRunIds.has(runId)) {
+      // A run id already seen is a RE-ENTERED historical segment: the
+      // thread stream re-opens an old run's segment whenever a row lands
+      // late under it (a coworker's answer is recorded under its
+      // dispatching turn's run) — nothing began, nothing closes.
+      return false;
+    }
+    this.seenRunIds.add(runId);
+    // A run beginning for the first time is closing evidence for the
+    // assistant's straggler entries — only the newest run can still be
+    // awaiting input. A coworker's pause outlives the parent's runs.
+    return this._removeWhere(
+      (entry) => entry.asker.kind === "assistant" && entry.runId !== runId,
+    );
+  }
+
+  noteToolCallStart(toolCallId: string): boolean {
+    // TOOL_CALL_START precedes its pause marker in stream order, so the
+    // set is complete by the time anchoring is judged — nothing to
+    // publish here (the approval inbox's own semantics).
+    this.seenToolCallIds.add(toolCallId);
+    return false;
+  }
+
+  noteExecutionRequested(payload: ToolExecutionRequestedPayload): boolean {
+    if (this.currentRunId === null) {
+      // A marker outside any run segment is unanchorable — ignore it.
+      return false;
+    }
+    const runId = this.currentRunId;
+    if (this._hasEntry(payload.interrupt_id)) {
+      // A replayed marker for an entry we already hold: keep the entry's
+      // status — replay must never reopen an already-reported request.
+      return false;
+    }
+    const coworkerAsk = this.coworkerAsks.get(payload.interrupt_id);
+    if (coworkerAsk !== undefined) {
+      if (MEMBER_ANSWERABLE_KINDS.has(payload.request.kind)) {
+        // The stream door of the adoption's skip below: not held here
+        // either, or it would be an assistant entry minting a question card.
+        return false;
+      }
+      // A marker for a request REST already named as a coworker's: its
+      // round is the coworker's own and never meets the parent's
+      // arbitration below.
+      this.entryList.push(
+        _entryOf(payload, this.seenToolCallIds, coworkerAsk.runId, coworkerAsk),
+      );
+      return true;
+    }
+    // THE PREMISE: round arbitration is the ASSISTANT's alone. A coworker's
+    // entry carries the dispatching turn's run id and the CHILD's segment
+    // round — two namespaces that share a bucket only by accident — and its
+    // lifetime is REST's, so it neither competes with nor supersedes the
+    // parent's rounds (the dashboard's inbox-asker census pins it).
+    const newestRound = this._newestRoundOf(runId);
+    if (newestRound !== null && payload.round < newestRound) {
+      // A lower round replaying after a later pause is history, not an ask.
+      return false;
+    }
+    // A higher round supersedes the run's earlier entries (round
+    // namespacing: multi-pause turns re-emit cards and must not collide).
+    if (newestRound !== null && payload.round > newestRound) {
+      this._removeWhere(
+        (entry) =>
+          entry.asker.kind === "assistant" &&
+          entry.runId === runId &&
+          entry.round < payload.round,
+      );
+    }
+    this.entryList.push(_entryOf(payload, this.seenToolCallIds, runId, null));
+    return true;
+  }
+
+  // --- the REST side -------------------------------------------
+
+  /**
+   * The coworker requests the turn snapshot lists, adopted: a card not
+   * held opens a pending entry addressed to its dispatching turn; a held
+   * pending entry the stream delivered first is re-labelled; a coworker
+   * entry no turn lists anymore is gone (its row left paused). Bypasses
+   * the marker path's round arbitration — a coworker's round is its own.
+   */
+  adoptCoworkerRequests(turns: readonly CoworkerRequestTurn[]): boolean {
+    let changed = false;
+    const listed = new Set<string>();
+    for (const turn of turns) {
+      for (const raw of turn.pending_coworker_executions ?? []) {
+        const request = coworkerExecutionRequestOf(raw);
+        if (request === null) {
+          continue;
+        }
+        const interruptId = request.card.interrupt_id;
+        // The label and drill-in handle the snapshot carries are the ledger
+        // join's to render; the entry keeps only what its readers use.
+        const ask: CoworkerAsk = {
+          asker: { kind: "coworker", ordinal: request.ordinal },
+          turnId: turn.id,
+          runId: turn.run_id ?? turn.id,
+        };
+        this.coworkerAsks.set(interruptId, ask);
+        if (MEMBER_ANSWERABLE_KINDS.has(request.card.request.kind)) {
+          // A coworker's request has exactly one door, the driver's POST
+          // under its dispatching turn. A member-answerable kind would leave
+          // through the question-set submit instead, addressed by the
+          // assistant's run and staling that whole run on a 409 — so it is
+          // held on neither door: not adopted here, and the ask is remembered
+          // so a stream marker for the id is dropped by noteExecutionRequested
+          // instead of landing as the assistant's (the playground twin's
+          // posture). Unreachable today: a coworker runs HEADLESS and ask_user
+          // mounts on LIVE only — the approval inbox's asker-carrying card
+          // does not change that.
+          // A marker that beat the snapshot here landed as the assistant's;
+          // it leaves now.
+          const dropped = this._removeWhere(
+            (entry) => entry.interruptId === interruptId,
+          );
+          changed = dropped || changed;
+          continue;
+        }
+        listed.add(interruptId);
+        const held = this.entryList.find(
+          (entry) => entry.interruptId === interruptId,
+        );
+        if (held === undefined) {
+          this.entryList.push(
+            _entryOf(request.card, this.seenToolCallIds, ask.runId, ask),
+          );
+          changed = true;
+        } else if (held.asker.kind === "assistant") {
+          held.asker = ask.asker;
+          held.turnId = ask.turnId;
+          changed = true;
+        }
+      }
+    }
+    if (turns.length > 0) {
+      const removed = this._removeWhere(
+        (entry) =>
+          entry.asker.kind === "coworker" && !listed.has(entry.interruptId),
+      );
+      changed = removed || changed;
+    }
+    return changed;
+  }
+
+  /** A 409 for a coworker's request speaks for that request alone. */
+  markCoworkerRequestStale(interruptId: string): boolean {
+    return this._staleWhere(
+      (entry) =>
+        entry.asker.kind === "coworker" && entry.interruptId === interruptId,
+    );
+  }
+
+  /** The member's send voids every paused coworker of the thread. */
+  markCoworkerRequestsStale(): boolean {
+    return this._staleWhere((entry) => entry.asker.kind === "coworker");
+  }
+
+  noteToolResultRecorded(interruptId: string, ok: boolean): boolean {
+    // The receipt is the stream saying "a delivery happened" — on a replay
+    // it lands right after the marker it answers, so the entry flips to
+    // reported in the same burst and the driver can never claim an
+    // already-answered request. The gated call's result (or RUN_ERROR, or
+    // the settled turn's word) still closes the entry, as on the live path.
+    return this._transition(interruptId, ["pending", "executing"], {
+      kind: "reported",
+      ok,
+    });
+  }
+
+  noteToolCallResult(toolCallId: string): boolean {
+    // The gated call producing a result is the resume made visible.
+    return this._removeWhere((entry) => entry.toolCallId === toolCallId);
+  }
+
+  noteRunFinished(): boolean {
+    // A RUN_FINISHED closes nothing by itself. THE PREMISE: the thread
+    // streamer synthesizes a RUN_FINISHED for the LIVE run right before it
+    // re-enters an old run's segment for a late row (a coworker's answer or
+    // receipt lands under its dispatching turn's run), and the two frames
+    // are indistinguishable on the wire from a real terminal — so removing
+    // the run's entries here would lose a live pause's ask that nothing
+    // re-delivers. The run's entries die on their own evidence (the receipt,
+    // the gated call's result), on a first-seen run beginning (the
+    // straggler wipe above), on RUN_ERROR, or on the durable turn record's
+    // word (reconcileWithTurns) — the approval inbox's posture too
+    // (the dashboard's run-lifecycle census pins it).
+    return false;
+  }
+
+  /** The durable turn record's word: the assistant's entries
+   *  whose run belongs to a SETTLED turn are gone — the REST-driven close a
+   *  synthesized terminal cannot fake. */
+  reconcileWithTurns(turns: readonly SettledRunView[]): boolean {
+    const settledRuns = new Set(
+      turns
+        .filter((turn) => isTerminalTurnStatus(turn.status))
+        .map((turn) => turn.run_id)
+        .filter((runId): runId is string => runId !== null),
+    );
+    return this._removeWhere(
+      (entry) =>
+        entry.asker.kind === "assistant" && settledRuns.has(entry.runId),
+    );
+  }
+
+  noteRunError(): boolean {
+    // RUN_ERROR carries no runId, and a serving RUN_ERROR ends the stream —
+    // nothing of the assistant's can be answered anymore.
+    return this._removeWhere((entry) => entry.asker.kind === "assistant");
+  }
+
+  // --- the driver side ---------------------------------------------------
+
+  beginExecution(interruptId: string): boolean {
+    // The at-most-once claim: synchronous, so two overlapping passes (or
+    // StrictMode's double connection) can never both win the same entry.
+    return this._transition(interruptId, ["pending"], { kind: "executing" });
+  }
+
+  settleReported(interruptId: string, ok: boolean): boolean {
+    return this._transition(interruptId, ["executing"], {
+      kind: "reported",
+      ok,
+    });
+  }
+
+  settlePostFailed(interruptId: string): boolean {
+    // The POST failed, not the execution — the entry returns to pending so
+    // a later pass re-POSTs the stored outcome. Re-execution is the
+    // ledger's to prevent, never this transition's to allow.
+    return this._transition(interruptId, ["executing"], PENDING);
+  }
+
+  markRunStale(runId: string): boolean {
+    // A 409 speaks for the whole pause: none of the run's open asks can
+    // land anymore. Reported entries keep their honest note.
+    return this._staleWhere(
+      (entry) => entry.asker.kind === "assistant" && entry.runId === runId,
+    );
+  }
+
+  // --- reading -------------------------------------------------------------
+
+  entries(): readonly ExecutionEntryModel[] {
+    return this.entryList.map((entry) => ({ ...entry }));
+  }
+
+  // --- internals -------------------------------------------------------------
+
+  private _hasEntry(interruptId: string): boolean {
+    return this.entryList.some((entry) => entry.interruptId === interruptId);
+  }
+
+  private _newestRoundOf(runId: string): number | null {
+    const rounds = this.entryList
+      .filter(
+        (entry) => entry.asker.kind === "assistant" && entry.runId === runId,
+      )
+      .map((entry) => entry.round);
+    return rounds.length > 0 ? Math.max(...rounds) : null;
+  }
+
+  private _staleWhere(
+    doomed: (entry: ExecutionEntryModel) => boolean,
+  ): boolean {
+    let changed = false;
+    for (const entry of this.entryList) {
+      if (
+        doomed(entry) &&
+        (entry.status.kind === "pending" || entry.status.kind === "executing")
+      ) {
+        entry.status = { kind: "stale" };
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  private _removeWhere(
+    doomed: (entry: ExecutionEntryModel) => boolean,
+  ): boolean {
+    const kept = this.entryList.filter((entry) => !doomed(entry));
+    if (kept.length === this.entryList.length) {
+      return false;
+    }
+    this.entryList = kept;
+    return true;
+  }
+
+  private _transition(
+    interruptId: string,
+    fromKinds: ExecutionEntryStatus["kind"][],
+    to: ExecutionEntryStatus,
+  ): boolean {
+    const entry = this.entryList.find(
+      (known) => known.interruptId === interruptId,
+    );
+    if (entry === undefined || !fromKinds.includes(entry.status.kind)) {
+      return false;
+    }
+    entry.status = to;
+    return true;
+  }
+}
+
+function _entryOf(
+  payload: ToolExecutionRequestedPayload,
+  seenToolCallIds: ReadonlySet<string>,
+  runId: string,
+  ask: CoworkerAsk | null,
+): ExecutionEntryModel {
+  return {
+    interruptId: payload.interrupt_id,
+    toolName: payload.tool_name,
+    toolCallId: payload.tool_call_id ?? null,
+    // A coworker's card names the CHILD run's tool call, which never
+    // streams in the parent's transcript — it anchors nothing here.
+    anchored:
+      payload.tool_call_id != null && seenToolCallIds.has(payload.tool_call_id),
+    kind: payload.request.kind,
+    action: recordOrNull(payload.request.action),
+    intent: recordOrNull(payload.request.intent),
+    round: payload.round,
+    runId,
+    status: PENDING,
+    asker: ask?.asker ?? { kind: "assistant" },
+    turnId: ask?.turnId ?? null,
+  };
+}
+
+/**
+ * The subscriber that feeds the stream into the inbox: markers open
+ * entries, receipts report them, and the resume's own evidence closes
+ * them. Only the server-named run id from RUN_STARTED is trusted — the
+ * connect-run's input.runId is the client's own and never names a
+ * recorded run.
+ *
+ * A quiet close needs nothing from this recorder: an open entry survives
+ * it untouched, because nothing about being answerable depends on whether
+ * the turn parked. The REST consult that tells a park from a dropped
+ * connection, and the go/no-go it drives, stay the approval recorder's.
+ */
+export function executionInboxRecorder(
+  inbox: ExecutionInbox,
+  onEntriesChanged: (entries: readonly ExecutionEntryModel[]) => void,
+): AgentSubscriber {
+  const publishWhen = (changed: boolean) => {
+    if (changed) {
+      onEntriesChanged(inbox.entries());
+    }
+  };
+  return {
+    onRunStartedEvent({ event }) {
+      publishWhen(inbox.noteRunStarted(event.runId));
+    },
+    onCustomEvent({ event }) {
+      if (event.name === TOOL_EXECUTION_REQUESTED_EVENT_NAME) {
+        const payload = executionRequestedPayloadOf(event.value);
+        if (payload !== null) {
+          publishWhen(inbox.noteExecutionRequested(payload));
+        }
+        return;
+      }
+      if (event.name === TOOL_RESULT_RECORDED_EVENT_NAME) {
+        const receipt = toolResultRecordedPayloadOf(event.value);
+        if (receipt !== null) {
+          publishWhen(
+            inbox.noteToolResultRecorded(receipt.interruptId, receipt.ok),
+          );
+        }
+      }
+    },
+    onToolCallStartEvent({ event }) {
+      publishWhen(inbox.noteToolCallStart(event.toolCallId));
+    },
+    onToolCallResultEvent({ event }) {
+      publishWhen(inbox.noteToolCallResult(event.toolCallId));
+    },
+    onRunFinishedEvent() {
+      publishWhen(inbox.noteRunFinished());
+    },
+    onRunErrorEvent() {
+      publishWhen(inbox.noteRunError());
+    },
+  };
+}

package/src/core/execution-kinds.ts

@@ -0,0 +1,98 @@
+// The execution-request kind vocabulary, as a dependency-free leaf:
+// these constants used to live in execution-handlers.ts,
+// whose HANDLERS legitimately import the transport adapter, the DOM
+// reader subtree and the affordances — but the KINDS are pure
+// vocabulary, and the tool-decision anchor family (a value export of
+// the ./transcript projection entry) needs only the member-answerable
+// table. Reading it through the handlers dragged 16
+// transport/reader/affordance modules into an entry whose own law is
+// "React-free and transport-free by construction"
+// (tests/bundle-closure.test.ts pins the closure now).
+// execution-handlers.ts re-exports everything here, so its consumers
+// are unchanged.
+//
+// The same maneuver holds for the outcome vocabulary: the canned
+// kind-unsupported refusal (and the ExecutionOutcome shape it inhabits)
+// moved here from execution-handlers.ts so ./transcript can export it —
+// the dashboard playground answers unservable execution kinds with the
+// package's own sentence rather than a transcription of it. Like the
+// kinds, these are import-free values, so the entry's closure stays
+// transport-free.
+
+// The execution-request kinds the navigate, http_actions, and read_page
+// capabilities mint (the serving contract, "Execution-request kinds").
+export const NAVIGATE_REQUEST_KIND = "builtin.navigate";
+export const HTTP_INTENT_REQUEST_KIND = "http_intent";
+export const READ_PAGE_REQUEST_KIND = "builtin.read_page";
+export const HIGHLIGHT_REQUEST_KIND = "builtin.highlight";
+export const PREFILL_FORM_REQUEST_KIND = "builtin.prefill_form";
+// The conversational elicitation kind: the assistant asked the
+// member a SET of questions in one pause; every answer is plain text.
+// Deliberately NOT in execution-handlers' handler registry.
+export const ASK_QUESTIONS_REQUEST_KIND = "builtin.ask_questions";
+
+/**
+ * The kinds whose executor is the MEMBER, not this client: the driver
+ * must never auto-answer them (its unknown-kind fallback would post
+ * kind_unsupported and withdraw the ask). Their entries stay pending in
+ * the inbox — closing on stream evidence like every entry — and are
+ * answered through the store's submitQuestionAnswers / cancelQuestionSet
+ * when the member submits the rendered panel. Any kind NOT here — one
+ * this client predates, or one it has since retired (the question set's
+ * one-question predecessor) — is answered
+ * kind_unsupported through the driver: the contract's documented
+ * degrade, which the server turns into "ask it in chat" — never an
+ * invisible wait.
+ */
+export const MEMBER_ANSWERABLE_KINDS: ReadonlySet<string> = new Set([
+  ASK_QUESTIONS_REQUEST_KIND,
+]);
+
+// A delivery that keeps failing on transport trouble stops re-posting
+// after this many attempts went wrong — the turn then parks exactly as
+// it did before the driver existed, and reopening the thread re-arms the
+// pass. One value for every deliverer (the package driver and the
+// dashboard playground's refusal pass), here because the
+// ./transcript entry exports it and this leaf is import-free.
+export const MAX_DELIVERY_ATTEMPTS = 3;
+
+type ExecutionErrorCode = "kind_unsupported" | "execution_failed";
+
+/** What the failing API itself said, when the host adapter's error
+ *  carried it: the HTTP status, the API's own error code, and its
+ *  per-field problems (a 422's validation list). Optional and additive
+ *  — an adapter that throws a bare Error yields none. Every member is
+ *  bounded before it rides (execution-handlers.ts). */
+export interface ExecutionFailureDetail {
+  status: number;
+  code: string;
+  fields?: { path: string; message: string }[];
+  /** How many problems the API named beyond `fields` — the per-detail
+   *  cap and the door fit both drop from the tail, and a partial list
+   *  must never read as complete. Present only when positive. */
+  fieldsOmitted?: number;
+}
+
+interface ExecutionError {
+  /** Distinguishes "this client can't serve the kind" from a real failure. */
+  code: ExecutionErrorCode;
+  message: string;
+  detail?: ExecutionFailureDetail;
+}
+
+export type ExecutionOutcome =
+  | { ok: true; result: Record<string, unknown> }
+  | { ok: false; error: ExecutionError };
+
+export const KIND_UNSUPPORTED_OUTCOME: Extract<
+  ExecutionOutcome,
+  { ok: false }
+> = {
+  ok: false,
+  error: {
+    code: "kind_unsupported",
+    message:
+      "This page cannot perform this action itself. Tell the user what " +
+      "you were trying to do and how they can do it themselves.",
+  },
+};