oxe-cc 1.0.0 → 1.2.1

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/context/context-pack-builder.ts

@@ -1,6 +1,8 @@
 import type { WorkItem } from '../models/work-item';
 import type { Evidence } from '../models/evidence';
 import type { RunState } from '../reducers/run-state-reducer';
+import type { ContextProfile } from './context-profiles';
+import type { AutonomyTier } from '../policy/policy-engine';
 
 export interface ContextArtifact {
   id: string;
@@ -32,6 +34,50 @@ export interface ContextPack {
   built_at: string;
 }
 
+// ─── Quality scoring ─────────────────────────────────────────────────────────
+
+export interface ContextQualityScore {
+  completeness: number;
+  relevance_mean: number;
+  redundancy: number;
+  recency_score: number;
+  overall: number;
+}
+
+export function scorePackQuality(pack: ContextPack, profile: ContextProfile): ContextQualityScore {
+  const expectedKinds = Object.keys(profile.artifact_kind_weights) as ContextArtifact['kind'][];
+  const presentKinds = new Set(pack.artifacts.map((a) => a.kind));
+  const completeness = expectedKinds.length > 0
+    ? expectedKinds.filter((k) => presentKinds.has(k)).length / expectedKinds.length
+    : 0;
+
+  const relevance_mean = pack.artifacts.length > 0
+    ? pack.artifacts.reduce((sum, a) => sum + a.relevanceScore, 0) / pack.artifacts.length
+    : 0;
+
+  const total = pack.total_artifacts_considered;
+  const redundancy = total > 0 ? 1 - (pack.artifacts.length / total) : 0;
+
+  const ageMs = Date.now() - new Date(pack.built_at).getTime();
+  const maxAgeMs = 24 * 60 * 60 * 1000;
+  const recency_score = Math.max(0, 1 - ageMs / maxAgeMs);
+
+  const overall = Math.min(1,
+    0.3 * completeness +
+    0.35 * relevance_mean +
+    0.1 * (1 - redundancy) +
+    0.25 * recency_score
+  );
+
+  return {
+    completeness: Math.round(completeness * 100) / 100,
+    relevance_mean: Math.round(relevance_mean * 100) / 100,
+    redundancy: Math.round(redundancy * 100) / 100,
+    recency_score: Math.round(recency_score * 100) / 100,
+    overall: Math.round(overall * 100) / 100,
+  };
+}
+
 // ─── Relevance scoring ────────────────────────────────────────────────────────
 
 function scoreEvidenceRelevance(evidence: Evidence, workItem: WorkItem): number {
@@ -190,4 +236,24 @@ export class ContextPackBuilder {
   buildLightweight(workItem: WorkItem, state: RunState, lessons: LessonMetric[]): ContextPack {
     return this.build(workItem, state, [], new Map(), lessons);
   }
+
+  /**
+   * Filter artifacts to those whose path-like tags are within mutation_scope.
+   * L0/L1 tiers apply the filter; L2/L3 skip it (full access).
+   */
+  filterByMutationScope(
+    artifacts: ContextArtifact[],
+    mutationScope: string[],
+    autonomyTier: AutonomyTier
+  ): ContextArtifact[] {
+    if (autonomyTier === 'L2' || autonomyTier === 'L3') return artifacts;
+    const scope = mutationScope.map((s) => s.toLowerCase());
+    return artifacts.filter((a) => {
+      const pathTags = a.tags.filter((t) => t.includes('/') || t.includes('\\'));
+      if (pathTags.length === 0) return true;
+      return pathTags.some((tag) =>
+        scope.some((s) => tag.toLowerCase().includes(s) || s.includes(tag.toLowerCase()))
+      );
+    });
+  }
 }

package/packages/runtime/src/context/context-pack-store.ts

@@ -0,0 +1,197 @@
+import path from 'path';
+import fs from 'fs';
+import type { ContextPack, ContextArtifact, ContextQualityScore } from './context-pack-builder';
+
+export interface ContextPackMeta {
+  pack_id: string;
+  work_item_id: string;
+  run_id: string;
+  built_at: string;
+  artifact_count: number;
+  estimated_tokens: number;
+  stale: boolean;
+  stale_reason: string | null;
+}
+
+export interface ContextPackDiff {
+  added: string[];
+  removed: string[];
+  score_changed: Array<{ id: string; before: number; after: number }>;
+}
+
+function packPath(projectRoot: string, runId: string, workItemId: string): string {
+  return path.join(projectRoot, '.oxe', 'runs', runId, `context-pack-${workItemId}.json`);
+}
+
+function metaIndexPath(projectRoot: string, runId: string): string {
+  return path.join(projectRoot, '.oxe', 'runs', runId, 'context-packs.index.json');
+}
+
+function estimateTokens(pack: ContextPack): number {
+  return Math.ceil(pack.artifacts.reduce((sum, a) => sum + a.content.length, 0) / 4);
+}
+
+export function savePack(
+  projectRoot: string,
+  runId: string,
+  pack: ContextPack
+): ContextPackMeta {
+  const p = packPath(projectRoot, runId, pack.work_item_id);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(pack, null, 2), 'utf8');
+
+  const meta: ContextPackMeta = {
+    pack_id: `cp-${runId}-${pack.work_item_id}`,
+    work_item_id: pack.work_item_id,
+    run_id: runId,
+    built_at: pack.built_at,
+    artifact_count: pack.artifacts.length,
+    estimated_tokens: estimateTokens(pack),
+    stale: false,
+    stale_reason: null,
+  };
+
+  updateMetaIndex(projectRoot, runId, meta);
+  return meta;
+}
+
+export function loadPack(
+  projectRoot: string,
+  runId: string,
+  workItemId: string
+): ContextPack | null {
+  const p = packPath(projectRoot, runId, workItemId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as ContextPack;
+  } catch {
+    return null;
+  }
+}
+
+export function markStale(
+  projectRoot: string,
+  runId: string,
+  workItemId: string,
+  reason: string
+): void {
+  const index = loadMetaIndex(projectRoot, runId);
+  const meta = index.find((m) => m.work_item_id === workItemId);
+  if (!meta) return;
+  meta.stale = true;
+  meta.stale_reason = reason;
+  saveMetaIndex(projectRoot, runId, index);
+}
+
+export function isStale(
+  projectRoot: string,
+  runId: string,
+  workItemId: string
+): boolean {
+  const index = loadMetaIndex(projectRoot, runId);
+  return index.find((m) => m.work_item_id === workItemId)?.stale ?? false;
+}
+
+export function diffPacks(before: ContextPack, after: ContextPack): ContextPackDiff {
+  const beforeIds = new Set(before.artifacts.map((a) => a.id));
+  const afterIds = new Set(after.artifacts.map((a) => a.id));
+  const beforeMap = new Map(before.artifacts.map((a) => [a.id, a]));
+  const afterMap = new Map(after.artifacts.map((a) => [a.id, a]));
+
+  const added = [...afterIds].filter((id) => !beforeIds.has(id));
+  const removed = [...beforeIds].filter((id) => !afterIds.has(id));
+
+  const score_changed: ContextPackDiff['score_changed'] = [];
+  for (const id of afterIds) {
+    if (!beforeIds.has(id)) continue;
+    const bScore = beforeMap.get(id)!.relevanceScore;
+    const aScore = afterMap.get(id)!.relevanceScore;
+    if (Math.abs(bScore - aScore) > 0.05) {
+      score_changed.push({ id, before: bScore, after: aScore });
+    }
+  }
+
+  return { added, removed, score_changed };
+}
+
+export function listPackMeta(projectRoot: string, runId: string): ContextPackMeta[] {
+  return loadMetaIndex(projectRoot, runId);
+}
+
+// ─── ContextPackRef — link pack to a specific execution attempt ───────────────
+
+export interface ContextPackRef {
+  ref_id: string;
+  pack_id: string;
+  attempt_id: string;
+  work_item_id: string;
+  run_id: string;
+  artifacts_used: string[];
+  quality: ContextQualityScore;
+  linked_at: string;
+}
+
+function packRefPath(projectRoot: string, runId: string, attemptId: string): string {
+  return path.join(projectRoot, '.oxe', 'runs', runId, `context-ref-${attemptId}.json`);
+}
+
+export function linkPackToAttempt(
+  projectRoot: string,
+  runId: string,
+  attemptId: string,
+  pack: ContextPack,
+  quality: ContextQualityScore
+): ContextPackRef {
+  const ref: ContextPackRef = {
+    ref_id: `ref-${runId}-${attemptId}`,
+    pack_id: `cp-${runId}-${pack.work_item_id}`,
+    attempt_id: attemptId,
+    work_item_id: pack.work_item_id,
+    run_id: runId,
+    artifacts_used: pack.artifacts.map((a) => a.id),
+    quality,
+    linked_at: new Date().toISOString(),
+  };
+  const p = packRefPath(projectRoot, runId, attemptId);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(ref, null, 2), 'utf8');
+  return ref;
+}
+
+export function getPackRefForAttempt(
+  projectRoot: string,
+  runId: string,
+  attemptId: string
+): ContextPackRef | null {
+  const p = packRefPath(projectRoot, runId, attemptId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as ContextPackRef;
+  } catch {
+    return null;
+  }
+}
+
+function loadMetaIndex(projectRoot: string, runId: string): ContextPackMeta[] {
+  const p = metaIndexPath(projectRoot, runId);
+  if (!fs.existsSync(p)) return [];
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as ContextPackMeta[];
+  } catch {
+    return [];
+  }
+}
+
+function saveMetaIndex(projectRoot: string, runId: string, index: ContextPackMeta[]): void {
+  const p = metaIndexPath(projectRoot, runId);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(index, null, 2), 'utf8');
+}
+
+function updateMetaIndex(projectRoot: string, runId: string, meta: ContextPackMeta): void {
+  const index = loadMetaIndex(projectRoot, runId);
+  const idx = index.findIndex((m) => m.work_item_id === meta.work_item_id);
+  if (idx >= 0) index[idx] = meta;
+  else index.push(meta);
+  saveMetaIndex(projectRoot, runId, index);
+}

package/packages/runtime/src/context/context-profiles.ts

@@ -0,0 +1,60 @@
+import type { ContextArtifact } from './context-pack-builder';
+
+export type ContextDecisionType = 'execute' | 'verify' | 'plan' | 'review' | 'debug' | 'migration';
+
+export interface ContextProfile {
+  decision_type: ContextDecisionType;
+  artifact_kind_weights: Record<ContextArtifact['kind'], number>;
+  quality_threshold: number;
+  max_artifacts: number;
+  max_tokens: number;
+}
+
+export const DEFAULT_PROFILES: Record<ContextDecisionType, ContextProfile> = {
+  execute: {
+    decision_type: 'execute',
+    artifact_kind_weights: { evidence: 0.8, lesson: 0.3, file: 0.6, summary: 0.4 },
+    quality_threshold: 0.6,
+    max_artifacts: 20,
+    max_tokens: 8000,
+  },
+  verify: {
+    decision_type: 'verify',
+    artifact_kind_weights: { evidence: 0.9, lesson: 0.2, file: 0.5, summary: 0.5 },
+    quality_threshold: 0.7,
+    max_artifacts: 15,
+    max_tokens: 6000,
+  },
+  plan: {
+    decision_type: 'plan',
+    artifact_kind_weights: { evidence: 0.4, lesson: 0.9, file: 0.7, summary: 0.6 },
+    quality_threshold: 0.5,
+    max_artifacts: 25,
+    max_tokens: 10000,
+  },
+  review: {
+    decision_type: 'review',
+    artifact_kind_weights: { evidence: 0.6, lesson: 0.5, file: 0.8, summary: 0.5 },
+    quality_threshold: 0.55,
+    max_artifacts: 20,
+    max_tokens: 8000,
+  },
+  debug: {
+    decision_type: 'debug',
+    artifact_kind_weights: { evidence: 0.9, lesson: 0.6, file: 0.7, summary: 0.4 },
+    quality_threshold: 0.6,
+    max_artifacts: 20,
+    max_tokens: 8000,
+  },
+  migration: {
+    decision_type: 'migration',
+    artifact_kind_weights: { evidence: 0.7, lesson: 0.7, file: 0.9, summary: 0.5 },
+    quality_threshold: 0.65,
+    max_artifacts: 30,
+    max_tokens: 12000,
+  },
+};
+
+export function getProfile(decisionType: ContextDecisionType): ContextProfile {
+  return DEFAULT_PROFILES[decisionType];
+}

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

@@ -1 +1,3 @@
 export * from './context-pack-builder';
+export * from './context-pack-store';
+export * from './context-profiles';