oxe-cc 1.5.1 → 1.7.0

package/packages/runtime/src/executor/stream-completion.ts

@@ -0,0 +1,145 @@
+import https from 'https';
+import http from 'http';
+import { URL } from 'url';
+
+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 async function streamCompletion(opts: StreamCompletionOptions): Promise<CompletionResponse> {
+  const url = new 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 ?? 120_000);
+  return parseSseResponse(rawText);
+}
+
+function fetchWithTimeout(url: URL, apiKey: string, body: string, timeoutMs: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const isHttps = url.protocol === 'https:';
+    const transport = isHttps ? https : http;
+    const chunks: Buffer[] = [];
+
+    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: Buffer) => 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: string): CompletionResponse {
+  let content = '';
+  const toolCallsMap = new Map<number, { id: string; name: string; args: string }>();
+  let finish_reason: string | null = 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: Record<string, unknown>;
+    try { chunk = JSON.parse(payload); } catch { continue; }
+
+    const choices = chunk.choices as Array<Record<string, unknown>> | undefined;
+    if (!choices?.length) continue;
+
+    const delta = choices[0].delta as Record<string, unknown> | undefined;
+    if (!delta) continue;
+
+    if (typeof delta.content === 'string') content += delta.content;
+    if (choices[0].finish_reason) finish_reason = choices[0].finish_reason as string;
+
+    const deltaToolCalls = delta.tool_calls as Array<Record<string, unknown>> | undefined;
+    if (deltaToolCalls) {
+      for (const dtc of deltaToolCalls) {
+        const idx = dtc.index as number;
+        if (!toolCallsMap.has(idx)) {
+          toolCallsMap.set(idx, { id: '', name: '', args: '' });
+        }
+        const entry = toolCallsMap.get(idx)!;
+        if (dtc.id) entry.id += dtc.id as string;
+        const fn = dtc.function as Record<string, unknown> | undefined;
+        if (fn?.name) entry.name += fn.name as string;
+        if (fn?.arguments) entry.args += fn.arguments as string;
+      }
+    }
+  }
+
+  const tool_calls: ToolCall[] = [...toolCallsMap.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([, tc]) => ({
+      id: tc.id || `call_${Math.random().toString(36).slice(2)}`,
+      type: 'function' as const,
+      function: { name: tc.name, arguments: tc.args },
+    }));
+
+  return { content, tool_calls, finish_reason };
+}

package/packages/runtime/src/index.ts

@@ -39,3 +39,6 @@ export * from './scheduler/multi-agent-coordinator';
 // R4 Public ABI — Decision, Audit & Enterprise
 export * from './decision/index';
 export * from './audit/index';
+
+// R5 Public ABI — LLM Task Executor
+export * from './executor/index';

package/packages/runtime/src/models/failure.ts

@@ -0,0 +1,11 @@
+/**
+ * Canonical failure classification used by TaskResult and VerificationManifest.
+ * Both must import from this file — never redefine inline.
+ */
+export type FailureClass =
+  | 'env'              // infrastructure / environment problem (network, disk, permissions)
+  | 'policy'           // blocked by policy engine before execution
+  | 'test'             // verification / acceptance test failed
+  | 'timeout'          // task or run exceeded time budget
+  | 'evidence_missing' // required evidence was not collected
+  | null;              // success — no failure

package/packages/runtime/src/plugins/capability-adapter.ts

@@ -1,11 +1,12 @@
 import fs from 'fs';
 import path from 'path';
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import type {
   OxePlugin,
   ToolProvider,
   ToolInvocationInput,
   ToolInvocationResult,
+  PreInvokeResult,
   VerifierProvider,
   VerificationInput,
 } from './plugin-abi';
@@ -19,6 +20,56 @@ interface CapabilityManifest {
   evidenceOutputs: string[];
   checkTypes: string[];
   dir: string;
+  timeoutMs: number;
+  preInvokeHook: string | null;
+  postInvokeHook: string | null;
+}
+
+const DEFAULT_CAPABILITY_TIMEOUT_MS = 60_000;
+
+export async 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 }> {
+  return new Promise((resolve) => {
+    const proc = spawn(program, args, { cwd, env, stdio: 'pipe' });
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let timedOut = false;
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill('SIGTERM');
+    }, timeoutMs);
+
+    proc.stdout.on('data', (chunk: Buffer) => {
+      stdoutChunks.push(chunk);
+      onChunk?.(chunk.toString(), 'stdout');
+    });
+    proc.stderr.on('data', (chunk: Buffer) => {
+      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: string): Record<string, string> {
@@ -62,6 +113,7 @@ function loadCapabilityManifests(projectRoot: string): CapabilityManifest[] {
       const fm = parseFrontmatter(raw);
       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,
@@ -69,6 +121,9 @@ function loadCapabilityManifests(projectRoot: string): CapabilityManifest[] {
         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): item is CapabilityManifest => Boolean(item));
@@ -124,7 +179,7 @@ function buildToolProvider(projectRoot: string, manifest: CapabilityManifest): T
         };
       }
       const ext = path.extname(entrypoint).toLowerCase();
-      const env = {
+      const env: NodeJS.ProcessEnv = {
         ...process.env,
         OXE_CAPABILITY_INPUT: JSON.stringify(input.params || {}),
         OXE_CAPABILITY_RUN_ID: input.run_id,
@@ -141,19 +196,71 @@ function buildToolProvider(projectRoot: string, manifest: CapabilityManifest): T
         program = 'powershell';
         args = ['-File', entrypoint];
       }
-      const result = 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: ToolInvocationInput): Promise<PreInvokeResult> {
+      if (!manifest.preInvokeHook) return { allowed: true };
+      const hookPath = path.isAbsolute(manifest.preInvokeHook)
+        ? manifest.preInvokeHook
+        : path.join(manifest.dir, manifest.preInvokeHook);
+      const env: NodeJS.ProcessEnv = {
+        ...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.extname(hookPath).toLowerCase();
+      let program = hookPath;
+      let args: string[] = [];
+      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, 10_000);
+      return result.exitCode === 0
+        ? { allowed: true }
+        : { allowed: false, reason: result.stderr || result.stdout || `pre_invoke_hook exited with status ${result.exitCode}` };
+    },
+
+    async postInvoke(input: ToolInvocationInput, _result: ToolInvocationResult): Promise<void> {
+      if (!manifest.postInvokeHook) return;
+      const hookPath = path.isAbsolute(manifest.postInvokeHook)
+        ? manifest.postInvokeHook
+        : path.join(manifest.dir, manifest.postInvokeHook);
+      const env: NodeJS.ProcessEnv = {
+        ...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.extname(hookPath).toLowerCase();
+      let program = hookPath;
+      let args: string[] = [];
+      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, 10_000).catch(() => {});
+    },
   };
 }
 

package/packages/runtime/src/plugins/plugin-abi.ts

@@ -21,12 +21,21 @@ export interface ToolInvocationResult {
   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>;
 }
 
 // ─── WorkspaceProvider ───────────────────────────────────────────────────────

package/packages/runtime/src/plugins/plugin-registry.ts

@@ -53,11 +53,20 @@ export class PluginRegistry {
     return loaded;
   }
 
-  toolProviderFor(actionType: string): ToolProvider | null {
+  toolProviderFor(actionType: string, required: true): ToolProvider;
+  toolProviderFor(actionType: string, required?: false): ToolProvider | null;
+  toolProviderFor(actionType: string, required = false): ToolProvider | null {
     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;
   }
 

package/packages/runtime/src/reducers/run-state-reducer.ts

@@ -61,6 +61,56 @@ export function reduce(events: OxeEvent[]): RunState {
 // Exported alias so debug-reducer can import applyEvent without circular issues
 export { applyEvent as applyEventExported };
 
+// ─── State machine: valid transitions ─────────────────────────────────────────
+
+import type { WorkItemStatus } from '../models/work-item';
+import type { RunStatus } from '../models/run';
+
+const VALID_WORK_ITEM_TRANSITIONS: Record<WorkItemStatus, readonly WorkItemStatus[]> = {
+  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: Record<RunStatus, readonly RunStatus[]> = {
+  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: string,
+  from: WorkItemStatus,
+  to: WorkItemStatus,
+  eventType: string
+): void {
+  const allowed = VALID_WORK_ITEM_TRANSITIONS[from] ?? [];
+  if (!(allowed as readonly string[]).includes(to)) {
+    throw new Error(
+      `[state-machine] Invalid work item transition for "${itemId}": ${from} → ${to} (event: ${eventType})`
+    );
+  }
+}
+
+function assertRunTransition(from: RunStatus, to: RunStatus, eventType: string): void {
+  const allowed = VALID_RUN_TRANSITIONS[from] ?? [];
+  if (!(allowed as readonly string[]).includes(to)) {
+    throw new Error(
+      `[state-machine] Invalid run transition: ${from} → ${to} (event: ${eventType})`
+    );
+  }
+}
+
 function applyEvent(state: RunState, event: OxeEvent): RunState {
   switch (event.type) {
     case 'RunStarted': {
@@ -71,6 +121,7 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
     case 'RunCompleted': {
       if (!state.run) return state;
       const status = (event.payload as { status?: Run['status'] }).status ?? 'completed';
+      assertRunTransition(state.run.status, status, event.type);
       return {
         ...state,
         run: { ...state.run, status, ended_at: event.timestamp },
@@ -121,7 +172,10 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
       if (!event.work_item_id) return state;
       const workItems = new Map(state.workItems);
       const item = workItems.get(event.work_item_id);
-      if (item) workItems.set(event.work_item_id, { ...item, status: 'completed' });
+      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
@@ -139,7 +193,10 @@ function applyEvent(state: RunState, event: OxeEvent): RunState {
       if (!event.work_item_id) return state;
       const workItems = new Map(state.workItems);
       const item = workItems.get(event.work_item_id);
-      if (item) workItems.set(event.work_item_id, { ...item, status: 'blocked' });
+      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 };