Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
13.6 KB
Raw Blame
/**
 * Admission-aware drain state machine for queued composer follow-ups.
 *
 * The previous drain used a single boolean "awaiting busy" edge-wait: it was
 * armed before every queued send and cleared only by an observed busy edge or
 * a failed send. When a send was admitted but the busy event never surfaced
 * (dropped SSE event, upstream dispatch failure after admission, or a stream
 * reconnect during admission), the boolean stayed armed forever and every
 * later queued item was wedged behind it.
 *
 * This machine replaces the edge-wait with explicit per-item admission state
 * keyed by the queued item id. A separate native messageID reconciles uncertain
 * POSTs; neither ID grants permission to replay a request. Resolutions include:
 *
 * - `admitted_running`               — admission + a busy observation
 * - `admitted_awaiting_observation`  — admitted, run not yet observed
 * - `completed`                      — an authoritative idle level observed
 *                                      at/after admission released the item
 * - `needs_input`                    — the pre-send gate blocked; the user
 *                                      must retry explicitly
 * - `rejected`                       — the send was cancelled (context
 *                                      changed / unmounted); item re-queued
 * - `admission_unknown`              — POST may have been accepted; only exact
 *                                      message observation releases the hold
 * - `terminal_failure`               — definite failure; explicit retry required
 *
 * A missing busy event is never the only signal that allows progress: an
 * item stuck in `awaiting_observation` is released by a *level-reconciled*
 * idle observation (an authoritative status read whose observation time is
 * at/after the admission time), never by a stale idle that predates the
 * admission.
 *
 * State lives in a module-level per-session store (not component refs) so an
 * in-flight admission survives navigating away from and back to the session.
 */

/** How long an admitted send may go unobserved before the drain probes an
 * authoritative status level instead of waiting for the busy edge. */
export const QUEUE_ADMISSION_OBSERVATION_TIMEOUT_MS = 10_000;

/** Spacing between authoritative probes when the first probe cannot decide
 * (for example the status endpoint is briefly unreachable). */
export const QUEUE_ADMISSION_PROBE_RETRY_MS = 5_000;

export type QueuedDrainPhase =
  | { kind: "ready" }
  | { kind: "sending"; itemId: string; busySeen: boolean }
  | { kind: "admission_unknown"; itemId: string; messageID: string; at: number }
  | { kind: "awaiting_observation"; itemId: string; admittedAt: number }
  | { kind: "running"; itemId: string }
  | { kind: "halted"; itemId: string; reason: "needs_input" | "terminal_failure" };

export type QueuedItemResolution =
  | "admitted_running"
  | "admitted_awaiting_observation"
  | "completed"
  | "needs_input"
  | "rejected"
  | "admission_unknown"
  | "terminal_failure";

export type QueuedDrainState = {
  phase: QueuedDrainPhase;
  attemptsByItemId: Record<string, number>;
  lastResolution: { itemId: string; resolution: QueuedItemResolution } | null;
};

export type QueuedDrainEvent =
  | { type: "send_started"; itemId: string; steer?: boolean }
  | { type: "stop_confirmed" }
  | { type: "send_result"; itemId: string; outcome: "sent" | "accepted" | "blocked" | "cancelled"; at: number }
  | { type: "send_error"; itemId: string }
  | { type: "send_unknown"; itemId: string; messageID: string; at: number }
  | { type: "admission_observed"; itemId: string; messageID: string; at: number }
  | { type: "busy_observed" }
  /** An authoritative status level read (SSE-followed idle after a busy
   * observation, or an explicit snapshot/status probe). `observedAt` is when
   * the observation was initiated so stale idles are ordered against the
   * admission time and dropped. */
  | { type: "idle_reconciled"; observedAt: number }
  | { type: "user_retry" }
  | { type: "queue_cleared" };

export const INITIAL_QUEUED_DRAIN_STATE: QueuedDrainState = {
  phase: { kind: "ready" },
  attemptsByItemId: {},
  lastResolution: null,
};

function resolved(
  state: QueuedDrainState,
  phase: QueuedDrainPhase,
  itemId: string,
  resolution: QueuedItemResolution,
  attemptsByItemId?: Record<string, number>,
): QueuedDrainState {
  return {
    phase,
    attemptsByItemId: attemptsByItemId ?? state.attemptsByItemId,
    lastResolution: { itemId, resolution },
  };
}

export function reduceQueuedDrain(state: QueuedDrainState, event: QueuedDrainEvent): QueuedDrainState {
  const { phase } = state;
  switch (event.type) {
    case "stop_confirmed":
      // A replacement may already hold the send slot while awaiting Stop.
      // Keep that claim, but discard activity belonging to its predecessor.
      if (phase.kind === "sending") return { ...state, phase: { ...phase, busySeen: false } };
      // A confirmed Stop settles an unknown admission too: nothing is resent.
      return { ...INITIAL_QUEUED_DRAIN_STATE, lastResolution: state.lastResolution };
    case "send_started": {
      if (phase.kind !== "ready") {
        if (!event.steer) return state;
        if (phase.kind === "running" || phase.kind === "awaiting_observation") {
          if (phase.itemId === event.itemId) return state;
        } else if (phase.kind !== "halted" || phase.itemId !== event.itemId) return state;
      }
      const attempts = (state.attemptsByItemId[event.itemId] ?? 0) + 1;
      return {
        phase: { kind: "sending", itemId: event.itemId, busySeen: phase.kind === "running" },
        attemptsByItemId: { ...state.attemptsByItemId, [event.itemId]: attempts },
        lastResolution: state.lastResolution,
      };
    }
    case "send_result": {
      if (phase.kind !== "sending" || phase.itemId !== event.itemId) return state;
      if (event.outcome === "sent" || event.outcome === "accepted") {
        // Admitted. The engine may have rendered its busy status before the
        // send promise resolved; a busy seen during the send belongs to this
        // admission.
        if (phase.busySeen) {
          return resolved(state, { kind: "running", itemId: event.itemId }, event.itemId, "admitted_running");
        }
        return resolved(
          state,
          { kind: "awaiting_observation", itemId: event.itemId, admittedAt: event.at },
          event.itemId,
          "admitted_awaiting_observation",
        );
      }
      if (event.outcome === "blocked") {
        return resolved(
          state,
          { kind: "halted", itemId: event.itemId, reason: "needs_input" },
          event.itemId,
          "needs_input",
        );
      }
      // cancelled: the submission context changed; the caller re-queues the
      // item and the drain may try again when conditions settle.
      return resolved(state, { kind: "ready" }, event.itemId, "rejected");
    }
    case "send_error": {
      if (phase.kind !== "sending" || phase.itemId !== event.itemId) return state;
      return resolved(state, { kind: "halted", itemId: event.itemId, reason: "terminal_failure" }, event.itemId, "terminal_failure");
    }
    case "send_unknown": {
      if (phase.kind !== "sending" || phase.itemId !== event.itemId) return state;
      return resolved(state, { kind: "admission_unknown", itemId: event.itemId, messageID: event.messageID, at: event.at }, event.itemId, "admission_unknown");
    }
    case "admission_observed": {
      if (phase.kind !== "admission_unknown" || phase.itemId !== event.itemId || phase.messageID !== event.messageID) return state;
      // This proves admission, not completion. Require a subsequent run/status
      // observation; a busy/idle from the previously running parent is not proof.
      return resolved(state, { kind: "awaiting_observation", itemId: event.itemId, admittedAt: event.at }, event.itemId, "admitted_awaiting_observation");
    }
    case "busy_observed": {
      if (phase.kind === "sending") {
        return { ...state, phase: { ...phase, busySeen: true } };
      }
      if (phase.kind === "awaiting_observation") {
        return resolved(state, { kind: "running", itemId: phase.itemId }, phase.itemId, "admitted_running");
      }
      return state;
    }
    case "idle_reconciled": {
      if (phase.kind === "running") {
        // Busy was observed for this admission, so a later idle level is a
        // genuinely new level: the run finished.
        return resolved(state, { kind: "ready" }, phase.itemId, "completed", dropAttempt(state, phase.itemId));
      }
      if (phase.kind === "awaiting_observation") {
        // Negative invariant: a stale idle observed before the admission
        // must never release the item — that idle predates our send.
        if (event.observedAt < phase.admittedAt) return state;
        // Authoritative idle at/after admission: either the run started and
        // finished between observations (missed busy edge) or upstream
        // dispatch failed after admission. Either way the admitted item can
        // no longer block the queue.
        return resolved(state, { kind: "ready" }, phase.itemId, "completed", dropAttempt(state, phase.itemId));
      }
      return state;
    }
    case "user_retry": {
      if (phase.kind !== "halted") return state;
      return {
        phase: { kind: "ready" },
        attemptsByItemId: dropAttempt(state, phase.itemId),
        lastResolution: state.lastResolution,
      };
    }
    case "queue_cleared": {
      // Stop invalidates preflight work, but cannot prove whether an in-flight
      // POST was accepted. Keep its slot until that send settles or is observed.
      if (phase.kind === "running" || phase.kind === "sending" || phase.kind === "admission_unknown") return state;
      return { ...INITIAL_QUEUED_DRAIN_STATE, lastResolution: state.lastResolution };
    }
  }
}

function dropAttempt(state: QueuedDrainState, itemId: string): Record<string, number> {
  if (!(itemId in state.attemptsByItemId)) return state.attemptsByItemId;
  const next = { ...state.attemptsByItemId };
  delete next[itemId];
  return next;
}

/** True when the drain may admit the next queued item. */
export function canAdmitNextQueuedItem(state: QueuedDrainState): boolean {
  return state.phase.kind === "ready";
}

/** When (epoch ms) the awaiting admission should be probed against an
 * authoritative status level; null when no probe is due. */
export function nextObservationProbeAt(state: QueuedDrainState, lastProbeAt: number | null): number | null {
  if (state.phase.kind !== "awaiting_observation" && state.phase.kind !== "admission_unknown") return null;
  const due = (state.phase.kind === "admission_unknown" ? state.phase.at : state.phase.admittedAt) + QUEUE_ADMISSION_OBSERVATION_TIMEOUT_MS;
  if (lastProbeAt === null) return due;
  return Math.max(due, lastProbeAt + QUEUE_ADMISSION_PROBE_RETRY_MS);
}

// --- Per-session store -----------------------------------------------------
//
// Component refs die on unmount, but an admission does not: navigating away
// from a session and back while its first queued item is running must not
// forget the in-flight admission (a fresh boolean would either wedge or,
// worse, drain the next item into a stale idle render). Sessions are pruned
// from the map as soon as they return to the initial state.

const drainStateBySession = new Map<string, QueuedDrainState>();
const drainListenersBySession = new Map<string, Set<() => void>>();
const sendGenerationBySession = new Map<string, number>();

export function getQueuedSendGeneration(sessionId: string): number {
  return sendGenerationBySession.get(sessionId) ?? 0;
}

export function assertQueuedSendCurrent(sessionId: string, generation: number): void {
  if (getQueuedSendGeneration(sessionId) !== generation) throw new Error("Send cancelled by Stop.");
}

export function getQueuedDrainState(sessionId: string): QueuedDrainState {
  return drainStateBySession.get(sessionId) ?? INITIAL_QUEUED_DRAIN_STATE;
}

export function dispatchQueuedDrain(sessionId: string, event: QueuedDrainEvent): QueuedDrainState {
  if (event.type === "queue_cleared") {
    sendGenerationBySession.set(sessionId, getQueuedSendGeneration(sessionId) + 1);
  }
  const current = getQueuedDrainState(sessionId);
  const next = reduceQueuedDrain(current, event);
  if (next === current) return current;
  if (next.phase.kind === "ready" && Object.keys(next.attemptsByItemId).length === 0 && next.lastResolution === null) {
    drainStateBySession.delete(sessionId);
  } else {
    drainStateBySession.set(sessionId, next);
  }
  const listeners = drainListenersBySession.get(sessionId);
  if (listeners) for (const listener of listeners) listener();
  return next;
}

/** Atomically claim the send slot for one queued item. Returns false when
 * another surface (for example a split view of the same session) already
 * holds a non-ready phase, so a queued item can never be sent twice. */
export function claimQueuedSend(sessionId: string, itemId: string, steer = false): boolean {
  const current = getQueuedDrainState(sessionId);
  const next = dispatchQueuedDrain(sessionId, { type: "send_started", itemId, steer });
  return next !== current && next.phase.kind === "sending" && next.phase.itemId === itemId;
}

export function subscribeQueuedDrain(sessionId: string, listener: () => void): () => void {
  const listeners = drainListenersBySession.get(sessionId) ?? new Set();
  drainListenersBySession.set(sessionId, listeners);
  listeners.add(listener);
  return () => {
    listeners.delete(listener);
    if (listeners.size === 0) drainListenersBySession.delete(sessionId);
  };
}

/** Test-only: forget every session's drain state. */
export function resetQueuedDrainForTests() {
  drainStateBySession.clear();
  drainListenersBySession.clear();
  sendGenerationBySession.clear();
}