vigiles 2.1.1 → 2.2.0

package/dist/frontmatter.js

@@ -56,11 +56,11 @@ function findLine(lines, needle, fromIndex) {
     return fromIndex + 1;
 }
 /**
- * Navigate a parsed frontmatter document to its `vigiles.enforce` list.
- * Returns "none" when there's nothing for vigiles to check, "error" when a
- * `vigiles`/`enforce` key is present but the wrong shape, or the list.
+ * Navigate a parsed frontmatter document to its `vigiles` mapping. Returns
+ * "none" when there's nothing for vigiles to check, "error" when the
+ * `vigiles` key is present but not a mapping, or the mapping itself.
  */
-function lookupEnforce(doc, lines, startLine) {
+function getVigiles(doc, lines, startLine) {
     if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
         return { kind: "none" };
     }
@@ -78,6 +78,13 @@ function lookupEnforce(doc, lines, startLine) {
             },
         };
     }
+    return { kind: "map", vigiles: vigiles };
+}
+/**
+ * Locate the `vigiles.enforce` list. Returns "none" when absent, "error" when
+ * present but not a list, or the list with its source line.
+ */
+function lookupEnforce(vigiles, lines, startLine) {
     const enforce = vigiles.enforce;
     if (enforce === undefined)
         return { kind: "none" };
@@ -93,6 +100,45 @@ function lookupEnforce(doc, lines, startLine) {
     }
     return { kind: "list", enforce, enforceLine };
 }
+/**
+ * Parse a `vigiles.<key>` list of plain strings (used for `files` and
+ * `commands`). Returns located items plus error findings for the wrong shape
+ * or non-string entries; an absent key yields empty results.
+ */
+function parseStringList(vigiles, key, lines, startLine) {
+    const raw = vigiles[key];
+    if (raw === undefined)
+        return { items: [], errors: [] };
+    const keyLine = findLine(lines, `${key}:`, startLine - 1);
+    if (!Array.isArray(raw)) {
+        return {
+            items: [],
+            errors: [
+                {
+                    line: keyLine,
+                    message: `\`vigiles.${key}\` must be a list of strings.`,
+                },
+            ],
+        };
+    }
+    const items = [];
+    const errors = [];
+    let cursor = keyLine;
+    for (let i = 0; i < raw.length; i++) {
+        const v = raw[i];
+        if (typeof v !== "string" || v.trim() === "") {
+            errors.push({
+                line: keyLine,
+                message: `vigiles.${key}[${String(i)}] must be a non-empty string.`,
+            });
+            continue;
+        }
+        const line = findLine(lines, v, cursor);
+        cursor = line;
+        items.push({ value: v, line });
+    }
+    return { items, errors };
+}
 /** Parse one `vigiles.enforce` entry into a rule or an error finding. */
 function parseEntry(entry, index, ctx) {
     if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
@@ -126,10 +172,15 @@ function parseEntry(entry, index, ctx) {
     }
     return { rule: { linterRule: rule, why, line }, nextCursor: line };
 }
+/** Fresh empty result — callers may push into the arrays, so never shared. */
+function emptyResult() {
+    return { rules: [], files: [], commands: [], errors: [] };
+}
 /**
- * Parse `vigiles.enforce` rules out of a markdown file's YAML frontmatter.
- * Does not touch the filesystem and does not verify rules against any
- * linter — callers feed the returned rules into `checkLinterRule`.
+ * Parse `vigiles.enforce` rules, `vigiles.files`, and `vigiles.commands` out
+ * of a markdown file's YAML frontmatter. Does not touch the filesystem and
+ * does not verify references — callers feed rules into `checkLinterRule` and
+ * file/command refs into `validateFileRef` / `validateCommandRef`.
  *
  * A file with no frontmatter, or frontmatter with no `vigiles` key, yields
  * empty results with no errors. Malformed YAML or a malformed `vigiles`
@@ -138,7 +189,7 @@ function parseEntry(entry, index, ctx) {
 function parseFrontmatterRules(content) {
     const fm = extractFrontmatter(content);
     if (!fm)
-        return { rules: [], errors: [] };
+        return emptyResult();
     const lines = content.split("\n");
     let doc;
     try {
@@ -149,6 +200,8 @@ function parseFrontmatterRules(content) {
         const line = (err.mark?.line ?? 0) + fm.startLine;
         return {
             rules: [],
+            files: [],
+            commands: [],
             errors: [
                 {
                     line,
@@ -157,34 +210,54 @@ function parseFrontmatterRules(content) {
             ],
         };
     }
-    const lookup = lookupEnforce(doc, lines, fm.startLine);
-    if (lookup.kind === "none")
-        return { rules: [], errors: [] };
-    if (lookup.kind === "error")
-        return { rules: [], errors: [lookup.error] };
+    const vig = getVigiles(doc, lines, fm.startLine);
+    if (vig.kind === "none")
+        return emptyResult();
+    if (vig.kind === "error")
+        return { rules: [], files: [], commands: [], errors: [vig.error] };
     const rules = [];
     const errors = [];
-    let cursor = lookup.enforceLine; // search start: line after `enforce:`
-    for (let i = 0; i < lookup.enforce.length; i++) {
-        const r = parseEntry(lookup.enforce[i], i, {
-            lines,
-            enforceLine: lookup.enforceLine,
-            cursor,
-        });
-        cursor = r.nextCursor;
-        if (r.rule)
-            rules.push(r.rule);
-        if (r.error)
-            errors.push(r.error);
+    const enforceLookup = lookupEnforce(vig.vigiles, lines, fm.startLine);
+    if (enforceLookup.kind === "error") {
+        errors.push(enforceLookup.error);
+    }
+    else if (enforceLookup.kind === "list") {
+        let cursor = enforceLookup.enforceLine; // search start: line after `enforce:`
+        for (let i = 0; i < enforceLookup.enforce.length; i++) {
+            const r = parseEntry(enforceLookup.enforce[i], i, {
+                lines,
+                enforceLine: enforceLookup.enforceLine,
+                cursor,
+            });
+            cursor = r.nextCursor;
+            if (r.rule)
+                rules.push(r.rule);
+            if (r.error)
+                errors.push(r.error);
+        }
     }
-    return { rules, errors };
+    const fileList = parseStringList(vig.vigiles, "files", lines, fm.startLine);
+    errors.push(...fileList.errors);
+    const files = fileList.items.map((it) => ({
+        path: it.value,
+        line: it.line,
+    }));
+    const cmdList = parseStringList(vig.vigiles, "commands", lines, fm.startLine);
+    errors.push(...cmdList.errors);
+    const commands = cmdList.items.map((it) => ({
+        command: it.value,
+        line: it.line,
+    }));
+    return { rules, files, commands, errors };
 }
 /**
- * True if the content has at least one parseable `vigiles.enforce` rule in
- * its frontmatter. Used by `require-spec` validation to treat frontmatter
- * mode as spec-equivalent, mirroring `hasInlineRules`.
+ * True if the content has at least one parseable `vigiles` reference in its
+ * frontmatter — an `enforce` rule, a `files` entry, or a `commands` entry.
+ * Used by `require-spec` validation to treat frontmatter mode as
+ * spec-equivalent, mirroring `hasInlineRules`.
  */
 function hasFrontmatterRules(content) {
-    return parseFrontmatterRules(content).rules.length > 0;
+    const r = parseFrontmatterRules(content);
+    return r.rules.length + r.files.length + r.commands.length > 0;
 }
 //# sourceMappingURL=frontmatter.js.map

package/dist/generate-schema.js

@@ -101,6 +101,16 @@ function generateSchema(options = {}) {
                             },
                         },
                     },
+                    files: {
+                        type: "array",
+                        description: "File paths referenced by this instruction file, verified to exist by `vigiles audit`.",
+                        items: { type: "string" },
+                    },
+                    commands: {
+                        type: "array",
+                        description: "Commands (npm scripts / script-runner invocations) referenced here, verified by `vigiles audit`.",
+                        items: { type: "string" },
+                    },
                 },
             },
         },

package/dist/harness-test.d.ts

@@ -0,0 +1,38 @@
+import { type ModelTurn } from "./mock-model.js";
+export { scriptModel, type ModelTurn } from "./mock-model.js";
+export interface HarnessTestSpec {
+    /** Fixture files to write in a fresh temp working dir (path → contents). */
+    readonly files?: Record<string, string>;
+    /** `.claude/settings.json` contents — the hooks/permissions under test. */
+    readonly settings?: unknown;
+    /** The scripted model turns the agent will take. */
+    readonly model: readonly ModelTurn[];
+    /** The user prompt. Default: "go". */
+    readonly prompt?: string;
+    /** Tools the agent may use. Default: Read Edit Write Bash. */
+    readonly allowedTools?: readonly string[];
+    /** Per-run wall-clock timeout in ms. Default 60000. */
+    readonly timeoutMs?: number;
+}
+export interface HarnessTestResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    /** Hook block messages and diagnostics land here. */
+    readonly stderr: string;
+    /** The temp working dir (inspect or clean it up). */
+    readonly cwd: string;
+    /** Number of model turns the agent took (mock turns served). */
+    readonly turns: number;
+    /** Final contents of a file under the working dir, or null if absent. */
+    file(path: string): string | null;
+    /** Remove the temp working dir. */
+    cleanup(): void;
+}
+/** Whether the `claude` CLI is available — harness tests need it. */
+export declare function claudeAvailable(): boolean;
+/**
+ * Run the real `claude` CLI against a scripted mock model, with the given
+ * fixture and settings (hooks). Deterministic — same script, same result.
+ */
+export declare function runHarnessTest(spec: HarnessTestSpec): Promise<HarnessTestResult>;
+//# sourceMappingURL=harness-test.d.ts.map

package/dist/harness-test.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scriptModel = void 0;
+exports.claudeAvailable = claudeAvailable;
+exports.runHarnessTest = runHarnessTest;
+/**
+ * vigiles — deterministic Claude Code harness testing.
+ *
+ * Test what your *harness* does — hooks, settings, skills, instruction files —
+ * without paying for or depending on a real model. `runHarnessTest` spins up the
+ * real `claude` CLI (so your real hooks and settings fire exactly as in
+ * production) but points it at a scripted mock model (`src/mock-model.ts`), so
+ * the agent's turns are fixed and the outcome is reproducible. No API key, no
+ * cost, CI-friendly.
+ *
+ *   const r = await runHarnessTest({
+ *     settings: { hooks: { Stop: [{ hooks: [{ type: "command",
+ *       command: "test -f DONE || { echo 'not done' >&2; exit 2; }" }] }] } },
+ *     model: scriptModel([
+ *       { text: "I'm done" },                              // tries to stop → blocked
+ *       { tool: "Bash", input: { command: "touch DONE" } },
+ *       { text: "now done" },
+ *     ]),
+ *   });
+ *   assert(JSON.parse(r.stdout).num_turns > 1);            // the Stop hook fired
+ *
+ * The "steps" are the scripted model turns — their real home is deterministic
+ * harness testing, not production enforcement.
+ *
+ * Note: the simple mock drives the Bash tool and Stop hooks reliably; the
+ * Edit/Write tools are gated in headless mode and don't fire via the mock —
+ * drive file actions through Bash, or use the real-model eval tier (`eval.ts`)
+ * for Edit/Write hooks.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const mock_model_js_1 = require("./mock-model.js");
+var mock_model_js_2 = require("./mock-model.js");
+Object.defineProperty(exports, "scriptModel", { enumerable: true, get: function () { return mock_model_js_2.scriptModel; } });
+/** Whether the `claude` CLI is available — harness tests need it. */
+function claudeAvailable() {
+    try {
+        return (0, node_child_process_1.spawnSync)("claude", ["--version"], { stdio: "ignore" }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function writeFixture(cwd, spec) {
+    for (const [p, content] of Object.entries(spec.files ?? {})) {
+        const full = (0, node_path_1.resolve)(cwd, p);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(full), { recursive: true });
+        (0, node_fs_1.writeFileSync)(full, content);
+    }
+    if (spec.settings !== undefined) {
+        // `{cwd}` in any hook command is substituted with the working dir, so a
+        // hook can reference an absolute path inside it (hooks don't run with the
+        // project dir as cwd).
+        const json = JSON.stringify(spec.settings, null, 2).replaceAll("{cwd}", cwd);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(cwd, "settings.json"), json);
+    }
+}
+function spawnClaude(args, cwd, baseUrl, timeoutMs) {
+    return new Promise((resolvePromise) => {
+        const child = (0, node_child_process_1.spawn)("claude", args, {
+            cwd,
+            env: {
+                ...process.env,
+                ANTHROPIC_BASE_URL: baseUrl,
+                // Any value works — the mock ignores auth; this avoids needing a real key.
+                ANTHROPIC_API_KEY: "sk-vigiles-mock",
+            },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (d) => (stdout += d.toString()));
+        child.stderr.on("data", (d) => (stderr += d.toString()));
+        const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolvePromise({ code: code ?? 0, stdout, stderr });
+        });
+    });
+}
+/**
+ * Run the real `claude` CLI against a scripted mock model, with the given
+ * fixture and settings (hooks). Deterministic — same script, same result.
+ */
+async function runHarnessTest(spec) {
+    const cwd = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), "vigiles-harness-"));
+    writeFixture(cwd, spec);
+    const mock = await (0, mock_model_js_1.startMock)(spec.model);
+    try {
+        const tools = spec.allowedTools ?? ["Read", "Edit", "Write", "Bash"];
+        const args = [
+            "-p",
+            spec.prompt ?? "go",
+            "--output-format",
+            "json",
+            "--model",
+            "claude-sonnet-4-5",
+            ...(spec.settings !== undefined ? ["--settings", "settings.json"] : []),
+            "--allowedTools",
+            ...tools,
+        ];
+        const out = await spawnClaude(args, cwd, mock.url, spec.timeoutMs ?? 60000);
+        return {
+            exitCode: out.code,
+            stdout: out.stdout,
+            stderr: out.stderr,
+            cwd,
+            turns: mock.count,
+            file: (p) => {
+                const f = (0, node_path_1.resolve)(cwd, p);
+                return (0, node_fs_1.existsSync)(f) ? (0, node_fs_1.readFileSync)(f, "utf-8") : null;
+            },
+            cleanup: () => {
+                (0, node_fs_1.rmSync)(cwd, { recursive: true, force: true });
+            },
+        };
+    }
+    finally {
+        mock.close();
+    }
+}
+//# sourceMappingURL=harness-test.js.map

package/dist/inline.d.ts

@@ -25,8 +25,24 @@ export interface InlineRule {
     /** 1-based line number of the comment in the source file. */
     line: number;
 }
+/** A `<!-- vigiles:file <path> -->` reference (verified to exist). */
+export interface InlineFileRef {
+    /** Project-relative path to verify exists. */
+    path: string;
+    /** 1-based line number of the comment in the source file. */
+    line: number;
+}
+/** A `<!-- vigiles:cmd "<command>" -->` reference (npm scripts verified). */
+export interface InlineCmdRef {
+    /** Command to verify (npm scripts checked against package.json). */
+    command: string;
+    /** 1-based line number of the comment in the source file. */
+    line: number;
+}
 export interface InlineParseResult {
     rules: InlineRule[];
+    files: InlineFileRef[];
+    commands: InlineCmdRef[];
     /** Lines that look like vigiles: markers but failed to parse. */
     errors: {
         line: number;
@@ -46,13 +62,15 @@ export interface InlineParseResult {
  */
 export declare function parseInlineRules(content: string): InlineParseResult;
 /**
- * True if the content contains at least one parseable vigiles:enforce
- * rule (ignoring fenced code blocks and malformed markers). Used by
- * `require-spec` validation to treat inline mode as spec-equivalent.
+ * True if the content contains at least one parseable vigiles inline marker —
+ * an `enforce` rule, a `file` reference, or a `cmd` reference (ignoring fenced
+ * code blocks and malformed markers). Used by `require-spec` validation to
+ * treat inline mode as spec-equivalent: a file that pins even a single path is
+ * meaningfully managed.
  *
  * Deliberately delegates to `parseInlineRules` so a loose prefix regex
  * can't satisfy require-spec with a malformed marker that produces no
- * real enforceable rule.
+ * real reference.
  */
 export declare function hasInlineRules(content: string): boolean;
 //# sourceMappingURL=inline.d.ts.map

package/dist/inline.js

@@ -29,6 +29,17 @@ exports.hasInlineRules = hasInlineRules;
  * embedded quotes, they can move to spec mode.
  */
 const ENFORCE_RE = /<!--\s*vigiles:enforce\s+([@A-Za-z0-9_/:.-]+)\s+"([^"\n]*)"\s*-->/;
+/**
+ * Match `<!-- vigiles:file <path> -->`. The path is a single whitespace-free
+ * token (project-relative); spaces in paths are vanishingly rare and would be
+ * ambiguous against the closing `-->`.
+ */
+const FILE_RE = /<!--\s*vigiles:file\s+(\S+)\s*-->/;
+/**
+ * Match `<!-- vigiles:cmd "<command>" -->`. The command is quoted because
+ * commands contain spaces (e.g. `npm run build`).
+ */
+const CMD_RE = /<!--\s*vigiles:cmd\s+"([^"\n]*)"\s*-->/;
 /**
  * Detects any `<!-- vigiles:<kind> -->` comment (valid or not) so we can
  * surface errors for typos and reserved-but-unrecognized kinds. Uses a
@@ -36,6 +47,16 @@ const ENFORCE_RE = /<!--\s*vigiles:enforce\s+([@A-Za-z0-9_/:.-]+)\s+"([^"\n]*)"\
  * circuit the pattern.
  */
 const MARKER_RE = /<!--\s*vigiles:([A-Za-z_-]+)[^]*?-->/;
+// vigiles markers handled by other subsystems (skill runtime gates, opt-outs).
+// The inline *rule* parser skips them rather than flagging them as unknown.
+const KNOWN_NON_RULE_MARKERS = new Set([
+    "disable",
+    "ignore",
+    "ignore-file",
+    "gate", // skill step gate (src/skill-runtime.ts)
+    "result", // skill result gate
+    "symbol", // symbol reference mark (src/refs.ts)
+]);
 /**
  * Parse inline vigiles rules out of a markdown file's contents.
  * Does not touch the filesystem and does not verify the rules against
@@ -48,6 +69,8 @@ const MARKER_RE = /<!--\s*vigiles:([A-Za-z_-]+)[^]*?-->/;
  */
 function parseInlineRules(content) {
     const rules = [];
+    const files = [];
+    const commands = [];
     const errors = [];
     const lines = content.split("\n");
     let fenceChar = null;
@@ -97,15 +120,24 @@ function parseInlineRules(content) {
             });
             continue;
         }
+        const fileMatch = FILE_RE.exec(scannable);
+        if (fileMatch) {
+            files.push({ path: fileMatch[1], line: i + 1 });
+            continue;
+        }
+        const cmdMatch = CMD_RE.exec(scannable);
+        if (cmdMatch) {
+            commands.push({ command: cmdMatch[1], line: i + 1 });
+            continue;
+        }
         // Skip the compiled-file hash header (`<!-- vigiles:sha256:... -->`)
         // entirely — it's not a rule marker and should not be reported.
         if (/<!--\s*vigiles:sha\d+:/.test(scannable))
             continue;
         const markerMatch = MARKER_RE.exec(scannable);
         if (markerMatch) {
-            // Looks like a vigiles marker but didn't parse as enforce —
-            // surface it so users catch typos like "vigile:enforce" or
-            // unquoted why.
+            // Looks like a vigiles marker but didn't parse — surface it so users
+            // catch typos like "vigile:enforce" or an unquoted why/command.
             const kind = markerMatch[1];
             if (kind === "enforce") {
                 errors.push({
@@ -114,29 +146,44 @@ function parseInlineRules(content) {
                     raw: line.trim(),
                 });
             }
-            else if (kind !== "disable" && kind !== "ignore") {
-                // `vigiles:disable ...` / `vigiles:ignore ...` are reserved for
-                // future disable-comment support; don't complain about them.
+            else if (kind === "file") {
+                errors.push({
+                    line: i + 1,
+                    message: "Malformed vigiles:file — expected `<!-- vigiles:file <path> -->`",
+                    raw: line.trim(),
+                });
+            }
+            else if (kind === "cmd") {
+                errors.push({
+                    line: i + 1,
+                    message: 'Malformed vigiles:cmd — expected `<!-- vigiles:cmd "<command>" -->`',
+                    raw: line.trim(),
+                });
+            }
+            else if (!KNOWN_NON_RULE_MARKERS.has(kind)) {
                 errors.push({
                     line: i + 1,
-                    message: `Unknown vigiles marker "${kind}". Only \`vigiles:enforce\` is supported.`,
+                    message: `Unknown vigiles marker "${kind}". Only \`vigiles:enforce\`, \`vigiles:file\`, and \`vigiles:cmd\` are supported.`,
                     raw: line.trim(),
                 });
             }
         }
     }
-    return { rules, errors };
+    return { rules, files, commands, errors };
 }
 /**
- * True if the content contains at least one parseable vigiles:enforce
- * rule (ignoring fenced code blocks and malformed markers). Used by
- * `require-spec` validation to treat inline mode as spec-equivalent.
+ * True if the content contains at least one parseable vigiles inline marker —
+ * an `enforce` rule, a `file` reference, or a `cmd` reference (ignoring fenced
+ * code blocks and malformed markers). Used by `require-spec` validation to
+ * treat inline mode as spec-equivalent: a file that pins even a single path is
+ * meaningfully managed.
  *
  * Deliberately delegates to `parseInlineRules` so a loose prefix regex
  * can't satisfy require-spec with a malformed marker that produces no
- * real enforceable rule.
+ * real reference.
  */
 function hasInlineRules(content) {
-    return parseInlineRules(content).rules.length > 0;
+    const r = parseInlineRules(content);
+    return r.rules.length + r.files.length + r.commands.length > 0;
 }
 //# sourceMappingURL=inline.js.map

package/dist/linters.js

@@ -20,6 +20,34 @@ const node_path_1 = require("node:path");
 const node_child_process_1 = require("node:child_process");
 const node_module_1 = require("node:module");
 const glob_1 = require("glob");
+/**
+ * Prepend version-manager shim directories (rbenv / asdf / rvm) to PATH so
+ * gem/pip-installed linters are found in non-login shells and CI, where the
+ * shims dir is often missing from PATH even though the tool is installed.
+ * Runs once; only adds directories that exist and aren't already present.
+ */
+function augmentToolPath() {
+    const home = process.env.HOME ?? "";
+    // rbenv/asdf shims don't resolve without a selected version, so add the
+    // concrete per-version `bin` dirs (where the gem executables actually live).
+    const candidates = [
+        ...(0, glob_1.globSync)("/opt/rbenv/versions/*/bin", { nodir: false }),
+        ...(home
+            ? (0, glob_1.globSync)(`${home}/.rbenv/versions/*/bin`, { nodir: false })
+            : []),
+        ...(home
+            ? (0, glob_1.globSync)(`${home}/.asdf/installs/*/*/bin`, { nodir: false })
+            : []),
+        `${home}/.rvm/bin`,
+        `${home}/.local/bin`,
+    ];
+    const current = (process.env.PATH ?? "").split(":");
+    const additions = candidates.filter((d) => d && (0, node_fs_1.existsSync)(d) && !current.includes(d));
+    if (additions.length > 0) {
+        process.env.PATH = [...current, ...additions].join(":");
+    }
+}
+augmentToolPath();
 // ---------------------------------------------------------------------------
 // Parsing enforcement references
 // ---------------------------------------------------------------------------

package/dist/mock-model.d.ts

@@ -0,0 +1,31 @@
+/** One scripted assistant turn: a final text answer, or a tool call. */
+export interface ModelTurn {
+    /** Final text answer (stops the turn). */
+    readonly text?: string;
+    /** A tool to invoke, e.g. "Bash" | "Write" | "Edit". */
+    readonly tool?: string;
+    /** The tool input, e.g. `{ file_path, content }` or `{ command }`. */
+    readonly input?: Record<string, unknown>;
+}
+/** Build a scripted model from an ordered list of turns. */
+export declare function scriptModel(turns: readonly ModelTurn[]): ModelTurn[];
+export interface TurnInfo {
+    readonly n: number;
+    readonly stream: boolean;
+    readonly hasToolResult: boolean;
+}
+export interface MockHandle {
+    readonly url: string;
+    close(): void;
+    /** Number of model turns served so far. */
+    readonly count: number;
+}
+/**
+ * Start the scripted mock on a free port. Each `/v1/messages` POST consumes the
+ * next turn (the last turn repeats if the client asks for more). Resolves to a
+ * handle with the base `url` and a `close()`.
+ */
+export declare function startMock(script: readonly ModelTurn[], opts?: {
+    onTurn?: (info: TurnInfo) => void;
+}): Promise<MockHandle>;
+//# sourceMappingURL=mock-model.d.ts.map