agentopology 0.1.0

package/dist/bindings/cursor.js

@@ -0,0 +1,1715 @@
+/**
+ * Cursor IDE binding.
+ *
+ * Generates `.cursor/rules/*.mdc`, `.cursor/mcp.json`, `.cursor/hooks.json`,
+ * `AGENTS.md`, and supporting shell scripts from a parsed {@link TopologyAST}.
+ *
+ * Cursor rules use `.mdc` files with YAML frontmatter supporting only three
+ * fields: `description`, `globs`, and `alwaysApply`. All other AST concepts
+ * are either mapped to hooks.json, shell scripts, or embedded as polyfill
+ * instructions in rule body text.
+ *
+ * @module
+ */
+import { deduplicateFiles } from "./types.js";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Convert a kebab-case id to Title Case. */
+function toTitle(id) {
+    return id
+        .split(/[-_]/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Downshift all markdown headings by one level so they nest properly
+ * inside ## Instructions. ## -> ###, ### -> ####, etc.
+ */
+function downshiftHeadings(text) {
+    return text.replace(/^(#{2,6})\s/gm, (_, hashes) => `#${hashes} `);
+}
+/**
+ * Generate .mdc-style YAML frontmatter.
+ *
+ * Only three fields are valid for Cursor: description, globs, alwaysApply.
+ * Fields with undefined/null values are omitted. When alwaysApply is false
+ * (the default), it is omitted.
+ */
+function frontmatter(fields) {
+    const lines = ["---"];
+    // Always emit all three fields (matching real-world .mdc convention).
+    // description and globs are empty when not set; alwaysApply defaults to false.
+    lines.push(`description: ${fields.description ?? ""}`);
+    if (fields.globs && fields.globs.length > 0) {
+        // Real .mdc files use comma-separated globs on a single line
+        lines.push(`globs: ${fields.globs.join(", ")}`);
+    }
+    else {
+        lines.push("globs:");
+    }
+    lines.push(`alwaysApply: ${fields.alwaysApply ? "true" : "false"}`);
+    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");
+}
+/** Generate an empty directory marker (a .gitkeep file). */
+function gitkeep(dirPath) {
+    return { path: `${dirPath}/.gitkeep`, content: "", category: "machine" };
+}
+/**
+ * Convert PascalCase .at hook event to camelCase Cursor event name.
+ * e.g. PreToolUse -> preToolUse, SessionStart -> sessionStart
+ */
+function mapHookEvent(atEvent) {
+    return atEvent.charAt(0).toLowerCase() + atEvent.slice(1);
+}
+/** Format a SchemaType to a human-readable string. */
+function formatSchemaType(t, schemas) {
+    switch (t.kind) {
+        case "primitive":
+            return t.value;
+        case "array":
+            return `${formatSchemaType(t.itemType, schemas)}[]`;
+        case "enum":
+            return t.values.join(" | ");
+        case "ref": {
+            if (schemas) {
+                const resolved = schemas.find((s) => s.id === t.name);
+                if (resolved) {
+                    const fields = resolved.fields.map((f) => `${f.name}${f.optional ? "?" : ""}: ${formatSchemaType(f.type, schemas)}`);
+                    return `${t.name} { ${fields.join(", ")} }`;
+                }
+            }
+            return t.name;
+        }
+    }
+}
+/** Format a SchemaFieldDef to a readable line. */
+function formatSchemaField(f) {
+    const opt = f.optional ? "?" : "";
+    return `- ${f.name}${opt}: ${formatSchemaType(f.type)}`;
+}
+/**
+ * Compile edges into natural-language workflow instructions.
+ */
+function compileEdges(ast) {
+    if (ast.edges.length === 0)
+        return "";
+    const lines = ["## Workflow", ""];
+    const nodeMap = new Map(ast.nodes.map((n) => [n.id, n.label]));
+    const label = (id) => nodeMap.get(id) ?? toTitle(id);
+    let step = 1;
+    for (const edge of ast.edges) {
+        const parts = [];
+        if (edge.isError) {
+            const errType = edge.errorType ? `${edge.errorType} ` : "";
+            parts.push(`${step}. On ${errType}error from **${label(edge.from)}**, route to **${label(edge.to)}**`);
+        }
+        else if (edge.condition) {
+            // Clean up condition: parser may include trailing "] [max N" artifacts
+            const cleanCondition = edge.condition
+                .replace(/\]\s*\[max\s+\d+\s*$/i, "")
+                .replace(/\]\s*$/, "")
+                .trim();
+            parts.push(`${step}. If ${cleanCondition}, proceed to **${label(edge.to)}**`);
+        }
+        else if (edge.reflection) {
+            parts.push(`${step}. Loop back to **${label(edge.from)}** for self-evaluation`);
+        }
+        else {
+            parts.push(`${step}. After **${label(edge.from)}**, proceed to **${label(edge.to)}**`);
+        }
+        if (edge.maxIterations) {
+            parts.push(`   - Repeat up to ${edge.maxIterations} times`);
+        }
+        if (edge.per) {
+            parts.push(`   - For each ${edge.per} item, run **${label(edge.to)}**`);
+        }
+        if (edge.race) {
+            parts.push(`   - Race **${label(edge.to)}** agents -- use first result`);
+        }
+        if (edge.tolerance != null) {
+            parts.push(`   - Allow up to ${edge.tolerance} failures`);
+        }
+        if (edge.wait) {
+            parts.push(`   - Wait ${edge.wait} before proceeding to **${label(edge.to)}**`);
+        }
+        if (edge.weight != null) {
+            parts.push(`   - Route to **${label(edge.to)}** with weight ${edge.weight}`);
+        }
+        lines.push(...parts);
+        step++;
+    }
+    // Delegation summary
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    if (agents.length > 0) {
+        lines.push("");
+        lines.push("### Delegation");
+        for (const agent of agents) {
+            const desc = agent.description ?? agent.label;
+            lines.push(`- **${agent.id}**: ${desc} -- activate with \`@${agent.id}\``);
+        }
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Section generators
+// ---------------------------------------------------------------------------
+/** Generate the topology overview rule (always-apply). */
+function generateTopologyOverview(ast) {
+    const orch = ast.nodes.find((n) => n.type === "orchestrator");
+    const fm = frontmatter({
+        description: ast.topology.description || `${ast.topology.name} topology overview`,
+        alwaysApply: true,
+    });
+    const sections = [fm, ""];
+    sections.push(`# ${ast.topology.name}`);
+    sections.push("");
+    sections.push(`<!-- Version: ${ast.topology.version} -->`);
+    sections.push("");
+    if (ast.topology.description) {
+        sections.push(ast.topology.description);
+        sections.push("");
+    }
+    // Orchestrator prompt merged in
+    if (orch) {
+        if (orch.model) {
+            sections.push(`**Model:** ${orch.model}`);
+            sections.push("");
+        }
+        if (orch.generates) {
+            sections.push(`**Generates:** ${orch.generates}`);
+            sections.push("");
+        }
+        if (orch.handles && orch.handles.length > 0) {
+            sections.push(`**Handles:** ${orch.handles.join(", ")}`);
+            sections.push("");
+        }
+        if (orch.outputs) {
+            sections.push("### Orchestrator Outputs");
+            for (const [field, values] of Object.entries(orch.outputs)) {
+                sections.push(`- ${field}: ${values.join(" | ")}`);
+            }
+            sections.push("");
+        }
+    }
+    // Agent table
+    const allAgents = ast.nodes.filter((n) => n.type === "agent" || n.type === "human" || n.type === "group");
+    if (allAgents.length > 0) {
+        sections.push("## Agents");
+        sections.push("");
+        sections.push("| Agent | Type | Description |");
+        sections.push("|-------|------|-------------|");
+        for (const node of allAgents) {
+            let desc = node.label;
+            if (node.type === "agent") {
+                desc = node.description ?? node.label;
+            }
+            else if (node.type === "human") {
+                desc = node.description ?? node.label;
+            }
+            else if (node.type === "group") {
+                desc = node.description ?? node.label;
+            }
+            sections.push(`| ${node.id} | ${node.type} | ${desc} |`);
+        }
+        sections.push("");
+    }
+    // Compiled edges
+    const edgeText = compileEdges(ast);
+    if (edgeText) {
+        sections.push(edgeText);
+    }
+    // Defaults
+    if (ast.defaults) {
+        const d = ast.defaults;
+        sections.push("## Defaults");
+        sections.push("");
+        if (d.temperature != null)
+            sections.push(`- Temperature: ${d.temperature}`);
+        if (d.maxTokens != null)
+            sections.push(`- Max tokens: ${d.maxTokens}`);
+        if (d.topP != null)
+            sections.push(`- Top-p: ${d.topP}`);
+        if (d.topK != null)
+            sections.push(`- Top-k: ${d.topK}`);
+        if (d.stop)
+            sections.push(`- Stop sequences: ${d.stop.join(", ")}`);
+        if (d.seed != null)
+            sections.push(`- Seed: ${d.seed}`);
+        if (d.thinking)
+            sections.push(`- Thinking: ${d.thinking}`);
+        if (d.thinkingBudget != null)
+            sections.push(`- Thinking budget: ${d.thinkingBudget}`);
+        if (d.outputFormat)
+            sections.push(`- Output format: ${d.outputFormat}`);
+        if (d.timeout)
+            sections.push(`- Timeout: ${d.timeout}`);
+        if (d.logLevel)
+            sections.push(`- Log level: ${d.logLevel}`);
+        sections.push("");
+    }
+    // Settings as behavioral instructions
+    if (ast.settings && Object.keys(ast.settings).length > 0) {
+        sections.push("## Settings");
+        sections.push("");
+        for (const [key, value] of Object.entries(ast.settings)) {
+            if (Array.isArray(value)) {
+                sections.push(`- ${key}: ${value.join(", ")}`);
+            }
+            else {
+                sections.push(`- ${key}: ${JSON.stringify(value)}`);
+            }
+        }
+        sections.push("");
+    }
+    // Depth levels
+    if (ast.depth && ast.depth.levels && ast.depth.levels.length > 0) {
+        sections.push("<!-- Depth levels:");
+        if (ast.depth.factors.length > 0) {
+            sections.push(`  Factors: ${ast.depth.factors.join(", ")}`);
+        }
+        for (const level of ast.depth.levels) {
+            let line = `  Level ${level.level}: ${level.label}`;
+            if (level.omit.length > 0)
+                line += ` (omit: ${level.omit.join(", ")})`;
+            sections.push(line);
+        }
+        sections.push("-->");
+        sections.push("");
+    }
+    // Batch
+    if (ast.batch && Object.keys(ast.batch).length > 0) {
+        sections.push("## Batch");
+        sections.push("");
+        for (const [key, value] of Object.entries(ast.batch)) {
+            sections.push(`- ${key}: ${JSON.stringify(value)}`);
+        }
+        sections.push("");
+    }
+    // Environments
+    if (ast.environments && Object.keys(ast.environments).length > 0) {
+        sections.push("<!-- Environments:");
+        for (const [envName, envConfig] of Object.entries(ast.environments)) {
+            sections.push(`  ${envName}:`);
+            for (const [key, value] of Object.entries(envConfig)) {
+                sections.push(`    ${key}: ${JSON.stringify(value)}`);
+            }
+        }
+        sections.push("-->");
+        sections.push("");
+    }
+    // Providers
+    if (ast.providers && ast.providers.length > 0) {
+        sections.push("<!-- Providers:");
+        for (const provider of ast.providers) {
+            let line = `  ${provider.name}`;
+            if (provider.default)
+                line += " (default)";
+            if (provider.models.length > 0)
+                line += ` -- models: ${provider.models.join(", ")}`;
+            sections.push(line);
+        }
+        sections.push("-->");
+        sections.push("");
+    }
+    // Schedules
+    if (ast.schedules.length > 0) {
+        sections.push("<!-- Schedules:");
+        for (const job of ast.schedules) {
+            const expr = job.cron
+                ? `cron: ${job.cron}`
+                : job.every
+                    ? `every: ${job.every}`
+                    : "";
+            const target = job.agent
+                ? `agent: ${job.agent}`
+                : job.action
+                    ? `action: ${job.action}`
+                    : "";
+            sections.push(`  ${job.id}: ${expr}${target ? ` -> ${target}` : ""}${job.enabled === false ? " (disabled)" : ""}`);
+        }
+        sections.push("-->");
+        sections.push("");
+    }
+    // Interfaces
+    if (ast.interfaces.length > 0) {
+        sections.push("<!-- Interfaces:");
+        for (const iface of ast.interfaces) {
+            const typePart = iface.type ? ` (${iface.type})` : "";
+            sections.push(`  ${iface.id}${typePart}`);
+        }
+        sections.push("-->");
+        sections.push("");
+    }
+    // Pattern metadata
+    if (ast.topology.patterns.length > 0) {
+        sections.push(`<!-- Patterns: ${ast.topology.patterns.join(", ")} -->`);
+    }
+    if (ast.topology.domain) {
+        sections.push(`<!-- Domain: ${ast.topology.domain} -->`);
+    }
+    if (ast.topology.foundations && ast.topology.foundations.length > 0) {
+        sections.push(`<!-- Foundations: ${ast.topology.foundations.join(", ")} -->`);
+    }
+    if (ast.topology.advanced && ast.topology.advanced.length > 0) {
+        sections.push(`<!-- Advanced: ${ast.topology.advanced.join(", ")} -->`);
+    }
+    if (ast.topology.durable) {
+        sections.push("<!-- Durable: yes -->");
+    }
+    if (ast.topology.timeout) {
+        sections.push(`<!-- Timeout: ${ast.topology.timeout} -->`);
+    }
+    if (ast.topology.errorHandler) {
+        sections.push(`<!-- Error handler: ${ast.topology.errorHandler} -->`);
+    }
+    // Params
+    if (ast.params && ast.params.length > 0) {
+        sections.push("<!-- Parameters:");
+        for (const p of ast.params) {
+            const req = p.required ? " (required)" : "";
+            const def = p.default != null ? ` = ${p.default}` : "";
+            sections.push(`  ${p.name}: ${p.type}${req}${def}`);
+        }
+        sections.push("-->");
+    }
+    // Interface endpoints
+    if (ast.interfaceEndpoints) {
+        sections.push(`<!-- Interface: entry=${ast.interfaceEndpoints.entry}, exit=${ast.interfaceEndpoints.exit} -->`);
+    }
+    // Imports
+    if (ast.imports && ast.imports.length > 0) {
+        sections.push("<!-- Imports:");
+        for (const imp of ast.imports) {
+            let line = `  ${imp.alias} from ${imp.source}`;
+            if (imp.sha256)
+                line += ` (sha256: ${imp.sha256})`;
+            sections.push(line);
+        }
+        sections.push("-->");
+    }
+    // Checkpoint
+    if (ast.checkpoint) {
+        const cp = ast.checkpoint;
+        sections.push("<!-- Checkpoint:");
+        sections.push(`  backend: ${cp.backend}`);
+        sections.push(`  strategy: ${cp.strategy}`);
+        if (cp.connection)
+            sections.push(`  connection: ${cp.connection}`);
+        if (cp.ttl)
+            sections.push(`  ttl: ${cp.ttl}`);
+        if (cp.replay) {
+            sections.push(`  replay: ${cp.replay.enabled ? "enabled" : "disabled"}`);
+        }
+        sections.push("-->");
+    }
+    // Artifacts
+    if (ast.artifacts && ast.artifacts.length > 0) {
+        sections.push("<!-- Artifacts:");
+        for (const a of ast.artifacts) {
+            let line = `  ${a.id} (${a.type})`;
+            if (a.path)
+                line += ` -- path: ${a.path}`;
+            if (a.retention)
+                line += `, retention: ${a.retention}`;
+            sections.push(line);
+        }
+        sections.push("-->");
+    }
+    sections.push("");
+    return {
+        path: ".cursor/rules/topology-overview.mdc",
+        content: sections.join("\n"),
+        category: "agent",
+    };
+}
+/** Generate .mdc rule files for each AgentNode. */
+function generateAgentRules(ast) {
+    const files = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "agent")
+            continue;
+        const agent = node;
+        // Warn about impossible features
+        if (agent.permissions) {
+            console.warn(`[cursor] Warning: permission "${agent.permissions}" has no Cursor equivalent -- skipped.`);
+        }
+        if (agent.isolation) {
+            console.warn(`[cursor] Warning: isolation "${agent.isolation}" has no Cursor equivalent -- skipped.`);
+        }
+        // Build frontmatter
+        const fm = {};
+        fm.description = agent.description ?? agent.label;
+        // Cursor-specific globs extension
+        const cursorExt = agent.extensions?.cursor;
+        if (cursorExt?.globs) {
+            fm.globs = cursorExt.globs;
+        }
+        // alwaysApply override
+        if (cursorExt?.alwaysApply) {
+            fm.alwaysApply = true;
+        }
+        // Manual invocation: omit description to make it @-mention only
+        if (agent.invocation === "manual") {
+            delete fm.description;
+        }
+        // Build body
+        const sections = [frontmatter(fm), ""];
+        sections.push(`# ${agent.label || toTitle(agent.id)}`);
+        sections.push("");
+        // Role text
+        const roleText = ast.roles[agent.role ?? ""] ?? ast.roles[agent.id] ?? agent.role;
+        if (roleText) {
+            sections.push(roleText);
+            sections.push("");
+        }
+        // Phase comment
+        if (agent.phase != null) {
+            sections.push(`<!-- Phase: ${agent.phase} -->`);
+            sections.push("");
+        }
+        // Model instruction
+        if (agent.model) {
+            sections.push(`**Model:** ${agent.model}`);
+            sections.push("");
+        }
+        // Instructions
+        sections.push("## Instructions");
+        sections.push("");
+        if (agent.prompt) {
+            sections.push(downshiftHeadings(agent.prompt));
+        }
+        else {
+            sections.push(`${agent.description || agent.role || "Complete the assigned task."}`);
+        }
+        sections.push("");
+        // Tools
+        if (agent.tools && agent.tools.length > 0) {
+            sections.push("## Tools");
+            for (const tool of agent.tools) {
+                sections.push(`- ${tool}`);
+            }
+            sections.push("");
+        }
+        // Disallowed tools
+        if (agent.disallowedTools && agent.disallowedTools.length > 0) {
+            sections.push("## Disallowed Tools");
+            sections.push(`**Do NOT use:** ${agent.disallowedTools.join(", ")}`);
+            sections.push("");
+        }
+        // Skills references
+        if (agent.skills && agent.skills.length > 0) {
+            sections.push("## Skills");
+            for (const skill of agent.skills) {
+                sections.push(`- @skill-${skill}`);
+            }
+            sections.push("");
+        }
+        // Memory: reads/writes
+        if ((agent.reads && agent.reads.length > 0) ||
+            (agent.writes && agent.writes.length > 0)) {
+            sections.push("## Memory");
+            if (agent.reads && agent.reads.length > 0) {
+                sections.push(`**Reads:** ${agent.reads.join(", ")}`);
+            }
+            if (agent.writes && agent.writes.length > 0) {
+                sections.push(`**Writes:** ${agent.writes.join(", ")}`);
+            }
+            sections.push("");
+        }
+        // Outputs
+        if (agent.outputs) {
+            sections.push("## Outputs");
+            for (const [field, values] of Object.entries(agent.outputs)) {
+                sections.push(`- ${field}: ${values.join(" | ")}`);
+            }
+            sections.push("");
+        }
+        // Sampling params
+        const hasModelConfig = agent.temperature != null ||
+            agent.maxTokens != null ||
+            agent.topP != null ||
+            agent.topK != null ||
+            agent.stop != null ||
+            agent.seed != null;
+        if (hasModelConfig) {
+            sections.push("## Model Configuration");
+            if (agent.temperature != null)
+                sections.push(`- Temperature: ${agent.temperature}`);
+            if (agent.maxTokens != null)
+                sections.push(`- Max tokens: ${agent.maxTokens}`);
+            if (agent.topP != null)
+                sections.push(`- Top-p: ${agent.topP}`);
+            if (agent.topK != null)
+                sections.push(`- Top-k: ${agent.topK}`);
+            if (agent.stop)
+                sections.push(`- Stop sequences: ${agent.stop.join(", ")}`);
+            if (agent.seed != null)
+                sections.push(`- Seed: ${agent.seed}`);
+            sections.push("");
+        }
+        // Thinking
+        if (agent.thinking) {
+            let thinkingLine = `Use ${agent.thinking} level reasoning.`;
+            if (agent.thinkingBudget != null) {
+                thinkingLine = `Use ${agent.thinking} level reasoning (budget: ${agent.thinkingBudget} tokens).`;
+            }
+            sections.push(thinkingLine);
+            sections.push("");
+        }
+        // Output format
+        if (agent.outputFormat) {
+            sections.push(`Output format: ${agent.outputFormat}`);
+            sections.push("");
+        }
+        // Log level
+        if (agent.logLevel) {
+            sections.push(`<!-- Log level: ${agent.logLevel} -->`);
+            sections.push("");
+        }
+        // Timeout
+        if (agent.timeout) {
+            sections.push(`**Timeout:** ${agent.timeout}`);
+            sections.push("");
+        }
+        // Max turns
+        if (agent.maxTurns != null) {
+            sections.push(`**Max turns:** ${agent.maxTurns}`);
+            sections.push("");
+        }
+        // On fail
+        if (agent.onFail) {
+            sections.push(`If you fail: ${agent.onFail}`);
+            sections.push("");
+        }
+        // Retry
+        if (agent.retry != null) {
+            if (typeof agent.retry === "number") {
+                sections.push(`**Retry:** up to ${agent.retry} times`);
+            }
+            else {
+                const r = agent.retry;
+                const parts = [`max ${r.max} attempts`];
+                if (r.backoff)
+                    parts.push(`${r.backoff} backoff`);
+                if (r.interval)
+                    parts.push(`interval ${r.interval}`);
+                if (r.maxInterval)
+                    parts.push(`max interval ${r.maxInterval}`);
+                if (r.jitter)
+                    parts.push("with jitter");
+                if (r.nonRetryable && r.nonRetryable.length > 0) {
+                    parts.push(`non-retryable: ${r.nonRetryable.join(", ")}`);
+                }
+                sections.push(`Retry strategy: ${parts.join(", ")}.`);
+            }
+            sections.push("");
+        }
+        // Circuit breaker
+        if (agent.circuitBreaker) {
+            const cb = agent.circuitBreaker;
+            sections.push("## Circuit Breaker");
+            sections.push(`- Failure threshold: ${cb.threshold}`);
+            sections.push(`- Window: ${cb.window}`);
+            sections.push(`- Cooldown: ${cb.cooldown}`);
+            sections.push("");
+        }
+        // Compensates
+        if (agent.compensates) {
+            sections.push(`This agent compensates (can undo) the work of: ${agent.compensates}`);
+            sections.push("");
+        }
+        // Input Schema
+        if (agent.inputSchema && agent.inputSchema.length > 0) {
+            sections.push("## Input Schema");
+            for (const field of agent.inputSchema) {
+                sections.push(formatSchemaField(field));
+            }
+            sections.push("");
+        }
+        // Output Schema
+        if (agent.outputSchema && agent.outputSchema.length > 0) {
+            sections.push("## Output Schema");
+            for (const field of agent.outputSchema) {
+                sections.push(formatSchemaField(field));
+            }
+            sections.push("");
+        }
+        // Rate limit
+        if (agent.rateLimit) {
+            sections.push(`Rate limit: ${agent.rateLimit}`);
+            sections.push("");
+        }
+        // Artifacts: produces/consumes
+        if ((agent.produces && agent.produces.length > 0) ||
+            (agent.consumes && agent.consumes.length > 0)) {
+            sections.push("## Artifacts");
+            if (agent.produces && agent.produces.length > 0) {
+                sections.push(`Produces: ${agent.produces.join(", ")}`);
+            }
+            if (agent.consumes && agent.consumes.length > 0) {
+                sections.push(`Consumes: ${agent.consumes.join(", ")}`);
+            }
+            sections.push("");
+        }
+        // Variants
+        if (agent.variants && agent.variants.length > 0) {
+            sections.push("## Variants");
+            for (const v of agent.variants) {
+                const parts = [`**${v.id}** (weight: ${v.weight})`];
+                if (v.model)
+                    parts.push(`model: ${v.model}`);
+                if (v.temperature != null)
+                    parts.push(`temperature: ${v.temperature}`);
+                sections.push(`- ${parts.join(", ")}`);
+                if (v.prompt) {
+                    sections.push(`  Prompt: ${v.prompt}`);
+                }
+            }
+            sections.push("");
+        }
+        // Scale
+        if (agent.scale) {
+            const s = agent.scale;
+            sections.push("## Scale");
+            sections.push(`- Mode: ${s.mode}`);
+            sections.push(`- By: ${s.by}`);
+            sections.push(`- Min: ${s.min}`);
+            sections.push(`- Max: ${s.max}`);
+            if (s.batchSize != null)
+                sections.push(`- Batch size: ${s.batchSize}`);
+            sections.push("");
+        }
+        // Sandbox
+        if (agent.sandbox != null) {
+            sections.push(`Sandbox: ${agent.sandbox}`);
+            sections.push("");
+        }
+        // Fallback chain
+        if (agent.fallbackChain && agent.fallbackChain.length > 0) {
+            sections.push(`Fallback chain: ${agent.fallbackChain.join(" -> ")}`);
+            sections.push("");
+        }
+        // Join
+        if (agent.join) {
+            sections.push(`Wait strategy: ${agent.join} (wait for upstream agents)`);
+            sections.push("");
+        }
+        // Background
+        if (agent.background) {
+            sections.push("This agent runs in the background.");
+            sections.push("");
+        }
+        // Skip
+        if (agent.skip) {
+            sections.push(`Skip when: ${agent.skip}`);
+            sections.push("");
+        }
+        // Behavior
+        if (agent.behavior) {
+            sections.push(`**Behavior:** ${agent.behavior}`);
+            sections.push("");
+        }
+        files.push({
+            path: `.cursor/rules/${agent.id}.mdc`,
+            content: sections.join("\n"),
+            category: "agent",
+        });
+    }
+    return files;
+}
+/** Generate .mdc rule files for each HumanNode. */
+function generateHumanRules(ast) {
+    const files = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "human")
+            continue;
+        const human = node;
+        const fm = frontmatter({
+            description: human.description ?? `Human approval required: ${human.label}`,
+        });
+        const sections = [fm, ""];
+        sections.push(`# ${human.label || toTitle(human.id)}`);
+        sections.push("");
+        sections.push("This step requires human review and approval.");
+        sections.push("");
+        if (human.description) {
+            sections.push(human.description);
+            sections.push("");
+        }
+        sections.push("## Process");
+        sections.push("1. Review the current state and outputs");
+        sections.push("2. Approve or reject the proposed changes");
+        sections.push("3. Provide feedback if rejecting");
+        sections.push("");
+        if (human.timeout) {
+            sections.push(`**Timeout:** ${human.timeout}`);
+            sections.push("");
+        }
+        if (human.onTimeout) {
+            sections.push(`**On timeout:** ${human.onTimeout}`);
+            sections.push("");
+        }
+        files.push({
+            path: `.cursor/rules/${human.id}.mdc`,
+            content: sections.join("\n"),
+            category: "agent",
+        });
+    }
+    return files;
+}
+/** Generate .mdc rule files for each GroupNode. */
+function generateGroupRules(ast) {
+    const files = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "group")
+            continue;
+        const group = node;
+        const fm = frontmatter({
+            description: group.description ?? `Group: ${group.label}`,
+        });
+        const sections = [fm, ""];
+        sections.push(`# ${group.label || toTitle(group.id)}`);
+        sections.push("");
+        sections.push("## Members");
+        for (const member of group.members) {
+            sections.push(`- @${member}`);
+        }
+        sections.push("");
+        sections.push("## Interaction Pattern");
+        if (group.speakerSelection) {
+            sections.push(`Speaker selection: ${group.speakerSelection}`);
+        }
+        if (group.maxRounds != null) {
+            sections.push(`Max rounds: ${group.maxRounds}`);
+        }
+        if (group.termination) {
+            sections.push(`Termination: ${group.termination}`);
+        }
+        if (group.timeout) {
+            sections.push(`Timeout: ${group.timeout}`);
+        }
+        sections.push("");
+        files.push({
+            path: `.cursor/rules/${group.id}.mdc`,
+            content: sections.join("\n"),
+            category: "agent",
+        });
+    }
+    return files;
+}
+/** Generate shell scripts for each ActionNode. */
+function generateActionScripts(ast) {
+    const files = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "action")
+            continue;
+        const action = node;
+        const lines = ["#!/usr/bin/env bash"];
+        lines.push(`# Action: ${action.id} -- ${action.description ?? action.label}`);
+        lines.push("# Auto-generated by agentopology scaffold -- edit as needed.");
+        lines.push("set -euo pipefail");
+        lines.push("");
+        if (action.timeout) {
+            lines.push(`# Timeout: ${action.timeout}`);
+        }
+        if (action.onFail) {
+            lines.push(`# On failure: ${action.onFail}`);
+        }
+        if (action.join) {
+            lines.push(`# Join semantics: ${action.join}`);
+        }
+        switch (action.kind) {
+            case "external":
+                lines.push(`# External source: ${action.source ?? "unknown"}`);
+                lines.push("");
+                lines.push(`echo "TODO: implement external action -- fetch from ${action.source ?? "source"}"`);
+                break;
+            case "inline":
+                if (action.commands && action.commands.length > 0) {
+                    lines.push("");
+                    for (const cmd of action.commands) {
+                        lines.push(cmd);
+                    }
+                }
+                else {
+                    lines.push("");
+                    lines.push('echo "TODO: implement inline action"');
+                }
+                break;
+            case "git":
+                lines.push("");
+                lines.push("# Git operation");
+                if (action.commands && action.commands.length > 0) {
+                    for (const cmd of action.commands) {
+                        lines.push(cmd);
+                    }
+                }
+                else {
+                    lines.push('echo "TODO: implement git action"');
+                }
+                break;
+            case "report":
+                lines.push("");
+                lines.push("# Report generation");
+                lines.push('echo "TODO: implement report action"');
+                break;
+            default:
+                lines.push("");
+                lines.push(`echo "TODO: implement ${action.kind ?? "unknown"} action"`);
+                break;
+        }
+        lines.push("");
+        files.push({
+            path: `.cursor/scripts/actions/${action.id}.sh`,
+            content: lines.join("\n"),
+            category: "script",
+        });
+    }
+    return files;
+}
+/**
+ * Generate gate hooks and scripts.
+ *
+ * Returns gate scripts as GeneratedFile[]. The hook entries are collected
+ * by generateHooksJson separately.
+ */
+function generateGateHooks(ast) {
+    const files = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "gate")
+            continue;
+        const gate = node;
+        const lines = [
+            "#!/usr/bin/env bash",
+            `# Gate: ${gate.id}`,
+            "# Auto-generated by agentopology scaffold -- edit as needed.",
+            "set -euo pipefail",
+            "",
+        ];
+        lines.push(`# After: ${gate.after ?? "any"}`);
+        lines.push(`# Before: ${gate.before ?? "any"}`);
+        if (gate.onFail)
+            lines.push(`# On failure: ${gate.onFail}`);
+        if (gate.behavior)
+            lines.push(`# Behavior: ${gate.behavior}`);
+        if (gate.timeout)
+            lines.push(`# Timeout: ${gate.timeout}`);
+        lines.push("");
+        if (gate.run) {
+            lines.push(`# Run: ${gate.run}`);
+            lines.push("");
+            if (gate.retry != null && gate.retry > 0) {
+                lines.push(`MAX_RETRIES=${gate.retry}`);
+                lines.push("ATTEMPT=0");
+                lines.push("GATE_RESULT=1");
+                lines.push("");
+                lines.push("while [ $ATTEMPT -le $MAX_RETRIES ] && [ $GATE_RESULT -ne 0 ]; do");
+                lines.push("  ATTEMPT=$((ATTEMPT + 1))");
+                lines.push(`  ${gate.run} && GATE_RESULT=0 || GATE_RESULT=$?`);
+                lines.push('  if [ $GATE_RESULT -ne 0 ] && [ $ATTEMPT -le $MAX_RETRIES ]; then');
+                lines.push(`    echo "Gate '${gate.id}' attempt $ATTEMPT failed, retrying..."`);
+                lines.push("    sleep 1");
+                lines.push("  fi");
+                lines.push("done");
+            }
+            else {
+                lines.push("GATE_RESULT=0");
+                lines.push(`${gate.run} || GATE_RESULT=$?`);
+            }
+        }
+        else if (gate.checks && gate.checks.length > 0) {
+            lines.push("# Checks:");
+            lines.push("GATE_RESULT=0");
+            lines.push("");
+            for (const check of gate.checks) {
+                lines.push(`# Check: ${check}`);
+                lines.push(`echo "TODO: implement check '${check}'"  # || GATE_RESULT=1`);
+            }
+        }
+        else {
+            lines.push("GATE_RESULT=0");
+            lines.push('echo "TODO: implement gate check"');
+        }
+        lines.push("");
+        const exitAction = gate.onFail === "halt" || gate.behavior === "blocking"
+            ? "exit 1"
+            : 'echo "Gate failed -- advisory only"';
+        lines.push('if [ "$GATE_RESULT" -ne 0 ]; then');
+        lines.push(`  echo "Gate '${gate.id}' FAILED (exit code $GATE_RESULT)"`);
+        lines.push(`  ${exitAction}`);
+        lines.push("fi");
+        lines.push("");
+        files.push({
+            path: `.cursor/hooks/gate-${gate.id}.sh`,
+            content: lines.join("\n"),
+            category: "script",
+        });
+    }
+    return files;
+}
+/** Generate .mdc rule files for each SkillDef. */
+function generateSkillRules(ast) {
+    const files = [];
+    for (const skill of ast.skills) {
+        const isManual = skill.userInvocable === true;
+        const fm = isManual
+            ? frontmatter({})
+            : frontmatter({ description: skill.description || skill.id });
+        const sections = [fm, ""];
+        sections.push(`# ${toTitle(skill.id)}`);
+        sections.push("");
+        if (skill.description) {
+            sections.push(skill.description);
+            sections.push("");
+        }
+        // Prompt content
+        if (skill.prompt) {
+            sections.push(`See: ${skill.prompt}`);
+            sections.push("");
+        }
+        // Scripts references
+        if (skill.scripts && skill.scripts.length > 0) {
+            sections.push("## Scripts");
+            for (const s of skill.scripts) {
+                sections.push(`- ${s}`);
+            }
+            sections.push("");
+        }
+        // Domains references
+        if (skill.domains && skill.domains.length > 0) {
+            sections.push("## Domains");
+            for (const d of skill.domains) {
+                sections.push(`- ${d}`);
+            }
+            sections.push("");
+        }
+        // File references
+        if (skill.references && skill.references.length > 0) {
+            sections.push("## References");
+            for (const r of skill.references) {
+                sections.push(`- @${r}`);
+            }
+            sections.push("");
+        }
+        // Allowed tools
+        if (skill.allowedTools && skill.allowedTools.length > 0) {
+            sections.push("## Allowed Tools");
+            for (const tool of skill.allowedTools) {
+                sections.push(`- ${tool}`);
+            }
+            sections.push("");
+        }
+        // disableModelInvocation
+        if (skill.disableModelInvocation) {
+            sections.push("**Note:** Model invocation is disabled for this skill. Execute scripts directly.");
+            sections.push("");
+        }
+        // Context mode
+        if (skill.context) {
+            sections.push(`<!-- Context mode: ${skill.context} -->`);
+        }
+        // Agent type
+        if (skill.agent) {
+            sections.push(`<!-- Agent type: ${skill.agent} -->`);
+        }
+        files.push({
+            path: `.cursor/rules/skill-${skill.id}.mdc`,
+            content: sections.join("\n"),
+            category: "agent",
+        });
+    }
+    return files;
+}
+/** Generate .mdc rule files for each TriggerDef. */
+function generateTriggerRules(ast) {
+    const files = [];
+    for (const trigger of ast.triggers) {
+        // Manual rule -- empty frontmatter
+        const fm = frontmatter({});
+        const sections = [fm, ""];
+        sections.push(`# ${toTitle(trigger.name)}`);
+        sections.push("");
+        sections.push(trigger.pattern);
+        sections.push("");
+        if (trigger.argument) {
+            sections.push("## Arguments");
+            sections.push(`- ${trigger.argument}: extracted from the command pattern`);
+            sections.push("");
+        }
+        files.push({
+            path: `.cursor/rules/trigger-${trigger.name}.mdc`,
+            content: sections.join("\n"),
+            category: "agent",
+        });
+    }
+    return files;
+}
+/** Generate .cursor/mcp.json from global and per-agent MCP servers. */
+function generateMcpJson(ast) {
+    // Collect all MCP servers (global + per-agent)
+    const allServers = {};
+    // Global MCP servers
+    for (const [name, config] of Object.entries(ast.mcpServers)) {
+        allServers[name] = config;
+    }
+    // Per-agent MCP servers: merge by reference
+    for (const node of ast.nodes) {
+        if (node.type !== "agent")
+            continue;
+        const agent = node;
+        if (!agent.mcpServers || agent.mcpServers.length === 0)
+            continue;
+        // Agent mcpServers are just names (strings), they reference global config
+        // The actual config comes from ast.mcpServers
+    }
+    if (Object.keys(allServers).length === 0)
+        return null;
+    const mcpConfig = { mcpServers: {} };
+    const servers = mcpConfig.mcpServers;
+    for (const [name, config] of Object.entries(allServers)) {
+        const entry = {};
+        for (const [key, value] of Object.entries(config)) {
+            if (key === "env" && typeof value === "object" && value !== null) {
+                // Handle SensitiveValue env vars
+                const envObj = {};
+                for (const [envKey, envVal] of Object.entries(value)) {
+                    if (typeof envVal === "string") {
+                        envObj[envKey] = envVal;
+                    }
+                    else if (typeof envVal === "object" &&
+                        envVal !== null &&
+                        "value" in envVal) {
+                        const sv = envVal;
+                        if (sv.sensitive) {
+                            envObj[envKey] = `\${${envKey}}`;
+                        }
+                        else {
+                            envObj[envKey] = sv.value;
+                        }
+                    }
+                }
+                entry.env = envObj;
+            }
+            else if (key === "args" && Array.isArray(value)) {
+                entry.args = value;
+            }
+            else if (key === "command" || key === "url") {
+                // Valid MCP server fields: command (stdio), url (SSE)
+                entry[key] = value;
+            }
+            // Skip unknown fields — the parser may leak env vars to top level
+        }
+        // Only include servers that have a command or url (filter parser artifacts)
+        if (!("command" in entry) && !("url" in entry))
+            continue;
+        servers[name] = entry;
+    }
+    return {
+        path: ".cursor/mcp.json",
+        content: JSON.stringify(mcpConfig, null, 2) + "\n",
+        category: "shared-config",
+    };
+}
+/**
+ * Generate .cursor/hooks.json from global hooks, per-agent hooks, gate nodes,
+ * and metering configuration.
+ */
+function generateHooksJson(ast) {
+    const hooksByEvent = {};
+    // Helper to add a hook entry
+    const addHook = (event, entry) => {
+        if (!hooksByEvent[event])
+            hooksByEvent[event] = [];
+        hooksByEvent[event].push(entry);
+    };
+    // Global hooks
+    for (const hook of ast.hooks) {
+        const event = mapHookEvent(hook.on);
+        const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+        const command = hook.run.startsWith("./")
+            ? hook.run
+            : `.cursor/hooks/${scriptName}`;
+        const cursorExt = hook.extensions?.cursor;
+        const entry = {
+            command,
+        };
+        if (hook.matcher)
+            entry.matcher = hook.matcher;
+        if (hook.timeout != null)
+            entry.timeout = Math.ceil(hook.timeout / 1000);
+        // Cursor hooks do NOT have a `type` field (unlike Claude Code).
+        // Only include failClosed when true (false is the default).
+        const failClosed = cursorExt?.failClosed ?? false;
+        if (failClosed)
+            entry.failClosed = true;
+        if (cursorExt?.loop_limit != null) {
+            entry.loop_limit = cursorExt.loop_limit;
+        }
+        addHook(event, entry);
+    }
+    // Per-agent hooks
+    for (const node of ast.nodes) {
+        if (node.type !== "agent")
+            continue;
+        const agent = node;
+        if (!agent.hooks || agent.hooks.length === 0)
+            continue;
+        for (const hook of agent.hooks) {
+            const event = mapHookEvent(hook.on);
+            const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+            const command = hook.run.startsWith("./")
+                ? hook.run
+                : `.cursor/hooks/${agent.id}-${scriptName}`;
+            const cursorExt = hook.extensions?.cursor;
+            const entry = {
+                command,
+            };
+            if (hook.matcher)
+                entry.matcher = hook.matcher;
+            else
+                entry.matcher = agent.id;
+            if (hook.timeout != null)
+                entry.timeout = Math.ceil(hook.timeout / 1000);
+            // Cursor hooks do NOT have a `type` field.
+            const agentFailClosed = cursorExt?.failClosed ?? false;
+            if (agentFailClosed)
+                entry.failClosed = true;
+            if (cursorExt?.loop_limit != null) {
+                entry.loop_limit = cursorExt.loop_limit;
+            }
+            addHook(event, entry);
+        }
+    }
+    // Gate compilation to hooks
+    const gates = ast.nodes.filter((n) => n.type === "gate");
+    for (const gate of gates) {
+        const scriptPath = `.cursor/hooks/gate-${gate.id}.sh`;
+        // Determine event
+        let event;
+        if (gate.before) {
+            event = "preToolUse";
+        }
+        else if (gate.after) {
+            event = "postToolUse";
+        }
+        else {
+            event = "preToolUse";
+        }
+        // Determine matcher
+        const matcher = gate.after ?? gate.before ?? undefined;
+        // Determine failClosed
+        const failClosed = gate.behavior === "blocking" || gate.onFail === "halt";
+        const entry = {
+            command: scriptPath,
+        };
+        if (failClosed)
+            entry.failClosed = true;
+        if (matcher)
+            entry.matcher = matcher;
+        if (gate.timeout) {
+            // Parse duration string to seconds (best-effort)
+            const match = gate.timeout.match(/^(\d+)(s|m|h)?$/);
+            if (match) {
+                const val = parseInt(match[1], 10);
+                const unit = match[2] ?? "s";
+                const seconds = unit === "h" ? val * 3600 : unit === "m" ? val * 60 : val;
+                entry.timeout = seconds;
+            }
+        }
+        const cursorExt = gate.extensions?.cursor;
+        if (cursorExt?.loop_limit != null) {
+            entry.loop_limit = cursorExt.loop_limit;
+        }
+        addHook(event, entry);
+    }
+    // Metering -> postToolUse hook
+    if (ast.metering) {
+        addHook("postToolUse", {
+            command: ".cursor/hooks/metering.sh",
+        });
+    }
+    if (Object.keys(hooksByEvent).length === 0)
+        return null;
+    const hooksJson = {
+        version: 1,
+        hooks: hooksByEvent,
+    };
+    return {
+        path: ".cursor/hooks.json",
+        content: JSON.stringify(hooksJson, null, 2) + "\n",
+        category: "shared-config",
+    };
+}
+/** Generate hook script stubs for global hooks. */
+function generateHookScripts(ast) {
+    const files = [];
+    for (const hook of ast.hooks) {
+        if (!hook.run)
+            continue;
+        // Skip if run already has an absolute/relative path prefix (external script)
+        if (hook.run.startsWith("./") || hook.run.startsWith("/"))
+            continue;
+        const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+        files.push({
+            path: `.cursor/hooks/${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"),
+            category: "script",
+        });
+    }
+    return files;
+}
+/** Generate per-agent hook script stubs. */
+function generateAgentHookScripts(ast) {
+    const files = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "agent")
+            continue;
+        const agent = node;
+        if (!agent.hooks || agent.hooks.length === 0)
+            continue;
+        for (const hook of agent.hooks) {
+            if (!hook.run)
+                continue;
+            if (hook.run.startsWith("./") || hook.run.startsWith("/"))
+                continue;
+            const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+            files.push({
+                path: `.cursor/hooks/${agent.id}-${scriptName}`,
+                content: [
+                    "#!/usr/bin/env bash",
+                    `# Hook: ${hook.name} -- fires on ${hook.on} (scoped to agent: ${agent.id})`,
+                    "# Auto-generated by agentopology scaffold -- edit as needed.",
+                    "set -euo pipefail",
+                    "",
+                    `echo "TODO: implement ${hook.name} hook for ${agent.id}"`,
+                    "",
+                ].join("\n"),
+                category: "script",
+            });
+        }
+    }
+    return files;
+}
+/** Generate tool script stubs. */
+function generateToolScripts(ast) {
+    const files = [];
+    for (const tool of ast.toolDefs) {
+        const ext = tool.lang === "python" ? "py" : tool.lang === "node" ? "js" : "sh";
+        const shebang = tool.lang === "python"
+            ? "#!/usr/bin/env python3"
+            : tool.lang === "node"
+                ? "#!/usr/bin/env node"
+                : "#!/usr/bin/env bash";
+        const lines = [
+            shebang,
+            `# Tool: ${tool.id} -- ${tool.description}`,
+            "# Auto-generated by agentopology scaffold -- edit as needed.",
+            "",
+        ];
+        if (tool.lang === "bash" || !tool.lang) {
+            lines.push("set -euo pipefail");
+            lines.push("");
+        }
+        if (tool.args && tool.args.length > 0) {
+            lines.push(`# Args: ${tool.args.join(", ")}`);
+            lines.push("");
+        }
+        if (tool.lang === "python") {
+            lines.push(`print("TODO: implement ${tool.id}")`);
+        }
+        else if (tool.lang === "node") {
+            lines.push(`console.log("TODO: implement ${tool.id}");`);
+        }
+        else {
+            lines.push(`echo "TODO: implement ${tool.id}"`);
+        }
+        lines.push("");
+        files.push({
+            path: `.cursor/scripts/tools/${tool.id}.${ext}`,
+            content: lines.join("\n"),
+            category: "script",
+        });
+    }
+    return files;
+}
+/** Generate metering script stub. */
+function generateMeteringScript(ast) {
+    if (!ast.metering)
+        return null;
+    const m = ast.metering;
+    const lines = [
+        "#!/usr/bin/env bash",
+        "# Metering / cost tracking script",
+        "# Auto-generated by agentopology scaffold -- edit as needed.",
+        "set -euo pipefail",
+        "",
+        `# Track: ${m.track.join(", ")}`,
+        `# Per: ${m.per.join(", ")}`,
+        `# Output: ${m.output} (${m.format})`,
+        `# Pricing: ${m.pricing}`,
+        "",
+        '# Read hook input from stdin',
+        'INPUT=$(cat)',
+        "",
+        '# TODO: Parse input JSON and record metrics',
+        `echo "TODO: implement metrics collection"`,
+        "",
+    ];
+    return {
+        path: ".cursor/hooks/metering.sh",
+        content: lines.join("\n"),
+        category: "script",
+    };
+}
+/** Generate the AGENTS.md context file. */
+function generateContextFile(ast) {
+    const DEFAULT_PATH = "AGENTS.md";
+    const fileName = ast.context.file ?? DEFAULT_PATH;
+    const sections = [];
+    sections.push(`# ${ast.topology.name}`);
+    sections.push("");
+    if (ast.topology.description) {
+        sections.push(ast.topology.description);
+        sections.push("");
+    }
+    // Agent roster table
+    const allAgents = ast.nodes.filter((n) => n.type === "agent" || n.type === "human" || n.type === "group");
+    if (allAgents.length > 0) {
+        sections.push("## Agents");
+        sections.push("");
+        sections.push("| Agent | Description |");
+        sections.push("|-------|-------------|");
+        for (const node of allAgents) {
+            let desc = node.label;
+            if (node.type === "agent") {
+                desc = node.description ?? node.label;
+            }
+            else if (node.type === "human") {
+                desc = node.description ?? node.label;
+            }
+            else if (node.type === "group") {
+                desc = node.description ?? node.label;
+            }
+            sections.push(`| ${node.id} | ${desc} |`);
+        }
+        sections.push("");
+    }
+    // Workflow summary (compiled edges)
+    const edgeText = compileEdges(ast);
+    if (edgeText) {
+        sections.push(edgeText);
+    }
+    // Rules usage guide
+    sections.push("## Rules");
+    sections.push("");
+    sections.push("- Use `@{rule-name}` to activate specific agent rules");
+    sections.push("- Agent rules are in `.cursor/rules/`");
+    sections.push("- MCP servers configured in `.cursor/mcp.json`");
+    sections.push("- Cursor supports Enterprise > Team > Project > User rule hierarchy. These are Project-level rules.");
+    sections.push("");
+    // Providers
+    if (ast.providers && ast.providers.length > 0) {
+        sections.push("## Providers");
+        sections.push("");
+        for (const provider of ast.providers) {
+            let line = `- **${provider.name}**`;
+            if (provider.default)
+                line += " (default)";
+            if (provider.models.length > 0)
+                line += ` -- models: ${provider.models.join(", ")}`;
+            sections.push(line);
+        }
+        sections.push("");
+    }
+    // Checkpoint
+    if (ast.checkpoint) {
+        const cp = ast.checkpoint;
+        sections.push("## Checkpoint");
+        sections.push("");
+        sections.push(`- Backend: ${cp.backend}`);
+        sections.push(`- Strategy: ${cp.strategy}`);
+        if (cp.connection)
+            sections.push(`- Connection: ${cp.connection}`);
+        if (cp.ttl)
+            sections.push(`- TTL: ${cp.ttl}`);
+        sections.push("");
+    }
+    // Artifacts
+    if (ast.artifacts && ast.artifacts.length > 0) {
+        sections.push("## Artifacts");
+        sections.push("");
+        for (const a of ast.artifacts) {
+            let line = `- **${a.id}** (${a.type})`;
+            if (a.path)
+                line += ` -- path: ${a.path}`;
+            if (a.retention)
+                line += `, retention: ${a.retention}`;
+            sections.push(line);
+        }
+        sections.push("");
+    }
+    // Context includes
+    if (ast.context.includes && ast.context.includes.length > 0) {
+        sections.push("## Includes");
+        sections.push("");
+        for (const inc of ast.context.includes) {
+            sections.push(`- ${inc}`);
+        }
+        sections.push("");
+    }
+    return {
+        path: fileName,
+        content: sections.join("\n"),
+        category: "agent",
+    };
+}
+/** Generate legacy .cursorrules file (flat markdown, no frontmatter). */
+function generateCursorrules(ast) {
+    // Only generate if explicitly requested via extensions
+    const cursorExt = ast.extensions?.cursor;
+    if (!cursorExt || cursorExt.legacyRules !== true)
+        return null;
+    const sections = [];
+    sections.push(`# ${ast.topology.name}`);
+    sections.push("");
+    if (ast.topology.description) {
+        sections.push(ast.topology.description);
+        sections.push("");
+    }
+    // Agent summaries
+    const agents = ast.nodes.filter((n) => n.type === "agent" || n.type === "human" || n.type === "group");
+    if (agents.length > 0) {
+        sections.push("## Agents");
+        sections.push("");
+        for (const node of agents) {
+            let desc = node.label;
+            if (node.type === "agent") {
+                desc = node.description ?? node.label;
+            }
+            else if (node.type === "human") {
+                desc = node.description ?? node.label;
+            }
+            else if (node.type === "group") {
+                desc = node.description ?? node.label;
+            }
+            sections.push(`- **${node.id}**: ${desc}`);
+        }
+        sections.push("");
+    }
+    // Workflow
+    const edgeText = compileEdges(ast);
+    if (edgeText) {
+        sections.push(edgeText);
+    }
+    // Settings/defaults as behavioral text
+    if (ast.defaults) {
+        const d = ast.defaults;
+        sections.push("## Defaults");
+        sections.push("");
+        if (d.temperature != null)
+            sections.push(`- Temperature: ${d.temperature}`);
+        if (d.maxTokens != null)
+            sections.push(`- Max tokens: ${d.maxTokens}`);
+        if (d.timeout)
+            sections.push(`- Timeout: ${d.timeout}`);
+        sections.push("");
+    }
+    return {
+        path: ".cursorrules",
+        content: sections.join("\n"),
+        category: "agent",
+    };
+}
+/** Generate memory directory markers. */
+function generateMemory(ast) {
+    const files = [];
+    const memKeys = Object.keys(ast.memory);
+    if (memKeys.length > 0) {
+        files.push(gitkeep(".cursor/memory"));
+    }
+    return files;
+}
+/** Generate observability hook scripts. */
+function generateObservabilityScripts(ast) {
+    const files = [];
+    if (!ast.observability || !ast.observability.enabled)
+        return files;
+    const o = ast.observability;
+    const lines = [
+        "#!/usr/bin/env bash",
+        "# Observability capture script",
+        "# Auto-generated by agentopology scaffold -- edit as needed.",
+        "set -euo pipefail",
+        "",
+        `# Exporter: ${o.exporter}`,
+        `# Level: ${o.level}`,
+        `# Sample rate: ${o.sampleRate}`,
+    ];
+    if (o.endpoint)
+        lines.push(`# Endpoint: ${o.endpoint}`);
+    if (o.service)
+        lines.push(`# Service: ${o.service}`);
+    lines.push("");
+    lines.push("# Read hook input from stdin");
+    lines.push("INPUT=$(cat)");
+    lines.push("");
+    lines.push('echo "TODO: forward trace data to exporter"');
+    lines.push("");
+    files.push({
+        path: ".cursor/scripts/observability.sh",
+        content: lines.join("\n"),
+        category: "script",
+    });
+    return files;
+}
+/** Generate schedule scripts. */
+function generateScheduleScripts(ast) {
+    const files = [];
+    if (!ast.schedules || ast.schedules.length === 0)
+        return files;
+    for (const job of ast.schedules) {
+        const target = job.agent
+            ? `agent ${job.agent}`
+            : job.action
+                ? `action ${job.action}`
+                : "unknown";
+        const lines = [
+            "#!/usr/bin/env bash",
+            `# Schedule: ${job.id} -- invokes ${target}`,
+            "# Auto-generated by agentopology scaffold -- edit as needed.",
+            "set -euo pipefail",
+            "",
+        ];
+        if (job.enabled === false) {
+            lines.push("# DISABLED -- this schedule is not enabled");
+            lines.push("exit 0");
+            lines.push("");
+        }
+        if (job.cron) {
+            lines.push(`# Cron: ${job.cron}`);
+        }
+        else if (job.every) {
+            lines.push(`# Every: ${job.every}`);
+        }
+        if (job.agent) {
+            lines.push(`# Invoke agent: ${job.agent}`);
+            lines.push(`echo "TODO: invoke agent ${job.agent}"`);
+        }
+        else if (job.action) {
+            lines.push(`# Invoke action: ${job.action}`);
+            lines.push(`bash ./.cursor/scripts/actions/${job.action}.sh`);
+        }
+        lines.push("");
+        files.push({
+            path: `.cursor/scripts/schedule-${job.id}.sh`,
+            content: lines.join("\n"),
+            category: "script",
+        });
+    }
+    return files;
+}
+/** Generate schema documentation files. */
+function generateSchemas(ast) {
+    const files = [];
+    if (!ast.schemas || ast.schemas.length === 0)
+        return files;
+    for (const schema of ast.schemas) {
+        const sections = [];
+        sections.push(`# Schema: ${schema.id}`);
+        sections.push("");
+        sections.push("## Fields");
+        sections.push("");
+        for (const field of schema.fields) {
+            const opt = field.optional ? " (optional)" : "";
+            sections.push(`- **${field.name}**${opt}: ${formatSchemaType(field.type, ast.schemas)}`);
+        }
+        sections.push("");
+        // Embed as a rule that agents can reference
+        const fm = frontmatter({
+            description: `Schema definition: ${schema.id}`,
+        });
+        files.push({
+            path: `.cursor/rules/schema-${schema.id}.mdc`,
+            content: fm + "\n\n" + sections.join("\n"),
+            category: "agent",
+        });
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Binding export
+// ---------------------------------------------------------------------------
+/** Cursor IDE binding. */
+export const cursorBinding = {
+    name: "cursor",
+    description: "Cursor IDE -- generates .cursor/rules/*.mdc, .cursor/mcp.json, .cursor/hooks.json, and scripts.",
+    scaffold(ast) {
+        // Fragment check
+        if (ast.isFragment) {
+            return deduplicateFiles([
+                generateTopologyOverview(ast),
+                ...generateAgentRules(ast),
+            ]);
+        }
+        const files = [];
+        // Rules
+        files.push(generateTopologyOverview(ast));
+        files.push(...generateAgentRules(ast));
+        files.push(...generateHumanRules(ast));
+        files.push(...generateGroupRules(ast));
+        files.push(...generateSkillRules(ast));
+        files.push(...generateTriggerRules(ast));
+        files.push(...generateSchemas(ast));
+        // Scripts
+        files.push(...generateActionScripts(ast));
+        files.push(...generateGateHooks(ast));
+        files.push(...generateHookScripts(ast));
+        files.push(...generateAgentHookScripts(ast));
+        files.push(...generateToolScripts(ast));
+        files.push(...generateScheduleScripts(ast));
+        files.push(...generateObservabilityScripts(ast));
+        // Config files
+        const mcpFile = generateMcpJson(ast);
+        if (mcpFile)
+            files.push(mcpFile);
+        const hooksFile = generateHooksJson(ast);
+        if (hooksFile)
+            files.push(hooksFile);
+        const meteringFile = generateMeteringScript(ast);
+        if (meteringFile)
+            files.push(meteringFile);
+        // Context
+        files.push(generateContextFile(ast));
+        // Legacy
+        const legacyFile = generateCursorrules(ast);
+        if (legacyFile)
+            files.push(legacyFile);
+        // Memory
+        files.push(...generateMemory(ast));
+        return deduplicateFiles(files);
+    },
+};
+//# sourceMappingURL=cursor.js.map