agency-lang 0.19.3 → 0.20.0

package/dist/lib/agentTarget.d.ts

@@ -3,6 +3,9 @@
  * entry point: `path`, `path:node`, or a directory (meaning its main.agency).
  * Consumed by the eval commands, the optimizer, and `agency test`.
  */
+/** Split `path:node` on its last colon, but only when the text after it is a
+ *  node name, so a path with a colon in it (`C:\agents\a.agency`) stays whole.
+ *  `nodeName` is "" when the target names no node. */
 export declare function parseTarget(target: string): {
     filename: string;
     nodeName: string;

package/dist/lib/agentTarget.js

@@ -2,19 +2,22 @@ import * as fs from "fs";
 import * as path from "path";
 import { MISSING_INPUT_PLACEHOLDER_ERROR, INPUT_PLACEHOLDER, OLD_TASK_PLACEHOLDER, OLD_TASK_PLACEHOLDER_ERROR, tokenizeCommand, } from "./eval/run/commandLine.js";
 import { parseAgency } from "./parser.js";
+import { LEGAL_IDENTIFIER } from "./parsers/parsers.js";
 /**
  * How an agent target string is parsed and resolved. A target names an agent
  * entry point: `path`, `path:node`, or a directory (meaning its main.agency).
  * Consumed by the eval commands, the optimizer, and `agency test`.
  */
+/** Split `path:node` on its last colon, but only when the text after it is a
+ *  node name, so a path with a colon in it (`C:\agents\a.agency`) stays whole.
+ *  `nodeName` is "" when the target names no node. */
 export function parseTarget(target) {
     const colonIndex = target.lastIndexOf(":");
-    if (colonIndex === -1) {
+    const nodeName = colonIndex === -1 ? "" : target.slice(colonIndex + 1);
+    if (!LEGAL_IDENTIFIER.test(nodeName)) {
         return { filename: target, nodeName: "" };
     }
-    const filename = target.slice(0, colonIndex);
-    const nodeName = target.slice(colonIndex + 1);
-    return { filename, nodeName };
+    return { filename: target.slice(0, colonIndex), nodeName };
 }
 /** Resolve a target into the agent file, node (default "main"), and the
  *  display label run results carry. */

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

@@ -185,7 +185,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/agency-agent/agent.agency", "999bad9373c6463c93b8af1dd3b5296e396908808edf7c699b0b7bfae769c2d5", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/agency-agent/agent.agency", "477c53c4122d493535511b176cc23dae7217561c563807d499143e18d4fa8547", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -1676,7 +1676,14 @@ if (__process.argv[1] === fileURLToPath(import.meta.url)) {
       data: {}
     };
     const __result = await runCliEntry({
-      runMain: () => main(initialState),
+      nodeNames: ["main"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
       resume: __resumeFromCheckpoint
     });
     await resolveCliInterrupts(__result, respondToInterrupts);

package/dist/lib/agents/agency-agent/brains/coordinator/prompts/codeSample.js

@@ -154,7 +154,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/agency-agent/brains/coordinator/prompts/codeSample.agency", "b6542c14a6ea0e41a06b5887656726eb1e101b01cf6326b68bcac6e174b0fb03", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/agency-agent/brains/coordinator/prompts/codeSample.agency", "54ac8e91969c7a431868443b870aa391a653a3d47c4d9330f0664006f13dd789", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -818,7 +818,14 @@ if (__process.argv[1] === fileURLToPath(import.meta.url)) {
       data: {}
     };
     const __result = await runCliEntry({
-      runMain: () => main(initialState),
+      nodeNames: ["main", "categorize", "scrapeRecipe", "createIngredients", "createMeals"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
       resume: __resumeFromCheckpoint
     });
     await resolveCliInterrupts(__result, respondToInterrupts);

package/dist/lib/agents/eval/goalJudge.js

@@ -150,7 +150,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/eval/goalJudge.agency", "4219fc3a089489bb68c8cf08fd2dcb81aeba5dfdef1d0961b42571fa13298776", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/eval/goalJudge.agency", "07ab1b0abd5c51e9ea1ae92777c7996a6534377c20ffb6bff823655241a30312", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -342,7 +342,14 @@ if (__process.argv[1] === fileURLToPath(import.meta.url)) {
       data: {}
     };
     const __result = await runCliEntry({
-      runMain: () => main(void 0, void 0, void 0, initialState),
+      nodeNames: ["main"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
       resume: __resumeFromCheckpoint
     });
     await resolveCliInterrupts(__result, respondToInterrupts);

package/dist/lib/agents/eval/judge.js

@@ -7,6 +7,7 @@ import { nanoid } from "agency-lang";
 import path from "path";
 import {
   RuntimeContext,
+  ThreadStore,
   Runner,
   setupNode,
   claimFrameForScope,
@@ -20,6 +21,8 @@ import {
   interrupt,
   isInterrupt,
   hasInterrupts,
+  resolveCliInterrupts,
+  reportBudgetExceededAndExit,
   isDebugger,
   isPaused,
   respondToInterrupts as _respondToInterrupts,
@@ -43,7 +46,8 @@ import {
   functionRefReviver as __functionRefReviver,
   DeterministicClient as __DeterministicClient,
   installFetchMock as __installFetchMock,
-  createLogger as __createLogger
+  createLogger as __createLogger,
+  runCliEntry
 } from "agency-lang/runtime";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -146,7 +150,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/eval/judge.agency", "a137ed1282e91493d391244bd661564878330b974336562c484b26ce135b687b", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/eval/judge.agency", "a32d8be051f27940441bda4ec03be6fcea27f03f790674e257c13d11a4ddd2ae", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -322,6 +326,31 @@ async function judge(actualOutput, expectedOutput, judgePrompt, { messages: __in
   });
 }
 const __judgeNodeParams = ["actualOutput", "expectedOutput", "judgePrompt"];
+if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const initialState = {
+      messages: new ThreadStore(),
+      data: {}
+    };
+    const __result = await runCliEntry({
+      nodeNames: ["judge"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
+      resume: __resumeFromCheckpoint
+    });
+    await resolveCliInterrupts(__result, respondToInterrupts);
+  } catch (__error) {
+    reportBudgetExceededAndExit(__error);
+    console.error(`
+Agent crashed: ${__error.message}`);
+    throw __error;
+  }
+}
 var stdin_default = graph;
 const __sourceMap = { "dist/lib/agents/eval/judge.agency:judge": { "1": { "line": 8, "col": 2 }, "2": { "line": 18, "col": 2 } } };
 export {

package/dist/lib/agents/eval/judgePairwise.js

@@ -7,6 +7,7 @@ import { nanoid } from "agency-lang";
 import path from "path";
 import {
   RuntimeContext,
+  ThreadStore,
   Runner,
   setupNode,
   claimFrameForScope,
@@ -20,6 +21,8 @@ import {
   interrupt,
   isInterrupt,
   hasInterrupts,
+  resolveCliInterrupts,
+  reportBudgetExceededAndExit,
   isDebugger,
   isPaused,
   respondToInterrupts as _respondToInterrupts,
@@ -43,7 +46,8 @@ import {
   functionRefReviver as __functionRefReviver,
   DeterministicClient as __DeterministicClient,
   installFetchMock as __installFetchMock,
-  createLogger as __createLogger
+  createLogger as __createLogger,
+  runCliEntry
 } from "agency-lang/runtime";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -146,7 +150,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/eval/judgePairwise.agency", "7a6ddc2bfc878cf2a5ff5233f8a461c4b9c62af9eebaea8968637ca377742350", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/eval/judgePairwise.agency", "86e1cfb0ee10433bc937c8caf288f1212ca5e9d0018aafec3d2853aa43af6d69", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -342,6 +346,31 @@ async function judgePairwise(goal, responseA, responseB, { messages: __invocatio
   });
 }
 const __judgePairwiseNodeParams = ["goal", "responseA", "responseB"];
+if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const initialState = {
+      messages: new ThreadStore(),
+      data: {}
+    };
+    const __result = await runCliEntry({
+      nodeNames: ["judgePairwise"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
+      resume: __resumeFromCheckpoint
+    });
+    await resolveCliInterrupts(__result, respondToInterrupts);
+  } catch (__error) {
+    reportBudgetExceededAndExit(__error);
+    console.error(`
+Agent crashed: ${__error.message}`);
+    throw __error;
+  }
+}
 var stdin_default = graph;
 const __sourceMap = { "dist/lib/agents/eval/judgePairwise.agency:judgePairwise": { "1": { "line": 11, "col": 2 }, "2": { "line": 37, "col": 2 }, "3": { "line": 39, "col": 2 } } };
 export {

package/dist/lib/agents/eval/rubricJudge.js

@@ -150,7 +150,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/eval/rubricJudge.agency", "15f077f083f41b3bee11dbe69f7b41b1a7aaae4bd0440731472e84246cbe770f", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/eval/rubricJudge.agency", "da6496cbfe73c0aebf577575b504bc9fb4d694e27512dbe202467b7ac8cc8ec2", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -346,7 +346,14 @@ if (__process.argv[1] === fileURLToPath(import.meta.url)) {
       data: {}
     };
     const __result = await runCliEntry({
-      runMain: () => main(void 0, void 0, void 0, initialState),
+      nodeNames: ["main"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
       resume: __resumeFromCheckpoint
     });
     await resolveCliInterrupts(__result, respondToInterrupts);

package/dist/lib/agents/optimize/gepaReflect.js

@@ -7,6 +7,7 @@ import { nanoid } from "agency-lang";
 import path from "path";
 import {
   RuntimeContext,
+  ThreadStore,
   Runner,
   setupNode,
   claimFrameForScope,
@@ -20,6 +21,8 @@ import {
   interrupt,
   isInterrupt,
   hasInterrupts,
+  resolveCliInterrupts,
+  reportBudgetExceededAndExit,
   isDebugger,
   isPaused,
   respondToInterrupts as _respondToInterrupts,
@@ -43,7 +46,8 @@ import {
   functionRefReviver as __functionRefReviver,
   DeterministicClient as __DeterministicClient,
   installFetchMock as __installFetchMock,
-  createLogger as __createLogger
+  createLogger as __createLogger,
+  runCliEntry
 } from "agency-lang/runtime";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -146,7 +150,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/optimize/gepaReflect.agency", "03d74acb529c3bff2e2fc8382e731aa316d5f618495c93d9bda9cac964abe687", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/optimize/gepaReflect.agency", "fe03cc0db80dc505434026e7434bad81f7ea754ee429b89717121d0f78a57130", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -361,6 +365,31 @@ async function gepaReflect(targets, goals, feedback, history, { messages: __invo
   });
 }
 const __gepaReflectNodeParams = ["targets", "goals", "feedback", "history"];
+if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const initialState = {
+      messages: new ThreadStore(),
+      data: {}
+    };
+    const __result = await runCliEntry({
+      nodeNames: ["gepaReflect"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
+      resume: __resumeFromCheckpoint
+    });
+    await resolveCliInterrupts(__result, respondToInterrupts);
+  } catch (__error) {
+    reportBudgetExceededAndExit(__error);
+    console.error(`
+Agent crashed: ${__error.message}`);
+    throw __error;
+  }
+}
 var stdin_default = graph;
 const __sourceMap = { "dist/lib/agents/optimize/gepaReflect.agency:gepaReflect": { "1": { "line": 19, "col": 2 }, "2": { "line": 61, "col": 2 }, "3": { "line": 62, "col": 2 } } };
 export {

package/dist/lib/agents/optimize/mutatePrompt.js

@@ -7,6 +7,7 @@ import { nanoid } from "agency-lang";
 import path from "path";
 import {
   RuntimeContext,
+  ThreadStore,
   Runner,
   setupNode,
   claimFrameForScope,
@@ -20,6 +21,8 @@ import {
   interrupt,
   isInterrupt,
   hasInterrupts,
+  resolveCliInterrupts,
+  reportBudgetExceededAndExit,
   isDebugger,
   isPaused,
   respondToInterrupts as _respondToInterrupts,
@@ -43,7 +46,8 @@ import {
   functionRefReviver as __functionRefReviver,
   DeterministicClient as __DeterministicClient,
   installFetchMock as __installFetchMock,
-  createLogger as __createLogger
+  createLogger as __createLogger,
+  runCliEntry
 } from "agency-lang/runtime";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -146,7 +150,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/optimize/mutatePrompt.agency", "73a91138ec4e25f3bb79b9a1843675dcd5a3790f2c2c95512d0377a8e9829517", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/optimize/mutatePrompt.agency", "aafb22db4a7e374680c56907854744b8adb41c32478291d5f684ea2aa5392b38", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -344,6 +348,31 @@ async function mutatePrompt(targets, goals, feedback, history, diagnostics = ``,
   });
 }
 const __mutatePromptNodeParams = ["targets", "goals", "feedback", "history", "diagnostics"];
+if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    const initialState = {
+      messages: new ThreadStore(),
+      data: {}
+    };
+    const __result = await runCliEntry({
+      nodeNames: ["mutatePrompt"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
+      resume: __resumeFromCheckpoint
+    });
+    await resolveCliInterrupts(__result, respondToInterrupts);
+  } catch (__error) {
+    reportBudgetExceededAndExit(__error);
+    console.error(`
+Agent crashed: ${__error.message}`);
+    throw __error;
+  }
+}
 var stdin_default = graph;
 const __sourceMap = { "dist/lib/agents/optimize/mutatePrompt.agency:mutatePrompt": { "1": { "line": 20, "col": 2 }, "2": { "line": 43, "col": 2 }, "3": { "line": 44, "col": 2 } } };
 export {

package/dist/lib/agents/policy/agent.js

@@ -172,7 +172,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/policy/agent.agency", "06bda8a109c760046eb71a1c6493a5f5b7a6538dacde97e92385a9371369d077", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/policy/agent.agency", "5913a37e61b1c33ab421267741ec0796de8edbb4f3683bbaa484b42d8b78def0", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -2069,7 +2069,14 @@ if (__process.argv[1] === fileURLToPath(import.meta.url)) {
       data: {}
     };
     const __result = await runCliEntry({
-      runMain: () => main(initialState),
+      nodeNames: ["main"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
       resume: __resumeFromCheckpoint
     });
     await resolveCliInterrupts(__result, respondToInterrupts);

package/dist/lib/agents/review/agent.js

@@ -160,7 +160,7 @@ function registerTools(tools) {
     }
   }
 }
-__registerModuleFingerprint("dist/lib/agents/review/agent.agency", "e9761740791d5dccde1e6273fd8d6d7acd55cb1c00146b7234501ece0d13ebe5", import.meta.url);
+__registerModuleFingerprint("dist/lib/agents/review/agent.agency", "d0387b58eb07bdfb06a7b7c1137ec4bad67d91282d9c1396323697ca959fdb7b", import.meta.url);
 __registerTool(print);
 __registerTool(printJSON);
 __registerTool(input);
@@ -837,7 +837,14 @@ if (__process.argv[1] === fileURLToPath(import.meta.url)) {
       data: {}
     };
     const __result = await runCliEntry({
-      runMain: () => main(initialState),
+      nodeNames: ["main", "end"],
+      startNode: (nodeName) => runNode({
+        ctx: __globalCtx,
+        nodeName,
+        data: initialState.data,
+        messages: initialState.messages,
+        initializeGlobals: __initializeGlobals
+      }),
       resume: __resumeFromCheckpoint
     });
     await resolveCliInterrupts(__result, respondToInterrupts);

package/dist/lib/backends/typescriptBuilder.js

@@ -3710,26 +3710,26 @@ export class TypeScriptBuilder {
             }));
             result.push(ts.export(ts.varDecl("const", `__${declaredName(node.nodeName)}NodeParams`, ts.arr(args.map((arg) => ts.str(arg.name))))));
         }
-        if (this.compilationUnit.graphNodes.some((n) => n.nodeName === "main")) {
-            // The direct-run call reserves one slot per declared parameter and puts
-            // initialState after them, in main's hidden OPTIONS argument.
+        if (this.compilationUnit.graphNodes.length > 0) {
+            // The direct-run block starts a node by name through runNode, the same
+            // call every exported node wrapper makes, so `agency run file.agency:node`
+            // can pick any node in this file. runCliEntry starts `main` unless the
+            // CLI names another. The names are this file's own: the graph also holds
+            // every node merged in from imports, which are not entry points.
             //
-            // The reservation is what matters: initialState used to be the FIRST
-            // argument, which was harmless while mains took no parameters (it landed
-            // in the options slot) and wrong once they did (#739) — the state object
-            // arrived as the first parameter's value. `undefined` in each slot keeps
-            // it where it belongs, and JavaScript treats an explicit `undefined` and
-            // an omitted argument alike, so parameter defaults still apply.
-            //
-            // The slots are filled with `undefined` rather than argv because a
-            // program's command line belongs to the program. `agency run` forwards
-            // trailing arguments to the child process, where `std::args` reads them;
-            // the compiler does not read them on the entry node's behalf.
-            const mainParamCount = this.compilationUnit.graphNodes.find((n) => n.nodeName === "main")?.parameters.length ?? 0;
-            const mainCallArgs = [
-                ...Array.from({ length: mainParamCount }, () => ts.id("undefined")),
-                ts.id("initialState"),
-            ];
+            // The node's parameters get no values: a program's command line belongs
+            // to the program. `agency run` forwards trailing arguments to the child
+            // process, where `std::args` reads them.
+            const nodeNames = ts.arr(this.compilationUnit.graphNodes.map((node) => ts.str(declaredName(node.nodeName))));
+            const startNode = ts.arrowFn([{ name: "nodeName", typeAnnotation: "string" }], ts.call(ts.id("runNode"), [
+                ts.obj({
+                    ctx: ts.id("__globalCtx"),
+                    nodeName: ts.id("nodeName"),
+                    data: $(ts.id("initialState")).prop("data").done(),
+                    messages: $(ts.id("initialState")).prop("messages").done(),
+                    initializeGlobals: ts.id("__initializeGlobals"),
+                }),
+            ]));
             result.push(ts.if(ts.binOp($(ts.id("__process")).prop("argv").index(ts.num(1)).done(), "===", ts.call(ts.id("fileURLToPath"), [$(ts.id("import")).prop("meta").prop("url").done()])), ts.statements([
                 ts.tryCatch(ts.statements([
                     ts.varDecl("const", "initialState", ts.obj({
@@ -3738,11 +3738,12 @@ export class TypeScriptBuilder {
                     })),
                     ts.varDecl("const", "__result", ts.await(ts.call(ts.id("runCliEntry"), [
                         ts.obj({
-                            runMain: ts.arrowFn([], ts.call(ts.id("main"), mainCallArgs)),
+                            nodeNames,
+                            startNode,
                             resume: ts.id("__resumeFromCheckpoint"),
                         }),
                     ]))),
-                    // Running `main` directly from the CLI: interrupts that no
+                    // Running a node directly from the CLI: interrupts that no
                     // handler settled have surfaced to the user. resolveCliInterrupts
                     // is that user endpoint — under a run policy it decides each one
                     // (prompting with --interactive, rejecting otherwise) and resumes

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

@@ -10,5 +10,7 @@ export type RootCarriers = {
         maxTime?: string;
     };
     resume?: ResumeCarrier;
+    /** The node to start, from `agency run file.agency:node`. Unset means `main`. */
+    entryNode?: string;
 };
 export declare function withRootCarriers(env: NodeJS.ProcessEnv, carriers: RootCarriers): NodeJS.ProcessEnv;

package/dist/lib/cli/childEnv.js

@@ -1,10 +1,11 @@
 /**
- * The root policy and budget a CLI command carries to the Agency program it
- * spawns, as env vars the runtime reads (`installRunPolicyHandler`,
- * `rootBudget`). Always cleared first: a child's behavior comes from this
- * invocation's flags, never from a parent shell or an outer run.
+ * The root policy, budget, resume request, and entry node a CLI command
+ * carries to the Agency program it spawns, as env vars the runtime reads
+ * (`installRunPolicyHandler`, `rootBudget`, `runCliEntry`). Always cleared
+ * first: a child's behavior comes from this invocation's flags, never from a
+ * parent shell or an outer run.
  */
-import { AGENCY_MAX_COST, AGENCY_MAX_TIME, AGENCY_RUN_POLICY, AGENCY_RUN_POLICY_INTERACTIVE, AGENCY_RUN_POLICY_INTERACTIVE_ON, AGENCY_RESUME_FILE, AGENCY_RESUME_FORCE, AGENCY_RESUME_OVERRIDES, } from "../constants.js";
+import { AGENCY_ENTRY_NODE, AGENCY_MAX_COST, AGENCY_MAX_TIME, AGENCY_RUN_POLICY, AGENCY_RUN_POLICY_INTERACTIVE, AGENCY_RUN_POLICY_INTERACTIVE_ON, AGENCY_RESUME_FILE, AGENCY_RESUME_FORCE, AGENCY_RESUME_OVERRIDES, } from "../constants.js";
 export function withRootCarriers(env, carriers) {
     const out = { ...env };
     delete out[AGENCY_RUN_POLICY];
@@ -14,6 +15,10 @@ export function withRootCarriers(env, carriers) {
     delete out[AGENCY_RESUME_FILE];
     delete out[AGENCY_RESUME_OVERRIDES];
     delete out[AGENCY_RESUME_FORCE];
+    delete out[AGENCY_ENTRY_NODE];
+    if (carriers.entryNode !== undefined) {
+        out[AGENCY_ENTRY_NODE] = carriers.entryNode;
+    }
     if (carriers.policy !== undefined) {
         out[AGENCY_RUN_POLICY] = carriers.policy.policyJson;
         if (carriers.policy.interactive)

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

@@ -67,7 +67,9 @@ capture?: {
     runDir: string;
 }, compileMode?: {
     agencyOnly: boolean;
-}): void;
+}, 
+/** The node to start, from `agency run file.agency:node`. Unset means `main`. */
+entryNode?: string): void;
 /**
  * The config overrides `agency run` hands its child. Inherited overrides are
  * kept (an eval harness hands this process its statelog path the same way),

package/dist/lib/cli/commands.js

@@ -229,7 +229,9 @@ export function run(config, inputFile, outputFile, resume, runPolicy, budget,
 nodeArgs = [], 
 /** `--capture-workdir <dir>`: after the run, write its statelog, code and a
  *  snapshot of the working directory as the run directory `<dir>/<traceId>/`. */
-capture, compileMode = { agencyOnly: false }) {
+capture, compileMode = { agencyOnly: false }, 
+/** The node to start, from `agency run file.agency:node`. Unset means `main`. */
+entryNode) {
     let output;
     if (compileMode.agencyOnly) {
         const compiled = compileAgencyOnly(inputFile);
@@ -253,7 +255,7 @@ capture, compileMode = { agencyOnly: false }) {
     }
     console.log(`Running ${output}...`);
     console.log("---");
-    const env = withRootCarriers(process.env, { policy: runPolicy, budget, resume });
+    const env = withRootCarriers(process.env, { policy: runPolicy, budget, resume, entryNode });
     const captured = capture === undefined ? undefined : prepareCapture(capture.runDir);
     env[CONFIG_OVERRIDES_ENV] = serializeConfigOverrides(runChildOverrides({
         inherited: readConfigOverrides(env),