Add launcher, parse, tool, workflow, and engine debug logging (#290)

Copilot · web-flow · commit 733898fa15c8 · 2026-07-30T08:42:08.000+02:00
diff --git a/skills/rig/engines/anthropic.ts b/skills/rig/engines/anthropic.ts
@@ -1,8 +1,15 @@
 import Anthropic from "@anthropic-ai/sdk";
 import type { ClientOptions } from "@anthropic-ai/sdk";
 import { betaTool } from "@anthropic-ai/sdk/helpers/beta/json-schema";
+import { debug } from "../rig.ts";
 import type { AgentFactory, Tool } from "../rig.ts";
 
+const debugCreate = debug("engine:anthropic:create");
+const debugAsk = debug("engine:anthropic:ask");
+const debugResponse = debug("engine:anthropic:response");
+const debugTool = debug("engine:anthropic:tool");
+const debugClose = debug("engine:anthropic:close");
+
 export type AnthropicEngineOptions = ClientOptions & {
   maxTokens?: number;
   maxIterations?: number;
@@ -11,12 +18,14 @@ export type AnthropicEngineOptions = ClientOptions & {
 export function anthropicEngine(options: AnthropicEngineOptions = {}): AgentFactory {
   const { maxTokens = 8192, maxIterations, ...clientOptions } = options;
   return (agentOptions) => {
+    debugCreate({ model: agentOptions.model, tools: agentOptions.tools?.map((tool) => tool.name) ?? [] });
     const client = new Anthropic(clientOptions);
     let messages: any[] = [];
     const tools = agentOptions.tools?.map(toAnthropicTool) ?? [];
 
     return {
       async ask(prompt, askOptions = {}) {
+        debugAsk({ model: agentOptions.model, prompt });
         const requestMessages = [...messages, { role: "user" as const, content: prompt }];
         const runner = client.beta.messages.toolRunner({
           model: agentOptions.model,
@@ -28,9 +37,13 @@ export function anthropicEngine(options: AnthropicEngineOptions = {}): AgentFact
         }, askOptions.signal ? { signal: askOptions.signal } : undefined);
         const response = await runner.runUntilDone();
         messages = [...runner.params.messages];
-        return contentText(response.content);
+        const text = contentText(response.content);
+        debugResponse({ model: agentOptions.model, response: text });
+        return text;
+      },
+      async close() {
+        debugClose({ model: agentOptions.model });
       },
-      async close() {},
     };
   };
 }
@@ -44,6 +57,7 @@ function toAnthropicTool(tool: Tool<any>) {
       if (!tool.handler) {
         throw new Error(`${tool.name} tool has no handler`);
       }
+      debugTool({ tool: tool.name, args });
       return toolResultText(await tool.handler(args));
     },
   });
diff --git a/skills/rig/engines/codex.ts b/skills/rig/engines/codex.ts
@@ -1,7 +1,13 @@
 import { Codex } from "@openai/codex-sdk";
 import type { CodexOptions, ThreadOptions } from "@openai/codex-sdk";
+import { debug } from "../rig.ts";
 import type { AgentFactory } from "../rig.ts";
 
+const debugCreate = debug("engine:codex:create");
+const debugAsk = debug("engine:codex:ask");
+const debugResponse = debug("engine:codex:response");
+const debugClose = debug("engine:codex:close");
+
 export type CodexEngineOptions = CodexOptions & {
   thread?: Omit<ThreadOptions, "model">;
 };
@@ -12,6 +18,7 @@ export function codexEngine(options: CodexEngineOptions = {}): AgentFactory {
     if (agentOptions.tools && agentOptions.tools.length > 0) {
       throw new Error("codexEngine does not support Rig tools");
     }
+    debugCreate({ model: agentOptions.model });
     const systemMessage = stringSystemMessage(agentOptions.systemMessage);
     const codex = new Codex({
       ...clientOptions,
@@ -31,6 +38,7 @@ export function codexEngine(options: CodexEngineOptions = {}): AgentFactory {
 
     return {
       async ask(prompt, askOptions = {}) {
+        debugAsk({ model: agentOptions.model, prompt, structured: askOptions.outputSchema !== undefined });
         throwIfAborted(closeController.signal);
         const signal = askOptions.signal
           ? AbortSignal.any([askOptions.signal, closeController.signal])
@@ -42,15 +50,15 @@ export function codexEngine(options: CodexEngineOptions = {}): AgentFactory {
         activeTurns.add(activeTurn);
         try {
           const turn = await activeTurn;
-          if (typeof turn.finalResponse === "string") {
-            return turn.finalResponse;
-          }
-          return JSON.stringify(turn.finalResponse);
+          const text = typeof turn.finalResponse === "string" ? turn.finalResponse : JSON.stringify(turn.finalResponse);
+          debugResponse({ model: agentOptions.model, response: text });
+          return text;
         } finally {
           activeTurns.delete(activeTurn);
         }
       },
       async close() {
+        debugClose({ model: agentOptions.model });
         closeController.abort(new DOMException("Agent closed", "AbortError"));
         await Promise.allSettled(activeTurns);
       },
diff --git a/skills/rig/engines/gemini.ts b/skills/rig/engines/gemini.ts
@@ -1,8 +1,14 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import type { ChildProcessWithoutNullStreams } from "node:child_process";
+import { debug } from "../rig.ts";
 import type { AgentFactory } from "../rig.ts";
 
+const debugCreate = debug("engine:gemini:create");
+const debugAsk = debug("engine:gemini:ask");
+const debugResponse = debug("engine:gemini:response");
+const debugClose = debug("engine:gemini:close");
+
 export type GeminiEngineOptions = {
   command?: string;
   cwd?: string;
@@ -32,6 +38,7 @@ export function geminiEngine(options: GeminiEngineOptions = {}): AgentFactory {
     if (agentOptions.tools && agentOptions.tools.length > 0) {
       throw new Error("geminiEngine does not support Rig tools");
     }
+    debugCreate({ model: agentOptions.model, command, ...(cwd !== undefined && { cwd }) });
     const systemMessage = stringSystemMessage(agentOptions.systemMessage);
     const closeController = new AbortController();
     const activeTurns = new Set<Promise<unknown>>();
@@ -40,6 +47,7 @@ export function geminiEngine(options: GeminiEngineOptions = {}): AgentFactory {
 
     return {
       async ask(prompt, askOptions = {}) {
+        debugAsk({ model: agentOptions.model, prompt, resumed: sessionId !== undefined });
         throwIfAborted(closeController.signal);
         if (activeProcess) {
           throw new Error("geminiEngine does not support concurrent turns");
@@ -78,13 +86,16 @@ export function geminiEngine(options: GeminiEngineOptions = {}): AgentFactory {
           if (output.error) {
             throw new Error(output.error.message ?? "Gemini CLI request failed");
           }
-          return output.response ?? "";
+          const text = output.response ?? "";
+          debugResponse({ model: agentOptions.model, session: sessionId, response: text });
+          return text;
         } finally {
           activeProcess = undefined;
           activeTurns.delete(activeTurn);
         }
       },
       async close() {
+        debugClose({ model: agentOptions.model, session: sessionId });
         closeController.abort(new DOMException("Agent closed", "AbortError"));
         await Promise.allSettled(activeTurns);
       },
diff --git a/skills/rig/engines/pi.ts b/skills/rig/engines/pi.ts
@@ -3,8 +3,15 @@ import type { AgentTool as PiAgentTool } from "@earendil-works/pi-agent-core";
 import { Type } from "@earendil-works/pi-ai";
 import type { Models } from "@earendil-works/pi-ai";
 import { builtinModels } from "@earendil-works/pi-ai/providers/all";
+import { debug } from "../rig.ts";
 import type { AgentFactory, Tool } from "../rig.ts";
 
+const debugCreate = debug("engine:pi:create");
+const debugAsk = debug("engine:pi:ask");
+const debugResponse = debug("engine:pi:response");
+const debugTool = debug("engine:pi:tool");
+const debugClose = debug("engine:pi:close");
+
 export type PiEngineOptions = {
   provider: string;
   models?: Models;
@@ -17,6 +24,7 @@ export function piEngine(options: PiEngineOptions): AgentFactory {
     if (!model) {
       throw new Error(`Unknown pi-agent model: ${options.provider}/${agentOptions.model}`);
     }
+    debugCreate({ provider: options.provider, model: agentOptions.model, tools: agentOptions.tools?.map((tool) => tool.name) ?? [] });
     const piAgent = new PiAgent({
       streamFn: models.streamSimple.bind(models),
       initialState: {
@@ -28,6 +36,7 @@ export function piEngine(options: PiEngineOptions): AgentFactory {
 
     return {
       async ask(prompt, askOptions = {}) {
+        debugAsk({ model: agentOptions.model, prompt });
         throwIfAborted(askOptions.signal);
         const abort = () => piAgent.abort();
         askOptions.signal?.addEventListener("abort", abort, { once: true });
@@ -37,12 +46,15 @@ export function piEngine(options: PiEngineOptions): AgentFactory {
           if (piAgent.state.errorMessage) {
             throw new Error(piAgent.state.errorMessage);
           }
-          return piResponseText(piAgent.state.messages);
+          const text = piResponseText(piAgent.state.messages);
+          debugResponse({ model: agentOptions.model, response: text });
+          return text;
         } finally {
           askOptions.signal?.removeEventListener("abort", abort);
         }
       },
       async close() {
+        debugClose({ model: agentOptions.model });
         piAgent.abort();
         await piAgent.waitForIdle();
       },
@@ -70,6 +82,7 @@ function toPiTool(tool: Tool<any>): PiAgentTool {
       if (!tool.handler) {
         throw new Error(`${tool.name} tool has no handler`);
       }
+      debugTool({ tool: tool.name, args: params });
       const result = await tool.handler(params);
       return {
         content: [{ type: "text", text: toolResultText(result) }],
diff --git a/skills/rig/references/runtime.md b/skills/rig/references/runtime.md
@@ -131,6 +131,22 @@ RIG_DEBUG="engine,agent:turn,-engine:copilot:event" node skills/rig/rig.ts src/p
 
 Debug records are `rig.*` JSONL events on stderr and never replace the final stdout result.
 
+| Category | Emitted when |
+|---|---|
+| `launcher:start` | CLI starts, with script name and argv |
+| `launcher:program` | Root program is resolved (file, stdin, or import mode) |
+| `launcher:typecheck` | Typecheck starts, passes, or fails |
+| `launcher:result` | Root result is rendered to stdout |
+| `agent:invoke` / `agent:turn` / `agent:response` | Agent call starts, each turn prompt, each raw response |
+| `agent:parse` | Response parse/validation outcome (`parse`, `validation`, `ok`) |
+| `agent:tools` | Tools registered on an agent spec |
+| `agent:complete` / `agent:retry` / `agent:error` / `agent:failure` / `agent:close` | Agent lifecycle outcomes |
+| `workflow:event` | Every workflow event (`run_start`, `phase_start`, `agent_start`, `log`, …) |
+| `engine:select` | Default engine selection |
+| `engine:copilot:*` | Copilot session create, event, ask, response, close |
+| `engine:anthropic:*` / `engine:pi:*` | Engine create, ask, response, tool call, close |
+| `engine:codex:*` / `engine:gemini:*` | Engine create, ask, response, close |
+
 ## Operational conventions
 
 - Assume Node.js 24.
diff --git a/skills/rig/rig.ts b/skills/rig/rig.ts
@@ -694,6 +694,13 @@ const debugAgentComplete = debug("agent:complete");
 const debugAgentRetry = debug("agent:retry");
 const debugAgentFailure = debug("agent:failure");
 const debugAgentClose = debug("agent:close");
+const debugAgentTools = debug("agent:tools");
+const debugAgentParse = debug("agent:parse");
+const debugLauncherStart = debug("launcher:start");
+const debugLauncherProgram = debug("launcher:program");
+const debugLauncherTypecheck = debug("launcher:typecheck");
+const debugLauncherResult = debug("launcher:result");
+const debugWorkflowEvent = debug("workflow:event");
 
 export type AgentAddonContext = {
   spec: NormalizedAgentSpec<any, any>;
@@ -1453,6 +1460,7 @@ export async function launchRigProgram(programPath: string, options: LaunchOptio
   const cwd = options.cwd ?? process.cwd();
   const resolvedPath = isAbsolute(programPath) ? programPath : resolve(cwd, programPath);
 
+  debugLauncherProgram({ mode: "import", program: resolvedPath, cwd, server: options.startServer === true });
   configureAgent(defaultAgentFactory({ cwd, ...(options.startServer ? { startServer: true } : {}) }));
   await import(pathToFileURL(resolvedPath).href);
 }
@@ -1626,6 +1634,7 @@ async function hasEsmPackageContext(filePath: string): Promise<boolean> {
 }
 
 async function typecheckProgram(programPath: string, cwd: string, displayPath = programPath): Promise<void> {
+  debugLauncherTypecheck({ phase: "start", program: displayPath, cwd });
   const execFileAsync = promisify(execFile);
   const skillTsconfigPath = resolve(dirname(fileURLToPath(import.meta.url)), "tsconfig.json");
   const candidateTsconfigPaths = [resolve(cwd, "tsconfig.json"), skillTsconfigPath];
@@ -1672,6 +1681,7 @@ async function typecheckProgram(programPath: string, cwd: string, displayPath =
         env: { ...process.env, npm_config_ignore_scripts: "true" },
       },
     );
+    debugLauncherTypecheck({ phase: "passed", program: displayPath });
   } catch (error) {
     const execError = error as NodeJS.ErrnoException & { stdout?: string; stderr?: string };
     if (execError.code === "ENOENT") {
@@ -1691,6 +1701,7 @@ async function typecheckProgram(programPath: string, cwd: string, displayPath =
       .replaceAll(relativeShadowPath, displayPath);
     const detail = diagnostics ? `\n${diagnostics}` : "";
     const hasCjsEsmMismatch = diagnostics.includes("TS1295") || diagnostics.includes("TS1479");
+    debugLauncherTypecheck({ phase: "failed", program: displayPath, diagnostics });
     const hint = hasCjsEsmMismatch
       ? "\nHint: add {\"type\":\"module\"} to a package.json in the same directory as your rig program."
       : "";
@@ -1725,9 +1736,12 @@ async function runRootAgentFromStdin(
   if (!rootAgent) {
     throw new Error("Expected program to export a root value (agent, workflow, string, or prompt builder) as default export.");
   }
+  debugLauncherProgram({ mode: "file", program: resolvedPath, root: rootAgent.agentName, promptLength: prompt.length });
 
   const result = await rootAgent(coerceStdinInput(rootAgent, prompt));
-  io.stdout.write(renderStdout(result));
+  const rendered = renderStdout(result);
+  debugLauncherResult({ mode: "file", root: rootAgent.agentName, bytes: Buffer.byteLength(rendered) });
+  io.stdout.write(rendered);
 }
 
 async function runProgramCodeFromStdin(
@@ -1759,12 +1773,15 @@ async function runProgramCodeFromStdin(
     if (!rootAgent) {
       throw new Error("Expected program to export a root value (agent, workflow, string, or prompt builder) as default export.");
     }
+    debugLauncherProgram({ mode: "stdin", program: tempProgramPath, root: rootAgent.agentName, codeLength: programCode.length });
     const input = noInputInvocation(rootAgent);
     if (input === undefined) {
       throw new Error("Expected stdin program root agent to have no input (omit input or use input: s.object({})).");
     }
     const result = await rootAgent(input);
-    io.stdout.write(renderStdout(result));
+    const rendered = renderStdout(result);
+    debugLauncherResult({ mode: "stdin", root: rootAgent.agentName, bytes: Buffer.byteLength(rendered) });
+    io.stdout.write(rendered);
   } finally {
     await rm(tempDir, { recursive: true, force: true });
   }
@@ -1825,6 +1842,7 @@ export async function runLauncherCli(
   io: LauncherIo = process,
 ): Promise<void> {
   const scriptName = process.argv[1] ? basename(process.argv[1]) : "launcher";
+  debugLauncherStart({ script: scriptName, argv });
   if (argv.some(isLauncherHelpArg)) {
     io.stdout.write(`${renderLauncherUsage(scriptName)}\n`);
     return;
@@ -2230,6 +2248,7 @@ export async function runWorkflow<Input, Output>(
   timer?.unref();
 
   const emit = (event: WorkflowEvent): void => {
+    debugWorkflowEvent(() => ({ workflow: definition.meta.name, event }));
     try {
       options.onEvent?.(event);
     } catch {
@@ -2374,6 +2393,7 @@ function normalizeToolConfig<T extends { skipPermission?: boolean }>(tool: T): T
 }
 
 function normalizeTools(tools: Tool<any>[], agentName: string): Tool<any>[] {
+  debugAgentTools(() => ({ agent: agentName, tools: tools.map((tool) => tool?.name) }));
   return tools.map((tool, index) => {
     if (!tool || typeof tool !== "object") {
       throw new Error(`Invalid tool for agent "${agentName}" at tools[${index}]. Expected a tool definition object.`);
@@ -2714,6 +2734,7 @@ export type ResponseAnalysisResult = { ok: true; output: unknown } | { ok: false
 export function analyzeResponse(response: string, outputSchema: Schema, agentName: string, turn: number): ResponseAnalysisResult {
   const parsed = parseJson(response);
   if (!parsed.ok) {
+    debugAgentParse({ agent: agentName, turn, kind: "parse", error: parsed.error });
     return {
       ok: false,
       error: new AgentError({
@@ -2729,6 +2750,7 @@ export function analyzeResponse(response: string, outputSchema: Schema, agentNam
 
   const result = validate(parsed.value, outputSchema);
   if (!result.ok) {
+    debugAgentParse({ agent: agentName, turn, kind: "validation", error: result.error });
     return {
       ok: false,
       error: new AgentError({
@@ -2742,6 +2764,7 @@ export function analyzeResponse(response: string, outputSchema: Schema, agentNam
     };
   }
 
+  debugAgentParse({ agent: agentName, turn, kind: "ok" });
   return { ok: true, output: parsed.value };
 }
 
diff --git a/src/rig.test.ts b/src/rig.test.ts
@@ -156,10 +156,36 @@ describe("debug logging", () => {
       "rig.agent:invoke",
       "rig.agent:turn",
       "rig.agent:response",
+      "rig.agent:parse",
       "rig.agent:complete",
       "rig.agent:close",
     ]);
   });
+
+  it("logs response parse failures with their kind", () => {
+    process.env["RIG_DEBUG"] = "agent:parse";
+
+    analyzeResponse("not json", s.string, "parse-debug", 1);
+    analyzeResponse(JSON.stringify(1), s.string, "parse-debug", 2);
+
+    const events = fsMocks.writeSync.mock.calls.map(([, line]) => JSON.parse(String(line)));
+    expect(events.map((event) => event.data.kind)).toEqual(["parse", "validation"]);
+    expect(events[0].type).toBe("rig.agent:parse");
+  });
+
+  it("logs registered tool names for an agent", () => {
+    process.env["RIG_DEBUG"] = "agent:tools";
+
+    agent({
+      name: "tool-debug",
+      tools: [defineTool("lookup", { description: "Lookup", parameters: s.object({ id: s.string }), handler: () => "ok" })],
+    });
+
+    expect(JSON.parse(String(fsMocks.writeSync.mock.calls[0]?.[1]))).toEqual({
+      type: "rig.agent:tools",
+      data: { agent: "tool-debug", tools: ["lookup"] },
+    });
+  });
 });
 
 describe("agent", () => {
