oxe-cc 0.9.3 → 1.2.1

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/capability-matrix.ts

@@ -0,0 +1,83 @@
+import type { PluginRegistry } from './plugin-registry';
+import { CURRENT_ABI_VERSION } from './plugin-manifest';
+
+export type ApiStability = 'stable' | 'experimental' | 'deprecated';
+
+export interface ProviderCapabilityEntry {
+  name: string;
+  provider_type: 'tool' | 'workspace' | 'verifier' | 'context';
+  stability: ApiStability;
+  since_abi_version: string;
+  deprecated_in?: string;
+  replacement?: string;
+}
+
+export interface CapabilityMatrix {
+  abi_version: string;
+  entries: ProviderCapabilityEntry[];
+}
+
+export function buildMatrix(registry: PluginRegistry): CapabilityMatrix {
+  const entries: ProviderCapabilityEntry[] = [];
+
+  for (const plugin of registry.list()) {
+    const providers = plugin.providers ?? [];
+
+    for (const prov of providers) {
+      let provider_type: ProviderCapabilityEntry['provider_type'];
+      if (prov.startsWith('tool:')) provider_type = 'tool';
+      else if (prov.startsWith('workspace:')) provider_type = 'workspace';
+      else if (prov.startsWith('verifier:')) provider_type = 'verifier';
+      else if (prov.startsWith('context:')) provider_type = 'context';
+      else continue;
+
+      const name = prov.slice(prov.indexOf(':') + 1);
+      entries.push({
+        name,
+        provider_type,
+        stability: 'stable',
+        since_abi_version: CURRENT_ABI_VERSION,
+      });
+    }
+  }
+
+  return { abi_version: CURRENT_ABI_VERSION, entries };
+}
+
+export function getStableEntries(matrix: CapabilityMatrix): ProviderCapabilityEntry[] {
+  return matrix.entries.filter((e) => e.stability === 'stable');
+}
+
+export function getExperimentalEntries(matrix: CapabilityMatrix): ProviderCapabilityEntry[] {
+  return matrix.entries.filter((e) => e.stability === 'experimental');
+}
+
+export function getDeprecatedEntries(matrix: CapabilityMatrix): ProviderCapabilityEntry[] {
+  return matrix.entries.filter((e) => e.stability === 'deprecated');
+}
+
+export function markDeprecated(
+  matrix: CapabilityMatrix,
+  name: string,
+  deprecatedIn: string,
+  replacement?: string
+): CapabilityMatrix {
+  return {
+    ...matrix,
+    entries: matrix.entries.map((e) =>
+      e.name === name
+        ? { ...e, stability: 'deprecated', deprecated_in: deprecatedIn, replacement }
+        : e
+    ),
+  };
+}
+
+export function addEntry(
+  matrix: CapabilityMatrix,
+  entry: ProviderCapabilityEntry
+): CapabilityMatrix {
+  if (matrix.entries.some((e) => e.name === entry.name && e.provider_type === entry.provider_type)) {
+    return matrix;
+  }
+  return { ...matrix, entries: [...matrix.entries, entry] };
+}

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

@@ -0,0 +1,4 @@
+export * from './plugin-abi';
+export * from './plugin-registry';
+export * from './plugin-manifest';
+export * from './capability-matrix';

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-manifest.ts

@@ -0,0 +1,113 @@
+import type { OxePlugin } from './plugin-abi';
+
+export const CURRENT_ABI_VERSION = '1.0.0';
+
+export interface PluginManifest {
+  name: string;
+  version: string;
+  abi_version: string;
+  capabilities: Array<'tool' | 'workspace' | 'verifier' | 'context' | 'hooks'>;
+  tool_action_types?: string[];
+  workspace_strategies?: string[];
+  verifier_check_types?: string[];
+  context_provider_names?: string[];
+  hook_names?: string[];
+}
+
+export interface PluginValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export function extractManifest(plugin: OxePlugin): PluginManifest {
+  const capabilities: PluginManifest['capabilities'] = [];
+  if (plugin.toolProviders?.length) capabilities.push('tool');
+  if (plugin.workspaceProviders?.length) capabilities.push('workspace');
+  if (plugin.verifierProviders?.length) capabilities.push('verifier');
+  if (plugin.contextProviders?.length) capabilities.push('context');
+  if (plugin.hooks && Object.keys(plugin.hooks).length > 0) capabilities.push('hooks');
+
+  return {
+    name: plugin.name,
+    version: plugin.version ?? '0.0.0',
+    abi_version: CURRENT_ABI_VERSION,
+    capabilities,
+    tool_action_types: plugin.toolProviders?.flatMap((p) =>
+      ['read_code', 'generate_patch', 'run_tests', 'collect_evidence', 'custom'].filter((t) => p.supports(t))
+    ) ?? [],
+    workspace_strategies: plugin.workspaceProviders?.map((p) => p.name) ?? [],
+    verifier_check_types: plugin.verifierProviders?.flatMap((p) =>
+      ['unit', 'integration', 'smoke', 'policy', 'security', 'custom'].filter((t) => p.supports(t))
+    ) ?? [],
+    context_provider_names: plugin.contextProviders?.map((p) => p.name) ?? [],
+    hook_names: plugin.hooks ? Object.keys(plugin.hooks) : [],
+  };
+}
+
+export function validatePlugin(plugin: OxePlugin): PluginValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!plugin.name || typeof plugin.name !== 'string') {
+    errors.push('Plugin must have a non-empty string name');
+  }
+
+  if (plugin.version && !/^\d+\.\d+\.\d+/.test(plugin.version)) {
+    warnings.push(`Plugin version "${plugin.version}" does not follow semver`);
+  }
+
+  if (!plugin.toolProviders?.length &&
+      !plugin.workspaceProviders?.length &&
+      !plugin.verifierProviders?.length &&
+      !plugin.contextProviders?.length &&
+      !plugin.hooks) {
+    warnings.push('Plugin declares no providers or hooks — it has no effect');
+  }
+
+  // Validate each tool provider
+  for (const tp of plugin.toolProviders ?? []) {
+    if (!tp.name) errors.push('ToolProvider missing name');
+    if (typeof tp.supports !== 'function') errors.push(`ToolProvider "${tp.name}" missing supports() method`);
+    if (typeof tp.invoke !== 'function') errors.push(`ToolProvider "${tp.name}" missing invoke() method`);
+  }
+
+  // Validate each workspace provider
+  for (const wp of plugin.workspaceProviders ?? []) {
+    if (!wp.name) errors.push('WorkspaceProvider missing name');
+    if (typeof wp.supportsStrategy !== 'function') errors.push(`WorkspaceProvider "${wp.name}" missing supportsStrategy()`);
+    if (typeof wp.allocate !== 'function') errors.push(`WorkspaceProvider "${wp.name}" missing allocate()`);
+  }
+
+  // Validate each verifier provider
+  for (const vp of plugin.verifierProviders ?? []) {
+    if (!vp.name) errors.push('VerifierProvider missing name');
+    if (typeof vp.supports !== 'function') errors.push(`VerifierProvider "${vp.name}" missing supports()`);
+    if (typeof vp.execute !== 'function') errors.push(`VerifierProvider "${vp.name}" missing execute()`);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+export function isAbiCompatible(pluginAbiVersion: string): boolean {
+  // Major version must match; minor/patch are backwards-compatible
+  const [currMajor] = CURRENT_ABI_VERSION.split('.').map(Number);
+  const [plugMajor] = pluginAbiVersion.split('.').map(Number);
+  return currMajor === plugMajor;
+}
+
+export function sandboxInvoke<T>(
+  fn: () => Promise<T>,
+  timeoutMs = 10_000
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Plugin invocation timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    fn().then(
+      (result) => { clearTimeout(timer); resolve(result); },
+      (err) => { clearTimeout(timer); reject(err instanceof Error ? err : new Error(String(err))); }
+    );
+  });
+}

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

@@ -0,0 +1,124 @@
+import fs from 'fs';
+import path from 'path';
+import type {
+  OxePlugin,
+  ToolProvider,
+  WorkspaceProvider,
+  VerifierProvider,
+  ContextProvider,
+} from './plugin-abi';
+import { validatePlugin } from './plugin-manifest';
+
+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`);
+    }
+    const validation = validatePlugin(plugin);
+    if (!validation.valid && validation.errors.length > 0) {
+      throw new Error(`Plugin "${plugin.name}" failed validation: ${validation.errors.join('; ')}`);
+    }
+    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';