agency-lang 0.7.0 → 0.7.2

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;

package/dist/lib/cli/runBundledAgent.js

@@ -1,9 +1,72 @@
+import { applyCliFlags, CONFIG_OVERRIDES_ENV, serializeConfigOverrides, } from "../config.js";
 import { compile, compiledOutputNodeArgs } from "./commands.js";
-import { spawn } from "child_process";
+import { spawn as realSpawn } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
+import { parseArgs } from "node:util";
 const currentDir = path.dirname(new URL(import.meta.url).pathname);
-export function runBundledAgent(config, agentName, args = []) {
+// The debug flags every bundled agent understands. Same names the agent
+// declares (for --help) and that `agency run` accepts.
+const AGENT_DEBUG_FLAGS = ["--trace", "--log-file"];
+/**
+ * Rewrite a bare debug flag to its empty attached form (`--trace` → `--trace=`)
+ * when its next token is absent or starts with `-`. This replicates exactly
+ * what `std::args` does before parsing (lib/stdlib/args.ts:499-505), so the
+ * agent's own parser and this pre-scan agree: `--trace --print` and `--trace
+ * -p` are BOTH bare here, not a trace file named "--print" / "-p". Stops at the
+ * `--` terminator (everything after is positional).
+ */
+function normalizeBareDebugFlags(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        const token = args[i];
+        if (token === "--") {
+            out.push(...args.slice(i));
+            break;
+        }
+        if (AGENT_DEBUG_FLAGS.includes(token)) {
+            const next = args[i + 1];
+            const bare = next === undefined || next === "--" || next.startsWith("-");
+            out.push(bare ? `${token}=` : token);
+        }
+        else {
+            out.push(token);
+        }
+    }
+    return out;
+}
+/**
+ * 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 function agentConfigOverride(args) {
+    const { values } = parseArgs({
+        args: normalizeBareDebugFlags(args),
+        options: { trace: { type: "string" }, "log-file": { type: "string" } },
+        strict: false,
+        allowPositionals: true,
+    });
+    const flags = {};
+    // After normalization a present --trace is always a string ("" when bare).
+    if (typeof values.trace === "string") {
+        flags.trace = values.trace;
+    }
+    // --log-file requires a value; a bare (now "") --log-file is ignored.
+    if (typeof values["log-file"] === "string" && values["log-file"] !== "") {
+        flags.logFile = values["log-file"];
+    }
+    return applyCliFlags({}, flags);
+}
+export function runBundledAgent(config, agentName, args = [], deps = {}) {
+    const spawn = deps.spawn ?? realSpawn;
     const agentDir = path.resolve(currentDir, `../agents/${agentName}`);
     const agencyFile = path.join(agentDir, "agent.agency");
     const precompiledFile = path.join(agentDir, "agent.js");
@@ -21,9 +84,17 @@ export function runBundledAgent(config, agentName, args = []) {
         console.error(`Failed to compile agent ${agentName}.`);
         process.exit(1);
     }
+    const overrides = agentConfigOverride(args);
+    const env = Object.keys(overrides).length > 0
+        ? {
+            ...process.env,
+            [CONFIG_OVERRIDES_ENV]: serializeConfigOverrides(overrides),
+        }
+        : process.env;
     const nodeProcess = spawn(process.execPath, [...compiledOutputNodeArgs(), runFile, ...args], {
         stdio: "inherit",
         shell: false,
+        env,
     });
     nodeProcess.on("error", (error) => {
         console.error(`Failed to run ${agentName}:`, error);

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,96 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+// Force the precompiled-file branch so runBundledAgent never invokes the
+// compiler; spawn is injected, so nothing actually launches.
+vi.mock("fs", async (importOriginal) => {
+    const actual = await importOriginal();
+    return { ...actual, existsSync: () => true };
+});
+import { CONFIG_OVERRIDES_ENV } from "../config.js";
+import { agentConfigOverride, runBundledAgent } from "./runBundledAgent.js";
+describe("agentConfigOverride", () => {
+    it("--trace <file> → traceFile", () => {
+        expect(agentConfigOverride(["--trace", "out.agencytrace"])).toEqual({
+            trace: true,
+            traceFile: "out.agencytrace",
+        });
+    });
+    it("--trace=<file> attached form", () => {
+        expect(agentConfigOverride(["--trace=x.trace"])).toEqual({
+            trace: true,
+            traceFile: "x.trace",
+        });
+    });
+    it("bare --trace → per-run dir (traceDir)", () => {
+        expect(agentConfigOverride(["--trace"])).toEqual({ trace: true, traceDir: "." });
+    });
+    it("empty --trace= behaves identically to bare --trace (the divergence bug)", () => {
+        expect(agentConfigOverride(["--trace="])).toEqual({ trace: true, traceDir: "." });
+    });
+    it("a following flag is NOT consumed as the --trace value (matches std::args)", () => {
+        // Both are bare on the agent side, so they must be bare here too — not a
+        // trace file named "--print" / "-p".
+        expect(agentConfigOverride(["--trace", "--print", "hi"])).toEqual({
+            trace: true,
+            traceDir: ".",
+        });
+        expect(agentConfigOverride(["--trace", "-p"])).toEqual({ trace: true, traceDir: "." });
+    });
+    it("bare --log-file (or one followed by a flag) is ignored, not a file named --print", () => {
+        expect(agentConfigOverride(["--log-file"])).toEqual({});
+        expect(agentConfigOverride(["--log-file", "--print"])).toEqual({});
+    });
+    it("--log-file <path> → log.logFile + observability, space and attached forms", () => {
+        const expected = { log: { logFile: "l.jsonl" }, observability: true };
+        expect(agentConfigOverride(["--log-file", "l.jsonl"])).toEqual(expected);
+        expect(agentConfigOverride(["--log-file=l.jsonl"])).toEqual(expected);
+    });
+    it("stops at the -- terminator", () => {
+        expect(agentConfigOverride(["--", "--trace", "x"])).toEqual({});
+    });
+    it("last --trace wins on repeats", () => {
+        expect(agentConfigOverride(["--trace", "a", "--trace", "b"])).toEqual({
+            trace: true,
+            traceFile: "b",
+        });
+    });
+    it("combines trace + log and ignores the agent's own flags/positionals", () => {
+        expect(agentConfigOverride(["--model", "gpt", "hi", "--trace", "t", "--log-file", "l"])).toEqual({
+            trace: true,
+            traceFile: "t",
+            log: { logFile: "l" },
+            observability: true,
+        });
+    });
+    it("empty when neither flag is present", () => {
+        expect(agentConfigOverride(["--print", "do it"])).toEqual({});
+    });
+});
+describe("runBundledAgent passes config overrides to the child via env", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("serializes the override into AGENCY_CONFIG_OVERRIDES", () => {
+        const onMock = vi.fn();
+        const spawnMock = vi.fn((..._args) => ({ on: onMock }));
+        runBundledAgent({}, "agency-agent", ["--trace", "t.trace", "--log-file", "l.jsonl"], {
+            spawn: spawnMock,
+        });
+        expect(spawnMock).toHaveBeenCalledTimes(1);
+        const opts = spawnMock.mock.calls[0][2];
+        const overrides = JSON.parse(opts.env[CONFIG_OVERRIDES_ENV]);
+        expect(overrides).toEqual({
+            trace: true,
+            traceFile: "t.trace",
+            log: { logFile: "l.jsonl" },
+            observability: true,
+        });
+        // Parent env is preserved (spread), so PATH survives.
+        expect(opts.env.PATH).toBe(process.env.PATH);
+    });
+    it("does not set the env var when no debug flags are present", () => {
+        const spawnMock = vi.fn((..._args) => ({ on: vi.fn() }));
+        runBundledAgent({}, "agency-agent", ["--print", "hi"], { spawn: spawnMock });
+        const opts = spawnMock.mock.calls[0][2];
+        expect(opts.env[CONFIG_OVERRIDES_ENV]).toBeUndefined();
+    });
+});

package/dist/lib/config.d.ts

@@ -24,34 +24,6 @@ export interface AgencyConfig {
     verbose?: boolean;
     logLevel?: LogLevel;
     outDir?: string;
-    /**
-     * Array of AST node types to exclude from code generation
-     * Example: ["comment", "typeAlias"]
-     */
-    excludeNodeTypes?: string[];
-    /**
-     * Array of built-in function names to exclude from code generation
-     * Example: ["fetch", "write"]
-     */
-    excludeBuiltinFunctions?: string[];
-    /**
-     * Array of domains allowed for fetch operations
-     * If specified, only these domains can be fetched
-     * Example: ["api.example.com", "data.mysite.com"]
-     */
-    allowedFetchDomains?: string[];
-    /**
-     * Array of domains disallowed for fetch operations
-     * These domains will throw an error if fetch is attempted
-     * If both allowed and disallowed are set, takes the intersection
-     * (only allowed domains, minus disallowed ones)
-     * Example: ["malicious.com", "blocked.site.com"]
-     */
-    disallowedFetchDomains?: string[];
-    /**
-     * Optionally specify a custom host for tarsec trace collection
-     */
-    tarsecTraceHost?: string;
     /**
      * Number of times the LLM can go back and forth between calling tools
      * and responding to their outputs before halting execution to prevent infinite loops.
@@ -339,11 +311,6 @@ export declare const AgencyConfigSchema: z.ZodObject<{
         error: "error";
     }>>;
     outDir: z.ZodOptional<z.ZodString>;
-    excludeNodeTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    excludeBuiltinFunctions: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    allowedFetchDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    disallowedFetchDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    tarsecTraceHost: z.ZodOptional<z.ZodString>;
     maxToolCallRounds: z.ZodOptional<z.ZodNumber>;
     observability: z.ZodOptional<z.ZodBoolean>;
     log: z.ZodOptional<z.ZodObject<{
@@ -507,3 +474,45 @@ export declare function loadConfigSafe(configPath: string): {
  * Returns the directory containing agency.json, or null if not found.
  */
 export declare function findProjectRoot(startPath: string): string | null;
+/** Per-invocation flags accepted by `agency run`/`compile` and forwarded to the
+ *  bundled agents. Mapped onto AgencyConfig by applyCliFlags. `trace` is
+ *  `string` for `--trace <file>`, `true` for a bare `--trace`. */
+export type CliFlags = {
+    trace?: string | true;
+    logFile?: string;
+    observability?: boolean;
+    strict?: boolean;
+    maxToolCallRounds?: number;
+    maxToolResultChars?: number;
+};
+/**
+ * Fold per-invocation CLI flags onto a config COPY (never mutates the input).
+ * The single definition of what each debug flag means:
+ *   --trace <file>   → trace + traceFile=<file>
+ *   --trace (bare)   → trace + traceFile=<input>.trace when an input path is
+ *                      known (agency run), else traceDir="." (a bundled agent
+ *                      with no input file → a per-run file in cwd)
+ *   --log-file <p>   → log.logFile=<p> and observability=true
+ *   --observability  → observability=true
+ *   --strict         → typechecker.strict + strictTypes (the compile-path gate
+ *                      never runs the checker on strictTypes alone)
+ *   --max-tool-call-rounds <n> → maxToolCallRounds=<n> (baked into runPrompt at
+ *                      compile time; overrides agency.json for this run)
+ *   --max-tool-result-chars <n> → client.maxToolResultChars=<n> (0 disables the
+ *                      cap; overrides agency.json for this run)
+ */
+export declare function applyCliFlags(config: AgencyConfig, flags: CliFlags, input?: string): AgencyConfig;
+/** The one env var carrying a JSON Partial<AgencyConfig> into an already-compiled
+ *  process (see the source-of-truth note above, source 3). */
+export declare const CONFIG_OVERRIDES_ENV = "AGENCY_CONFIG_OVERRIDES";
+/** Serialize config overrides for a child process's AGENCY_CONFIG_OVERRIDES. */
+export declare function serializeConfigOverrides(overrides: Partial<AgencyConfig>): string;
+/** Read + validate AGENCY_CONFIG_OVERRIDES. Returns {} when the var is absent,
+ *  unparseable, or fails schema validation, so a malformed value can never
+ *  brick startup. */
+export declare function readConfigOverrides(env?: NodeJS.ProcessEnv): Partial<AgencyConfig>;
+/** Return a deep copy of `config` with secret-bearing fields masked, for
+ *  human-facing output (`agency config show`). Masks every `apiKey` — the
+ *  top-level `log.apiKey` string and each key under `client.apiKey` /
+ *  `client.statelog.apiKey` — to `•••<last4>`. */
+export declare function redactConfigSecrets(config: AgencyConfig): AgencyConfig;

package/dist/lib/config.js

@@ -29,12 +29,10 @@ export const AgencyConfigSchema = z
     verbose: z.boolean(),
     logLevel: z.enum(["debug", "info", "warn", "error"]),
     outDir: z.string(),
-    excludeNodeTypes: z.array(z.string()),
-    excludeBuiltinFunctions: z.array(z.string()),
-    allowedFetchDomains: z.array(z.string()),
-    disallowedFetchDomains: z.array(z.string()),
-    tarsecTraceHost: z.string(),
-    maxToolCallRounds: z.number(),
+    // Positive integer: the generated code does `maxToolCallRounds || 10`, so a
+    // 0 would silently mean 10 and a float/negative is meaningless — reject at
+    // load rather than surprise. Mirrors maxCallDepth.
+    maxToolCallRounds: z.number().int().positive(),
     observability: z.boolean(),
     log: z
         .object({
@@ -228,3 +226,107 @@ export function findProjectRoot(startPath) {
         current = parent;
     }
 }
+/**
+ * Fold per-invocation CLI flags onto a config COPY (never mutates the input).
+ * The single definition of what each debug flag means:
+ *   --trace <file>   → trace + traceFile=<file>
+ *   --trace (bare)   → trace + traceFile=<input>.trace when an input path is
+ *                      known (agency run), else traceDir="." (a bundled agent
+ *                      with no input file → a per-run file in cwd)
+ *   --log-file <p>   → log.logFile=<p> and observability=true
+ *   --observability  → observability=true
+ *   --strict         → typechecker.strict + strictTypes (the compile-path gate
+ *                      never runs the checker on strictTypes alone)
+ *   --max-tool-call-rounds <n> → maxToolCallRounds=<n> (baked into runPrompt at
+ *                      compile time; overrides agency.json for this run)
+ *   --max-tool-result-chars <n> → client.maxToolResultChars=<n> (0 disables the
+ *                      cap; overrides agency.json for this run)
+ */
+export function applyCliFlags(config, flags, input) {
+    const next = { ...config };
+    if (flags.trace !== undefined) {
+        next.trace = true;
+        const explicitFile = typeof flags.trace === "string" && flags.trace !== "";
+        if (explicitFile) {
+            next.traceFile = flags.trace;
+        }
+        else if (input) {
+            next.traceFile = input.replace(/\.agency$/, ".trace");
+        }
+        else {
+            next.traceDir = ".";
+        }
+    }
+    if (flags.logFile) {
+        next.log = { ...next.log, logFile: flags.logFile };
+        next.observability = true;
+    }
+    if (flags.observability) {
+        next.observability = true;
+    }
+    if (flags.strict) {
+        next.typechecker = { ...next.typechecker, strict: true, strictTypes: true };
+    }
+    if (flags.maxToolCallRounds !== undefined) {
+        next.maxToolCallRounds = flags.maxToolCallRounds;
+    }
+    if (flags.maxToolResultChars !== undefined) {
+        next.client = { ...next.client, maxToolResultChars: flags.maxToolResultChars };
+    }
+    return next;
+}
+/** The one env var carrying a JSON Partial<AgencyConfig> into an already-compiled
+ *  process (see the source-of-truth note above, source 3). */
+export const CONFIG_OVERRIDES_ENV = "AGENCY_CONFIG_OVERRIDES";
+/** Serialize config overrides for a child process's AGENCY_CONFIG_OVERRIDES. */
+export function serializeConfigOverrides(overrides) {
+    return JSON.stringify(overrides);
+}
+/** Read + validate AGENCY_CONFIG_OVERRIDES. Returns {} when the var is absent,
+ *  unparseable, or fails schema validation, so a malformed value can never
+ *  brick startup. */
+export function readConfigOverrides(env = process.env) {
+    const raw = env[CONFIG_OVERRIDES_ENV];
+    if (!raw)
+        return {};
+    try {
+        const result = AgencyConfigSchema.safeParse(JSON.parse(raw));
+        if (!result.success) {
+            // Don't brick startup, but never fail silently — a typo'd override that
+            // makes --trace/--log-file quietly do nothing is the worst failure mode.
+            console.error(`Ignoring invalid ${CONFIG_OVERRIDES_ENV}: ${result.error.issues
+                .map((i) => i.path.join("."))
+                .join(", ")}`);
+            return {};
+        }
+        return result.data;
+    }
+    catch (err) {
+        console.error(`Ignoring unparseable ${CONFIG_OVERRIDES_ENV}: ${err instanceof Error ? err.message : String(err)}`);
+        return {};
+    }
+}
+/** Return a deep copy of `config` with secret-bearing fields masked, for
+ *  human-facing output (`agency config show`). Masks every `apiKey` — the
+ *  top-level `log.apiKey` string and each key under `client.apiKey` /
+ *  `client.statelog.apiKey` — to `•••<last4>`. */
+export function redactConfigSecrets(config) {
+    const mask = (value) => value.length <= 4 ? "•••" : `•••${value.slice(-4)}`;
+    const clone = JSON.parse(JSON.stringify(config));
+    const redactKeyMap = (obj) => {
+        if (!obj)
+            return;
+        for (const key of Object.keys(obj)) {
+            if (typeof obj[key] === "string")
+                obj[key] = mask(obj[key]);
+        }
+    };
+    if (clone.log && typeof clone.log.apiKey === "string") {
+        clone.log.apiKey = mask(clone.log.apiKey);
+    }
+    redactKeyMap(clone.client?.apiKey);
+    if (clone.client?.statelog && typeof clone.client.statelog.apiKey === "string") {
+        clone.client.statelog.apiKey = mask(clone.client.statelog.apiKey);
+    }
+    return clone;
+}

package/dist/lib/config.test.js

@@ -1,5 +1,8 @@
-import { describe, it, expect } from "vitest";
-import { AgencyConfigSchema } from "./config.js";
+import { describe, it, expect, vi } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { AgencyConfigSchema, applyCliFlags, CONFIG_OVERRIDES_ENV, loadConfigSafe, readConfigOverrides, redactConfigSecrets, serializeConfigOverrides, } from "./config.js";
 describe("AgencyConfigSchema", () => {
     it("should accept an empty config", () => {
         const result = AgencyConfigSchema.safeParse({});
@@ -79,6 +82,16 @@ describe("AgencyConfig maxCallDepth key", () => {
         expect(AgencyConfigSchema.safeParse({ maxCallDepth: 12.5 }).success).toBe(false);
     });
 });
+describe("AgencyConfig maxToolCallRounds key", () => {
+    it("accepts a positive integer", () => {
+        expect(AgencyConfigSchema.safeParse({ maxToolCallRounds: 20 }).success).toBe(true);
+    });
+    it("rejects 0, negative, and non-integer (0 would silently mean 10 via `|| 10`)", () => {
+        expect(AgencyConfigSchema.safeParse({ maxToolCallRounds: 0 }).success).toBe(false);
+        expect(AgencyConfigSchema.safeParse({ maxToolCallRounds: -1 }).success).toBe(false);
+        expect(AgencyConfigSchema.safeParse({ maxToolCallRounds: 1.5 }).success).toBe(false);
+    });
+});
 describe("AgencyConfig typechecker key", () => {
     it("accepts the new typechecker object", () => {
         const result = AgencyConfigSchema.safeParse({
@@ -102,3 +115,109 @@ describe("AgencyConfig typechecker key", () => {
         expect(result.success).toBe(true);
     });
 });
+describe("loadConfigSafe — removed options are ignored, not rejected", () => {
+    it("loads an agency.json with the removed keys, and a stale wrong-typed key, without error", () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cfg-removed-"));
+        const cfgPath = path.join(dir, "agency.json");
+        fs.writeFileSync(cfgPath, JSON.stringify({
+            excludeNodeTypes: "oops-was-string-array", // stale + wrong type: Zod error before removal, ignored after
+            excludeBuiltinFunctions: ["write"],
+            allowedFetchDomains: ["api.example.com"],
+            disallowedFetchDomains: ["blocked.com"],
+            outDir: "./dist",
+        }));
+        const { config, error } = loadConfigSafe(cfgPath);
+        expect(error).toBeUndefined();
+        expect(config.outDir).toBe("./dist");
+        fs.rmSync(dir, { recursive: true, force: true });
+    });
+});
+describe("applyCliFlags", () => {
+    it("--trace <file> sets trace + traceFile", () => {
+        const out = applyCliFlags({}, { trace: "out.trace" });
+        expect(out.trace).toBe(true);
+        expect(out.traceFile).toBe("out.trace");
+        expect(out.traceDir).toBeUndefined();
+    });
+    it("bare --trace with an input derives <input>.trace (agency run)", () => {
+        const out = applyCliFlags({}, { trace: true }, "prog.agency");
+        expect(out.traceFile).toBe("prog.trace");
+    });
+    it("bare or empty --trace with no input uses traceDir='.' (bundled agent)", () => {
+        expect(applyCliFlags({}, { trace: true }).traceDir).toBe(".");
+        // Empty attached (--trace=) must behave like bare, not set traceFile="".
+        expect(applyCliFlags({}, { trace: "" }).traceDir).toBe(".");
+        expect(applyCliFlags({}, { trace: "" }).traceFile).toBeUndefined();
+    });
+    it("--log-file sets log.logFile and enables observability, preserving log.host", () => {
+        const out = applyCliFlags({ log: { host: "https://h" } }, { logFile: "x" });
+        expect(out.log).toEqual({ host: "https://h", logFile: "x" });
+        expect(out.observability).toBe(true);
+    });
+    it("--strict sets strict AND strictTypes", () => {
+        expect(applyCliFlags({}, { strict: true }).typechecker).toEqual({
+            strict: true,
+            strictTypes: true,
+        });
+    });
+    it("--max-tool-call-rounds sets the top-level maxToolCallRounds", () => {
+        expect(applyCliFlags({}, { maxToolCallRounds: 20 }).maxToolCallRounds).toBe(20);
+    });
+    it("--max-tool-result-chars sets client.maxToolResultChars, preserving other client fields", () => {
+        const out = applyCliFlags({ client: { defaultModel: "gpt" } }, { maxToolResultChars: 50000 });
+        expect(out.client).toEqual({ defaultModel: "gpt", maxToolResultChars: 50000 });
+    });
+    it("keeps maxToolResultChars=0 (0 disables the cap, not falsy-skipped)", () => {
+        expect(applyCliFlags({}, { maxToolResultChars: 0 }).client?.maxToolResultChars).toBe(0);
+    });
+    it("does not mutate the input config", () => {
+        const input = {};
+        applyCliFlags(input, { strict: true, logFile: "x", trace: "t", maxToolCallRounds: 5 });
+        expect(input).toEqual({});
+    });
+});
+describe("config overrides env round-trip", () => {
+    it("serialize → read yields the same Partial<AgencyConfig>", () => {
+        const overrides = { trace: true, traceDir: ".", observability: true, log: { logFile: "l.jsonl" } };
+        const env = { [CONFIG_OVERRIDES_ENV]: serializeConfigOverrides(overrides) };
+        expect(readConfigOverrides(env)).toEqual(overrides);
+    });
+    it("returns {} for an absent value without warning", () => {
+        const spy = vi.spyOn(console, "error").mockImplementation(() => { });
+        expect(readConfigOverrides({})).toEqual({});
+        expect(spy).not.toHaveBeenCalled();
+        spy.mockRestore();
+    });
+    it("returns {} and warns (never throws) for unparseable JSON", () => {
+        const spy = vi.spyOn(console, "error").mockImplementation(() => { });
+        expect(readConfigOverrides({ [CONFIG_OVERRIDES_ENV]: "not json" })).toEqual({});
+        expect(spy).toHaveBeenCalledWith(expect.stringContaining("unparseable"));
+        spy.mockRestore();
+    });
+    it("returns {} and warns for a schema-violating field", () => {
+        const spy = vi.spyOn(console, "error").mockImplementation(() => { });
+        expect(readConfigOverrides({ [CONFIG_OVERRIDES_ENV]: '{"maxCallDepth":-1}' })).toEqual({});
+        expect(spy).toHaveBeenCalledWith(expect.stringContaining("invalid"));
+        spy.mockRestore();
+    });
+});
+describe("redactConfigSecrets", () => {
+    it("masks log.apiKey and client.apiKey.* while keeping other fields", () => {
+        const redacted = redactConfigSecrets({
+            outDir: "./dist",
+            log: { host: "https://h", apiKey: "sk-secret-1234" },
+            client: { defaultModel: "gpt", apiKey: { openAi: "sk-openai-abcd", anthropic: "x" } },
+        });
+        expect(redacted.outDir).toBe("./dist");
+        expect(redacted.log?.host).toBe("https://h");
+        expect(redacted.log?.apiKey).toBe("•••1234");
+        expect(redacted.client?.apiKey?.openAi).toBe("•••abcd");
+        expect(redacted.client?.apiKey?.anthropic).toBe("•••"); // <=4 chars fully masked
+        expect(redacted.client?.defaultModel).toBe("gpt");
+    });
+    it("does not mutate the input", () => {
+        const input = { log: { apiKey: "sk-secret-1234" } };
+        redactConfigSecrets(input);
+        expect(input.log.apiKey).toBe("sk-secret-1234");
+    });
+});

package/dist/lib/ir/prettyPrint.js

@@ -326,8 +326,16 @@ export function printTs(node, indent = 0) {
             // Always pass an opts object so Runner.thread has a single,
             // uniform signature: legacy callers see `{}` and the
             // hook-firing path can treat opts as required.
-            const optsArg = optsParts.length === 0 ? "{}" : `{ ${optsParts.join(", ")} }`;
-            return `await runner.thread(${node.id}, "${node.method}", ${optsArg}, async (runner) => {\n${body}\n${ind(indent)}});`;
+            //
+            // The opts object is emitted as a thunk (`async () => (<opts>)`) so its
+            // value expressions (`label`, `session`, ...) are evaluated inside
+            // `runner.thread`, AFTER its halt/skip guards. An early `return` earlier
+            // in the function halts the runner and skips the steps that assign the
+            // locals those expressions reference; evaluating them eagerly here would
+            // then dereference an unset local and throw. Deferring lets the early
+            // return win — same fix as `runnerLoop`.
+            const optsObj = optsParts.length === 0 ? "{}" : `{ ${optsParts.join(", ")} }`;
+            return `await runner.thread(${node.id}, "${node.method}", async () => (${optsObj}), async (runner) => {\n${body}\n${ind(indent)}});`;
         }
         case "runnerHandle": {
             const handler = printTs(node.handler, indent);
@@ -392,10 +400,23 @@ export function printTs(node, indent = 0) {
             return `runner.exitMatch(${node.matchId}, ${value});\nreturn;`;
         }
         case "runnerLoop": {
-            const items = printTs(node.items, indent);
+            // The iterable is emitted as a thunk (`async () => (<expr>)`) so its
+            // expression is evaluated inside `runner.loop`, AFTER the halt/skip
+            // guards. An early `return` earlier in the function halts the runner and
+            // skips the steps that assign the iterable's backing locals; evaluating
+            // the iterable eagerly here would then dereference an unset local and
+            // throw. Deferring it lets the early return win. Mirrors how
+            // `runnerWhileLoop` wraps its condition.
+            //
+            // The expression MUST be parenthesized: a bare `async () => ${items}`
+            // breaks when the iterable prints as an object literal (record
+            // iteration over a literal, e.g. `for (k in { a: 1 })`) — `async () => {
+            // a: 1 }` parses as a function BODY block, not an object. The parens
+            // force expression context. (Same reason `runnerThread` wraps its opts.)
+            const items = printTs(node.items, indent + 1);
             const idxVar = node.indexVar ?? "_";
             const body = node.body.map((n) => printTs(n, indent + 1)).join("\n");
-            return `await runner.loop(${node.id}, ${items}, async (${node.itemVar}, ${idxVar}, runner) => {\n${body}\n${ind(indent)}});`;
+            return `await runner.loop(${node.id}, async () => (${items}), async (${node.itemVar}, ${idxVar}, runner) => {\n${body}\n${ind(indent)}});`;
         }
         case "runnerWhileLoop": {
             const cond = printTs(node.condition, indent + 1);

package/dist/lib/parseCache.js

@@ -27,23 +27,18 @@ export function parseAgencyFileCached(absPath, config = {}, applyTemplate = !isN
             rest: "",
         };
     }
-    const bypass = !!config.tarsecTraceHost;
     const key = `${applyTemplate ? "t" : "r"}:${absPath}`;
-    if (!bypass) {
-        const entry = cache[key];
-        if (entry && entry.mtimeMs === stat.mtimeMs && entry.size === stat.size) {
-            stats.hits++;
-            return {
-                success: true,
-                result: structuredClone(entry.program),
-                rest: "",
-            };
-        }
+    const entry = cache[key];
+    if (entry && entry.mtimeMs === stat.mtimeMs && entry.size === stat.size) {
+        stats.hits++;
+        return {
+            success: true,
+            result: structuredClone(entry.program),
+            rest: "",
+        };
     }
     const contents = fs.readFileSync(absPath, "utf-8");
     const result = parseAgency(contents, config, applyTemplate);
-    if (bypass)
-        return result;
     stats.misses++;
     if (result.success) {
         cache[key] = {