agentopology 0.2.1 → 0.2.3

package/dist/bindings/__tests__/stub-generation.test.js

@@ -0,0 +1,117 @@
+/**
+ * Tests for Change 4 + 5: Agent-scoped env var injection + stub script generation.
+ *
+ * Change 4: When scaffold generates a hook stub, it must include logic to
+ * extract ACTIVE_AGENT from the Claude Code stdin JSON payload (agent_type field).
+ *
+ * Change 5: When a hook's run: path does not exist on disk, scaffold emits a stub
+ * at that path with:
+ *   - #!/usr/bin/env bash shebang
+ *   - jq-based AGENT_TYPE extraction from stdin
+ *   - A metrics.jsonl append
+ *   - chmod +x (executable bit)
+ *   - Auto-generated marker comment
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { parse } from "../../parser/index.js";
+import { bindings } from "../index.js";
+let tmpDir;
+beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "stub-gen-test-"));
+});
+afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// Topology with a hook pointing at a non-existent script
+// ---------------------------------------------------------------------------
+const STUB_TOPOLOGY = `
+topology stub-test : [supervisor] {
+  meta { version: "1.0.0" description: "Stub generation test" }
+  orchestrator { model: opus handles: [start] }
+  action start { kind: inline }
+  agent tracker { model: sonnet phase: 1 prompt { You are tracker. } }
+  flow { start -> tracker }
+  hooks {
+    hook log-finish {
+      on: SubagentStop
+      matcher: "tracker"
+      run: ".claude/scripts/log-finish.sh"
+      type: command
+      timeout: 5000
+    }
+  }
+}
+`;
+// ---------------------------------------------------------------------------
+// Change 5 — stub generation for non-existent hook scripts
+// ---------------------------------------------------------------------------
+describe("Change 5 — hook stub generation", () => {
+    const ast = parse(STUB_TOPOLOGY);
+    const binding = bindings["claude-code"];
+    it("generates a stub script file for hook with non-existent run path", () => {
+        const files = binding.scaffold(ast);
+        // The stub should be at the path declared in hook.run
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub).toBeDefined();
+    });
+    it("stub file has category 'script'", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.category).toBe("script");
+    });
+    it("stub contains shebang line", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("#!/usr/bin/env bash");
+    });
+    it("stub contains auto-generated marker", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("Auto-generated by agentopology scaffold");
+    });
+    it("stub extracts AGENT_TYPE from stdin JSON (Change 4 — env var injection)", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        // Stub must extract agent_type from the Claude Code stdin payload
+        expect(stub.content).toContain("agent_type");
+        expect(stub.content).toContain("AGENT_TYPE");
+    });
+    it("stub appends to metrics.jsonl", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("metrics.jsonl");
+    });
+    it("stub includes hook name in header comment", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("log-finish");
+    });
+    it("stub includes event name in header comment", () => {
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub.content).toContain("SubagentStop");
+    });
+    it("stub is marked executable (via a generated chmod hint or content)", () => {
+        // Since scaffold returns file content (not real fs writes), we check the
+        // category is 'script' — the executeActions function sets chmod on creation.
+        // The actual chmod happens in executeActions. We verify it in an integration
+        // test by writing the file and checking the mode.
+        const files = binding.scaffold(ast);
+        const stub = files.find((f) => f.path === ".claude/scripts/log-finish.sh");
+        expect(stub).toBeDefined();
+        expect(stub.category).toBe("script");
+        expect(stub.executable).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// Change 5 — NO stub if the script already exists on disk (not scaffold's job)
+// ---------------------------------------------------------------------------
+// Note: scaffold() generates file lists; the incremental engine decides
+// what to write. The stub is always in the generated list — the incremental
+// engine's "script" category + shouldOverwriteScript() prevents overwriting
+// user-edited stubs. This is correct behaviour, already tested in scaffold.test.ts.
+//# sourceMappingURL=stub-generation.test.js.map

package/dist/bindings/__tests__/stub-generation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-generation.test.js","sourceRoot":"","sources":["../../../src/bindings/__tests__/stub-generation.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;AA+xE/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aA0F/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;AAk3E/D,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,EAAE,aA0F/B,CAAC"}

package/dist/bindings/claude-code.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { deduplicateFiles } from "./types.js";
+import { shellStub } from "./lib/stub.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -76,17 +77,18 @@ function frontmatter(fields) {
     lines.push("---");
     return lines.join("\n");
 }
-/** Generate a shell script stub with a header comment. */
-function shellStub(description) {
-    return [
-        "#!/usr/bin/env bash",
-        `# ${description}`,
-        "# Auto-generated by agentopology scaffold — edit as needed.",
-        'set -euo pipefail',
-        "",
-        'echo "TODO: implement this script"',
-        "",
-    ].join("\n");
+/**
+ * Check whether `name` refers to a node registered as a Claude Code subagent_type.
+ *
+ * Both `agent` and `group` nodes scaffold a `.claude/agents/<name>/AGENT.md`
+ * file, which is what Claude Code registers as a subagent_type. Action, gate,
+ * human, and orchestrator nodes are NOT registered and therefore CANNOT be
+ * used as SubagentStop matchers.
+ */
+function isRegisteredSubagentType(ast, name) {
+    if (!name)
+        return false;
+    return ast.nodes.some((n) => (n.type === "agent" || n.type === "group") && n.id === name);
 }
 /** Generate an empty directory marker (a .gitkeep file). */
 function gitkeep(dirPath) {
@@ -1457,11 +1459,19 @@ function generateGateWrapperScripts(ast) {
         const onFailExit = gate.onFail === "halt"
             ? `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 wiredAsHook = isRegisteredSubagentType(ast, gate.after);
+        const enforcementNote = wiredAsHook
+            ? `# Enforcement: SubagentStop hook on agent "${gate.after}". Exit 2 blocks the subagent`
+            : `# Enforcement: NOT wired as a SubagentStop hook (after: ${gate.after || "<unset>"} is not an agent).`;
+        const enforcementNote2 = wiredAsHook
+            ? `#              from stopping (Claude Code prevents stop and surfaces stderr to Claude).`
+            : `#              Invoke this script from your orchestrator playbook or a /command at the right step.`;
         const contentLines = [
             "#!/usr/bin/env bash",
             `# Gate wrapper: ${gate.id}`,
-            `# Enforces gate "${gate.id}" on SubagentStop (after: ${gate.after || "any"}).`,
             `# Auto-generated by agentopology scaffold — edit as needed.`,
+            enforcementNote,
+            enforcementNote2,
             "set -euo pipefail",
             "",
             "# Gate runs after: " + (gate.after || "any"),
@@ -1517,27 +1527,66 @@ function generateGateWrapperScripts(ast) {
     }
     return files;
 }
-/** Generate hook script stubs for every hook's `run` field. */
+/**
+ * Generate an observability-aware hook stub (Changes 4+5).
+ *
+ * For SubagentStop/Stop hooks: extract agent_type from the Claude Code stdin
+ * JSON payload and export as AGENT_TYPE, then append a metrics.jsonl entry.
+ * For other events: emit a simple TODO stub.
+ */
+function observabilityStub(hookName, eventName, matcherHint) {
+    const isFinishEvent = eventName === "SubagentStop" || eventName === "Stop";
+    if (isFinishEvent) {
+        return [
+            "#!/usr/bin/env bash",
+            `# Auto-generated by agentopology scaffold on ${new Date().toISOString().slice(0, 10)}`,
+            `# Hook: ${hookName} · Event: ${eventName} · Matcher: ${matcherHint || "*"}`,
+            "# Replace this stub with your implementation.",
+            "# Stdin JSON payload from Claude Code is available on FD 0.",
+            "set -euo pipefail",
+            "",
+            "PAYLOAD=$(cat)",
+            'AGENT_TYPE=$(echo "$PAYLOAD" | jq -r \'.agent_type // "unknown"\')',
+            'SESSION_ID=$(echo "$PAYLOAD" | jq -r \'.session_id // ""\')',
+            "",
+            `echo "{\\\"ts\\\":\\\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\\\",\\\"event\\\":\\\"${eventName}\\\",\\\"agent\\\":\\\"$AGENT_TYPE\\\",\\\"session\\\":\\\"$SESSION_ID\\\",\\\"hook\\\":\\\"${hookName}\\\"}" >> .claude/memory/metrics.jsonl`,
+            "",
+        ].join("\n");
+    }
+    return [
+        "#!/usr/bin/env bash",
+        `# Auto-generated by agentopology scaffold on ${new Date().toISOString().slice(0, 10)}`,
+        `# Hook: ${hookName} · Event: ${eventName} · Matcher: ${matcherHint || "*"}`,
+        "# Replace this stub with your implementation.",
+        "# Stdin JSON payload from Claude Code is available on FD 0.",
+        "set -euo pipefail",
+        "",
+        'PAYLOAD=$(cat)',
+        'AGENT_TYPE=$(echo "$PAYLOAD" | jq -r \'.agent_type // "unknown"\')',
+        "",
+        `echo "TODO: implement ${hookName} hook (event: ${eventName}, agent: $AGENT_TYPE)"`,
+        "",
+    ].join("\n");
+}
+/** Generate hook script stubs for every hook's `run` field (Changes 1, 4, 5). */
 function generateHookScripts(ast) {
     const files = [];
     const name = ast.topology.name;
     for (const hook of ast.hooks) {
         if (!hook.run)
             continue;
-        // Extract script filename from the run command
-        const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+        const runPath = hook.run;
+        // If the run path starts with '.' or '/' it is already project-relative —
+        // generate the stub at exactly that path (observability pattern).
+        // Otherwise scope the stub into this topology's skill scripts directory.
+        const filePath = runPath.startsWith(".") || runPath.startsWith("/")
+            ? runPath
+            : `.claude/skills/${name}/scripts/${runPath.replace(/^.*\//, "").replace(/\s.*$/, "")}`;
         files.push({
-            path: `.claude/skills/${name}/scripts/${scriptName}`,
-            content: [
-                "#!/usr/bin/env bash",
-                `# Hook: ${hook.name} — fires on ${hook.on}`,
-                "# Auto-generated by agentopology scaffold — edit as needed.",
-                'set -euo pipefail',
-                "",
-                `echo "TODO: implement ${hook.name} hook"`,
-                "",
-            ].join("\n"),
+            path: filePath,
+            content: observabilityStub(hook.name, hook.on, hook.matcher ?? ""),
             category: "script",
+            executable: true,
         });
     }
     return files;
@@ -1589,9 +1638,16 @@ function generateSettings(ast) {
         if (!hooksByEvent[eventName]) {
             hooksByEvent[eventName] = [];
         }
-        // Build the script command with proper path prefix
-        const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
-        const command = `bash .claude/skills/${topologyName}/scripts/${scriptName}`;
+        // Build the script command.
+        // If hook.run starts with '.' or '/' it is already a project-relative or
+        // absolute path — use it verbatim so observability hooks like
+        // ".claude/scripts/log-subagent.sh" land at the correct location.
+        // Otherwise treat it as a bare filename scoped to this topology's skill
+        // scripts directory.
+        const runPath = hook.run;
+        const command = runPath.startsWith(".") || runPath.startsWith("/")
+            ? `bash ${runPath}`
+            : `bash .claude/skills/${topologyName}/scripts/${runPath.replace(/^.*\//, "").replace(/\s.*$/, "")}`;
         const hookEntry = {
             hooks: [
                 {
@@ -1610,22 +1666,47 @@ function generateSettings(ast) {
     // Per-agent hooks are now rendered in AGENT.md frontmatter (not in settings.json).
     // This is the Claude Code native approach: hooks in the agent file are scoped
     // to that agent automatically.
-    // Gate enforcement — compile gates with run: to SubagentStop hooks
-    // Gates fire AFTER an agent finishes (SubagentStop), not before a tool runs.
-    // The matcher is the gate's `after:` agent name so the hook fires when that
-    // specific agent completes.
+    // Gate enforcement — compile gates with run: to SubagentStop hooks.
+    //
+    // SubagentStop fires when a subagent finishes. Its `matcher` field is matched
+    // against `agent_type` (the registered subagent name from .claude/agents/),
+    // NOT against arbitrary node ids. So a SubagentStop hook only fires when its
+    // matcher names a real agent node — human, action, and orchestrator nodes are
+    // NOT registered as subagent_types and their matchers would silently never
+    // fire.
+    //
+    // SubagentStop with exit code 2 (or `decision: "block"`) DOES block: per the
+    // Claude Code hooks reference, exit 2 "prevents subagent from stopping" and
+    // surfaces stderr to Claude. That is the strongest enforcement available for
+    // a gate that runs after an agent completes.
+    //
+    // For gates whose `after` target is not an agent (e.g. a human checkpoint, an
+    // action, or "any"), no SubagentStop hook fires reliably. We skip emitting
+    // dead config and warn the user — the topology's orchestrator (or a slash
+    // command playbook) must invoke the gate script at the right step.
     const gates = ast.nodes.filter((n) => n.type === "gate");
     for (const gate of gates) {
         if (!gate.run)
             continue;
         if (gate.behavior === "advisory")
             continue; // advisory gates stay in markdown only
+        // 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";
+            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.`);
+            continue;
+        }
         const eventName = "SubagentStop";
         if (!hooksByEvent[eventName])
             hooksByEvent[eventName] = [];
         const scriptName = `gate-${gate.id}.sh`;
         const command = `bash .claude/skills/${topologyName}/scripts/${scriptName}`;
         const hookEntry = {
+            matcher: gate.after,
             hooks: [
                 {
                     type: "command",
@@ -1633,11 +1714,6 @@ function generateSettings(ast) {
                 },
             ],
         };
-        // Use the gate's after: agent as matcher so the hook only fires
-        // when that specific agent completes. Without after:, match all agents.
-        if (gate.after) {
-            hookEntry.matcher = gate.after;
-        }
         hooksByEvent[eventName].push(hookEntry);
     }
     // Write hooksByEvent to settings if any hooks or gates were registered