agency-lang 0.13.2 → 0.13.3

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

@@ -1594,10 +1594,6 @@ 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/prompts/codeSample.js

@@ -768,10 +768,6 @@ 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/eval/goalJudge.js

@@ -320,16 +320,12 @@ 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(__process.argv[2], __process.argv[3], __process.argv[4], initialState);
+    const __result = await main(void 0, void 0, void 0, initialState);
     await resolveCliInterrupts(__result, respondToInterrupts);
   } catch (__error) {
     reportBudgetExceededAndExit(__error);

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

@@ -2073,10 +2073,6 @@ 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

@@ -808,10 +808,6 @@ 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/backends/agencyGenerator.d.ts

@@ -76,6 +76,7 @@ export declare class AgencyGenerator {
     constructor(args?: {
         config?: AgencyConfig;
         preserveOrder?: boolean;
+        debug?: boolean;
     });
     protected trace(methodName: string, result: string): string;
     configDefaults(): Partial<AgencyConfig>;
@@ -344,6 +345,7 @@ export declare class AgencyGenerator {
 export declare function printCodeLiteralBody(node: CodeLiteral): string;
 export declare function generateAgency(program: AgencyProgram, opts?: {
     preserveOrder?: boolean;
+    debug?: boolean;
 }): string;
 /**
  * Formatter-exact source rendering of a single expression — the same

package/dist/lib/backends/agencyGenerator.js

@@ -105,6 +105,9 @@ export class AgencyGenerator {
     constructor(args = {}) {
         this.agencyConfig = mergeDeep(this.configDefaults(), args.config || {});
         this.preserveOrder = args.preserveOrder ?? false;
+        // Explicit override for callers whose output must not vary with the
+        // environment (agency doc); default keeps the AGENCY_DEBUG behavior.
+        this.debug = args.debug ?? this.debug;
         if (this.agencyConfig.verbose) {
             console.log("Generator config:", this.agencyConfig);
         }
@@ -1861,7 +1864,10 @@ export function printCodeLiteralBody(node) {
     return generateAgency({ type: "agencyProgram", nodes: node.nodes }).trimEnd();
 }
 export function generateAgency(program, opts = {}) {
-    const generator = new AgencyGenerator({ preserveOrder: opts.preserveOrder });
+    const generator = new AgencyGenerator({
+        preserveOrder: opts.preserveOrder,
+        debug: opts.debug,
+    });
     return (generator
         .generate(program)
         .output.trim()

package/dist/lib/backends/typescriptBuilder.js

@@ -57,7 +57,6 @@ function coarseKindFor(typeHint) {
 }
 import { printTs } from "../ir/prettyPrint.js";
 import { SourceMapBuilder } from "./sourceMap.js";
-import { directRunExtraArgsCheck } from "./typescriptBuilder/directRunArgsCheck.js";
 import { nodeWrapperParams } from "./typescriptBuilder/nodeWrapperParams.js";
 import { ScopeManager } from "./typescriptBuilder/scopeManager.js";
 import { StepPathTracker } from "./typescriptBuilder/stepPathTracker.js";
@@ -3686,24 +3685,29 @@ 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")) {
-            // Direct-run argv maps onto main's parameters positionally (argv[2]
-            // onward — `agency run file.agency -- <args>` forwards them), and
-            // initialState is the OPTIONS argument after them. Before this,
-            // initialState was always the first argument: harmless when mains took
-            // no parameters (it landed in the options slot), wrong once entry
-            // nodes take parameters (#739) — the state object arrived as the
-            // first parameter's value. Absent argv entries are undefined, so
-            // parameter defaults apply.
+            // The direct-run call reserves one slot per declared parameter and puts
+            // initialState after them, in main's hidden OPTIONS argument.
+            //
+            // 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 }, (_unused, i) => $(ts.id("__process")).prop("argv").index(ts.num(2 + i)).done()),
+                ...Array.from({ length: mainParamCount }, () => ts.id("undefined")),
                 ts.id("initialState"),
             ];
             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([
-                directRunExtraArgsCheck(mainParamCount),
                 ts.tryCatch(ts.statements([
                     ts.varDecl("const", "initialState", ts.obj({
                         messages: ts.newThreadStore(),

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

@@ -0,0 +1,62 @@
+/**
+ * Decides where agency's command line ends and the program's begins.
+ *
+ * `agency run --policy strict greet.agency --name alice` carries two command
+ * lines. The rule is position: agency's flags and its own positional arguments
+ * come first, and everything after them belongs to the program. Commander
+ * cannot express that — `passThroughOptions` would, but it requires positional
+ * parsing on the root command, which stops every nested command from seeing its
+ * parent's options (`agency label ingest --store x` fails outright).
+ *
+ * So the boundary is drawn before commander runs, by inserting `--`. Commander
+ * removes the separator itself, so the program never sees it.
+ *
+ * Three commands need this and differ only in their policy, which is why they
+ * share one walk rather than one each:
+ *
+ *   run       one owned positional (the filename); warns on a collision
+ *   agent     no owned positionals; forwards its own flags without comment
+ *   shorthand `agency greet.agency` — run without the word `run`
+ */
+export type Arity = "none" | "required" | "optional";
+export type CliOption = {
+    short?: string;
+    long?: string;
+    arity: Arity;
+};
+export type Boundary = {
+    /** Subcommand this applies to, or null for the bare `agency greet.agency`
+     *  form, which is whatever is left when the first word names no command. */
+    command: string | null;
+    /** Agency's own positional arguments, which sit before the program's. */
+    ownedPositionals: number;
+    /** Options agency parses before the boundary. */
+    options: CliOption[];
+    /** Whether to warn when one of `options` turns up after the boundary. */
+    warnOnCollision: boolean;
+};
+export type SplitCommandLine = {
+    /** argv with the separator inserted, ready for commander. */
+    argv: string[];
+    /** An agency flag that went to the program because of where it was written.
+     *  Position still decides — this only says so out loud. */
+    warning?: string;
+};
+export declare function splitCommandLine(argv: string[], rootOptions: CliOption[], boundaries: Boundary[], 
+/** Every command and alias the CLI knows, so a filename can be told from a
+ *  command name. Without it `agency compile a.agency b.agency` would look
+ *  like the shorthand and have a separator pushed into its file list. */
+commandNames?: string[]): SplitCommandLine;
+export declare function misplacedFlagWarning(flag: string, input: string): string;
+/**
+ * Walks past `node`, the script path, and agency's own top-level flags to find
+ * the subcommand. Returns -1 if there is none.
+ */
+export declare function findSubcommandIndex(argv: string[], rootOptions: CliOption[]): number;
+/**
+ * The agency options a token names. Commander accepts four spellings and a
+ * check that understands only the plainest one stays quiet for the rest:
+ *
+ *   --policy strict   --policy=strict   -c file.json   -cfile.json   -iv
+ */
+export declare function flagNamesIn(token: string, options: CliOption[]): string[];

package/dist/lib/cli/commandLine.js

@@ -0,0 +1,178 @@
+export function splitCommandLine(argv, rootOptions, boundaries, 
+/** Every command and alias the CLI knows, so a filename can be told from a
+ *  command name. Without it `agency compile a.agency b.agency` would look
+ *  like the shorthand and have a separator pushed into its file list. */
+commandNames = []) {
+    // The shorthand puts run's flags at the top level, so the scan for the
+    // subcommand has to recognize every flag agency owns anywhere — not just the
+    // root's. Otherwise `agency --policy strict greet.agency` stops on `strict`
+    // and treats it as the filename.
+    const subcommand = findSubcommandIndex(argv, [
+        ...rootOptions,
+        ...boundaries.flatMap((b) => b.options),
+    ]);
+    if (subcommand === -1)
+        return { argv };
+    const named = boundaries.find((b) => b.command === argv[subcommand]);
+    const boundary = named ??
+        (commandNames.includes(argv[subcommand])
+            ? undefined
+            : boundaries.find((b) => b.command === null));
+    if (boundary === undefined)
+        return { argv };
+    // Agency's flags come first, then its own positionals. Anything after that
+    // is the program's, flags included — which is what the position rule means.
+    // The shorthand has no command word to step over, so its walk starts on the
+    // filename itself.
+    let i = subcommand + (boundary.command === null ? 0 : 1);
+    while (isFlag(argv[i])) {
+        // The user drew the line themselves.
+        if (argv[i] === "--")
+            return { argv };
+        const consumed = ownedFlagTokens(argv[i], argv[i + 1], boundary.options);
+        // A flag agency does not own is already the program's.
+        if (consumed === undefined)
+            break;
+        i += consumed;
+    }
+    if (argv[i] === "--")
+        return { argv };
+    let input;
+    for (let n = 0; n < boundary.ownedPositionals; n += 1) {
+        // Agency's own positional is missing. Commander reports that better.
+        if (i >= argv.length || isFlag(argv[i]))
+            return { argv };
+        input = argv[i];
+        i += 1;
+    }
+    const rest = argv.slice(i);
+    if (rest.length === 0 || rest[0] === "--")
+        return { argv };
+    const claimed = boundary.warnOnCollision
+        ? rest.flatMap((token) => flagNamesIn(token, boundary.options)).find((name) => findOption(name, boundary.options) !== undefined)
+        : undefined;
+    return {
+        argv: [...argv.slice(0, i), "--", ...rest],
+        warning: claimed === undefined
+            ? undefined
+            : misplacedFlagWarning(claimed, input ?? "your-program.agency"),
+    };
+}
+export function misplacedFlagWarning(flag, input) {
+    return [
+        `Warning: ${flag} went to your program, not to agency.`,
+        `  Agency flags go before the filename: agency run ${flag} ... ${input}`,
+        `  Write -- before it to silence this:  agency run ${input} -- ${flag} ...`,
+    ].join("\n");
+}
+/**
+ * Walks past `node`, the script path, and agency's own top-level flags to find
+ * the subcommand. Returns -1 if there is none.
+ */
+export function findSubcommandIndex(argv, rootOptions) {
+    // argv[0] = node, argv[1] = script path. The search starts at 2.
+    let i = 2;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (token === "--")
+            return -1;
+        if (!isFlag(token))
+            return i;
+        i += tokensConsumedBy(token, argv[i + 1], rootOptions);
+    }
+    return -1;
+}
+function isFlag(token) {
+    return token !== undefined && token.startsWith("-") && token !== "-";
+}
+function findOption(name, options) {
+    return options.find((o) => o.short === name || o.long === name);
+}
+/**
+ * The agency options a token names. Commander accepts four spellings and a
+ * check that understands only the plainest one stays quiet for the rest:
+ *
+ *   --policy strict   --policy=strict   -c file.json   -cfile.json   -iv
+ */
+export function flagNamesIn(token, options) {
+    if (!isFlag(token))
+        return [];
+    if (token.startsWith("--")) {
+        const equals = token.indexOf("=");
+        return [equals === -1 ? token : token.slice(0, equals)];
+    }
+    return parseShortToken(token, options).names;
+}
+/**
+ * Reads a short token left to right, the way commander does.
+ *
+ * The first letter decides whether the token is agency's at all: `-print` is a
+ * program's flag, not a bundle containing agency's `-i`, because `-p` is not an
+ * agency flag. Reading every letter instead would warn about it.
+ */
+function parseShortToken(token, options) {
+    const letters = [...token.slice(1)];
+    const names = [];
+    for (const [index, letter] of letters.entries()) {
+        const option = findOption(`-${letter}`, options);
+        // Unknown first letter: the whole token belongs to the program. Unknown
+        // later: it is the attached value of the option before it.
+        if (option === undefined) {
+            return { names: index === 0 ? [] : names };
+        }
+        names.push(`-${letter}`);
+        // A value-taking option ends the bundle. Its value is the rest of the
+        // token, or the next word when it is the last letter.
+        if (option.arity !== "none") {
+            return index === letters.length - 1
+                ? { names, trailing: option }
+                : { names };
+        }
+    }
+    return { names };
+}
+/**
+ * How many tokens an agency flag covers, or undefined if it is not agency's.
+ *
+ * The next token is needed because commander treats the two value kinds
+ * differently. A required value takes whatever follows, even another flag:
+ * `--policy --verbose` gives policy="--verbose". An optional value steps over
+ * something that looks like a flag — `--trace --verbose` leaves trace bare —
+ * but still takes `-5`, because a digit after the dash reads as a negative
+ * number rather than a flag.
+ */
+function ownedFlagTokens(token, next, options) {
+    if (token.startsWith("--")) {
+        const equals = token.indexOf("=");
+        const name = equals === -1 ? token : token.slice(0, equals);
+        const arity = findOption(name, options)?.arity;
+        if (arity === undefined)
+            return undefined;
+        if (equals !== -1)
+            return 1;
+        return tokensForValue(arity, next);
+    }
+    const short = parseShortToken(token, options);
+    if (short.names.length === 0)
+        return undefined;
+    if (short.trailing === undefined)
+        return 1;
+    return tokensForValue(short.trailing.arity, next);
+}
+function tokensForValue(arity, next) {
+    if (arity === "none")
+        return 1;
+    if (arity === "required")
+        return 2;
+    return next === undefined || looksLikeOption(next) ? 1 : 2;
+}
+/** Commander's own test for "this token is a flag, not a value". */
+function looksLikeOption(token) {
+    return (token.length > 1 &&
+        token[0] === "-" &&
+        (token[1] === "-" || Number.isNaN(Number.parseFloat(token[1]))));
+}
+/** Root-flag walking, where an unknown flag simply covers itself. */
+function tokensConsumedBy(token, next, options) {
+    return ownedFlagTokens(token, next, options) ?? 1;
+}

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

@@ -49,6 +49,7 @@ export declare function run(config: AgencyConfig, inputFile: string, outputFile?
     maxCost?: string;
     maxTime?: string;
 }, 
-/** Forwarded to the compiled entry's argv (positions 2+), which the
- *  direct-run block maps onto main's parameters positionally. */
+/** Forwarded to the compiled program's argv (positions 2+), for the program
+ *  itself to read — `std::args` is how. They are NOT mapped onto the entry
+ *  node's parameters, which receive `undefined` on this path. */
 nodeArgs?: string[]): void;

package/dist/lib/cli/commands.js

@@ -209,8 +209,9 @@ export async function formatFile(inputFile, inPlace = false, config = {}) {
     }
 }
 export function run(config, inputFile, outputFile, resumeFile, runPolicy, budget, 
-/** Forwarded to the compiled entry's argv (positions 2+), which the
- *  direct-run block maps onto main's parameters positionally. */
+/** Forwarded to the compiled program's argv (positions 2+), for the program
+ *  itself to read — `std::args` is how. They are NOT mapped onto the entry
+ *  node's parameters, which receive `undefined` on this path. */
 nodeArgs = []) {
     const output = compile(config, inputFile, outputFile, {
         importStrategy: new RunStrategy(),

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

@@ -1,3 +1,27 @@
+import { SymbolTable } from "../symbolTable.js";
 import { AgencyConfig } from "../config.js";
+import { AgencyProgram } from "../types.js";
+import { VariableType } from "../types/typeHints.js";
+type SymbolRegistry = Record<string, string>;
+type DocContext = {
+    baseUrl?: string;
+    sourceRelPath?: string;
+    symbolRegistry: SymbolRegistry;
+    currentMdPath?: string;
+    config: AgencyConfig;
+    /** Built on first use, PER PAGE (each page gets a fresh DocContext). */
+    symbolTable?: SymbolTable;
+    /** When set, formatTypeLinked records every registry lookup it makes:
+     *  name → target md path, or null for "rendered unlinked". This is the
+     *  cache's evidence for re-checking links against next run's registry. */
+    linkRecorder?: Record<string, string | null>;
+};
 export declare function generateDoc(config: AgencyConfig, inputPath: string, outputDir: string, ignoreDirs?: string[], baseUrlOverride?: string): void;
+/** A file's pass-1 registry contributions. NOT "exported symbols": all
+ *  function definitions (non-exported and underscore-prefixed included),
+ *  node names, global-scope type aliases, and exported constants — the
+ *  set link targets resolve against. Cached per page as
+ *  `registrySymbols`, so an unchanged file costs no parse. */
+export declare function extractRegistrySymbols(program: AgencyProgram): string[];
+export declare function formatTypeLinked(type: VariableType | undefined | null, ctx: DocContext): string;
 export { extractSummaryOverride, firstParagraph, firstSentence, sanitizeDescription, moduleDescription, } from "../utils/moduleDoc.js";