alp-code 0.9.0

package/dist/src/runtime/render-session-context.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderSessionContext = renderSessionContext;
+/**
+ * Renders what is true for the whole session, regardless of what the principal asks next.
+ *
+ * This is the half of the old `renderCapsulePrompt` that must never become a user turn.
+ * It reaches both runtimes the same way — written to `session-context.md`, pointed at by
+ * `ALP_SESSION_CONTEXT`, and emitted by the SessionStart hook as `additionalContext`.
+ * Claude and Codex both land it as a developer-role message ahead of turn 1, so an
+ * interactive session is fully briefed while still waiting for its first real input.
+ *
+ * Nothing per-task belongs here: the current task and the memory selected for it live in
+ * `renderTaskInput`, because those do create a turn.
+ */
+/**
+ * The `Delegates to` row grants the roles; this says how to reach them.
+ *
+ * Neither runtime carries a delegation tool — `DelegationService` is reachable only through
+ * the `alp delegate` CLI, so the shell is the channel. Left unsaid, a role reads its grant,
+ * finds no tool matching it, and correctly reports itself blocked rather than inventing a
+ * command: the line above forbids exactly that guess. Naming the command is what turns the
+ * grant into something usable.
+ *
+ * Gated on the session-wide `Bash` grant rather than `capsule.allowedTools`, which is
+ * narrowed to the opening workflow state and would hide the section from a role that gets a
+ * shell one state later. Runtime enforcement reads the same session-wide grant.
+ *
+ * No identity appears in the command. `alp delegate` takes the caller from
+ * `ALP_DELEGATED_ROLE` in the inherited environment and rejects `--role` and
+ * `--parent-role`, so a role cannot delegate as anyone but itself.
+ */
+function delegationSection(capsule, policy) {
+    if (policy.delegatesTo.length === 0 || !policy.allowedTools.includes("Bash"))
+        return [];
+    return [
+        "## Delegation",
+        "",
+        "Specialists are separate executions, launched from your shell — there is no delegation tool. One role per call, task after `--`:",
+        "",
+        "```",
+        `alp delegate <role> --project ${capsule.activeWorkspace} -- "<task>"`,
+        "```",
+        "",
+        "Add `--background` to keep working while it runs, then follow it with `alp delegation status <id>` and `alp delegation wait <id>`.",
+        "",
+        "Pass no identity flag — the call inherits yours, and the roles in the table above are the only ones policy accepts. What comes back is a report to verify, not a result to forward unchecked.",
+        "",
+    ];
+}
+/**
+ * Teaches how to keep continuity alive across a runtime's own compaction.
+ *
+ * Gated on the same session-wide `Bash` grant as `delegationSection`, for the same reason:
+ * a read-only role (search, librarian, compaction…) has no shell to run `alp context pin`
+ * from, and a section it cannot act on would just be noise. `source: "agent"` therefore only
+ * ever shows up where the command is actually reachable.
+ */
+function continuitySection(policy) {
+    if (!policy.allowedTools.includes("Bash"))
+        return [];
+    return [
+        "## Continuity",
+        "",
+        "Record decisions and constraints the moment you settle them, not at the end of the session. After the runtime compacts, only what you pinned survives:",
+        "",
+        "```",
+        'alp context pin decision -- "chose X over Y because Z"',
+        'alp context pin constraint -- "do not touch Z"',
+        'alp context pin open-item -- "..."',
+        'alp context pin next-action -- "..."',
+        "```",
+        "",
+        "A pin is one sentence, not a summary. Never pin a secret or a file's contents.",
+        "",
+    ];
+}
+function renderSessionContext(capsule, policy) {
+    const list = (values) => values.length === 0 ? "—" : values.join(", ");
+    return [
+        `# ${capsule.displayName} — \`${capsule.role}\``,
+        "",
+        capsule.instructions,
+        "",
+        "## Authority",
+        "",
+        "| | |",
+        "| --- | --- |",
+        `| Workspace | ${policy.workspaceAccess === "none"
+            ? "— (no workspace grant; memory only)"
+            : `\`${capsule.activeWorkspace}\` (${policy.workspaceMode})`} |`,
+        // The session-wide grant, which is what both runtimes actually enforce. `capsule.allowedTools`
+        // is narrowed to the opening workflow state and only advances at the Stop hook, so printing
+        // it here told `main` it held three tools for a whole session in which it held nine — under a
+        // table that calls itself the whole of your authority. The workflow still gates the output
+        // contract; it was never the runtime's tool list.
+        `| Tools | ${list(policy.allowedTools)} |`,
+        // Named grants (§5.3). A role that holds none still sees the row: "you have no MCP
+        // server" is authority information, and its absence reads as an unanswered question.
+        `| Skills | ${list(policy.skills)} |`,
+        `| Subagents | ${list(policy.subagents.map((subagent) => subagent.name))} |`,
+        `| MCP servers | ${list(policy.mcpServers.map((server) => `${server.name} (${server.egress} egress)`))} |`,
+        `| Memory read | ${list(policy.memory.read)} |`,
+        `| Memory write | ${list(policy.memory.write)} |`,
+        `| Delegates to | ${list(policy.delegatesTo)} |`,
+        "",
+        "That table is the whole of your authority. If something you need is blocked, report it — do not route around it.",
+        "",
+        ...delegationSection(capsule, policy),
+        ...continuitySection(policy),
+        "## Invariants",
+        "",
+        capsule.memoryContext.invariantContext,
+        "",
+        "## Policy",
+        "",
+        capsule.memoryContext.policyContext,
+        "",
+        "## Reporting",
+        "",
+        "Answer in prose. Close with your status, what you actually did, and the evidence for it — commands you ran, files you changed, output you saw. Do not claim a step you skipped.",
+        "",
+    ].join("\n");
+}

package/dist/src/runtime/render-task-input.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderTaskInput = renderTaskInput;
+/**
+ * Renders the half of an execution that is *meant* to create a turn.
+ *
+ * Only a headless run has one. An interactive session gets its first turn from the
+ * principal, so no adapter may render this into a positional prompt there — that is the
+ * synthetic turn this split exists to remove.
+ *
+ * Memory sits here rather than in the session context because it is selected per task:
+ * `MemoryService.buildContext` runs against the task's queries and budget, and what it
+ * returns is state, not identity.
+ */
+function renderTaskInput(capsule) {
+    const memory = capsule.memoryContext.entries.length === 0
+        ? "(no memory entries selected)"
+        : capsule.memoryContext.entries
+            .map((entry) => `### ${entry.id}\n\n${entry.content}`)
+            .join("\n\n");
+    return [
+        `# ALP execution ${capsule.executionId}`,
+        "",
+        "## Relevant memory",
+        "",
+        memory,
+        "",
+        "## Task",
+        "",
+        capsule.task,
+        "",
+    ].join("\n");
+}

package/dist/src/runtime/runtime-adapter.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/runtime/runtime-preference-store.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileRuntimePreferenceStore = void 0;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+function isRuntimeId(value) {
+    return value === "claude" || value === "codex";
+}
+class FileRuntimePreferenceStore {
+    file;
+    constructor(options = {}) {
+        this.file = options.file ?? (0, node_path_1.join)((0, node_os_1.homedir)(), ".alp", "runtime.json");
+    }
+    async read() {
+        let content;
+        try {
+            content = await (0, promises_1.readFile)(this.file, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return { runtime: null };
+            }
+            return {
+                runtime: null,
+                warning: `invalid runtime preference at ${this.file}; using Claude default`,
+            };
+        }
+        try {
+            const parsed = JSON.parse(content);
+            if (parsed === null ||
+                typeof parsed !== "object" ||
+                !isRuntimeId(parsed.runtime)) {
+                throw new Error("invalid runtime");
+            }
+            return { runtime: parsed.runtime };
+        }
+        catch {
+            return {
+                runtime: null,
+                warning: `invalid runtime preference at ${this.file}; using Claude default`,
+            };
+        }
+    }
+    async write(runtime) {
+        if (!isRuntimeId(runtime)) {
+            throw new Error(`invalid runtime \`${String(runtime)}\``);
+        }
+        const directory = (0, node_path_1.dirname)(this.file);
+        await (0, promises_1.mkdir)(directory, { recursive: true, mode: 0o700 });
+        await (0, promises_1.chmod)(directory, 0o700);
+        const temporary = (0, node_path_1.join)(directory, `.${(0, node_crypto_1.randomUUID)()}.runtime.tmp`);
+        try {
+            await (0, promises_1.writeFile)(temporary, `${JSON.stringify({ runtime })}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+            await (0, promises_1.chmod)(temporary, 0o600);
+            await (0, promises_1.rename)(temporary, this.file);
+            await (0, promises_1.chmod)(this.file, 0o600);
+        }
+        catch (error) {
+            await (0, promises_1.rm)(temporary, { force: true });
+            throw error;
+        }
+    }
+}
+exports.FileRuntimePreferenceStore = FileRuntimePreferenceStore;

package/dist/src/runtime/runtime-selector.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeSelector = void 0;
+const node_stream_1 = require("node:stream");
+const node_readline_1 = require("node:readline");
+const runtime_preference_store_1 = require("./runtime-preference-store");
+const RUNTIMES = ["claude", "codex"];
+const LABELS = {
+    claude: "Claude",
+    codex: "Codex",
+};
+const DEFAULT_RUNTIME = "claude";
+function normalizeKeypress(sequence, key = {}) {
+    if (key.ctrl && key.name === "c")
+        return "cancel";
+    if (key.name === "up")
+        return "up";
+    if (key.name === "down")
+        return "down";
+    if (key.name === "return" ||
+        key.name === "enter" ||
+        sequence === "\r" ||
+        sequence === "\n") {
+        return "enter";
+    }
+    return "other";
+}
+function createKeypressReader(input) {
+    const decoder = new node_stream_1.PassThrough();
+    const queued = [];
+    const waiting = [];
+    let terminalError = null;
+    const onKeypress = (sequence, key) => {
+        const value = normalizeKeypress(sequence, key);
+        const waiter = waiting.shift();
+        if (waiter)
+            waiter.resolve(value);
+        else
+            queued.push(value);
+    };
+    const onError = (error) => {
+        terminalError = error;
+        for (const waiter of waiting.splice(0))
+            waiter.reject(error);
+    };
+    const onData = (chunk) => {
+        decoder.write(chunk);
+    };
+    (0, node_readline_1.emitKeypressEvents)(decoder);
+    decoder.on("keypress", onKeypress);
+    input.on("data", onData);
+    input.on("error", onError);
+    return {
+        read() {
+            const queuedKey = queued.shift();
+            if (queuedKey !== undefined)
+                return Promise.resolve(queuedKey);
+            if (terminalError !== null)
+                return Promise.reject(terminalError);
+            return new Promise((resolve, reject) => {
+                waiting.push({ resolve, reject });
+            });
+        },
+        close() {
+            input.removeListener("data", onData);
+            input.removeListener("error", onError);
+            decoder.removeListener("keypress", onKeypress);
+            decoder.destroy();
+        },
+    };
+}
+function renderMenu(output, current, selectedIndex, redraw) {
+    if (redraw)
+        output.write(`\u001b[${RUNTIMES.length + 1}A`);
+    for (const [index, runtime] of RUNTIMES.entries()) {
+        const pointer = index === selectedIndex ? "❯" : " ";
+        const persisted = runtime === current ? " (current)" : "";
+        output.write(`\r\u001b[2K  ${pointer} ${LABELS[runtime]}${persisted}\n`);
+    }
+    output.write("\r\u001b[2K↑/↓ select · Enter confirm · Ctrl+C cancel\n");
+}
+class RuntimeSelector {
+    preferenceStore;
+    input;
+    output;
+    injectedReadKey;
+    constructor(options = {}) {
+        this.preferenceStore = options.preferenceStore ?? new runtime_preference_store_1.FileRuntimePreferenceStore();
+        this.input = options.input ?? process.stdin;
+        this.output = options.output ?? process.stdout;
+        this.injectedReadKey = options.readKey;
+    }
+    async select(input) {
+        if (input.requestedRuntime !== undefined) {
+            if (!RUNTIMES.includes(input.requestedRuntime)) {
+                throw new Error(`invalid runtime \`${String(input.requestedRuntime)}\``);
+            }
+            return {
+                ok: true,
+                runtime: input.requestedRuntime,
+                source: "explicit",
+            };
+        }
+        const preference = await this.preferenceStore.read();
+        if (preference.warning) {
+            this.output.write(`WARNING  ${preference.warning}\n`);
+        }
+        const current = preference.runtime ?? DEFAULT_RUNTIME;
+        if (!input.interactive) {
+            return {
+                ok: true,
+                runtime: current,
+                source: preference.runtime === null ? "default" : "persisted",
+            };
+        }
+        const selected = await this.prompt(current);
+        if (selected === null)
+            return { ok: false, exitCode: 130 };
+        await this.preferenceStore.write(selected);
+        return { ok: true, runtime: selected, source: "interactive" };
+    }
+    async prompt(current) {
+        if (!this.injectedReadKey && !this.input) {
+            throw new Error("interactive runtime selection requires terminal input");
+        }
+        const wasFlowing = this.input?.readableFlowing === true;
+        const wasRaw = Boolean(this.input?.isRaw);
+        const keypress = this.injectedReadKey || !this.input
+            ? null
+            : createKeypressReader(this.input);
+        const readKey = this.injectedReadKey ?? keypress.read;
+        let changedRawMode = false;
+        let selectedIndex = Math.max(0, RUNTIMES.indexOf(current));
+        this.output.write("\nSelect runtime for this ALP session:\n");
+        this.output.write("\u001b[?25l");
+        try {
+            if (keypress &&
+                !wasRaw &&
+                typeof this.input?.setRawMode === "function") {
+                this.input.setRawMode(true);
+                changedRawMode = true;
+            }
+            if (keypress && typeof this.input?.resume === "function") {
+                this.input.resume();
+            }
+            renderMenu(this.output, current, selectedIndex, false);
+            for (;;) {
+                const key = await readKey();
+                if (key === "up") {
+                    selectedIndex = (selectedIndex - 1 + RUNTIMES.length) % RUNTIMES.length;
+                    renderMenu(this.output, current, selectedIndex, true);
+                }
+                else if (key === "down") {
+                    selectedIndex = (selectedIndex + 1) % RUNTIMES.length;
+                    renderMenu(this.output, current, selectedIndex, true);
+                }
+                else if (key === "enter") {
+                    return RUNTIMES[selectedIndex];
+                }
+                else if (key === "cancel") {
+                    return null;
+                }
+            }
+        }
+        finally {
+            keypress?.close();
+            if (keypress &&
+                !wasFlowing &&
+                typeof this.input?.pause === "function") {
+                this.input.pause();
+            }
+            if (changedRawMode)
+                this.input?.setRawMode?.(false);
+            this.output.write("\u001b[?25h");
+        }
+    }
+}
+exports.RuntimeSelector = RuntimeSelector;

package/dist/src/runtime/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/runtime/windows-shim.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSpawnCommand = resolveSpawnCommand;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Matches the launch line of a Windows batch shim: `"<node>" "<script>" %*`, anchored to
+ * one line so it cannot straddle the `SET "_prog=…"` line that precedes it in npm's shims.
+ */
+const LAUNCH_LINE = /"(?:%_prog%|[^"\r\n]*?node(?:\.exe)?)"[ \t]+([^\r\n]+?)[ \t]+%\*[ \t]*$/im;
+const ARGUMENT = /"([^"]*)"|(\S+)/g;
+function locate(command, env) {
+    if ((0, node_path_1.isAbsolute)(command) || /[\\/]/.test(command))
+        return (0, node_fs_1.existsSync)(command) ? command : null;
+    for (const directory of (env.PATH ?? env.Path ?? "").split(node_path_1.delimiter).filter(Boolean)) {
+        const candidate = (0, node_path_1.join)(directory, command);
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    return null;
+}
+function tokenize(launchArguments, directory) {
+    const tokens = [];
+    ARGUMENT.lastIndex = 0;
+    for (let match = ARGUMENT.exec(launchArguments); match; match = ARGUMENT.exec(launchArguments))
+        tokens.push((match[1] ?? match[2]).replace(/%~?dp0%?/gi, directory));
+    return tokens;
+}
+/**
+ * Node cannot spawn a Windows `.cmd`/`.bat` directly — it fails with EINVAL — and
+ * `shell: true` is not an option here: cmd.exe would re-parse the prompt argument, which
+ * carries spaces and quotes. Every such shim we launch (`claude.cmd`, `codex.cmd` from
+ * npm) wraps a Node script, so read the wrapper and spawn that script ourselves with
+ * argv passed through byte for byte.
+ *
+ * Anything else — a real `.exe`, any POSIX platform, a shim we cannot parse — is returned
+ * untouched, so the caller still gets the original error rather than a silent substitute.
+ */
+function resolveSpawnCommand(command, args, env = process.env, platform = process.platform, nodeExecutable = process.execPath) {
+    if (platform !== "win32" || !/\.(?:cmd|bat)$/i.test(command))
+        return { command, args };
+    const file = locate(command, env);
+    if (file === null)
+        return { command, args };
+    let text;
+    try {
+        text = (0, node_fs_1.readFileSync)(file, "utf8");
+    }
+    catch {
+        return { command, args };
+    }
+    const launch = LAUNCH_LINE.exec(text);
+    if (launch === null)
+        return { command, args };
+    const tokens = tokenize(launch[1], (0, node_path_1.dirname)(file));
+    return tokens.length === 0 ? { command, args } : { command: nodeExecutable, args: [...tokens, ...args] };
+}

package/dist/src/state-paths.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stateHome = stateHome;
+exports.memoryRoot = memoryRoot;
+exports.agentsDirectory = agentsDirectory;
+exports.hookForwarder = hookForwarder;
+exports.executionsDirectory = executionsDirectory;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/**
+ * Nơi ALP giữ state cục bộ, phía TypeScript.
+ *
+ * Từ v0.9.0 thư mục cài là artifact dùng một lần — `npm i -g` xoá sạch package dir cũ, bản
+ * tarball giải nén sang `versions/<tag>` mới — nên không thứ gì của người dùng được nằm trong
+ * đó. Mọi thứ sống lâu hơn một version đều ở `~/.alp`.
+ *
+ * Cùng bộ luật này có một bản CommonJS ở `scripts/lib/install-paths.cjs` cho installer và các
+ * script bảo trì, vì chúng phải chạy được khi `dist/` chưa tồn tại hoặc đã hỏng.
+ * `test/cli/state-paths.test.ts` so hai bản với nhau để chúng không trôi khỏi nhau.
+ */
+function stateHome(env = process.env) {
+    if (env.ALP_STATE_HOME)
+        return (0, node_path_1.resolve)(env.ALP_STATE_HOME);
+    const home = env.HOME || env.USERPROFILE || (0, node_os_1.homedir)();
+    if (!home)
+        throw new Error("không xác định được HOME/USERPROFILE");
+    return (0, node_path_1.join)(home, ".alp");
+}
+/** `ALP_MEMORY_ROOT` vẫn thắng: đó là đường duy nhất chạy được một ALP cô lập hoàn toàn. */
+function memoryRoot(env = process.env) {
+    return env.ALP_MEMORY_ROOT ? (0, node_path_1.resolve)(env.ALP_MEMORY_ROOT) : (0, node_path_1.join)(stateHome(env), "memory");
+}
+/** `~/.alp/agents/<role>.md` — cache identity phẳng mà SessionStart hook đọc. */
+function agentsDirectory(env = process.env) {
+    return (0, node_path_1.join)(stateHome(env), "agents");
+}
+/**
+ * Đường dẫn hook ổn định để ghi vào cấu hình project.
+ *
+ * File nhận đường dẫn này nằm trong repo của người dùng và sống lâu hơn mọi bản cài ALP.
+ * Trỏ thẳng vào thư mục cài là hẹn ngày hỏng câm: lên version, đổi channel, hay gỡ rồi cài
+ * lại chỗ khác đều làm nó chết mà phiên `claude` chỉ im lặng mất identity.
+ */
+function hookForwarder(name, env = process.env) {
+    return (0, node_path_1.join)(stateHome(env), "hooks", `${name}.cjs`);
+}
+function executionsDirectory(env = process.env) {
+    return (0, node_path_1.join)(stateHome(env), "executions");
+}

package/dist/src/workflow/output-validator.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineOutputContract = defineOutputContract;
+exports.validateOutput = validateOutput;
+const zod_1 = require("zod");
+function formatPath(path) {
+    return path.length === 0 ? "output" : path.map(String).join(".");
+}
+function defineOutputContract(name, schema) {
+    return Object.freeze({
+        name,
+        schema: (0, zod_1.toJSONSchema)(schema),
+        validate(value) {
+            const result = schema.safeParse(value);
+            if (result.success) {
+                return { ok: true, value: result.data };
+            }
+            return {
+                ok: false,
+                issues: Object.freeze(result.error.issues.map((issue) => `${formatPath(issue.path)}: ${issue.message}`)),
+            };
+        },
+    });
+}
+function validateOutput(contract, value) {
+    return contract.validate(value);
+}

package/dist/src/workflow/repair-policy.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_OUTPUT_REPAIR_ATTEMPTS = void 0;
+exports.canRepairOutput = canRepairOutput;
+exports.MAX_OUTPUT_REPAIR_ATTEMPTS = 1;
+function canRepairOutput(repairAttempts) {
+    return repairAttempts < exports.MAX_OUTPUT_REPAIR_ATTEMPTS;
+}

package/dist/src/workflow/types.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineLinearWorkflow = defineLinearWorkflow;
+function defineLinearWorkflow(id, linearStates) {
+    if (linearStates.length === 0) {
+        throw new Error(`workflow \`${id}\` must declare at least one state`);
+    }
+    const states = {};
+    linearStates.forEach((state, index) => {
+        const next = linearStates[index + 1];
+        states[state.id] = {
+            allowedTools: [...state.allowedTools],
+            transitions: next === undefined ? [] : [next.id],
+            ...(next === undefined ? { terminal: true } : {}),
+        };
+    });
+    return {
+        id,
+        initial: linearStates[0].id,
+        states,
+    };
+}

package/dist/src/workflow/workflow-runner.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowRunner = void 0;
+const output_validator_1 = require("./output-validator");
+const repair_policy_1 = require("./repair-policy");
+function stateSnapshot(workflowId, currentState, status, repairAttempts) {
+    return Object.freeze({ workflowId, currentState, status, repairAttempts });
+}
+function validateDefinition(definition) {
+    if (!definition.states[definition.initial]) {
+        throw new Error(`workflow \`${definition.id}\` has unknown initial state \`${definition.initial}\``);
+    }
+    for (const [stateId, state] of Object.entries(definition.states)) {
+        if (state.terminal && state.transitions.length > 0) {
+            throw new Error(`terminal workflow state \`${stateId}\` cannot declare transitions`);
+        }
+        for (const target of state.transitions) {
+            if (!definition.states[target]) {
+                throw new Error(`workflow state \`${stateId}\` has unknown transition target \`${target}\``);
+            }
+        }
+    }
+}
+function assertStateBelongsToWorkflow(definition, state) {
+    if (state.workflowId !== definition.id) {
+        throw new Error(`workflow state belongs to \`${state.workflowId}\`, not \`${definition.id}\``);
+    }
+    if (!definition.states[state.currentState]) {
+        throw new Error(`workflow \`${definition.id}\` has no state \`${state.currentState}\``);
+    }
+}
+class WorkflowRunner {
+    initialize(definition) {
+        validateDefinition(definition);
+        const initial = definition.states[definition.initial];
+        return stateSnapshot(definition.id, definition.initial, initial.terminal ? "awaiting-output" : "running", 0);
+    }
+    transition(definition, state, next) {
+        assertStateBelongsToWorkflow(definition, state);
+        if (state.status !== "running") {
+            throw new Error(`cannot transition workflow in \`${state.status}\` status`);
+        }
+        const current = definition.states[state.currentState];
+        if (!current.transitions.includes(next)) {
+            throw new Error(`transition \`${state.currentState}\` -> \`${next}\` is not declared`);
+        }
+        const target = definition.states[next];
+        return stateSnapshot(definition.id, next, target.terminal ? "awaiting-output" : "running", state.repairAttempts);
+    }
+    isToolAllowed(definition, state, tool) {
+        assertStateBelongsToWorkflow(definition, state);
+        return (state.status === "running" &&
+            definition.states[state.currentState].allowedTools.includes(tool));
+    }
+    submitOutput(state, contract, value) {
+        if (state.status !== "awaiting-output" && state.status !== "repairing") {
+            throw new Error(`cannot submit output in \`${state.status}\` status`);
+        }
+        const validation = (0, output_validator_1.validateOutput)(contract, value);
+        if (validation.ok) {
+            return Object.freeze({
+                state: stateSnapshot(state.workflowId, state.currentState, "completed", state.repairAttempts),
+                validation,
+            });
+        }
+        const repairAllowed = (0, repair_policy_1.canRepairOutput)(state.repairAttempts);
+        return Object.freeze({
+            state: stateSnapshot(state.workflowId, state.currentState, repairAllowed ? "repairing" : "failed", repairAllowed ? state.repairAttempts + 1 : state.repairAttempts),
+            validation,
+        });
+    }
+    cancel(state) {
+        if (state.status !== "running" &&
+            state.status !== "awaiting-output" &&
+            state.status !== "repairing") {
+            throw new Error(`cannot cancel workflow in \`${state.status}\` status`);
+        }
+        return stateSnapshot(state.workflowId, state.currentState, "cancelled", state.repairAttempts);
+    }
+}
+exports.WorkflowRunner = WorkflowRunner;