oxe-cc 0.9.3 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "oxe-cc",
-	"version": "0.9.3",
+	"version": "1.2.1",
 	"description": "OXE — spec-driven workflows in .oxe/; integrates with Cursor, GitHub Copilot, Claude, OpenCode, Gemini, Codex, Windsurf, Antigravity (npx)",
 	"license": "GPL-3.0",
 	"author": "",
@@ -49,14 +49,20 @@
 		".github",
 		"commands",
 		"vscode-extension",
+		"packages/runtime/src",
+		"packages/runtime/package.json",
+		"packages/runtime/tsconfig.json",
 		"AGENTS.md",
 		"README.md",
 		"CHANGELOG.md"
 	],
 	"scripts": {
+		"build:runtime": "cd packages/runtime && npm run build",
 		"sync:runtime-metadata": "node scripts/sync-runtime-metadata.cjs",
 		"sync:cursor": "node scripts/sync-cursor-from-prompts.cjs",
-		"test": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-dashboard.test.cjs tests/oxe-operational.test.cjs tests/oxe-azure.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs tests/oxe-security-permissions.test.cjs tests/oxe-runtime-semantics.test.cjs",
+		"test:root": "node --test tests/install.test.cjs tests/oxe-project-health.test.cjs tests/oxe-dashboard.test.cjs tests/oxe-operational.test.cjs tests/oxe-azure.test.cjs tests/oxe-sdk.test.cjs tests/oxe-manifest.test.cjs tests/oxe-agent-install.test.cjs tests/oxe-install-resolve-full.test.cjs tests/oxe-health-extended.test.cjs tests/oxe-workflows-edge.test.cjs tests/oxe-sdk-edge.test.cjs tests/oxe-cli-edge.test.cjs tests/oxe-npm-version.test.cjs tests/oxe-scripts.test.cjs tests/oxe-retro-health.test.cjs tests/oxe-security-permissions.test.cjs tests/oxe-runtime-semantics.test.cjs",
+		"test:runtime": "cd packages/runtime && npm test",
+		"test": "npm run build:runtime && npm run test:root && npm run test:runtime",
 		"test:coverage": "c8 --check-coverage --lines 82 --functions 85 --branches 58 --statements 82 npm test",
 		"scan:assets": "node scripts/oxe-assets-scan.cjs",
 		"build:vscode-ext": "cd vscode-extension && npx @vscode/vsce package --no-yarn --allow-missing-repository",
@@ -83,4 +89,4 @@
 	"dependencies": {
 		"semver": "^7.7.4"
 	}
-}
+}

package/packages/runtime/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@oxe/runtime",
+  "version": "0.1.0",
+  "private": true,
+  "description": "OXE agentic execution engine — Runtime Foundation (R1)",
+  "main": "../../lib/runtime/index.js",
+  "types": "../../lib/runtime/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc --project tsconfig.test.json && node --test dist-tests/tests/*.test.js",
+    "clean": "node -e \"const fs=require('fs');['../../lib/runtime','dist-tests'].forEach(d=>{try{fs.rmSync(d,{recursive:true})}catch{}});\""
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^5.4.5"
+  }
+}

package/packages/runtime/src/audit/audit-trail.ts

@@ -0,0 +1,243 @@
+import crypto from 'crypto';
+import path from 'path';
+import fs from 'fs';
+
+// ─── RemoteAuditSink ─────────────────────────────────────────────────────────
+
+export interface AuditQueryFilter {
+  action?: AuditAction;
+  severity?: AuditSeverity;
+  runId?: string;
+  since?: string;
+}
+
+export interface RemoteAuditSink {
+  write(entry: AuditEntry): Promise<void>;
+  query(filter: AuditQueryFilter): Promise<AuditEntry[]>;
+}
+
+// ─── AuditMetrics ────────────────────────────────────────────────────────────
+
+export interface AuditMetrics {
+  total_entries: number;
+  critical_count: number;
+  warn_count: number;
+  by_action: Partial<Record<AuditAction, number>>;
+  actors: string[];
+  oldest: string | null;
+  newest: string | null;
+}
+
+export type AuditAction =
+  | 'run_started'
+  | 'run_completed'
+  | 'run_paused'
+  | 'run_recovered'
+  | 'gate_requested'
+  | 'gate_resolved'
+  | 'policy_denied'
+  | 'plugin_registered'
+  | 'plugin_invoked'
+  | 'secret_accessed'
+  | 'infra_mutation'
+  | 'pr_created'
+  | 'merge_approved'
+  | 'merge_blocked';
+
+export type AuditSeverity = 'info' | 'warn' | 'critical';
+
+export interface AuditEntry {
+  audit_id: string;
+  action: AuditAction;
+  severity: AuditSeverity;
+  run_id: string | null;
+  work_item_id: string | null;
+  actor: string;
+  resource: string | null;
+  detail: Record<string, unknown>;
+  timestamp: string;
+}
+
+export interface RunQuota {
+  run_id: string;
+  max_work_items: number;
+  max_mutations: number;
+  max_retries_total: number;
+  consumed_work_items: number;
+  consumed_mutations: number;
+  consumed_retries: number;
+}
+
+export interface QuotaViolation {
+  quota_type: 'work_items' | 'mutations' | 'retries';
+  limit: number;
+  consumed: number;
+}
+
+const ACTION_SEVERITY: Record<AuditAction, AuditSeverity> = {
+  run_started: 'info',
+  run_completed: 'info',
+  run_paused: 'info',
+  run_recovered: 'warn',
+  gate_requested: 'warn',
+  gate_resolved: 'info',
+  policy_denied: 'warn',
+  plugin_registered: 'info',
+  plugin_invoked: 'info',
+  secret_accessed: 'critical',
+  infra_mutation: 'critical',
+  pr_created: 'info',
+  merge_approved: 'warn',
+  merge_blocked: 'warn',
+};
+
+export class AuditTrail {
+  constructor(
+    private readonly projectRoot: string,
+    private readonly remoteSink?: RemoteAuditSink
+  ) {}
+
+  record(
+    action: AuditAction,
+    actor: string,
+    options: {
+      runId?: string;
+      workItemId?: string;
+      resource?: string;
+      detail?: Record<string, unknown>;
+    } = {}
+  ): AuditEntry {
+    const entry: AuditEntry = {
+      audit_id: `aud-${crypto.randomBytes(4).toString('hex')}`,
+      action,
+      severity: ACTION_SEVERITY[action],
+      run_id: options.runId ?? null,
+      work_item_id: options.workItemId ?? null,
+      actor,
+      resource: options.resource ?? null,
+      detail: options.detail ?? {},
+      timestamp: new Date().toISOString(),
+    };
+
+    this.append(entry);
+    return entry;
+  }
+
+  query(filter: {
+    action?: AuditAction;
+    severity?: AuditSeverity;
+    runId?: string;
+    since?: string;
+  } = {}): AuditEntry[] {
+    return this.load().filter((e) => {
+      if (filter.action && e.action !== filter.action) return false;
+      if (filter.severity && e.severity !== filter.severity) return false;
+      if (filter.runId && e.run_id !== filter.runId) return false;
+      if (filter.since && e.timestamp < filter.since) return false;
+      return true;
+    });
+  }
+
+  critical(): AuditEntry[] {
+    return this.query({ severity: 'critical' });
+  }
+
+  metrics(): AuditMetrics {
+    const entries = this.load();
+    const by_action: Partial<Record<AuditAction, number>> = {};
+    const actorSet = new Set<string>();
+    let oldest: string | null = null;
+    let newest: string | null = null;
+    let critical_count = 0;
+    let warn_count = 0;
+
+    for (const e of entries) {
+      by_action[e.action] = (by_action[e.action] ?? 0) + 1;
+      actorSet.add(e.actor);
+      if (e.severity === 'critical') critical_count++;
+      if (e.severity === 'warn') warn_count++;
+      if (!oldest || e.timestamp < oldest) oldest = e.timestamp;
+      if (!newest || e.timestamp > newest) newest = e.timestamp;
+    }
+
+    return {
+      total_entries: entries.length,
+      critical_count,
+      warn_count,
+      by_action,
+      actors: [...actorSet],
+      oldest,
+      newest,
+    };
+  }
+
+  private append(entry: AuditEntry): void {
+    const p = this.trailPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf8');
+    // Fire-and-forget remote sink (failures are non-fatal)
+    if (this.remoteSink) {
+      this.remoteSink.write(entry).catch(() => {});
+    }
+  }
+
+  private load(): AuditEntry[] {
+    const p = this.trailPath();
+    if (!fs.existsSync(p)) return [];
+    try {
+      return fs
+        .readFileSync(p, 'utf8')
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => JSON.parse(line) as AuditEntry);
+    } catch {
+      return [];
+    }
+  }
+
+  private trailPath(): string {
+    return path.join(this.projectRoot, '.oxe', 'AUDIT-TRAIL.ndjson');
+  }
+}
+
+// ─── RunQuota ─────────────────────────────────────────────────────────────────
+
+export function createQuota(
+  runId: string,
+  limits: Partial<Omit<RunQuota, 'run_id' | 'consumed_work_items' | 'consumed_mutations' | 'consumed_retries'>> = {}
+): RunQuota {
+  return {
+    run_id: runId,
+    max_work_items: limits.max_work_items ?? Infinity,
+    max_mutations: limits.max_mutations ?? Infinity,
+    max_retries_total: limits.max_retries_total ?? Infinity,
+    consumed_work_items: 0,
+    consumed_mutations: 0,
+    consumed_retries: 0,
+  };
+}
+
+export function checkQuota(quota: RunQuota): QuotaViolation | null {
+  if (quota.consumed_work_items > quota.max_work_items) {
+    return { quota_type: 'work_items', limit: quota.max_work_items, consumed: quota.consumed_work_items };
+  }
+  if (quota.consumed_mutations > quota.max_mutations) {
+    return { quota_type: 'mutations', limit: quota.max_mutations, consumed: quota.consumed_mutations };
+  }
+  if (quota.consumed_retries > quota.max_retries_total) {
+    return { quota_type: 'retries', limit: quota.max_retries_total, consumed: quota.consumed_retries };
+  }
+  return null;
+}
+
+export function consumeQuota(
+  quota: RunQuota,
+  type: QuotaViolation['quota_type'],
+  amount = 1
+): RunQuota {
+  switch (type) {
+    case 'work_items': return { ...quota, consumed_work_items: quota.consumed_work_items + amount };
+    case 'mutations': return { ...quota, consumed_mutations: quota.consumed_mutations + amount };
+    case 'retries': return { ...quota, consumed_retries: quota.consumed_retries + amount };
+  }
+}

package/packages/runtime/src/audit/index.ts

@@ -0,0 +1,2 @@
+export * from './audit-trail';
+export * from './policy-pack';

package/packages/runtime/src/audit/policy-pack.ts

@@ -0,0 +1,62 @@
+import path from 'path';
+import fs from 'fs';
+import type { PolicyRule, EnvironmentGuardrail } from '../policy/policy-engine';
+import { PolicyEngine } from '../policy/policy-engine';
+
+export interface PolicyPack {
+  pack_id: string;
+  org_id: string;
+  name: string;
+  version: string;
+  policies: PolicyRule[];
+  guardrail: EnvironmentGuardrail;
+  created_at: string;
+}
+
+function packDir(projectRoot: string): string {
+  return path.join(projectRoot, '.oxe', 'policy-packs');
+}
+
+function packFilePath(projectRoot: string, packId: string): string {
+  return path.join(packDir(projectRoot), `${packId}.json`);
+}
+
+export function savePolicyPack(projectRoot: string, pack: PolicyPack): void {
+  const dir = packDir(projectRoot);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(packFilePath(projectRoot, pack.pack_id), JSON.stringify(pack, null, 2), 'utf8');
+}
+
+export function loadPolicyPack(projectRoot: string, packId: string): PolicyPack | null {
+  const p = packFilePath(projectRoot, packId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as PolicyPack;
+  } catch {
+    return null;
+  }
+}
+
+export function listPolicyPacks(projectRoot: string): PolicyPack[] {
+  const dir = packDir(projectRoot);
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      try {
+        return JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')) as PolicyPack;
+      } catch {
+        return null;
+      }
+    })
+    .filter((p): p is PolicyPack => p !== null);
+}
+
+export function applyPolicyPack(engine: PolicyEngine, pack: PolicyPack): PolicyEngine {
+  let result = engine.withGuardrail(pack.guardrail);
+  for (const rule of pack.policies) {
+    result = result.withRule(rule);
+  }
+  return result;
+}

package/packages/runtime/src/compiler/graph-compiler.ts

@@ -0,0 +1,245 @@
+import crypto from 'crypto';
+import type { WorkspaceStrategy } from '../models/workspace';
+
+// Mirror of SDK ParsedTask / ParsedSpec / ParsedPlan interfaces
+// (avoids a hard dependency on the CJS SDK from TypeScript source)
+export interface ParsedTask {
+  id: string;
+  title: string;
+  wave: number | null;
+  dependsOn: string[];
+  files: string[];
+  verifyCommand: string | null;
+  aceite: string[];
+  done: boolean;
+  meta?: Record<string, unknown> | null;
+}
+
+export interface ParsedSpecCriterion {
+  id: string;
+  criterion: string;
+  howToVerify: string;
+}
+
+export interface ParsedSpec {
+  objective: string | null;
+  criteria: ParsedSpecCriterion[];
+}
+
+export interface ParsedPlan {
+  tasks: ParsedTask[];
+  waves: Record<number, string[]>;
+  totalTasks: number;
+}
+
+export interface Action {
+  type: 'read_code' | 'generate_patch' | 'run_tests' | 'run_lint' | 'collect_evidence' | 'custom';
+  command?: string;
+  targets?: string[];
+}
+
+export interface VerifyContract {
+  must_pass: string[];
+  acceptance_refs: string[];
+  command: string | null;
+}
+
+export interface NodePolicy {
+  requires_human_approval: boolean;
+  max_retries: number;
+}
+
+export interface GraphNode {
+  id: string;
+  title: string;
+  wave: number;
+  depends_on: string[];
+  workspace_strategy: WorkspaceStrategy;
+  mutation_scope: string[];
+  actions: Action[];
+  verify: VerifyContract;
+  policy: NodePolicy;
+}
+
+export interface GraphEdge {
+  from: string;
+  to: string;
+  type: 'dependency' | 'wave_sequence';
+}
+
+export interface Wave {
+  wave_number: number;
+  node_ids: string[];
+}
+
+export interface ExecutionGraphMetadata {
+  compiled_at: string;
+  plan_hash: string;
+  spec_hash: string;
+  node_count: number;
+  wave_count: number;
+}
+
+export interface ExecutionGraph {
+  nodes: Map<string, GraphNode>;
+  edges: GraphEdge[];
+  waves: Wave[];
+  metadata: ExecutionGraphMetadata;
+}
+
+export interface CompilerOptions {
+  default_workspace_strategy?: WorkspaceStrategy;
+  default_max_retries?: number;
+  require_approval_for_all?: boolean;
+  skip_done_tasks?: boolean;
+}
+
+export function compile(
+  plan: ParsedPlan,
+  spec: ParsedSpec,
+  options: CompilerOptions = {}
+): ExecutionGraph {
+  const {
+    default_workspace_strategy = 'git_worktree',
+    default_max_retries = 2,
+    require_approval_for_all = false,
+    skip_done_tasks = false,
+  } = options;
+
+  const nodes = new Map<string, GraphNode>();
+  const edges: GraphEdge[] = [];
+  const waveMap = new Map<number, string[]>();
+
+  for (const task of plan.tasks) {
+    if (skip_done_tasks && task.done) continue;
+
+    const waveNumber = task.wave ?? 1;
+    const node: GraphNode = {
+      id: task.id,
+      title: task.title,
+      wave: waveNumber,
+      depends_on: task.dependsOn,
+      workspace_strategy: default_workspace_strategy,
+      mutation_scope: task.files,
+      actions: buildActions(task),
+      verify: {
+        must_pass: task.verifyCommand ? ['tests'] : [],
+        acceptance_refs: task.aceite,
+        command: task.verifyCommand,
+      },
+      policy: {
+        requires_human_approval: require_approval_for_all,
+        max_retries: default_max_retries,
+      },
+    };
+
+    nodes.set(task.id, node);
+
+    for (const dep of task.dependsOn) {
+      edges.push({ from: dep, to: task.id, type: 'dependency' });
+    }
+
+    if (!waveMap.has(waveNumber)) waveMap.set(waveNumber, []);
+    waveMap.get(waveNumber)!.push(task.id);
+  }
+
+  const waves: Wave[] = Array.from(waveMap.entries())
+    .sort(([a], [b]) => a - b)
+    .map(([wave_number, node_ids]) => ({ wave_number, node_ids }));
+
+  return {
+    nodes,
+    edges,
+    waves,
+    metadata: {
+      compiled_at: new Date().toISOString(),
+      plan_hash: hashObject(plan),
+      spec_hash: hashObject(spec),
+      node_count: nodes.size,
+      wave_count: waves.length,
+    },
+  };
+}
+
+export function validateGraph(graph: ExecutionGraph): string[] {
+  const errors: string[] = [];
+  const nodeIds = new Set(graph.nodes.keys());
+
+  for (const [id, node] of graph.nodes) {
+    for (const dep of node.depends_on) {
+      if (!nodeIds.has(dep)) {
+        errors.push(`Node ${id} depends on unknown node ${dep}`);
+      }
+    }
+  }
+
+  // Detect cycles using DFS
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+
+  function hasCycle(nodeId: string): boolean {
+    if (inStack.has(nodeId)) return true;
+    if (visited.has(nodeId)) return false;
+    visited.add(nodeId);
+    inStack.add(nodeId);
+    const node = graph.nodes.get(nodeId);
+    if (node) {
+      for (const dep of node.depends_on) {
+        if (hasCycle(dep)) return true;
+      }
+    }
+    inStack.delete(nodeId);
+    return false;
+  }
+
+  for (const id of nodeIds) {
+    if (hasCycle(id)) {
+      errors.push(`Cycle detected involving node ${id}`);
+      break;
+    }
+  }
+
+  return errors;
+}
+
+export function toSerializable(graph: ExecutionGraph): Record<string, unknown> {
+  return {
+    nodes: Object.fromEntries(graph.nodes),
+    edges: graph.edges,
+    waves: graph.waves,
+    metadata: graph.metadata,
+  };
+}
+
+export function fromSerializable(raw: Record<string, unknown>): ExecutionGraph {
+  const nodes = new Map<string, GraphNode>(
+    Object.entries(raw.nodes as Record<string, GraphNode>)
+  );
+  return {
+    nodes,
+    edges: raw.edges as GraphEdge[],
+    waves: raw.waves as Wave[],
+    metadata: raw.metadata as ExecutionGraphMetadata,
+  };
+}
+
+function buildActions(task: ParsedTask): Action[] {
+  const actions: Action[] = [];
+  if (task.files.length > 0) {
+    actions.push({ type: 'read_code', targets: task.files });
+  }
+  actions.push({ type: 'generate_patch' });
+  if (task.verifyCommand) {
+    actions.push({ type: 'run_tests', command: task.verifyCommand });
+  }
+  actions.push({ type: 'collect_evidence' });
+  return actions;
+}
+
+function hashObject(obj: unknown): string {
+  return crypto
+    .createHash('sha256')
+    .update(JSON.stringify(obj))
+    .digest('hex')
+    .slice(0, 12);
+}

package/packages/runtime/src/compiler/index.ts

@@ -0,0 +1 @@
+export * from './graph-compiler';