agentopology 0.1.0

package/dist/bindings/codex.js

@@ -0,0 +1,1633 @@
+/**
+ * OpenAI Codex CLI binding.
+ *
+ * Generates `.codex/config.toml`, `AGENTS.md`, and supporting scripts
+ * from a parsed {@link TopologyAST}.
+ *
+ * Codex CLI uses TOML-based configuration and reads markdown instruction
+ * files. Multi-agent topologies generate per-agent TOML files under
+ * `.codex/agents/<name>.toml` and an `[agents]` section in config.toml.
+ * AGENTS.md provides a high-level topology overview with references to
+ * individual agent TOML files.
+ *
+ * @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(" ");
+}
+/**
+ * Map topology permission strings to Codex approval_policy values.
+ *
+ * Codex CLI supports these approval policies:
+ *   - "untrusted"  — only run trusted commands without asking (default, most restrictive)
+ *   - "on-request" — model decides when to ask the user
+ *   - "never"      — never ask for user approval
+ *
+ * Legacy/deprecated:
+ *   - "on-failure"  — deprecated, prefer "on-request" for interactive or "never" for non-interactive
+ */
+function mapApprovalPolicy(perm) {
+    // Codex-native values — pass through
+    const nativeValues = ["untrusted", "on-request", "on-failure", "never"];
+    if (nativeValues.includes(perm))
+        return perm;
+    // Topology-level semantic values
+    switch (perm) {
+        case "supervised":
+            return "untrusted";
+        case "autonomous":
+            return "on-request";
+        case "interactive":
+            return "untrusted";
+        case "unrestricted":
+            return "never";
+        // Legacy Codex values — map to current equivalents
+        case "suggest":
+            return "untrusted";
+        case "auto-edit":
+            return "on-request";
+        case "full-auto":
+            return "never";
+        // Claude Code native values mapped to Codex equivalents
+        case "plan":
+            return "untrusted";
+        case "auto":
+            return "on-request";
+        case "confirm":
+            return "untrusted";
+        case "bypassPermissions":
+            return "never";
+        default:
+            return "untrusted"; // safe default
+    }
+}
+/**
+ * Escape a TOML string value.
+ * Wraps in double quotes, escaping internal quotes and backslashes.
+ */
+function tomlString(value) {
+    const escaped = value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n");
+    return `"${escaped}"`;
+}
+/** Format a TOML array of strings on a single line. */
+function tomlStringArray(values) {
+    return `[${values.map(tomlString).join(", ")}]`;
+}
+/** 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" };
+}
+/** Format a SchemaType to a human-readable string. */
+function formatSchemaType(t) {
+    switch (t.kind) {
+        case "primitive":
+            return t.value;
+        case "array":
+            return `${formatSchemaType(t.itemType)}[]`;
+        case "enum":
+            return t.values.join(" | ");
+        case "ref":
+            return t.name;
+    }
+}
+/** Format a SchemaFieldDef to a readable line. */
+function formatSchemaField(f) {
+    const opt = f.optional ? "?" : "";
+    return `- ${f.name}${opt}: ${formatSchemaType(f.type)}`;
+}
+/** Format a RetryConfig to a readable string. */
+function formatRetryConfig(retry) {
+    if (typeof retry === "number")
+        return String(retry);
+    const parts = [`max ${retry.max}`];
+    if (retry.backoff)
+        parts.push(`backoff ${retry.backoff}`);
+    if (retry.interval)
+        parts.push(`interval ${retry.interval}`);
+    if (retry.maxInterval)
+        parts.push(`max-interval ${retry.maxInterval}`);
+    if (retry.jitter)
+        parts.push("jitter");
+    if (retry.nonRetryable && retry.nonRetryable.length > 0) {
+        parts.push(`non-retryable: ${retry.nonRetryable.join(", ")}`);
+    }
+    return parts.join(", ");
+}
+// ---------------------------------------------------------------------------
+// TOML generation — .codex/config.toml
+// ---------------------------------------------------------------------------
+/**
+ * Generate the main `.codex/config.toml` configuration file.
+ *
+ * Maps topology metadata, the most permissive agent's approval policy,
+ * model, sandbox, and provider settings. Extension fields from
+ * `extensions["codex"]` on the topology or agents are merged in.
+ */
+function generateCodexToml(ast) {
+    const lines = [];
+    lines.push("# Codex CLI configuration");
+    lines.push("# Auto-generated by agentopology scaffold — edit as needed.");
+    lines.push("");
+    // Determine the primary model and approval policy from agents.
+    // Use the first orchestrator or first agent's model, falling back to gpt-4o.
+    const orchestrator = ast.nodes.find((n) => n.type === "orchestrator");
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    const primaryModel = orchestrator?.model ?? agents[0]?.model ?? "o4-mini";
+    const primaryPermission = agents[0]?.permissions ?? "supervised";
+    lines.push(`model = ${tomlString(primaryModel)}`);
+    lines.push(`approval_policy = ${tomlString(mapApprovalPolicy(primaryPermission))}`);
+    // Disable response storage if env has a flag or topology explicitly sets it
+    const codexTopologyExt = getTopologyExtensions(ast);
+    if (codexTopologyExt?.disable_response_storage != null) {
+        lines.push(`disable_response_storage = ${codexTopologyExt.disable_response_storage === true}`);
+    }
+    lines.push("");
+    // Model params from defaults or primary agent
+    const temp = ast.defaults?.temperature ?? agents[0]?.temperature;
+    const maxTok = ast.defaults?.maxTokens ?? agents[0]?.maxTokens;
+    if (temp != null || maxTok != null) {
+        lines.push("# Model parameters");
+        if (temp != null)
+            lines.push(`# temperature = ${temp}`);
+        if (maxTok != null)
+            lines.push(`# max_tokens = ${maxTok}`);
+        lines.push("");
+    }
+    // History settings from extensions
+    if (codexTopologyExt?.history) {
+        const history = codexTopologyExt.history;
+        lines.push("[history]");
+        if (history.max_conversations != null) {
+            lines.push(`max_conversations = ${history.max_conversations}`);
+        }
+        if (history.persistence != null) {
+            lines.push(`persistence = ${tomlString(String(history.persistence))}`);
+        }
+        lines.push("");
+    }
+    // Sandbox settings — first-class AST field, then extension, then derived
+    // Codex supports: "read-only", "workspace-write", "danger-full-access"
+    const topSandbox = ast.settings?.sandbox;
+    const sandboxType = topSandbox != null
+        ? (typeof topSandbox === 'boolean' ? (topSandbox ? 'read-only' : 'danger-full-access') : mapSandboxMode(String(topSandbox)))
+        : codexTopologyExt?.sandbox_type ?? deriveSandboxType(ast);
+    if (sandboxType) {
+        lines.push(`sandbox_mode = ${tomlString(String(sandboxType))}`);
+        lines.push("");
+    }
+    // Providers from extensions or ast.providers
+    const extProviders = codexTopologyExt?.providers;
+    if (extProviders && extProviders.length > 0) {
+        // Extensions path takes priority
+        for (const provider of extProviders) {
+            lines.push("[[providers]]");
+            if (provider.name)
+                lines.push(`name = ${tomlString(String(provider.name))}`);
+            if (provider.base_url)
+                lines.push(`base_url = ${tomlString(String(provider.base_url))}`);
+            if (provider.env_key)
+                lines.push(`env_key = ${tomlString(String(provider.env_key))}`);
+            lines.push("");
+        }
+    }
+    else if (ast.providers && ast.providers.length > 0) {
+        // Fallback: map ast.providers to Codex [[providers]] format
+        for (const p of ast.providers) {
+            lines.push("[[providers]]");
+            lines.push(`name = ${tomlString(p.name)}`);
+            if (p.baseUrl)
+                lines.push(`base_url = ${tomlString(p.baseUrl)}`);
+            if (p.apiKey) {
+                // Convert ${ENV_VAR} to just ENV_VAR for Codex env_key format
+                const envKey = p.apiKey.replace(/^\$\{(.+)\}$/, "$1");
+                lines.push(`env_key = ${tomlString(envKey)}`);
+            }
+            if (p.default)
+                lines.push(`default = true`);
+            if (p.models && p.models.length > 0) {
+                lines.push(`models = ${tomlStringArray(p.models)}`);
+            }
+            if (p.auth) {
+                lines.push(`# Auth type: ${p.auth.type}`);
+                if (p.auth.issuer)
+                    lines.push(`# Auth issuer: ${p.auth.issuer}`);
+                if (p.auth.audience)
+                    lines.push(`# Auth audience: ${p.auth.audience}`);
+                if (p.auth.tokenUrl)
+                    lines.push(`# Auth token URL: ${p.auth.tokenUrl}`);
+                if (p.auth.clientId)
+                    lines.push(`# Auth client ID: ${p.auth.clientId}`);
+                if (p.auth.scopes && p.auth.scopes.length > 0) {
+                    lines.push(`# Auth scopes: ${p.auth.scopes.join(", ")}`);
+                }
+            }
+            if (p.extra) {
+                for (const [ek, ev] of Object.entries(p.extra)) {
+                    if (typeof ev === "string") {
+                        lines.push(`${ek} = ${tomlString(ev)}`);
+                    }
+                    else if (typeof ev === "boolean") {
+                        lines.push(`${ek} = ${ev}`);
+                    }
+                    else if (typeof ev === "number") {
+                        lines.push(`${ek} = ${ev}`);
+                    }
+                }
+            }
+            lines.push("");
+        }
+    }
+    // MCP servers from ast.mcpServers — render as [mcp_servers.<name>] tables
+    if (ast.mcpServers && Object.keys(ast.mcpServers).length > 0) {
+        for (const [name, config] of Object.entries(ast.mcpServers)) {
+            lines.push(`[mcp_servers.${name}]`);
+            for (const [ck, cv] of Object.entries(config)) {
+                if (typeof cv === "string") {
+                    lines.push(`${ck} = ${tomlString(cv)}`);
+                }
+                else if (typeof cv === "boolean") {
+                    lines.push(`${ck} = ${cv}`);
+                }
+                else if (typeof cv === "number") {
+                    lines.push(`${ck} = ${cv}`);
+                }
+                else if (Array.isArray(cv)) {
+                    lines.push(`${ck} = ${tomlStringArray(cv.map(String))}`);
+                }
+            }
+            lines.push("");
+        }
+    }
+    // Fallback chain — document if present (Codex doesn't natively support it)
+    const fallbackChain = ast.settings?.["fallback-chain"];
+    if (fallbackChain && fallbackChain.length > 0) {
+        lines.push(`# Model fallback chain: ${fallbackChain.join(" -> ")}`);
+        lines.push("");
+    }
+    // Merge any remaining extension fields as top-level TOML keys
+    if (codexTopologyExt) {
+        const handled = new Set([
+            "disable_response_storage",
+            "history",
+            "sandbox_type",
+            "providers",
+        ]);
+        for (const [key, value] of Object.entries(codexTopologyExt)) {
+            if (handled.has(key))
+                continue;
+            if (typeof value === "string") {
+                lines.push(`${key} = ${tomlString(value)}`);
+            }
+            else if (typeof value === "boolean") {
+                lines.push(`${key} = ${value}`);
+            }
+            else if (typeof value === "number") {
+                lines.push(`${key} = ${value}`);
+            }
+        }
+    }
+    // Multi-agent support: [agents] section with per-agent references
+    if (agents.length > 0) {
+        lines.push("");
+        lines.push("[agents]");
+        lines.push(`max_threads = ${Math.min(agents.length, 10)}`);
+        lines.push(`max_depth = 1`);
+        lines.push("");
+        for (const agent of agents) {
+            const desc = agent.description
+                ?? ast.roles[agent.role ?? ""]
+                ?? ast.roles[agent.id]
+                ?? agent.role
+                ?? toTitle(agent.id);
+            lines.push(`[agents.${agent.id}]`);
+            lines.push(`description = ${tomlString(desc)}`);
+            lines.push(`config_file = ${tomlString(`agents/${agent.id}.toml`)}`);
+            lines.push("");
+        }
+    }
+    return {
+        path: ".codex/config.toml",
+        content: lines.join("\n") + "\n",
+        category: "machine",
+    };
+}
+/**
+ * Map generic sandbox mode strings to Codex sandbox values.
+ * Codex supports: "read-only", "workspace-write", "danger-full-access"
+ */
+function mapSandboxMode(mode) {
+    // Pass through native Codex values
+    const nativeValues = ["read-only", "workspace-write", "danger-full-access"];
+    if (nativeValues.includes(mode))
+        return mode;
+    switch (mode) {
+        case "docker":
+        case "container":
+        case "strict":
+            return "read-only";
+        case "write":
+        case "workspace":
+            return "workspace-write";
+        case "none":
+        case "disabled":
+        case "off":
+            return "danger-full-access";
+        default:
+            return "read-only"; // safe default
+    }
+}
+/**
+ * Map agent sandbox values to Codex sandbox_mode for per-agent TOML.
+ * true/"docker"/"strict" → "read-only", "write"/"workspace" → "workspace-write",
+ * false/"none" → "danger-full-access", "network-only" → "read-only"
+ */
+function mapAgentSandbox(sandbox) {
+    if (typeof sandbox === "boolean") {
+        return sandbox ? "read-only" : "danger-full-access";
+    }
+    switch (sandbox) {
+        case "docker":
+        case "strict":
+        case "container":
+        case "network-only":
+        case "read-only":
+            return "read-only";
+        case "write":
+        case "workspace":
+        case "workspace-write":
+            return "workspace-write";
+        case "none":
+        case "disabled":
+        case "off":
+        case "danger-full-access":
+            return "danger-full-access";
+        default:
+            return "read-only"; // safe default
+    }
+}
+/**
+ * Map thinking/reasoning level to Codex model_reasoning_effort.
+ * off → "" (omit), low → "low", medium → "medium", high → "high", max → "high"
+ */
+function mapReasoningEffort(thinking) {
+    switch (thinking) {
+        case "off":
+            return null; // omit from TOML
+        case "low":
+            return "low";
+        case "medium":
+            return "medium";
+        case "high":
+            return "high";
+        case "max":
+            return "high";
+        default:
+            return null;
+    }
+}
+/**
+ * Derive sandbox type from topology permissions.
+ * More restrictive permissions suggest sandboxing.
+ */
+function deriveSandboxType(ast) {
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    const hasUnrestricted = agents.some((a) => a.permissions === "unrestricted" ||
+        a.permissions === "full-auto" ||
+        a.permissions === "bypassPermissions");
+    // If any agent is unrestricted, no sandbox (user opted out of restrictions)
+    if (hasUnrestricted)
+        return "danger-full-access";
+    // Default: no explicit sandbox section needed
+    return null;
+}
+/**
+ * Extract codex-specific extension fields from the topology level.
+ * Checks settings.extensions["codex"] and any top-level extension block.
+ */
+function getTopologyExtensions(ast) {
+    const settingsExt = ast.settings?.extensions;
+    if (settingsExt?.codex)
+        return settingsExt.codex;
+    // Also check top-level ast.extensions["codex"]
+    if (ast.extensions?.codex)
+        return ast.extensions.codex;
+    return null;
+}
+// ---------------------------------------------------------------------------
+// AGENTS.md generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate `AGENTS.md` — the primary instructions file for Codex CLI.
+ *
+ * Since Codex is a single-agent CLI, multi-agent topologies are expressed
+ * as instruction sections describing each agent's role, responsibilities,
+ * tools, and memory access patterns. The orchestrator reads this file to
+ * understand the full workflow.
+ */
+function generateAgentsMd(ast) {
+    const sections = [];
+    const name = ast.topology.name;
+    // Header
+    sections.push(`# ${toTitle(name)} — Agent Instructions`);
+    sections.push("");
+    // #17 — isFragment notice
+    if (ast.isFragment) {
+        sections.push("**Note:** This is a topology fragment — it defines a reusable sub-topology.");
+        sections.push("");
+    }
+    if (ast.topology.description) {
+        sections.push(ast.topology.description);
+        sections.push("");
+    }
+    sections.push(`Version: ${ast.topology.version}`);
+    if (ast.topology.patterns.length > 0) {
+        sections.push(`Patterns: ${ast.topology.patterns.join(", ")}`);
+    }
+    // #7 — topology-level domain, timeout, errorHandler, durable, foundations, advanced
+    if (ast.topology.domain) {
+        sections.push(`Domain: ${ast.topology.domain}`);
+    }
+    if (ast.topology.timeout) {
+        sections.push(`Timeout: ${ast.topology.timeout}`);
+    }
+    if (ast.topology.errorHandler) {
+        sections.push(`Error handler: ${ast.topology.errorHandler}`);
+    }
+    if (ast.topology.durable) {
+        sections.push(`Durable: true`);
+    }
+    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(", ")}`);
+    }
+    sections.push("");
+    // Defaults section
+    if (ast.defaults) {
+        sections.push("## Defaults");
+        sections.push("");
+        const d = ast.defaults;
+        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 && d.stop.length > 0)
+            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("");
+    }
+    // Orchestrator section (#14)
+    const orch = ast.nodes.find((n) => n.type === "orchestrator");
+    if (orch) {
+        const orchTitle = orch.label || toTitle(orch.id);
+        sections.push(`## Orchestrator — ${orchTitle}`);
+        sections.push("");
+        sections.push(`Model: ${orch.model}`);
+        if (orch.handles?.length > 0) {
+            sections.push(`Handles: ${orch.handles.join(", ")}`);
+        }
+        if (orch.generates) {
+            sections.push(`Generates: ${orch.generates}`);
+        }
+        if (orch.outputs) {
+            sections.push("Outputs:");
+            for (const [field, values] of Object.entries(orch.outputs)) {
+                sections.push(`  - ${field}: ${values.join(" | ")}`);
+            }
+        }
+        sections.push("");
+    }
+    // Flow section
+    if (ast.edges.length > 0) {
+        sections.push("## Flow");
+        sections.push("");
+        for (const edge of ast.edges) {
+            let line = `${edge.from} -> ${edge.to}`;
+            if (edge.condition)
+                line += ` [when ${edge.condition}]`;
+            if (edge.maxIterations)
+                line += ` [max ${edge.maxIterations}]`;
+            if (edge.per)
+                line += ` [per ${edge.per}]`;
+            if (edge.isError)
+                line += ` [error${edge.errorType ? `: ${edge.errorType}` : ""}]`;
+            if (edge.weight != null)
+                line += ` [weight ${edge.weight}]`;
+            if (edge.reflection)
+                line += ` [reflection]`;
+            if (edge.race)
+                line += ` [race]`;
+            if (edge.tolerance != null)
+                line += ` [tolerance: ${edge.tolerance}]`;
+            if (edge.wait)
+                line += ` [wait ${edge.wait}]`;
+            sections.push(`- ${line}`);
+        }
+        sections.push("");
+    }
+    // Schedules section (Codex doesn't natively support cron; document for reference)
+    if (ast.schedules && ast.schedules.length > 0) {
+        sections.push("## Schedules");
+        sections.push("");
+        for (const job of ast.schedules) {
+            const timing = job.cron ? `runs at \`${job.cron}\`` : `runs ${job.every}`;
+            const target = job.agent
+                ? `triggers agent \`${job.agent}\``
+                : job.action
+                    ? `triggers action \`${job.action}\``
+                    : "";
+            const suffix = target ? `, ${target}` : "";
+            const enabled = job.enabled === false ? " (disabled)" : "";
+            sections.push(`- **${job.id}**: ${timing}${suffix}${enabled}`);
+        }
+        sections.push("");
+    }
+    // Interfaces section (document external interfaces for reference)
+    if (ast.interfaces && ast.interfaces.length > 0) {
+        sections.push("## Interfaces");
+        sections.push("");
+        for (const iface of ast.interfaces) {
+            const details = [];
+            if (iface.type)
+                details.push(iface.type);
+            for (const [k, v] of Object.entries(iface.config)) {
+                details.push(`${k} ${v}`);
+            }
+            const desc = details.length > 0 ? details.join(", ") : "configured";
+            sections.push(`- **${iface.id}**: ${desc}`);
+        }
+        sections.push("");
+    }
+    // Agent sections
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    if (agents.length > 0) {
+        sections.push("## Agents");
+        sections.push("");
+        for (const agent of agents) {
+            sections.push(`### ${agent.label || toTitle(agent.id)}`);
+            sections.push("");
+            sections.push(`> See \`.codex/agents/${agent.id}.toml\` for full configuration.`);
+            sections.push("");
+            // Role
+            const roleText = ast.roles[agent.role ?? ""] ?? ast.roles[agent.id] ?? agent.role;
+            if (roleText) {
+                sections.push(`**Role:** ${roleText}`);
+                sections.push("");
+            }
+            // Description
+            if (agent.description) {
+                sections.push(agent.description);
+                sections.push("");
+            }
+            // Model and permissions
+            const model = agent.model ?? "o4-mini";
+            const policy = mapApprovalPolicy(agent.permissions ?? "supervised");
+            sections.push(`- **Model:** ${model}`);
+            sections.push(`- **Approval policy:** ${policy}`);
+            // Phase
+            if (agent.phase != null) {
+                sections.push(`- **Phase:** ${agent.phase}`);
+            }
+            // Sampling parameters
+            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 && agent.stop.length > 0) {
+                sections.push(`- **Stop sequences:** ${agent.stop.join(", ")}`);
+            }
+            if (agent.seed != null) {
+                sections.push(`- **Seed:** ${agent.seed}`);
+            }
+            // Thinking / reasoning
+            if (agent.thinking) {
+                sections.push(`- **Reasoning level:** ${agent.thinking}`);
+            }
+            if (agent.thinkingBudget != null) {
+                sections.push(`- **Thinking budget:** ${agent.thinkingBudget}`);
+            }
+            // Output format
+            if (agent.outputFormat) {
+                sections.push(`- **Output format:** ${agent.outputFormat}`);
+            }
+            // Log level
+            if (agent.logLevel) {
+                sections.push(`- **Log level:** ${agent.logLevel}`);
+            }
+            // Timeout
+            if (agent.timeout) {
+                sections.push(`- **Maximum execution time:** ${agent.timeout}`);
+            }
+            // On-fail
+            if (agent.onFail) {
+                sections.push(`- **On failure:** ${agent.onFail}`);
+            }
+            // Retry
+            if (agent.retry != null) {
+                sections.push(`- **Retry:** ${formatRetryConfig(agent.retry)}`);
+            }
+            // Join semantics
+            if (agent.join) {
+                sections.push(`- **Wait for:** ${agent.join}`);
+            }
+            // Rate limit
+            if (agent.rateLimit) {
+                sections.push(`- **Rate limit:** ${agent.rateLimit}`);
+            }
+            // Circuit breaker
+            if (agent.circuitBreaker) {
+                const cb = agent.circuitBreaker;
+                sections.push(`- **Circuit breaker:** threshold ${cb.threshold}, window ${cb.window}, cooldown ${cb.cooldown}`);
+            }
+            // Compensates (saga)
+            if (agent.compensates) {
+                sections.push(`- **Compensates:** ${agent.compensates} (saga rollback)`);
+            }
+            // Prompt
+            if (agent.prompt) {
+                sections.push("");
+                sections.push("#### Instructions");
+                sections.push("");
+                sections.push(agent.prompt);
+                sections.push("");
+            }
+            // Prompt variants
+            if (agent.variants && agent.variants.length > 0) {
+                sections.push("");
+                sections.push("#### Prompt Variants");
+                sections.push("");
+                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(`  > ${v.prompt.replace(/\n/g, "\n  > ")}`);
+                    }
+                }
+                sections.push("");
+            }
+            // Tools
+            if (agent.tools && agent.tools.length > 0) {
+                sections.push(`- **Tools:** ${agent.tools.join(", ")}`);
+            }
+            if (agent.disallowedTools && agent.disallowedTools.length > 0) {
+                sections.push(`- **Disallowed tools:** ${agent.disallowedTools.join(", ")}`);
+            }
+            // Skills
+            if (agent.skills && agent.skills.length > 0) {
+                sections.push(`- **Skills:** ${agent.skills.join(", ")}`);
+            }
+            // Memory access
+            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(", ")}`);
+            }
+            // Input/Output schemas
+            if (agent.inputSchema && agent.inputSchema.length > 0) {
+                sections.push("- **Input schema:**");
+                for (const field of agent.inputSchema) {
+                    sections.push(`  ${formatSchemaField(field)}`);
+                }
+            }
+            if (agent.outputSchema && agent.outputSchema.length > 0) {
+                sections.push("- **Output schema:**");
+                for (const field of agent.outputSchema) {
+                    sections.push(`  ${formatSchemaField(field)}`);
+                }
+            }
+            // Outputs
+            if (agent.outputs) {
+                sections.push("- **Outputs:**");
+                for (const [field, values] of Object.entries(agent.outputs)) {
+                    sections.push(`  - ${field}: ${values.join(" | ")}`);
+                }
+            }
+            // Artifact lineage
+            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(", ")}`);
+            }
+            // Behavior modifiers
+            if (agent.behavior) {
+                sections.push(`- **Behavior:** ${agent.behavior}`);
+            }
+            if (agent.skip) {
+                sections.push(`- **Skip when:** ${agent.skip}`);
+            }
+            if (agent.isolation) {
+                sections.push(`- **Isolation:** ${agent.isolation}`);
+            }
+            if (agent.background) {
+                sections.push(`- **Background:** true`);
+            }
+            if (agent.maxTurns != null) {
+                sections.push(`- **Max turns:** ${agent.maxTurns}`);
+            }
+            // Scale (#10 — include batchSize)
+            if (agent.scale) {
+                let scaleLine = `- **Scale:** ${agent.scale.mode} by ${agent.scale.by} (${agent.scale.min}-${agent.scale.max}`;
+                if (agent.scale.batchSize != null) {
+                    scaleLine += `, batch ${agent.scale.batchSize}`;
+                }
+                scaleLine += `)`;
+                sections.push(scaleLine);
+            }
+            // #4 — per-agent MCP servers
+            if (agent.mcpServers && agent.mcpServers.length > 0) {
+                sections.push(`- **MCP servers:** ${agent.mcpServers.join(", ")}`);
+            }
+            // #5 — sandbox
+            if (agent.sandbox != null) {
+                sections.push(`- **Sandbox:** ${agent.sandbox}`);
+            }
+            // #5 — fallbackChain
+            if (agent.fallbackChain && agent.fallbackChain.length > 0) {
+                sections.push(`- **Fallback chain:** ${agent.fallbackChain.join(" -> ")}`);
+            }
+            // #5 — per-agent hooks
+            if (agent.hooks && agent.hooks.length > 0) {
+                const hookDesc = agent.hooks.map((h) => `${h.name} (on ${h.on})`).join(", ");
+                sections.push(`- **Hooks:** ${hookDesc}`);
+            }
+            // Codex-specific extensions
+            if (agent.extensions?.codex) {
+                sections.push("- **Codex config:**");
+                for (const [k, v] of Object.entries(agent.extensions.codex)) {
+                    sections.push(`  - ${k}: ${v}`);
+                }
+            }
+            sections.push("");
+        }
+    }
+    // Human nodes section
+    const humans = ast.nodes.filter((n) => n.type === "human");
+    if (humans.length > 0) {
+        sections.push("## Human Checkpoints");
+        sections.push("");
+        for (const human of humans) {
+            sections.push(`### ${human.label || toTitle(human.id)}`);
+            sections.push("");
+            if (human.description) {
+                sections.push(human.description);
+                sections.push("");
+            }
+            sections.push(`- **Type:** Human pause point — requires manual input or approval`);
+            if (human.timeout) {
+                sections.push(`- **Timeout:** ${human.timeout}`);
+            }
+            if (human.onTimeout) {
+                sections.push(`- **On timeout:** ${human.onTimeout}`);
+            }
+            sections.push("");
+        }
+    }
+    // Group nodes section
+    const groups = ast.nodes.filter((n) => n.type === "group");
+    if (groups.length > 0) {
+        sections.push("## Group Chats");
+        sections.push("");
+        for (const group of groups) {
+            sections.push(`### ${group.label || toTitle(group.id)}`);
+            sections.push("");
+            if (group.description) {
+                sections.push(group.description);
+                sections.push("");
+            }
+            sections.push(`- **Members:** ${group.members.join(", ")}`);
+            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("");
+        }
+    }
+    // Gates section
+    const gates = ast.nodes.filter((n) => n.type === "gate");
+    if (gates.length > 0) {
+        sections.push("## Gates");
+        sections.push("");
+        for (const gate of gates) {
+            sections.push(`### ${gate.label || toTitle(gate.id)}`);
+            sections.push("");
+            if (gate.after)
+                sections.push(`- **After:** ${gate.after}`);
+            if (gate.before)
+                sections.push(`- **Before:** ${gate.before}`);
+            if (gate.run)
+                sections.push(`- **Run:** ${gate.run}`);
+            if (gate.checks && gate.checks.length > 0) {
+                sections.push(`- **Checks:** ${gate.checks.join(", ")}`);
+            }
+            if (gate.onFail)
+                sections.push(`- **On fail:** ${gate.onFail}`);
+            if (gate.retry != null)
+                sections.push(`- **Retry:** ${gate.retry}`);
+            if (gate.timeout)
+                sections.push(`- **Timeout:** ${gate.timeout}`);
+            sections.push(`- **Enforcement:** script-level — run gate script manually between agents`);
+            sections.push("");
+        }
+    }
+    // #1 — Action nodes section
+    const actions = ast.nodes.filter((n) => n.type === "action");
+    if (actions.length > 0) {
+        sections.push("## Actions");
+        sections.push("");
+        for (const action of actions) {
+            sections.push(`### ${action.label || toTitle(action.id)}`);
+            sections.push("");
+            if (action.description) {
+                sections.push(action.description);
+                sections.push("");
+            }
+            if (action.kind)
+                sections.push(`- **Kind:** ${action.kind}`);
+            if (action.source)
+                sections.push(`- **Source:** ${action.source}`);
+            if (action.commands && action.commands.length > 0) {
+                sections.push(`- **Commands:** ${action.commands.join("; ")}`);
+            }
+            if (action.timeout)
+                sections.push(`- **Timeout:** ${action.timeout}`);
+            if (action.onFail)
+                sections.push(`- **On fail:** ${action.onFail}`);
+            if (action.join)
+                sections.push(`- **Join:** ${action.join}`);
+            sections.push("");
+        }
+    }
+    // Triggers section
+    if (ast.triggers.length > 0) {
+        sections.push("## Triggers");
+        sections.push("");
+        for (const trigger of ast.triggers) {
+            sections.push(`### ${trigger.name}`);
+            sections.push(`Pattern: \`${trigger.pattern}\``);
+            if (trigger.argument)
+                sections.push(`Argument: ${trigger.argument}`);
+            sections.push("");
+        }
+    }
+    // Memory paths section
+    if (Object.keys(ast.memory).length > 0) {
+        sections.push("## Memory");
+        sections.push("");
+        if (ast.memory.domains) {
+            sections.push(`- **Domains:** .codex/domains/`);
+        }
+        if (ast.memory.references) {
+            sections.push(`- **References:** .codex/references/`);
+        }
+        if (ast.memory.metrics) {
+            sections.push(`- **Metrics:** .codex/metrics.jsonl`);
+        }
+        if (ast.memory.workspace) {
+            sections.push(`- **Workspace:** .codex/runs/`);
+        }
+        sections.push("");
+    }
+    // Observability section
+    if (ast.observability) {
+        const o = ast.observability;
+        sections.push("## Observability");
+        sections.push("");
+        sections.push(`- **Enabled:** ${o.enabled}`);
+        sections.push(`- **Level:** ${o.level}`);
+        sections.push(`- **Exporter:** ${o.exporter}`);
+        if (o.endpoint)
+            sections.push(`- **Endpoint:** ${o.endpoint}`);
+        if (o.service)
+            sections.push(`- **Service:** ${o.service}`);
+        sections.push(`- **Sample rate:** ${o.sampleRate}`);
+        sections.push(`- **Capture:** prompts=${o.capture.prompts}, completions=${o.capture.completions}, toolArgs=${o.capture.toolArgs}, toolResults=${o.capture.toolResults}`);
+        sections.push(`- **Spans:** agents=${o.spans.agents}, tools=${o.spans.tools}, gates=${o.spans.gates}, memory=${o.spans.memory}`);
+        sections.push("");
+    }
+    // Checkpoint section
+    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}`);
+        if (cp.replay) {
+            sections.push(`- **Replay:** enabled=${cp.replay.enabled}${cp.replay.maxHistory != null ? `, maxHistory=${cp.replay.maxHistory}` : ""}${cp.replay.branch != null ? `, branch=${cp.replay.branch}` : ""}`);
+        }
+        sections.push("");
+    }
+    // Artifacts section
+    if (ast.artifacts && ast.artifacts.length > 0) {
+        sections.push("## Artifacts");
+        sections.push("");
+        for (const art of ast.artifacts) {
+            const parts = [`type: ${art.type}`];
+            if (art.path)
+                parts.push(`path: ${art.path}`);
+            if (art.retention)
+                parts.push(`retention: ${art.retention}`);
+            if (art.dependsOn && art.dependsOn.length > 0) {
+                parts.push(`depends-on: ${art.dependsOn.join(", ")}`);
+            }
+            sections.push(`- **${art.id}**: ${parts.join(", ")}`);
+        }
+        sections.push("");
+    }
+    // #8 — Batch section
+    if (ast.batch && Object.keys(ast.batch).length > 0) {
+        sections.push("## Batch");
+        sections.push("");
+        for (const [key, val] of Object.entries(ast.batch)) {
+            sections.push(`- **${key}:** ${JSON.stringify(val)}`);
+        }
+        sections.push("");
+    }
+    // #9 — Environments section
+    if (ast.environments && Object.keys(ast.environments).length > 0) {
+        sections.push("## Environments");
+        sections.push("");
+        for (const [envName, overrides] of Object.entries(ast.environments)) {
+            sections.push(`### ${toTitle(envName)}`);
+            sections.push("");
+            for (const [key, val] of Object.entries(overrides)) {
+                sections.push(`- **${key}:** ${JSON.stringify(val)}`);
+            }
+            sections.push("");
+        }
+    }
+    // Schemas section
+    if (ast.schemas && ast.schemas.length > 0) {
+        sections.push("## Schemas");
+        sections.push("");
+        for (const schema of ast.schemas) {
+            sections.push(`### ${toTitle(schema.id)}`);
+            sections.push("");
+            for (const field of schema.fields) {
+                sections.push(formatSchemaField(field));
+            }
+            sections.push("");
+        }
+    }
+    // Depth levels
+    if (ast.depth && ast.depth.levels && ast.depth.levels.length > 0) {
+        sections.push("## Depth Levels");
+        sections.push("");
+        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("");
+    }
+    // Composition: params
+    if (ast.params && ast.params.length > 0) {
+        sections.push("## Parameters");
+        sections.push("");
+        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("");
+    }
+    // Composition: interface endpoints
+    if (ast.interfaceEndpoints) {
+        sections.push("## Interface");
+        sections.push("");
+        sections.push(`- Entry: ${ast.interfaceEndpoints.entry}`);
+        sections.push(`- Exit: ${ast.interfaceEndpoints.exit}`);
+        sections.push("");
+    }
+    // Composition: imports
+    if (ast.imports && ast.imports.length > 0) {
+        sections.push("## Imports");
+        sections.push("");
+        for (const imp of ast.imports) {
+            let line = `- **${imp.alias}** from \`${imp.source}\``;
+            if (imp.sha256)
+                line += ` (sha256: ${imp.sha256})`;
+            if (imp.registry)
+                line += ` [registry: ${imp.registryPackage}@${imp.registryVersion}]`;
+            sections.push(line);
+            if (Object.keys(imp.params).length > 0) {
+                for (const [k, v] of Object.entries(imp.params)) {
+                    sections.push(`  - ${k}: ${v}`);
+                }
+            }
+        }
+        sections.push("");
+    }
+    // Composition: includes
+    if (ast.includes && ast.includes.length > 0) {
+        sections.push("## Includes");
+        sections.push("");
+        for (const inc of ast.includes) {
+            sections.push(`- ${inc.source}`);
+        }
+        sections.push("");
+    }
+    // Skills summary (#11 — additional skill fields)
+    if (ast.skills.length > 0) {
+        sections.push("## Skills");
+        sections.push("");
+        for (const skill of ast.skills) {
+            sections.push(`### ${toTitle(skill.id)}`);
+            if (skill.description) {
+                sections.push(skill.description);
+            }
+            if (skill.scripts && skill.scripts.length > 0) {
+                sections.push(`Scripts: ${skill.scripts.join(", ")}`);
+            }
+            if (skill.prompt) {
+                sections.push(`Prompt file: ${skill.prompt}`);
+            }
+            if (skill.userInvocable != null) {
+                sections.push(`User-invocable: ${skill.userInvocable ? "yes" : "no"}`);
+            }
+            if (skill.allowedTools && skill.allowedTools.length > 0) {
+                sections.push(`Allowed tools: ${skill.allowedTools.join(", ")}`);
+            }
+            if (skill.context) {
+                sections.push(`Context: ${skill.context}`);
+            }
+            if (skill.agent) {
+                sections.push(`Agent: ${skill.agent}`);
+            }
+            if (skill.disableModelInvocation) {
+                sections.push(`Model invocation: disabled`);
+            }
+            sections.push("");
+        }
+    }
+    // Context includes (#16 — also show context.file)
+    if ((ast.context.includes && ast.context.includes.length > 0) || ast.context.file) {
+        sections.push("## References");
+        sections.push("");
+        if (ast.context.file) {
+            sections.push(`- Context file: ${ast.context.file}`);
+        }
+        if (ast.context.includes) {
+            for (const inc of ast.context.includes) {
+                sections.push(`- ${inc}`);
+            }
+        }
+        sections.push("");
+    }
+    // Environment variables (#2 — handle sensitive, secretRef, encrypted)
+    if (Object.keys(ast.env).length > 0) {
+        sections.push("## Environment");
+        sections.push("");
+        for (const [key, val] of Object.entries(ast.env)) {
+            if (typeof val === "string") {
+                sections.push(`- \`${key}\`: ${val}`);
+            }
+            else {
+                const sv = val;
+                let displayVal;
+                if (sv.secretRef) {
+                    displayVal = `[secret: ${sv.secretRef.scheme}:${sv.secretRef.uri}]`;
+                }
+                else if (sv.encrypted) {
+                    displayVal = `[encrypted]`;
+                }
+                else if (sv.sensitive) {
+                    displayVal = `\${${key}}`;
+                }
+                else {
+                    displayVal = sv.value;
+                }
+                sections.push(`- \`${key}\`: ${displayVal}`);
+            }
+        }
+        sections.push("");
+    }
+    return {
+        path: "AGENTS.md",
+        content: sections.join("\n") + "\n",
+        category: "agent",
+    };
+}
+// ---------------------------------------------------------------------------
+// .codex/instructions.md — REMOVED
+// ---------------------------------------------------------------------------
+// Codex CLI does NOT use .codex/instructions.md. It reads AGENTS.md files
+// from the workspace root and nested directories. Skills, context includes,
+// and environment info are now folded into AGENTS.md generation above.
+// ---------------------------------------------------------------------------
+// Memory directories
+// ---------------------------------------------------------------------------
+/** Generate memory structure directories under .codex/. */
+function generateMemory(ast) {
+    const files = [];
+    if (ast.memory.domains) {
+        files.push(gitkeep(".codex/domains"));
+    }
+    if (ast.memory.references) {
+        files.push(gitkeep(".codex/references"));
+    }
+    if (ast.memory.metrics) {
+        files.push({
+            path: ".codex/metrics.jsonl",
+            content: "",
+            category: "machine",
+        });
+    }
+    if (ast.memory.workspace) {
+        files.push(gitkeep(".codex/runs"));
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Gate scripts
+// ---------------------------------------------------------------------------
+/** Generate gate script stubs under .codex/scripts/. */
+function generateGateScripts(ast) {
+    const files = [];
+    for (const node of ast.nodes) {
+        if (node.type !== "gate")
+            continue;
+        const gate = node;
+        if (gate.run) {
+            const scriptName = gate.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+            files.push({
+                path: `.codex/scripts/${scriptName}`,
+                content: shellStub(`Gate: ${gate.id} — ${gate.run}`),
+                category: "script",
+            });
+        }
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Hook scripts
+// ---------------------------------------------------------------------------
+/** Generate hook script stubs under .codex/scripts/. */
+function generateHookScripts(ast) {
+    const files = [];
+    // Global hooks
+    for (const hook of ast.hooks) {
+        if (!hook.run)
+            continue;
+        const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+        const hookLines = [
+            "#!/usr/bin/env bash",
+            `# Hook: ${hook.name} — fires on ${hook.on}`,
+        ];
+        // #12 — include matcher, type, timeout as comments
+        if (hook.matcher)
+            hookLines.push(`# Matcher: ${hook.matcher}`);
+        if (hook.type)
+            hookLines.push(`# Type: ${hook.type}`);
+        if (hook.timeout != null)
+            hookLines.push(`# Timeout: ${hook.timeout}ms`);
+        hookLines.push("# Auto-generated by agentopology scaffold — edit as needed.", "set -euo pipefail", "", `echo "TODO: implement ${hook.name} hook"`, "");
+        files.push({
+            path: `.codex/scripts/${scriptName}`,
+            content: hookLines.join("\n"),
+            category: "script",
+        });
+    }
+    // #5 — per-agent hook script stubs
+    for (const node of ast.nodes) {
+        if (node.type !== "agent")
+            continue;
+        const agent = node;
+        if (!agent.hooks)
+            continue;
+        for (const hook of agent.hooks) {
+            if (!hook.run)
+                continue;
+            const scriptName = hook.run.replace(/^.*\//, "").replace(/\s.*$/, "");
+            const hookLines = [
+                "#!/usr/bin/env bash",
+                `# Hook: ${hook.name} — fires on ${hook.on} (agent: ${agent.id})`,
+            ];
+            if (hook.matcher)
+                hookLines.push(`# Matcher: ${hook.matcher}`);
+            if (hook.type)
+                hookLines.push(`# Type: ${hook.type}`);
+            if (hook.timeout != null)
+                hookLines.push(`# Timeout: ${hook.timeout}ms`);
+            hookLines.push("# Auto-generated by agentopology scaffold — edit as needed.", "set -euo pipefail", "", `echo "TODO: implement ${hook.name} hook"`, "");
+            files.push({
+                path: `.codex/scripts/${scriptName}`,
+                content: hookLines.join("\n"),
+                category: "script",
+            });
+        }
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Tool scripts
+// ---------------------------------------------------------------------------
+/** Generate tool script stubs under .codex/scripts/. */
+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: `.codex/scripts/${tool.id}.${ext}`,
+            content: lines.join("\n"),
+            category: "script",
+        });
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Metering script
+// ---------------------------------------------------------------------------
+/** Generate metering script stub. */
+function generateMetering(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}`,
+        "",
+        'echo "TODO: implement metrics collection"',
+        "",
+    ];
+    return {
+        path: "scripts/collect-metrics.sh",
+        content: lines.join("\n"),
+        category: "script",
+    };
+}
+// ---------------------------------------------------------------------------
+// Workspace protocol
+// ---------------------------------------------------------------------------
+/** Generate workspace-protocol.md if workspace memory has a protocol field. */
+function generateWorkspaceProtocol(ast) {
+    const workspace = ast.memory.workspace;
+    if (!workspace || !workspace.protocol)
+        return null;
+    const protocol = workspace.protocol;
+    const sections = [];
+    sections.push("# Workspace Protocol");
+    sections.push("");
+    // Directory structure from workspace.structure
+    const structure = workspace.structure;
+    if (structure && Array.isArray(structure)) {
+        sections.push("## Directory Structure");
+        for (const item of structure) {
+            sections.push(`- ${item}`);
+        }
+        sections.push("");
+    }
+    // Read/Write rules from agent nodes
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    if (agents.length > 0) {
+        sections.push("## Read/Write Rules");
+        for (const agent of agents) {
+            const reads = agent.reads ?? [];
+            const writes = agent.writes ?? [];
+            if (reads.length > 0 || writes.length > 0) {
+                sections.push(`### ${toTitle(agent.id)}`);
+                if (reads.length > 0) {
+                    sections.push(`- Reads: ${reads.join(", ")}`);
+                }
+                if (writes.length > 0) {
+                    sections.push(`- Writes: ${writes.join(", ")}`);
+                }
+                sections.push("");
+            }
+        }
+    }
+    return {
+        path: `.codex/${protocol}`,
+        content: sections.join("\n") + "\n",
+        category: "machine",
+    };
+}
+// ---------------------------------------------------------------------------
+// Skill documentation
+// ---------------------------------------------------------------------------
+/** Generate skill documentation files under .codex/skills/. */
+function generateSkills(ast) {
+    const files = [];
+    for (const skill of ast.skills) {
+        const sections = [];
+        sections.push(`# ${toTitle(skill.id)} Skill`);
+        sections.push("");
+        if (skill.description) {
+            sections.push(skill.description);
+            sections.push("");
+        }
+        if (skill.scripts && skill.scripts.length > 0) {
+            sections.push("## Scripts");
+            for (const s of skill.scripts) {
+                sections.push(`- ${s}`);
+            }
+            sections.push("");
+        }
+        if (skill.domains && skill.domains.length > 0) {
+            sections.push("## Domains");
+            for (const d of skill.domains) {
+                sections.push(`- ${d}`);
+            }
+            sections.push("");
+        }
+        if (skill.references && skill.references.length > 0) {
+            sections.push("## References");
+            for (const r of skill.references) {
+                sections.push(`- ${r}`);
+            }
+            sections.push("");
+        }
+        // #11 — additional skill fields in skill docs
+        if (skill.prompt) {
+            sections.push(`Prompt file: ${skill.prompt}`);
+            sections.push("");
+        }
+        if (skill.userInvocable != null) {
+            sections.push(`User-invocable: ${skill.userInvocable ? "yes" : "no"}`);
+            sections.push("");
+        }
+        if (skill.allowedTools && skill.allowedTools.length > 0) {
+            sections.push(`Allowed tools: ${skill.allowedTools.join(", ")}`);
+            sections.push("");
+        }
+        if (skill.context) {
+            sections.push(`Context: ${skill.context}`);
+            sections.push("");
+        }
+        if (skill.agent) {
+            sections.push(`Agent: ${skill.agent}`);
+            sections.push("");
+        }
+        if (skill.disableModelInvocation) {
+            sections.push(`Model invocation: disabled`);
+            sections.push("");
+        }
+        files.push({
+            path: `.codex/skills/${skill.id}.md`,
+            content: sections.join("\n") + "\n",
+            category: "agent",
+        });
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Per-agent TOML files — .codex/agents/<name>.toml
+// ---------------------------------------------------------------------------
+/**
+ * Build developer_instructions for an agent that has no explicit prompt.
+ * Constructs instructions from role description, tools, reads/writes, and outputs.
+ */
+function buildDeveloperInstructions(agent, ast) {
+    const parts = [];
+    // Role description
+    const roleText = ast.roles[agent.role ?? ""] ?? ast.roles[agent.id] ?? agent.role;
+    if (roleText) {
+        parts.push(`You are a ${toTitle(agent.id)} agent. ${roleText}`);
+    }
+    else {
+        parts.push(`You are the ${toTitle(agent.id)} agent.`);
+    }
+    // Tools
+    if (agent.tools && agent.tools.length > 0) {
+        parts.push(`\nAvailable tools: ${agent.tools.join(", ")}`);
+    }
+    if (agent.disallowedTools && agent.disallowedTools.length > 0) {
+        parts.push(`Disallowed tools: ${agent.disallowedTools.join(", ")}`);
+    }
+    // Memory access
+    if (agent.reads && agent.reads.length > 0) {
+        parts.push(`\nReads from: ${agent.reads.join(", ")}`);
+    }
+    if (agent.writes && agent.writes.length > 0) {
+        parts.push(`Writes to: ${agent.writes.join(", ")}`);
+    }
+    // Outputs
+    if (agent.outputs) {
+        const outputLines = [];
+        for (const [field, values] of Object.entries(agent.outputs)) {
+            outputLines.push(`  ${field}: ${values.join(" | ")}`);
+        }
+        parts.push(`\nOutputs:\n${outputLines.join("\n")}`);
+    }
+    return parts.join("\n");
+}
+/**
+ * Generate per-agent TOML files under `.codex/agents/<name>.toml`.
+ *
+ * Each agent in the topology gets its own TOML configuration file with
+ * name, description, developer_instructions, model, sandbox_mode,
+ * model_reasoning_effort, nickname_candidates, and optional MCP servers.
+ */
+function generateAgentTomlFiles(ast) {
+    const files = [];
+    const agents = ast.nodes.filter((n) => n.type === "agent");
+    for (const agent of agents) {
+        const lines = [];
+        // name
+        lines.push(`name = ${tomlString(agent.id)}`);
+        // description
+        const desc = agent.description
+            ?? ast.roles[agent.role ?? ""]
+            ?? ast.roles[agent.id]
+            ?? agent.role
+            ?? toTitle(agent.id);
+        lines.push(`description = ${tomlString(desc)}`);
+        // developer_instructions — use prompt if available, otherwise construct
+        const instructions = agent.prompt ?? buildDeveloperInstructions(agent, ast);
+        lines.push(`developer_instructions = """\n${instructions}\n"""`);
+        // model
+        if (agent.model) {
+            lines.push(`model = ${tomlString(agent.model)}`);
+        }
+        // sandbox_mode
+        if (agent.sandbox != null) {
+            lines.push(`sandbox_mode = ${tomlString(mapAgentSandbox(agent.sandbox))}`);
+        }
+        // model_reasoning_effort
+        if (agent.thinking) {
+            const effort = mapReasoningEffort(agent.thinking);
+            if (effort) {
+                lines.push(`model_reasoning_effort = ${tomlString(effort)}`);
+            }
+        }
+        // nickname_candidates — derive from agent id
+        const nickname = agent.id
+            .split(/[-_]/)
+            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+            .join("");
+        lines.push(`nickname_candidates = [${tomlString(nickname)}]`);
+        // MCP servers — include sections for agent-specific MCP servers
+        if (agent.mcpServers && agent.mcpServers.length > 0 && ast.mcpServers) {
+            lines.push("");
+            for (const serverName of agent.mcpServers) {
+                const config = ast.mcpServers[serverName];
+                if (!config)
+                    continue;
+                lines.push(`[mcp_servers.${serverName}]`);
+                for (const [ck, cv] of Object.entries(config)) {
+                    if (typeof cv === "string") {
+                        lines.push(`${ck} = ${tomlString(cv)}`);
+                    }
+                    else if (typeof cv === "boolean") {
+                        lines.push(`${ck} = ${cv}`);
+                    }
+                    else if (typeof cv === "number") {
+                        lines.push(`${ck} = ${cv}`);
+                    }
+                    else if (Array.isArray(cv)) {
+                        lines.push(`${ck} = ${tomlStringArray(cv.map(String))}`);
+                    }
+                }
+                lines.push("");
+            }
+        }
+        files.push({
+            path: `.codex/agents/${agent.id}.toml`,
+            content: lines.join("\n") + "\n",
+            category: "agent",
+        });
+    }
+    return files;
+}
+// ---------------------------------------------------------------------------
+// Binding export
+// ---------------------------------------------------------------------------
+/** OpenAI Codex CLI binding — full implementation. */
+export const codexBinding = {
+    name: "codex",
+    description: "OpenAI Codex CLI — generates .codex/config.toml, AGENTS.md, .codex/ directory structure, and scripts.",
+    scaffold(ast) {
+        const files = [];
+        // 1. .codex/config.toml — main configuration
+        files.push(generateCodexToml(ast));
+        // 2. AGENTS.md — agent instructions with roles, flow, memory paths
+        //    (Codex reads AGENTS.md from workspace root; no separate instructions.md)
+        files.push(generateAgentsMd(ast));
+        // 3. Per-agent TOML files under .codex/agents/
+        files.push(...generateAgentTomlFiles(ast));
+        // 4. Memory directories
+        files.push(...generateMemory(ast));
+        // 5. Skill documentation
+        files.push(...generateSkills(ast));
+        // 6. Gate scripts
+        files.push(...generateGateScripts(ast));
+        // 7. Hook scripts
+        files.push(...generateHookScripts(ast));
+        // 8. Tool scripts
+        files.push(...generateToolScripts(ast));
+        // 9. Workspace protocol
+        const wsProtocol = generateWorkspaceProtocol(ast);
+        if (wsProtocol)
+            files.push(wsProtocol);
+        // 10. Metering
+        const meteringFile = generateMetering(ast);
+        if (meteringFile)
+            files.push(meteringFile);
+        return deduplicateFiles(files);
+    },
+};
+//# sourceMappingURL=codex.js.map