open-multi-agent-kit 0.79.3 → 0.80.2

package/dist/runtime/freedomd-router.js

@@ -0,0 +1,433 @@
+/**
+ * Freedomd runtime router.
+ *
+ * Wraps the base RuntimeRouter with provider-sovereignty scoring, data-retention
+ * gating, cutoff-resilient fallback, degraded-mode planning, and local-first
+ * evidence envelopes. This is the control-plane boundary that keeps OMK loops
+ * alive when a provider becomes unavailable or policy-blocked.
+ */
+import { createRuntimeRouter } from "./runtime-router.js";
+import { computeRuntimeCapabilityScore } from "./runtime-router.js";
+import { compileFreedomdPolicy } from "./freedomd-policy.js";
+import { buildProviderSovereigntyProfiles, computeProviderSovereigntyScore, lookupSovereigntyProfile, } from "./provider-sovereignty.js";
+import { evaluateDataRetentionGate } from "./data-retention-gate.js";
+import { buildLocalFirstEvidenceEnvelope } from "./freedomd-evidence-envelope.js";
+import { runtimeProviderId, runtimeModeOf } from "./authority-matrix.js";
+import { maskSensitiveText } from "../util/secret-mask.js";
+import { loadProviderIncidents } from "./freedomd-incidents.js";
+import { requestProviderException } from "./freedomd-exception.js";
+function severityOrdinal(severity) {
+    if (severity === "block")
+        return 2;
+    if (severity === "warn")
+        return 1;
+    return 0;
+}
+function hasLocalRuntime(runtimes) {
+    return runtimes.some((r) => runtimeProviderId(r) === "local-llm" || r.id.startsWith("local-"));
+}
+export function evaluateTaskSovereignty(task, policy, runtimes, incidents) {
+    const localAvailable = hasLocalRuntime(runtimes);
+    const candidateProviderIds = new Set(runtimes.map((r) => runtimeProviderId(r)));
+    const matchedIncidents = (incidents ?? []).filter((i) => candidateProviderIds.has(i.providerId));
+    const incident = matchedIncidents.sort((a, b) => severityOrdinal(b.severity) - severityOrdinal(a.severity))[0];
+    const cutoffRisk = incident?.severity === "block" ? 1.0 : incident?.severity === "warn" ? 0.5 : 0.0;
+    let retentionDecision = "allow";
+    if (policy.mode === "strict" && !localAvailable) {
+        retentionDecision = "block";
+    }
+    else if (!policy.allowExportRestrictedProvider && incident?.kind === "export-control") {
+        retentionDecision = "block";
+    }
+    let jurisdictionDecision = "allow";
+    if (incident?.kind === "jurisdiction" || incident?.kind === "export-control") {
+        jurisdictionDecision = incident.severity === "block" ? "block" : "downgrade";
+    }
+    const reasonParts = [`mode=${policy.mode}`];
+    if (incident)
+        reasonParts.push(`incident=${incident.kind}:${incident.severity}`);
+    if (!localAvailable)
+        reasonParts.push("no-local-fallback");
+    return {
+        mode: policy.mode === "off" ? "standard" : "freedomd",
+        dataBoundary: "internal",
+        retentionDecision,
+        jurisdictionDecision,
+        providerCutoffRisk: cutoffRisk,
+        localFallbackAvailable: localAvailable,
+        reason: reasonParts.join("; "),
+    };
+}
+function classifyFreedomdIntent(task, capsule) {
+    const text = `${task.context.nodeId} ${task.context.goal ?? ""} ${task.prompt} ${task.context.role ?? ""} ${capsule?.node?.role ?? ""}`.toLowerCase();
+    const role = (task.context.role ?? capsule?.node?.role ?? "").toLowerCase();
+    if (/debug|fix|error|failure|bug|trace/.test(text) || role === "debugger")
+        return "debugging";
+    if (/review|audit|check|validate|verify/.test(text) || role === "reviewer")
+        return "review";
+    if (/test|spec|coverage|assertion/.test(text) || role === "tester")
+        return "test-generation";
+    if (/refactor|optimize|clean|improve|simplify/.test(text) || role === "refactor")
+        return "refactor";
+    if (/research|investigate|explore|search|discover|analyze/.test(text) || role === "researcher")
+        return "research";
+    if (/plan|design|architect|strategy|roadmap/.test(text) || role === "planner")
+        return "planning";
+    if (/doc|readme|changelog|comment/.test(text) || role === "documenter")
+        return "documentation";
+    if (/shell|command|run|exec|script/.test(text) || role === "shell")
+        return "shell-operation";
+    return "coding";
+}
+function runtimePriorityScore(runtime) {
+    return Math.max(0, Math.min(1, runtime.priority / 100));
+}
+export function scoreRuntimesWithSovereignty(task, runtimes, policy, options = {}) {
+    const profiles = options.profiles ?? buildProviderSovereigntyProfiles();
+    const incidents = options.incidents ?? [];
+    const intent = classifyFreedomdIntent(task, options.capsule);
+    const scored = [];
+    for (const runtime of runtimes) {
+        const profile = lookupSovereigntyProfile(runtime, profiles);
+        if (!profile)
+            continue;
+        const sovereignty = computeProviderSovereigntyScore(runtime, task, {
+            profile,
+            userCountry: options.userCountry,
+            taskRisk: task.safety?.risk,
+            incidents,
+            localAvailable: runtimeProviderId(runtime) === "local-llm" || runtime.id.startsWith("local-"),
+        });
+        if (policy.mode !== "off") {
+            if (sovereignty.diagnostics.jurisdictionRisk > policy.maxJurisdictionRisk)
+                continue;
+            if (sovereignty.diagnostics.retentionRisk > policy.maxRetentionRisk)
+                continue;
+            if (sovereignty.diagnostics.cutoffRisk > policy.maxCutoffRisk)
+                continue;
+        }
+        const retention = evaluateDataRetentionGate({
+            task,
+            runtime,
+            providerProfile: profile,
+            orgMaxRetentionDays: policy.maxRetentionDays,
+            allowRedaction: options.allowRedaction ?? false,
+        });
+        if (retention.decision === "block")
+            continue;
+        const capabilityScore = computeRuntimeCapabilityScore(runtime, intent);
+        const priorityScore = runtimePriorityScore(runtime);
+        let capabilityWeight;
+        let priorityWeight;
+        let sovereigntyWeight;
+        if (policy.mode === "strict") {
+            capabilityWeight = 0.3;
+            priorityWeight = 0.1;
+            sovereigntyWeight = 0.6;
+            const isLocal = runtimeProviderId(runtime) === "local-llm" || runtime.id.startsWith("local-");
+            if (isLocal) {
+                sovereigntyWeight = 0.5;
+                capabilityWeight = 0.4;
+            }
+        }
+        else if (policy.mode === "balanced") {
+            capabilityWeight = 0.5;
+            priorityWeight = 0.2;
+            sovereigntyWeight = 0.3;
+        }
+        else {
+            capabilityWeight = 0.7;
+            priorityWeight = 0.3;
+            sovereigntyWeight = 0.0;
+        }
+        const score = capabilityWeight * capabilityScore +
+            priorityWeight * priorityScore +
+            sovereigntyWeight * sovereignty.score;
+        scored.push({ runtime, score, sovereignty, retention });
+    }
+    return scored.sort((a, b) => b.score - a.score);
+}
+export function buildFreedomdDegradedPlan(task, reason, runtimes) {
+    const localAuthority = runtimes.find((r) => {
+        const pid = runtimeProviderId(r);
+        return (pid === "local-llm" || r.id.startsWith("local-")) && (r.capabilities?.write || r.capabilities?.shell);
+    });
+    if (localAuthority) {
+        return {
+            mode: "local-authority",
+            runtime: localAuthority,
+            allowedCapabilities: ["read", "write", "patch", "shell"],
+            reason,
+        };
+    }
+    const localRead = runtimes.find((r) => runtimeProviderId(r) === "local-llm" || r.id.startsWith("local-"));
+    if (localRead) {
+        return {
+            mode: "read-only-local-review",
+            runtime: localRead,
+            allowedCapabilities: ["read", "review"],
+            reason,
+            blockedOriginalAuthority: Object.entries(task.capabilities)
+                .filter(([, v]) => v === true)
+                .map(([k]) => k),
+        };
+    }
+    return {
+        mode: "blocked",
+        allowedCapabilities: [],
+        reason,
+    };
+}
+function agentResultToRunResult(result, runtimeId) {
+    return {
+        success: result.exitCode === 0,
+        exitCode: result.exitCode,
+        stdout: result.output,
+        stderr: "",
+        metadata: { ...result.metadata, runtime: runtimeId },
+        tokenUsage: result.tokenUsage,
+        toolCalls: result.toolCalls,
+    };
+}
+export async function createFreedomdRuntimeRouter(options = {}) {
+    const policy = compileFreedomdPolicy({
+        taskFlags: options.freedomdMode ? { mode: options.freedomdMode } : undefined,
+    });
+    const profiles = options.sovereigntyProfiles ?? buildProviderSovereigntyProfiles();
+    const loadedIncidents = options.autoLoadIncidents !== false ? await loadProviderIncidents({ projectRoot: options.projectRoot, feedUrls: policy.incidentFeedUrls }) : [];
+    const incidents = options.incidents ?? loadedIncidents;
+    const graphStore = options.graphStore;
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const baseOptions = {
+        runtimes: options.runtimes,
+        fallbackChain: options.fallbackChain,
+        memoryPath: options.memoryPath,
+    };
+    const baseRouter = createRuntimeRouter(baseOptions);
+    async function materialize(runId, nodeId, route, envelope) {
+        if (!graphStore)
+            return;
+        try {
+            await graphStore.materializeFreedomdSovereignty({
+                runId,
+                nodeId,
+                providerId: route.selectedRuntime ? runtimeProviderId(route.selectedRuntime) : "none",
+                runtimeMode: route.selectedRuntime ? runtimeModeOf(route.selectedRuntime) : "none",
+                sovereignty: route.sovereignty,
+                degradedMode: route.degradedPlan?.mode,
+                incident: route.sovereignty.providerCutoffRisk >= 0.5
+                    ? { kind: "cutoff", severity: route.sovereignty.providerCutoffRisk >= 1 ? "block" : "warn", reason: route.sovereignty.reason }
+                    : undefined,
+            });
+            if (envelope) {
+                await graphStore.materializeFreedomdEvidenceEnvelope({
+                    runId,
+                    nodeId,
+                    envelopePath: `.omk/runs/${runId}/freedomd/${nodeId}-evidence-envelope.json`,
+                });
+            }
+        }
+        catch {
+            // Graph materialization is best-effort; do not block turn execution.
+        }
+    }
+    async function freedomdRoute(task, capsule) {
+        const sovereignty = evaluateTaskSovereignty(task, policy, options.runtimes ?? [], incidents);
+        if (sovereignty.retentionDecision === "block" || sovereignty.jurisdictionDecision === "block") {
+            const degraded = buildFreedomdDegradedPlan(task, sovereignty.reason, options.runtimes ?? []);
+            return {
+                fallbackChain: [],
+                degradedPlan: degraded,
+                sovereignty,
+                diagnostics: `blocked; degraded=${degraded.mode}`,
+            };
+        }
+        const scored = scoreRuntimesWithSovereignty(task, options.runtimes ?? [], policy, {
+            profiles,
+            incidents,
+            userCountry: options.userCountry,
+            allowRedaction: options.allowRedaction,
+            capsule,
+        });
+        if (scored.length === 0) {
+            const degraded = buildFreedomdDegradedPlan(task, "NO_FREEDOMD_COMPATIBLE_RUNTIME", options.runtimes ?? []);
+            if (policy.allowProviderExceptions && options.isTty !== false) {
+                const blocked = options.runtimes?.[0];
+                if (blocked) {
+                    const profile = lookupSovereigntyProfile(blocked, profiles);
+                    const exception = await requestProviderException({
+                        providerId: runtimeProviderId(blocked),
+                        runtimeMode: runtimeModeOf(blocked),
+                        blockedReason: "NO_FREEDOMD_COMPATIBLE_RUNTIME",
+                        retentionDays: profile?.retentionDays ?? 0,
+                        jurisdictionRisk: profile ? computeProviderSovereigntyScore(blocked, task, { profile, incidents }).diagnostics.jurisdictionRisk : 0,
+                        localFallbackAvailable: hasLocalRuntime(options.runtimes ?? []),
+                        taskSensitivity: task.safety?.risk ?? "unknown",
+                    }, {
+                        runId: task.context.runId,
+                        nodeId: task.context.nodeId,
+                        projectRoot,
+                        graphStore,
+                        isTty: options.isTty,
+                        promptUser: options.promptUser,
+                    });
+                    if (exception.decision === "once" || exception.decision === "run") {
+                        return {
+                            selectedRuntime: blocked,
+                            fallbackChain: [],
+                            sovereignty,
+                            diagnostics: `provider exception ${exception.decision} for ${blocked.id}`,
+                            providerException: exception,
+                        };
+                    }
+                }
+            }
+            return {
+                fallbackChain: [],
+                degradedPlan: degraded,
+                sovereignty,
+                diagnostics: "no compatible runtime; degraded",
+            };
+        }
+        const selected = scored[0];
+        const fallbackChain = scored.slice(1).map((s) => s.runtime);
+        if (selected.retention.decision === "downgrade") {
+            const degraded = buildFreedomdDegradedPlan(task, selected.retention.reason, options.runtimes ?? []);
+            return {
+                selectedRuntime: selected.runtime,
+                fallbackChain,
+                degradedPlan: degraded,
+                sovereignty,
+                diagnostics: `retention downgrade; selected=${selected.runtime.id}; fallback=${fallbackChain.map((r) => r.id).join(",")}`,
+            };
+        }
+        return {
+            selectedRuntime: selected.runtime,
+            fallbackChain,
+            sovereignty,
+            diagnostics: `selected=${selected.runtime.id}; sovereignty=${selected.sovereignty.score.toFixed(2)}; fallback=${fallbackChain.map((r) => r.id).join(",")}`,
+        };
+    }
+    async function executeTask(task, capsule, signal) {
+        const route = await freedomdRoute(task, capsule);
+        return runFreedomdRoute(task, capsule, route, signal);
+    }
+    async function runFreedomdRoute(task, capsule, route, signal) {
+        const runId = task.context.runId;
+        const nodeId = task.context.nodeId;
+        if (route.degradedPlan && !route.selectedRuntime) {
+            const result = {
+                success: false,
+                exitCode: 78,
+                stdout: "",
+                stderr: `Freedomd degraded mode: ${route.degradedPlan.mode}. ${route.degradedPlan.reason}`,
+                metadata: {
+                    freedomd: true,
+                    degradedMode: route.degradedPlan.mode,
+                    sovereignty: route.sovereignty,
+                    remediation: [
+                        "Enable local-llm runtime",
+                        "Configure an authority-capable CLI runtime",
+                        "Lower task authority to read/review",
+                        "Provide user-approved provider exception",
+                    ],
+                },
+            };
+            await materialize(runId, nodeId, route);
+            return result;
+        }
+        const primary = route.selectedRuntime;
+        const allCandidates = [primary, ...route.fallbackChain];
+        let lastError;
+        for (const runtime of allCandidates) {
+            if (signal.aborted) {
+                return {
+                    success: false,
+                    exitCode: 130,
+                    stdout: "",
+                    stderr: "Aborted before execution",
+                    metadata: { runtime: runtime.id, aborted: true, sovereignty: route.sovereignty },
+                };
+            }
+            try {
+                const rawResult = runtime.execute
+                    ? await runtime.execute(task)
+                    : await runtime.runNode(capsule, signal);
+                const result = "stdout" in rawResult ? rawResult : agentResultToRunResult(rawResult, runtime.id);
+                const safeResult = {
+                    success: result.success,
+                    exitCode: result.exitCode,
+                    stdout: result.stdout,
+                    stderr: maskSensitiveText(result.stderr),
+                    metadata: {
+                        ...result.metadata,
+                        selectedRuntime: runtime.id,
+                        sovereignty: route.sovereignty,
+                        fallbackChain: allCandidates.map((r) => r.id),
+                        freedomd: true,
+                    },
+                    tokenUsage: result.tokenUsage,
+                    toolCalls: result.toolCalls,
+                };
+                const envelope = await buildLocalFirstEvidenceEnvelope({
+                    task,
+                    selectedRuntime: runtime,
+                    runContext: { runId, nodeId, projectRoot },
+                    providerResponse: safeResult,
+                    sovereignty: route.sovereignty,
+                });
+                await materialize(runId, nodeId, route, envelope);
+                if (safeResult.success) {
+                    return {
+                        ...safeResult,
+                        metadata: {
+                            ...safeResult.metadata,
+                            freedomdEvidenceEnvelope: envelope.localArtifacts[envelope.localArtifacts.length - 1]?.path,
+                        },
+                    };
+                }
+                lastError = safeResult;
+            }
+            catch (err) {
+                const error = maskSensitiveText(String(err));
+                lastError = {
+                    success: false,
+                    exitCode: 1,
+                    stdout: "",
+                    stderr: error,
+                    metadata: { runtime: runtime.id, error, sovereignty: route.sovereignty },
+                };
+            }
+        }
+        const final = lastError ?? {
+            success: false,
+            exitCode: 1,
+            stdout: "",
+            stderr: "No Freedomd runtime available",
+            metadata: { attempted: allCandidates.map((r) => r.id), sovereignty: route.sovereignty },
+        };
+        const envelope = await buildLocalFirstEvidenceEnvelope({
+            task,
+            selectedRuntime: primary,
+            runContext: { runId, nodeId, projectRoot },
+            providerResponse: final,
+            sovereignty: route.sovereignty,
+        });
+        await materialize(runId, nodeId, route, envelope);
+        return final;
+    }
+    return {
+        policy,
+        // baseRouter intentionally omitted from public return type to avoid leaking
+        // internal RuntimeRouter history types; use executeTask for routing.
+        baseRouter: baseRouter,
+        freedomdRoute,
+        scoreRuntimesWithSovereignty: (task) => scoreRuntimesWithSovereignty(task, options.runtimes ?? [], policy, {
+            profiles,
+            incidents,
+            userCountry: options.userCountry,
+            allowRedaction: options.allowRedaction,
+        }),
+        executeTask,
+    };
+}

package/dist/runtime/headroom-aware-loop-decision.d.ts

@@ -0,0 +1,21 @@
+import { type HeadroomDecisionHistoryEntry, type HeadroomLoopRiskSignal } from "./headroom-loop-risk.js";
+export type HeadroomLoopAction = "continue" | "block" | "replan" | "context-adjustment";
+export interface HeadroomAwareLoopDecision {
+    readonly action: HeadroomLoopAction;
+    readonly reason: string;
+    readonly confidence: number;
+    readonly contextAdjustment?: {
+        readonly dropLowPriorityGraphMemory: boolean;
+        readonly reduceFileSlices: boolean;
+        readonly forceStructuredFallback: boolean;
+    };
+    readonly risk?: {
+        readonly headroom: HeadroomLoopRiskSignal;
+    };
+}
+export declare function evaluateHeadroomAwareLoopDecision(input: {
+    readonly baseAction: HeadroomLoopAction;
+    readonly baseReason: string;
+    readonly baseConfidence: number;
+    readonly headroomHistory: readonly HeadroomDecisionHistoryEntry[];
+}): HeadroomAwareLoopDecision;

package/dist/runtime/headroom-aware-loop-decision.js

@@ -0,0 +1,67 @@
+import { computeHeadroomLoopRiskSignal } from "./headroom-loop-risk.js";
+function isStrictGuardrailMode() {
+    const raw = process.env.OMK_STRICT_GUARDRAIL ?? "";
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "on";
+}
+export function evaluateHeadroomAwareLoopDecision(input) {
+    const headroomRisk = computeHeadroomLoopRiskSignal(input.headroomHistory);
+    if (headroomRisk.kind === "none") {
+        return {
+            action: input.baseAction,
+            reason: input.baseReason,
+            confidence: input.baseConfidence,
+            risk: { headroom: headroomRisk },
+        };
+    }
+    if (!isStrictGuardrailMode()) {
+        return {
+            action: "continue",
+            reason: `${input.baseReason}; headroom risk noted under agent-freedom mode: ${headroomRisk.reason}`,
+            confidence: Math.min(input.baseConfidence, headroomRisk.severity),
+            contextAdjustment: headroomRisk.recommendedAction === "summarize-or-drop-low-priority-context"
+                ? {
+                    dropLowPriorityGraphMemory: true,
+                    reduceFileSlices: true,
+                    forceStructuredFallback: true,
+                }
+                : undefined,
+            risk: { headroom: headroomRisk },
+        };
+    }
+    if (headroomRisk.recommendedAction === "block") {
+        return {
+            action: "block",
+            reason: headroomRisk.reason,
+            confidence: Math.max(input.baseConfidence, headroomRisk.severity),
+            risk: { headroom: headroomRisk },
+        };
+    }
+    if (headroomRisk.recommendedAction === "replan") {
+        return {
+            action: input.baseAction === "continue" || input.baseAction === "context-adjustment" ? "replan" : input.baseAction,
+            reason: `${input.baseReason}; ${headroomRisk.reason}`,
+            confidence: Math.max(input.baseConfidence, headroomRisk.severity),
+            risk: { headroom: headroomRisk },
+        };
+    }
+    if (headroomRisk.recommendedAction === "summarize-or-drop-low-priority-context") {
+        return {
+            action: "continue",
+            reason: `${input.baseReason}; ${headroomRisk.reason}`,
+            confidence: Math.max(input.baseConfidence, headroomRisk.severity),
+            contextAdjustment: {
+                dropLowPriorityGraphMemory: true,
+                reduceFileSlices: true,
+                forceStructuredFallback: true,
+            },
+            risk: { headroom: headroomRisk },
+        };
+    }
+    return {
+        action: input.baseAction,
+        reason: input.baseReason,
+        confidence: input.baseConfidence,
+        risk: { headroom: headroomRisk },
+    };
+}

package/dist/runtime/headroom-loop-risk.d.ts

@@ -0,0 +1,19 @@
+export type HeadroomLoopRiskKind = "none" | "compaction-contract-drift" | "headroom-no-apply" | "low-compaction-yield";
+export type HeadroomLoopRecommendedAction = "continue" | "block" | "replan" | "summarize-or-drop-low-priority-context";
+export interface HeadroomDecisionHistoryEntry {
+    readonly attempted?: boolean;
+    readonly applied?: boolean;
+    readonly validated?: boolean;
+    readonly compactedTextProduced?: boolean;
+    readonly beforeTokens?: number | null;
+    readonly afterTokens?: number | null;
+    readonly reason?: string;
+    readonly missingSections?: readonly string[];
+}
+export interface HeadroomLoopRiskSignal {
+    readonly kind: HeadroomLoopRiskKind;
+    readonly severity: number;
+    readonly recommendedAction: HeadroomLoopRecommendedAction;
+    readonly reason: string;
+}
+export declare function computeHeadroomLoopRiskSignal(history: readonly HeadroomDecisionHistoryEntry[]): HeadroomLoopRiskSignal;

package/dist/runtime/headroom-loop-risk.js

@@ -0,0 +1,43 @@
+export function computeHeadroomLoopRiskSignal(history) {
+    const recent = history.slice(-3);
+    if (recent.length < 2) {
+        return noHeadroomLoopRisk("not enough headroom decision history");
+    }
+    const failedApplyCount = recent.filter((entry) => entry.attempted === true && entry.applied !== true).length;
+    const validationFailureCount = recent.filter((entry) => entry.compactedTextProduced === true && entry.validated !== true).length;
+    const lowYieldCount = recent.filter((entry) => {
+        if (entry.applied !== true)
+            return false;
+        const before = Math.max(1, entry.beforeTokens ?? 0);
+        const after = Math.max(0, entry.afterTokens ?? 0);
+        return after / before > 0.85;
+    }).length;
+    if (validationFailureCount >= 2) {
+        return {
+            kind: "compaction-contract-drift",
+            severity: 0.9,
+            recommendedAction: "block",
+            reason: "structured compaction repeatedly stripped or mismatched required contract sections",
+        };
+    }
+    if (failedApplyCount >= 3) {
+        return {
+            kind: "headroom-no-apply",
+            severity: 0.8,
+            recommendedAction: "replan",
+            reason: "headroom crossed the threshold repeatedly but no compacted capsule was applied",
+        };
+    }
+    if (lowYieldCount >= 2) {
+        return {
+            kind: "low-compaction-yield",
+            severity: 0.6,
+            recommendedAction: "summarize-or-drop-low-priority-context",
+            reason: "compaction applied repeatedly but did not reduce context enough",
+        };
+    }
+    return noHeadroomLoopRisk("headroom decisions show no repeated compaction risk");
+}
+function noHeadroomLoopRisk(reason) {
+    return { kind: "none", severity: 0, recommendedAction: "continue", reason };
+}

package/dist/runtime/headroom-policy.d.ts

@@ -6,7 +6,8 @@
  * a configurable threshold (default 90%).
  *
  * Prefers the external `headroom` CLI compressor when available;
- * falls back to the built-in `optimizeContextBudget` when not.
+ * falls back to caller-provided structured text and finally to legacy
+ * side-effect optimizers when not.
  *
  * Deterministic except for the injectable `runHeadroom` runner.
  */
@@ -18,9 +19,20 @@ export interface HeadroomDecision {
     readonly contextWindow: number;
     readonly reason: string;
 }
+export type HeadroomBackend = "headroom" | "structured-fallback" | "side-effect-fallback" | "none";
 export interface HeadroomCompactResult {
+    /** Backward-compatible summary: a backend produced compacted text or completed a legacy fallback. */
     readonly compacted: boolean;
+    /** Backward-compatible backend family. */
     readonly via: "headroom" | "fallback" | "none";
+    readonly compactedText?: string;
+    readonly reason?: string;
+    /** Whether a compaction attempt was made because the policy threshold was crossed. */
+    readonly attempted: boolean;
+    /** Specific backend that produced this result. */
+    readonly backend: HeadroomBackend;
+    /** Whether a textual backend produced non-empty compacted text. */
+    readonly compactedTextProduced: boolean;
 }
 export declare function resolveHeadroomThreshold(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): number;
 export declare function isHeadroomEnabled(env?: NodeJS.ProcessEnv | Record<string, string | undefined>): boolean;
@@ -34,4 +46,5 @@ export declare function maybeCompactWithHeadroom(args: {
     text?: string;
     runHeadroom?: (text: string) => Promise<string | null>;
     fallback?: () => Promise<void>;
+    fallbackText?: () => string | null | Promise<string | null>;
 }): Promise<HeadroomCompactResult>;