agency-lang 0.10.0 → 0.12.0

package/dist/lib/agentTarget.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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`.
+ */
+export declare function parseTarget(target: string): {
+    filename: string;
+    nodeName: string;
+};
+/** Resolve a target into the agent file, node (default "main"), and the
+ *  display label run results carry. */
+export declare function resolveEvalRunTarget(target: string): {
+    agentFile: string;
+    node: string;
+    label: string;
+};
+/** What runs as the agent, and what evidence it produces. `file` is the
+ *  classic seeded-and-compiled .agency target; `command` is a CLI run in the
+ *  workdir (Agency CLIs only — the statelog is the evidence contract). A
+ *  future non-Agency variant would be a third kind with a weaker record. */
+export type EvalTarget = {
+    kind: "file";
+    agentFile: string;
+    node: string;
+    label: string;
+} | {
+    kind: "command";
+    tokens: string[];
+    label: string;
+};
+/** Resolve the runner-side agent choice. Exactly one of --agent /
+ *  --agent-cmd; the command's {task} placeholder is validated here, before
+ *  any run. Commands come ONLY from these flags, never from suite content —
+ *  suites can be remote git sources, and a suite that named its own command
+ *  would be remote code execution. */
+export declare function resolveEvalTarget(opts: {
+    agent?: string;
+    agentCmd?: string;
+}): EvalTarget;
+/**
+ * Fail fast when the entry node cannot receive a task: eval delivers the
+ * input's task as the node's single positional parameter, so the node must
+ * take exactly one. The subprocess bootstrap enforces the same rule at run
+ * time (resolveNodeCallArgs), but by then a workdir has been seeded and the
+ * agent compiled — and the optimizer would pay that once per candidate.
+ * A misconfigured agent should cost one error, not a suite of run failures.
+ *
+ * Best-effort: an unreadable or unparseable file, or a node defined
+ * elsewhere than the entry file, is left for compile/run to report with
+ * better errors than a pre-parse could.
+ */
+export declare function assertEvalEntryNodeTakesOneParameter(agentFile: string, node: string): void;

package/dist/lib/agentTarget.js

@@ -0,0 +1,83 @@
+import * as fs from "fs";
+import * as path from "path";
+import { MISSING_TASK_PLACEHOLDER_ERROR, TASK_PLACEHOLDER, tokenizeCommand } from "./eval/run/commandLine.js";
+import { parseAgency } from "./parser.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`.
+ */
+export function parseTarget(target) {
+    const colonIndex = target.lastIndexOf(":");
+    if (colonIndex === -1) {
+        return { filename: target, nodeName: "" };
+    }
+    const filename = target.slice(0, colonIndex);
+    const nodeName = target.slice(colonIndex + 1);
+    return { filename, nodeName };
+}
+/** Resolve a target into the agent file, node (default "main"), and the
+ *  display label run results carry. */
+export function resolveEvalRunTarget(target) {
+    const parsed = parseTarget(target);
+    const resolved = path.resolve(parsed.filename);
+    const agentFile = fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()
+        ? path.join(resolved, "main.agency")
+        : resolved;
+    const node = parsed.nodeName || "main";
+    return { agentFile, node, label: `${agentFile}:${node}` };
+}
+/** Resolve the runner-side agent choice. Exactly one of --agent /
+ *  --agent-cmd; the command's {task} placeholder is validated here, before
+ *  any run. Commands come ONLY from these flags, never from suite content —
+ *  suites can be remote git sources, and a suite that named its own command
+ *  would be remote code execution. */
+export function resolveEvalTarget(opts) {
+    if ((opts.agent ? 1 : 0) + (opts.agentCmd ? 1 : 0) !== 1) {
+        throw new Error("Provide exactly one of --agent or --agent-cmd");
+    }
+    if (opts.agentCmd) {
+        const tokens = tokenizeCommand(opts.agentCmd);
+        if (!tokens.some((t) => t.includes(TASK_PLACEHOLDER))) {
+            throw new Error(MISSING_TASK_PLACEHOLDER_ERROR);
+        }
+        return { kind: "command", tokens, label: opts.agentCmd };
+    }
+    return { kind: "file", ...resolveEvalRunTarget(opts.agent) };
+}
+/**
+ * Fail fast when the entry node cannot receive a task: eval delivers the
+ * input's task as the node's single positional parameter, so the node must
+ * take exactly one. The subprocess bootstrap enforces the same rule at run
+ * time (resolveNodeCallArgs), but by then a workdir has been seeded and the
+ * agent compiled — and the optimizer would pay that once per candidate.
+ * A misconfigured agent should cost one error, not a suite of run failures.
+ *
+ * Best-effort: an unreadable or unparseable file, or a node defined
+ * elsewhere than the entry file, is left for compile/run to report with
+ * better errors than a pre-parse could.
+ */
+export function assertEvalEntryNodeTakesOneParameter(agentFile, node) {
+    let source;
+    try {
+        source = fs.readFileSync(agentFile, "utf-8");
+    }
+    catch {
+        return;
+    }
+    const parsed = parseAgency(source, {}, false);
+    if (!parsed.success)
+        return;
+    for (const candidate of parsed.result.nodes) {
+        if (candidate.type !== "graphNode" || candidate.nodeName !== node)
+            continue;
+        const count = candidate.parameters.length;
+        if (count !== 1) {
+            const detail = count === 0
+                ? `takes none — add one (it may go unused: \`node ${node}(task: string) { ... }\`)`
+                : `takes ${count} (${candidate.parameters.map((p) => p.name).join(", ")}) — add a one-parameter adapter node`;
+            throw new Error(`eval delivers the input's task as the entry node's single parameter, ` +
+                `but node "${node}" in ${agentFile} ${detail}.`);
+        }
+    }
+}

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

@@ -725,7 +725,7 @@ async function __oneShotAgent_impl(target, prompt) {
           __stack.locals.__scrutinee_5 = __stack.locals.result;
         });
         await runner2.step(2, async (runner3) => {
-          __stack.locals.__hoist_0 = await isSuccess(__stack.locals.__scrutinee_5);
+          __stack.locals.__hoist_0 = await isSuccess(__stack.locals.result);
           if (hasInterrupts(__stack.locals.__hoist_0)) {
             await getRuntimeContext().ctx.pendingPromises.awaitAll();
             runner3.halt(__stack.locals.__hoist_0);
@@ -741,7 +741,7 @@ async function __oneShotAgent_impl(target, prompt) {
             condition: async () => __stack.locals.__hoist_0,
             body: async (runner3) => {
               await runner3.step(0, async (runner4) => {
-                __stack.locals.r = __stack.locals.__scrutinee_5.value;
+                __stack.locals.r = __stack.locals.result.value;
               });
               await runner3.step(1, async (runner4) => {
                 __stack.locals.__armval_3 = __stack.locals.r;
@@ -754,7 +754,7 @@ async function __oneShotAgent_impl(target, prompt) {
           }
         ], async (runner3) => {
           await runner3.step(3, async (runner4) => {
-            __stack.locals.__hoist_1 = await isFailure(__stack.locals.__scrutinee_5);
+            __stack.locals.__hoist_1 = await isFailure(__stack.locals.result);
             if (hasInterrupts(__stack.locals.__hoist_1)) {
               await getRuntimeContext().ctx.pendingPromises.awaitAll();
               runner4.halt(__stack.locals.__hoist_1);
@@ -770,7 +770,7 @@ async function __oneShotAgent_impl(target, prompt) {
               condition: async () => __stack.locals.__hoist_1,
               body: async (runner4) => {
                 await runner4.step(0, async (runner5) => {
-                  __stack.locals.f = __stack.locals.__scrutinee_5.error;
+                  __stack.locals.f = __stack.locals.result.error;
                 });
                 await runner4.step(1, async (runner5) => {
                   __stack.locals.__armval_4 = await __call(formatTurnFailure, {
@@ -1588,6 +1588,10 @@ async function main({ messages, callbacks } = {}) {
 }
 const __mainNodeParams = [];
 if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (__process.argv.length > 2) {
+    console.error(`main() takes 0 argument(s) but got ${__process.argv.length - 2}; extra: ${__process.argv.slice(2).join(" ")}`);
+    __process.exit(1);
+  }
   try {
     const initialState = {
       messages: new ThreadStore(),

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

@@ -2038,7 +2038,7 @@ async function __runTurn_impl(agentName, userMsg) {
           __stack.locals.__scrutinee_14 = __stack.locals.result;
         });
         await runner2.step(4, async (runner3) => {
-          __stack.locals.__hoist_2 = await isSuccess(__stack.locals.__scrutinee_14);
+          __stack.locals.__hoist_2 = await isSuccess(__stack.locals.result);
           if (hasInterrupts(__stack.locals.__hoist_2)) {
             await getRuntimeContext().ctx.pendingPromises.awaitAll();
             runner3.halt(__stack.locals.__hoist_2);
@@ -2054,7 +2054,7 @@ async function __runTurn_impl(agentName, userMsg) {
             condition: async () => __stack.locals.__hoist_2,
             body: async (runner3) => {
               await runner3.step(0, async (runner4) => {
-                __stack.locals.reply = __stack.locals.__scrutinee_14.value;
+                __stack.locals.reply = __stack.locals.result.value;
               });
               await runner3.step(1, async (runner4) => {
                 __stack.locals.__armval_13 = __stack.locals.reply;
@@ -2067,7 +2067,7 @@ async function __runTurn_impl(agentName, userMsg) {
           }
         ], async (runner3) => {
           await runner3.step(3, async (runner4) => {
-            __stack.locals.__hoist_3 = await isFailure(__stack.locals.__scrutinee_14);
+            __stack.locals.__hoist_3 = await isFailure(__stack.locals.result);
             if (hasInterrupts(__stack.locals.__hoist_3)) {
               await getRuntimeContext().ctx.pendingPromises.awaitAll();
               runner4.halt(__stack.locals.__hoist_3);
@@ -2083,7 +2083,7 @@ async function __runTurn_impl(agentName, userMsg) {
               condition: async () => __stack.locals.__hoist_3,
               body: async (runner4) => {
                 await runner4.step(0, async (runner5) => {
-                  __stack.locals.f = __stack.locals.__scrutinee_14.error;
+                  __stack.locals.f = __stack.locals.result.error;
                 });
                 await runner4.step(1, async (runner5) => {
                   __stack.locals.dimension = `cost`;

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

@@ -326,7 +326,7 @@ async function __missingProviderEnvVar_impl(provider) {
       });
       await runner.ifElse(4, [
         {
-          condition: async () => !__eq(__stack.locals.baseVar, void 0) && (__eq(await __call(env, {
+          condition: async () => !__eq(__stack.locals.baseVar, null) && (__eq(await __call(env, {
             type: "positional",
             args: [__stack.locals.baseVar]
           }), null) || __eq(await __call(env, {
@@ -948,7 +948,7 @@ async function __resolveDetected_impl(model, fast, slow, provider) {
             });
             await runner2.ifElse(1, [
               {
-                condition: async () => __eq(__nn(__readStatic(MODELS, "MODELS", "dist/lib/agents/agency-agent/lib/models.agency")[__stack.args.provider]), void 0) && (__stack.locals.needFast || __stack.locals.needSlow),
+                condition: async () => __eq(__nn(__readStatic(MODELS, "MODELS", "dist/lib/agents/agency-agent/lib/models.agency")[__stack.args.provider]), null) && (__stack.locals.needFast || __stack.locals.needSlow),
                 body: async (runner3) => {
                   await runner3.step(0, async (runner4) => {
                     __stack.locals.known = await __callMethod(Object, "keys", {

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

@@ -851,7 +851,7 @@ async function __getPolicyForAgent_impl(_policyArg, interactive) {
                 __stack.locals.__scrutinee_7 = __stack.locals.loaded;
               });
               await runner3.step(2, async (runner4) => {
-                __stack.locals.__hoist_6 = await isSuccess(__stack.locals.__scrutinee_7);
+                __stack.locals.__hoist_6 = await isSuccess(__stack.locals.loaded);
                 if (hasInterrupts(__stack.locals.__hoist_6)) {
                   await getRuntimeContext().ctx.pendingPromises.awaitAll();
                   runner4.halt(__stack.locals.__hoist_6);
@@ -867,7 +867,7 @@ async function __getPolicyForAgent_impl(_policyArg, interactive) {
                   condition: async () => __stack.locals.__hoist_6,
                   body: async (runner4) => {
                     await runner4.step(0, async (runner5) => {
-                      __stack.locals._ = __stack.locals.__scrutinee_7.value;
+                      __stack.locals._ = __stack.locals.loaded.value;
                     });
                     await runner4.step(1, async (runner5) => {
                       __stack.locals.__armval_6 = __stack.args._policyArg;
@@ -880,7 +880,7 @@ async function __getPolicyForAgent_impl(_policyArg, interactive) {
                 }
               ], async (runner4) => {
                 await runner4.step(3, async (runner5) => {
-                  __stack.locals.__hoist_7 = await isFailure(__stack.locals.__scrutinee_7);
+                  __stack.locals.__hoist_7 = await isFailure(__stack.locals.loaded);
                   if (hasInterrupts(__stack.locals.__hoist_7)) {
                     await getRuntimeContext().ctx.pendingPromises.awaitAll();
                     runner5.halt(__stack.locals.__hoist_7);
@@ -896,7 +896,7 @@ async function __getPolicyForAgent_impl(_policyArg, interactive) {
                     condition: async () => __stack.locals.__hoist_7,
                     body: async (runner5) => {
                       await runner5.step(0, async (runner6) => {
-                        __stack.locals.f = __stack.locals.__scrutinee_7.error;
+                        __stack.locals.f = __stack.locals.loaded.error;
                       });
                       await runner5.step(1, async (runner6) => {
                         __stack.locals.__hoist_8 = await __call(builtinPolicyNames, {

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

@@ -441,7 +441,7 @@ async function __searchSlashCommand_impl() {
       });
       await runner.ifElse(4, [
         {
-          condition: async () => !__eq(__stack.locals.choice, ``) && !__eq(__stack.locals.choice, null) && !__eq(__stack.locals.choice, void 0),
+          condition: async () => !__eq(__stack.locals.choice, ``) && !__eq(__stack.locals.choice, null) && !__eq(__stack.locals.choice, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               const __funcResult = await __call(setSearchBackend, {

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

@@ -2047,7 +2047,7 @@ async function __appendTool_impl(opts, tool) {
       });
       await runner.ifElse(2, [
         {
-          condition: async () => __eq(__stack.locals.base, null) || __eq(__stack.locals.base, void 0),
+          condition: async () => __eq(__stack.locals.base, null) || __eq(__stack.locals.base, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               __stack.locals.base = [];
@@ -2196,7 +2196,7 @@ async function __withWebSearch_impl(opts) {
       });
       await runner.ifElse(3, [
         {
-          condition: async () => !__eq(__stack.locals.tool, null) && !__eq(__stack.locals.tool, void 0),
+          condition: async () => !__eq(__stack.locals.tool, null) && !__eq(__stack.locals.tool, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               const __funcResult = await __call(appendTool, {
@@ -2221,7 +2221,7 @@ async function __withWebSearch_impl(opts) {
       });
       await runner.ifElse(5, [
         {
-          condition: async () => !__eq(__stack.locals.hosted, null) && !__eq(__stack.locals.hosted, void 0),
+          condition: async () => !__eq(__stack.locals.hosted, null) && !__eq(__stack.locals.hosted, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               __stack.args.opts.hostedTools = __stack.locals.hosted;
@@ -2558,7 +2558,7 @@ async function __configureSearch_impl(isLocal) {
       });
       await runner.ifElse(5, [
         {
-          condition: async () => !__eq(__stack.locals.settings.search, null) && !__eq(__stack.locals.settings.search, void 0),
+          condition: async () => !__eq(__stack.locals.settings.search, null) && !__eq(__stack.locals.settings.search, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               __stack.locals.saved = __stack.locals.settings.search.backend ?? ``;

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

@@ -233,7 +233,7 @@ async function __renderLLMCallResponse_impl(data) {
       });
       await runner.ifElse(2, [
         {
-          condition: async () => !__eq(__stack.args.data.output, ``) && !__eq(__stack.args.data.output, null) && !__eq(__stack.args.data.output, void 0),
+          condition: async () => !__eq(__stack.args.data.output, ``) && !__eq(__stack.args.data.output, null) && !__eq(__stack.args.data.output, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               await __callMethod(__stack.locals.response, "push", {

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

@@ -762,6 +762,10 @@ async function createMeals({ messages, callbacks } = {}) {
 }
 const __createMealsNodeParams = [];
 if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (__process.argv.length > 2) {
+    console.error(`main() takes 0 argument(s) but got ${__process.argv.length - 2}; extra: ${__process.argv.slice(2).join(" ")}`);
+    __process.exit(1);
+  }
   try {
     const initialState = {
       messages: new ThreadStore(),

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

@@ -1912,7 +1912,7 @@ graph.node("tavilyBackendAppendsOneSearchTool", async (__state) => {
         }
       });
       await runner.step(3, async (runner2) => {
-        __stack.locals.hostedSet = !__eq(__stack.locals.opts.hostedTools, null) && !__eq(__stack.locals.opts.hostedTools, void 0);
+        __stack.locals.hostedSet = !__eq(__stack.locals.opts.hostedTools, null) && !__eq(__stack.locals.opts.hostedTools, null);
       });
       await runner.step(4, async (runner2) => {
         __stack.locals.__hoist_0 = await __call(toolCount, {
@@ -2043,7 +2043,7 @@ graph.node("offBackendLeavesOptsUnchanged", async (__state) => {
         }
       });
       await runner.step(3, async (runner2) => {
-        __stack.locals.hostedSet = !__eq(__stack.locals.opts.hostedTools, null) && !__eq(__stack.locals.opts.hostedTools, void 0);
+        __stack.locals.hostedSet = !__eq(__stack.locals.opts.hostedTools, null) && !__eq(__stack.locals.opts.hostedTools, null);
       });
       await runner.step(4, async (runner2) => {
         __stack.locals.__hoist_0 = await __call(toolCount, {

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

@@ -393,7 +393,7 @@ graph.node("missingFileLoadsAsEmpty", async (__state) => {
       });
       await runner.ifElse(4, [
         {
-          condition: async () => __eq(__stack.locals.loaded.search, null) || __eq(__stack.locals.loaded.search, void 0),
+          condition: async () => __eq(__stack.locals.loaded.search, null) || __eq(__stack.locals.loaded.search, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               runner3.halt({
@@ -521,7 +521,7 @@ graph.node("corruptFileLoadsAsEmpty", async (__state) => {
       });
       await runner.ifElse(4, [
         {
-          condition: async () => __eq(__stack.locals.loaded.search, null) || __eq(__stack.locals.loaded.search, void 0),
+          condition: async () => __eq(__stack.locals.loaded.search, null) || __eq(__stack.locals.loaded.search, null),
           body: async (runner2) => {
             await runner2.step(0, async (runner3) => {
               runner3.halt({

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

@@ -194,7 +194,7 @@ graph.node("main", async (__state) => {
   if (!__state.isResume) {
     __stack.args["goal"] = __state.data.goal;
     __stack.args["output"] = __state.data.output;
-    __stack.args["expected"] = __state.data.expected;
+    __stack.args["expected"] = __state.data.expected === void 0 ? `` : __state.data.expected;
   }
   try {
     await agencyStore.run({
@@ -298,7 +298,7 @@ Reserve scores above 0.5 for outputs that a careful human would accept as a corr
     };
   }
 });
-async function main(goal, output, expected, { messages, callbacks } = {}) {
+async function main(goal, output, expected = ``, { messages, callbacks } = {}) {
   return runNode({
     ctx: __globalCtx,
     nodeName: "main",
@@ -314,12 +314,16 @@ async function main(goal, output, expected, { messages, callbacks } = {}) {
 }
 const __mainNodeParams = ["goal", "output", "expected"];
 if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (__process.argv.length > 5) {
+    console.error(`main() takes 3 argument(s) but got ${__process.argv.length - 2}; extra: ${__process.argv.slice(5).join(" ")}`);
+    __process.exit(1);
+  }
   try {
     const initialState = {
       messages: new ThreadStore(),
       data: {}
     };
-    const __result = await main(initialState);
+    const __result = await main(__process.argv[2], __process.argv[3], __process.argv[4], initialState);
     await resolveCliInterrupts(__result, respondToInterrupts);
   } catch (__error) {
     reportBudgetExceededAndExit(__error);

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

@@ -194,7 +194,7 @@ graph.node("mutatePrompt", async (__state) => {
     __stack.args["goals"] = __state.data.goals;
     __stack.args["feedback"] = __state.data.feedback;
     __stack.args["history"] = __state.data.history;
-    __stack.args["diagnostics"] = __state.data.diagnostics;
+    __stack.args["diagnostics"] = __state.data.diagnostics === void 0 ? `` : __state.data.diagnostics;
   }
   try {
     await agencyStore.run({
@@ -306,7 +306,7 @@ graph.node("mutatePrompt", async (__state) => {
     };
   }
 });
-async function mutatePrompt(targets, goals, feedback, history, diagnostics, { messages, callbacks } = {}) {
+async function mutatePrompt(targets, goals, feedback, history, diagnostics = ``, { messages, callbacks } = {}) {
   return runNode({
     ctx: __globalCtx,
     nodeName: "mutatePrompt",

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

@@ -2067,6 +2067,10 @@ async function main({ messages, callbacks } = {}) {
 }
 const __mainNodeParams = [];
 if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (__process.argv.length > 2) {
+    console.error(`main() takes 0 argument(s) but got ${__process.argv.length - 2}; extra: ${__process.argv.slice(2).join(" ")}`);
+    __process.exit(1);
+  }
   try {
     const initialState = {
       messages: new ThreadStore(),

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

@@ -802,6 +802,10 @@ async function end({ messages, callbacks } = {}) {
 }
 const __endNodeParams = [];
 if (__process.argv[1] === fileURLToPath(import.meta.url)) {
+  if (__process.argv.length > 2) {
+    console.error(`main() takes 0 argument(s) but got ${__process.argv.length - 2}; extra: ${__process.argv.slice(2).join(" ")}`);
+    __process.exit(1);
+  }
   try {
     const initialState = {
       messages: new ThreadStore(),

package/dist/lib/analysis/closure.d.ts

@@ -0,0 +1,26 @@
+import type { AgencyProgram } from "../types.js";
+/** One file of an agent's .agency import closure, parsed exactly once.
+ *  Two consumers: seeding reads only `absoluteFile`; the optimizer's target
+ *  discovery reads `source` (content hashes for safe writeback) and
+ *  `program` (finding optimize-marked declarations). */
+export type ParsedSourceFile = {
+    absoluteFile: string;
+    source: string;
+    program: AgencyProgram;
+};
+/** Walk the local .agency import closure of `absoluteEntryFile`, parsing each
+ *  file once. The single parse pass target discovery and seeding both share. */
+export declare function walkAgencyClosure(absoluteEntryFile: string): ParsedSourceFile[];
+/** Absolute base directory a closure's relative paths hang off: the files'
+ *  common ancestor, unless that lies inside the current working directory, in
+ *  which case cwd wins. */
+export declare function closureBaseDir(absoluteFiles: string[]): string;
+/** The entry file's full local closure: every .agency file the walk reaches,
+ *  plus the transitive local TS/JS files their interop imports need. baseDir
+ *  is computed from the .agency files only, so adding TS deps can never
+ *  shift it. */
+export declare function agentClosure(entryFile: string): {
+    baseDir: string;
+    files: string[];
+};
+export declare function agentClosureBaseDir(entryFile: string): string;

package/dist/lib/analysis/closure.js

@@ -0,0 +1,99 @@
+import fs from "fs";
+import path from "path";
+import { buildSync } from "esbuild";
+import { agencyImportTargets, nonAgencyLocalImportTargets, resolveAgencyImportPath } from "../importPaths.js";
+import { parseAgency } from "../parser.js";
+/** Walk the local .agency import closure of `absoluteEntryFile`, parsing each
+ *  file once. The single parse pass target discovery and seeding both share. */
+export function walkAgencyClosure(absoluteEntryFile) {
+    const parsedFiles = [];
+    visitFile(absoluteEntryFile, {}, parsedFiles);
+    return parsedFiles;
+}
+function visitFile(absoluteFile, visited, parsedFiles) {
+    const canonicalFile = fs.realpathSync(absoluteFile);
+    if (visited[canonicalFile])
+        return;
+    visited[canonicalFile] = true;
+    const source = fs.readFileSync(canonicalFile, "utf8");
+    const parseResult = parseAgency(source, {}, false);
+    if (!parseResult.success) {
+        throw new Error(`Failed to parse ${canonicalFile}: ${parseResult.message ?? "parse error"}`);
+    }
+    parsedFiles.push({ absoluteFile: canonicalFile, source, program: parseResult.result });
+    for (const importPath of agencyImportTargets(parseResult.result, { localOnly: true })) {
+        visitFile(resolveAgencyImportPath(importPath, canonicalFile), visited, parsedFiles);
+    }
+}
+/** Absolute base directory a closure's relative paths hang off: the files'
+ *  common ancestor, unless that lies inside the current working directory, in
+ *  which case cwd wins. */
+export function closureBaseDir(absoluteFiles) {
+    const ancestor = commonAncestor(absoluteFiles.map((file) => path.dirname(file)));
+    const cwd = fs.realpathSync(process.cwd());
+    return isInsideOrSame(ancestor, cwd) ? cwd : ancestor;
+}
+function commonAncestor(paths) {
+    if (paths.length === 0)
+        return process.cwd();
+    const [first, ...rest] = paths.map((candidate) => path.resolve(candidate).split(path.sep));
+    const prefix = [];
+    for (let index = 0; index < first.length; index += 1) {
+        const segment = first[index];
+        if (rest.some((candidate) => candidate[index] !== segment))
+            break;
+        prefix.push(segment);
+    }
+    const joined = prefix.join(path.sep);
+    return joined === "" ? path.sep : joined;
+}
+function isInsideOrSame(candidate, parent) {
+    const relative = path.relative(parent, path.resolve(candidate));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+/** The entry file's full local closure: every .agency file the walk reaches,
+ *  plus the transitive local TS/JS files their interop imports need. baseDir
+ *  is computed from the .agency files only, so adding TS deps can never
+ *  shift it. */
+export function agentClosure(entryFile) {
+    const absoluteEntryFile = fs.realpathSync(path.resolve(entryFile));
+    const parsedFiles = walkAgencyClosure(absoluteEntryFile);
+    const agencyFiles = parsedFiles.map((parsed) => parsed.absoluteFile);
+    const interopEntries = parsedFiles.flatMap((parsed) => nonAgencyLocalImportTargets(parsed.program).map((specifier) => resolveInteropEntry(path.dirname(parsed.absoluteFile), specifier)));
+    const interopFiles = interopEntries.flatMap((interopEntry) => transitiveTsFiles(interopEntry));
+    const files = uniqueSorted([...agencyFiles, ...interopFiles].sort());
+    return { baseDir: closureBaseDir(agencyFiles), files };
+}
+/** `./greet.js` on disk may be greet.ts (the guide says to write .js even for
+ *  TypeScript sources). Prefer the file that exists; .ts when both do not. */
+function resolveInteropEntry(fromDir, specifier) {
+    const asWritten = path.resolve(fromDir, specifier);
+    if (fs.existsSync(asWritten))
+        return asWritten;
+    const asTs = asWritten.replace(/\.js$/, ".ts");
+    if (fs.existsSync(asTs))
+        return asTs;
+    return asWritten; // let esbuild produce the resolution error, which names the importer
+}
+/** The transitive local file set of one TS/JS entry, from esbuild's metafile.
+ *  Bare (package) imports stay external, so only relative files appear. */
+function transitiveTsFiles(interopEntry) {
+    const result = buildSync({
+        entryPoints: [interopEntry],
+        bundle: true,
+        write: false,
+        metafile: true,
+        packages: "external",
+        logLevel: "silent",
+    });
+    return Object.keys(result.metafile.inputs).map((inputPath) => path.resolve(inputPath));
+}
+/** Remove duplicates from a sorted list (equal items are adjacent). Dupes
+ *  arise when two .agency files import the same TS helper, or two TS entries
+ *  share transitive files. */
+function uniqueSorted(sorted) {
+    return sorted.filter((item, index) => index === 0 || item !== sorted[index - 1]);
+}
+export function agentClosureBaseDir(entryFile) {
+    return agentClosure(entryFile).baseDir;
+}

package/dist/lib/analysis/imports.d.ts

@@ -0,0 +1,10 @@
+import { AgencyProgram } from "../types.js";
+/** The agency-file imports a program declares: import-node statements plus
+ *  `import ... from "<agency path>"` statements. Filters out npm/Node module
+ *  imports — see compile.ts's getAllImports for the unfiltered walk. */
+export declare function getImports(program: AgencyProgram): string[];
+export type AnyImport = {
+    path: string;
+    kind: "module" | "node";
+};
+export declare function getAllImports(program: AgencyProgram): AnyImport[];

package/dist/lib/analysis/imports.js

@@ -0,0 +1,25 @@
+import { isAgencyImport } from "../importPaths.js";
+/** The agency-file imports a program declares: import-node statements plus
+ *  `import ... from "<agency path>"` statements. Filters out npm/Node module
+ *  imports — see compile.ts's getAllImports for the unfiltered walk. */
+export function getImports(program) {
+    const toolAndNodeImports = program.nodes
+        .filter((node) => node.type === "importNodeStatement")
+        .map((node) => node.agencyFile.trim());
+    // this makes compile() try to parse non-agency files
+    const importStatements = program.nodes
+        .filter((node) => node.type === "importStatement" && isAgencyImport(node.modulePath))
+        .map((node) => node.modulePath.trim());
+    return [...toolAndNodeImports, ...importStatements];
+}
+export function getAllImports(program) {
+    return program.nodes.flatMap((node) => {
+        if (node.type === "importStatement") {
+            return [{ path: node.modulePath.trim(), kind: "module" }];
+        }
+        if (node.type === "importNodeStatement") {
+            return [{ path: node.agencyFile.trim(), kind: "node" }];
+        }
+        return [];
+    });
+}