oxe-cc 0.9.3 → 1.0.0

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';

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

@@ -0,0 +1,95 @@
+import type { WorkspaceRequest, WorkspaceManager } from '../workspace/workspace-manager';
+import type { WorkspaceLease, SnapshotRef } from '../models/workspace';
+import type { VerificationResult } from '../models/verification-result';
+
+// ─── ToolProvider ────────────────────────────────────────────────────────────
+
+export interface ToolInvocationInput {
+  action_type: string;
+  work_item_id: string;
+  run_id: string;
+  attempt_id: string;
+  params: Record<string, unknown>;
+  workspace_root: string;
+}
+
+export interface ToolInvocationResult {
+  success: boolean;
+  output: string;
+  evidence_paths: string[];
+  side_effects_applied: string[];
+  error?: 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>;
+}
+
+// ─── WorkspaceProvider ───────────────────────────────────────────────────────
+
+export interface WorkspaceProvider extends WorkspaceManager {
+  readonly name: string;
+  supportsStrategy(strategy: string): boolean;
+}
+
+// ─── VerifierProvider ────────────────────────────────────────────────────────
+
+export interface VerificationInput {
+  check_id: string;
+  check_type: string;
+  command: string | null;
+  work_item_id: string;
+  workspace_root: string;
+  evidence_dir: string;
+}
+
+export interface VerifierProvider {
+  readonly name: string;
+  supports(checkType: string): boolean;
+  execute(input: VerificationInput): Promise<VerificationResult>;
+}
+
+// ─── ContextProvider ─────────────────────────────────────────────────────────
+
+export interface ContextRequest {
+  work_item_id: string;
+  run_id: string;
+  decision_type: 'execute' | 'verify' | 'plan' | 'review';
+  artifact_paths: string[];
+  project_root: string;
+}
+
+export interface PluginContextArtifact {
+  source: string;
+  weight: number;
+  reason: string;
+  content?: string;
+}
+
+export interface PluginContextArtifacts {
+  included: PluginContextArtifact[];
+  excluded: Array<{ source: string; reason: string }>;
+  total_weight: number;
+}
+
+export interface ContextProvider {
+  readonly name: string;
+  collect(input: ContextRequest): Promise<PluginContextArtifacts>;
+}
+
+// ─── OxePlugin (unified) ─────────────────────────────────────────────────────
+
+export interface OxePlugin {
+  readonly name: string;
+  readonly version?: string;
+  toolProviders?: ToolProvider[];
+  workspaceProviders?: WorkspaceProvider[];
+  verifierProviders?: VerifierProvider[];
+  contextProviders?: ContextProvider[];
+  /** Legacy lifecycle hooks (compatible with oxe-plugins.cjs) */
+  hooks?: Record<string, (ctx: Record<string, unknown>) => Promise<void> | void>;
+}

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

@@ -0,0 +1,119 @@
+import fs from 'fs';
+import path from 'path';
+import type {
+  OxePlugin,
+  ToolProvider,
+  WorkspaceProvider,
+  VerifierProvider,
+  ContextProvider,
+} from './plugin-abi';
+
+export class PluginRegistry {
+  private plugins: OxePlugin[] = [];
+
+  register(plugin: OxePlugin): void {
+    if (this.plugins.some((p) => p.name === plugin.name)) {
+      throw new Error(`Plugin "${plugin.name}" is already registered`);
+    }
+    this.plugins.push(plugin);
+  }
+
+  unregister(name: string): void {
+    this.plugins = this.plugins.filter((p) => p.name !== name);
+  }
+
+  loadFromDirectory(dir: string): string[] {
+    if (!fs.existsSync(dir)) return [];
+    const loaded: string[] = [];
+    for (const file of fs.readdirSync(dir)) {
+      if (!file.endsWith('.cjs') && !file.endsWith('.js')) continue;
+      const fullPath = path.resolve(dir, file);
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require(fullPath) as OxePlugin | { default?: OxePlugin };
+        const plugin = 'default' in mod && mod.default ? mod.default : (mod as OxePlugin);
+        if (plugin && plugin.name) {
+          this.register(plugin);
+          loaded.push(plugin.name);
+        }
+      } catch {
+        // skip invalid plugin files
+      }
+    }
+    return loaded;
+  }
+
+  toolProviderFor(actionType: string): ToolProvider | null {
+    for (const plugin of this.plugins) {
+      const provider = plugin.toolProviders?.find((p) => p.supports(actionType));
+      if (provider) return provider;
+    }
+    return null;
+  }
+
+  workspaceProviderFor(strategy: string): WorkspaceProvider | null {
+    for (const plugin of this.plugins) {
+      const provider = plugin.workspaceProviders?.find((p) => p.supportsStrategy(strategy));
+      if (provider) return provider;
+    }
+    return null;
+  }
+
+  verifierProviderFor(checkType: string): VerifierProvider | null {
+    for (const plugin of this.plugins) {
+      const provider = plugin.verifierProviders?.find((p) => p.supports(checkType));
+      if (provider) return provider;
+    }
+    return null;
+  }
+
+  contextProviderFor(name: string): ContextProvider | null {
+    for (const plugin of this.plugins) {
+      const provider = plugin.contextProviders?.find((p) => p.name === name);
+      if (provider) return provider;
+    }
+    return null;
+  }
+
+  allContextProviders(): ContextProvider[] {
+    return this.plugins.flatMap((p) => p.contextProviders ?? []);
+  }
+
+  allToolProviders(): ToolProvider[] {
+    return this.plugins.flatMap((p) => p.toolProviders ?? []);
+  }
+
+  async runHook(
+    hookName: string,
+    ctx: Record<string, unknown>
+  ): Promise<void> {
+    for (const plugin of this.plugins) {
+      const hook = plugin.hooks?.[hookName];
+      if (hook) await hook(ctx);
+    }
+  }
+
+  list(): Array<{ name: string; version?: string; providers: string[] }> {
+    return this.plugins.map((p) => ({
+      name: p.name,
+      version: p.version,
+      providers: [
+        ...(p.toolProviders?.map((tp) => `tool:${tp.name}`) ?? []),
+        ...(p.workspaceProviders?.map((wp) => `workspace:${wp.name}`) ?? []),
+        ...(p.verifierProviders?.map((vp) => `verifier:${vp.name}`) ?? []),
+        ...(p.contextProviders?.map((cp) => `context:${cp.name}`) ?? []),
+      ],
+    }));
+  }
+}
+
+let _globalRegistry: PluginRegistry | null = null;
+
+export function globalRegistry(): PluginRegistry {
+  if (!_globalRegistry) _globalRegistry = new PluginRegistry();
+  return _globalRegistry;
+}
+
+export function resetGlobalRegistry(): void {
+  _globalRegistry = null;
+}

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

@@ -0,0 +1 @@
+export * from './policy-engine';

package/packages/runtime/src/policy/policy-engine.ts

@@ -0,0 +1,113 @@
+export type PolicyAction = 'allow' | 'deny' | 'require_human_gate';
+
+export interface PolicyWhenClause {
+  tool?: string;
+  env?: string;
+  kind?: string;
+}
+
+export interface PolicyAssertClause {
+  diff_within_scope?: boolean;
+}
+
+export interface PolicyRule {
+  id: string;
+  when: PolicyWhenClause;
+  assert?: PolicyAssertClause;
+  action: PolicyAction;
+}
+
+export interface PolicyContext {
+  tool: string;
+  env?: string;
+  kind?: string;
+  mutation_scope?: string[];
+  affected_paths?: string[];
+}
+
+export interface PolicyDecision {
+  allowed: boolean;
+  gate_required: boolean;
+  reason: string;
+  rule_id: string | null;
+}
+
+const ALLOW_ALL: PolicyDecision = {
+  allowed: true,
+  gate_required: false,
+  reason: 'no matching policy — default allow',
+  rule_id: null,
+};
+
+export class PolicyEngine {
+  constructor(private readonly rules: PolicyRule[] = []) {}
+
+  evaluate(ctx: PolicyContext): PolicyDecision {
+    for (const rule of this.rules) {
+      if (!this.matches(rule.when, ctx)) continue;
+
+      if (rule.assert) {
+        const assertFailed = this.checkAssert(rule.assert, ctx);
+        if (assertFailed) {
+          return {
+            allowed: false,
+            gate_required: false,
+            reason: `Assert failed for rule ${rule.id}: ${assertFailed}`,
+            rule_id: rule.id,
+          };
+        }
+      }
+
+      switch (rule.action) {
+        case 'allow':
+          return { allowed: true, gate_required: false, reason: `Allowed by rule ${rule.id}`, rule_id: rule.id };
+        case 'deny':
+          return { allowed: false, gate_required: false, reason: `Denied by rule ${rule.id}`, rule_id: rule.id };
+        case 'require_human_gate':
+          return { allowed: true, gate_required: true, reason: `Gate required by rule ${rule.id}`, rule_id: rule.id };
+      }
+    }
+    return ALLOW_ALL;
+  }
+
+  private matches(when: PolicyWhenClause, ctx: PolicyContext): boolean {
+    if (when.tool && when.tool !== ctx.tool) return false;
+    if (when.env && when.env !== ctx.env) return false;
+    if (when.kind && when.kind !== ctx.kind) return false;
+    return true;
+  }
+
+  private checkAssert(assert: PolicyAssertClause, ctx: PolicyContext): string | null {
+    if (assert.diff_within_scope === true) {
+      const scope = ctx.mutation_scope ?? [];
+      const affected = ctx.affected_paths ?? [];
+      if (scope.length === 0) return null; // no scope declared — pass
+      const outsideScope = affected.filter(
+        (p) => !scope.some((s) => p.startsWith(s) || s.startsWith(p))
+      );
+      if (outsideScope.length > 0) {
+        return `paths outside mutation scope: ${outsideScope.join(', ')}`;
+      }
+    }
+    return null;
+  }
+
+  withRule(rule: PolicyRule): PolicyEngine {
+    return new PolicyEngine([...this.rules, rule]);
+  }
+
+  static fromConfig(config: { policies?: PolicyRule[] }): PolicyEngine {
+    return new PolicyEngine(config.policies ?? []);
+  }
+
+  static fromConfigFile(configPath: string): PolicyEngine {
+    try {
+      // Dynamic require to avoid bundling issues
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const cfg = require(configPath) as { policies?: PolicyRule[] };
+      return PolicyEngine.fromConfig(cfg);
+    } catch {
+      return new PolicyEngine();
+    }
+  }
+}

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

@@ -0,0 +1 @@
+export * from './projection-engine';