oxe-cc 0.9.3 → 1.2.1

package/packages/runtime/src/delivery/promotion-pipeline.ts

@@ -0,0 +1,180 @@
+import path from 'path';
+import fs from 'fs';
+import type { PRManager } from './pr-manager';
+import type { BranchManager } from './branch-manager';
+import type { VerificationManifest, ResidualRiskLedger } from '../verification/verification-manifest';
+import type { RunResult } from '../scheduler/scheduler';
+
+export interface RunPRLink {
+  run_id: string;
+  branch: string;
+  pr_url: string | null;
+  pr_number: number | null;
+  status: 'pending' | 'open' | 'merged' | 'closed' | 'blocked';
+  created_at: string;
+  merged_at: string | null;
+}
+
+export interface PromotionOptions {
+  baseBranch?: string;
+  draftPR?: boolean;
+  autoMerge?: boolean;
+  mergeMethod?: 'merge' | 'squash' | 'rebase';
+}
+
+export type MergeGateVerdict = 'approved' | 'blocked' | 'needs_review';
+
+export interface MergeGateReport {
+  verdict: MergeGateVerdict;
+  reasons: string[];
+  blocking_risks: string[];
+}
+
+export class MergeGateEvaluator {
+  evaluate(
+    runResult: RunResult,
+    manifest: VerificationManifest | null,
+    riskLedger: ResidualRiskLedger | null
+  ): MergeGateReport {
+    const reasons: string[] = [];
+    const blockingRisks: string[] = [];
+
+    if (runResult.failed.length > 0) {
+      reasons.push(`${runResult.failed.length} task(s) failed: ${runResult.failed.join(', ')}`);
+    }
+
+    if (runResult.blocked.length > 0) {
+      reasons.push(`${runResult.blocked.length} task(s) blocked: ${runResult.blocked.join(', ')}`);
+    }
+
+    if (manifest && !manifest.summary.all_passed) {
+      reasons.push(`Verification: ${manifest.summary.fail} check(s) failed, ${manifest.summary.error} error(s)`);
+    }
+
+    if (riskLedger) {
+      const critical = riskLedger.risks.filter((r) => r.severity === 'critical' || r.severity === 'high');
+      for (const risk of critical) {
+        blockingRisks.push(`[${risk.severity.toUpperCase()}] ${risk.description}`);
+      }
+    }
+
+    const hasBlockers = reasons.length > 0 || blockingRisks.length > 0;
+    const verdict: MergeGateVerdict = hasBlockers ? 'blocked' : 'approved';
+
+    return { verdict, reasons, blocking_risks: blockingRisks };
+  }
+}
+
+export class PromotionPipeline {
+  constructor(
+    private readonly projectRoot: string,
+    private readonly branchManager: BranchManager,
+    private readonly prManager: PRManager,
+    private readonly gateEvaluator: MergeGateEvaluator = new MergeGateEvaluator()
+  ) {}
+
+  buildPRBody(
+    runResult: RunResult,
+    manifest: VerificationManifest | null,
+    riskLedger: ResidualRiskLedger | null
+  ): string {
+    const lines: string[] = [];
+    lines.push('## OXE Run Summary');
+    lines.push('');
+    lines.push(`**Run ID:** \`${runResult.run_id}\``);
+    lines.push(`**Status:** ${runResult.status}`);
+    lines.push(`**Completed:** ${runResult.completed.length} tasks`);
+    if (runResult.failed.length > 0) {
+      lines.push(`**Failed:** ${runResult.failed.join(', ')}`);
+    }
+    if (runResult.blocked.length > 0) {
+      lines.push(`**Blocked:** ${runResult.blocked.join(', ')}`);
+    }
+
+    if (manifest) {
+      lines.push('');
+      lines.push('## Verification');
+      lines.push(`- Total: ${manifest.summary.total}`);
+      lines.push(`- Pass: ${manifest.summary.pass}`);
+      lines.push(`- Fail: ${manifest.summary.fail}`);
+      lines.push(`- Skip: ${manifest.summary.skip}`);
+    }
+
+    if (riskLedger && riskLedger.risks.length > 0) {
+      lines.push('');
+      lines.push('## Residual Risks');
+      for (const risk of riskLedger.risks) {
+        lines.push(`- [${risk.severity.toUpperCase()}] ${risk.description}`);
+        if (risk.mitigation) lines.push(`  - Mitigation: ${risk.mitigation}`);
+      }
+    }
+
+    lines.push('');
+    lines.push('---');
+    lines.push('*Generated by OXE Runtime*');
+
+    return lines.join('\n');
+  }
+
+  async promote(
+    runResult: RunResult,
+    manifest: VerificationManifest | null,
+    riskLedger: ResidualRiskLedger | null,
+    opts: PromotionOptions = {}
+  ): Promise<RunPRLink> {
+    const gateReport = this.gateEvaluator.evaluate(runResult, manifest, riskLedger);
+    const link: RunPRLink = {
+      run_id: runResult.run_id,
+      branch: this.branchManager.currentBranch(),
+      pr_url: null,
+      pr_number: null,
+      status: 'pending',
+      created_at: new Date().toISOString(),
+      merged_at: null,
+    };
+
+    if (gateReport.verdict === 'blocked') {
+      link.status = 'blocked';
+      this.savePRLink(runResult.run_id, link);
+      return link;
+    }
+
+    const body = this.buildPRBody(runResult, manifest, riskLedger);
+    const title = `oxe: run ${runResult.run_id} — ${runResult.completed.length} tasks`;
+
+    const prResult = this.prManager.createDraft({
+      title,
+      body,
+      base: opts.baseBranch ?? 'main',
+      draft: opts.draftPR !== false,
+    });
+
+    if (!prResult.success || !prResult.url) {
+      link.status = 'blocked';
+      this.savePRLink(runResult.run_id, link);
+      return link;
+    }
+
+    link.pr_url = prResult.url;
+    link.status = 'open';
+    this.savePRLink(runResult.run_id, link);
+
+    return link;
+  }
+
+  savePRLink(runId: string, link: RunPRLink): void {
+    const p = path.join(this.projectRoot, '.oxe', 'runs', runId, 'pr-link.json');
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(link, null, 2), 'utf8');
+  }
+
+  loadPRLink(runId: string): RunPRLink | null {
+    const p = path.join(this.projectRoot, '.oxe', 'runs', runId, 'pr-link.json');
+    if (!fs.existsSync(p)) return null;
+    try {
+      return JSON.parse(fs.readFileSync(p, 'utf8')) as RunPRLink;
+    } catch {
+      return null;
+    }
+  }
+}

package/packages/runtime/src/events/bus.ts

@@ -0,0 +1,92 @@
+import type { OxeEvent } from './envelope';
+import type { EventType } from './catalog';
+import path from 'path';
+import fs from 'fs';
+
+export type EventInput = Partial<Omit<OxeEvent, 'type'>> & { type: EventType };
+
+interface OperationalEvent {
+  event_id?: string;
+  type?: string;
+  timestamp?: string;
+  session_id?: string | null;
+  run_id?: string | null;
+  task_id?: string | null;
+  work_item_id?: string | null;
+  attempt_id?: string | null;
+  causation_id?: string | null;
+  correlation_id?: string | null;
+  payload?: Record<string, unknown>;
+}
+
+function loadOperationalModule(): {
+  appendEvent: (projectRoot: string, sessionId: string | null, event: Record<string, unknown>) => OperationalEvent;
+  readEvents: (projectRoot: string, sessionId: string | null) => OperationalEvent[];
+} {
+  const candidates = [
+    path.resolve(__dirname, '../../../bin/lib/oxe-operational.cjs'),
+    path.resolve(__dirname, '../../../../bin/lib/oxe-operational.cjs'),
+    path.resolve(__dirname, '../../../../../bin/lib/oxe-operational.cjs'),
+  ];
+  for (const candidate of candidates) {
+    if (!fs.existsSync(candidate)) continue;
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    return require(candidate) as {
+      appendEvent: (projectRoot: string, sessionId: string | null, event: Record<string, unknown>) => OperationalEvent;
+      readEvents: (projectRoot: string, sessionId: string | null) => OperationalEvent[];
+    };
+  }
+  throw new Error(`Unable to locate oxe-operational.cjs from ${__dirname}`);
+}
+
+const operational = loadOperationalModule();
+
+function fromOperationalEvent(raw: OperationalEvent): OxeEvent {
+  return {
+    id: String(raw.event_id || ''),
+    type: String(raw.type || 'RunStarted') as EventType,
+    timestamp: String(raw.timestamp || new Date().toISOString()),
+    session_id: raw.session_id ?? null,
+    run_id: raw.run_id ?? null,
+    work_item_id: raw.work_item_id ?? raw.task_id ?? null,
+    attempt_id: raw.attempt_id ?? null,
+    causation_id: raw.causation_id ?? null,
+    correlation_id: raw.correlation_id ?? null,
+    payload: raw.payload && typeof raw.payload === 'object' ? raw.payload : {},
+  };
+}
+
+export function appendEvent(
+  projectRoot: string,
+  sessionId: string | null,
+  input: EventInput,
+  causationId?: string
+): OxeEvent {
+  const event = operational.appendEvent(projectRoot, sessionId, {
+    event_id: input.id,
+    type: input.type,
+    timestamp: input.timestamp,
+    run_id: input.run_id ?? null,
+    work_item_id: input.work_item_id ?? null,
+    attempt_id: input.attempt_id ?? null,
+    causation_id: input.causation_id ?? causationId ?? null,
+    correlation_id: input.correlation_id ?? null,
+    payload: input.payload && typeof input.payload === 'object' ? input.payload : {},
+  });
+  return fromOperationalEvent(event);
+}
+
+export function readEvents(
+  projectRoot: string,
+  sessionId: string | null
+): OxeEvent[] {
+  return operational.readEvents(projectRoot, sessionId).map(fromOperationalEvent);
+}
+
+export function filterByRun(events: OxeEvent[], runId: string): OxeEvent[] {
+  return events.filter((e) => e.run_id === runId);
+}
+
+export function filterByWorkItem(events: OxeEvent[], workItemId: string): OxeEvent[] {
+  return events.filter((e) => e.work_item_id === workItemId);
+}

package/packages/runtime/src/events/catalog.ts

@@ -0,0 +1,29 @@
+export const EVENT_TYPES = [
+  'SessionCreated',
+  'RunStarted',
+  'GraphCompiled',
+  'WorkItemReady',
+  'WorkspaceAllocated',
+  'AttemptStarted',
+  'ToolInvoked',
+  'ToolCompleted',
+  'ToolFailed',
+  'EvidenceCollected',
+  'PolicyEvaluated',
+  'GateRequested',
+  'GateResolved',
+  'VerificationStarted',
+  'VerificationCompleted',
+  'RetryScheduled',
+  'WorkItemCompleted',
+  'WorkItemBlocked',
+  'RunCompleted',
+  'RetroPublished',
+  'LessonPromoted',
+] as const;
+
+export type EventType = (typeof EVENT_TYPES)[number];
+
+export function isValidEventType(type: string): type is EventType {
+  return (EVENT_TYPES as readonly string[]).includes(type);
+}

package/packages/runtime/src/events/envelope.ts

@@ -0,0 +1,14 @@
+import type { EventType } from './catalog';
+
+export interface OxeEvent {
+  id: string;
+  type: EventType;
+  timestamp: string;
+  session_id: string | null;
+  run_id: string | null;
+  work_item_id: string | null;
+  attempt_id: string | null;
+  causation_id: string | null;
+  correlation_id: string | null;
+  payload: Record<string, unknown>;
+}

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

@@ -0,0 +1,3 @@
+export * from './catalog';
+export * from './envelope';
+export * from './bus';

package/packages/runtime/src/evidence/evidence-store.ts

@@ -0,0 +1,130 @@
+import crypto from 'crypto';
+import path from 'path';
+import fs from 'fs';
+import type { Evidence, EvidenceType } from '../models/evidence';
+
+export interface EvidenceCollectOptions {
+  work_item_id: string;
+  run_id: string;
+  attempt_number: number;
+}
+
+export interface EvidenceContent {
+  evidence: Evidence;
+  content: Buffer;
+}
+
+const EXT_MAP: Record<EvidenceType, string> = {
+  diff: 'patch',
+  stdout: 'txt',
+  stderr: 'txt',
+  junit_xml: 'xml',
+  coverage: 'json',
+  screenshot: 'png',
+  trace: 'json',
+  log: 'txt',
+  security_report: 'json',
+  api_output: 'json',
+  summary: 'json',
+};
+
+export class EvidenceStore {
+  constructor(private readonly projectRoot: string) {}
+
+  private evidenceDir(runId: string, workItemId: string, attemptNumber: number): string {
+    return path.join(
+      this.projectRoot,
+      '.oxe',
+      'evidence',
+      'runs',
+      runId,
+      workItemId,
+      `attempt-${attemptNumber}`
+    );
+  }
+
+  private indexPath(runId: string, workItemId: string, attemptNumber: number): string {
+    return path.join(this.evidenceDir(runId, workItemId, attemptNumber), 'index.json');
+  }
+
+  private readIndex(runId: string, workItemId: string, attemptNumber: number): Evidence[] {
+    const p = this.indexPath(runId, workItemId, attemptNumber);
+    if (!fs.existsSync(p)) return [];
+    try {
+      return JSON.parse(fs.readFileSync(p, 'utf8')) as Evidence[];
+    } catch {
+      return [];
+    }
+  }
+
+  private writeIndex(runId: string, workItemId: string, attemptNumber: number, items: Evidence[]): void {
+    fs.writeFileSync(this.indexPath(runId, workItemId, attemptNumber), JSON.stringify(items, null, 2), 'utf8');
+  }
+
+  async collect(
+    type: EvidenceType,
+    content: Buffer | string,
+    opts: EvidenceCollectOptions
+  ): Promise<Evidence> {
+    const { work_item_id, run_id, attempt_number } = opts;
+    const dir = this.evidenceDir(run_id, work_item_id, attempt_number);
+    fs.mkdirSync(dir, { recursive: true });
+
+    const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+    const checksum = crypto.createHash('sha256').update(buf).digest('hex').slice(0, 16);
+    const ext = EXT_MAP[type] ?? 'bin';
+
+    const existing = this.readIndex(run_id, work_item_id, attempt_number);
+    const seq = existing.filter((e) => e.type === type).length + 1;
+    const filename = seq === 1 ? `${type}.${ext}` : `${type}-${seq}.${ext}`;
+    const filePath = path.join(dir, filename);
+
+    fs.writeFileSync(filePath, buf);
+
+    const evidence: Evidence = {
+      evidence_id: `ev-${run_id}-${work_item_id}-a${attempt_number}-${type}-${seq}`,
+      attempt_id: `${work_item_id}-a${attempt_number}`,
+      type,
+      path: path.relative(this.projectRoot, filePath),
+      checksum,
+      created_at: new Date().toISOString(),
+    };
+
+    this.writeIndex(run_id, work_item_id, attempt_number, [...existing, evidence]);
+    return evidence;
+  }
+
+  async list(opts: EvidenceCollectOptions): Promise<Evidence[]> {
+    return this.readIndex(opts.run_id, opts.work_item_id, opts.attempt_number);
+  }
+
+  async get(evidenceId: string, opts: EvidenceCollectOptions): Promise<EvidenceContent | null> {
+    const items = this.readIndex(opts.run_id, opts.work_item_id, opts.attempt_number);
+    const ev = items.find((e) => e.evidence_id === evidenceId);
+    if (!ev) return null;
+    const absPath = path.join(this.projectRoot, ev.path);
+    if (!fs.existsSync(absPath)) return null;
+    return { evidence: ev, content: fs.readFileSync(absPath) };
+  }
+
+  async listByRun(runId: string): Promise<Evidence[]> {
+    const runDir = path.join(this.projectRoot, '.oxe', 'evidence', 'runs', runId);
+    if (!fs.existsSync(runDir)) return [];
+    const all: Evidence[] = [];
+    for (const workItem of fs.readdirSync(runDir)) {
+      const wiDir = path.join(runDir, workItem);
+      for (const attempt of fs.readdirSync(wiDir)) {
+        const indexPath = path.join(wiDir, attempt, 'index.json');
+        if (fs.existsSync(indexPath)) {
+          try {
+            const items = JSON.parse(fs.readFileSync(indexPath, 'utf8')) as Evidence[];
+            all.push(...items);
+          } catch {
+            // skip corrupt index
+          }
+        }
+      }
+    }
+    return all;
+  }
+}

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

@@ -0,0 +1 @@
+export * from './evidence-store';

package/packages/runtime/src/gate/gate-manager.ts

@@ -0,0 +1,137 @@
+import crypto from 'crypto';
+import path from 'path';
+import fs from 'fs';
+import { appendEvent } from '../events/bus';
+import type { GateScope, GateDecisionValue } from '../models/gate-decision';
+
+export interface GateContext {
+  work_item_id?: string;
+  run_id?: string;
+  description: string;
+  evidence_refs: string[];
+  risks: string[];
+}
+
+export interface GateToken {
+  gate_id: string;
+  scope: GateScope;
+  requested_at: string;
+  context: GateContext;
+  status: 'pending' | 'resolved';
+  decision?: GateDecisionValue;
+  actor?: string;
+  reason?: string;
+  resolved_at?: string;
+}
+
+export interface GateResolution {
+  decision: GateDecisionValue;
+  actor: string;
+  reason?: string;
+}
+
+export class GateManager {
+  constructor(
+    private readonly projectRoot: string,
+    private readonly sessionId: string | null,
+    private readonly runId: string
+  ) {}
+
+  private gatesPath(): string {
+    if (this.sessionId) {
+      return path.join(this.projectRoot, '.oxe', this.sessionId, 'execution', 'GATES.json');
+    }
+    return path.join(this.projectRoot, '.oxe', 'execution', 'GATES.json');
+  }
+
+  private readGates(): GateToken[] {
+    const p = this.gatesPath();
+    if (!fs.existsSync(p)) return [];
+    try {
+      return JSON.parse(fs.readFileSync(p, 'utf8')) as GateToken[];
+    } catch {
+      return [];
+    }
+  }
+
+  private writeGates(gates: GateToken[]): void {
+    const p = this.gatesPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(gates, null, 2), 'utf8');
+  }
+
+  async request(scope: GateScope, ctx: GateContext): Promise<GateToken> {
+    const token: GateToken = {
+      gate_id: `gate-${crypto.randomBytes(4).toString('hex')}`,
+      scope,
+      requested_at: new Date().toISOString(),
+      context: ctx,
+      status: 'pending',
+    };
+
+    const gates = this.readGates();
+    gates.push(token);
+    this.writeGates(gates);
+
+    appendEvent(this.projectRoot, this.sessionId, {
+      type: 'GateRequested',
+      run_id: this.runId,
+      work_item_id: ctx.work_item_id ?? null,
+      payload: {
+        gate_id: token.gate_id,
+        scope,
+        description: ctx.description,
+        evidence_refs: ctx.evidence_refs,
+        risks: ctx.risks,
+      },
+    });
+
+    return token;
+  }
+
+  async resolve(token: GateToken, resolution: GateResolution): Promise<GateToken> {
+    const gates = this.readGates();
+    const idx = gates.findIndex((g) => g.gate_id === token.gate_id);
+    if (idx === -1) throw new Error(`Gate ${token.gate_id} not found`);
+
+    const resolved: GateToken = {
+      ...gates[idx],
+      status: 'resolved',
+      decision: resolution.decision,
+      actor: resolution.actor,
+      reason: resolution.reason ?? undefined,
+      resolved_at: new Date().toISOString(),
+    };
+    gates[idx] = resolved;
+    this.writeGates(gates);
+
+    appendEvent(this.projectRoot, this.sessionId, {
+      type: 'GateResolved',
+      run_id: this.runId,
+      payload: {
+        gate_id: token.gate_id,
+        scope: token.scope,
+        decision: resolution.decision,
+        actor: resolution.actor,
+      },
+    });
+
+    return resolved;
+  }
+
+  isPending(scope: GateScope): boolean {
+    return this.readGates().some((g) => g.scope === scope && g.status === 'pending');
+  }
+
+  listPending(): GateToken[] {
+    return this.readGates().filter((g) => g.status === 'pending');
+  }
+
+  listAll(): GateToken[] {
+    return this.readGates();
+  }
+
+  get(gateId: string): GateToken | null {
+    return this.readGates().find((g) => g.gate_id === gateId) ?? null;
+  }
+}

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

@@ -0,0 +1 @@
+export * from './gate-manager';

package/packages/runtime/src/index.ts

@@ -0,0 +1,37 @@
+// R1 Public ABI — OXE Runtime Foundation
+export * from './models/index';
+export * from './events/index';
+export * from './reducers/index';
+export * from './compiler/index';
+export * from './scheduler/index';
+export * from './workspace/index';
+
+// R2 Public ABI — OXE Evidence & Verification
+export * from './evidence/index';
+// verification exports compile as compileVerification to avoid conflict with compiler/compile
+export {
+  compile as compileVerification,
+  runCheck,
+  runSuite,
+  summarizeSuite,
+} from './verification/verification-compiler';
+export type {
+  CheckType,
+  AcceptanceCheck,
+  AcceptanceCheckSuite,
+  CheckResult,
+} from './verification/verification-compiler';
+export * from './verification/verification-manifest';
+export * from './policy/index';
+export * from './gate/index';
+export * from './projection/index';
+
+// R3 Public ABI — OXE Delivery & Extensibility
+export * from './plugins/index';
+export * from './delivery/index';
+export * from './context/index';
+export * from './scheduler/multi-agent-coordinator';
+
+// R4 Public ABI — Decision, Audit & Enterprise
+export * from './decision/index';
+export * from './audit/index';

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

@@ -0,0 +1,19 @@
+export type AttemptOutcome =
+  | 'success'
+  | 'failure_env'
+  | 'failure_policy'
+  | 'failure_test'
+  | 'failure_timeout'
+  | 'cancelled';
+
+export interface Attempt {
+  attempt_id: string;
+  work_item_id: string;
+  attempt_number: number;
+  workspace_id: string | null;
+  agent_profile: string | null;
+  model: string | null;
+  started_at: string;
+  ended_at: string | null;
+  outcome: AttemptOutcome | null;
+}

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

@@ -0,0 +1,21 @@
+export type EvidenceType =
+  | 'diff'
+  | 'stdout'
+  | 'stderr'
+  | 'junit_xml'
+  | 'coverage'
+  | 'screenshot'
+  | 'trace'
+  | 'log'
+  | 'security_report'
+  | 'api_output'
+  | 'summary';
+
+export interface Evidence {
+  evidence_id: string;
+  attempt_id: string;
+  type: EvidenceType;
+  path: string;
+  checksum: string | null;
+  created_at: string;
+}

package/packages/runtime/src/models/gate-decision.ts

@@ -0,0 +1,21 @@
+export type GateDecisionValue =
+  | 'approved'
+  | 'rejected'
+  | 'approved_with_caveats'
+  | 'needs_more_evidence';
+
+export type GateScope =
+  | 'plan_approval'
+  | 'critical_mutation'
+  | 'security'
+  | 'pr_promotion'
+  | 'merge';
+
+export interface GateDecision {
+  gate_id: string;
+  scope: GateScope;
+  decision: GateDecisionValue;
+  actor: string;
+  reason: string | null;
+  timestamp: string;
+}