agency-lang 0.7.1 → 0.7.2

package/dist/lib/agents/agency-agent/tests/oneShotRounds.js

@@ -0,0 +1,555 @@
+import { print, printJSON, input, sleep, read, write, writeBinary, readBinary, range, callback, map, filter, exclude, find, findIndex, reduce, flatMap, every, some, count, sortBy, unique, groupBy } from "agency-lang/stdlib/index.js";
+import { resolveMaxToolCallRounds } from "../shared.js";
+import { fileURLToPath } from "url";
+import __process from "process";
+import { readFileSync } from "fs";
+import { nanoid } from "agency-lang";
+import path from "path";
+import {
+  RuntimeContext,
+  Runner,
+  setupNode,
+  runNode,
+  callHook,
+  checkpoint as __checkpoint_impl,
+  getCheckpoint as __getCheckpoint_impl,
+  restore as __restore_impl,
+  _run as __runtime_run_impl,
+  interrupt,
+  isInterrupt,
+  hasInterrupts,
+  isDebugger,
+  respondToInterrupts as _respondToInterrupts,
+  rewindFrom as _rewindFrom,
+  runExportedFunction as _runExportedFunction,
+  RestoreSignal,
+  AgencyAbort,
+  __registerGlobalsInit,
+  failure,
+  __eq,
+  AgencyFunction as __AgencyFunction,
+  __call,
+  __threads,
+  getRuntimeContext,
+  agencyStore,
+  functionRefReviver as __functionRefReviver,
+  DeterministicClient as __DeterministicClient,
+  installFetchMock as __installFetchMock,
+  createLogger as __createLogger
+} from "agency-lang/runtime";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const __cwd = __process.cwd();
+const getDirname = () => __dirname;
+const __globalCtx = new RuntimeContext({
+  statelogConfig: {
+    host: "https://statelog.adit.io",
+    apiKey: __process.env["STATELOG_API_KEY"] || "",
+    projectId: "agency-lang",
+    debugMode: false,
+    observability: true,
+    logFile: "log.jsonl"
+  },
+  smoltalkDefaults: {
+    apiKey: {
+      openAi: __process.env["OPENAI_API_KEY"] || "",
+      google: __process.env["GEMINI_API_KEY"] || "",
+      anthropic: __process.env["ANTHROPIC_API_KEY"] || "",
+      openRouter: __process.env["OPENROUTER_API_KEY"] || "",
+      deepInfra: __process.env["DEEPINFRA_API_KEY"] || "",
+      liteLlm: __process.env["LITELLM_API_KEY"] || "",
+      openAiCompat: __process.env["OPENAI_COMPAT_API_KEY"] || ""
+    },
+    baseUrl: {
+      liteLlm: __process.env["LITELLM_BASE_URL"] || "",
+      openAiCompat: __process.env["OPENAI_COMPAT_BASE_URL"] || ""
+    },
+    model: "gpt-4o-mini",
+    logLevel: "warn",
+    statelog: {
+      host: "https://statelog.adit.io",
+      projectId: "smoltalk",
+      apiKey: __process.env["STATELOG_SMOLTALK_API_KEY"] || "",
+      traceId: nanoid()
+    }
+  },
+  dirname: __dirname,
+  logLevel: "info",
+  traceConfig: {
+    program: "dist/lib/agents/agency-agent/tests/oneShotRounds.agency"
+  }
+});
+const graph = __globalCtx.graph;
+function approve(value) {
+  return { type: "approve", value };
+}
+function reject(value) {
+  return { type: "reject", value };
+}
+function propagate() {
+  return { type: "propagate" };
+}
+const respondToInterrupts = (interrupts, responses, opts) => _respondToInterrupts({ ctx: __globalCtx, interrupts, responses, overrides: opts?.overrides, metadata: opts?.metadata, registerTopLevelCallbacks: __registerTopLevelCallbacks, moduleDir: __dirname });
+const rewindFrom = (checkpoint2, overrides, opts) => _rewindFrom({ ctx: __globalCtx, checkpoint: checkpoint2, overrides, metadata: opts?.metadata, registerTopLevelCallbacks: __registerTopLevelCallbacks, moduleDir: __dirname });
+const __invokeFunction = (fn, namedArgs) => _runExportedFunction({ ctx: __globalCtx, fn, namedArgs, initializeGlobals: __initializeGlobals, registerTopLevelCallbacks: __registerTopLevelCallbacks, moduleDir: __dirname });
+const __setDebugger = (dbg) => {
+  __globalCtx.debuggerState = dbg;
+};
+const __setTraceFile = (filePath) => {
+  __globalCtx.traceConfig.traceFile = filePath;
+};
+const __setLLMClient = (client) => {
+  __globalCtx.setLLMClient(client);
+};
+const __getCheckpoints = () => __globalCtx.checkpoints;
+if (__process.env.AGENCY_LLM_MOCKS) {
+  __globalCtx.setLLMClient(
+    new __DeterministicClient(JSON.parse(__process.env.AGENCY_LLM_MOCKS))
+  );
+}
+if (__process.env.AGENCY_FETCH_MOCKS_FILE) {
+  __installFetchMock(JSON.parse(readFileSync(__process.env.AGENCY_FETCH_MOCKS_FILE, "utf-8")));
+}
+const __toolRegistry = __functionRefReviver.registry ??= {};
+function __registerTool(value, _aliasName) {
+  if (__AgencyFunction.isAgencyFunction(value)) {
+    __toolRegistry[`${value.module}:${value.name}`] = value;
+  }
+}
+const checkpoint = __AgencyFunction.create({ name: "checkpoint", module: "__runtime", fn: __checkpoint_impl, params: [], toolDefinition: null }, __toolRegistry);
+const getCheckpoint = __AgencyFunction.create({ name: "getCheckpoint", module: "__runtime", fn: __getCheckpoint_impl, params: [{ name: "checkpointId", hasDefault: false, defaultValue: void 0, variadic: false }], toolDefinition: null }, __toolRegistry);
+const restore = __AgencyFunction.create({ name: "restore", module: "__runtime", fn: __restore_impl, params: [{ name: "checkpointIdOrCheckpoint", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "options", hasDefault: false, defaultValue: void 0, variadic: false }], toolDefinition: null }, __toolRegistry);
+const _run = __AgencyFunction.create({ name: "_run", module: "__runtime", fn: __runtime_run_impl, params: [{ name: "compiled", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "node", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "args", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "wallClock", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "memory", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "ipcPayload", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "stdout", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "configOverrides", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "cwd", hasDefault: false, defaultValue: void 0, variadic: false }, { name: "maxDepth", hasDefault: false, defaultValue: void 0, variadic: false }], toolDefinition: null }, __toolRegistry);
+function setLLMClient(client) {
+  __globalCtx.setLLMClient(client);
+}
+function registerTools(tools) {
+  for (const tool of tools) {
+    if (__AgencyFunction.isAgencyFunction(tool)) {
+      __toolRegistry[`${tool.module}:${tool.name}`] = tool;
+    }
+  }
+}
+__registerTool(print);
+__registerTool(printJSON);
+__registerTool(input);
+__registerTool(sleep);
+__registerTool(read);
+__registerTool(write);
+__registerTool(writeBinary);
+__registerTool(readBinary);
+__registerTool(range);
+__registerTool(callback);
+__registerTool(map);
+__registerTool(filter);
+__registerTool(exclude);
+__registerTool(find);
+__registerTool(findIndex);
+__registerTool(reduce);
+__registerTool(flatMap);
+__registerTool(every);
+__registerTool(some);
+__registerTool(count);
+__registerTool(sortBy);
+__registerTool(unique);
+__registerTool(groupBy);
+__registerTool(resolveMaxToolCallRounds);
+async function __initializeGlobals(__ctx) {
+  if (__ctx.globals.isInitialized("dist/lib/agents/agency-agent/tests/oneShotRounds.agency")) {
+    return;
+  }
+  __ctx.globals.markInitialized("dist/lib/agents/agency-agent/tests/oneShotRounds.agency");
+}
+__registerGlobalsInit("dist/lib/agents/agency-agent/tests/oneShotRounds.agency", __initializeGlobals);
+async function __registerTopLevelCallbacks(__ctx) {
+  __ctx.topLevelCallbacks = [];
+}
+__functionRefReviver.registry = __toolRegistry;
+graph.node("explicitWinsOverOneShot", async (__state) => {
+  const __setupData = setupNode({
+    state: __state
+  });
+  const __stack = __setupData.stack;
+  const __step = __setupData.step;
+  const __self = __setupData.self;
+  const __ctx = getRuntimeContext().ctx;
+  let __forked;
+  let __functionCompleted = false;
+  const runner = new Runner(__ctx, __stack, { nodeContext: true, state: __stack, moduleId: "dist/lib/agents/agency-agent/tests/oneShotRounds.agency", scopeName: "explicitWinsOverOneShot", threads: __setupData.threads });
+  try {
+    await agencyStore.run({
+      ...getRuntimeContext(),
+      ctx: __ctx,
+      stack: __ctx.stateStack,
+      threads: __setupData.threads
+    }, async () => {
+      await runner.hook(0, async () => {
+        await callHook({
+          name: "onNodeStart",
+          data: {
+            nodeName: "explicitWinsOverOneShot"
+          }
+        });
+      });
+      await runner.step(1, async (runner2) => {
+        __self.__retryable = false;
+        runner2.halt({
+          messages: __threads(),
+          data: __eq(await __call(resolveMaxToolCallRounds, {
+            type: "positional",
+            args: [7, true]
+          }), 7)
+        });
+        return;
+      });
+    });
+    if (runner.halted) return runner.haltResult;
+    await runner.hook(2, async () => {
+      await callHook({
+        name: "onNodeEnd",
+        data: {
+          nodeName: "explicitWinsOverOneShot",
+          data: void 0
+        }
+      });
+    });
+    return {
+      messages: __threads(),
+      data: void 0
+    };
+  } catch (__error) {
+    if (__error instanceof RestoreSignal) {
+      throw __error;
+    }
+    if (__error instanceof AgencyAbort) {
+      throw __error;
+    }
+    {
+      const __errMsg = __error instanceof Error ? __error.message : String(__error);
+      const __errStack = __error instanceof Error && __error.stack ? __error.stack : "";
+      const __log = __createLogger(__ctx.logLevel);
+      __log.error(`Node explicitWinsOverOneShot crashed: ${__errMsg}`);
+      if (__errStack) __log.error(__errStack);
+      __ctx.statelogClient?.error?.({
+        errorType: "runtimeError",
+        message: __errMsg,
+        functionName: "explicitWinsOverOneShot"
+      });
+    }
+    return {
+      messages: __threads(),
+      data: failure(__error instanceof Error ? __error.message : String(__error), { functionName: "explicitWinsOverOneShot" })
+    };
+  }
+});
+graph.node("oneShotDefaults50", async (__state) => {
+  const __setupData = setupNode({
+    state: __state
+  });
+  const __stack = __setupData.stack;
+  const __step = __setupData.step;
+  const __self = __setupData.self;
+  const __ctx = getRuntimeContext().ctx;
+  let __forked;
+  let __functionCompleted = false;
+  const runner = new Runner(__ctx, __stack, { nodeContext: true, state: __stack, moduleId: "dist/lib/agents/agency-agent/tests/oneShotRounds.agency", scopeName: "oneShotDefaults50", threads: __setupData.threads });
+  try {
+    await agencyStore.run({
+      ...getRuntimeContext(),
+      ctx: __ctx,
+      stack: __ctx.stateStack,
+      threads: __setupData.threads
+    }, async () => {
+      await runner.hook(0, async () => {
+        await callHook({
+          name: "onNodeStart",
+          data: {
+            nodeName: "oneShotDefaults50"
+          }
+        });
+      });
+      await runner.step(1, async (runner2) => {
+        __self.__retryable = false;
+        runner2.halt({
+          messages: __threads(),
+          data: __eq(await __call(resolveMaxToolCallRounds, {
+            type: "positional",
+            args: [null, true]
+          }), 50)
+        });
+        return;
+      });
+    });
+    if (runner.halted) return runner.haltResult;
+    await runner.hook(2, async () => {
+      await callHook({
+        name: "onNodeEnd",
+        data: {
+          nodeName: "oneShotDefaults50",
+          data: void 0
+        }
+      });
+    });
+    return {
+      messages: __threads(),
+      data: void 0
+    };
+  } catch (__error) {
+    if (__error instanceof RestoreSignal) {
+      throw __error;
+    }
+    if (__error instanceof AgencyAbort) {
+      throw __error;
+    }
+    {
+      const __errMsg = __error instanceof Error ? __error.message : String(__error);
+      const __errStack = __error instanceof Error && __error.stack ? __error.stack : "";
+      const __log = __createLogger(__ctx.logLevel);
+      __log.error(`Node oneShotDefaults50 crashed: ${__errMsg}`);
+      if (__errStack) __log.error(__errStack);
+      __ctx.statelogClient?.error?.({
+        errorType: "runtimeError",
+        message: __errMsg,
+        functionName: "oneShotDefaults50"
+      });
+    }
+    return {
+      messages: __threads(),
+      data: failure(__error instanceof Error ? __error.message : String(__error), { functionName: "oneShotDefaults50" })
+    };
+  }
+});
+graph.node("explicitWinsOverInteractive", async (__state) => {
+  const __setupData = setupNode({
+    state: __state
+  });
+  const __stack = __setupData.stack;
+  const __step = __setupData.step;
+  const __self = __setupData.self;
+  const __ctx = getRuntimeContext().ctx;
+  let __forked;
+  let __functionCompleted = false;
+  const runner = new Runner(__ctx, __stack, { nodeContext: true, state: __stack, moduleId: "dist/lib/agents/agency-agent/tests/oneShotRounds.agency", scopeName: "explicitWinsOverInteractive", threads: __setupData.threads });
+  try {
+    await agencyStore.run({
+      ...getRuntimeContext(),
+      ctx: __ctx,
+      stack: __ctx.stateStack,
+      threads: __setupData.threads
+    }, async () => {
+      await runner.hook(0, async () => {
+        await callHook({
+          name: "onNodeStart",
+          data: {
+            nodeName: "explicitWinsOverInteractive"
+          }
+        });
+      });
+      await runner.step(1, async (runner2) => {
+        __self.__retryable = false;
+        runner2.halt({
+          messages: __threads(),
+          data: __eq(await __call(resolveMaxToolCallRounds, {
+            type: "positional",
+            args: [3, false]
+          }), 3)
+        });
+        return;
+      });
+    });
+    if (runner.halted) return runner.haltResult;
+    await runner.hook(2, async () => {
+      await callHook({
+        name: "onNodeEnd",
+        data: {
+          nodeName: "explicitWinsOverInteractive",
+          data: void 0
+        }
+      });
+    });
+    return {
+      messages: __threads(),
+      data: void 0
+    };
+  } catch (__error) {
+    if (__error instanceof RestoreSignal) {
+      throw __error;
+    }
+    if (__error instanceof AgencyAbort) {
+      throw __error;
+    }
+    {
+      const __errMsg = __error instanceof Error ? __error.message : String(__error);
+      const __errStack = __error instanceof Error && __error.stack ? __error.stack : "";
+      const __log = __createLogger(__ctx.logLevel);
+      __log.error(`Node explicitWinsOverInteractive crashed: ${__errMsg}`);
+      if (__errStack) __log.error(__errStack);
+      __ctx.statelogClient?.error?.({
+        errorType: "runtimeError",
+        message: __errMsg,
+        functionName: "explicitWinsOverInteractive"
+      });
+    }
+    return {
+      messages: __threads(),
+      data: failure(__error instanceof Error ? __error.message : String(__error), { functionName: "explicitWinsOverInteractive" })
+    };
+  }
+});
+graph.node("interactiveKeepsBaked", async (__state) => {
+  const __setupData = setupNode({
+    state: __state
+  });
+  const __stack = __setupData.stack;
+  const __step = __setupData.step;
+  const __self = __setupData.self;
+  const __ctx = getRuntimeContext().ctx;
+  let __forked;
+  let __functionCompleted = false;
+  const runner = new Runner(__ctx, __stack, { nodeContext: true, state: __stack, moduleId: "dist/lib/agents/agency-agent/tests/oneShotRounds.agency", scopeName: "interactiveKeepsBaked", threads: __setupData.threads });
+  try {
+    await agencyStore.run({
+      ...getRuntimeContext(),
+      ctx: __ctx,
+      stack: __ctx.stateStack,
+      threads: __setupData.threads
+    }, async () => {
+      await runner.hook(0, async () => {
+        await callHook({
+          name: "onNodeStart",
+          data: {
+            nodeName: "interactiveKeepsBaked"
+          }
+        });
+      });
+      await runner.step(1, async (runner2) => {
+        __self.__retryable = false;
+        runner2.halt({
+          messages: __threads(),
+          data: __eq(await __call(resolveMaxToolCallRounds, {
+            type: "positional",
+            args: [null, false]
+          }), null)
+        });
+        return;
+      });
+    });
+    if (runner.halted) return runner.haltResult;
+    await runner.hook(2, async () => {
+      await callHook({
+        name: "onNodeEnd",
+        data: {
+          nodeName: "interactiveKeepsBaked",
+          data: void 0
+        }
+      });
+    });
+    return {
+      messages: __threads(),
+      data: void 0
+    };
+  } catch (__error) {
+    if (__error instanceof RestoreSignal) {
+      throw __error;
+    }
+    if (__error instanceof AgencyAbort) {
+      throw __error;
+    }
+    {
+      const __errMsg = __error instanceof Error ? __error.message : String(__error);
+      const __errStack = __error instanceof Error && __error.stack ? __error.stack : "";
+      const __log = __createLogger(__ctx.logLevel);
+      __log.error(`Node interactiveKeepsBaked crashed: ${__errMsg}`);
+      if (__errStack) __log.error(__errStack);
+      __ctx.statelogClient?.error?.({
+        errorType: "runtimeError",
+        message: __errMsg,
+        functionName: "interactiveKeepsBaked"
+      });
+    }
+    return {
+      messages: __threads(),
+      data: failure(__error instanceof Error ? __error.message : String(__error), { functionName: "interactiveKeepsBaked" })
+    };
+  }
+});
+async function explicitWinsOverOneShot({ messages, callbacks } = {}) {
+  return runNode({
+    ctx: __globalCtx,
+    nodeName: "explicitWinsOverOneShot",
+    data: {},
+    messages,
+    callbacks,
+    initializeGlobals: __initializeGlobals,
+    registerTopLevelCallbacks: __registerTopLevelCallbacks,
+    moduleDir: __dirname
+  });
+}
+const __explicitWinsOverOneShotNodeParams = [];
+async function oneShotDefaults50({ messages, callbacks } = {}) {
+  return runNode({
+    ctx: __globalCtx,
+    nodeName: "oneShotDefaults50",
+    data: {},
+    messages,
+    callbacks,
+    initializeGlobals: __initializeGlobals,
+    registerTopLevelCallbacks: __registerTopLevelCallbacks,
+    moduleDir: __dirname
+  });
+}
+const __oneShotDefaults50NodeParams = [];
+async function explicitWinsOverInteractive({ messages, callbacks } = {}) {
+  return runNode({
+    ctx: __globalCtx,
+    nodeName: "explicitWinsOverInteractive",
+    data: {},
+    messages,
+    callbacks,
+    initializeGlobals: __initializeGlobals,
+    registerTopLevelCallbacks: __registerTopLevelCallbacks,
+    moduleDir: __dirname
+  });
+}
+const __explicitWinsOverInteractiveNodeParams = [];
+async function interactiveKeepsBaked({ messages, callbacks } = {}) {
+  return runNode({
+    ctx: __globalCtx,
+    nodeName: "interactiveKeepsBaked",
+    data: {},
+    messages,
+    callbacks,
+    initializeGlobals: __initializeGlobals,
+    registerTopLevelCallbacks: __registerTopLevelCallbacks,
+    moduleDir: __dirname
+  });
+}
+const __interactiveKeepsBakedNodeParams = [];
+var stdin_default = graph;
+const __sourceMap = { "dist/lib/agents/agency-agent/tests/oneShotRounds.agency:explicitWinsOverOneShot": { "1": { "line": 6, "col": 2 } }, "dist/lib/agents/agency-agent/tests/oneShotRounds.agency:oneShotDefaults50": { "1": { "line": 10, "col": 2 } }, "dist/lib/agents/agency-agent/tests/oneShotRounds.agency:explicitWinsOverInteractive": { "1": { "line": 14, "col": 2 } }, "dist/lib/agents/agency-agent/tests/oneShotRounds.agency:interactiveKeepsBaked": { "1": { "line": 18, "col": 2 } } };
+export {
+  __explicitWinsOverInteractiveNodeParams,
+  __explicitWinsOverOneShotNodeParams,
+  __getCheckpoints,
+  __interactiveKeepsBakedNodeParams,
+  __invokeFunction,
+  __oneShotDefaults50NodeParams,
+  __setDebugger,
+  __setLLMClient,
+  __setTraceFile,
+  __sourceMap,
+  __toolRegistry,
+  approve,
+  stdin_default as default,
+  explicitWinsOverInteractive,
+  explicitWinsOverOneShot,
+  hasInterrupts,
+  interactiveKeepsBaked,
+  interrupt,
+  isDebugger,
+  isInterrupt,
+  oneShotDefaults50,
+  reject,
+  respondToInterrupts,
+  rewindFrom
+};

package/dist/lib/agents/agency-agent/tests/oneShotRounds.test.json

@@ -0,0 +1,9 @@
+{
+  "sourceFile": "oneShotRounds.agency",
+  "tests": [
+    { "nodeName": "explicitWinsOverOneShot", "input": "", "expectedOutput": "true", "evaluationCriteria": [{ "type": "exact" }] },
+    { "nodeName": "oneShotDefaults50", "input": "", "expectedOutput": "true", "evaluationCriteria": [{ "type": "exact" }] },
+    { "nodeName": "explicitWinsOverInteractive", "input": "", "expectedOutput": "true", "evaluationCriteria": [{ "type": "exact" }] },
+    { "nodeName": "interactiveKeepsBaked", "input": "", "expectedOutput": "true", "evaluationCriteria": [{ "type": "exact" }] }
+  ]
+}

package/dist/lib/cli/doctor.d.ts

@@ -1,5 +1,13 @@
 import { AgencyConfig } from "../config.js";
 export declare function buildDoctorPrompt(file: string, symptom?: string): string;
+export declare function buildDoctorArgs(opts: {
+    file: string;
+    symptom?: string;
+    trace?: string | true;
+    logFile?: string;
+}): string[];
 export declare function doctor(config: AgencyConfig, file: string, opts?: {
     symptom?: string;
+    trace?: string | true;
+    logFile?: string;
 }): void;

package/dist/lib/cli/doctor.js

@@ -26,18 +26,26 @@ export function buildDoctorPrompt(file, symptom) {
             "re-run `typecheck` to confirm the file is clean.",
     ].join("\n");
 }
-// `agency doctor <file> [--symptom <text>]` — launch the agency agent in
-// interactive mode, seeded with a diagnosis prompt routed to the code
-// subagent. A thin wrapper over the generic --interactive/--agent flags.
+// Build the argv forwarded to the bundled agent. Kept pure and exported so
+// the flag assembly can be unit-tested without launching the agent. Debug
+// flags go BEFORE the `--` terminator (tokens after `--` are positionals to
+// the agent's std::args parser); the prompt is the sole positional after it.
+export function buildDoctorArgs(opts) {
+    const prompt = buildDoctorPrompt(opts.file, opts.symptom);
+    const debug = [];
+    if (opts.trace !== undefined) {
+        debug.push("--trace");
+        if (typeof opts.trace === "string")
+            debug.push(opts.trace);
+    }
+    if (opts.logFile)
+        debug.push("--log-file", opts.logFile);
+    return ["--interactive", "--agent", "code", ...debug, "--", prompt];
+}
+// `agency doctor <file> [--symptom <text>] [--trace [file]] [--log-file <path>]`
+// — launch the agency agent in interactive mode, seeded with a diagnosis prompt
+// routed to the code subagent. A thin wrapper over the generic
+// --interactive/--agent flags.
 export function doctor(config, file, opts = {}) {
-    const prompt = buildDoctorPrompt(file, opts.symptom);
-    // `--` ends flag parsing so the prompt (which may start with `-`) is
-    // treated as a positional by the agent's std::args parser.
-    runBundledAgent(config, "agency-agent", [
-        "--interactive",
-        "--agent",
-        "code",
-        "--",
-        prompt,
-    ]);
+    runBundledAgent(config, "agency-agent", buildDoctorArgs({ file, ...opts }));
 }

package/dist/lib/cli/doctor.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { buildDoctorArgs } from "./doctor.js";
+describe("buildDoctorArgs", () => {
+    it("appends --trace / --log-file before the -- terminator", () => {
+        const args = buildDoctorArgs({
+            file: "x.agency",
+            symptom: "boom",
+            trace: "t.trace",
+            logFile: "l.jsonl",
+        });
+        const dashDash = args.indexOf("--");
+        expect(dashDash).toBeGreaterThan(-1);
+        expect(args.indexOf("--trace")).toBeGreaterThan(-1);
+        expect(args.indexOf("--trace")).toBeLessThan(dashDash);
+        expect(args.indexOf("--log-file")).toBeLessThan(dashDash);
+        expect(args.slice(args.indexOf("--trace"), args.indexOf("--trace") + 2)).toEqual([
+            "--trace",
+            "t.trace",
+        ]);
+    });
+    it("bare --trace appends just the flag before --", () => {
+        const args = buildDoctorArgs({ file: "x.agency", trace: true });
+        expect(args.filter((a) => a === "--trace")).toHaveLength(1);
+        expect(args.indexOf("--trace")).toBeLessThan(args.indexOf("--"));
+        // No stray value token after a bare --trace.
+        expect(args[args.indexOf("--trace") + 1]).toBe("--");
+    });
+    it("omits the debug flags entirely when not requested", () => {
+        const args = buildDoctorArgs({ file: "x.agency", symptom: "boom" });
+        expect(args).not.toContain("--trace");
+        expect(args).not.toContain("--log-file");
+        expect(args[args.length - 2]).toBe("--");
+    });
+});

package/dist/lib/cli/help.js

@@ -27,11 +27,7 @@ Flags:
 Config File (agency.json):
   {
     "verbose": false,                   Enable verbose logging by default
-    "outDir": "./dist",                 Default output directory for compiled files
-    "excludeNodeTypes": ["comment"],    Node types to exclude from code generation
-    "excludeBuiltinFunctions": ["write"], Builtin functions to exclude
-    "allowedFetchDomains": ["api.example.com"], Whitelist for fetch domains
-    "disallowedFetchDomains": ["blocked.com"]   Blacklist for fetch domains
+    "outDir": "./dist"                  Default output directory for compiled files
   }
 
 Examples:

package/dist/lib/cli/runBundledAgent.d.ts

@@ -1,2 +1,18 @@
 import { AgencyConfig } from "../config.js";
-export declare function runBundledAgent(config: AgencyConfig, agentName: string, args?: string[]): void;
+import { spawn as realSpawn } from "child_process";
+/**
+ * Extract the debug flags (`--trace`, `--log-file`) from a bundled agent's
+ * forwarded argv, as a config override. This is the ONE place these flags are
+ * handled — every bundled agent gets them for free by going through
+ * `runBundledAgent`; no agent writes flag code.
+ *
+ * Tokenization is `node:util.parseArgs` (which `std::args` is itself built on)
+ * after the same bare-flag normalization std::args applies, so `--flag=value`,
+ * the `--` terminator, last-wins-on-repeat, AND a following-flag-is-not-a-value
+ * all match the agent's own parser. An empty/bare `--trace` maps to a per-run
+ * trace file in cwd; the flag→config meaning lives in `applyCliFlags`.
+ */
+export declare function agentConfigOverride(args: string[]): Partial<AgencyConfig>;
+export declare function runBundledAgent(config: AgencyConfig, agentName: string, args?: string[], deps?: {
+    spawn?: typeof realSpawn;
+}): void;