refactor: take each run's route from its program and drop the global debug sink

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589

Author: gewenyu99

src/agent/agent-interface.ts

@@ -6,18 +6,24 @@ import { randomUUID } from 'node:crypto';
 
 import path from 'path';
 import * as os from 'os';
+// eslint-disable-next-line no-restricted-imports -- resolves the SDK's bundled CLI path where ESM has no bare require
 import { createRequire } from 'node:module';
 import type {
   ProgressEmitter,
   SpinnerHandle,
   TokenUsageDelta,
 } from './progress';
-import { debug, logToFile, initLogFile, getLogFilePath } from '@utils/debug';
+import {
+  formatLogLine,
+  logToFile,
+  initLogFile,
+  getLogFilePath,
+} from '@utils/debug';
 import type { WizardRunOptions } from '@utils/types';
 import { analytics } from '@utils/analytics';
 import { isTemplateEnvFileName } from '@utils/env-scan';
 import { runtimeEnv } from '@env';
-import type { AioCapture } from '@agent/aio-capture';
+import type { AioCapture } from './aio-capture';
 import {
   Harness,
   CallType,
@@ -36,14 +42,14 @@ import {
   gatewayAuth,
   isPastRefresh,
   type GatewayAuth,
-} from '@agent/gateway-session';
+} from './gateway-session';
 import { evaluateBashCommand } from './bash-fence';
-import { createWizardToolsServer, WIZARD_TOOL_NAMES } from '@agent/tools';
+import { createWizardToolsServer, WIZARD_TOOL_NAMES } from './tools';
 import {
   createPreToolUseYaraHooks,
   createPostToolUseYaraHooks,
   prewarmYaraScanner,
-} from '@agent/yara-hooks';
+} from './yara-hooks';
 import { createTriageLLMProvider } from './triage-provider';
 import type { LLMProvider } from '@posthog/warlock';
 import { assembleCommandments } from './runner/switchboard/commandments';
@@ -91,11 +97,8 @@ async function getSDKModule(): Promise<any> {
  * This ensures we use the SDK's bundled version rather than the user's installed Claude Code.
  */
 function getClaudeCodeExecutablePath(): string {
-  // Bare `require` is undefined in ESM (tsx dev runs) — fall back to createRequire.
-  const resolver =
-    typeof require !== 'undefined'
-      ? require
-      : createRequire(process.argv[1] ?? `${process.cwd()}/`);
+  // ESM has no bare `require`: resolve from the entry script.
+  const resolver = createRequire(process.argv[1] ?? `${process.cwd()}/`);
   // resolve finds the package's main entry, then we get cli.js from same dir
   const sdkPackagePath = resolver.resolve('@anthropic-ai/claude-agent-sdk');
   return path.join(path.dirname(sdkPackagePath), 'cli.js');
@@ -221,7 +224,7 @@ export type AgentConfig = {
   /** Schema for callers that consume a structured SDK result. */
   outputFormat?: import('@anthropic-ai/claude-agent-sdk').Options['outputFormat'];
   /** Bridge that drives the `wizard_ask` overlay. Omit in non-interactive hosts. */
-  askBridge?: import('@agent/wizard-ask-bridge').WizardAskBridge;
+  askBridge?: import('./wizard-ask-bridge').WizardAskBridge;
   /** Per-run cap on `wizard_ask` invocations. Defaults to 10. */
   askMaxQuestions?: number;
   /** Extra tools added on top of BASE_ALLOWED_TOOLS for this run. */
@@ -239,7 +242,7 @@ export type AgentConfig = {
    * flag routes the run here; threaded into wizard-tools so the orchestrator
    * tools register.
    */
-  orchestrator?: import('@agent/runner/sequence/orchestrator/queue-tools').OrchestratorToolsContext;
+  orchestrator?: import('./runner/sequence/orchestrator/queue-tools').OrchestratorToolsContext;
   /**
    * Optional AIO capture — mirrors each assistant SDK message into the
    * authenticated project as `$ai_generation`. No-op instance when
@@ -417,6 +420,16 @@ export function buildAgentEnv(
 // Re-export for backwards compatibility — canonical source is skill-install.ts
 export { isSkillInstallCommand } from '@shared/skill-install';
 
+/** A debug run's diagnostic line, as info log progress; a run without `debug` emits nothing. */
+function debugLine(
+  emit: ProgressEmitter,
+  options: Pick<WizardRunOptions, 'debug'>,
+  ...args: unknown[]
+): void {
+  if (!options.debug) return;
+  emit({ kind: 'log', level: 'info', message: formatLogLine(...args) });
+}
+
 /**
  * Permission hook that allows only safe commands. Bash commands are gated by
  * the exact per-manager fence in bash-fence.ts (install/build/typecheck/lint
@@ -435,6 +448,8 @@ export function wizardCanUseTool(
     readOnly?: boolean;
     wizardAskPending?: boolean;
     disallowedTools?: readonly string[];
+    /** A debug run's line for each Bash decision. */
+    onDebug?: (line: string) => void;
   } = {},
 ):
   | { behavior: 'allow'; updatedInput: Record<string, unknown> }
@@ -516,12 +531,14 @@ export function wizardCanUseTool(
   const decision = evaluateBashCommand(command);
   if (decision.allowed) {
     logToFile(`Allowing bash command: ${command}`);
-    debug(`Allowing bash command: ${command}`);
+    context.onDebug?.(`Allowing bash command: ${command}`);
     return { behavior: 'allow', updatedInput: input };
   }
 
   logToFile(`Denying bash command (${decision.analyticsReason}): ${command}`);
-  debug(`Denying bash command (${decision.analyticsReason}): ${command}`);
+  context.onDebug?.(
+    `Denying bash command (${decision.analyticsReason}): ${command}`,
+  );
   analytics.wizardCapture('bash denied', {
     reason: decision.analyticsReason,
     command,
@@ -689,14 +706,12 @@ export async function initializeAgent(
       apiKeyPresent: !!config.posthogApiKey,
     });
 
-    if (options.debug) {
-      debug('Agent config:', {
-        workingDirectory: agentRunConfig.workingDirectory,
-        posthogMcpUrl: config.posthogMcpUrl,
-        gatewayUrl,
-        apiKeyPresent: !!config.posthogApiKey,
-      });
-    }
+    debugLine(emit, options, 'Agent config:', {
+      workingDirectory: agentRunConfig.workingDirectory,
+      posthogMcpUrl: config.posthogMcpUrl,
+      gatewayUrl,
+      apiKeyPresent: !!config.posthogApiKey,
+    });
 
     // Pre-warm the warlock scanner (WASM init + rule compile) off the hook path
     // so the first tool-call scan doesn't pay cold-start under a hook timeout.
@@ -714,7 +729,7 @@ export async function initializeAgent(
       message: `Failed to initialize agent: ${(error as Error).message}`,
     });
     logToFile('Agent initialization error:', error);
-    debug('Agent initialization error:', error);
+    debugLine(emit, options, 'Agent initialization error:', error);
     throw error;
   }
 }
@@ -1181,6 +1196,7 @@ export async function runAgent(
                 readOnly: agentConfig.readOnly,
                 wizardAskPending: agentConfig.getPendingQuestion?.() != null,
                 disallowedTools: agentConfig.disallowedTools,
+                onDebug: (line) => debugLine(emit, options, line),
               },
             );
             logToFile('canUseTool result:', result);
@@ -1204,9 +1220,7 @@ export async function runAgent(
           // Capture stderr from CLI subprocess for debugging
           stderr: (data: string) => {
             logToFile('CLI stderr:', data);
-            if (options.debug) {
-              debug('CLI stderr:', data);
-            }
+            debugLine(emit, options, 'CLI stderr:', data);
           },
           // Stop hook: collect remark, then allow stop
           hooks: {
@@ -1672,7 +1686,7 @@ export async function runAgent(
       message: `Error: ${(error as Error).message}`,
     });
     logToFile('Agent run failed:', error);
-    debug('Full error:', error);
+    debugLine(emit, options, 'Full error:', error);
     throw error;
   } finally {
     agentConfig.signal?.removeEventListener('abort', onExternalAbort);
@@ -2042,9 +2056,7 @@ function handleSDKMessage(
   };
   logToFile(`SDK Message: ${message.type}`, JSON.stringify(message, null, 2));
 
-  if (options.debug) {
-    debug(`SDK Message type: ${message.type}`);
-  }
+  debugLine(emit, options, `SDK Message type: ${message.type}`);
 
   switch (message.type) {
     case 'assistant': {
@@ -2227,9 +2239,7 @@ function handleSDKMessage(
 
     default:
       // Log other message types for debugging
-      if (options.debug) {
-        debug(`Unhandled message type: ${message.type}`);
-      }
+      debugLine(emit, options, `Unhandled message type: ${message.type}`);
       break;
   }
 }

src/agent/agent-prompt-loader.ts

@@ -28,7 +28,7 @@ import {
 import { logToFile } from '@utils/debug';
 import { analytics } from '@utils/analytics';
 import { fetchWithRetry } from '@shared/fetch-retry';
-import { WIZARD_TOOL_NAMES } from '@agent/tools/tools';
+import { WIZARD_TOOL_NAMES } from './tools/tools';
 
 /**
  * The basics the client injects around every agent-prompt body. The `/agents/`

src/agent/bash-fence.ts

@@ -13,7 +13,7 @@
  * (`npx <anything>` downloads and runs it), and shell injection. Matching is
  * token-exact per manager — keyword prefixes admitted `npm publish` via `pub`.
  */
-import { LINTING_TOOLS } from '@agent/safe-tools';
+import { LINTING_TOOLS } from './safe-tools';
 
 export type BashFenceDecision =
   | { allowed: true }

src/agent/gateway-session.ts

@@ -6,16 +6,15 @@
  * unattributed money to hide an outage.
  */
 
-import { readFileSync } from 'node:fs';
 import { logToFile } from '@utils/debug';
 import { analytics } from '@utils/analytics';
 import { ErrorCodes, WizardError } from '@shared/errors';
+import type { GatewayCredential } from '@shared/api';
 import type { HostResolution } from '@shared/host-resolution';
 import { oauthLoginKey } from '@shared/oauth-session';
 import { checkLlmGatewayHealth } from '@shared/health-checks/endpoints';
 import { ServiceHealthStatus } from '@shared/health-checks/types';
-import { IS_PRODUCTION_BUILD, runtimeEnv } from '@env';
-import type { CloudRegion } from '@utils/types';
+import { IS_PRODUCTION_BUILD } from '@env';
 
 export interface GatewayAuth {
   /** Base URL for model calls (no `/v1`; transports append their route). */
@@ -73,25 +72,16 @@ export function configureGatewayCredentialsForCI(
   };
 }
 
-// TODO: CI credential loading belongs outside the agent. It leaves with the rest
-// of this module once RunInput carries resolved inference auth, later in the
-// refactor.
-export function configureGatewayFromCIEnvironment(
+/** Use this run's pre-issued gateway token, or mint when it has none; the keyed mint cache stays. */
+export function useRunGatewayCredential(
+  gateway: GatewayCredential | undefined,
   projectId: number,
-  region: CloudRegion,
 ): void {
-  if (IS_PRODUCTION_BUILD)
-    throw new Error('CI gateway auth requires a non-production build');
-  const path = runtimeEnv('WIZARD_CI_GATEWAY_TOKEN_FILE');
-  if (!path) throw new Error('WIZARD_CI_GATEWAY_TOKEN_FILE is required for CI');
-  const token = readFileSync(path, 'utf8');
-  delete process.env.WIZARD_CI_GATEWAY_TOKEN_FILE;
-  configureGatewayCredentialsForCI(
-    token,
-    projectId,
-    runtimeEnv('WIZARD_CI_GATEWAY_URL') ||
-      `https://ai-gateway.${region}.posthog.com`,
-  );
+  if (gateway) {
+    configureGatewayCredentialsForCI(gateway.token, projectId, gateway.url);
+    return;
+  }
+  ciAuth = null;
 }
 
 /**

src/agent/index.ts

@@ -1,15 +1,14 @@
 /**
  * Public entry of the agent. Code outside `src/agent` imports runtime values
- * from here and types from `./types`; deeper imports fail lint and the
- * architecture test. Keep this list to what callers use, and keep it cheap:
+ * from here and types from `./types`; deeper imports fail `pnpm typecheck`.
+ * Keep this list to what callers use, and keep it cheap:
  * the startup chunk imports this module, so anything re-exported here loads
  * before the wizard does any work. Heavy paths stay behind a lazy import.
- *
- * Grouped by fate, per the stack plan (sections 4.1 to 4.5 and 7).
  */
+import type { LLMProvider } from '@posthog/warlock';
 
 /**
- * Stays. The agent's contract: the one way to run it, the marker strings
+ * The agent's contract: the one way to run it, the marker strings
  * program prompts embed, and the tool ids programs put in allowedTools and
  * disallowedTools.
  */
@@ -18,45 +17,35 @@ export { runAgent, RunOutcome } from './runner';
 export { AgentSignals } from './agent-interface';
 export { WIZARD_TOOL_NAMES } from './tools';
 
-/**
- * Leaves when the bindings move to programs. Bindings and program data move to
- * programs: resolveBinding
- * is keyed by PROGRAM_BINDINGS and the agent keeps only "run from an
- * already-resolved binding"; shouldDisableAsk is a flags policy programs
- * decide and pass in; LONGER_ASK_TIMEOUT_MS is a tuning number programs own
- * as askTimeoutMs.
- */
-export {
-  resolveBinding,
-  resolveScanBindings,
-  shouldDisableAsk,
-} from './runner';
-export { captureSwitchboardDecision } from './runner/switchboard/resolve-run';
-export { LONGER_ASK_TIMEOUT_MS } from './wizard-ask-bridge';
+/** The binding a program gets when it declares none. */
+export { DEFAULT_BINDING } from './runner';
+
+/** What a scan's matches decide: end the session or only warn. The Warlock release gate reads it. */
+export { scanVerdict } from './yara-policy';
 
 /**
- * Leaves later in the refactor. buildRunTags builds the trace tags runProgram
- * and agentic detection send. configureGatewayFromCIEnvironment loads the CI
- * gateway token. flushScanReport becomes a progress event rather than a call.
- * downloadSkill leaves once skill install becomes shared.
+ * The scan a freshly installed skill directory goes through: a returned reason
+ * means it is poisoned. Callers of `downloadSkill` inject it, since @shared
+ * cannot import @agent. It loads the scanner on first call so the startup
+ * chunk does not grow.
  */
-export { buildRunTags } from './agent-interface';
-export { configureGatewayFromCIEnvironment } from './gateway-session';
-export { flushScanReport } from './yara-hooks';
-export { downloadSkill } from './tools';
-/** The frameworkContext slot the legacy adapter fills for the e2e harness. */
-export { TASK_OUTCOMES_KEY } from './runner';
+export async function scanInstalledSkill(
+  skillDir: string,
+  llmProvider: LLMProvider | undefined,
+): Promise<string | null> {
+  const yara = await import('./yara-hooks');
+  return yara.scanInstalledSkill(skillDir, llmProvider);
+}
 
 /**
- * Leaves in C2. The TUI receives agent data through program state. Until
- * then the suggested-prompts screen streams through this wrapper, which loads
- * the streaming module on first call so the startup chunk does not grow.
+ * The MCP tutorial's prompt stream: one prompt against the PostHog MCP server,
+ * streamed as chunks. `@tools` re-exports it unchanged, and the TUI reaches it
+ * only through there. It loads the streaming module on first call so the
+ * startup chunk does not grow.
  */
-export async function* runMcpPromptViaSdk(
-  args: Parameters<
-    typeof import('./mcp-prompt-streaming').runMcpPromptViaSdk
-  >[0],
-): AsyncIterable<import('./types').AgentChunk> {
+export async function* streamMcpPrompt(
+  args: Parameters<typeof import('./mcp-prompt-streaming').streamMcpPrompt>[0],
+): AsyncIterable<import('./types').McpPromptChunk> {
   const streaming = await import('./mcp-prompt-streaming');
-  yield* streaming.runMcpPromptViaSdk(args);
+  yield* streaming.streamMcpPrompt(args);
 }