agentopology 0.2.1 → 0.2.4

package/dist/bindings/__tests__/bindings.test.js

@@ -1,6 +1,7 @@
 import { describe, it, expect } from "vitest";
 import { parse } from "../../parser/index.js";
 import { bindings, claudeCodeBinding, kiroBinding, cursorBinding, } from "../index.js";
+import { isStubContent, STUB_MARKER } from "../lib/stub.js";
 // ---------------------------------------------------------------------------
 // Minimal but valid .at topology exercising most features
 // ---------------------------------------------------------------------------
@@ -244,6 +245,246 @@ describe("claude-code binding", () => {
         const advisoryWrapper = files.find((f) => f.path.includes("gate-soft-review.sh"));
         expect(advisoryWrapper).toBeUndefined();
     });
+    it("gate stub contains the AGENTOPOLOGY_STUB marker (#4)", () => {
+        // The gate's `run` script is a stub generated by shellStub() in the
+        // shared lib. It must carry the marker so tooling can detect it.
+        const stub = files.find((f) => f.path.endsWith("/scripts/lint.sh"));
+        expect(stub).toBeDefined();
+        expect(stub.content).toContain(STUB_MARKER);
+        expect(isStubContent(stub.content)).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// claude-code — Issue #3: SubagentStop matcher targeting
+//
+// Per https://code.claude.com/docs/en/hooks.md, the SubagentStop hook's
+// `matcher` field is matched against agent_type (the registered subagent
+// name). Only agent and group nodes scaffold a `.claude/agents/<name>/AGENT.md`
+// file and therefore register as subagent_types. Human, action, and
+// orchestrator targets cannot be matched and would produce dead config that
+// never fires. The scaffolder must skip those hooks (and warn) but still
+// generate the wrapper script so the orchestrator can invoke it directly.
+// ---------------------------------------------------------------------------
+describe("claude-code binding — gate SubagentStop targeting (#3)", () => {
+    // Build a topology where one gate targets an agent and another targets a
+    // human node — proves both branches of isRegisteredSubagentType.
+    const GATE_TARGETING_SOURCE = `
+topology gate-target-test : [pipeline] {
+  meta {
+    version: "1.0.0"
+    description: "Gate targeting test"
+  }
+
+  orchestrator { model: opus handles: [intake] }
+  action intake { kind: external source: "user" }
+
+  agent writer {
+    model: sonnet
+    phase: 1
+    tools: [Read, Write]
+    reads: ["workspace/input.md"]
+    writes: ["workspace/draft.md"]
+    permissions: autonomous
+  }
+
+  human approver {
+    description: "Approve the draft before publishing"
+    timeout: 1h
+    on-timeout: skip
+  }
+
+  agent publisher {
+    model: sonnet
+    phase: 3
+    tools: [Read, Bash]
+    reads: ["workspace/draft.md"]
+    writes: ["workspace/published.md"]
+    permissions: autonomous
+  }
+
+  flow {
+    intake -> writer
+    writer -> approver
+    approver -> publisher
+  }
+
+  gates {
+    gate gate-on-agent {
+      after: writer
+      before: approver
+      run: "scripts/check-draft.sh"
+      on-fail: bounce-back
+      behavior: blocking
+    }
+    gate gate-on-human {
+      after: approver
+      before: publisher
+      run: "scripts/check-approval.sh"
+      on-fail: halt
+      behavior: blocking
+    }
+  }
+}
+`;
+    const ast = parse(GATE_TARGETING_SOURCE);
+    // Capture warnings emitted during scaffold so tests can assert on them.
+    const originalWarn = console.warn;
+    const warnings = [];
+    console.warn = (...args) => {
+        warnings.push(args.map(String).join(" "));
+    };
+    let files;
+    try {
+        files = claudeCodeBinding.scaffold(ast);
+    }
+    finally {
+        console.warn = originalWarn;
+    }
+    const settingsFile = files.find((f) => f.path === ".claude/settings.json");
+    const settings = JSON.parse(settingsFile.content);
+    it("emits SubagentStop hook when gate.after is an agent", () => {
+        expect(settings.hooks.SubagentStop).toBeDefined();
+        const agentHook = settings.hooks.SubagentStop.find((h) => h.matcher === "writer");
+        expect(agentHook).toBeDefined();
+        expect(JSON.stringify(agentHook)).toContain("gate-gate-on-agent");
+    });
+    it("does NOT emit SubagentStop hook when gate.after is a human node", () => {
+        const humanHook = (settings.hooks?.SubagentStop ?? []).find((h) => h.matcher === "approver");
+        expect(humanHook).toBeUndefined();
+    });
+    it("warns at scaffold time when a blocking gate targets a non-agent node", () => {
+        const humanWarning = warnings.find((w) => w.includes("gate-on-human") && w.includes("approver"));
+        expect(humanWarning).toBeDefined();
+        expect(humanWarning).toContain("non-agent");
+    });
+    it("still generates the gate wrapper script for non-agent-targeted gate", () => {
+        // The wrapper must exist so the orchestrator/playbook can invoke it
+        // manually at the right step, even when no hook fires.
+        const wrapper = files.find((f) => f.path.endsWith("/scripts/gate-gate-on-human.sh"));
+        expect(wrapper).toBeDefined();
+    });
+    it("wrapper script for non-agent-targeted gate documents the limitation", () => {
+        const wrapper = files.find((f) => f.path.endsWith("/scripts/gate-gate-on-human.sh"));
+        expect(wrapper.content).toContain("NOT wired as a SubagentStop hook");
+        expect(wrapper.content).toContain("orchestrator playbook");
+    });
+    it("wrapper script for agent-targeted gate documents SubagentStop enforcement", () => {
+        const wrapper = files.find((f) => f.path.endsWith("/scripts/gate-gate-on-agent.sh"));
+        expect(wrapper.content).toContain("SubagentStop hook on agent \"writer\"");
+        expect(wrapper.content).toContain("Exit 2 blocks");
+    });
+    it("scaffolded hook entry uses agent name (not 'Agent' or arbitrary) as matcher", () => {
+        // Sanity check: matchers must be exactly the agent id, since Claude Code
+        // matches them against agent_type, not against the tool name.
+        const hooks = settings.hooks.SubagentStop ?? [];
+        for (const h of hooks) {
+            // Each matcher must correspond to an agent or group node in the AST.
+            const matcher = h.matcher;
+            expect(matcher).toBeTruthy();
+            const matchingNode = ast.nodes.find((n) => (n.type === "agent" || n.type === "group") && n.id === matcher);
+            expect(matchingNode, `matcher "${matcher}" must resolve to an agent or group node`).toBeDefined();
+        }
+    });
+});
+// ---------------------------------------------------------------------------
+// claude-code — Integration test: youtube-flywheel.at fixture (#3)
+//
+// The real-world failure from agentopology-content: gates with after: human
+// produced dead SubagentStop entries. This integration test pins the fix
+// against the actual fixture and asserts the right hooks fire and the wrong
+// ones don't.
+// ---------------------------------------------------------------------------
+describe("claude-code binding — youtube-flywheel integration (#3)", () => {
+    const YOUTUBE_FLYWHEEL_SOURCE = `
+topology youtube-flywheel : [pipeline, fan-out, human-gate] {
+  meta { version: "1.0.0" }
+
+  orchestrator { model: opus handles: [start] }
+  action start { kind: inline }
+
+  agent briefer {
+    model: opus
+    phase: 4
+    tools: [Read, Write]
+    reads: ["workspace/idea.json"]
+    writes: ["workspace/brief.json"]
+    permissions: supervised
+  }
+
+  human approve-brief {
+    description: "Review the brief before render"
+    timeout: 8h
+    on-timeout: skip
+  }
+
+  agent renderer {
+    model: sonnet
+    phase: 6
+    tools: [Read, Write, Bash]
+    reads: ["workspace/brief.json"]
+    writes: ["workspace/render/"]
+    permissions: autonomous
+  }
+
+  flow {
+    start -> briefer
+    briefer -> approve-brief
+    approve-brief -> renderer
+  }
+
+  gates {
+    gate brief-schema-valid {
+      after: briefer
+      before: approve-brief
+      run: "scripts/validate-brief.sh"
+      on-fail: bounce-back
+      behavior: blocking
+    }
+    gate render-quality {
+      after: renderer
+      before: start
+      run: "scripts/qa-render.sh"
+      on-fail: bounce-back
+      behavior: blocking
+    }
+    gate platform-credentials {
+      after: approve-brief
+      before: renderer
+      run: "scripts/check-platform-auth.sh"
+      on-fail: halt
+      behavior: blocking
+    }
+  }
+}
+`;
+    const ast = parse(YOUTUBE_FLYWHEEL_SOURCE);
+    const originalWarn = console.warn;
+    const warnings = [];
+    console.warn = (...args) => {
+        warnings.push(args.map(String).join(" "));
+    };
+    let files;
+    try {
+        files = claudeCodeBinding.scaffold(ast);
+    }
+    finally {
+        console.warn = originalWarn;
+    }
+    const settingsFile = files.find((f) => f.path === ".claude/settings.json");
+    const settings = JSON.parse(settingsFile.content);
+    it("emits SubagentStop hooks for the two agent-targeted gates", () => {
+        const matchers = (settings.hooks?.SubagentStop ?? []).map((h) => h.matcher);
+        expect(matchers).toContain("briefer");
+        expect(matchers).toContain("renderer");
+    });
+    it("does NOT emit a SubagentStop hook for the gate targeting the human 'approve-brief'", () => {
+        const matchers = (settings.hooks?.SubagentStop ?? []).map((h) => h.matcher);
+        expect(matchers).not.toContain("approve-brief");
+    });
+    it("warns at scaffold time about the platform-credentials gate", () => {
+        const w = warnings.find((m) => m.includes("platform-credentials") && m.includes("approve-brief"));
+        expect(w).toBeDefined();
+    });
 });
 // ---------------------------------------------------------------------------
 // claude-code — Exotic features: groups, humans, circuit breakers, scale,
@@ -2086,4 +2327,186 @@ topology debate-test : [fan-out, debate, pipeline] {
         });
     });
 });
+// ---------------------------------------------------------------------------
+// claude-code — Inline orchestrator delegation mode (#7)
+//
+// When orchestrator { delegation: inline } is declared, no subagent is ever
+// spawned — the orchestrator drives every agent step in its own session. So
+// SubagentStop hooks would be dead config even when the matcher names a real
+// agent. The binding must suppress those hooks and emit a playbook cheat
+// sheet instead.
+// ---------------------------------------------------------------------------
+describe("claude-code binding — inline orchestrator delegation (#7)", () => {
+    const INLINE_SOURCE = `
+topology inline-test : [pipeline] {
+  meta { version: "1.0.0" description: "Inline-orchestrator topology" }
+  orchestrator {
+    model: opus
+    delegation: inline
+    handles: [start]
+  }
+  action start { kind: inline }
+  agent writer {
+    model: sonnet
+    phase: 1
+    tools: [Read, Write]
+    reads: ["workspace/input.md"]
+    writes: ["workspace/draft.md"]
+    permissions: autonomous
+  }
+  agent publisher {
+    model: sonnet
+    phase: 2
+    tools: [Read, Bash]
+    reads: ["workspace/draft.md"]
+    writes: ["workspace/published.md"]
+    permissions: autonomous
+  }
+  flow {
+    start -> writer
+    writer -> publisher
+  }
+  gates {
+    gate quality-check {
+      after: writer
+      before: publisher
+      run: "scripts/check.sh"
+      on-fail: bounce-back
+      behavior: blocking
+    }
+  }
+  triggers {
+    command run { pattern: "/run" }
+  }
+  hooks {
+    hook log-finish {
+      on: SubagentStop
+      matcher: writer
+      run: "scripts/log.sh"
+      type: command
+    }
+  }
+}
+`;
+    const ast = parse(INLINE_SOURCE);
+    const originalWarn = console.warn;
+    const warnings = [];
+    console.warn = (...args) => {
+        warnings.push(args.map(String).join(" "));
+    };
+    let files;
+    try {
+        files = claudeCodeBinding.scaffold(ast);
+    }
+    finally {
+        console.warn = originalWarn;
+    }
+    it("does NOT emit any SubagentStop entries in settings.json (gates + global hooks suppressed)", () => {
+        const settingsFile = files.find((f) => f.path === ".claude/settings.json");
+        if (!settingsFile)
+            return; // no hooks/permissions → no settings file
+        const settings = JSON.parse(settingsFile.content);
+        const stop = settings.hooks?.SubagentStop ?? [];
+        expect(stop).toEqual([]);
+    });
+    it("warns once per blocking gate that the hook is suppressed", () => {
+        const gateWarn = warnings.find((w) => w.includes("quality-check") && w.includes('"inline"'));
+        expect(gateWarn).toBeDefined();
+    });
+    it("warns when an explicit global SubagentStop hook is declared in inline mode", () => {
+        const hookWarn = warnings.find((w) => w.includes("log-finish") && w.includes('"inline"'));
+        expect(hookWarn).toBeDefined();
+    });
+    it("still generates the gate wrapper script (for orchestrator to invoke)", () => {
+        const wrapper = files.find((f) => f.path.endsWith("/scripts/gate-quality-check.sh"));
+        expect(wrapper).toBeDefined();
+        expect(wrapper.content).toContain('orchestrator.delegation is "inline"');
+        expect(wrapper.content).toContain("playbook");
+    });
+    it("emits a 'Gates to invoke' cheat sheet in the trigger playbook", () => {
+        const playbook = files.find((f) => f.path === ".claude/commands/run.md");
+        expect(playbook).toBeDefined();
+        expect(playbook.content).toContain("Gates to invoke (inline-orchestrator)");
+        expect(playbook.content).toContain("bash .claude/skills/inline-test/scripts/gate-quality-check.sh");
+        expect(playbook.content).toContain("after `writer`");
+    });
+});
+describe("claude-code binding — default delegation: subagent (backward compat)", () => {
+    // No `delegation:` field declared → treat as "subagent" → hooks fire as before.
+    const SUBAGENT_SOURCE = `
+topology subagent-test : [pipeline] {
+  meta { version: "1.0.0" }
+  orchestrator { model: opus handles: [start] }
+  action start { kind: inline }
+  agent writer {
+    model: sonnet
+    phase: 1
+    tools: [Read, Write]
+    reads: ["workspace/input.md"]
+    writes: ["workspace/draft.md"]
+    permissions: autonomous
+  }
+  flow {
+    start -> writer
+  }
+  gates {
+    gate quality-check {
+      after: writer
+      run: "scripts/check.sh"
+      on-fail: bounce-back
+      behavior: blocking
+    }
+  }
+}
+`;
+    const ast = parse(SUBAGENT_SOURCE);
+    const files = claudeCodeBinding.scaffold(ast);
+    const settings = JSON.parse(files.find((f) => f.path === ".claude/settings.json").content);
+    it("emits SubagentStop hook (default behavior preserved)", () => {
+        const hooks = settings.hooks?.SubagentStop ?? [];
+        expect(hooks.length).toBe(1);
+        expect(hooks[0].matcher).toBe("writer");
+    });
+    it("wrapper script header documents the SubagentStop enforcement", () => {
+        const wrapper = files.find((f) => f.path.endsWith("/scripts/gate-quality-check.sh"));
+        expect(wrapper.content).toContain('SubagentStop hook on agent "writer"');
+        expect(wrapper.content).toContain("Exit 2 blocks");
+    });
+});
+// ---------------------------------------------------------------------------
+// Cross-binding: AGENTOPOLOGY_STUB marker uniformity (#4)
+//
+// All bindings that scaffold gate scripts must emit them via the shared
+// shellStub() util — which embeds the AGENTOPOLOGY_STUB marker. This test
+// loops over every binding and verifies that at least one stub file in its
+// scaffold output is detectable by isStubContent().
+// ---------------------------------------------------------------------------
+describe("Stub marker uniformity across bindings (#4)", () => {
+    // The baseline TOPOLOGY_SOURCE at the top of this file has gate
+    // `quality-check` whose `run: "scripts/lint.sh"` becomes a stub. Bindings
+    // that scaffold gates (5 of 7) must produce a stub for it. The two that
+    // don't (copilot-cli, cursor) have no gate-script generation and are
+    // excluded.
+    const stubProducers = ["claude-code", "codex", "gemini-cli", "kiro", "openclaw"];
+    for (const bindingName of stubProducers) {
+        it(`${bindingName} emits at least one stub with the AGENTOPOLOGY_STUB marker`, () => {
+            const files = scaffoldBinding(bindingName);
+            const stubs = files.filter((f) => isStubContent(f.content));
+            expect(stubs.length, `${bindingName} should emit at least one stub`).toBeGreaterThan(0);
+            // Every stub must contain the literal marker string (pinned by the
+            // STUB_MARKER constant — see lib/stub.ts).
+            for (const s of stubs) {
+                expect(s.content).toContain(STUB_MARKER);
+            }
+        });
+    }
+    it("copilot-cli produces NO stubs (no shell-script scaffolds)", () => {
+        // Sanity check — confirms the two non-stub-producing bindings stay
+        // in their respective lanes. If this fails, copilot-cli probably
+        // grew a gate-script path and needs the same marker treatment.
+        const files = scaffoldBinding("copilot-cli");
+        const stubs = files.filter((f) => isStubContent(f.content));
+        expect(stubs).toEqual([]);
+    });
+});
 //# sourceMappingURL=bindings.test.js.map