Merge remote-tracking branch 'origin/main' into cl-7919-chat-director-decide-the-shape-for-workflowcoordinator-and

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -177,7 +177,7 @@ When a cycle's input tokens cross a threshold, the director compacts the inferen
 - **Idle (end-of-turn)** — An interactive turn can end with a reply and then sit idle with no tool batch to intercept; the governor requests a continuation at that pause and compacts when it arrives. An operator message that races the continuation still compacts first, then re-enters inference to answer it.
 - **Overflow recovery** — A `context_overflow` inference error would otherwise become a terminal error reply; the governor compacts and retries instead, bounded so a history the compactor cannot shrink does not loop forever. Overflow ignores hysteresis for the compact itself.
 
-The compaction control flow is shaped by a reactor invariant: a `compact` action runs in its own cycle (it cannot be paired with `infer`), and **the reactor delivers no event after a compact cycle**. A director that simply emitted `compact` in place of the follow-up `infer` would leave the loop idle forever — the cause of an earlier stall. Instead the governor, after emitting `compact`, self-delivers a content-less inbound message (a host-supplied `requestContinuation` callback). That message adds no turn (`createInboundTurn` returns `null` for empty content) but re-enters the loop, where the director issues the follow-up `infer` against the freshly truncated history.
+The compaction control flow is shaped by a reactor invariant: a `compact` action runs in its own cycle (it cannot be paired with `infer`), and **the reactor delivers no event after a compact cycle**. A director that simply emitted `compact` in place of the follow-up `infer` would leave the loop idle forever — the cause of an earlier stall. Instead the governor pairs `compact` with an emit action (`custom.compaction.continue`), and the host answers that emission by delivering a content-less inbound message (`buildCompactionContinuationMessage()`) through the serial operation queue, generation-guarded like every other deliver. That message adds no turn (`createInboundTurn` returns `null` for empty content) but re-enters the loop, where the director issues the follow-up `infer` against the freshly truncated history. Each emission is answered at most once (a replayed duplicate of an already-answered emission is ignored), and an unsolicited continuation with neither resume flag set answers `wait` rather than burning a billable inference. The legacy `requestContinuation` closure survives only on the sub-agent path, which delivers directly with no host emit hop; idle arming keeps the two channels exclusive (closure fires and the arming flag stays false, or no closure and the flag reports the arming) so a caller honoring both cannot double-deliver.
 
 Compaction replaces older turns with a structured, workflow-aware summary rather than a stats blob: sections for **What Happened / What We're Doing / Relevant Links / Action Items / Next Steps**, with the active workflow and step woven in so compacting mid-`/build` or mid-`/plan` preserves the contract. The summary is produced by a one-shot model call; on any failure it falls back to a deterministic summary so a compaction cycle never breaks the session.
 

scripts/check-dead-exports.test.ts

@@ -28,20 +28,12 @@ import {
 const repoRoot = join(import.meta.dir, "..");
 
 // A probe dead export in one of the scoped files must fail the guard: the
-// exact-name exemptions cover only the five deferred-cleanup flags, never
-// the whole module.
+// exact-name exemptions cover only the remaining deferred-cleanup flags
+// (the usage-formatter flags were removed with their exports by the CL-6815
+// trim), never the whole module.
 describe("scoped exemptions", () => {
   test("the real allowlist covers the named flags but not a sibling probe", () => {
     const rules = loadAllowlist();
-    expect(
-      isAllowlisted(rules, "src/auth/codex/usage.ts", "fetchCodexUsage"),
-    ).toBe(true);
-    expect(
-      isAllowlisted(rules, "src/auth/codex/usage.ts", "fetchCodexModels"),
-    ).toBe(true);
-    expect(isAllowlisted(rules, "src/auth/xai/usage.ts", "fetchXaiUsage")).toBe(
-      true,
-    );
     expect(
       isAllowlisted(
         rules,

scripts/dead-export-allowlist.txt

@@ -26,16 +26,21 @@ vendor/
 # flags so a new dead export in these files fails the guard instead of
 # hiding under a whole-file exemption. Remove each entry with the export it
 # names when the owning cleanup lands.
-src/auth/codex/usage.ts: fetchCodexUsage
-src/auth/codex/usage.ts: fetchCodexModels
-src/auth/xai/usage.ts: fetchXaiUsage
 src/auth/codex/constants.ts: CODEX_REFRESH_SKEW_MS
 src/auth/codex/constants.ts: CODEX_HEADLESS_REFRESH_INTERVAL_MS
 
 # Plugin fixture entry point. Loaded by file path from the fixture's plugin
 # manifest by the plugin-registration tests, so it has no static importers.
 tests/fixtures/plugins/implement-feature/src/index.ts
 
+# Eval completion-harness task fixtures (CL-7932 lane). Loaded by file path
+# from each task's script.json by the harness runner, so they have no static
+# importers.
+evals/completion/tasks/decline-refactor/fixture/notes.ts: addNote
+evals/completion/tasks/stall-read/fixture/data.ts: data
+evals/completion/tasks/sum-fix/fixture/sum.ts: total
+evals/completion/tasks/version-endpoint/fixture/service.ts: handleRequest
+
 # ts-prune parser false positives: bare tokens on `as const satisfies ...`
 # lines inside live exports. None of these is an export declaration.
 src/provider/reasoning-effort.ts: satisfies

src/agent/chat-event-subscribers.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import {
+  CHAT_TASKS_CHANGED_EVENT,
+  CHAT_TOOLS_ACTIVATE_EVENT,
+} from "./director.js";
+import { handleChatDirectorEvent } from "./chat-event-subscribers.js";
+import type { Task } from "./tasks.js";
+
+function makeLog() {
+  const calls: { message: string; fields?: Record<string, unknown> }[] = [];
+  return {
+    calls,
+    log: (message: string, fields?: Record<string, unknown>): void => {
+      calls.push(fields !== undefined ? { message, fields } : { message });
+    },
+  };
+}
+
+describe("handleChatDirectorEvent", () => {
+  test("dispatches a valid tasks-changed payload without logging", () => {
+    const seen: Task[][] = [];
+    const log = makeLog();
+    const handled = handleChatDirectorEvent(
+      {
+        type: CHAT_TASKS_CHANGED_EVENT,
+        data: { tasks: [{ id: "t1", title: "work", status: "doing" }] },
+      },
+      {
+        onTasksChanged: (tasks) => seen.push(tasks),
+        onToolsActivate: () => {
+          throw new Error("unexpected tools-activate dispatch");
+        },
+      },
+      log.log,
+    );
+    expect(handled).toBe(true);
+    expect(seen).toEqual([[{ id: "t1", title: "work", status: "doing" }]]);
+    expect(log.calls).toEqual([]);
+  });
+
+  test("dispatches a valid tools-activate payload without logging", () => {
+    const seen: string[][] = [];
+    const log = makeLog();
+    const handled = handleChatDirectorEvent(
+      { type: CHAT_TOOLS_ACTIVATE_EVENT, data: { names: ["lsp"] } },
+      {
+        onTasksChanged: () => {
+          throw new Error("unexpected tasks-changed dispatch");
+        },
+        onToolsActivate: (names) => seen.push([...names]),
+      },
+      log.log,
+    );
+    expect(handled).toBe(true);
+    expect(seen).toEqual([["lsp"]]);
+    expect(log.calls).toEqual([]);
+  });
+
+  test("drops an invalid tasks payload with a debug log naming the failure", () => {
+    let dispatched = false;
+    const log = makeLog();
+    const handled = handleChatDirectorEvent(
+      { type: CHAT_TASKS_CHANGED_EVENT, data: { tasks: "not-a-list" } },
+      {
+        onTasksChanged: () => {
+          dispatched = true;
+        },
+        onToolsActivate: () => {
+          dispatched = true;
+        },
+      },
+      log.log,
+    );
+    expect(handled).toBe(true);
+    expect(dispatched).toBe(false);
+    expect(log.calls).toHaveLength(1);
+    expect(log.calls[0]?.message).toMatch(/tasks-changed/);
+    expect(typeof log.calls[0]?.fields?.["error"]).toBe("string");
+  });
+
+  test("drops an invalid tools payload with a debug log naming the failure", () => {
+    let dispatched = false;
+    const log = makeLog();
+    const handled = handleChatDirectorEvent(
+      { type: CHAT_TOOLS_ACTIVATE_EVENT, data: { names: [42] } },
+      {
+        onTasksChanged: () => {
+          dispatched = true;
+        },
+        onToolsActivate: () => {
+          dispatched = true;
+        },
+      },
+      log.log,
+    );
+    expect(handled).toBe(true);
+    expect(dispatched).toBe(false);
+    expect(log.calls).toHaveLength(1);
+    expect(log.calls[0]?.message).toMatch(/tools-activate/);
+    expect(typeof log.calls[0]?.fields?.["error"]).toBe("string");
+  });
+
+  test("ignores unrelated events without logging or dispatching", () => {
+    let dispatched = false;
+    const log = makeLog();
+    const handled = handleChatDirectorEvent(
+      { type: "inference.done", data: {} },
+      {
+        onTasksChanged: () => {
+          dispatched = true;
+        },
+        onToolsActivate: () => {
+          dispatched = true;
+        },
+      },
+      log.log,
+    );
+    expect(handled).toBe(false);
+    expect(dispatched).toBe(false);
+    expect(log.calls).toEqual([]);
+  });
+});

src/agent/chat-event-subscribers.ts

@@ -0,0 +1,62 @@
+/**
+ * Shared subscriber for the chat-director reactor events. The TUI and exec
+ * stream sinks both listen for the task-list and tool-activation events the
+ * chat director emits in place of the former host closures; the parse,
+ * validation, and invalid-payload handling live here so the two sinks cannot
+ * drift apart.
+ */
+
+import { type } from "arktype";
+import {
+  CHAT_TASKS_CHANGED_EVENT,
+  CHAT_TOOLS_ACTIVATE_EVENT,
+  ChatTasksChangedDataSchema,
+  ChatToolsActivateDataSchema,
+} from "./director.js";
+import type { Task } from "./tasks.js";
+
+export interface ChatDirectorEventHandlers {
+  onTasksChanged: (tasks: Task[]) => void;
+  onToolsActivate: (names: string[]) => void;
+}
+
+export type ChatDirectorEventDebugLog = (
+  message: string,
+  fields?: Record<string, unknown>,
+) => void;
+
+/**
+ * Dispatch one stream event to the chat-director handlers. Returns true when
+ * the event is a chat-director event (valid or not) so sinks can fall through
+ * to their own handling otherwise. Invalid payloads are dropped after a
+ * debug-level log naming the failure — never silently.
+ */
+export function handleChatDirectorEvent(
+  event: { type: string; data: unknown },
+  handlers: ChatDirectorEventHandlers,
+  logDebug: ChatDirectorEventDebugLog,
+): boolean {
+  if (event.type === CHAT_TASKS_CHANGED_EVENT) {
+    const parsed = ChatTasksChangedDataSchema(event.data);
+    if (parsed instanceof type.errors) {
+      logDebug("chat tasks-changed event dropped invalid payload: {error}", {
+        error: parsed.summary,
+      });
+      return true;
+    }
+    handlers.onTasksChanged(parsed.tasks);
+    return true;
+  }
+  if (event.type === CHAT_TOOLS_ACTIVATE_EVENT) {
+    const parsed = ChatToolsActivateDataSchema(event.data);
+    if (parsed instanceof type.errors) {
+      logDebug("chat tools-activate event dropped invalid payload: {error}", {
+        error: parsed.summary,
+      });
+      return true;
+    }
+    handlers.onToolsActivate(parsed.names);
+    return true;
+  }
+  return false;
+}

src/agent/compaction.test.ts

@@ -6,7 +6,10 @@ import type {
   ReactorInboundEvent,
   TokenUsage,
 } from "@intx/types/runtime";
-import { createCompactionGovernor } from "./compaction.js";
+import {
+  COMPACTION_CONTINUATION_EVENT,
+  createCompactionGovernor,
+} from "./compaction.js";
 import {
   compactionResumeDeltaFor,
   compactionThresholdFor,
@@ -28,6 +31,11 @@ const capabilities = {
     compactor,
     reason,
   }),
+  emit: (eventType: string, data: unknown) => ({
+    type: "emit",
+    eventType,
+    data,
+  }),
 } as unknown as ReactorCapabilities;
 
 // Distinct, non-zero cacheRead/cacheWrite so a test asserting on the total
@@ -182,15 +190,34 @@ describe("compaction governor", () => {
     ).toBeNull();
   });
 
-  test("stays inert without a continuation channel", () => {
+  test("expresses continuation as an emit action without a closure", () => {
     const governor = createCompactionGovernor(undefined);
     governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+    const actions = governor.interceptActions(
+      toolDone(),
+      inferAction,
+      capabilities,
+    );
+    expect(actions?.some((a) => a.type === "compact")).toBe(true);
+    expect(actions?.some((a) => a.type === "infer")).toBe(false);
     expect(
-      governor.interceptActions(toolDone(), inferAction, capabilities),
-    ).toBeNull();
-    expect(
-      governor.interceptOverflow(overflowError(), capabilities),
-    ).toBeNull();
+      actions?.some(
+        (a) =>
+          a.type === "emit" &&
+          "eventType" in a &&
+          a.eventType === COMPACTION_CONTINUATION_EVENT,
+      ),
+    ).toBe(true);
+    expect(
+      governor
+        .interceptOverflow(overflowError(), capabilities)
+        ?.some(
+          (a) =>
+            a.type === "emit" &&
+            "eventType" in a &&
+            a.eventType === COMPACTION_CONTINUATION_EVENT,
+        ),
+    ).toBe(true);
   });
 
   test("recovers from context overflow a bounded number of times", () => {
@@ -241,6 +268,61 @@ describe("compaction governor", () => {
     ).toBeNull();
   });
 
+  test("an idle over-threshold turn arms an emit continuation without a closure", () => {
+    const governor = createCompactionGovernor(undefined);
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+
+    const terminal: ReactorAction[] = [{ type: "reply", content: "done" }];
+    expect(governor.noteIdleTurn(inferenceDone(overThreshold), terminal)).toBe(
+      true,
+    );
+    // Only arms once even if the idle turn is observed again.
+    expect(governor.noteIdleTurn(inferenceDone(overThreshold), terminal)).toBe(
+      false,
+    );
+
+    const actions = governor.interceptIdleContinuation(
+      emptyMessage(),
+      capabilities,
+    );
+    expect(
+      actions?.some(
+        (a) =>
+          a.type === "compact" &&
+          "reason" in a &&
+          a.reason === "context-threshold",
+      ),
+    ).toBe(true);
+    expect(
+      actions?.some(
+        (a) =>
+          a.type === "emit" &&
+          "eventType" in a &&
+          a.eventType === COMPACTION_CONTINUATION_EVENT,
+      ),
+    ).toBe(true);
+  });
+
+  test("idle arming with a closure fires once and never returns true", () => {
+    // Single-delivery contract: a caller that both installs the legacy closure
+    // and honors the boolean (appending an emit action on true) must still
+    // deliver exactly once. The closure fires; the return stays false.
+    let continuations = 0;
+    const governor = createCompactionGovernor(() => continuations++);
+    governor.noteInferenceDone(inferenceDone(overThreshold), tenTurns);
+
+    const terminal: ReactorAction[] = [{ type: "reply", content: "done" }];
+    expect(governor.noteIdleTurn(inferenceDone(overThreshold), terminal)).toBe(
+      false,
+    );
+    expect(continuations).toBe(1);
+    // A repeated idle turn neither refires nor arms.
+    expect(governor.noteIdleTurn(inferenceDone(overThreshold), terminal)).toBe(
+      false,
+    );
+    expect(continuations).toBe(1);
+  });
+
   // Idle compact with an empty continuation previously left postCompactInfer
   // unset, so resumeAfterCompact never fired and notePostCompact never ran —
   // the Ctx meter stayed on pre-compact lastTurnUsage until the next user turn.