agentopology 0.4.3 → 0.5.1

package/README.md

@@ -96,7 +96,7 @@ who works, when they work, and what they know when they work. One file, two ways
                         ┌────────────┐
       ┌──────────────┐  │  Parser &  │   scaffold ──▶ Platform configs
       │   .at file   │─▶│  Validator │──┤                ├── .claude/agents/
-      │  (you write) │  │  92 rules  │  │                ├── <topology>.workflow.js
+      │  (you write) │  │  93 rules  │  │                ├── <topology>.workflow.js
       └──────────────┘  └────────────┘  │                ├── .codex/  .cursor/rules/
                                         │                ├── .openclaw/  .github/agents/
                                         │                └── .kiro/  …
@@ -234,7 +234,7 @@ In Claude Code, type `/agentopology` — or just ask naturally:
 Say **"I want a code review team with an analyzer, security scanner, and reviewer"** — the skill:
 
 1. Generates the `.at` file with the right syntax
-2. Validates it against 92 rules
+2. Validates it against 93 rules
 3. Scaffolds it to Claude Code, OpenClaw, Cursor, or any target
 
 **Full agent team in under 2 minutes.** No docs to read. No syntax to memorize. You describe what you want, the skill handles the rest.
@@ -566,7 +566,7 @@ import { parse, validate, bindings } from "agentopology";
 // Parse
 const ast = parse(atSource);
 
-// Validate (92 built-in rules, V1-V92)
+// Validate (93 built-in rules, V1-V93)
 const issues = validate(ast);
 
 // Scaffold — generate platform files
@@ -624,7 +624,7 @@ You can `agentopology visualize` it into an interactive graph. You can hand it t
 | **Switch platforms** | Rewrite everything | Change `--target` |
 | **Add an agent** | Update 5-12 files across 3 tools | Add 4 lines to `.at` file |
 | **See the architecture** | Read YAML, JSON, TOML, Markdown across 6 dirs | One `.at` file. Or `visualize` it. |
-| **Validate** | Hope for the best | 92 built-in rules catch errors before deploy |
+| **Validate** | Hope for the best | 93 built-in rules catch errors before deploy |
 | **Onboard someone** | "Read these 15 files and figure it out" | "Read this `.at` file" |
 | **Version control** | Diff 47 generated files | Diff one `.at` file |
 | **Move to a new tool** | Start over | `--target new-tool` |
@@ -646,7 +646,7 @@ You can `agentopology visualize` it into an interactive graph. You can hand it t
 ## CLI Reference
 
 ```
-agentopology validate <file>              Validate an .at file (92 rules)
+agentopology validate <file>              Validate an .at file (93 rules)
 agentopology plan <file>                  Resolve for interpreted execution — no files written
 agentopology scaffold <file> --target <t> Generate platform configs
 agentopology sync <file> --target <t> --dir <d>  Sync platform files back to .at

package/dist/bindings/__tests__/reasoning-effort.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `thinking` IS the reasoning-effort field.
+ *
+ * First-contact feedback asked for an `effort` field beside `model`. An audit
+ * found `AgentNode.thinking` already existed AND that codex already compiled it
+ * to `model_reasoning_effort`. Adding a second field would have given the
+ * language two words for one concept — the exact failure mode the anti-KPIs
+ * name. So: zero new vocabulary, three real fixes.
+ */
+export {};
+//# sourceMappingURL=reasoning-effort.test.d.ts.map

package/dist/bindings/__tests__/reasoning-effort.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-effort.test.d.ts","sourceRoot":"","sources":["../../../src/bindings/__tests__/reasoning-effort.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/bindings/__tests__/reasoning-effort.test.js

@@ -0,0 +1,93 @@
+/**
+ * `thinking` IS the reasoning-effort field.
+ *
+ * First-contact feedback asked for an `effort` field beside `model`. An audit
+ * found `AgentNode.thinking` already existed AND that codex already compiled it
+ * to `model_reasoning_effort`. Adding a second field would have given the
+ * language two words for one concept — the exact failure mode the anti-KPIs
+ * name. So: zero new vocabulary, three real fixes.
+ */
+import { describe, it, expect } from "vitest";
+import { parse } from "../../parser/index.js";
+import { validate } from "../../parser/validator.js";
+import { bindings } from "../index.js";
+const at = (thinking, extra = "") => `topology t : [pipeline] {
+  meta {
+    version: "1.0.0"
+    description: "x"
+  }
+  agent a {
+    model: opus
+    description: "a"
+    thinking: ${thinking}${extra}
+  }
+  action i {
+    kind: inline
+    description: "in"
+  }
+  flow { i -> a }
+}`;
+const WORKFLOW_EXT = `
+    extensions {
+      claude-workflow {
+        execution: workflow
+      }
+    }`;
+describe("thinking accepts the full effort ladder", () => {
+    it("accepts xhigh, which modern routing exposes and the enum lacked", () => {
+        expect(validate(parse(at("xhigh"))).filter((r) => r.rule === "V35")).toEqual([]);
+    });
+    it("still accepts every previously valid level", () => {
+        for (const t of ["off", "low", "medium", "high", "max"]) {
+            expect(validate(parse(at(t))).filter((r) => r.rule === "V35"), t).toEqual([]);
+        }
+    });
+    it("still rejects a level that does not exist", () => {
+        expect(validate(parse(at("ludicrous"))).filter((r) => r.rule === "V35")).toHaveLength(1);
+    });
+});
+describe("codex maps every level to a DISTINCT value", () => {
+    const effortOf = (thinking) => {
+        const f = bindings["codex"]
+            .scaffold(parse(at(thinking)))
+            .find((x) => x.path.endsWith("agents/a.toml"));
+        return /model_reasoning_effort = "(\w+)"/.exec(f.content)?.[1];
+    };
+    it("no longer collapses max onto high", () => {
+        // `max` returned "high", so max and xhigh had no distinct Codex value.
+        expect(effortOf("max")).toBe("max");
+        expect(effortOf("xhigh")).toBe("xhigh");
+        expect(effortOf("high")).toBe("high");
+        expect(new Set(["max", "xhigh", "high"]).size).toBe(3);
+    });
+    it("omits the key entirely for off", () => {
+        expect(effortOf("off")).toBeUndefined();
+    });
+});
+describe("claude-workflow emits effort — the option its runtime accepts", () => {
+    const script = (thinking) => bindings["claude-workflow"]
+        .scaffold(parse(at(thinking, WORKFLOW_EXT)))
+        .find((f) => f.path.endsWith(".js"))?.content ?? "";
+    it("passes thinking through as the agent() effort option", () => {
+        // This binding emitted nothing for it and never read agent.thinking at all,
+        // so a declared reasoning level was dropped on the one target that can
+        // honour it natively.
+        expect(script("xhigh")).toContain("effort: 'xhigh'");
+    });
+    it("omits effort when thinking is off", () => {
+        const s = script("off");
+        expect(s.length).toBeGreaterThan(0);
+        expect(s).not.toContain("effort:");
+    });
+});
+describe("no `effort` field was added to the language", () => {
+    it("rejects `effort` as an agent field rather than silently accepting it", () => {
+        // Two words for one concept is the failure mode. If someone writes
+        // `effort:` expecting it to work, they should find out.
+        const src = at("high").replace("thinking: high", "effort: high");
+        const ast = parse(src);
+        const agent = ast.nodes.find((n) => n.id === "a");
+        expect(agent.effort, "no effort field should exist on the AST").toBeUndefined();
+    });
+});
+//# sourceMappingURL=reasoning-effort.test.js.map

package/dist/bindings/__tests__/reasoning-effort.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasoning-effort.test.js","sourceRoot":"","sources":["../../../src/bindings/__tests__/reasoning-effort.test.ts"],"names":[],"mappings":"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"}

package/dist/bindings/claude-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAw4F/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aAkG/B,CAAC"}
+{"version":3,"file":"claude-code.d.ts","sourceRoot":"","sources":["../../src/bindings/claude-code.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuBH,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAo5F/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aAkG/B,CAAC"}

package/dist/bindings/claude-code.js

@@ -10,6 +10,7 @@ import { deduplicateFiles } from "./types.js";
 import { shellStub, STUB_MARKER } from "./lib/stub.js";
 import { isWorkflowSeamAgent, seamFiles } from "./lib/seam.js";
 import { phaseOf as sharedPhaseOf } from "../resolve/phase.js";
+import { gateAnchors } from "../parser/ast.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -1236,9 +1237,9 @@ function generateTopologySkill(ast) {
         for (const gate of gates) {
             sections.push(`### ${toTitle(gate.id)}`);
             if (gate.after)
-                sections.push(`After: ${gate.after}`);
+                sections.push(`After: ${gateAnchors(gate, "after").join(", ")}`);
             if (gate.before)
-                sections.push(`Before: ${gate.before}`);
+                sections.push(`Before: ${gateAnchors(gate, "before").join(", ")}`);
             if (gate.run)
                 sections.push(`Run: ${gate.run}`);
             if (gate.checks && gate.checks.length > 0) {
@@ -1669,7 +1670,10 @@ function generateGateWrapperScripts(ast) {
             ? `echo "Gate '${gate.id}' validation failed. Fix issues before proceeding." >&2\n  exit 2`
             : `echo "Gate '${gate.id}' failed — bounce back and fix the issues." >&2\n  exit 2`;
         const inlineMode = getDelegationMode(ast) === "inline";
-        const wiredAsHook = !inlineMode && isRegisteredSubagentType(ast, gate.after);
+        const gateAfters = gateAnchors(gate, "after");
+        const wiredAsHook = !inlineMode &&
+            gateAfters.length > 0 &&
+            gateAfters.every((a) => isRegisteredSubagentType(ast, a));
         let enforcementNote;
         let enforcementNote2;
         if (inlineMode) {
@@ -1677,11 +1681,11 @@ function generateGateWrapperScripts(ast) {
             enforcementNote2 = `#              Invoke this script from your /${ast.topology.name} playbook at the right step.`;
         }
         else if (wiredAsHook) {
-            enforcementNote = `# Enforcement: SubagentStop hook on agent "${gate.after}". Exit 2 blocks the subagent`;
+            enforcementNote = `# Enforcement: SubagentStop hook on agent "${gateAnchors(gate, "after").join('", "')}". Exit 2 blocks the subagent`;
             enforcementNote2 = `#              from stopping (Claude Code prevents stop and surfaces stderr to Claude).`;
         }
         else {
-            enforcementNote = `# Enforcement: NOT wired as a SubagentStop hook (after: ${gate.after || "<unset>"} is not an agent).`;
+            enforcementNote = `# Enforcement: NOT wired as a SubagentStop hook (after: ${gateAnchors(gate, "after").join(", ") || "<unset>"} is not an agent).`;
             enforcementNote2 = `#              Invoke this script from your orchestrator playbook or a /command at the right step.`;
         }
         const contentLines = [
@@ -1692,8 +1696,8 @@ function generateGateWrapperScripts(ast) {
             enforcementNote2,
             "set -euo pipefail",
             "",
-            "# Gate runs after: " + (gate.after || "any"),
-            "# Gate runs before: " + (gate.before || "any"),
+            "# Gate runs after: " + (gateAnchors(gate, "after").join(", ") || "any"),
+            "# Gate runs before: " + (gateAnchors(gate, "before").join(", ") || "any"),
             `# On failure: ${gate.onFail || "halt"}`,
         ];
         if (gate.timeout) {
@@ -1937,8 +1941,12 @@ function generateSettings(ast) {
         // SubagentStop matcher must be a registered subagent_type. If the gate
         // doesn't target an agent node, we cannot wire it as a hook — warn and
         // skip so we don't ship dead config that never fires.
-        if (!isRegisteredSubagentType(ast, gate.after)) {
-            const targetDesc = gate.after ? `non-agent target "${gate.after}"` : "no after: target";
+        const anchors = gateAnchors(gate, "after");
+        if (anchors.length === 0 || !anchors.every((a) => isRegisteredSubagentType(ast, a))) {
+            const bad = anchors.filter((a) => !isRegisteredSubagentType(ast, a));
+            const targetDesc = anchors.length
+                ? `non-agent target ${bad.map((b) => `"${b}"`).join(", ")}`
+                : "no after: target";
             console.warn(`[claude-code] Gate "${gate.id}" has ${targetDesc} — SubagentStop hook not emitted ` +
                 `(matcher must be an agent node id). The gate wrapper script is still generated; ` +
                 `invoke it from your orchestrator playbook or a slash command at the right step.`);
@@ -1949,16 +1957,20 @@ function generateSettings(ast) {
             hooksByEvent[eventName] = [];
         const scriptName = `gate-${gate.id}.sh`;
         const command = `bash .claude/skills/${topologyName}/scripts/${scriptName}`;
-        const hookEntry = {
-            matcher: gate.after,
+        // ONE ENTRY PER ANCHOR. A SubagentStop matcher is a STRING — an array would
+        // land in settings.json, type-check clean through Record<string, unknown>,
+        // and the hook would simply never fire. Silent, and the gate would look
+        // wired while doing nothing.
+        const hookEntries = anchors.map((anchor) => ({
+            matcher: anchor,
             hooks: [
                 {
                     type: "command",
                     command,
                 },
             ],
-        };
-        hooksByEvent[eventName].push(hookEntry);
+        }));
+        hooksByEvent[eventName].push(...hookEntries);
     }
     // HYBRID: host-layer concurrent Blackboard observer.
     //
@@ -2337,8 +2349,8 @@ function generateCommandFiles(ast) {
                     "by its `after:` field. Exit code 0 = pass, non-zero = fail.");
                 sections.push("");
                 for (const gate of blockingGates) {
-                    const after = gate.after ?? "(any)";
-                    const before = gate.before ?? "(any)";
+                    const after = gateAnchors(gate, "after").join(", ") || "(any)";
+                    const before = gateAnchors(gate, "before").join(", ") || "(any)";
                     const onFail = gate.onFail ?? "halt";
                     sections.push(`### gate \`${gate.id}\` — after \`${after}\`, before \`${before}\`, on-fail \`${onFail}\``);
                     sections.push("");