feat(tui): show required operator input at composer

Author: bwachman

BUILD_PLAN.md

@@ -4,6 +4,11 @@ import type {
 } from "../permission/types.js";
 import type { OperatorResult } from "../agent/tools.js";
 
+/** Provenance minted only by the primary session's ask_operator callback. */
+export const PRIMARY_ASK_OPERATOR_SOURCE = "primary-ask-operator" as const;
+
+export type OperatorGateSource = typeof PRIMARY_ASK_OPERATOR_SOURCE;
+
 /** Fail-closed settle when no approval UI can bind the operator's accept. */
 export const APPROVAL_UNAVAILABLE_MESSAGE =
   "no approval UI available; request denied" as const;
@@ -27,6 +32,18 @@ export interface OperatorGateEvent {
    * queue — the modal cannot outlive a tool that already finished.
    */
   signal?: AbortSignal;
+  /**
+   * Optional display provenance minted by the session emitter, never inferred
+   * from an operator question by the TUI.
+   */
+  source?: OperatorGateSource;
+}
+
+/** Only an explicitly marked primary ask may enter input-required chrome. */
+export function isPrimaryAskOperatorEvent(
+  event: OperatorGateEvent,
+): event is OperatorGateEvent & { readonly source: OperatorGateSource } {
+  return event.source === PRIMARY_ASK_OPERATOR_SOURCE;
 }
 
 export interface PermissionGateEvent {

src/tui/gate-events.ts

@@ -23,6 +23,7 @@ import {
 import { streamRowGutter } from "./stream.js";
 import {
   APPROVAL_UNAVAILABLE_MESSAGE,
+  PRIMARY_ASK_OPERATOR_SOURCE,
   type OperatorGateEvent,
   type PermissionGateEvent,
 } from "./gate-events.js";
@@ -36,6 +37,7 @@ import {
   PERMISSION_ONCE_ID,
   permissionBodyFromRequest,
   permissionChoicesFromRequest,
+  type GateLifecycleHooks,
   wireGates,
 } from "./gate-wire.js";
 
@@ -60,6 +62,7 @@ type GateCtx = {
 
 type GateOpts = {
   readonly terminal?: { readonly columns: number; readonly rows: number };
+  readonly hooks?: Partial<GateLifecycleHooks>;
 };
 
 async function withGates(
@@ -70,7 +73,11 @@ async function withGates(
   await withAppShell(
     async (shell, h) => {
       const emitter = new EventEmitter();
-      const disposeGates = wireGates(emitter, shell);
+      const disposeGates = wireGates(emitter, shell, {
+        onGateOpened: () => undefined,
+        onGateClosed: () => undefined,
+        ...opts.hooks,
+      });
       try {
         await fn({ h, shell, emitter, disposeGates });
       } finally {
@@ -463,6 +470,107 @@ describe("wireGates", () => {
     });
   });
 
+  test("marked primary asks notify admission and settlement exactly once", async () => {
+    const admitted: string[] = [];
+    const settled: string[] = [];
+    await withGates(
+      async ({ shell, emitter }) => {
+        emitOperator(emitter, { source: PRIMARY_ASK_OPERATOR_SOURCE });
+        expect(admitted).toEqual(["ask-1"]);
+        acceptOverlaySelection(shell);
+        expect(settled).toEqual(["ask-1"]);
+        closeInsetOverlay(shell);
+        expect(settled).toEqual(["ask-1"]);
+      },
+      {
+        hooks: {
+          onPrimaryOperatorAdmitted: (event) => admitted.push(event.id),
+          onPrimaryOperatorSettled: (event) => settled.push(event.id),
+        },
+      },
+    );
+  });
+
+  test("re-emitted marked primary ask keeps one live gate and resolves once", async () => {
+    const admitted: string[] = [];
+    const settled: string[] = [];
+    const resolved: unknown[] = [];
+    await withGates(
+      async ({ shell, emitter }) => {
+        const event = {
+          id: "same-ask",
+          source: PRIMARY_ASK_OPERATOR_SOURCE,
+          resolve: (result: unknown) => resolved.push(result),
+        };
+        emitOperator(emitter, event);
+        emitOperator(emitter, event);
+
+        expect(admitted).toEqual(["same-ask"]);
+        expect(shell.overlayKind).toBe("operator");
+
+        acceptOverlaySelection(shell);
+
+        expect(settled).toEqual(["same-ask"]);
+        expect(resolved).toEqual([{ kind: "option", index: 0 }]);
+        expect(shell.overlayList).toBeNull();
+      },
+      {
+        hooks: {
+          onPrimaryOperatorAdmitted: (event) => admitted.push(event.id),
+          onPrimaryOperatorSettled: (event) => settled.push(event.id),
+        },
+      },
+    );
+  });
+
+  test("unmarked operator gates retain modal behavior without input-required hooks", async () => {
+    let admitted = 0;
+    let settled = 0;
+    await withGates(
+      async ({ shell, emitter }) => {
+        emitOperator(emitter);
+        expect(shell.overlayKind).toBe("operator");
+        acceptOverlaySelection(shell);
+        expect(admitted).toBe(0);
+        expect(settled).toBe(0);
+      },
+      {
+        hooks: {
+          onPrimaryOperatorAdmitted: () => admitted++,
+          onPrimaryOperatorSettled: () => settled++,
+        },
+      },
+    );
+  });
+
+  test("a marked queued ask settles its own indicator on abort and disposal", async () => {
+    const settled: string[] = [];
+    await withGates(
+      async ({ emitter, disposeGates }) => {
+        emitOperator(emitter, {
+          id: "open",
+          source: PRIMARY_ASK_OPERATOR_SOURCE,
+        });
+        const controller = new AbortController();
+        emitOperator(emitter, {
+          id: "queued",
+          source: PRIMARY_ASK_OPERATOR_SOURCE,
+          signal: controller.signal,
+        });
+        controller.abort();
+        expect(settled).toEqual(["queued"]);
+        disposeGates();
+        expect(settled).toEqual(["queued", "open"]);
+      },
+      {
+        hooks: {
+          onPrimaryOperatorAdmitted: () => undefined,
+          onPrimaryOperatorSettled: (event) => settled.push(event.id),
+        },
+      },
+    );
+  });
+
   test("sequential operator asks paint B's labels and id-scoped values, not A's", async () => {
     await withGates(async ({ shell, emitter }) => {
       const settledA = settleCapture();

src/tui/gate-wire.test.ts

@@ -25,6 +25,7 @@ import {
 import { EXPAND_KEY } from "./stream.js";
 import {
   APPROVAL_UNAVAILABLE_MESSAGE,
+  isPrimaryAskOperatorEvent,
   type OperatorGateEvent,
   type PermissionGateEvent,
 } from "./gate-events.js";
@@ -209,6 +210,10 @@ export interface GateLifecycleHooks {
   readonly onGateOpened: () => void;
   /** A previously raised gate resolved. */
   readonly onGateClosed: () => void;
+  /** A marked primary ask_operator gate became outstanding. */
+  readonly onPrimaryOperatorAdmitted?: (event: OperatorGateEvent) => void;
+  /** A marked primary ask_operator gate settled. */
+  readonly onPrimaryOperatorSettled?: (event: OperatorGateEvent) => void;
 }
 
 const NOOP_GATE_HOOKS: GateLifecycleHooks = {
@@ -258,9 +263,20 @@ export function wireGates(
   // gate still queued at session teardown settles instead of hanging its
   // promise.
   const operatorTeardowns = new Set<() => void>();
-  // Bumped on every open. A settle that knows only "my overlay opened" cannot
-  // tell whether the host has since opened a newer gate; comparing the
-  // open-time capture against the current value closes only its own overlay.
+// A live ask_operator gate can be re-emitted while its original event is
+  // still awaiting an answer. Its id owns the single overlay and resolver
+  // until that gate settles.
+  const liveOperatorGateIds = new Set<string>();
+  // Bumped every time any gate (permission or operator) opens on the shared
+  // host. A settle path that only knows "my overlay was opened" cannot tell
+  // whether the host has since moved on to a newer one - the shell closes an
+  // accepted/cancelled overlay and may open the next queued gate before that
+  // gate's own settle callback runs - and closing blind would tear down that
+  // newer overlay instead of its own. Comparing the generation captured at
+  // open-time against the current one answers that directly, so correctness
+  // never rests on remembering shell.ts's close-before-callback ordering at
+  // each call site. openHost is the only place an overlay opens, so it is
+  // the only place this counter needs to change.
   let overlayGeneration = 0;
 
   function openHost(open: () => void): void {
@@ -438,12 +454,18 @@ export function wireGates(
   }
 
   function onOperator(ev: OperatorGateEvent): void {
-    hooks.onGateOpened();
-    const resolve = onceClosed(hooks.onGateClosed, ev.resolve);
     if (typeof ev.id !== "string" || ev.id.length === 0) {
+      hooks.onGateOpened();
+      const resolve = onceClosed(hooks.onGateClosed, ev.resolve);
       resolve(operatorCancelResult());
       return;
     }
+    if (liveOperatorGateIds.has(ev.id)) return;
+    liveOperatorGateIds.add(ev.id);
+    hooks.onGateOpened();
+    const resolve = onceClosed(hooks.onGateClosed, ev.resolve);
+    const primaryOperator = isPrimaryAskOperatorEvent(ev);
+    if (primaryOperator) hooks.onPrimaryOperatorAdmitted?.(ev);
     const choices = operatorChoicesFromOptions(ev.options, ev.id);
     // Guarded like the permission gate: a settle path that forgets its guard
     // would double-resolve this promise.
@@ -501,6 +523,8 @@ export function wireGates(
       settled = true;
       clearTimers();
       operatorTeardowns.delete(teardown);
+      liveOperatorGateIds.delete(ev.id);
+      if (primaryOperator) hooks.onPrimaryOperatorSettled?.(ev);
       if (openedGeneration === undefined) {
         unqueue(open);
       } else if (openedGeneration === overlayGeneration) {

src/tui/gate-wire.ts

@@ -41,6 +41,8 @@ export interface ZoneVisibility {
   readonly pending?: boolean | number;
   /** WORKER WAITING strip on (default off). */
   readonly workerWait?: boolean;
+  /** INPUT REQUIRED strip for marked primary ask_operator gates (default off). */
+  readonly inputRequired?: boolean;
   /** Progress: false/omit = 0; true = 2; or explicit 1|2. */
   readonly progress?: boolean | 1 | 2;
   /** Progress divider (0–1). Default on when progress is shown. */
@@ -150,6 +152,7 @@ export function desiredHeights(input: GeometryInput): MutableHeights {
     notice: vis.notice === true ? 1 : ZONE_REGISTRY.notice.idleDefault,
     pending: clamp(boolOrRows(vis.pending, 1), 0, ZONE_REGISTRY.pending.max),
     worker_wait: vis.workerWait === true ? 1 : 0,
+    input_required: vis.inputRequired === true ? 1 : 0,
     prompt: promptRows,
     task: clamp(boolOrRows(vis.task, 1), 0, ZONE_REGISTRY.task.max),
     // The board asks for exactly the rows it paints; the fraction stops a large

src/tui/geometry/resolve.ts

@@ -9,6 +9,7 @@ const ZONE_IDS = [
   "notice",
   "pending",
   "worker_wait",
+  "input_required",
   "prompt",
   "task",
   "agents",
@@ -92,8 +93,15 @@ export const ZONE_REGISTRY: Readonly<Record<ZoneId, ZoneDeclaration>> = {
     idleDefault: 0,
     alwaysOn: false,
   },
-  // Grows with the draft; the resolver caps it at PROMPT_CAP_FRACTION and
-  // collapses toward min when the transcript would breach its floor.
+input_required: {
+    id: "input_required",
+    min: 0,
+    max: 1,
+    idleDefault: 0,
+    alwaysOn: false,
+  },
+  // Grows with what is being composed; the resolver caps it at PROMPT_CAP_FRACTION
+  // and collapses it back toward min when the transcript would breach its floor.
   prompt: {
     id: "prompt",
     min: 3,
@@ -208,6 +216,7 @@ export const COLLAPSE_ORDER = [
   // once the wake turn scrolls away, so its single row is the last optional
   // cut, just ahead of prompt growth reclaim.
   "worker_wait",
+  "input_required",
   // prompt growth reclaimed next (handled specially; never below PROMPT_BASE_ROWS)
   "prompt",
 ] as const satisfies readonly ZoneId[];
@@ -227,6 +236,7 @@ export const PAINT_ORDER = [
   "notice",
   "pending",
   "worker_wait",
+  "input_required",
   "prompt",
 ] as const satisfies readonly ZoneId[];