agentopology 0.2.3 → 0.2.5

package/dist/bindings/claude-code.js

@@ -7,7 +7,8 @@
  * @module
  */
 import { deduplicateFiles } from "./types.js";
-import { shellStub } from "./lib/stub.js";
+import { shellStub, STUB_MARKER } from "./lib/stub.js";
+import { isWorkflowSeamAgent, seamFiles } from "./lib/seam.js";
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -90,10 +91,106 @@ function isRegisteredSubagentType(ast, name) {
         return false;
     return ast.nodes.some((n) => (n.type === "agent" || n.type === "group") && n.id === name);
 }
+/**
+ * Resolve the topology's orchestration delegation mode.
+ *
+ * Returns `"inline"` if the orchestrator block declares `delegation: inline`.
+ * Otherwise returns `"subagent"` (the default). Inline-orchestrator topologies
+ * drive every agent in the main session's context; no Task-tool subagent is
+ * ever spawned, so any `SubagentStop` hook would silently never fire.
+ */
+function getDelegationMode(ast) {
+    const orch = ast.nodes.find((n) => n.type === "orchestrator");
+    return orch?.delegation === "inline" ? "inline" : "subagent";
+}
 /** Generate an empty directory marker (a .gitkeep file). */
 function gitkeep(dirPath) {
     return { path: `${dirPath}/.gitkeep`, content: "", category: "machine" };
 }
+// ---------------------------------------------------------------------------
+// HYBRID AWARENESS (host + embedded claude-workflow rung)
+//
+// A topology can mark an agent/phase `extensions { claude-workflow { execution:
+// workflow } }`. The claude-workflow binding compiles those phases into a
+// `<topology>.workflow.js` rung. THIS (claude-code) binding is the HOST: it must
+// NOT emit a subagent AGENT.md for a workflow-marked agent — in the hybrid, the
+// host does not run that agent as a subagent; it LAUNCHES the workflow rung that
+// contains it and OBSERVES the Blackboard writes.
+//
+// The seam vocabulary here MUST stay in sync with src/bindings/claude-workflow.ts:
+//   - workflow.js filename:  `<topology>.workflow.js`
+//   - seam contract doc:     `<topology>-SEAM.md`
+//   - human-split README:    `<topology>-README.md`
+//   - Blackboard root:       `memory.workspace.path` (e.g. "workspace/")
+//   - run order: host runs host phases in-session, LAUNCHES the workflow.js for
+//     the workflow-marked phase(s), host hooks observe the writes LIVE.
+// ---------------------------------------------------------------------------
+// Seam constants/helpers (SEAM_NS, isWorkflowSeamAgent, seamFiles, workspaceRoot)
+// are the single source of truth shared with the claude-workflow binding —
+// imported from ./lib/seam.js. Do NOT re-hardcode the namespace or filenames here.
+/** Resolve an agent's phase (defaults to a large value so unphased trails). */
+function agentPhase(agent) {
+    return agent.phase ?? Number.MAX_SAFE_INTEGER;
+}
+/**
+ * The set of phases that compile into the embedded workflow rung — every phase
+ * that contains ≥1 agent marked `execution: workflow`. (Matches the
+ * claude-workflow binding's `workflowPhases`: an agent sharing a workflow phase
+ * is folded into the rung too.)
+ */
+function workflowPhaseSet(ast) {
+    const phases = new Set();
+    for (const n of ast.nodes) {
+        if (n.type === "agent" && isWorkflowSeamAgent(n)) {
+            phases.add(agentPhase(n));
+        }
+    }
+    return phases;
+}
+/** Does this topology have ≥1 workflow-marked phase (i.e. is it a hybrid)? */
+function isHybridTopology(ast) {
+    return workflowPhaseSet(ast).size > 0;
+}
+/**
+ * The Blackboard root path from `memory.workspace.path`, or null. Both bindings
+ * key the seam off this path.
+ */
+function workspaceRoot(ast) {
+    const ws = ast.memory?.workspace;
+    return ws?.path ?? null;
+}
+/**
+ * Group the workflow-marked phases into contiguous runs (by sorted phase
+ * number). Each contiguous run is ONE launch directive (the host launches the
+ * workflow.js once for that span). Returns a list of phase-number arrays.
+ */
+function contiguousWorkflowPhaseRuns(ast) {
+    const sorted = [...workflowPhaseSet(ast)].sort((a, b) => a - b);
+    const runs = [];
+    let current = [];
+    for (const p of sorted) {
+        if (current.length === 0 || p === current[current.length - 1] + 1) {
+            current.push(p);
+        }
+        else {
+            runs.push(current);
+            current = [p];
+        }
+    }
+    if (current.length > 0)
+        runs.push(current);
+    return runs;
+}
+/** A short, stable label for a phase run (used in stub filenames). */
+function workflowRunLabel(ast, run) {
+    // Prefer the first workflow-marked agent id in the run's lowest phase — that
+    // reads naturally (e.g. "build" from `builder`). Fall back to phase numbers.
+    const lowest = run[0];
+    const agentInPhase = ast.nodes.find((n) => n.type === "agent" && agentPhase(n) === lowest && isWorkflowSeamAgent(n));
+    if (agentInPhase)
+        return agentInPhase.id;
+    return run.length === 1 ? `phase-${run[0]}` : `phases-${run[0]}-${run[run.length - 1]}`;
+}
 /**
  * Map topology permission strings to Claude Code permissionMode values.
  * Returns undefined when the permission mode should be omitted (default/autonomous).
@@ -230,6 +327,13 @@ function generateAgents(ast) {
         if (node.type !== "agent")
             continue;
         const agent = node;
+        // HYBRID SEAM: an agent marked `execution: workflow` is owned by the
+        // embedded workflow rung (claude-workflow binding → <topology>.workflow.js),
+        // NOT by the host. The host does not run it as a subagent — it launches the
+        // workflow rung and observes its Blackboard writes. So do NOT emit a
+        // .claude/agents/<name>/AGENT.md for it. See generateWorkflowLaunchArtifacts.
+        if (isWorkflowSeamAgent(agent))
+            continue;
         // Build frontmatter fields
         const fm = {};
         fm.name = agent.id;
@@ -1215,6 +1319,12 @@ function generateTopologySkill(ast) {
             sections.push("");
         }
     }
+    // HYBRID run order — mirrors the claude-workflow SEAM.md so the host playbook
+    // knows where it launches the embedded workflow rung and observes its writes.
+    const hybridRunOrder = buildHybridRunOrderSection(ast);
+    if (hybridRunOrder) {
+        sections.push(hybridRunOrder);
+    }
     files.push({
         path: `.claude/skills/${name}/SKILL.md`,
         content: sections.join("\n") + "\n",
@@ -1459,13 +1569,22 @@ 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 inlineMode = getDelegationMode(ast) === "inline";
+        const wiredAsHook = !inlineMode && isRegisteredSubagentType(ast, gate.after);
+        let enforcementNote;
+        let enforcementNote2;
+        if (inlineMode) {
+            enforcementNote = `# Enforcement: NOT wired as a SubagentStop hook (orchestrator.delegation is "inline").`;
+            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`;
+            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).`;
+            enforcementNote2 = `#              Invoke this script from your orchestrator playbook or a /command at the right step.`;
+        }
         const contentLines = [
             "#!/usr/bin/env bash",
             `# Gate wrapper: ${gate.id}`,
@@ -1631,10 +1750,21 @@ function generateAgentHookScripts(ast) {
 function generateSettings(ast) {
     const settings = {};
     const topologyName = ast.topology.name;
+    const isInline = getDelegationMode(ast) === "inline";
     // Hooks section — grouped by event name
     const hooksByEvent = {};
     for (const hook of ast.hooks) {
         const eventName = hook.on;
+        // Inline orchestrator mode never spawns subagents, so SubagentStop /
+        // SubagentStart hooks would never fire. Warn the user and skip emission
+        // — keeping them in settings.json would be a maintenance trap.
+        if (isInline && (eventName === "SubagentStop" || eventName === "SubagentStart")) {
+            console.warn(`[claude-code] Hook "${hook.name}" targets ${eventName} but ` +
+                `orchestrator.delegation is "inline" — no subagent ever runs, so the hook would ` +
+                `never fire. Skipped. Move the work into your orchestrator playbook or change ` +
+                `delegation to "subagent".`);
+            continue;
+        }
         if (!hooksByEvent[eventName]) {
             hooksByEvent[eventName] = [];
         }
@@ -1684,12 +1814,27 @@ function generateSettings(ast) {
     // 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.
+    //
+    // INLINE-ORCHESTRATOR MODE: when the topology declares
+    // `orchestrator { delegation: inline }`, no subagent is ever spawned even
+    // when the matcher names a real agent — the orchestrator drives every step
+    // in its own session context. SubagentStop hooks would be dead config in
+    // this mode, so we skip emitting them entirely (still generate the wrapper
+    // script). The gate must be invoked from the playbook at the right step.
+    const delegationMode = getDelegationMode(ast);
     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
+        if (delegationMode === "inline") {
+            console.warn(`[claude-code] Gate "${gate.id}" — orchestrator.delegation is "inline", ` +
+                `so no subagent ever runs. SubagentStop hook not emitted; invoke ` +
+                `.claude/skills/${topologyName}/scripts/gate-${gate.id}.sh from your ` +
+                `orchestrator playbook at the right step.`);
+            continue;
+        }
         // 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.
@@ -1716,6 +1861,21 @@ function generateSettings(ast) {
         };
         hooksByEvent[eventName].push(hookEntry);
     }
+    // HYBRID: host-layer concurrent Blackboard observer.
+    //
+    // The topology's bare-event `hooks { PostToolUse { matcher: "Write" ... } }`
+    // block is not surfaced into ast.hooks (only the named `hook <name> {}` form is
+    // parsed). We don't change the parser (out of scope); instead, when this is a
+    // hybrid topology WITH a Blackboard, we synthesize the observe-hook: a
+    // Blackboard implies a host-side observer that watches the workflow rung's
+    // Write tool-calls LIVE. This is the host's piece of the hybrid's concurrent
+    // observability (the deterministic workflow rung cannot express it).
+    const observeHook = buildHybridObserveHook(ast, topologyName);
+    if (observeHook) {
+        if (!hooksByEvent[observeHook.event])
+            hooksByEvent[observeHook.event] = [];
+        hooksByEvent[observeHook.event].push(observeHook.entry);
+    }
     // Write hooksByEvent to settings if any hooks or gates were registered
     if (Object.keys(hooksByEvent).length > 0) {
         settings.hooks = hooksByEvent;
@@ -2062,6 +2222,34 @@ function generateCommandFiles(ast) {
             }
             sections.push("");
         }
+        // Inline-orchestrator topologies cannot wire gates via SubagentStop hooks
+        // (no subagent is ever spawned). The orchestrator playbook must invoke
+        // each non-advisory gate at the right step. We emit a copy-pasteable
+        // cheat sheet so the user knows exactly which command to drop in and
+        // where in the flow it belongs.
+        if (getDelegationMode(ast) === "inline") {
+            const blockingGates = ast.nodes.filter((n) => n.type === "gate")
+                .filter((g) => g.run && g.behavior !== "advisory");
+            if (blockingGates.length > 0) {
+                sections.push("## Gates to invoke (inline-orchestrator)");
+                sections.push("");
+                sections.push("Because `orchestrator.delegation: inline` is declared, no `SubagentStop` " +
+                    "hooks fire. Invoke each gate from this playbook at the step indicated " +
+                    "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 onFail = gate.onFail ?? "halt";
+                    sections.push(`### gate \`${gate.id}\` — after \`${after}\`, before \`${before}\`, on-fail \`${onFail}\``);
+                    sections.push("");
+                    sections.push("```bash");
+                    sections.push(`bash .claude/skills/${ast.topology.name}/scripts/gate-${gate.id}.sh`);
+                    sections.push("```");
+                    sections.push("");
+                }
+            }
+        }
         files.push({
             path: `.claude/commands/${trigger.name}.md`,
             content: sections.join("\n") + "\n",
@@ -2244,12 +2432,198 @@ function generateContextFile(ast) {
         }
         sections.push("");
     }
+    // HYBRID run order — when this topology composes with an embedded
+    // claude-workflow rung, document who runs/launches/observes what.
+    const hybridRunOrder = buildHybridRunOrderSection(ast);
+    if (hybridRunOrder) {
+        sections.push(hybridRunOrder);
+    }
     return {
         path: fileName,
         content: sections.join("\n") + "\n",
         category: "machine",
     };
 }
+/**
+ * HYBRID: emit a host-side "launch the workflow rung" skill stub for each
+ * contiguous workflow-marked phase run.
+ *
+ * In the hybrid model the host does NOT run the workflow-marked agents as
+ * subagents. At the corresponding point in the flow, the host LAUNCHES the
+ * embedded deterministic workflow rung (`<topology>.workflow.js`, emitted by the
+ * sibling claude-workflow binding). These stubs are the documented launch
+ * directives, scoped into the topology's skill scripts directory next to the
+ * gate/hook stubs (same AGENTOPOLOGY_STUB mechanism so CI can detect them).
+ */
+function generateWorkflowLaunchArtifacts(ast) {
+    const files = [];
+    if (!isHybridTopology(ast))
+        return files;
+    const name = ast.topology.name;
+    const workflowFile = seamFiles.workflowScript(name);
+    const seamDoc = seamFiles.seamDoc(name);
+    const root = workspaceRoot(ast);
+    const runs = contiguousWorkflowPhaseRuns(ast);
+    for (const run of runs) {
+        const label = workflowRunLabel(ast, run);
+        // Agents that this rung owns (for documentation in the stub body).
+        const ownedAgents = ast.nodes
+            .filter((n) => n.type === "agent" && run.includes(agentPhase(n)) && isWorkflowSeamAgent(n))
+            .map((a) => a.id);
+        const phaseLabel = run.length === 1 ? `phase ${run[0]}` : `phases ${run[0]}–${run[run.length - 1]}`;
+        const body = [
+            "#!/usr/bin/env bash",
+            `# Launch the embedded workflow rung for ${phaseLabel} (${ownedAgents.join(", ")}).`,
+            "# Auto-generated by agentopology scaffold — edit as needed.",
+            STUB_MARKER,
+            "set -euo pipefail",
+            "",
+            `# HYBRID SEAM (host -> embedded workflow). This step does NOT run`,
+            `# ${ownedAgents.join(", ")} as host subagent(s). Instead the host LAUNCHES the`,
+            `# deterministic workflow rung that owns ${phaseLabel}, emitted by the`,
+            `# claude-workflow binding as: ${workflowFile}`,
+            "#",
+            "# The rung reads its inputs from the Blackboard (seeded by the host's prior",
+            `# phase) and writes its results back so host hooks observe them LIVE.`,
+            root ? `# Blackboard root (shared by host + rung): ${root}` : "# Blackboard root: (memory.workspace.path not declared)",
+            `# Seam contract both bindings honor: ${seamDoc}`,
+            "#",
+            "# Claude Workflows are launched IN-SESSION via the /workflow keyword, not as a",
+            "# detached process. The orchestrator invokes the workflow at this step:",
+            "#",
+            `#     /workflow ${workflowFile}`,
+            "#",
+            "# If your harness launches workflows out-of-process instead, replace the line",
+            `# below with the real launcher (e.g. \`claude workflow ${workflowFile}\`).`,
+            "",
+            `echo "TODO: launch the workflow rung — invoke '/workflow ${workflowFile}' in-session (${phaseLabel}: ${ownedAgents.join(", ")})."`,
+            "",
+        ].join("\n");
+        files.push({
+            path: `.claude/skills/${name}/scripts/launch-${label}-workflow.sh`,
+            content: body,
+            category: "script",
+            executable: true,
+        });
+    }
+    return files;
+}
+/**
+ * HYBRID: build the "Hybrid run order" markdown block appended to the generated
+ * context file (.claude/CLAUDE.md) and the topology SKILL.md. It states the
+ * host's interleaving with the embedded workflow rung, in the SAME run-order
+ * vocabulary the claude-workflow binding's SEAM.md uses, so the two bindings
+ * stay in sync. Returns null when the topology is not a hybrid.
+ */
+function buildHybridRunOrderSection(ast) {
+    if (!isHybridTopology(ast))
+        return null;
+    const name = ast.topology.name;
+    const workflowFile = seamFiles.workflowScript(name);
+    const seamDoc = seamFiles.seamDoc(name);
+    const root = workspaceRoot(ast);
+    const wfPhases = workflowPhaseSet(ast);
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    const human = ast.nodes.find((n) => n.type === "human") ?? null;
+    const allPhases = [...new Set(agents.map(agentPhase))].sort((a, b) => a - b);
+    const idsInPhase = (p) => agents.filter((a) => agentPhase(a) === p).map((a) => a.id).join(", ");
+    const lines = [];
+    lines.push("## Hybrid run order");
+    lines.push("");
+    lines.push(`This topology is a **hybrid**: it composes the host (this \`.claude/\` tree) with an embedded deterministic workflow rung emitted by the \`claude-workflow\` binding as \`${workflowFile}\`. The host runs the host phases in-session; for the workflow-marked phase(s) it **launches the rung** and **observes** its Blackboard writes. Both sides honor the seam contract in \`${seamDoc}\`.`);
+    lines.push("");
+    if (root) {
+        lines.push(`**Blackboard root** (shared by host + rung): \`${root}\``);
+        lines.push("");
+    }
+    lines.push("Run order:");
+    lines.push("");
+    let step = 1;
+    for (const p of allPhases) {
+        if (wfPhases.has(p)) {
+            lines.push(`${step}. **Host launches \`${workflowFile}\`** for phase ${p} (${idsInPhase(p)}) — the deterministic rung. It reads the Blackboard inputs the host seeded, does the work, and writes its results back. Host hooks observe those writes LIVE (the concurrent observability the workflow rung itself cannot express). Launch via \`.claude/skills/${name}/scripts/launch-${workflowRunLabel(ast, [p])}-workflow.sh\` (i.e. \`/workflow ${workflowFile}\`).`);
+        }
+        else {
+            lines.push(`${step}. **Host (in-session)** runs phase ${p} (${idsInPhase(p)}) — writes its outputs to the Blackboard so the next rung can read them.`);
+        }
+        step++;
+    }
+    if (human) {
+        lines.push(`${step}. **Host** presents the Blackboard artifacts to the human \`${human.id}\`, who acts (e.g. promotes). Promotion triggers the SEPARATE downstream workflow.`);
+    }
+    lines.push("");
+    lines.push(`> This run order MUST match \`${seamDoc}\`'s "Run order" section (emitted by the claude-workflow binding). If you change one, change the other.`);
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * HYBRID: emit the host-layer concurrent Blackboard observer hook into
+ * settings.json.
+ *
+ * Rationale: the topology's `hooks { PostToolUse { matcher: "Write" ... } }`
+ * block is the bare-event form, which the parser does NOT currently surface into
+ * `ast.hooks` (only the named `hook <name> {}` form is parsed; changing the
+ * parser is out of scope). So we synthesize the observer hook from the presence
+ * of a Blackboard (`memory.workspace`): a Blackboard in a hybrid topology IMPLIES
+ * a host-side observer that watches the workflow rung's Write tool-calls live.
+ *
+ * Returns the hook entry to merge into settings.hooks.PostToolUse, or null.
+ */
+function buildHybridObserveHook(ast, topologyName) {
+    if (!isHybridTopology(ast))
+        return null;
+    if (!workspaceRoot(ast))
+        return null; // no Blackboard → no observer
+    // If a real ast.hook already targets PostToolUse/Write, the generic hook path
+    // emits it — don't double up.
+    const alreadyEmitted = ast.hooks.some((h) => h.on === "PostToolUse" && (h.matcher === "Write" || !h.matcher));
+    if (alreadyEmitted)
+        return null;
+    const scriptPath = `.claude/skills/${topologyName}/scripts/observe-blackboard.sh`;
+    return {
+        event: "PostToolUse",
+        scriptPath,
+        entry: {
+            matcher: "Write",
+            hooks: [
+                {
+                    type: "command",
+                    command: `bash ${scriptPath}`,
+                },
+            ],
+        },
+    };
+}
+/** HYBRID: the observe-blackboard.sh stub the observe-hook points at. */
+function generateObserveBlackboardScript(ast) {
+    const hook = buildHybridObserveHook(ast, ast.topology.name);
+    if (!hook)
+        return null;
+    const root = workspaceRoot(ast) ?? "workspace/";
+    const body = [
+        "#!/usr/bin/env bash",
+        "# Host-layer concurrent Blackboard observer.",
+        "# Auto-generated by agentopology scaffold — edit as needed.",
+        STUB_MARKER,
+        "set -euo pipefail",
+        "",
+        "# HYBRID SEAM (host observability for the embedded workflow rung).",
+        "# Wired as a PostToolUse(Write) hook in .claude/settings.json. It fires on every",
+        `# Write tool-call so the host can watch the Blackboard (${root}) the workflow`,
+        "# rung's agents write — that IS the concurrent observability the deterministic",
+        "# workflow rung itself cannot express. Stdin JSON payload is on FD 0.",
+        "",
+        "PAYLOAD=$(cat)",
+        `echo "TODO: observe Blackboard write under ${root} — inspect the payload and log/notify."`,
+        "",
+    ].join("\n");
+    return {
+        path: hook.scriptPath,
+        content: body,
+        category: "script",
+        executable: true,
+    };
+}
 /**
  * Merge `ast.env` into the settings.json output under an `env` key.
  *
@@ -2363,6 +2737,13 @@ export const claudeCodeBinding = {
         files.push(...generateHookScripts(ast));
         // Hook scripts (per-agent)
         files.push(...generateAgentHookScripts(ast));
+        // HYBRID: host-side launch directives for the embedded workflow rung(s).
+        files.push(...generateWorkflowLaunchArtifacts(ast));
+        // HYBRID: host-layer concurrent Blackboard observer script (paired with the
+        // synthesized PostToolUse(Write) hook in settings.json).
+        const observeScript = generateObserveBlackboardScript(ast);
+        if (observeScript)
+            files.push(observeScript);
         // Tool scripts
         files.push(...generateToolScripts(ast));
         // Schedule scripts