open-multi-agent-kit 0.79.1 → 0.79.3

package/dist/replay/replay-engine.js

@@ -0,0 +1,265 @@
+/**
+ * ReplayEngine — restores and replays a run's full execution timeline.
+ *
+ * Reads context capsules, evidence results, and decision traces to reconstruct
+ * the exact sequence of events: provider selection, context delivery,
+ * evidence gates, and repair decisions.
+ */
+import { readFile } from "fs/promises";
+import { join } from "path";
+import { createManifestBuilder } from "./manifest-builder.js";
+import { getRunPath } from "../util/run-store.js";
+import { style, status, label } from "../util/theme.js";
+export async function replayRun(runId, options = {}) {
+    const builder = createManifestBuilder({ runsDir: options.runsDir });
+    const validation = await builder.validate(runId);
+    if (!validation.valid) {
+        console.error(status.error(`Run ${runId} is not replayable:`));
+        for (const err of validation.errors)
+            console.error(`  ${style.red("✕")} ${err}`);
+        process.exit(1);
+    }
+    const manifest = await builder.build(runId);
+    // Filter nodes if requested
+    let nodes = manifest.nodes;
+    if (options.nodeId) {
+        nodes = nodes.filter((n) => n.nodeId === options.nodeId);
+        if (nodes.length === 0) {
+            console.error(status.error(`Node ${options.nodeId} not found in run ${runId}`));
+            process.exit(1);
+        }
+    }
+    // Filter attempts if requested
+    if (options.attemptId) {
+        const targetAttempt = manifest.nodes
+            .flatMap((n) => n.attempts)
+            .find((a) => a.attemptId === options.attemptId);
+        if (!targetAttempt) {
+            console.error(status.error(`Attempt ${options.attemptId} not found in run ${runId}`));
+            process.exit(1);
+        }
+        const parentNode = manifest.nodes.find((n) => n.attempts.some((a) => a.attemptId === options.attemptId));
+        if (parentNode) {
+            nodes = [{
+                    ...parentNode,
+                    attempts: parentNode.attempts.filter((a) => a.attemptId === options.attemptId),
+                }];
+        }
+    }
+    // Build timeline
+    const timeline = await buildTimeline(runId, nodes, options);
+    if (options.json) {
+        console.log(JSON.stringify({ runId, manifest, timeline }, null, 2));
+        return;
+    }
+    renderReplay(runId, manifest, nodes, timeline, options);
+}
+async function buildTimeline(runId, nodes, options) {
+    const events = [];
+    // Load evidence and decisions
+    const evidenceEntries = await loadEvidenceEntries(runId, options.runsDir);
+    const allDecisions = await loadDecisions(runId, options.runsDir);
+    events.push({ at: "", kind: "start", payload: { runId } });
+    for (const node of nodes) {
+        for (const attempt of node.attempts) {
+            events.push({
+                at: attempt.startedAt,
+                kind: "attempt",
+                nodeId: node.nodeId,
+                attemptId: attempt.attemptId,
+                payload: { runtime: attempt.runtime, model: attempt.model, provider: attempt.provider },
+            });
+            // Context capsule event
+            if (options.context) {
+                const capsule = await loadContextCapsule(runId, node.nodeId, attempt.attemptId, options.runsDir);
+                if (capsule) {
+                    events.push({
+                        at: attempt.startedAt,
+                        kind: "context",
+                        nodeId: node.nodeId,
+                        attemptId: attempt.attemptId,
+                        payload: capsule,
+                    });
+                }
+            }
+            // Decisions for this attempt
+            const attemptDecisions = allDecisions.filter((d) => d.attemptId === attempt.attemptId || (d.nodeId === node.nodeId && !d.attemptId));
+            for (const d of attemptDecisions) {
+                const isRepair = d.component === "repair-policy";
+                if (options.decisions || (options.repair && isRepair)) {
+                    events.push({
+                        at: d.at,
+                        kind: isRepair ? "repair" : "decision",
+                        nodeId: node.nodeId,
+                        attemptId: attempt.attemptId,
+                        payload: d,
+                    });
+                }
+            }
+            // Evidence for this attempt
+            if (options.evidence) {
+                const attemptEvidence = evidenceEntries.filter((e) => e.attemptId === attempt.attemptId && e.nodeId === node.nodeId);
+                for (const ev of attemptEvidence) {
+                    events.push({
+                        at: ev.timestamp ?? attempt.endedAt ?? attempt.startedAt,
+                        kind: "evidence",
+                        nodeId: node.nodeId,
+                        attemptId: attempt.attemptId,
+                        payload: ev,
+                    });
+                }
+            }
+            events.push({
+                at: attempt.endedAt ?? attempt.startedAt,
+                kind: "end",
+                nodeId: node.nodeId,
+                attemptId: attempt.attemptId,
+                payload: { status: attempt.status, error: attempt.error, latencyMs: attempt.latencyMs },
+            });
+        }
+    }
+    // Sort by time, stable for same timestamps
+    events.sort((a, b) => {
+        const ta = a.at || "";
+        const tb = b.at || "";
+        if (ta !== tb)
+            return ta.localeCompare(tb);
+        const order = ["start", "attempt", "context", "decision", "repair", "evidence", "end"];
+        return order.indexOf(a.kind) - order.indexOf(b.kind);
+    });
+    return events;
+}
+function renderReplay(runId, manifest, nodes, timeline, _options) {
+    console.log(style.purpleBold(`▶ Replay — ${runId}`));
+    console.log(label("OMK Version", manifest.omkVersion));
+    console.log(label("Started", manifest.startedAt));
+    if (manifest.completedAt)
+        console.log(label("Completed", manifest.completedAt));
+    console.log(label("DAG Hash", manifest.dagHash));
+    console.log("");
+    const nodeMap = new Map(nodes.map((n) => [n.nodeId, n]));
+    for (const event of timeline) {
+        switch (event.kind) {
+            case "start": {
+                console.log(style.gray("┌─ Run started"));
+                break;
+            }
+            case "attempt": {
+                const p = event.payload;
+                const providerInfo = p.provider ? ` via ${style.cream(p.provider)}` : "";
+                const modelInfo = p.model ? ` (${p.model})` : "";
+                console.log(`\n  ${style.purpleBold("▸")} ${style.creamBold(event.nodeId ?? "")} ${style.gray(event.attemptId ?? "")}`);
+                console.log(`    ${style.gray("Runtime:")} ${p.runtime}${modelInfo}${providerInfo}`);
+                break;
+            }
+            case "context": {
+                const capsule = event.payload;
+                const tokens = capsule._snapshot?.estimatedTokens ?? 0;
+                const fileCount = capsule.relevantFiles?.length ?? 0;
+                const memCount = capsule.graphMemory?.length ?? 0;
+                console.log(`    ${style.gray("Context:")} ${tokens} tokens, ${fileCount} files, ${memCount} memory facts`);
+                if (capsule.budget) {
+                    console.log(`      ${style.gray("Budget:")} ${capsule.budget.maxInputTokens} max-input, ${capsule.budget.compression} compression`);
+                }
+                if (capsule.goal) {
+                    const goalPreview = capsule.goal.slice(0, 80).replace(/\n/g, " ");
+                    console.log(`      ${style.gray("Goal:")} ${goalPreview}${capsule.goal.length > 80 ? "…" : ""}`);
+                }
+                break;
+            }
+            case "decision": {
+                const d = event.payload;
+                const scores = d.scores ? ` ${style.gray(JSON.stringify(d.scores))}` : "";
+                console.log(`    ${style.gray("Decision:")} [${style.purple(d.component)}] ${d.outputDecision}${scores}`);
+                console.log(`      ${style.gray(d.reason)}`);
+                break;
+            }
+            case "repair": {
+                const d = event.payload;
+                console.log(`    ${style.orange("Repair:")} [${style.purple(d.component)}] ${d.outputDecision}`);
+                console.log(`      ${style.gray(d.reason)}`);
+                break;
+            }
+            case "evidence": {
+                const ev = event.payload;
+                const icon = ev.passed ? style.mint("✓") : style.red("✕");
+                console.log(`    ${icon} ${style.gray("Evidence:")} ${ev.gate}`);
+                if (ev.message)
+                    console.log(`      ${style.gray(ev.message)}`);
+                if (ev.ref)
+                    console.log(`      ${style.gray("Ref: " + ev.ref)}`);
+                break;
+            }
+            case "end": {
+                const p = event.payload;
+                const icon = p.status === "success" ? style.mint("✓") : style.red("✕");
+                const latency = p.latencyMs ? ` ${formatMs(p.latencyMs)}` : "";
+                console.log(`    ${icon} ${style.gray("Result:")} ${p.status}${latency}`);
+                if (p.error)
+                    console.log(`      ${style.red(p.error)}`);
+                const node = nodeMap.get(event.nodeId ?? "");
+                if (node && node.attempts[node.attempts.length - 1]?.attemptId === event.attemptId) {
+                    console.log(`  ${style.gray("└─ Node " + event.nodeId + " complete")}`);
+                }
+                break;
+            }
+        }
+    }
+    // Summary
+    console.log("");
+    console.log(style.purpleBold("Replay Summary"));
+    console.log(`  Nodes:    ${nodes.length}`);
+    console.log(`  Attempts: ${nodes.reduce((s, n) => s + n.attempts.length, 0)}`);
+    console.log(`  Success:  ${style.mint(String(nodes.filter((n) => n.finalStatus === "success").length))}`);
+    console.log(`  Failed:   ${style.red(String(nodes.filter((n) => n.finalStatus === "failed").length))}`);
+}
+async function loadEvidenceEntries(runId, runsDir) {
+    const dir = getRunPath(runId, undefined, runsDir);
+    const path = join(dir, "evidence.jsonl");
+    try {
+        const content = await readFile(path, "utf-8");
+        return content
+            .trim()
+            .split("\n")
+            .filter((l) => l.length > 0)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+async function loadDecisions(runId, runsDir) {
+    const dir = getRunPath(runId, undefined, runsDir);
+    const path = join(dir, "decisions.jsonl");
+    try {
+        const content = await readFile(path, "utf-8");
+        return content
+            .trim()
+            .split("\n")
+            .filter((l) => l.length > 0)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+async function loadContextCapsule(runId, nodeId, attemptId, runsDir) {
+    const dir = getRunPath(runId, undefined, runsDir);
+    const path = join(dir, "context-capsules", `${nodeId}-${attemptId}.json`);
+    try {
+        const content = await readFile(path, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+function formatMs(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const m = Math.floor(ms / 60_000);
+    const s = Math.floor((ms % 60_000) / 1000);
+    return `${m}m${s}s`;
+}

package/dist/runtime/adapter.d.ts

@@ -0,0 +1,77 @@
+/**
+ * RuntimeAdapter — provider-routing interface.
+ *
+ * Used by the provider routing layer (src/providers/) to select candidate
+ * runtimes, check health, and dispatch AgentRunRequests.
+ *
+ * It is stricter than AgentRuntime: runNode operates on AgentRunRequest,
+ * and health()/supports()/runNode() are all mandatory.
+ *
+ * For the internal runtime implementation interface, see
+ * src/runtime/agent-runtime.ts (AgentRuntime).
+ */
+import type { RuntimeId, RuntimeKind, RuntimeAuthority, RuntimeCapabilities, RuntimeHealth } from "./contracts/shared.js";
+export type { RuntimeId, RuntimeKind, RuntimeAuthority, RuntimeCapabilities, RuntimeHealth };
+export interface AgentRunRequest {
+    runId: string;
+    nodeId: string;
+    role: string;
+    taskType: string;
+    goalDigest: string;
+    contextCapsule: unknown;
+    worktree: {
+        root: string;
+        isolated: boolean;
+        branch?: string;
+    };
+    authority: {
+        mode: "authority" | "executor" | "proposal" | "advisory" | "veto";
+        allowed: RuntimeAuthority[];
+    };
+    routing: {
+        preferredRuntime?: RuntimeId;
+        candidateRuntimes: RuntimeId[];
+        fallbackChain: RuntimeId[];
+        reason?: string;
+    };
+    constraints: {
+        timeoutMs?: number;
+        maxTokens?: number;
+        requireEvidence: boolean;
+        allowNetwork: boolean;
+        allowShell: boolean;
+        allowFileWrite: boolean;
+        allowMcp: boolean;
+    };
+}
+export interface AgentRunResult {
+    success: boolean;
+    exitCode?: number;
+    stdout: string;
+    stderr: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RuntimeAdapter {
+    id: RuntimeId;
+    displayName: string;
+    kind: RuntimeKind;
+    priority: number;
+    capabilities: RuntimeCapabilities;
+    health(): Promise<RuntimeHealth>;
+    supports(request: AgentRunRequest): boolean;
+    runNode(request: AgentRunRequest, signal?: AbortSignal): Promise<AgentRunResult>;
+}
+export interface RuntimeRouteDecision {
+    selectedRuntime: RuntimeId;
+    candidateRuntimes: RuntimeId[];
+    fallbackChain: RuntimeId[];
+    authorityMode: "authority" | "executor" | "proposal" | "advisory" | "veto";
+    reason: string;
+    confidence: number;
+    rejected?: Array<{
+        runtimeId: RuntimeId;
+        reason: string;
+    }>;
+}
+export declare function isRuntimeId(value: unknown): value is RuntimeId;
+export declare function isRuntimeAdapter(value: unknown): value is RuntimeAdapter;

package/dist/runtime/adapter.js

@@ -0,0 +1,28 @@
+/**
+ * RuntimeAdapter — provider-routing interface.
+ *
+ * Used by the provider routing layer (src/providers/) to select candidate
+ * runtimes, check health, and dispatch AgentRunRequests.
+ *
+ * It is stricter than AgentRuntime: runNode operates on AgentRunRequest,
+ * and health()/supports()/runNode() are all mandatory.
+ *
+ * For the internal runtime implementation interface, see
+ * src/runtime/agent-runtime.ts (AgentRuntime).
+ */
+export function isRuntimeId(value) {
+    return typeof value === "string" && value.length > 0;
+}
+export function isRuntimeAdapter(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const r = value;
+    return (typeof r.id === "string" &&
+        typeof r.displayName === "string" &&
+        typeof r.priority === "number" &&
+        typeof r.capabilities === "object" &&
+        r.capabilities !== null &&
+        typeof r.health === "function" &&
+        typeof r.supports === "function" &&
+        typeof r.runNode === "function");
+}

package/dist/runtime/advanced-control-loop.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Advanced Control Loop — Phase 6 of OMK Weakness Remediation (Algorithm 12).
+ *
+ * Orchestrates Phases 1–5 into a single turn-gating engine:
+ * 1. Public surface compression
+ * 2. Proof bundle trust evaluation
+ * 3. Provider maturity gating
+ * 4. Evidence-calibrated router v2
+ * 5. Release gate advisory
+ */
+import type { CompressionResult, SurfaceItem } from "./public-surface.js";
+import type { ProofBundleScores, TrustScoreResult } from "./proof-bundle-trust.js";
+import type { MaturityResult } from "./provider-maturity-gate.js";
+import type { RuntimeRouterDecisionV2, EvidenceHistoryEntry, NodeIntent } from "./contracts/router-v2.js";
+import type { ReleasePromotionInputs, ReleasePromotionResult } from "./contracts/weakness-remediation.js";
+import type { ReleasePromotionGate } from "../cli/release-promotion-gate.js";
+import type { AdapterTestResult } from "./contracts/evidence.js";
+import type { AgentRuntime } from "./agent-runtime.js";
+export type IntegrationResultKind = "verified" | "blocked" | "handoff";
+export interface WeaknessRemediationState {
+    readonly publicSurface: CompressionResult;
+    readonly proofTrust: TrustScoreResult;
+    readonly providerMaturity: MaturityResult;
+    readonly routerV2Decision: RuntimeRouterDecisionV2 | null;
+    readonly releaseGate: ReleasePromotionResult | null;
+}
+export interface AdvancedControlLoopInput {
+    readonly turnId: string;
+    readonly intent: NodeIntent;
+    readonly surfaceItems: readonly SurfaceItem[];
+    readonly proofScores: ProofBundleScores;
+    readonly providerTests: readonly AdapterTestResult[];
+    readonly candidates: readonly AgentRuntime[];
+    readonly evidenceHistory: readonly EvidenceHistoryEntry[];
+    readonly releaseInputs?: ReleasePromotionInputs;
+    readonly retryBudget?: number;
+}
+export interface AdvancedControlLoopResult {
+    readonly kind: IntegrationResultKind;
+    readonly turnId: string;
+    readonly state: WeaknessRemediationState;
+    readonly replan?: {
+        readonly triggered: boolean;
+        readonly reason: string;
+        readonly retryBudgetRemaining: number;
+    };
+    readonly evidenceContractPath: string;
+}
+export interface AdvancedControlLoop {
+    readonly run: (input: AdvancedControlLoopInput) => Promise<AdvancedControlLoopResult>;
+}
+export interface AdvancedControlLoopOptions {
+    readonly publicSurfaceBudget?: number;
+    readonly tauProof?: number;
+    readonly tauEvidence?: number;
+    readonly releaseGate?: ReleasePromotionGate;
+    readonly releaseGateEnabled?: boolean;
+    readonly evidenceContractDir?: string;
+}
+export declare function createAdvancedControlLoop(options?: AdvancedControlLoopOptions): AdvancedControlLoop;

package/dist/runtime/advanced-control-loop.js

@@ -0,0 +1,136 @@
+/**
+ * Advanced Control Loop — Phase 6 of OMK Weakness Remediation (Algorithm 12).
+ *
+ * Orchestrates Phases 1–5 into a single turn-gating engine:
+ * 1. Public surface compression
+ * 2. Proof bundle trust evaluation
+ * 3. Provider maturity gating
+ * 4. Evidence-calibrated router v2
+ * 5. Release gate advisory
+ */
+import { PublicSurfaceCompressor } from "./public-surface.js";
+import { createProofBundleTrustEngine } from "./proof-bundle-trust.js";
+import { TAU_PROOF } from "./contracts/weakness-remediation.js";
+import { createProviderMaturityGate } from "./provider-maturity-gate.js";
+import { createRouterV2ScoringEngine } from "./router-v2-scoring.js";
+import { TAU_EVIDENCE } from "./contracts/weakness-remediation.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function clamp01(n) {
+    return Math.max(0, Math.min(1, n));
+}
+function buildState(publicSurface, proofTrust, providerMaturity, routerV2Decision, releaseGate) {
+    return Object.freeze({
+        publicSurface,
+        proofTrust: proofTrust ??
+            Object.freeze({
+                score: 0,
+                permissionLevel: "no-claim",
+                passed: false,
+                breakdown: Object.freeze({
+                    schema: 0,
+                    hashes: 0,
+                    commands: 0,
+                    stdout: 0,
+                    decisions: 0,
+                    evidence: 0,
+                    limitations: 0,
+                    replay: 0,
+                }),
+            }),
+        providerMaturity: providerMaturity ??
+            Object.freeze({
+                score: 0,
+                authorityClass: "disabled",
+                passed: false,
+                subScores: Object.freeze({
+                    auth: 0,
+                    read: 0,
+                    write: 0,
+                    shell: 0,
+                    mcp: 0,
+                    merge: 0,
+                    evidence: 0,
+                    fallback: 0,
+                }),
+            }),
+        routerV2Decision,
+        releaseGate,
+    });
+}
+// ─── Factory ─────────────────────────────────────────────────────────────────
+export function createAdvancedControlLoop(options = {}) {
+    const { publicSurfaceBudget, tauProof = TAU_PROOF, tauEvidence = TAU_EVIDENCE, releaseGate, releaseGateEnabled = true, evidenceContractDir = ".omk/evidence", } = options;
+    const compressorOptions = publicSurfaceBudget
+        ? { budget: publicSurfaceBudget }
+        : {};
+    const compressor = new PublicSurfaceCompressor(compressorOptions);
+    const proofEngine = createProofBundleTrustEngine();
+    const maturityGate = createProviderMaturityGate();
+    const routerV2Engine = createRouterV2ScoringEngine();
+    return {
+        async run(input) {
+            // Phase 1 — Public surface compression
+            const publicSurface = compressor.compress(input.surfaceItems);
+            if (!publicSurface.invariantPassed) {
+                return Object.freeze({
+                    kind: "blocked",
+                    turnId: input.turnId,
+                    state: buildState(publicSurface, null, null, null, null),
+                    evidenceContractPath: `${evidenceContractDir}/${input.turnId}-blocked.json`,
+                });
+            }
+            // Phase 2 — Proof bundle trust evaluation
+            const proofTrust = proofEngine.evaluate(input.proofScores);
+            if (proofTrust.score < tauProof) {
+                return Object.freeze({
+                    kind: "handoff",
+                    turnId: input.turnId,
+                    state: buildState(publicSurface, proofTrust, null, null, null),
+                    replan: {
+                        triggered: false,
+                        reason: `Proof trust ${clamp01(proofTrust.score).toFixed(3)} < τ_proof ${tauProof}`,
+                        retryBudgetRemaining: input.retryBudget ?? 0,
+                    },
+                    evidenceContractPath: `${evidenceContractDir}/${input.turnId}-handoff.json`,
+                });
+            }
+            // Phase 3 — Provider maturity gating
+            const providerMaturity = maturityGate.evaluate(input.providerTests);
+            if (!providerMaturity.passed || providerMaturity.authorityClass === "disabled") {
+                return Object.freeze({
+                    kind: "blocked",
+                    turnId: input.turnId,
+                    state: buildState(publicSurface, proofTrust, providerMaturity, null, null),
+                    evidenceContractPath: `${evidenceContractDir}/${input.turnId}-blocked.json`,
+                });
+            }
+            // Phase 4 — Evidence-calibrated router v2
+            const routerV2Decision = routerV2Engine.select([...input.candidates], input.intent, [...input.evidenceHistory]);
+            const bestScore = routerV2Decision.scores[0];
+            if (!bestScore || bestScore.bayesianEvidenceScore < tauEvidence) {
+                return Object.freeze({
+                    kind: "handoff",
+                    turnId: input.turnId,
+                    state: buildState(publicSurface, proofTrust, providerMaturity, routerV2Decision, null),
+                    replan: {
+                        triggered: true,
+                        reason: `Router v2 bayesian evidence ${bestScore ? clamp01(bestScore.bayesianEvidenceScore).toFixed(3) : "n/a"} < τ_evidence ${tauEvidence}`,
+                        retryBudgetRemaining: Math.max(0, (input.retryBudget ?? 1) - 1),
+                    },
+                    evidenceContractPath: `${evidenceContractDir}/${input.turnId}-handoff.json`,
+                });
+            }
+            // Phase 5 — Release gate advisory (optional)
+            let releaseGateResult = null;
+            if (releaseGateEnabled && releaseGate && input.releaseInputs) {
+                releaseGateResult = releaseGate.evaluate(input.releaseInputs);
+            }
+            return Object.freeze({
+                kind: "verified",
+                turnId: input.turnId,
+                state: buildState(publicSurface, proofTrust, providerMaturity, routerV2Decision, releaseGateResult),
+                evidenceContractPath: `${evidenceContractDir}/${input.turnId}-verified.json`,
+            });
+        },
+    };
+}