oxe-cc 1.5.1 → 1.7.0

package/lib/runtime/executor/llm-task-executor.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LlmTaskExecutor = void 0;
+const stream_completion_1 = require("./stream-completion");
+const built_in_tools_1 = require("./built-in-tools");
+const action_tool_map_1 = require("./action-tool-map");
+const node_prompt_builder_1 = require("./node-prompt-builder");
+const DEFAULT_SYSTEM_PROMPT = 'You are a precise software engineering agent. Use the tools provided to complete the task. ' +
+    'When the task is done, summarize what was accomplished in your final message without calling any tools.';
+class LlmTaskExecutor {
+    constructor(provider, registry, onProgress) {
+        this.provider = provider;
+        this.registry = registry;
+        this.onProgress = onProgress;
+    }
+    async execute(node, lease, runId, attempt) {
+        const prompt = (0, node_prompt_builder_1.buildNodePrompt)(node, lease, runId, attempt);
+        const tools = (0, action_tool_map_1.selectToolsForActions)(node.actions);
+        const cwd = lease.root_path;
+        const maxTurns = this.provider.maxTurns ?? 10;
+        const systemPrompt = this.provider.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+        const messages = [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: prompt },
+        ];
+        let finalOutput = '';
+        const evidencePaths = [];
+        for (let turn = 0; turn < maxTurns; turn++) {
+            this.emit({ type: 'turn_start', nodeId: node.id, attempt, detail: { turn } });
+            let response;
+            try {
+                response = await (0, stream_completion_1.streamCompletion)({
+                    baseUrl: this.provider.baseUrl,
+                    apiKey: this.provider.apiKey,
+                    model: this.provider.model,
+                    messages,
+                    tools: tools.length > 0 ? tools : undefined,
+                    maxTokens: this.provider.maxTokens,
+                    timeoutMs: this.provider.timeoutMs,
+                });
+            }
+            catch (err) {
+                return { success: false, failure_class: 'env', evidence: evidencePaths, output: String(err) };
+            }
+            this.emit({ type: 'turn_complete', nodeId: node.id, attempt, detail: { turn, finish_reason: response.finish_reason } });
+            if (response.content)
+                finalOutput = response.content;
+            if (!response.tool_calls.length)
+                break;
+            messages.push({
+                role: 'assistant',
+                content: response.content || null,
+                tool_calls: response.tool_calls,
+            });
+            // Partition: idempotent tools run concurrently, mutations run serially
+            const [concurrent, serial] = partitionToolCalls(response.tool_calls, tools);
+            const concurrentResults = await Promise.all(concurrent.map((tc) => this.invokeToolCall(tc, cwd, node, evidencePaths)));
+            const serialResults = [];
+            for (const tc of serial) {
+                serialResults.push(await this.invokeToolCall(tc, cwd, node, evidencePaths));
+            }
+            messages.push(...concurrentResults, ...serialResults);
+        }
+        return {
+            success: true,
+            failure_class: null,
+            evidence: evidencePaths,
+            output: finalOutput,
+        };
+    }
+    async invokeToolCall(tc, cwd, node, evidencePaths) {
+        this.emit({ type: 'tool_call', nodeId: node.id, attempt: 0, detail: { tool: tc.function.name } });
+        let args = {};
+        try {
+            args = JSON.parse(tc.function.arguments || '{}');
+        }
+        catch {
+            // malformed args — pass empty
+        }
+        let result;
+        const builtIn = built_in_tools_1.BUILT_IN_TOOLS[tc.function.name];
+        if (builtIn) {
+            try {
+                result = await builtIn.execute(args, cwd);
+                if (tc.function.name === 'write_file' || tc.function.name === 'patch_file') {
+                    if (typeof args.path === 'string')
+                        evidencePaths.push(args.path);
+                }
+            }
+            catch (err) {
+                result = `[tool error] ${err}`;
+            }
+        }
+        else {
+            // Delegate to plugin registry
+            const provider = this.registry?.toolProviderFor(tc.function.name);
+            if (provider) {
+                try {
+                    const res = await provider.invoke({
+                        action_type: tc.function.name,
+                        work_item_id: node.id,
+                        run_id: '',
+                        attempt_id: '',
+                        params: args,
+                        workspace_root: cwd,
+                    });
+                    result = res.output || (res.success ? 'done' : res.error ?? 'failed');
+                    evidencePaths.push(...res.evidence_paths);
+                }
+                catch (err) {
+                    result = `[plugin error] ${err}`;
+                }
+            }
+            else {
+                result = `[unknown tool: ${tc.function.name}]`;
+            }
+        }
+        this.emit({ type: 'tool_result', nodeId: node.id, attempt: 0, detail: { tool: tc.function.name, length: result.length } });
+        return {
+            role: 'tool',
+            tool_call_id: tc.id,
+            name: tc.function.name,
+            content: result,
+        };
+    }
+    emit(event) {
+        this.onProgress?.(event);
+    }
+}
+exports.LlmTaskExecutor = LlmTaskExecutor;
+function partitionToolCalls(toolCalls, schemas) {
+    const idempotentNames = new Set(schemas
+        .map((s) => s.function.name)
+        .filter((name) => built_in_tools_1.BUILT_IN_TOOLS[name]?.idempotent ?? true));
+    const concurrent = toolCalls.filter((tc) => idempotentNames.has(tc.function.name));
+    const serial = toolCalls.filter((tc) => !idempotentNames.has(tc.function.name));
+    return [concurrent, serial];
+}

package/lib/runtime/executor/node-prompt-builder.d.ts

@@ -0,0 +1,3 @@
+import type { GraphNode } from '../compiler/graph-compiler';
+import type { WorkspaceLease } from '../models/workspace';
+export declare function buildNodePrompt(node: GraphNode, lease: WorkspaceLease, runId: string, attempt: number): string;

package/lib/runtime/executor/node-prompt-builder.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildNodePrompt = buildNodePrompt;
+function buildNodePrompt(node, lease, runId, attempt) {
+    const lines = [
+        `# Tarefa: ${node.title}`,
+        '',
+        `**Run:** ${runId} | **Attempt:** ${attempt}`,
+        `**Workspace:** ${lease.root_path}`,
+    ];
+    if (node.mutation_scope.length > 0) {
+        lines.push(`**Escopo de mutação:** ${node.mutation_scope.join(', ')}`);
+    }
+    if (node.actions.length > 0) {
+        lines.push('', '## Ações requeridas');
+        for (const action of node.actions) {
+            let line = `- ${action.type}`;
+            if (action.command)
+                line += `: \`${action.command}\``;
+            if (action.targets?.length)
+                line += ` em ${action.targets.join(', ')}`;
+            lines.push(line);
+        }
+    }
+    if (node.verify.must_pass.length > 0) {
+        lines.push('', '## Critérios de aceite');
+        for (const criterion of node.verify.must_pass) {
+            lines.push(`- ${criterion}`);
+        }
+    }
+    if (node.verify.command) {
+        lines.push('', `**Verificação:** \`${node.verify.command}\``);
+    }
+    lines.push('', 'Execute as ações acima usando as ferramentas disponíveis e confirme o resultado.');
+    return lines.join('\n');
+}

package/lib/runtime/executor/stream-completion.d.ts

@@ -0,0 +1,38 @@
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    name?: string;
+}
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface CompletionResponse {
+    content: string;
+    tool_calls: ToolCall[];
+    finish_reason: string | null;
+}
+export interface StreamCompletionOptions {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    messages: ChatMessage[];
+    tools?: ToolSchema[];
+    maxTokens?: number;
+    timeoutMs?: number;
+}
+export interface ToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export declare function streamCompletion(opts: StreamCompletionOptions): Promise<CompletionResponse>;

package/lib/runtime/executor/stream-completion.js

@@ -0,0 +1,105 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.streamCompletion = streamCompletion;
+const https_1 = __importDefault(require("https"));
+const http_1 = __importDefault(require("http"));
+const url_1 = require("url");
+async function streamCompletion(opts) {
+    const url = new url_1.URL('/chat/completions', opts.baseUrl.replace(/\/$/, '') + '/');
+    const body = JSON.stringify({
+        model: opts.model,
+        messages: opts.messages,
+        max_tokens: opts.maxTokens ?? 4096,
+        stream: true,
+        ...(opts.tools?.length ? { tools: opts.tools, tool_choice: 'auto' } : {}),
+    });
+    const rawText = await fetchWithTimeout(url, opts.apiKey, body, opts.timeoutMs ?? 120000);
+    return parseSseResponse(rawText);
+}
+function fetchWithTimeout(url, apiKey, body, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const isHttps = url.protocol === 'https:';
+        const transport = isHttps ? https_1.default : http_1.default;
+        const chunks = [];
+        const req = transport.request({
+            hostname: url.hostname,
+            port: url.port || (isHttps ? 443 : 80),
+            path: url.pathname + url.search,
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+                'Content-Length': Buffer.byteLength(body),
+            },
+        }, (res) => {
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+            res.on('error', reject);
+        });
+        const timer = setTimeout(() => {
+            req.destroy(new Error(`LLM request timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        req.on('close', () => clearTimeout(timer));
+        req.on('error', (err) => { clearTimeout(timer); reject(err); });
+        req.write(body);
+        req.end();
+    });
+}
+function parseSseResponse(raw) {
+    let content = '';
+    const toolCallsMap = new Map();
+    let finish_reason = null;
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('data:'))
+            continue;
+        const payload = trimmed.slice(5).trim();
+        if (payload === '[DONE]')
+            break;
+        let chunk;
+        try {
+            chunk = JSON.parse(payload);
+        }
+        catch {
+            continue;
+        }
+        const choices = chunk.choices;
+        if (!choices?.length)
+            continue;
+        const delta = choices[0].delta;
+        if (!delta)
+            continue;
+        if (typeof delta.content === 'string')
+            content += delta.content;
+        if (choices[0].finish_reason)
+            finish_reason = choices[0].finish_reason;
+        const deltaToolCalls = delta.tool_calls;
+        if (deltaToolCalls) {
+            for (const dtc of deltaToolCalls) {
+                const idx = dtc.index;
+                if (!toolCallsMap.has(idx)) {
+                    toolCallsMap.set(idx, { id: '', name: '', args: '' });
+                }
+                const entry = toolCallsMap.get(idx);
+                if (dtc.id)
+                    entry.id += dtc.id;
+                const fn = dtc.function;
+                if (fn?.name)
+                    entry.name += fn.name;
+                if (fn?.arguments)
+                    entry.args += fn.arguments;
+            }
+        }
+    }
+    const tool_calls = [...toolCallsMap.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([, tc]) => ({
+        id: tc.id || `call_${Math.random().toString(36).slice(2)}`,
+        type: 'function',
+        function: { name: tc.name, arguments: tc.args },
+    }));
+    return { content, tool_calls, finish_reason };
+}

package/lib/runtime/index.d.ts

@@ -17,3 +17,4 @@ export * from './context/index';
 export * from './scheduler/multi-agent-coordinator';
 export * from './decision/index';
 export * from './audit/index';
+export * from './executor/index';

package/lib/runtime/index.js

@@ -44,3 +44,5 @@ __exportStar(require("./scheduler/multi-agent-coordinator"), exports);
 // R4 Public ABI — Decision, Audit & Enterprise
 __exportStar(require("./decision/index"), exports);
 __exportStar(require("./audit/index"), exports);
+// R5 Public ABI — LLM Task Executor
+__exportStar(require("./executor/index"), exports);

package/lib/runtime/models/failure.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Canonical failure classification used by TaskResult and VerificationManifest.
+ * Both must import from this file — never redefine inline.
+ */
+export type FailureClass = 'env' | 'policy' | 'test' | 'timeout' | 'evidence_missing' | null;

package/lib/runtime/models/failure.js

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

package/lib/runtime/plugins/capability-adapter.d.ts

@@ -6,7 +6,16 @@ interface CapabilityManifest {
     evidenceOutputs: string[];
     checkTypes: string[];
     dir: string;
+    timeoutMs: number;
+    preInvokeHook: string | null;
+    postInvokeHook: string | null;
 }
+export declare function runCapabilityAsync(program: string, args: string[], env: NodeJS.ProcessEnv, cwd: string, timeoutMs: number, onChunk?: (chunk: string, stream: 'stdout' | 'stderr') => void): Promise<{
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+}>;
 export declare function createCapabilityPlugin(projectRoot: string, manifest: CapabilityManifest): OxePlugin;
 export declare function loadCapabilityPlugins(projectRoot: string): OxePlugin[];
 export {};

package/lib/runtime/plugins/capability-adapter.js

@@ -3,12 +3,47 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCapabilityAsync = runCapabilityAsync;
 exports.createCapabilityPlugin = createCapabilityPlugin;
 exports.loadCapabilityPlugins = loadCapabilityPlugins;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const plugin_manifest_1 = require("./plugin-manifest");
+const DEFAULT_CAPABILITY_TIMEOUT_MS = 60000;
+async function runCapabilityAsync(program, args, env, cwd, timeoutMs, onChunk) {
+    return new Promise((resolve) => {
+        const proc = (0, child_process_1.spawn)(program, args, { cwd, env, stdio: 'pipe' });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            proc.kill('SIGTERM');
+        }, timeoutMs);
+        proc.stdout.on('data', (chunk) => {
+            stdoutChunks.push(chunk);
+            onChunk?.(chunk.toString(), 'stdout');
+        });
+        proc.stderr.on('data', (chunk) => {
+            stderrChunks.push(chunk);
+            onChunk?.(chunk.toString(), 'stderr');
+        });
+        proc.on('close', (exitCode) => {
+            clearTimeout(timer);
+            resolve({
+                exitCode,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                stderr: Buffer.concat(stderrChunks).toString('utf8'),
+                timedOut,
+            });
+        });
+        proc.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({ exitCode: null, stdout: '', stderr: String(err), timedOut: false });
+        });
+    });
+}
 function parseFrontmatter(text) {
     const match = String(text || '').match(/^---\r?\n([\s\S]*?)\r?\n---/);
     if (!match)
@@ -55,6 +90,7 @@ function loadCapabilityManifests(projectRoot) {
         const id = String(fm.id || '').trim();
         if (!id)
             return null;
+        const rawTimeout = parseInt(String(fm.timeout_ms || ''), 10);
         return {
             id,
             entrypoint: String(fm.entrypoint || '').trim() || null,
@@ -62,6 +98,9 @@ function loadCapabilityManifests(projectRoot) {
             evidenceOutputs: parseArrayField(fm.evidence_outputs),
             checkTypes: parseArrayField(fm.check_types || fm.supports_checks),
             dir,
+            timeoutMs: isNaN(rawTimeout) ? DEFAULT_CAPABILITY_TIMEOUT_MS : rawTimeout,
+            preInvokeHook: String(fm.pre_invoke_hook || '').trim() || null,
+            postInvokeHook: String(fm.post_invoke_hook || '').trim() || null,
         };
     })
         .filter((item) => Boolean(item));
@@ -141,18 +180,82 @@ function buildToolProvider(projectRoot, manifest) {
                 program = 'powershell';
                 args = ['-File', entrypoint];
             }
-            const result = (0, child_process_1.spawnSync)(program, args, {
-                cwd: projectRoot,
-                encoding: 'utf8',
-                env,
-            });
+            const result = await runCapabilityAsync(program, args, env, projectRoot, manifest.timeoutMs);
+            const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+            if (result.timedOut) {
+                return {
+                    success: false,
+                    output,
+                    evidence_paths: resolveEvidencePaths(projectRoot, manifest),
+                    side_effects_applied: manifest.sideEffects,
+                    error: `Capability ${manifest.id} timed out after ${manifest.timeoutMs}ms`,
+                };
+            }
             return {
-                success: result.status === 0 && !result.error,
-                output: [result.stdout || '', result.stderr || ''].filter(Boolean).join('\n').trim(),
+                success: result.exitCode === 0,
+                output,
                 evidence_paths: resolveEvidencePaths(projectRoot, manifest),
                 side_effects_applied: manifest.sideEffects,
-                error: result.error ? String(result.error) : result.status === 0 ? undefined : (result.stderr || result.stdout || `Capability exited with status ${result.status}`),
+                error: result.exitCode === 0 ? undefined : (result.stderr || result.stdout || `Capability exited with status ${result.exitCode}`),
+            };
+        },
+        async preInvoke(input) {
+            if (!manifest.preInvokeHook)
+                return { allowed: true };
+            const hookPath = path_1.default.isAbsolute(manifest.preInvokeHook)
+                ? manifest.preInvokeHook
+                : path_1.default.join(manifest.dir, manifest.preInvokeHook);
+            const env = {
+                ...process.env,
+                OXE_CAPABILITY_INPUT: JSON.stringify(input.params || {}),
+                OXE_CAPABILITY_RUN_ID: input.run_id,
+                OXE_CAPABILITY_WORK_ITEM_ID: input.work_item_id,
+                OXE_CAPABILITY_ATTEMPT_ID: input.attempt_id,
+                OXE_CAPABILITY_WORKSPACE_ROOT: input.workspace_root,
             };
+            const ext = path_1.default.extname(hookPath).toLowerCase();
+            let program = hookPath;
+            let args = [];
+            if (ext === '.js' || ext === '.cjs' || ext === '.mjs') {
+                program = process.execPath;
+                args = [hookPath];
+            }
+            else if (ext === '.ps1') {
+                program = 'powershell';
+                args = ['-File', hookPath];
+            }
+            const result = await runCapabilityAsync(program, args, env, projectRoot, 10000);
+            return result.exitCode === 0
+                ? { allowed: true }
+                : { allowed: false, reason: result.stderr || result.stdout || `pre_invoke_hook exited with status ${result.exitCode}` };
+        },
+        async postInvoke(input, _result) {
+            if (!manifest.postInvokeHook)
+                return;
+            const hookPath = path_1.default.isAbsolute(manifest.postInvokeHook)
+                ? manifest.postInvokeHook
+                : path_1.default.join(manifest.dir, manifest.postInvokeHook);
+            const env = {
+                ...process.env,
+                OXE_CAPABILITY_INPUT: JSON.stringify(input.params || {}),
+                OXE_CAPABILITY_RUN_ID: input.run_id,
+                OXE_CAPABILITY_WORK_ITEM_ID: input.work_item_id,
+                OXE_CAPABILITY_ATTEMPT_ID: input.attempt_id,
+                OXE_CAPABILITY_WORKSPACE_ROOT: input.workspace_root,
+                OXE_INVOKE_SUCCESS: _result.success ? '1' : '0',
+            };
+            const ext = path_1.default.extname(hookPath).toLowerCase();
+            let program = hookPath;
+            let args = [];
+            if (ext === '.js' || ext === '.cjs' || ext === '.mjs') {
+                program = process.execPath;
+                args = [hookPath];
+            }
+            else if (ext === '.ps1') {
+                program = 'powershell';
+                args = ['-File', hookPath];
+            }
+            await runCapabilityAsync(program, args, env, projectRoot, 10000).catch(() => { });
         },
     };
 }

package/lib/runtime/plugins/plugin-abi.d.ts

@@ -15,12 +15,20 @@ export interface ToolInvocationResult {
     side_effects_applied: string[];
     error?: string;
 }
+export interface PreInvokeResult {
+    allowed: boolean;
+    reason?: string;
+}
 export interface ToolProvider {
     readonly name: string;
     readonly kind: 'read' | 'mutation' | 'verification' | 'analysis' | 'external_operation';
     readonly idempotent: boolean;
     supports(actionType: string): boolean;
     invoke(input: ToolInvocationInput): Promise<ToolInvocationResult>;
+    /** Optional: called before invoke. Return allowed:false to block execution. */
+    preInvoke?(input: ToolInvocationInput): Promise<PreInvokeResult>;
+    /** Optional: called after invoke. Errors are swallowed — does not affect outcome. */
+    postInvoke?(input: ToolInvocationInput, result: ToolInvocationResult): Promise<void>;
 }
 export interface WorkspaceProvider extends WorkspaceManager {
     readonly name: string;

package/lib/runtime/plugins/plugin-registry.d.ts

@@ -6,7 +6,8 @@ export declare class PluginRegistry {
     register(plugin: OxePlugin): void;
     unregister(name: string): void;
     loadFromDirectory(dir: string): string[];
-    toolProviderFor(actionType: string): ToolProvider | null;
+    toolProviderFor(actionType: string, required: true): ToolProvider;
+    toolProviderFor(actionType: string, required?: false): ToolProvider | null;
     workspaceProviderFor(strategy: string): WorkspaceProvider | null;
     verifierProviderFor(checkType: string): VerifierProvider | null;
     contextProviderFor(name: string): ContextProvider | null;

package/lib/runtime/plugins/plugin-registry.js

@@ -54,12 +54,17 @@ class PluginRegistry {
         }
         return loaded;
     }
-    toolProviderFor(actionType) {
+    toolProviderFor(actionType, required = false) {
         for (const plugin of this.plugins) {
             const provider = plugin.toolProviders?.find((p) => p.supports(actionType));
             if (provider)
                 return provider;
         }
+        if (required) {
+            const loaded = this.plugins.map(p => p.name).join(', ') || '(none)';
+            throw new Error(`[plugin-registry] No provider supports action type "${actionType}". ` +
+                `Loaded plugins: [${loaded}]. Load errors: ${this.loadErrors.length}.`);
+        }
         return null;
     }
     workspaceProviderFor(strategy) {

package/lib/runtime/reducers/run-state-reducer.js

@@ -31,6 +31,38 @@ function createEmptyRunState() {
 function reduce(events) {
     return events.reduce(applyEvent, createEmptyRunState());
 }
+const VALID_WORK_ITEM_TRANSITIONS = {
+    pending: ['ready'],
+    ready: ['running', 'completed', 'failed', 'blocked'],
+    running: ['completed', 'failed', 'blocked'],
+    failed: ['ready'], // retry path
+    completed: [], // terminal
+    blocked: [], // terminal
+    skipped: [], // terminal
+};
+const VALID_RUN_TRANSITIONS = {
+    planned: ['running'],
+    running: ['paused', 'failed', 'completed', 'aborted', 'cancelled', 'waiting_approval'],
+    paused: ['running', 'cancelled'],
+    waiting_approval: ['running', 'cancelled'],
+    failed: ['replaying'],
+    replaying: ['running', 'failed', 'completed'],
+    completed: [],
+    aborted: [],
+    cancelled: [],
+};
+function assertWorkItemTransition(itemId, from, to, eventType) {
+    const allowed = VALID_WORK_ITEM_TRANSITIONS[from] ?? [];
+    if (!allowed.includes(to)) {
+        throw new Error(`[state-machine] Invalid work item transition for "${itemId}": ${from} → ${to} (event: ${eventType})`);
+    }
+}
+function assertRunTransition(from, to, eventType) {
+    const allowed = VALID_RUN_TRANSITIONS[from] ?? [];
+    if (!allowed.includes(to)) {
+        throw new Error(`[state-machine] Invalid run transition: ${from} → ${to} (event: ${eventType})`);
+    }
+}
 function applyEvent(state, event) {
     switch (event.type) {
         case 'RunStarted': {
@@ -41,6 +73,7 @@ function applyEvent(state, event) {
             if (!state.run)
                 return state;
             const status = event.payload.status ?? 'completed';
+            assertRunTransition(state.run.status, status, event.type);
             return {
                 ...state,
                 run: { ...state.run, status, ended_at: event.timestamp },
@@ -92,8 +125,10 @@ function applyEvent(state, event) {
                 return state;
             const workItems = new Map(state.workItems);
             const item = workItems.get(event.work_item_id);
-            if (item)
+            if (item) {
+                assertWorkItemTransition(event.work_item_id, item.status, 'completed', event.type);
                 workItems.set(event.work_item_id, { ...item, status: 'completed' });
+            }
             const completedWorkItems = new Set(state.completedWorkItems);
             completedWorkItems.add(event.work_item_id);
             // Collect evidence refs from payload
@@ -111,8 +146,10 @@ function applyEvent(state, event) {
                 return state;
             const workItems = new Map(state.workItems);
             const item = workItems.get(event.work_item_id);
-            if (item)
+            if (item) {
+                assertWorkItemTransition(event.work_item_id, item.status, 'blocked', event.type);
                 workItems.set(event.work_item_id, { ...item, status: 'blocked' });
+            }
             const blockedWorkItems = new Set(state.blockedWorkItems);
             blockedWorkItems.add(event.work_item_id);
             return { ...state, workItems, blockedWorkItems };