@teaflask/assistant 0.3.0 → 0.6.0

package/src/core/execution-driver.ts

@@ -1,438 +0,0 @@
-import type {
-  AssistantThreadDetailResponse,
-  ResolveTurnToolResultsRequest,
-  ResolveTurnToolResultsResponse,
-  ServingAssistantTurn,
-} from "../contract/threads.js";
-import {
-  readExecutedOutcome,
-  recordExecutedOutcome,
-  recordExecutionClaimed,
-} from "../persistence/execution-ledger.js";
-import { ServingApiError } from "../transport/serving-error.js";
-import {
-  KIND_UNSUPPORTED_OUTCOME,
-  MEMBER_ANSWERABLE_KINDS,
-  type ExecutionHandler,
-  type ExecutionOutcome,
-} from "./execution-handlers.js";
-import {
-  coworkerExecutionRequestOf,
-  type ExecutionEntryModel,
-  type ExecutionInbox,
-} from "./execution-inbox.js";
-import { MAX_DELIVERY_ATTEMPTS } from "./execution-kinds.js";
-
-// The driver that drains the execution inbox — the automatic half the
-// approval flow leaves to a human. Never inside an event callback: a
-// deferred pass lets a replay burst's own evidence (the receipt, the
-// gated call's result) close stale entries before anything acts, then a
-// REST read confirms the pause is genuinely open, the inbox claim takes
-// the entry, and the ledger makes the execution at-most-once even across
-// the remount a navigation causes.
-const EXECUTION_PASS_DELAY_MS = 400;
-// A failed POST retries on a slower cadence — the outcome is already in
-// the ledger, so only the delivery is being retried.
-const EXECUTION_RETRY_DELAY_MS = 2000;
-
-export interface ExecutionPassContext {
-  inbox: ExecutionInbox;
-  threadId: string;
-  handlers: ReadonlyMap<string, ExecutionHandler>;
-  /** Delivery attempts per interrupt id — exhausted entries stay pending
-   *  for the NEXT connection's pass (re-POST is the designed recovery). */
-  attempts: Map<string, number>;
-  fetchThreadDetail: () => Promise<AssistantThreadDetailResponse>;
-  postResults: (
-    turnId: string,
-    request: ResolveTurnToolResultsRequest,
-  ) => Promise<ResolveTurnToolResultsResponse>;
-  publishEntries: (entries: readonly ExecutionEntryModel[]) => void;
-  onWorkflowRestarted: () => void;
-}
-
-/**
- * One drain of the inbox's pending entries. Exported so the pass logic
- * unit-tests in node — the ExecutionDriver below is only a scheduler
- * around it.
- */
-export async function runExecutionPass(
-  context: ExecutionPassContext,
-): Promise<void> {
-  const eligible = eligibleEntriesOf(context.inbox.entries(), context.attempts);
-  if (eligible.length === 0) {
-    return;
-  }
-  const turns = await _theTurnsOrNull(context);
-  if (turns === null || turns.length === 0) {
-    return;
-  }
-  for (const entry of eligible) {
-    await _serveEntry(context, entry, turns);
-  }
-}
-
-function eligibleEntriesOf(
-  entries: readonly ExecutionEntryModel[],
-  attempts: ReadonlyMap<string, number>,
-): ExecutionEntryModel[] {
-  return entries.filter(
-    (entry) =>
-      entry.status.kind === "pending" &&
-      // A member-answerable kind (builtin.ask_questions) is never the
-      // driver's to serve: auto-answering it — even as unsupported —
-      // would withdraw the ask. Its entry stays pending for the member's
-      // own submit and closes on stream evidence like every entry.
-      !MEMBER_ANSWERABLE_KINDS.has(entry.kind) &&
-      (attempts.get(entry.interruptId) ?? 0) < MAX_DELIVERY_ATTEMPTS,
-  );
-}
-
-async function _serveEntry(
-  context: ExecutionPassContext,
-  entry: ExecutionEntryModel,
-  turns: readonly ServingAssistantTurn[],
-): Promise<void> {
-  const stored = readExecutedOutcome(context.threadId, entry.interruptId);
-  // The pause's holder is resolved across the WHOLE window, newest match
-  // first (there is no busy 409, so the answerable turn can sit
-  // behind QUEUED rows — "newest turn" is not "the pause").
-  const holder = _theTurnStillHoldingThisPause(turns, entry);
-  if (stored === null && holder === null) {
-    // REST is the acting authority, never the lifetime authority: the
-    // entry stays untouched and the stream's own evidence closes it.
-    return;
-  }
-  if (!context.inbox.beginExecution(entry.interruptId)) {
-    return;
-  }
-  context.publishEntries(context.inbox.entries());
-  const outcome = stored ?? (await _freshOutcomeOf(context, entry));
-  // A stored outcome with no live holder re-POSTs to the ORIGIN turn —
-  // the run the card came from — where the door's evidence arms
-  // (recorded_after_void / already_recorded) expect it; a queued newer
-  // member turn must never be guessed at (it would 409 and markRunStale
-  // would drop the executed result). The newest turn remains only the
-  // lost-capture fallback, backstopped by the door's own 409.
-  // THE PREMISE: a coworker's request has exactly ONE legal
-  // door — its dispatching turn. The door's coworker arms key on the
-  // coworker's ordinal across the whole thread and on the posted turn's
-  // own status, so a wrong turn is not backstopped by a 409 the way the
-  // assistant's newest-turn guess is: it can DELIVER under a pause that
-  // never asked, or record evidence under an unrelated run, and it would
-  // dodge the door's off-page refusal by naming an on-page turn. So a
-  // coworker's stored outcome re-POSTs to its dispatching turn or waits
-  // this pass — the entry stays pending; the row leaving paused delists it.
-  const target =
-    holder ??
-    (entry.asker.kind === "coworker"
-      ? turns.find((turn) => turn.id === entry.turnId)
-      : (_theTurnOfThisEntriesRun(turns, entry) ?? turns.at(-1)));
-  if (target === undefined) {
-    // Reachable only for a coworker's stored outcome whose dispatching turn
-    // is off the fetched window. Every arm that returns an entry to pending
-    // without a delivery counts an attempt (tests/driver-retry-arms): the
-    // driver's next pass then rides the retry cadence and the cap parks the
-    // entry for the next connection — a bounded wait, never a spin.
-    _countDeliveryAttempt(context.attempts, entry.interruptId);
-    if (context.inbox.settlePostFailed(entry.interruptId)) {
-      context.publishEntries(context.inbox.entries());
-    }
-    return;
-  }
-  await _reportOutcome(context, entry, target.id, outcome);
-}
-
-function _theTurnStillHoldingThisPause(
-  turns: readonly ServingAssistantTurn[],
-  entry: ExecutionEntryModel,
-): ServingAssistantTurn | null {
-  for (let index = turns.length - 1; index >= 0; index -= 1) {
-    const turn = turns[index];
-    if (_turnStillHoldsThisPause(turn, entry)) {
-      return turn;
-    }
-  }
-  return null;
-}
-
-function _theTurnOfThisEntriesRun(
-  turns: readonly ServingAssistantTurn[],
-  entry: ExecutionEntryModel,
-): ServingAssistantTurn | undefined {
-  return turns.find((turn) => turn.run_id === entry.runId);
-}
-
-async function _freshOutcomeOf(
-  context: ExecutionPassContext,
-  entry: ExecutionEntryModel,
-): Promise<ExecutionOutcome> {
-  // Claimed in the ledger before the handler runs: a tab dying mid-handler
-  // must read back as unknown-outcome, never as unexecuted.
-  recordExecutionClaimed(context.threadId, entry.interruptId);
-  const handler = context.handlers.get(entry.kind);
-  const outcome =
-    handler === undefined
-      ? KIND_UNSUPPORTED_OUTCOME
-      : await _outcomeNeverThrown(handler, entry);
-  recordExecutedOutcome(context.threadId, entry.interruptId, outcome);
-  return outcome;
-}
-
-async function _reportOutcome(
-  context: ExecutionPassContext,
-  entry: ExecutionEntryModel,
-  turnId: string,
-  outcome: ExecutionOutcome,
-): Promise<void> {
-  try {
-    const resolution = await context.postResults(turnId, {
-      results: [
-        {
-          interrupt_id: entry.interruptId,
-          ok: outcome.ok,
-          ...(outcome.ok
-            ? { result: outcome.result }
-            : { error: { ...outcome.error } }),
-          // Names the coworker for a report that lands after its row
-          // settled — the door's evidence arm reads it.
-          ...(entry.asker.kind === "coworker"
-            ? { coworker_ordinal: entry.asker.ordinal }
-            : {}),
-        },
-      ],
-    });
-    context.inbox.settleReported(entry.interruptId, outcome.ok);
-    // Delivery is asynchronous (the response's turn still says
-    // awaiting_input); on a live pause the stream's own resume closes the
-    // entry. A result that restarted a parked turn's workflow has no live
-    // stream to do that — reconnecting is what picks up the restarted run.
-    // The delivery field alone decides (the submit paths' law): a notice
-    // can accompany a DELIVERED restart too — the door pairs the
-    // oversize-drop notice with workflow_restarted — and skipping the
-    // reconnect there would freeze the transcript on the dead run.
-    if (resolution.delivery === "workflow_restarted") {
-      context.onWorkflowRestarted();
-    }
-  } catch (error) {
-    if (_turnNoLongerAwaitingToolResults(error)) {
-      // Voided, settled, or answered elsewhere: the whole pause is over —
-      // or, for a coworker's request, that one request is.
-      if (entry.asker.kind === "coworker") {
-        context.inbox.markCoworkerRequestStale(entry.interruptId);
-      } else {
-        context.inbox.markRunStale(entry.runId);
-      }
-    } else {
-      // The POST failed, not the execution — pending again, and the next
-      // pass re-POSTs the stored outcome on the retry cadence.
-      _countDeliveryAttempt(context.attempts, entry.interruptId);
-      context.inbox.settlePostFailed(entry.interruptId);
-    }
-  } finally {
-    context.publishEntries(context.inbox.entries());
-  }
-}
-
-async function _outcomeNeverThrown(
-  handler: ExecutionHandler,
-  entry: ExecutionEntryModel,
-): Promise<ExecutionOutcome> {
-  try {
-    return await handler(entry);
-  } catch (error) {
-    // Handlers shape their own failures; this catches only a handler bug,
-    // and the turn must still resume.
-    return {
-      ok: false,
-      error: {
-        code: "execution_failed",
-        message:
-          "The page hit an unexpected error while performing this action. " +
-          "Tell the user what was being attempted so they can do it " +
-          `themselves. (${error instanceof Error ? error.message : String(error)})`,
-      },
-    };
-  }
-}
-
-async function _theTurnsOrNull(
-  context: ExecutionPassContext,
-): Promise<readonly ServingAssistantTurn[] | null> {
-  try {
-    // The whole newest window, not just the newest row: a
-    // message during a live turn QUEUES, so the turn holding the pause
-    // is not necessarily the newest one.
-    return (await context.fetchThreadDetail()).turns;
-  } catch {
-    // A transient read failure: the entries stay pending and the next
-    // publish (or the next connection) schedules another pass.
-    return null;
-  }
-}
-
-function _turnStillHoldsThisPause(
-  turn: ServingAssistantTurn,
-  entry: ExecutionEntryModel,
-): boolean {
-  if (entry.asker.kind === "coworker") {
-    // A coworker's request is held by its DISPATCHING turn, whatever that
-    // turn's status (normally settled), for as long as the snapshot lists
-    // it — the coworker's row leaving paused is what delists it.
-    return (
-      turn.id === entry.turnId &&
-      (turn.pending_coworker_executions ?? []).some(
-        (raw) =>
-          coworkerExecutionRequestOf(raw)?.card.interrupt_id ===
-          entry.interruptId,
-      )
-    );
-  }
-  const stillAnswerable =
-    turn.status === "awaiting_input" || turn.status === "parked";
-  if (!stillAnswerable) {
-    return false;
-  }
-  // A null run_id is a lost capture — the server cannot locate the
-  // pause's cards either (pending_interrupt_ids reads empty), so the
-  // status gate alone holds and the door's own 409 backstops a stale
-  // guess.
-  if (turn.run_id === null) {
-    return true;
-  }
-  return (
-    turn.run_id === entry.runId && _turnStillAwaitsThisInterrupt(turn, entry)
-  );
-}
-
-function _turnStillAwaitsThisInterrupt(
-  turn: ServingAssistantTurn,
-  entry: ExecutionEntryModel,
-): boolean {
-  // A replayed card from a superseded round must not act even though
-  // status and run still match. A server predating the field sends no
-  // array at all — that degrades to the status+run gate; an actual empty
-  // list means the pause moved on, so absent must never read as empty.
-  return (
-    !Array.isArray(turn.pending_interrupt_ids) ||
-    turn.pending_interrupt_ids.includes(entry.interruptId)
-  );
-}
-
-function _turnNoLongerAwaitingToolResults(error: unknown): boolean {
-  return (
-    error instanceof ServingApiError &&
-    error.code === "ASSISTANT_TURN_NOT_AWAITING_TOOL_RESULTS"
-  );
-}
-
-function _countDeliveryAttempt(
-  attempts: Map<string, number>,
-  interruptId: string,
-): void {
-  attempts.set(interruptId, (attempts.get(interruptId) ?? 0) + 1);
-}
-
-export interface ExecutionDriverDeps {
-  inbox: ExecutionInbox;
-  threadId: string;
-  /** Read fresh at each pass: the host's handlers map changes identity
-   *  with the provider's re-renders (navigate ref), and the driver must
-   *  never act on a stale one. */
-  handlersOf: () => ReadonlyMap<string, ExecutionHandler>;
-  fetchThreadDetail: () => Promise<AssistantThreadDetailResponse>;
-  postResults: (
-    turnId: string,
-    request: ResolveTurnToolResultsRequest,
-  ) => Promise<ResolveTurnToolResultsResponse>;
-  publishEntries: (entries: readonly ExecutionEntryModel[]) => void;
-  onWorkflowRestarted: () => void;
-}
-
-/**
- * Schedules a drain whenever the inbox holds actionable entries. One pass
- * runs at a time; a signal that lands mid-pass queues exactly one
- * follow-up, so evidence arriving during a pass is never missed. The
- * timer dies with `dispose()`, but an in-flight pass runs to completion —
- * that is what carries the result POST across whatever tears the driver
- * down.
- */
-export class ExecutionDriver {
-  /** Per-driver on purpose: exhausted entries stay pending for the NEXT
-   *  connection's driver (re-POST is the designed recovery). */
-  private readonly attempts = new Map<string, number>();
-  private passRunning = false;
-  private passQueued = false;
-  private timer: ReturnType<typeof setTimeout> | null = null;
-  private disposed = false;
-
-  constructor(private readonly deps: ExecutionDriverDeps) {}
-
-  /** Call with every published entries snapshot; each call resets the
-   *  pending timer, so the drain fires one quiet delay after the latest
-   *  evidence rather than racing a replay burst. */
-  noteEntriesChanged(entries: readonly ExecutionEntryModel[]): void {
-    if (this.disposed) {
-      return;
-    }
-    this._clearTimer();
-    const eligible = eligibleEntriesOf(entries, this.attempts);
-    if (eligible.length === 0) {
-      return;
-    }
-    this.timer = setTimeout(
-      () => {
-        void this._drainInbox();
-      },
-      this._someDeliveryWasAttempted(eligible)
-        ? EXECUTION_RETRY_DELAY_MS
-        : EXECUTION_PASS_DELAY_MS,
-    );
-  }
-
-  dispose(): void {
-    this.disposed = true;
-    this._clearTimer();
-  }
-
-  private async _drainInbox(): Promise<void> {
-    if (this.passRunning) {
-      this.passQueued = true;
-      return;
-    }
-    this.passRunning = true;
-    try {
-      do {
-        this.passQueued = false;
-        await runExecutionPass({
-          inbox: this.deps.inbox,
-          threadId: this.deps.threadId,
-          handlers: this.deps.handlersOf(),
-          attempts: this.attempts,
-          fetchThreadDetail: this.deps.fetchThreadDetail,
-          postResults: this.deps.postResults,
-          publishEntries: this.deps.publishEntries,
-          onWorkflowRestarted: this.deps.onWorkflowRestarted,
-        });
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- a timer firing mid-pass flips the flag during the await above
-      } while (this.passQueued);
-    } finally {
-      this.passRunning = false;
-    }
-  }
-
-  private _someDeliveryWasAttempted(
-    eligible: readonly ExecutionEntryModel[],
-  ): boolean {
-    return eligible.some(
-      (entry) => (this.attempts.get(entry.interruptId) ?? 0) > 0,
-    );
-  }
-
-  private _clearTimer(): void {
-    if (this.timer !== null) {
-      clearTimeout(this.timer);
-      this.timer = null;
-    }
-  }
-}