vigiles 2.3.0 → 2.5.0

package/dist/agent-result.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * vigiles — parse a subagent's railway result.
+ *
+ * A subagent with a `result()` contract is told (in its compiled system prompt)
+ * to end its turn with exactly one fenced block:
+ *
+ *   ```vigiles:ok
+ *   { "files": ["a.ts"], "summary": "done" }
+ *   ```
+ *
+ * or `vigiles:err` for the error track. This module extracts and validates that
+ * block — the single primitive the railway orchestrator and the harness-test
+ * assertions (`assertAgentOk`/`assertAgentErr`) both build on. Pure and
+ * model-free: hand it the worker's text, get back a discriminated outcome.
+ *
+ * "Railway-oriented" is literal here: the parse is `text -> Result<S, E>` with a
+ * third `malformed` track for a worker that didn't honor its contract (no block,
+ * bad JSON, or a shape that doesn't match the declared schema).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAgentResult = parseAgentResult;
+// Capture every vigiles:ok / vigiles:err fenced block; the LAST one is the
+// worker's final answer (earlier ones may be illustrative in its reasoning).
+const BLOCK_RE = /```vigiles:(ok|err)[ \t]*\r?\n([\s\S]*?)```/g;
+/** Does a runtime value match a declared field type? */
+function fieldMatches(value, type) {
+    switch (type) {
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number";
+        case "boolean":
+            return typeof value === "boolean";
+        case "string[]":
+            return Array.isArray(value) && value.every((v) => typeof v === "string");
+    }
+}
+/** Validate a parsed object against a contract track; null when it conforms. */
+function shapeError(obj, shape) {
+    for (const [field, type] of Object.entries(shape)) {
+        if (!(field in obj))
+            return `missing field "${field}"`;
+        if (!fieldMatches(obj[field], type)) {
+            return `field "${field}" should be ${type}`;
+        }
+    }
+    return null;
+}
+/**
+ * Parse the last `vigiles:ok` / `vigiles:err` block from a worker's output.
+ *
+ * With a `contract`, the parsed object is validated against the matching track's
+ * shape — a worker that emits the wrong shape is `malformed`, not a silent pass.
+ * Without one, any well-formed JSON block is accepted.
+ */
+function parseAgentResult(text, contract) {
+    BLOCK_RE.lastIndex = 0;
+    let last = null;
+    for (let m = BLOCK_RE.exec(text); m !== null; m = BLOCK_RE.exec(text)) {
+        last = { track: m[1], body: m[2] };
+    }
+    if (!last) {
+        return {
+            kind: "malformed",
+            reason: "no vigiles:ok/vigiles:err block found",
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(last.body);
+    }
+    catch {
+        return {
+            kind: "malformed",
+            reason: `invalid JSON in vigiles:${last.track} block`,
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            kind: "malformed",
+            reason: `vigiles:${last.track} block must be a JSON object`,
+        };
+    }
+    const obj = parsed;
+    if (contract) {
+        const shape = last.track === "ok" ? contract.ok : contract.err;
+        const err = shapeError(obj, shape);
+        if (err) {
+            return { kind: "malformed", reason: `${last.track} block: ${err}` };
+        }
+    }
+    return last.track === "ok"
+        ? { kind: "ok", value: obj }
+        : { kind: "err", error: obj };
+}
+//# sourceMappingURL=agent-result.js.map

package/dist/agent-runtime.d.ts

@@ -0,0 +1,64 @@
+/**
+ * vigiles — Agent runtime: the PreToolUse tool-contract rail.
+ *
+ * A subagent declares an allowed-tools contract in its frontmatter (`tools:`).
+ * But that field is documentation, not a hard runtime boundary (Claude Code
+ * issue #54898): permissions are session-wide, a subagent inherits the parent
+ * session's grants, and `tools:` only filters what's *offered* — it can't deny
+ * what the session allows. The deterministic layer that actually closes the gap
+ * is a **PreToolUse hook** that blocks any tool the active agent's contract
+ * doesn't list.
+ *
+ * This is the same emit-a-hook pattern the skill runtime already ships
+ * (`src/skill-runtime.ts`): there a `Stop` hook reads the active skill's
+ * compiled SKILL.md and runs its result gate; here a `PreToolUse` hook reads
+ * the active agent's compiled `.md`, parses its `tools:` allowlist, and
+ * allows/denies the tool call. The compiled markdown's frontmatter is the
+ * single source of truth — the same list that documents intent IS the list the
+ * hook enforces, so the two agree by construction (see `enforcedTools`).
+ *
+ * Which agent is active is recorded in `.vigiles/active-agent.json` — Claude
+ * Code hooks don't surface the dispatched subagent, so vigiles records it
+ * (mirrors `.vigiles/active-skill.json`). The decision logic below is
+ * harness-agnostic and fully testable.
+ */
+/**
+ * Parse an agent's allowed-tools contract from its compiled markdown.
+ *
+ * Returns the list of allowed tool names, or `null` when the agent declares no
+ * `tools:` line at all — which in Claude Code means it inherits EVERY tool (the
+ * #1 footgun). `null` is the "no restriction" signal the decision logic honors;
+ * an empty list (`tools:` with nothing after it) means "no tools allowed".
+ */
+export declare function parseAgentTools(markdown: string): string[] | null;
+export interface PreToolDecision {
+    /** Whether the tool call is allowed (true) or blocked (false). */
+    readonly allow: boolean;
+    /** Message fed back to the model on a block; empty on allow. */
+    readonly message: string;
+}
+/**
+ * Decide whether `tool` is allowed under an agent's tool contract. Pure, so the
+ * rail is unit-testable without spawning anything.
+ *
+ * - `allowed === null` → the agent declared no `tools:` line, so it inherits
+ *   everything and the rail imposes no restriction (allow).
+ * - otherwise → allow iff the tool is in the allowlist; deny anything else,
+ *   feeding the contract back to the model so it self-corrects.
+ */
+export declare function decidePreToolUse(allowed: readonly string[] | null, tool: string): PreToolDecision;
+/** Record the subagent currently dispatched, so PreToolUse enforces its contract. */
+export declare function setActiveAgent(cwd: string, agentPath: string): void;
+/** Clear the active-agent marker (the subagent finished). */
+export declare function clearActiveAgent(cwd: string): void;
+/** The path of the active agent's compiled `.md`, or null when none is active. */
+export declare function readActiveAgent(cwd: string): string | null;
+/**
+ * PreToolUse-hook decision. If an agent is active, parse its compiled `.md`
+ * tool contract and allow the call only when the tool is in the allowlist;
+ * otherwise block and tell the model which tools it may use. With no active
+ * agent (or an agent that inherits all tools), always allow — the rail only
+ * constrains agents that declared a contract.
+ */
+export declare function evaluatePreToolUse(cwd: string, tool: string): PreToolDecision;
+//# sourceMappingURL=agent-runtime.d.ts.map

package/dist/agent-runtime.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * vigiles — Agent runtime: the PreToolUse tool-contract rail.
+ *
+ * A subagent declares an allowed-tools contract in its frontmatter (`tools:`).
+ * But that field is documentation, not a hard runtime boundary (Claude Code
+ * issue #54898): permissions are session-wide, a subagent inherits the parent
+ * session's grants, and `tools:` only filters what's *offered* — it can't deny
+ * what the session allows. The deterministic layer that actually closes the gap
+ * is a **PreToolUse hook** that blocks any tool the active agent's contract
+ * doesn't list.
+ *
+ * This is the same emit-a-hook pattern the skill runtime already ships
+ * (`src/skill-runtime.ts`): there a `Stop` hook reads the active skill's
+ * compiled SKILL.md and runs its result gate; here a `PreToolUse` hook reads
+ * the active agent's compiled `.md`, parses its `tools:` allowlist, and
+ * allows/denies the tool call. The compiled markdown's frontmatter is the
+ * single source of truth — the same list that documents intent IS the list the
+ * hook enforces, so the two agree by construction (see `enforcedTools`).
+ *
+ * Which agent is active is recorded in `.vigiles/active-agent.json` — Claude
+ * Code hooks don't surface the dispatched subagent, so vigiles records it
+ * (mirrors `.vigiles/active-skill.json`). The decision logic below is
+ * harness-agnostic and fully testable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAgentTools = parseAgentTools;
+exports.decidePreToolUse = decidePreToolUse;
+exports.setActiveAgent = setActiveAgent;
+exports.clearActiveAgent = clearActiveAgent;
+exports.readActiveAgent = readActiveAgent;
+exports.evaluatePreToolUse = evaluatePreToolUse;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// Parse the tool contract from a compiled agent .md
+// ---------------------------------------------------------------------------
+/** Extract the YAML frontmatter block (between the first pair of `---` fences). */
+function extractFrontmatter(markdown) {
+    const lines = markdown.split("\n");
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === "---") {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return null;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---") {
+            return lines.slice(start + 1, i).join("\n");
+        }
+    }
+    return null;
+}
+/**
+ * Parse an agent's allowed-tools contract from its compiled markdown.
+ *
+ * Returns the list of allowed tool names, or `null` when the agent declares no
+ * `tools:` line at all — which in Claude Code means it inherits EVERY tool (the
+ * #1 footgun). `null` is the "no restriction" signal the decision logic honors;
+ * an empty list (`tools:` with nothing after it) means "no tools allowed".
+ */
+function parseAgentTools(markdown) {
+    const fm = extractFrontmatter(markdown);
+    if (fm === null)
+        return null;
+    const match = /^tools:[ \t]*(.*)$/m.exec(fm);
+    if (!match)
+        return null;
+    return match[1]
+        .split(",")
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0);
+}
+/**
+ * Decide whether `tool` is allowed under an agent's tool contract. Pure, so the
+ * rail is unit-testable without spawning anything.
+ *
+ * - `allowed === null` → the agent declared no `tools:` line, so it inherits
+ *   everything and the rail imposes no restriction (allow).
+ * - otherwise → allow iff the tool is in the allowlist; deny anything else,
+ *   feeding the contract back to the model so it self-corrects.
+ */
+function decidePreToolUse(allowed, tool) {
+    if (allowed === null)
+        return { allow: true, message: "" };
+    if (allowed.includes(tool))
+        return { allow: true, message: "" };
+    const list = allowed.length > 0 ? allowed.join(", ") : "(none)";
+    return {
+        allow: false,
+        message: `Tool "${tool}" is not in this subagent's allowed-tools contract ` +
+            `(${list}). Use only the listed tools, or widen the agent's \`tools\`.`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Active-agent tracking (mirrors .vigiles/active-skill.json)
+// ---------------------------------------------------------------------------
+const ACTIVE_PATH = ".vigiles/active-agent.json";
+/** Record the subagent currently dispatched, so PreToolUse enforces its contract. */
+function setActiveAgent(cwd, agentPath) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+    (0, node_fs_1.writeFileSync)(p, JSON.stringify({ agent: agentPath }) + "\n");
+}
+/** Clear the active-agent marker (the subagent finished). */
+function clearActiveAgent(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if ((0, node_fs_1.existsSync)(p))
+        (0, node_fs_1.rmSync)(p);
+}
+/** The path of the active agent's compiled `.md`, or null when none is active. */
+function readActiveAgent(cwd) {
+    const p = (0, node_path_1.resolve)(cwd, ACTIVE_PATH);
+    if (!(0, node_fs_1.existsSync)(p))
+        return null;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(p, "utf-8"));
+        return typeof parsed.agent === "string" ? parsed.agent : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// PreToolUse-hook decision
+// ---------------------------------------------------------------------------
+/**
+ * PreToolUse-hook decision. If an agent is active, parse its compiled `.md`
+ * tool contract and allow the call only when the tool is in the allowlist;
+ * otherwise block and tell the model which tools it may use. With no active
+ * agent (or an agent that inherits all tools), always allow — the rail only
+ * constrains agents that declared a contract.
+ */
+function evaluatePreToolUse(cwd, tool) {
+    const agentPath = readActiveAgent(cwd);
+    if (!agentPath)
+        return { allow: true, message: "" };
+    const full = (0, node_path_1.resolve)(cwd, agentPath);
+    if (!(0, node_fs_1.existsSync)(full))
+        return { allow: true, message: "" };
+    const allowed = parseAgentTools((0, node_fs_1.readFileSync)(full, "utf-8"));
+    return decidePreToolUse(allowed, tool);
+}
+//# sourceMappingURL=agent-runtime.js.map

package/dist/cli.js

@@ -23,7 +23,9 @@ const frontmatter_js_1 = require("./frontmatter.js");
 const generate_schema_js_1 = require("./generate-schema.js");
 const compile_generator_js_1 = require("./compile-generator.js");
 const action_gate_js_1 = require("./action-gate.js");
+const agent_runtime_js_1 = require("./agent-runtime.js");
 const refs_js_1 = require("./refs.js");
+const mcp_js_1 = require("./mcp.js");
 const skill_runtime_js_1 = require("./skill-runtime.js");
 const linters_js_1 = require("./linters.js");
 const harness_test_js_1 = require("./harness-test.js");
@@ -176,8 +178,57 @@ function compileSkillToFile(spec, specPath) {
     printErrors(specPath, errors);
     return false;
 }
+/** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
+function compileAgentToFile(spec, specPath) {
+    const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    const { markdown, errors } = (0, compile_js_1.compileAgent)(spec, {
+        basePath: process.cwd(),
+        specFile: specPath,
+    });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    if (errors.length === 0) {
+        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        return true;
+    }
+    console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+    printErrors(specPath, errors);
+    return false;
+}
+/**
+ * Compile a railway spec → the orchestrator command markdown. `knownAgents` is
+ * the set of compiled agent names in the project, so every `delegate()` target
+ * is resolved at compile time (an unknown target is a stale-ref error).
+ */
+function compileRailwayToFile(spec, specPath, knownAgents) {
+    const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    const { markdown, errors } = (0, compile_js_1.compileRailway)(spec, {
+        specFile: specPath,
+        knownAgents,
+    });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    if (errors.length === 0) {
+        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        return true;
+    }
+    console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+    printErrors(specPath, errors);
+    return false;
+}
+/** Names of every compiled agent spec in the project — resolves delegate() targets. */
+async function collectAgentNames() {
+    const names = [];
+    for (const p of findSpecs()) {
+        const s = await loadSpec(p);
+        if (s && s._specType === "agent")
+            names.push(s.name);
+    }
+    return names;
+}
 async function compile(specPaths, config) {
     let allValid = true;
+    // Resolved lazily on the first railway spec — every delegate() target is
+    // checked against the agents defined anywhere in the project.
+    let knownAgents = null;
     for (const specPath of specPaths) {
         // Generator skills can't be executed to markdown — compile from source.
         const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), specPath), "utf-8");
@@ -201,6 +252,15 @@ async function compile(specPaths, config) {
             if (!compileSkillToFile(spec, specPath))
                 allValid = false;
         }
+        else if (spec._specType === "agent") {
+            if (!compileAgentToFile(spec, specPath))
+                allValid = false;
+        }
+        else if (spec._specType === "railway") {
+            knownAgents ??= await collectAgentNames();
+            if (!compileRailwayToFile(spec, specPath, knownAgents))
+                allValid = false;
+        }
     }
     return allValid;
 }
@@ -433,6 +493,46 @@ function verifyMarkdownSymbols(files, silent) {
     }
     return errors;
 }
+/**
+ * Verify `vigiles:mcp server#tool` marks in instruction files against the live
+ * MCP servers declared in `.mcp.json` — the referenced tool must exist on the
+ * server (it gets started for the check). No `.mcp.json` ⇒ skipped; a server is
+ * only started if a mark actually references it. Returns the count of broken
+ * references. Async because it speaks to real servers.
+ */
+async function verifyMarkdownMcpRefs(files, silent) {
+    const cwd = process.cwd();
+    const servers = (0, mcp_js_1.loadMcpServers)(cwd);
+    if (files.length === 0 || Object.keys(servers).length === 0)
+        return 0;
+    let printedHeader = false;
+    let errors = 0;
+    for (const f of files) {
+        let markdown;
+        try {
+            markdown = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, f), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const broken = await (0, mcp_js_1.verifyMcpRefs)(markdown, servers);
+        if (broken.length === 0)
+            continue;
+        if (!silent) {
+            if (!printedHeader) {
+                console.log("\nMCP reference check:\n");
+                printedHeader = true;
+            }
+            for (const b of broken) {
+                const msg = (0, mcp_js_1.mcpRefMessage)(b);
+                console.log(`  ✗ ${f}:${String(b.line)} ${msg}`);
+                ghAnnotate("error", msg, f, b.line);
+            }
+        }
+        errors += broken.length;
+    }
+    return errors;
+}
 /** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
 function auditExitCode(report) {
     if (report.hashErrors > 0 ||
@@ -441,7 +541,8 @@ function auditExitCode(report) {
         report.frontmatterErrors > 0 ||
         report.integrityErrors > 0 ||
         report.coverageErrors > 0 ||
-        report.symbolRefErrors > 0)
+        report.symbolRefErrors > 0 ||
+        report.mcpRefErrors > 0)
         return 2;
     if (report.duplicatePairs > 0 ||
         report.orphanCount > 0 ||
@@ -730,6 +831,9 @@ async function audit(restArgs, flags, config) {
     }
     // 9. Verify code-shaped symbol references live (see src/refs.ts).
     const symbolRefErrors = verifyMarkdownSymbols(files, silent);
+    // 10. Verify `vigiles:mcp server#tool` marks against live MCP servers
+    // (only when a .mcp.json declares them). See src/mcp.ts.
+    const mcpRefErrors = await verifyMarkdownMcpRefs(files, silent);
     const report = {
         hashErrors: hashResult.hashErrors,
         validationErrors: hashResult.validationErrors,
@@ -746,6 +850,7 @@ async function audit(restArgs, flags, config) {
         orphanCount: orphanReport.orphans.length,
         docRefErrors: docRefReport.errors.length,
         symbolRefErrors,
+        mcpRefErrors,
         files,
     };
     if (summary) {
@@ -775,6 +880,8 @@ function printAuditSummary(report) {
         parts.push(`${String(report.docRefErrors)} broken doc refs`);
     if (report.symbolRefErrors > 0)
         parts.push(`${String(report.symbolRefErrors)} broken symbol refs`);
+    if (report.mcpRefErrors > 0)
+        parts.push(`${String(report.mcpRefErrors)} broken MCP refs`);
     const undocumented = report.coverageEnabled - report.coverageDocumented;
     if (undocumented > 0)
         parts.push(`${String(undocumented)} undocumented rules`);
@@ -1564,6 +1671,44 @@ function skillStartCommand(target) {
     (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
     console.log(`Active skill: ${target}`);
 }
+/**
+ * PreToolUse-hook entrypoint: enforce the active subagent's allowed-tools
+ * contract. Reads the tool event on stdin, parses the active agent's compiled
+ * `.md` tool rail, and blocks (exit 2 + reason on stderr) any tool outside it —
+ * the deterministic boundary `tools:` alone can't provide (Claude Code #54898).
+ */
+function agentHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let tool = "";
+    try {
+        tool = JSON.parse(raw).tool_name ?? "";
+    }
+    catch {
+        /* malformed input → no tool, allow */
+    }
+    if (!tool)
+        return;
+    const decision = (0, agent_runtime_js_1.evaluatePreToolUse)(process.cwd(), tool);
+    if (!decision.allow) {
+        console.error(decision.message);
+        process.exit(2);
+    }
+}
+/** Mark a subagent active so the PreToolUse hook enforces its tool contract. */
+function agentStartCommand(target) {
+    if (!target) {
+        console.error("Usage: vigiles agent-start <agents/<name>.md>");
+        process.exit(2);
+    }
+    (0, agent_runtime_js_1.setActiveAgent)(process.cwd(), target);
+    console.log(`Active agent: ${target}`);
+}
 /** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
 function handleSkillCommand(command, restArgs) {
     switch (command) {
@@ -1579,6 +1724,15 @@ function handleSkillCommand(command, restArgs) {
         case "skill-hook":
             skillHookCommand();
             return true;
+        case "agent-start":
+            agentStartCommand(restArgs[0]);
+            return true;
+        case "agent-done":
+            (0, agent_runtime_js_1.clearActiveAgent)(process.cwd());
+            return true;
+        case "agent-hook":
+            agentHookCommand();
+            return true;
         case "action-hook":
             actionHookCommand();
             return true;

package/dist/compile.d.ts

@@ -4,7 +4,7 @@
  * Reads .spec.ts files, validates references, and produces
  * markdown instruction files with integrity hashes.
  */
-import type { ClaudeSpec, SkillSpec } from "./spec.js";
+import type { ClaudeSpec, SkillSpec, AgentSpec, Railway } from "./spec.js";
 import type { LinterCheckResult } from "./linters.js";
 /** @internal Compute SHA-256 hash of content (excluding any existing hash line). */
 export declare function computeHash(content: string): string;
@@ -24,7 +24,7 @@ export declare function verifyHash(content: string): {
  */
 /** @internal */ export declare function estimateTokens(text: string): number;
 export interface CompileError {
-    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch";
+    type: "stale-file" | "stale-command" | "stale-ref" | "invalid-rule" | "budget-exceeded" | "section-too-long" | "section-has-header" | "reserved-section-key" | "spec-name-mismatch" | "unknown-tool" | "invalid-railway";
     message: string;
     path?: string;
 }
@@ -79,6 +79,35 @@ export declare function compileSkill(spec: SkillSpec, options?: {
     basePath?: string;
     specFile?: string;
 }): CompileSkillResult;
+export interface CompileAgentResult {
+    markdown: string;
+    errors: CompileError[];
+}
+/**
+ * Compile an AgentSpec into a subagent markdown file with YAML frontmatter.
+ * Verifies the tool contract and the body's references; the marks the body
+ * carries (`vigiles:symbol`, file/cmd refs) are the same ones `audit` re-checks.
+ */
+export declare function compileAgent(spec: AgentSpec, options?: {
+    basePath?: string;
+    specFile?: string;
+}): CompileAgentResult;
+export interface CompileRailwayOptions {
+    /** Names of compiled agents, to resolve `delegate` targets. Skipped if omitted. */
+    knownAgents?: readonly string[];
+    specFile?: string;
+}
+export interface CompileRailwayResult {
+    markdown: string;
+    errors: CompileError[];
+}
+/** Verify a railway: non-empty, bounded recovery, every delegate target real. */
+export declare function validateRailway(rw: Railway, knownAgents?: readonly string[]): CompileError[];
+/**
+ * Compile a railway into an orchestrator command markdown (with integrity hash),
+ * resolving every delegate target against `knownAgents` when provided.
+ */
+export declare function compileRailway(rw: Railway, options?: CompileRailwayOptions): CompileRailwayResult;
 export interface HashCheckResult {
     hasHash: boolean;
     valid: boolean;
@@ -101,5 +130,5 @@ export interface AdoptResult {
  * Compare a generated file against what the spec would produce.
  * Returns the diff so users can see what was manually changed.
  */
-export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec, basePath: string): AdoptResult;
+export declare function adoptDiff(filePath: string, spec: ClaudeSpec | SkillSpec | AgentSpec, basePath: string): AdoptResult;
 //# sourceMappingURL=compile.d.ts.map