@bastani/atomic 0.5.16 → 0.5.17-0

package/src/sdk/components/orchestrator-panel-store.test.ts

@@ -715,6 +715,94 @@ describe("PanelStore", () => {
     });
   });
 
+  // ── awaitingInput ──────────────────────────────────────────────────────────
+
+  describe("awaitingInput", () => {
+    beforeEach(() => {
+      store.setWorkflowInfo("wf", "claude", [{ name: "worker", parents: [] }], "prompt");
+      store.startSession("worker");
+    });
+
+    test("changes status to awaiting_input when session is running", () => {
+      store.awaitingInput("worker");
+      const s = store.sessions.find((s) => s.name === "worker")!;
+      expect(s.status).toBe("awaiting_input");
+    });
+
+    test("bumps version by exactly 1", () => {
+      const before = store.version;
+      store.awaitingInput("worker");
+      expect(store.version).toBe(before + 1);
+    });
+
+    test("notifies subscribed listeners", () => {
+      const listener = mock(() => {});
+      store.subscribe(listener);
+      store.awaitingInput("worker");
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    test("does not change status when session is not running (pending)", () => {
+      store.setWorkflowInfo("wf2", "claude", [{ name: "idle", parents: [] }], "prompt");
+      const before = store.version;
+      store.awaitingInput("idle");
+      const s = store.sessions.find((s) => s.name === "idle")!;
+      expect(s.status).toBe("pending");
+      expect(store.version).toBe(before);
+    });
+
+    test("does not emit when session not found", () => {
+      const before = store.version;
+      store.awaitingInput("nonexistent");
+      expect(store.version).toBe(before);
+    });
+  });
+
+  // ── resumeSession ──────────────────────────────────────────────────────────
+
+  describe("resumeSession", () => {
+    beforeEach(() => {
+      store.setWorkflowInfo("wf", "claude", [{ name: "worker", parents: [] }], "prompt");
+      store.startSession("worker");
+      store.awaitingInput("worker");
+    });
+
+    test("changes status back to running when session is awaiting_input", () => {
+      store.resumeSession("worker");
+      const s = store.sessions.find((s) => s.name === "worker")!;
+      expect(s.status).toBe("running");
+    });
+
+    test("bumps version by exactly 1", () => {
+      const before = store.version;
+      store.resumeSession("worker");
+      expect(store.version).toBe(before + 1);
+    });
+
+    test("notifies subscribed listeners", () => {
+      const listener = mock(() => {});
+      store.subscribe(listener);
+      store.resumeSession("worker");
+      expect(listener).toHaveBeenCalledTimes(1);
+    });
+
+    test("does not change status when session is not awaiting_input (running)", () => {
+      store.setWorkflowInfo("wf2", "claude", [{ name: "active", parents: [] }], "prompt");
+      store.startSession("active");
+      const before = store.version;
+      store.resumeSession("active");
+      const s = store.sessions.find((s) => s.name === "active")!;
+      expect(s.status).toBe("running");
+      expect(store.version).toBe(before);
+    });
+
+    test("does not emit when session not found", () => {
+      const before = store.version;
+      store.resumeSession("nonexistent");
+      expect(store.version).toBe(before);
+    });
+  });
+
   // ── setViewMode ────────────────────────────────────────────────────────────
 
   describe("setViewMode", () => {

package/src/sdk/components/orchestrator-panel-store.ts

@@ -90,6 +90,22 @@ export class PanelStore {
     this.emit();
   }
 
+  awaitingInput(name: string): void {
+    const session = this.sessions.find((s) => s.name === name);
+    if (session && session.status === "running") {
+      session.status = "awaiting_input";
+      this.emit();
+    }
+  }
+
+  resumeSession(name: string): void {
+    const session = this.sessions.find((s) => s.name === name);
+    if (session && session.status === "awaiting_input") {
+      session.status = "running";
+      this.emit();
+    }
+  }
+
   addSession(session: SessionData): void {
     this.sessions.push(session);
     this.emit();

package/src/sdk/components/orchestrator-panel-types.ts

@@ -1,6 +1,6 @@
 // ─── Orchestrator Panel Types ─────────────────────
 
-export type SessionStatus = "pending" | "running" | "complete" | "error";
+export type SessionStatus = "pending" | "running" | "complete" | "error" | "awaiting_input";
 
 export type ViewMode = "graph" | "attached";
 

package/src/sdk/components/orchestrator-panel.tsx

@@ -111,6 +111,14 @@ export class OrchestratorPanel {
     this.store.failSession(name, message);
   }
 
+  sessionAwaitingInput(name: string): void {
+    this.store.awaitingInput(name);
+  }
+
+  sessionResumed(name: string): void {
+    this.store.resumeSession(name);
+  }
+
   /** Dynamically add a new session node to the graph UI. */
   addSession(name: string, parents: string[]): void {
     this.store.addSession({

package/src/sdk/components/session-graph-panel.tsx

@@ -100,7 +100,7 @@ export function SessionGraphPanel() {
 
   // Pulse animation for running nodes — paused when nothing is running
   const hasRunning = useMemo(
-    () => store.sessions.some((s) => s.status === "running"),
+    () => store.sessions.some((s) => s.status === "running" || s.status === "awaiting_input"),
     [storeVersion],
   );
   const [pulsePhase, setPulsePhase] = useState(0);

package/src/sdk/components/status-helpers.ts

@@ -9,19 +9,20 @@ export function statusColor(status: string, theme: GraphTheme): string {
       complete: theme.success,
       pending: theme.textDim,
       error: theme.error,
+      awaiting_input: theme.info,
     }[status] ?? theme.textDim
   );
 }
 
 export function statusLabel(status: string): string {
   return (
-    { running: "running", complete: "done", pending: "waiting", error: "failed" }[status] ??
+    { running: "running", complete: "done", pending: "waiting", error: "failed", awaiting_input: "input needed" }[status] ??
     status
   );
 }
 
 export function statusIcon(status: string): string {
-  return { running: "●", complete: "✓", pending: "○", error: "✗" }[status] ?? "○";
+  return { running: "●", complete: "✓", pending: "○", error: "✗", awaiting_input: "?" }[status] ?? "○";
 }
 
 // ─── Duration ─────────────────────────────────────

package/src/sdk/providers/claude.ts

@@ -240,6 +240,114 @@ function resolveSessionDir(cwd: string): string {
   return `${home}/.claude/projects/${encodedCwd}`;
 }
 
+// ---------------------------------------------------------------------------
+// HIL detection helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if the most recent assistant message contains an
+ * `AskUserQuestion` tool_use block that has not yet been resolved
+ * by a corresponding `tool_result` in a subsequent user message.
+ *
+ * Pure function — no side effects, safe to call from a watch loop.
+ *
+ * Exported as `_hasUnresolvedHILTool` for unit testing.
+ */
+export function _hasUnresolvedHILTool(messages: SessionMessage[]): boolean {
+  const resolvedIds = new Set<string>();
+
+  for (const msg of messages) {
+    if (msg.type !== "user") continue;
+    const content = (msg.message as { content: unknown })?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (block.type === "tool_result" && block.tool_use_id) {
+        resolvedIds.add(block.tool_use_id);
+      }
+    }
+  }
+
+  for (const msg of [...messages].reverse()) {
+    if (msg.type !== "assistant") continue;
+    const content = (msg.message as { content: unknown })?.content;
+    if (!Array.isArray(content)) continue;
+    for (const block of content) {
+      if (
+        block.type === "tool_use" &&
+        block.name === "AskUserQuestion" &&
+        block.id &&
+        !resolvedIds.has(block.id)
+      ) {
+        return true;
+      }
+    }
+    break;
+  }
+
+  return false;
+}
+
+/**
+ * Core HIL watcher loop — pure logic, dependency-injected for testability.
+ *
+ * Iterates an async iterable of "file change" events (each event triggers a
+ * transcript read via `readMessages`). Calls `onHIL(true)` when
+ * `_hasUnresolvedHILTool` first returns true, `onHIL(false)` when it returns
+ * false after having been true. The `wasHIL` guard prevents redundant
+ * callbacks on repeated events with the same HIL state.  Read errors from
+ * `readMessages` are swallowed so a single corrupt JSONL write doesn't kill
+ * the watcher.
+ *
+ * Exported as `_runHILWatcher` for unit testing (event source and message
+ * reader are injected rather than hard-coded to `fs.watch` / `getSessionMessages`).
+ */
+export async function _runHILWatcher(
+  events: AsyncIterable<unknown>,
+  readMessages: () => Promise<SessionMessage[]>,
+  onHIL: (waiting: boolean) => void,
+): Promise<void> {
+  let wasHIL = false;
+
+  for await (const _event of events) {
+    try {
+      const msgs = await readMessages();
+      const isHIL = _hasUnresolvedHILTool(msgs);
+      if (isHIL !== wasHIL) {
+        onHIL(isHIL);
+        wasHIL = isHIL;
+      }
+    } catch {
+      // Transcript read failed — skip this event, try again on next write
+    }
+  }
+}
+
+/**
+ * Watch the Claude session JSONL transcript for `AskUserQuestion` HIL events.
+ *
+ * Uses `fs/promises` `watch()` (inotify/kqueue in Bun) on the session file.
+ * On each write, re-reads messages via `getSessionMessages()` and calls
+ * `onHIL(true)` when an unresolved `AskUserQuestion` appears or
+ * `onHIL(false)` when it is resolved. Only fires on state transitions to
+ * avoid redundant callbacks.
+ *
+ * The loop exits when the provided `AbortSignal` is aborted (e.g. session
+ * becomes idle). Individual read errors are silently swallowed so a single
+ * corrupt write doesn't kill the watcher.
+ */
+async function watchTranscriptForHIL(
+  sessionId: string,
+  signal: AbortSignal,
+  onHIL: (waiting: boolean) => void,
+): Promise<void> {
+  const jsonlPath = `${resolveSessionDir(process.cwd())}/${sessionId}.jsonl`;
+  await _runHILWatcher(
+    watch(jsonlPath, { signal }),
+    () => getSessionMessages(sessionId, { dir: process.cwd(), includeSystemMessages: true }),
+    onHIL,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -268,10 +376,13 @@ async function waitForIdle(
   transcriptBeforeCount: number,
   beforeContent: string,
   pollIntervalMs: number,
+  onHIL?: (waiting: boolean) => void,
 ): Promise<SessionMessage[]> {
   // Give Claude time to start processing before first poll
   await Bun.sleep(3_000);
 
+  let hilActive = false;
+
   while (true) {
     const currentContent = normalizeTmuxLines(capturePaneScrollback(paneId));
 
@@ -279,13 +390,37 @@ async function waitForIdle(
     if (currentContent !== beforeContent) {
       const visible = capturePaneVisible(paneId);
       if (paneLooksReady(visible) && !paneHasActiveTask(visible)) {
-        // Pane is idle — return transcript messages from this turn
+        // Pane looks idle — but it might be waiting for user input (HIL).
+        // Check the transcript for an unresolved AskUserQuestion before
+        // treating this as a true completion.
         if (claudeSessionId) {
           try {
             const msgs = await getSessionMessages(claudeSessionId, {
               dir: process.cwd(),
               includeSystemMessages: true,
             });
+
+            if (_hasUnresolvedHILTool(msgs)) {
+              // Agent is blocked on user input — signal HIL and keep waiting
+              if (!hilActive && onHIL) {
+                onHIL(true);
+                hilActive = true;
+              }
+              await Bun.sleep(pollIntervalMs);
+              continue;
+            }
+
+            // HIL was active but is now resolved — signal resumption
+            if (hilActive && onHIL) {
+              onHIL(false);
+              hilActive = false;
+              // Agent may still be processing after HIL resolution — keep
+              // polling instead of returning immediately
+              await Bun.sleep(pollIntervalMs);
+              continue;
+            }
+
+            // Truly idle — return transcript messages from this turn
             if (msgs.length > transcriptBeforeCount) {
               return msgs.slice(transcriptBeforeCount);
             }
@@ -294,6 +429,13 @@ async function waitForIdle(
           }
         }
         return [];
+      } else if (hilActive) {
+        // Pane is active again (user responded, agent resumed processing).
+        // Clear HIL state.
+        if (onHIL) {
+          onHIL(false);
+          hilActive = false;
+        }
       }
     }
 
@@ -318,6 +460,12 @@ export interface ClaudeQueryOptions {
   maxSubmitRounds?: number;
   /** Timeout in ms waiting for pane to be ready before sending (default: 30s) */
   readyTimeoutMs?: number;
+  /**
+   * Called when the agent's human-in-the-loop state changes.
+   * `waiting=true`  → AskUserQuestion is pending (agent blocked on user input).
+   * `waiting=false` → AskUserQuestion was resolved (agent resumed processing).
+   */
+  onHIL?: (waiting: boolean) => void;
 }
 
 /**
@@ -386,6 +534,7 @@ export async function claudeQuery(options: ClaudeQueryOptions): Promise<SessionM
     submitPresses = 1,
     maxSubmitRounds = 6,
     readyTimeoutMs = 30_000,
+    onHIL,
   } = options;
 
   const paneState = initializedPanes.get(paneId);
@@ -485,12 +634,17 @@ export async function claudeQuery(options: ClaudeQueryOptions): Promise<SessionM
   // Interactive Claude Code sessions don't write idle/result events to the
   // JSONL. The pane prompt indicator is the only reliable idle signal.
   // Once idle, output is extracted from the transcript when available.
-  return waitForIdle(
+  //
+  // HIL detection is integrated into waitForIdle — when the pane looks idle
+  // but the transcript has an unresolved AskUserQuestion, the function
+  // calls onHIL(true) and keeps waiting instead of returning prematurely.
+  return await waitForIdle(
     paneId,
     claudeSessionId,
     transcriptBeforeCount,
     beforeContent,
     pollIntervalMs,
+    onHIL,
   );
 }
 
@@ -550,15 +704,18 @@ export class ClaudeSessionWrapper {
   readonly paneId: string;
   readonly sessionId: string;
   private readonly defaults: ClaudeQueryDefaults;
+  private readonly onHIL: ((waiting: boolean) => void) | undefined;
 
   constructor(
     paneId: string,
     sessionId: string,
     defaults: ClaudeQueryDefaults = {},
+    onHIL?: (waiting: boolean) => void,
   ) {
     this.paneId = paneId;
     this.sessionId = sessionId;
     this.defaults = defaults;
+    this.onHIL = onHIL;
   }
 
   /** Send a prompt to Claude and wait for the response. */
@@ -571,6 +728,7 @@ export class ClaudeSessionWrapper {
       prompt,
       ...this.defaults,
       ...opts,
+      onHIL: this.onHIL,
     });
   }
 

package/src/sdk/runtime/executor.test.ts

@@ -4,6 +4,8 @@ import {
   hasContent,
   escBash,
   escPwsh,
+  watchCopilotSessionForHIL,
+  type CopilotHILSessionSurface,
 } from "./executor.ts";
 import type { SavedMessage } from "../types.ts";
 import type { SessionEvent } from "@github/copilot-sdk";
@@ -380,3 +382,145 @@ describe("escPwsh", () => {
     expect(escPwsh('$`"\0')).toBe('`$```"');
   });
 });
+
+// ---------------------------------------------------------------------------
+// watchCopilotSessionForHIL — event-driven HIL detection via tool.execution_*
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal mock of the Copilot session surface that records handlers by event
+ * type and lets tests dispatch synthetic events.  Mirrors the structural
+ * `on()` contract of `CopilotHILSessionSurface`.
+ */
+function makeMockCopilotSession(): CopilotHILSessionSurface & {
+  dispatch: (type: string, data: unknown) => void;
+  handlerCount: (type: string) => number;
+} {
+  const handlers = new Map<string, Set<(event: { data?: unknown }) => void>>();
+  return {
+    on(eventType, handler) {
+      let set = handlers.get(eventType);
+      if (!set) {
+        set = new Set();
+        handlers.set(eventType, set);
+      }
+      set.add(handler);
+      return () => {
+        set!.delete(handler);
+      };
+    },
+    dispatch(type, data) {
+      const set = handlers.get(type);
+      if (set) for (const h of set) h({ data });
+    },
+    handlerCount(type) {
+      return handlers.get(type)?.size ?? 0;
+    },
+  };
+}
+
+describe("watchCopilotSessionForHIL", () => {
+  test("fires onHIL(true) on ask_user start and onHIL(false) on matching complete", () => {
+    const session = makeMockCopilotSession();
+    const calls: boolean[] = [];
+    const unsubscribe = watchCopilotSessionForHIL(session, (w) =>
+      calls.push(w),
+    );
+
+    session.dispatch("tool.execution_start", {
+      toolName: "ask_user",
+      toolCallId: "tc-1",
+    });
+    expect(calls).toEqual([true]);
+
+    session.dispatch("tool.execution_complete", { toolCallId: "tc-1" });
+    expect(calls).toEqual([true, false]);
+
+    unsubscribe();
+  });
+
+  test("ignores tool.execution_start for non-ask_user tools", () => {
+    const session = makeMockCopilotSession();
+    const calls: boolean[] = [];
+    const unsubscribe = watchCopilotSessionForHIL(session, (w) =>
+      calls.push(w),
+    );
+
+    session.dispatch("tool.execution_start", {
+      toolName: "edit_file",
+      toolCallId: "tc-2",
+    });
+    session.dispatch("tool.execution_complete", { toolCallId: "tc-2" });
+    expect(calls).toEqual([]);
+
+    unsubscribe();
+  });
+
+  test("ignores complete events for toolCallIds it did not mark active", () => {
+    const session = makeMockCopilotSession();
+    const calls: boolean[] = [];
+    const unsubscribe = watchCopilotSessionForHIL(session, (w) =>
+      calls.push(w),
+    );
+
+    // complete arrives for a tool we never started (e.g. another tool's id)
+    session.dispatch("tool.execution_complete", { toolCallId: "tc-unknown" });
+    expect(calls).toEqual([]);
+
+    unsubscribe();
+  });
+
+  test("only fires onHIL(false) after the last overlapping ask_user completes", () => {
+    const session = makeMockCopilotSession();
+    const calls: boolean[] = [];
+    const unsubscribe = watchCopilotSessionForHIL(session, (w) =>
+      calls.push(w),
+    );
+
+    session.dispatch("tool.execution_start", {
+      toolName: "ask_user",
+      toolCallId: "tc-a",
+    });
+    session.dispatch("tool.execution_start", {
+      toolName: "ask_user",
+      toolCallId: "tc-b",
+    });
+    // onHIL(true) fires exactly once on the first start
+    expect(calls).toEqual([true]);
+
+    session.dispatch("tool.execution_complete", { toolCallId: "tc-a" });
+    // still one active — must not fire onHIL(false) yet
+    expect(calls).toEqual([true]);
+
+    session.dispatch("tool.execution_complete", { toolCallId: "tc-b" });
+    expect(calls).toEqual([true, false]);
+
+    unsubscribe();
+  });
+
+  test("skips ask_user start events that are missing a toolCallId", () => {
+    const session = makeMockCopilotSession();
+    const calls: boolean[] = [];
+    const unsubscribe = watchCopilotSessionForHIL(session, (w) =>
+      calls.push(w),
+    );
+
+    session.dispatch("tool.execution_start", { toolName: "ask_user" });
+    expect(calls).toEqual([]);
+
+    unsubscribe();
+  });
+
+  test("unsubscribe removes both listeners", () => {
+    const session = makeMockCopilotSession();
+    const unsubscribe = watchCopilotSessionForHIL(session, () => {});
+
+    expect(session.handlerCount("tool.execution_start")).toBe(1);
+    expect(session.handlerCount("tool.execution_complete")).toBe(1);
+
+    unsubscribe();
+
+    expect(session.handlerCount("tool.execution_start")).toBe(0);
+    expect(session.handlerCount("tool.execution_complete")).toBe(0);
+  });
+});