oxe-cc 0.9.2 → 1.0.0

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,32 @@
+// 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 './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';

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;
+}

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

@@ -0,0 +1,8 @@
+export * from './session';
+export * from './run';
+export * from './work-item';
+export * from './attempt';
+export * from './workspace';
+export * from './evidence';
+export * from './gate-decision';
+export * from './verification-result';

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

@@ -0,0 +1,24 @@
+export type RunStatus =
+  | 'planned'
+  | 'running'
+  | 'paused'
+  | 'waiting_approval'
+  | 'failed'
+  | 'completed'
+  | 'replaying'
+  | 'aborted'
+  | 'cancelled';
+
+export type RunMode = 'completo' | 'por_onda' | 'por_tarefa';
+export type RunInitiator = 'user' | 'scheduler' | 'retry' | 'replay';
+
+export interface Run {
+  run_id: string;
+  session_id: string | null;
+  graph_version: string;
+  started_at: string;
+  ended_at: string | null;
+  status: RunStatus;
+  initiator: RunInitiator;
+  mode: RunMode;
+}

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

@@ -0,0 +1,11 @@
+export type SessionStatus = 'active' | 'archived' | 'closed';
+
+export interface Session {
+  session_id: string;
+  title: string;
+  created_at: string;
+  status: SessionStatus;
+  repo_root: string;
+  baseline_commit: string | null;
+  active_run_id: string | null;
+}

package/packages/runtime/src/models/verification-result.ts

@@ -0,0 +1,10 @@
+export type VerificationStatus = 'pass' | 'fail' | 'skip' | 'error';
+
+export interface VerificationResult {
+  verification_id: string;
+  work_item_id: string;
+  check_id: string;
+  status: VerificationStatus;
+  evidence_refs: string[];
+  summary: string | null;
+}

package/packages/runtime/src/models/work-item.ts

@@ -0,0 +1,25 @@
+import type { WorkspaceStrategy } from './workspace';
+
+export type WorkItemStatus =
+  | 'pending'
+  | 'ready'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'blocked'
+  | 'skipped';
+
+export type WorkItemType = 'task' | 'checkpoint' | 'gate' | 'verification';
+
+export interface WorkItem {
+  work_item_id: string;
+  run_id: string;
+  title: string;
+  type: WorkItemType;
+  depends_on: string[];
+  mutation_scope: string[];
+  policy_ref: string | null;
+  verify_ref: string[];
+  status: WorkItemStatus;
+  workspace_strategy: WorkspaceStrategy;
+}

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

@@ -0,0 +1,28 @@
+export type WorkspaceStrategy = 'inplace' | 'git_worktree' | 'ephemeral_container';
+export type WorkspaceStatus = 'allocating' | 'ready' | 'dirty' | 'disposed' | 'error';
+
+export interface Workspace {
+  workspace_id: string;
+  strategy: WorkspaceStrategy;
+  base_commit: string | null;
+  branch: string | null;
+  container_ref: string | null;
+  status: WorkspaceStatus;
+  root_path: string;
+}
+
+export interface WorkspaceLease {
+  workspace_id: string;
+  strategy: WorkspaceStrategy;
+  branch: string | null;
+  base_commit: string | null;
+  root_path: string;
+  ttl_minutes: number;
+}
+
+export interface SnapshotRef {
+  snapshot_id: string;
+  workspace_id: string;
+  commit: string;
+  created_at: string;
+}

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

@@ -0,0 +1,2 @@
+export * from './plugin-abi';
+export * from './plugin-registry';