agency-lang 0.9.0 → 0.11.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/agentTarget.test.js

@@ -0,0 +1,76 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import { assertEvalEntryNodeTakesOneParameter, parseTarget, resolveEvalRunTarget, resolveEvalTarget } from "./agentTarget.js";
+const dirs = [];
+afterEach(() => {
+    // Raw rmSync, not safeDelete: mkdtemp paths sit outside any project root,
+    // which safeDelete refuses by design. Same reasoning as runArtifacts.ts.
+    for (const tempDir of dirs.splice(0)) {
+        fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+});
+describe("agent targets", () => {
+    it("splits path from node on the last colon", () => {
+        expect(parseTarget("a.agency:main")).toEqual({ filename: "a.agency", nodeName: "main" });
+        expect(parseTarget("a.agency")).toEqual({ filename: "a.agency", nodeName: "" });
+    });
+    it("resolves file and directory agent targets", () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-target-"));
+        dirs.push(tmpDir);
+        const file = path.join(tmpDir, "agent.agency");
+        fs.writeFileSync(file, "node main() {}\n");
+        const dir = path.join(tmpDir, "agent-dir");
+        fs.mkdirSync(dir);
+        fs.writeFileSync(path.join(dir, "main.agency"), "node main() {}\n");
+        expect(resolveEvalRunTarget(`${file}:evalMain`)).toEqual({ agentFile: file, node: "evalMain", label: `${file}:evalMain` });
+        expect(resolveEvalRunTarget(file)).toEqual({ agentFile: file, node: "main", label: `${file}:main` });
+        expect(resolveEvalRunTarget(dir)).toEqual({ agentFile: path.join(dir, "main.agency"), node: "main", label: `${path.join(dir, "main.agency")}:main` });
+    });
+});
+describe("resolveEvalTarget", () => {
+    it("resolves --agent into a file target", () => {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "target-"));
+        dirs.push(tmpDir);
+        const file = path.join(tmpDir, "a.agency");
+        fs.writeFileSync(file, "node main(task: string) {}\n");
+        expect(resolveEvalTarget({ agent: `${file}:main` }))
+            .toEqual({ kind: "file", agentFile: file, node: "main", label: `${file}:main` });
+    });
+    it("resolves --agent-cmd into a command target with the placeholder intact", () => {
+        expect(resolveEvalTarget({ agentCmd: `agency agent -p -- {task}` }))
+            .toEqual({ kind: "command", tokens: ["agency", "agent", "-p", "--", "{task}"], label: "agency agent -p -- {task}" });
+    });
+    it("rejects both, neither, and a command without {task}", () => {
+        expect(() => resolveEvalTarget({ agent: "a.agency", agentCmd: "x {task}" })).toThrow(/exactly one of/);
+        expect(() => resolveEvalTarget({})).toThrow(/exactly one of/);
+        expect(() => resolveEvalTarget({ agentCmd: "agency agent -p hello" })).toThrow(/\{task\}/);
+    });
+});
+describe("assertEvalEntryNodeTakesOneParameter", () => {
+    function agentWith(source) {
+        const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-shape-"));
+        dirs.push(tmpDir);
+        const file = path.join(tmpDir, "agent.agency");
+        fs.writeFileSync(file, source);
+        return file;
+    }
+    it("accepts a one-parameter node, default value or not", () => {
+        expect(() => assertEvalEntryNodeTakesOneParameter(agentWith("node main(task: string) {}\n"), "main")).not.toThrow();
+        expect(() => assertEvalEntryNodeTakesOneParameter(agentWith('node main(task: string = "") {}\n'), "main")).not.toThrow();
+    });
+    it("rejects a zero-parameter node with the add-one hint", () => {
+        expect(() => assertEvalEntryNodeTakesOneParameter(agentWith("node main() {}\n"), "main"))
+            .toThrow(/takes none — add one/);
+    });
+    it("rejects a two-parameter node, naming the parameters", () => {
+        expect(() => assertEvalEntryNodeTakesOneParameter(agentWith("node main(a: string, b: string) {}\n"), "main"))
+            .toThrow(/takes 2 \(a, b\)/);
+    });
+    it("stays quiet on unparseable files and absent nodes — compile/run report those better", () => {
+        expect(() => assertEvalEntryNodeTakesOneParameter(agentWith("this is not agency"), "main")).not.toThrow();
+        expect(() => assertEvalEntryNodeTakesOneParameter(agentWith("node other(x: string) {}\n"), "main")).not.toThrow();
+        expect(() => assertEvalEntryNodeTakesOneParameter(path.join(os.tmpdir(), "does-not-exist.agency"), "main")).not.toThrow();
+    });
+});