Install turn and token caps on the main chat director

DefaultDirector's afterInferenceDone hook is the runtime's designed
extension point for turn/token/time/cost caps, but ChatDirectorImpl
passed it an empty policy, so a runaway loop or a stuck goal run had no
ceiling on inference calls or spend.

Interactive sessions warn once and stay alive (send another message to
keep going); non-interactive runs hard-stop, since there's no operator
to hand a continueable warning to.

Claude-Session: https://claude.ai/code/session_01PiLfSXwRgDgMp5wC3SVAZn

Author: TheGreatAxios

src/agent/director.ts

@@ -1,4 +1,4 @@
-import { DefaultDirector } from "@intx/inference";
+import { DefaultDirector, type DefaultDirectorPolicy } from "@intx/inference";
 import { getLogger } from "@intx/log";
 import type {
   ReactorDirector,
@@ -9,6 +9,7 @@ import type {
   ToolDefinition,
   InferenceOptions,
   ConversationTurn,
+  TokenUsage,
 } from "@intx/types/runtime";
 import {
   type SessionMetadata,
@@ -27,6 +28,31 @@ const RETRY_POLICY = createIntercodeRetryPolicy();
 
 const logger = getLogger(["intercode", "agent", "director"]);
 
+// Stability backstop, not a UX-facing turn limit: without these, a runaway
+// loop or a stuck goal run has no ceiling on inference calls or spend. 500
+// turns and 10M tokens sit well above any normal session so the cap only
+// fires on genuinely runaway behavior.
+const DEFAULT_SESSION_TURN_CAP = 500;
+const DEFAULT_SESSION_TOKEN_BUDGET = 10_000_000;
+
+export type SessionCapsOptions = {
+  /** Overrides DEFAULT_SESSION_TURN_CAP; fed by the resolved profile's maxTurns. */
+  maxTurns?: number;
+  /** Overrides DEFAULT_SESSION_TOKEN_BUDGET. */
+  maxTokens?: number;
+  /**
+   * Interactive sessions (TUI) stay alive and warn once, so the operator can
+   * keep going with a plain message. Non-interactive runs (headless, an
+   * unattended goal) hard-stop instead, since there is no operator to hand
+   * the warning to.
+   */
+  interactive?: boolean;
+};
+
+function sessionTokenTotal(usage: TokenUsage): number {
+  return usage.input + usage.output + usage.cacheRead + usage.cacheWrite + usage.thinking;
+}
+
 function isInternalRecoveryAbort(event: Extract<ReactorInboundEvent, { type: "inference.error" }>): boolean {
   return isInternalRecoveryAbortRaw(event.error.raw);
 }
@@ -325,6 +351,7 @@ class ChatDirectorImpl extends DefaultDirector {
   private tasks: Task[] = [];
   private readonly onTasksChange: ((tasks: Task[]) => void) | undefined;
   private turnCount = 0;
+  private sessionCapWarned = false;
   private currentTaskLabel: string | undefined;
   private lastTaskSummary: string | undefined;
   private startedAt = Date.now();
@@ -341,8 +368,41 @@ class ChatDirectorImpl extends DefaultDirector {
     workflowCoordinator?: WorkflowCoordinator,
     onTasksChange?: (tasks: Task[]) => void,
     requestContinuation?: () => void,
+    sessionCaps?: SessionCapsOptions,
   ) {
-    super(systemPrompt, toolDefinitions, {});
+    const maxTurns = sessionCaps?.maxTurns ?? DEFAULT_SESSION_TURN_CAP;
+    const maxTokens = sessionCaps?.maxTokens ?? DEFAULT_SESSION_TOKEN_BUDGET;
+    const interactive = sessionCaps?.interactive ?? true;
+    // Reads `this.turnCount`/`this.sessionCapWarned`, which do not exist until
+    // super() returns, but the hook itself only runs on a later decide() call
+    // (after construction has fully completed) — defining it here just wires
+    // it into the policy super() needs up front.
+    const policy: DefaultDirectorPolicy = {
+      afterInferenceDone: (state: ReactorState) => {
+        if (this.sessionCapWarned) return { type: "continue" };
+        const tokensUsed = sessionTokenTotal(
+          state.tokenUsage ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, thinking: 0 },
+        );
+        const overTurns = this.turnCount >= maxTurns;
+        const overTokens = tokensUsed >= maxTokens;
+        if (!overTurns && !overTokens) return { type: "continue" };
+        this.sessionCapWarned = true;
+        const reason = overTurns
+          ? `Session turn cap reached (${this.turnCount}/${maxTurns} inference turns).`
+          : `Session token budget reached (${tokensUsed}/${maxTokens} tokens).`;
+        if (interactive) {
+          return {
+            type: "halt",
+            reason: `${reason} Send another message to keep going.`,
+          };
+        }
+        return {
+          type: "abort",
+          reason: `${reason} Stopping this run to avoid runaway cost.`,
+        };
+      },
+    };
+    super(systemPrompt, toolDefinitions, policy);
     this._systemPrompt = systemPrompt;
     this._toolDefinitions = toolDefinitions;
     this.inactivityTimeoutMs = inactivityTimeoutMs;
@@ -678,6 +738,7 @@ export function createChatDirector(
   workflowCoordinator?: WorkflowCoordinator,
   onTasksChange?: (tasks: Task[]) => void,
   requestContinuation?: () => void,
+  sessionCaps?: SessionCapsOptions,
 ): ChatDirector {
   return new ChatDirectorImpl(
     systemPrompt,
@@ -689,6 +750,7 @@ export function createChatDirector(
     workflowCoordinator,
     onTasksChange,
     requestContinuation,
+    sessionCaps,
   );
 }
 

src/director.test.ts

@@ -753,3 +753,72 @@ describe("goal continue-rule", () => {
   });
 });
 
+describe("session turn and token caps", () => {
+  const textTurn = (): ReactorInboundEvent =>
+    ({
+      type: "inference.done",
+      turn: { role: "assistant", model: "test", timestamp: 0, content: [{ type: "text", text: "done" }] },
+      usage: { input: 10, output: 1, cacheRead: 0, cacheWrite: 0, thinking: 0 },
+      source: { model: "test-model" },
+    }) as unknown as ReactorInboundEvent;
+
+  const stateWithTokens = (totalInput: number): ReactorState =>
+    ({
+      tokenUsage: { input: totalInput, output: 0, cacheRead: 0, cacheWrite: 0, thinking: 0 },
+    }) as unknown as ReactorState;
+
+  const isHalt = (a: ReactorAction[]): boolean =>
+    a.some((x) => x.type === "wait") && a.some((x) => x.type === "reply") && !a.some((x) => x.type === "done");
+  const isAbort = (a: ReactorAction[]): boolean =>
+    a.some((x) => x.type === "done") && a.some((x) => x.type === "reply");
+
+  test("interactive session surfaces a continueable warning once the turn cap is reached", async () => {
+    const director = createChatDirector(
+      "base", [], undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+      { maxTurns: 1, interactive: true },
+    );
+    const actions = actionsArray(await director.decide(textTurn(), stateWithTokens(0), mockCapabilities));
+    expect(isHalt(actions)).toBe(true);
+  });
+
+  test("a warned interactive session keeps going instead of warning on every turn", async () => {
+    const director = createChatDirector(
+      "base", [], undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+      { maxTurns: 1, interactive: true },
+    );
+    const first = actionsArray(await director.decide(textTurn(), stateWithTokens(0), mockCapabilities));
+    expect(isHalt(first)).toBe(true);
+
+    const second = actionsArray(await director.decide(textTurn(), stateWithTokens(0), mockCapabilities));
+    expect(isHalt(second)).toBe(false);
+    expect(isAbort(second)).toBe(false);
+  });
+
+  test("headless (non-interactive) run hard-stops when the turn cap is reached", async () => {
+    const director = createChatDirector(
+      "base", [], undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+      { maxTurns: 1, interactive: false },
+    );
+    const actions = actionsArray(await director.decide(textTurn(), stateWithTokens(0), mockCapabilities));
+    expect(isAbort(actions)).toBe(true);
+  });
+
+  test("token budget hard-stops a headless run the same way as the turn cap", async () => {
+    const director = createChatDirector(
+      "base", [], undefined, undefined, undefined, undefined, undefined, undefined, undefined,
+      { maxTokens: 100, interactive: false },
+    );
+    const actions = actionsArray(await director.decide(textTurn(), stateWithTokens(500), mockCapabilities));
+    expect(isAbort(actions)).toBe(true);
+  });
+
+  test("default caps do not fire during ordinary short sessions", async () => {
+    const director = createChatDirector("base", []);
+    for (let i = 0; i < 5; i++) {
+      const actions = actionsArray(await director.decide(textTurn(), stateWithTokens(1000), mockCapabilities));
+      expect(isAbort(actions)).toBe(false);
+      expect(isHalt(actions)).toBe(false);
+    }
+  });
+});
+