agency-lang 0.7.0 → 0.7.2

package/dist/lib/parseCache.test.js

@@ -86,15 +86,12 @@ describe("parseAgencyFileCached", () => {
         expect(_internal.stats.hits).toBe(0);
         expect(_internal.stats.misses).toBe(2);
     });
-    test("bypasses the cache entirely when tarsecTraceHost is set", () => {
+    test("a stale tarsecTraceHost key no longer bypasses the cache", () => {
         const file = writeTempAgencyFile(VALID_PROGRAM);
-        const traced = parseAgencyFileCached(file, { tarsecTraceHost: true });
-        expect(traced.success).toBe(true);
-        expect(_internal.stats.hits).toBe(0);
-        expect(_internal.stats.misses).toBe(0);
-        // The traced parse must not have stored an entry either.
-        parseAgencyFileCached(file, {});
-        expect(_internal.stats.hits).toBe(0);
+        parseAgencyFileCached(file, { tarsecTraceHost: "http://x" });
+        parseAgencyFileCached(file, { tarsecTraceHost: "http://x" });
+        // Old code: bypass → hits 0, misses 0 (nothing stored). New code: caches.
+        expect(_internal.stats.hits).toBe(1);
         expect(_internal.stats.misses).toBe(1);
     });
     test("failed parses are not cached", () => {

package/dist/lib/parser.js

@@ -1,5 +1,4 @@
-import { buildLineTable, capture, eof, getErrorMessage, getRightmostFailure, many, map, offsetToPosition, or, resetMemos, seqC, set, setInputStr, setTraceHost, setTraceId, success, TarsecError, trace, } from "tarsec";
-import { nanoid } from "nanoid";
+import { buildLineTable, capture, eof, getErrorMessage, getRightmostFailure, many, map, offsetToPosition, or, resetMemos, seqC, set, setInputStr, success, TarsecError, trace, } from "tarsec";
 import { lowerPatterns, PatternLoweringError } from "./lowering/patternLowering.js";
 import { LoweringError } from "./lowering/loweringError.js";
 import render from "./templates/backends/agency/template.js";
@@ -48,16 +47,10 @@ export function _parseAgency(input, config = {}) {
     // Clear memo caches so loc info derived from `setInputStr` in a previous
     // parse (which may have used a different source) doesn't leak through.
     resetMemos();
-    // CAUTION (parse cache): `tarsecTraceHost` is currently the ONLY config
-    // field the parse path reads, and lib/parseCache.ts relies on that — its
-    // cache key deliberately excludes config (tracing is handled via a full
-    // cache bypass). If you add any config-driven parse behavior here (e.g. a
-    // syntax feature flag), you MUST add that field to the parseCache key, or
-    // the cache will silently serve one config's AST to another.
-    if (config.tarsecTraceHost) {
-        setTraceHost("http://localhost:1465");
-        setTraceId(nanoid());
-    }
+    // NOTE (parse cache): the parse path reads NO field of `config`, so
+    // lib/parseCache.ts can key entries without config. If you ever add
+    // config-driven parse behavior here, you MUST add that field to the
+    // parseCache key, or the cache will serve one config's AST to another.
     const result = agencyParser(normalized);
     if (!result.success) {
         const betterMessage = getErrorMessage();

package/dist/lib/preprocessors/typescriptPreprocessor.d.ts

@@ -85,34 +85,6 @@ export declare class TypescriptPreprocessor {
     protected _insertAwaitPendingCalls(body: AgencyNode[], locationToVars: Record<string, string[]>, currentPath?: number[]): AgencyNode[];
     protected nodeHasBody(node: AgencyNode): node is FunctionDefinition | AgencyNode | IfElse | WhileLoop | MessageThread;
     protected _nodeUsesVariable(node: AgencyNode, varName: string): boolean;
-    /**
-     * Filter out nodes based on excludeNodeTypes config
-     */
-    protected filterExcludedNodeTypes(): void;
-    /**
-     * Recursively filter nodes by type, handling all node structures
-     */
-    protected filterNodesByType(nodes: AgencyNode[], excludeSet: Set<string>): AgencyNode[];
-    /**
-     * Filter out builtin function calls based on excludeBuiltinFunctions config
-     */
-    protected filterExcludedBuiltinFunctions(): void;
-    /**
-     * Recursively filter builtin function calls
-     */
-    protected filterBuiltinFunctionCalls(nodes: AgencyNode[], excludeSet: Set<string>): AgencyNode[];
-    /**
-     * Validate fetch calls against allowed/disallowed domains
-     */
-    protected validateFetchDomains(): void;
-    /**
-     * Validate a single fetch call's domain
-     */
-    protected _validateFetchCall(node: FunctionCall, effectiveAllowed: Set<string> | null, disallowedSet: Set<string>): void;
-    /**
-     * Extract domain from URL string
-     */
-    protected _extractDomain(url: string): string | null;
     /**
      * Validate that no async function calls appear inside loops.
      * Async calls inside loops can't be properly serialized for interrupt

package/dist/lib/preprocessors/typescriptPreprocessor.js

@@ -272,9 +272,6 @@ export class TypescriptPreprocessor {
         injectSchemaArgsInProgram(this.program, this.functionDefinitions, this.importedFunctions);
         this.collectSkills();
         this.addAwaitPendingCalls();
-        this.filterExcludedNodeTypes();
-        this.filterExcludedBuiltinFunctions();
-        this.validateFetchDomains();
         this.validateNoAsyncInLoops();
         this.resolveVariableScopes();
         return this.program;
@@ -729,248 +726,6 @@ export class TypescriptPreprocessor {
         }
         return false;
     }
-    /**
-     * Filter out nodes based on excludeNodeTypes config
-     */
-    filterExcludedNodeTypes() {
-        if (!this.config.excludeNodeTypes ||
-            this.config.excludeNodeTypes.length === 0) {
-            return;
-        }
-        const excludeSet = new Set(this.config.excludeNodeTypes);
-        this.program.nodes = this.filterNodesByType(this.program.nodes, excludeSet);
-    }
-    /**
-     * Recursively filter nodes by type, handling all node structures
-     */
-    filterNodesByType(nodes, excludeSet) {
-        const filteredNodes = [];
-        for (const node of nodes) {
-            // Skip nodes of excluded types
-            if (excludeSet.has(node.type)) {
-                continue;
-            }
-            // Recursively filter child nodes
-            if (node.type === "function" || node.type === "graphNode") {
-                node.body = this.filterNodesByType(node.body, excludeSet);
-            }
-            else if (node.type === "ifElse") {
-                node.thenBody = this.filterNodesByType(node.thenBody, excludeSet);
-                if (node.elseBody) {
-                    node.elseBody = this.filterNodesByType(node.elseBody, excludeSet);
-                }
-            }
-            else if (node.type === "whileLoop") {
-                node.body = this.filterNodesByType(node.body, excludeSet);
-            }
-            else if (node.type === "messageThread") {
-                node.body = this.filterNodesByType(node.body, excludeSet);
-            }
-            else if (node.type === "handleBlock") {
-                node.body = this.filterNodesByType(node.body, excludeSet);
-                if (node.handler.kind === "inline") {
-                    node.handler.body = this.filterNodesByType(node.handler.body, excludeSet);
-                }
-            }
-            else if (node.type === "withModifier") {
-                const filtered = this.filterNodesByType([node.statement], excludeSet)[0];
-                if (!filtered)
-                    continue;
-                node.statement = filtered;
-            }
-            else if (node.type === "matchBlock") {
-                // Case bodies are arrays of nodes, but this filter (filterNodesByType)
-                // isn't wired up for match arms yet — mirrors pre-existing behavior.
-            }
-            else if (node.type === "assignment") {
-                node.value = (this.filterNodesByType([node.value], excludeSet)[0] || node.value);
-            }
-            else if (node.type === "functionCall") {
-                node.arguments = this.filterNodesByType(node.arguments, excludeSet);
-            }
-            else if (node.type === "agencyArray") {
-                node.items = this.filterNodesByType(node.items, excludeSet);
-            }
-            else if (node.type === "agencyObject") {
-                node.entries = node.entries.map((entry) => ({
-                    ...entry,
-                    value: (this.filterNodesByType([entry.value], excludeSet)[0] || entry.value),
-                }));
-            }
-            filteredNodes.push(node);
-        }
-        return filteredNodes;
-    }
-    /**
-     * Filter out builtin function calls based on excludeBuiltinFunctions config
-     */
-    filterExcludedBuiltinFunctions() {
-        if (!this.config.excludeBuiltinFunctions ||
-            this.config.excludeBuiltinFunctions.length === 0) {
-            return;
-        }
-        const excludeSet = new Set(this.config.excludeBuiltinFunctions);
-        this.program.nodes = this.filterBuiltinFunctionCalls(this.program.nodes, excludeSet);
-    }
-    /**
-     * Recursively filter builtin function calls
-     */
-    filterBuiltinFunctionCalls(nodes, excludeSet) {
-        const filteredNodes = [];
-        for (const node of nodes) {
-            // Skip excluded builtin function calls
-            if (node.type === "functionCall" && excludeSet.has(node.functionName)) {
-                continue;
-            }
-            // Skip assignments to excluded builtin function calls
-            if (node.type === "assignment" &&
-                node.value.type === "functionCall" &&
-                excludeSet.has(node.value.functionName)) {
-                continue;
-            }
-            // Recursively filter child nodes
-            if (node.type === "function" || node.type === "graphNode") {
-                node.body = this.filterBuiltinFunctionCalls(node.body, excludeSet);
-            }
-            else if (node.type === "ifElse") {
-                node.thenBody = this.filterBuiltinFunctionCalls(node.thenBody, excludeSet);
-                if (node.elseBody) {
-                    node.elseBody = this.filterBuiltinFunctionCalls(node.elseBody, excludeSet);
-                }
-            }
-            else if (node.type === "whileLoop") {
-                node.body = this.filterBuiltinFunctionCalls(node.body, excludeSet);
-            }
-            else if (node.type === "messageThread") {
-                node.body = this.filterBuiltinFunctionCalls(node.body, excludeSet);
-            }
-            else if (node.type === "handleBlock") {
-                node.body = this.filterBuiltinFunctionCalls(node.body, excludeSet);
-                if (node.handler.kind === "inline") {
-                    node.handler.body = this.filterBuiltinFunctionCalls(node.handler.body, excludeSet);
-                }
-            }
-            else if (node.type === "withModifier") {
-                const filtered = this.filterBuiltinFunctionCalls([node.statement], excludeSet)[0];
-                if (!filtered)
-                    continue;
-                node.statement = filtered;
-            }
-            else if (node.type === "matchBlock") {
-                node.cases = node.cases.map((caseItem) => {
-                    if (caseItem.type === "comment") {
-                        return caseItem;
-                    }
-                    if (caseItem.type === "newLine") {
-                        return caseItem;
-                    }
-                    return {
-                        ...caseItem,
-                        body: this.filterBuiltinFunctionCalls(caseItem.body, excludeSet),
-                    };
-                });
-            }
-            else if (node.type === "functionCall") {
-                // Filter arguments that are function calls
-                node.arguments = this.filterBuiltinFunctionCalls(node.arguments, excludeSet);
-            }
-            else if (node.type === "agencyArray") {
-                node.items = this.filterBuiltinFunctionCalls(node.items, excludeSet);
-            }
-            else if (node.type === "agencyObject") {
-                node.entries = node.entries.map((entry) => {
-                    const filteredValues = this.filterBuiltinFunctionCalls([entry.value], excludeSet);
-                    return {
-                        ...entry,
-                        value: filteredValues[0] || entry.value,
-                    };
-                });
-            }
-            filteredNodes.push(node);
-        }
-        return filteredNodes;
-    }
-    /**
-     * Validate fetch calls against allowed/disallowed domains
-     */
-    validateFetchDomains() {
-        const hasAllowed = this.config.allowedFetchDomains &&
-            this.config.allowedFetchDomains.length > 0;
-        const hasDisallowed = this.config.disallowedFetchDomains &&
-            this.config.disallowedFetchDomains.length > 0;
-        if (!hasAllowed && !hasDisallowed) {
-            return; // No domain restrictions
-        }
-        // Compute the effective allowed domains
-        let effectiveAllowed = null;
-        if (hasAllowed) {
-            effectiveAllowed = new Set(this.config.allowedFetchDomains);
-            // If both allowed and disallowed are set, remove disallowed from allowed
-            if (hasDisallowed) {
-                for (const domain of this.config.disallowedFetchDomains) {
-                    effectiveAllowed.delete(domain);
-                }
-            }
-        }
-        const disallowedSet = hasDisallowed
-            ? new Set(this.config.disallowedFetchDomains)
-            : new Set();
-        // Walk through all nodes and validate fetch calls
-        for (const { node } of walkNodesArray(this.program.nodes)) {
-            if (node.type === "functionCall" &&
-                (node.functionName === "fetch" ||
-                    node.functionName === "fetchJSON" ||
-                    node.functionName === "fetchJson")) {
-                this._validateFetchCall(node, effectiveAllowed, disallowedSet);
-            }
-        }
-    }
-    /**
-     * Validate a single fetch call's domain
-     */
-    _validateFetchCall(node, effectiveAllowed, disallowedSet) {
-        // Get the URL argument (first argument to fetch)
-        if (node.arguments.length === 0) {
-            return; // No URL provided, let it fail at runtime
-        }
-        const urlArg = node.arguments[0];
-        let url = null;
-        // Extract URL if it's a string literal
-        if (urlArg.type === "string") {
-            // Reconstruct the URL from segments
-            url = urlArg.segments
-                .map((seg) => (seg.type === "text" ? seg.value : ""))
-                .join("");
-        }
-        if (!url) {
-            return; // Can't validate variable URLs at compile time
-        }
-        // Extract domain from URL
-        const domain = this._extractDomain(url);
-        if (!domain) {
-            return; // Can't extract domain, skip validation
-        }
-        // Check if domain is allowed
-        if (effectiveAllowed !== null && !effectiveAllowed.has(domain)) {
-            throw new Error(`Fetch to domain "${domain}" is not allowed. Allowed domains: ${Array.from(effectiveAllowed).join(", ")}`);
-        }
-        // Check if domain is disallowed
-        if (disallowedSet.has(domain)) {
-            throw new Error(`Fetch to domain "${domain}" is explicitly disallowed.`);
-        }
-    }
-    /**
-     * Extract domain from URL string
-     */
-    _extractDomain(url) {
-        try {
-            const urlObj = new URL(url);
-            return urlObj.hostname;
-        }
-        catch {
-            return null; // Invalid URL
-        }
-    }
     /**
      * Validate that no async function calls appear inside loops.
      * Async calls inside loops can't be properly serialized for interrupt

package/dist/lib/runtime/configOverrides.d.ts

@@ -20,22 +20,23 @@ export type RuntimeContextConstructorArgs = {
 export declare function setRuntimeConfigOverrides(overrides: Partial<AgencyConfig> | undefined): void;
 export declare function getRuntimeConfigOverrides(): Partial<AgencyConfig> | undefined;
 /**
- * Apply runtime config overrides (set per-subprocess via
- * `setRuntimeConfigOverrides`) to the args used to construct a
- * `RuntimeContext`. `log.*` fields and the top-level `observability` flag flow
- * into the statelog config; `client.providerModules` and `maxCallDepth` are
- * forwarded explicitly (see below). Other `AgencyConfig` fields are ignored
- * because the runtime has its own pathways for them. If a new statelog-relevant
- * override field is added, it will be picked up automatically by the shallow
- * merge below.
+ * Apply runtime config overrides — a `Partial<AgencyConfig>` — onto the args
+ * used to construct a `RuntimeContext`. This is THE single runtime merge; it
+ * serves two transports:
+ *   • subprocess IPC: the parent forwards `configOverrides` in the spawn
+ *     message (`setRuntimeConfigOverrides` sets the active value).
+ *   • bundled agents / packed bundles: `AGENCY_CONFIG_OVERRIDES` in the env
+ *     (`config.ts` `readConfigOverrides`), passed explicitly by the caller.
  *
- * `client.providerModules` is honored: `_run` forwards the parent's
- * (absolutized) provider-module paths here so a subprocess loads the same
- * custom/local providers the parent has, regardless of how the child was
- * compiled. They are merged with any baked-in `providerModules` on `args`;
- * `loadProviderModules` de-duplicates by resolved path at load time.
- *
- * `maxCallDepth` is honored so a subprocess inherits the parent's runaway-
- * recursion ceiling rather than falling back to the default.
+ * Fields honored (others are ignored — the runtime has its own pathways):
+ *   • `log.*` + `observability` → statelogConfig
+ *   • `traceFile` / `traceDir` → traceConfig (the `trace` boolean is only a
+ *     marker set alongside them by applyCliFlags; the file/dir drive output).
+ *     An override always wins over the baked traceConfig: a supplied `traceDir`
+ *     clears any baked `traceFile` (which `resolveTraceFilePath` would otherwise
+ *     prefer), so a per-run `--trace` dir actually takes effect.
+ *   • `client.providerModules` → merged with baked modules (subprocess loads
+ *     the same custom/local providers; de-duped at load time).
+ *   • `maxCallDepth` → inherit the parent's runaway-recursion ceiling.
  */
 export declare function applyRuntimeConfigOverridesToContextArgs(args: RuntimeContextConstructorArgs, overrides?: Partial<AgencyConfig> | undefined): RuntimeContextConstructorArgs;

package/dist/lib/runtime/configOverrides.js

@@ -6,23 +6,24 @@ export function getRuntimeConfigOverrides() {
     return activeRuntimeConfigOverrides;
 }
 /**
- * Apply runtime config overrides (set per-subprocess via
- * `setRuntimeConfigOverrides`) to the args used to construct a
- * `RuntimeContext`. `log.*` fields and the top-level `observability` flag flow
- * into the statelog config; `client.providerModules` and `maxCallDepth` are
- * forwarded explicitly (see below). Other `AgencyConfig` fields are ignored
- * because the runtime has its own pathways for them. If a new statelog-relevant
- * override field is added, it will be picked up automatically by the shallow
- * merge below.
+ * Apply runtime config overrides — a `Partial<AgencyConfig>` — onto the args
+ * used to construct a `RuntimeContext`. This is THE single runtime merge; it
+ * serves two transports:
+ *   • subprocess IPC: the parent forwards `configOverrides` in the spawn
+ *     message (`setRuntimeConfigOverrides` sets the active value).
+ *   • bundled agents / packed bundles: `AGENCY_CONFIG_OVERRIDES` in the env
+ *     (`config.ts` `readConfigOverrides`), passed explicitly by the caller.
  *
- * `client.providerModules` is honored: `_run` forwards the parent's
- * (absolutized) provider-module paths here so a subprocess loads the same
- * custom/local providers the parent has, regardless of how the child was
- * compiled. They are merged with any baked-in `providerModules` on `args`;
- * `loadProviderModules` de-duplicates by resolved path at load time.
- *
- * `maxCallDepth` is honored so a subprocess inherits the parent's runaway-
- * recursion ceiling rather than falling back to the default.
+ * Fields honored (others are ignored — the runtime has its own pathways):
+ *   • `log.*` + `observability` → statelogConfig
+ *   • `traceFile` / `traceDir` → traceConfig (the `trace` boolean is only a
+ *     marker set alongside them by applyCliFlags; the file/dir drive output).
+ *     An override always wins over the baked traceConfig: a supplied `traceDir`
+ *     clears any baked `traceFile` (which `resolveTraceFilePath` would otherwise
+ *     prefer), so a per-run `--trace` dir actually takes effect.
+ *   • `client.providerModules` → merged with baked modules (subprocess loads
+ *     the same custom/local providers; de-duped at load time).
+ *   • `maxCallDepth` → inherit the parent's runaway-recursion ceiling.
  */
 export function applyRuntimeConfigOverridesToContextArgs(args, overrides = activeRuntimeConfigOverrides) {
     if (!overrides)
@@ -37,6 +38,16 @@ export function applyRuntimeConfigOverridesToContextArgs(args, overrides = activ
         ...args,
         statelogConfig: { ...args.statelogConfig, ...statelogOverrides },
     };
+    if (overrides.traceFile || overrides.traceDir) {
+        merged.traceConfig = {
+            ...(args.traceConfig ?? {}),
+            // Override wins over baked. An explicit file sets traceFile; a dir-only
+            // override clears any baked traceFile so the dir is honored (see above).
+            ...(overrides.traceFile
+                ? { traceFile: overrides.traceFile }
+                : { traceFile: undefined, traceDir: overrides.traceDir }),
+        };
+    }
     const overrideModules = overrides.client?.providerModules;
     if (overrideModules && overrideModules.length > 0) {
         merged.providerModules = [

package/dist/lib/runtime/configOverrides.test.js

@@ -1,5 +1,8 @@
-import { describe, expect, it } from "vitest";
-import { applyRuntimeConfigOverridesToContextArgs } from "./configOverrides.js";
+import { afterEach, describe, expect, it } from "vitest";
+import { applyRuntimeConfigOverridesToContextArgs, setRuntimeConfigOverrides, } from "./configOverrides.js";
+import { CONFIG_OVERRIDES_ENV, serializeConfigOverrides, } from "../config.js";
+import { RuntimeContext } from "./state/context.js";
+import { agentConfigOverride } from "../cli/runBundledAgent.js";
 describe("runtime config overrides", () => {
     it("applies eval run statelog overrides without replacing existing fields", () => {
         const result = applyRuntimeConfigOverridesToContextArgs({
@@ -57,3 +60,114 @@ describe("runtime config overrides", () => {
         expect(result.providerModules).toEqual(["/baked/a.mjs"]);
     });
 });
+describe("applyRuntimeConfigOverridesToContextArgs — trace overrides", () => {
+    const baseArgs = () => ({
+        statelogConfig: {
+            host: "https://kept",
+            apiKey: "",
+            projectId: "",
+            debugMode: true,
+            observability: false,
+        },
+        smoltalkDefaults: {},
+        dirname: "/project",
+        traceConfig: { program: "agent" },
+    });
+    it("folds an override traceFile and preserves traceConfig.program", () => {
+        const r = applyRuntimeConfigOverridesToContextArgs(baseArgs(), {
+            trace: true,
+            traceFile: "/t.agencytrace",
+        });
+        expect(r.traceConfig?.traceFile).toBe("/t.agencytrace");
+        expect(r.traceConfig?.program).toBe("agent");
+    });
+    it("folds an override traceDir", () => {
+        const r = applyRuntimeConfigOverridesToContextArgs(baseArgs(), {
+            trace: true,
+            traceDir: "/traces",
+        });
+        expect(r.traceConfig?.traceDir).toBe("/traces");
+    });
+    it("an override traceDir clears a baked traceFile so the dir takes effect", () => {
+        const baked = { ...baseArgs(), traceConfig: { program: "agent", traceFile: "baked.trace" } };
+        const r = applyRuntimeConfigOverridesToContextArgs(baked, {
+            trace: true,
+            traceDir: "/x",
+        });
+        expect(r.traceConfig?.traceFile).toBeUndefined();
+        expect(r.traceConfig?.traceDir).toBe("/x");
+    });
+    it("applies trace + statelog overrides together, keeping statelog siblings", () => {
+        const r = applyRuntimeConfigOverridesToContextArgs(baseArgs(), {
+            trace: true,
+            traceFile: "/t",
+            observability: true,
+            log: { logFile: "/l" },
+        });
+        expect(r.traceConfig?.traceFile).toBe("/t");
+        expect(r.statelogConfig.logFile).toBe("/l");
+        expect(r.statelogConfig.observability).toBe(true);
+        expect(r.statelogConfig.host).toBe("https://kept");
+    });
+    it("is a no-op when overrides are empty/undefined", () => {
+        expect(applyRuntimeConfigOverridesToContextArgs(baseArgs(), {}).traceConfig?.traceFile).toBeUndefined();
+        expect(applyRuntimeConfigOverridesToContextArgs(baseArgs(), undefined).traceConfig?.program).toBe("agent");
+    });
+});
+describe("RuntimeContext honors AGENCY_CONFIG_OVERRIDES at construction", () => {
+    const saved = { ...process.env };
+    afterEach(() => {
+        process.env = { ...saved };
+    });
+    it("reads the env override into statelogConfig", () => {
+        process.env[CONFIG_OVERRIDES_ENV] = serializeConfigOverrides({
+            observability: true,
+            log: { logFile: "/tmp/wired.jsonl" },
+        });
+        const ctx = new RuntimeContext({
+            statelogConfig: { host: "", apiKey: "", projectId: "", debugMode: false, observability: false },
+            smoltalkDefaults: {},
+            dirname: "/project",
+        });
+        const sc = ctx.statelogConfig;
+        expect(sc.logFile).toBe("/tmp/wired.jsonl");
+        expect(sc.observability).toBe(true);
+    });
+    it("still applies the env override when an IPC override is also present (both transports layer)", () => {
+        process.env[CONFIG_OVERRIDES_ENV] = serializeConfigOverrides({
+            observability: true,
+            log: { logFile: "/tmp/tree.jsonl" },
+        });
+        // A subprocess launched with explicit IPC overrides (e.g. an eval run) must
+        // NOT drop out of the env-based statelog tree.
+        setRuntimeConfigOverrides({ maxCallDepth: 7 });
+        try {
+            const ctx = new RuntimeContext({
+                statelogConfig: { host: "", apiKey: "", projectId: "", debugMode: false, observability: false },
+                smoltalkDefaults: {},
+                dirname: "/project",
+            });
+            const sc = ctx.statelogConfig;
+            expect(sc.logFile).toBe("/tmp/tree.jsonl");
+            expect(sc.observability).toBe(true);
+        }
+        finally {
+            setRuntimeConfigOverrides(undefined);
+        }
+    });
+});
+describe("writer→reader override contract", () => {
+    it("agentConfigOverride output applies cleanly through the runtime merge", () => {
+        const base = {
+            statelogConfig: { host: "", apiKey: "", projectId: "", debugMode: false, observability: false },
+            smoltalkDefaults: {},
+            dirname: "/p",
+            traceConfig: { program: "agent" },
+        };
+        // The exact object runBundledAgent serializes into AGENCY_CONFIG_OVERRIDES.
+        const overrides = agentConfigOverride(["--trace", "t.trace", "--log-file", "l.jsonl"]);
+        const r = applyRuntimeConfigOverridesToContextArgs(base, overrides);
+        expect(r.traceConfig?.traceFile).toBe("t.trace");
+        expect(r.statelogConfig.logFile).toBe("l.jsonl");
+    });
+});

package/dist/lib/runtime/prompt.js

@@ -536,7 +536,11 @@ export async function runPrompt(args) {
     // `smoltalkDefaults` and the per-call options, so precedence is
     // baked agency.json < stack defaults < per-call `llm({...})`.
     const stackDefaults = stateStack?.other?.llmDefaults ?? {};
-    const { maxToolResultChars: stackMaxToolResultChars, ...stackSmolDefaults } = stackDefaults;
+    const { maxToolResultChars: stackMaxToolResultChars, maxToolCallRounds: stackMaxToolCallRounds, ...stackSmolDefaults } = stackDefaults;
+    // maxToolCallRounds precedence: a branch default (setLlmOptions) overrides the
+    // baked per-call value (agency.json → codegen literal, default 10). Kept out
+    // of stackSmolDefaults above — it isn't a smoltalk config field.
+    const effectiveMaxToolCallRounds = stackMaxToolCallRounds ?? maxToolCallRounds;
     const clientConfig = ctx.getSmoltalkConfig({
         ...stackSmolDefaults,
         ...restClientConfig,
@@ -882,9 +886,9 @@ export async function runPrompt(args) {
                     });
                     return;
                 }
-                if (self.toolCallRound >= maxToolCallRounds) {
+                if (self.toolCallRound >= effectiveMaxToolCallRounds) {
                     await b.step(`round.${round}.tool.${callSlug}.tooManyRounds`, async () => {
-                        messages.push(smoltalk.toolMessage(`Error: Maximum number of tool call rounds (${maxToolCallRounds}) exceeded. This tool call will not be executed.`, { tool_call_id: toolCall.id, name: toolCall.name }));
+                        messages.push(smoltalk.toolMessage(`Error: Maximum number of tool call rounds (${effectiveMaxToolCallRounds}) exceeded. This tool call will not be executed.`, { tool_call_id: toolCall.id, name: toolCall.name }));
                     });
                     return;
                 }

package/dist/lib/runtime/runner.d.ts

@@ -205,7 +205,7 @@ export declare class Runner {
     hook(id: number, bodyFn: () => Promise<void>): Promise<void>;
     debugger(id: number, label: string): Promise<void>;
     pipe(id: number, input: any, fn: (value: any) => any): Promise<any>;
-    thread(id: number, method: "create" | "createSubthread", opts: ThreadStepOpts, callback: (runner: Runner) => Promise<void>): Promise<void>;
+    thread(id: number, method: "create" | "createSubthread", optsArg: ThreadStepOpts | (() => ThreadStepOpts | Promise<ThreadStepOpts>), callback: (runner: Runner) => Promise<void>): Promise<void>;
     handle(id: number, handlerFn: HandlerFn, callback: (runner: Runner) => Promise<void>): Promise<void>;
     ifElse(id: number, branches: {
         condition: () => boolean | Promise<boolean>;
@@ -213,7 +213,7 @@ export declare class Runner {
     }[], elseBranch?: (runner: Runner) => Promise<void>, opts?: {
         matchId?: number;
     }): Promise<void>;
-    loop(id: number, items: any[] | Record<string, any>, callback: (item: any, second: any, runner: Runner) => Promise<void>): Promise<void>;
+    loop(id: number, items: any[] | Record<string, any> | (() => any[] | Record<string, any> | Promise<any[] | Record<string, any>>), callback: (item: any, second: any, runner: Runner) => Promise<void>): Promise<void>;
     whileLoop(id: number, condition: () => boolean | Promise<boolean>, callback: (runner: Runner) => Promise<void>): Promise<void>;
     branchStep(id: number, branchKey: string, callback: (runner: Runner) => Promise<void>): Promise<void>;
     /**