open-multi-agent-kit 0.78.0 → 0.78.1

package/dist/orchestration/adaptorch-topology.js

@@ -0,0 +1,194 @@
+/**
+ * AdaptOrch-style topology router — pure TS, no IO, no python dependency.
+ *
+ * Extracts 5 structural features from a DAG and selects an execution topology
+ * using threshold-based rules matching the AdaptOrch TopologyRouter spec.
+ */
+// ─────────────────────────────────────────────
+// Defaults
+// ─────────────────────────────────────────────
+const DEFAULT_THRESHOLDS = {
+    parallelRatio: 0.5,
+    highCoupling: 0.6,
+    hierarchicalSubtasks: 5,
+};
+// ─────────────────────────────────────────────
+// Env gate
+// ─────────────────────────────────────────────
+/**
+ * Returns `true` unless OMK_ADAPTORCH_ROUTING is explicitly off/0/false.
+ */
+export function isAdaptorchRoutingEnabled(env) {
+    const val = (env ?? process.env)["OMK_ADAPTORCH_ROUTING"];
+    if (val === undefined)
+        return true;
+    const norm = val.trim().toLowerCase();
+    return norm !== "0" && norm !== "off" && norm !== "false";
+}
+// ─────────────────────────────────────────────
+// Feature extraction
+// ─────────────────────────────────────────────
+/**
+ * Compute structural features of a DAG via Kahn topological sort.
+ * Returns layers (waves) and derived metrics.  If a cycle is detected,
+ * all nodes collapse into a single wave.
+ */
+export function computeTopologyFeatures(nodes, edges) {
+    const n = nodes.length;
+    if (n === 0) {
+        return {
+            nodeCount: 0,
+            edgeCount: 0,
+            width: 0,
+            criticalDepth: 0,
+            couplingDensity: 0,
+            parallelRatio: 0,
+            layers: [],
+        };
+    }
+    // Build adjacency + in-degree
+    const inDeg = new Map();
+    const adjacency = new Map();
+    for (const id of nodes) {
+        inDeg.set(id, 0);
+        adjacency.set(id, []);
+    }
+    for (const e of edges) {
+        adjacency.get(e.from)?.push(e.to);
+        inDeg.set(e.to, (inDeg.get(e.to) ?? 0) + 1);
+    }
+    // Kahn topological sort
+    const layers = [];
+    const visited = new Set();
+    // Seed: zero-in-degree nodes
+    let frontier = nodes.filter((id) => (inDeg.get(id) ?? 0) === 0);
+    if (frontier.length === 0) {
+        // All nodes are in a cycle — single wave fallback
+        return {
+            nodeCount: n,
+            edgeCount: edges.length,
+            width: n,
+            criticalDepth: 1,
+            couplingDensity: computeCouplingDensity(n, edges.length),
+            parallelRatio: 1,
+            layers: [nodes.slice()],
+        };
+    }
+    while (frontier.length > 0) {
+        layers.push(frontier.slice());
+        for (const id of frontier)
+            visited.add(id);
+        const nextFrontier = [];
+        for (const id of frontier) {
+            for (const child of adjacency.get(id) ?? []) {
+                const newDeg = (inDeg.get(child) ?? 1) - 1;
+                inDeg.set(child, newDeg);
+                if (newDeg === 0 && !visited.has(child)) {
+                    nextFrontier.push(child);
+                }
+            }
+        }
+        frontier = nextFrontier;
+    }
+    // Cycle detection: if any nodes remain unvisited, collapse to single wave
+    if (visited.size < n) {
+        return {
+            nodeCount: n,
+            edgeCount: edges.length,
+            width: n,
+            criticalDepth: 1,
+            couplingDensity: computeCouplingDensity(n, edges.length),
+            parallelRatio: 1,
+            layers: [nodes.slice()],
+        };
+    }
+    const width = Math.max(...layers.map((l) => l.length));
+    const criticalDepth = layers.length;
+    const couplingDensity = computeCouplingDensity(n, edges.length);
+    const parallelRatio = n > 0 ? width / n : 0;
+    return {
+        nodeCount: n,
+        edgeCount: edges.length,
+        width,
+        criticalDepth,
+        couplingDensity,
+        parallelRatio,
+        layers,
+    };
+}
+// ─────────────────────────────────────────────
+// Topology selection
+// ─────────────────────────────────────────────
+/**
+ * Select a topology and emit layered execution waves.
+ *
+ * Selection rules (in priority order):
+ *   0 nodes       → singleton
+ *   1 node        → singleton
+ *   high coupling → dag (if depth==1) or hierarchical (if depth>1)
+ *   parallelRatio ≥ θ_ω and nodes > 1 → parallel / map_reduce
+ *   criticalDepth == nodes → pipeline
+ *   otherwise     → hybrid
+ */
+export function routeTopology(nodeIds, edges, thresholds) {
+    const t = { ...DEFAULT_THRESHOLDS, ...thresholds };
+    const features = computeTopologyFeatures(nodeIds, edges);
+    const { nodeCount, width, criticalDepth, couplingDensity, parallelRatio } = features;
+    // 0 or 1 node → singleton
+    if (nodeCount <= 1) {
+        return {
+            topology: "singleton",
+            reason: nodeCount === 0 ? "empty DAG" : "single-node DAG",
+            features,
+            waves: features.layers,
+        };
+    }
+    // High coupling check
+    if (couplingDensity >= t.highCoupling) {
+        const topology = criticalDepth > 1 ? "hierarchical" : "dag";
+        return {
+            topology,
+            reason: `high coupling density ${couplingDensity.toFixed(2)} ≥ θ_γ=${t.highCoupling}`,
+            features,
+            waves: features.layers,
+        };
+    }
+    // Parallel / map_reduce — wide low-coupling DAG
+    if (parallelRatio >= t.parallelRatio && nodeCount > 1) {
+        // map_reduce when enough nodes form ≥2 layers with fan-out then fan-in
+        const topology = features.layers.length >= 2 && width >= t.hierarchicalSubtasks
+            ? "map_reduce"
+            : "parallel";
+        return {
+            topology,
+            reason: `parallel ratio ${parallelRatio.toFixed(2)} ≥ θ_ω=${t.parallelRatio}, width=${width}`,
+            features,
+            waves: features.layers,
+        };
+    }
+    // Linear chain → pipeline
+    if (criticalDepth === nodeCount) {
+        return {
+            topology: "pipeline",
+            reason: `linear chain: critical depth (${criticalDepth}) equals node count`,
+            features,
+            waves: features.layers,
+        };
+    }
+    // Fall-through → hybrid
+    return {
+        topology: "hybrid",
+        reason: `mixed structure: depth=${criticalDepth}, width=${width}, coupling=${couplingDensity.toFixed(2)}`,
+        features,
+        waves: features.layers,
+    };
+}
+// ─────────────────────────────────────────────
+// Internal helpers
+// ─────────────────────────────────────────────
+function computeCouplingDensity(n, edgeCount) {
+    if (n <= 1)
+        return 0;
+    const maxEdges = (n * (n - 1)) / 2;
+    return maxEdges > 0 ? edgeCount / maxEdges : 0;
+}

package/dist/orchestration/capability-routing.d.ts

@@ -1,9 +1,20 @@
 import type { DagNode, DagNodeRouting } from "./dag.js";
+import type { ProviderAuthorityLevel } from "../contracts/provider-health.js";
 export interface NodeCapabilityScopes {
     readonly skills: readonly string[];
     readonly mcpServers: readonly string[];
     readonly tools: readonly string[];
     readonly hooks: readonly string[];
+    /**
+     * Provider authority for write/mutation work on this node. Defaults to the
+     * authority-provider value ("full") so the primary coder/authority lane is
+     * never over-blocked. Advisory/opportunistic providers carry lower levels.
+     */
+    readonly writeAuthority: ProviderAuthorityLevel;
+    /** Provider authority for shell/CLI work on this node. Defaults to "full". */
+    readonly shellAuthority: ProviderAuthorityLevel;
+    /** Provider authority for MCP tool work on this node. Defaults to "full". */
+    readonly mcpAuthority: ProviderAuthorityLevel;
 }
 export interface CapabilityRoutingEntry extends NodeCapabilityScopes {
     readonly nodeId: string;
@@ -31,6 +42,18 @@ export interface CapabilityRoutingArtifact {
     readonly nodes: readonly CapabilityRoutingEntry[];
     readonly orchestrator: CapabilityRoutingIdentity;
 }
+/**
+ * Authority levels are derived from the authority-provider doctrine: when a
+ * node does not pin an explicit provider authority it inherits the
+ * authority-provider level ("full") so the primary coder lane stays unblocked.
+ */
+export declare const DEFAULT_NODE_AUTHORITY: ProviderAuthorityLevel;
+/**
+ * Resolve the write/shell/MCP authority levels for a routing entry. Used both
+ * by {@link capabilityScopesFromRouting} and by the live tool-authority gate so
+ * the gate consumes the same authority that routing assigned.
+ */
+export declare function resolveNodeToolAuthorities(routing: DagNodeRouting | undefined, fallback?: Partial<NodeCapabilityScopes>): Pick<NodeCapabilityScopes, "writeAuthority" | "shellAuthority" | "mcpAuthority">;
 export declare function uniqueCapabilityNames(values: readonly (string | undefined)[]): string[];
 export declare function capabilityScopesFromRouting(routing: DagNodeRouting | undefined, fallback?: Partial<NodeCapabilityScopes>): NodeCapabilityScopes;
 export declare function mergeCapabilityScopes(...scopes: readonly (Partial<NodeCapabilityScopes> | undefined)[]): NodeCapabilityScopes;

package/dist/orchestration/capability-routing.js

@@ -1,3 +1,55 @@
+/** Authority levels ordered from most restrictive (0) to most permissive (3). */
+const AUTHORITY_RANK = {
+    none: 0,
+    advisory: 1,
+    direct: 2,
+    full: 3,
+};
+/**
+ * Authority levels are derived from the authority-provider doctrine: when a
+ * node does not pin an explicit provider authority it inherits the
+ * authority-provider level ("full") so the primary coder lane stays unblocked.
+ */
+export const DEFAULT_NODE_AUTHORITY = "full";
+/**
+ * Map a routing `assignedProviderAuthority` token to a {@link ProviderAuthorityLevel}.
+ * Returns `undefined` when the routing does not pin an authority so callers can
+ * fall back to the authority-provider default.
+ */
+function authorityLevelFromAssigned(assigned) {
+    switch (assigned) {
+        case "authority":
+            return "full";
+        case "direct":
+            return "direct";
+        case "advisory":
+            return "advisory";
+        case "veto":
+            return "none";
+        default:
+            return undefined;
+    }
+}
+/** Pick the most restrictive defined authority level, or the fallback. */
+function mostRestrictiveAuthority(values, fallback = DEFAULT_NODE_AUTHORITY) {
+    const defined = values.filter((value) => value !== undefined);
+    if (defined.length === 0)
+        return fallback;
+    return defined.reduce((min, value) => (AUTHORITY_RANK[value] < AUTHORITY_RANK[min] ? value : min));
+}
+/**
+ * Resolve the write/shell/MCP authority levels for a routing entry. Used both
+ * by {@link capabilityScopesFromRouting} and by the live tool-authority gate so
+ * the gate consumes the same authority that routing assigned.
+ */
+export function resolveNodeToolAuthorities(routing, fallback = {}) {
+    const base = authorityLevelFromAssigned(routing?.assignedProviderAuthority);
+    return {
+        writeAuthority: base ?? fallback.writeAuthority ?? DEFAULT_NODE_AUTHORITY,
+        shellAuthority: base ?? fallback.shellAuthority ?? DEFAULT_NODE_AUTHORITY,
+        mcpAuthority: base ?? fallback.mcpAuthority ?? DEFAULT_NODE_AUTHORITY,
+    };
+}
 export function uniqueCapabilityNames(values) {
     return [...new Set(values.filter((value) => Boolean(value?.trim())).map((value) => value.trim()))];
 }
@@ -8,6 +60,7 @@ export function capabilityScopesFromRouting(routing, fallback = {}) {
         mcpServers: uniqueCapabilityNames(routing?.mcpServers ?? assigned?.mcpServers ?? fallback.mcpServers ?? []),
         tools: uniqueCapabilityNames(routing?.tools ?? assigned?.tools ?? fallback.tools ?? []),
         hooks: uniqueCapabilityNames(routing?.hooks ?? assigned?.hooks ?? fallback.hooks ?? []),
+        ...resolveNodeToolAuthorities(routing, fallback),
     };
 }
 export function mergeCapabilityScopes(...scopes) {
@@ -16,6 +69,9 @@ export function mergeCapabilityScopes(...scopes) {
         mcpServers: uniqueCapabilityNames(scopes.flatMap((scope) => scope?.mcpServers ?? [])),
         tools: uniqueCapabilityNames(scopes.flatMap((scope) => scope?.tools ?? [])),
         hooks: uniqueCapabilityNames(scopes.flatMap((scope) => scope?.hooks ?? [])),
+        writeAuthority: mostRestrictiveAuthority(scopes.map((scope) => scope?.writeAuthority)),
+        shellAuthority: mostRestrictiveAuthority(scopes.map((scope) => scope?.shellAuthority)),
+        mcpAuthority: mostRestrictiveAuthority(scopes.map((scope) => scope?.mcpAuthority)),
     };
 }
 export function attachAssignedCapabilities(routing) {

package/dist/orchestration/dag-compiler-types.d.ts

@@ -2,6 +2,7 @@ import type { IntentFrame, GoalSpec } from "../contracts/goal.js";
 import type { ExecutionSelectionDecision, ExecutionStrategy, UserIntentV2 } from "../contracts/orchestration.js";
 import type { InputEnvelope } from "../input/input-envelope.js";
 import type { Dag } from "./dag.js";
+import type { TopologyDecision } from "./adaptorch-topology.js";
 export interface DagCompileInput {
     input: InputEnvelope;
     goal?: GoalSpec;
@@ -26,6 +27,8 @@ export interface DagCompileResult {
     intentFrame?: IntentFrame;
     artifacts: DagCompileArtifactSummary;
     compiledAt: string;
+    /** AdaptOrch topology routing — additive, optional, non-fatal */
+    topology?: TopologyDecision;
 }
 export interface BuildDagCompileResultInput {
     input: InputEnvelope;

package/dist/orchestration/dag-compiler.js

@@ -2,6 +2,7 @@ import { analyzeUserIntentV2 } from "../goal/intent-analyzer.js";
 import { buildIntentFrame } from "../goal/intent-frame.js";
 import { createDag } from "./dag.js";
 import { buildRoleSpecificDagNodes, shouldCompileRoleSpecificDag, } from "./dag-compiler-presets.js";
+import { isAdaptorchRoutingEnabled, routeTopology, } from "./adaptorch-topology.js";
 export async function compileInputEnvelopeToDag(input) {
     const intent = input.intent ??
         (await analyzeUserIntentV2({
@@ -38,7 +39,7 @@ export async function compileInputEnvelopeToDag(input) {
     });
 }
 export function buildDagCompileResult(input) {
-    return {
+    const result = {
         schemaVersion: 1,
         inputId: input.input.inputId,
         runId: input.input.runId,
@@ -53,6 +54,18 @@ export function buildDagCompileResult(input) {
         },
         compiledAt: input.compiledAt ?? new Date().toISOString(),
     };
+    // AdaptOrch topology routing — additive, non-fatal
+    try {
+        if (isAdaptorchRoutingEnabled()) {
+            const nodeIds = input.dag.nodes.map((n) => n.id);
+            const edges = input.dag.nodes.flatMap((n) => n.dependsOn.map((from) => ({ from, to: n.id })));
+            result.topology = routeTopology(nodeIds, edges);
+        }
+    }
+    catch {
+        // non-fatal: topology is optional
+    }
+    return result;
 }
 function selectExecutionStrategy(requested, intent) {
     return (requested ??

package/dist/orchestration/parallel-orchestrator.d.ts

@@ -85,6 +85,12 @@ export declare class ParallelOrchestrator {
      * 오케스트레이션 실행
      */
     execute(): Promise<ParallelOrchestrationResult>;
+    /**
+     * Non-fatal finalizer: if a run-manifest.json was persisted for this run,
+     * link its run -> providerRoute -> provider / evidence / decision / artifact
+     * nodes into the local graph. Failures are swallowed so the run is unaffected.
+     */
+    private linkRunManifestToGraph;
     /**
      * 오케스트레이션 중단
      */

package/dist/orchestration/parallel-orchestrator.js

@@ -161,6 +161,9 @@ export class ParallelOrchestrator {
             // 상태 업데이트: 완료
             this.stateManager.setStatus(success ? "completed" : "failed");
             this.stateManager.setCompletedAt(new Date().toISOString());
+            // Wave-3 p8: link the finalized run manifest into the local graph.
+            // Non-fatal: a graph write failure must never fail the run.
+            await this.linkRunManifestToGraph();
             // 결과 반환
             return this.createResult(success);
         }
@@ -176,6 +179,34 @@ export class ParallelOrchestrator {
             await this.cleanup();
         }
     }
+    /**
+     * Non-fatal finalizer: if a run-manifest.json was persisted for this run,
+     * link its run -> providerRoute -> provider / evidence / decision / artifact
+     * nodes into the local graph. Failures are swallowed so the run is unaffected.
+     */
+    async linkRunManifestToGraph() {
+        try {
+            const { readFile } = await import("fs/promises");
+            const { getRunArtifactPath } = await import("../util/run-store.js");
+            let raw;
+            try {
+                raw = await readFile(getRunArtifactPath(this.runId, "run-manifest.json", this.cwd), "utf-8");
+            }
+            catch {
+                return; // no manifest persisted for this run; nothing to link
+            }
+            const { RunManifestSchema } = await import("../schema/run-manifest.schema.js");
+            const parsed = RunManifestSchema.safeParse(JSON.parse(raw));
+            if (!parsed.success)
+                return;
+            const { linkRunToGraph } = await import("../memory/memory-store.js");
+            await linkRunToGraph(this.runId, parsed.data, { projectRoot: this.cwd });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.logStreamer.log("warn", `graph link skipped: ${message}`);
+        }
+    }
     /**
      * 오케스트레이션 중단
      */

package/dist/providers/provider-health.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Maps existing provider doctor payloads onto the shared {@link ProviderHealth}
+ * shape. This is additive: callers keep their original JSON keys and embed the
+ * result under a `health` key.
+ *
+ * Only type imports are used so the module has no runtime dependencies and can
+ * be unit-tested in isolation. The mapper never surfaces secret values — it
+ * relies on boolean signals (e.g. `apiKeySet`) and environment-variable *names*.
+ */
+import type { ProviderHealth } from "../contracts/provider-health.js";
+import type { ProviderDoctorStatus } from "./model-registry.js";
+/** DeepSeek `provider doctor` JSON object shape (balance preflight + config). */
+export interface DeepSeekDoctorHealthInput {
+    provider: string;
+    available: boolean;
+    enabled?: boolean;
+    apiKeySet?: boolean;
+    checkedAt?: number;
+    reason?: string;
+    balance?: {
+        is_available?: boolean;
+    } | null;
+}
+/** Union of the doctor payloads the mapper understands. */
+export type ProviderHealthInput = ProviderDoctorStatus | DeepSeekDoctorHealthInput;
+/** Optional extra context (never carries secrets). */
+export interface ProviderHealthExtras {
+    /** Resolvable model override (used when the input lacks a `model`). */
+    model?: string;
+    /** ISO timestamp override (mainly for deterministic tests). */
+    checkedAt?: string;
+}
+/**
+ * Maps a provider doctor payload onto the shared {@link ProviderHealth} shape.
+ *
+ * @param status A {@link ProviderDoctorStatus} or DeepSeek doctor object.
+ * @param extras Optional non-sensitive context overrides.
+ */
+export declare function toProviderHealth(status: ProviderHealthInput, extras?: ProviderHealthExtras): ProviderHealth;

package/dist/providers/provider-health.js

@@ -0,0 +1,161 @@
+const SHELL_KINDS = new Set(["external-cli", "codex-cli", "local"]);
+const QUOTA_PATTERN = /balance|quota|insufficient|402|rate[\s_-]*limit/i;
+function toAuthorityLevel(authority) {
+    switch (authority) {
+        case "authority":
+        case "full":
+            return "full";
+        case "direct":
+            return "direct";
+        case "advisory":
+        case "read-only":
+            return "advisory";
+        case "veto":
+        case "none":
+            return "none";
+        default:
+            return "advisory";
+    }
+}
+function hasResolvableModel(model) {
+    return typeof model === "string" && model.trim().length > 0 && model !== "default";
+}
+function isDoctorStatus(input) {
+    return typeof input.kind === "string";
+}
+// Classification relies on the already-derived boolean signals (quotaOk/authOk
+// encode the doctor reason where relevant) so free-text reasons never override
+// an explicit signal — and raw reason text is never echoed into remediation.
+function classifyFailure(signals) {
+    const { runtimeOk, authOk, modelOk, quotaOk } = signals;
+    if (runtimeOk && authOk && modelOk && quotaOk) {
+        return { failureKind: "none", remediation: [] };
+    }
+    if (!quotaOk) {
+        return {
+            failureKind: "quota",
+            remediation: ["Check the provider balance/quota and top up or wait for the quota to reset."],
+        };
+    }
+    if (!authOk) {
+        return {
+            failureKind: "auth",
+            remediation: [
+                signals.apiKeyEnv
+                    ? `Set the ${signals.apiKeyEnv} environment variable, then re-run provider doctor.`
+                    : "Configure provider authentication, then re-run provider doctor.",
+            ],
+        };
+    }
+    if (!runtimeOk) {
+        if (signals.codexCliAvailable === false) {
+            return {
+                failureKind: "runtime",
+                remediation: ["Install the Codex CLI and ensure `codex` is on PATH."],
+            };
+        }
+        if (signals.enabled === false) {
+            return {
+                failureKind: "policy",
+                remediation: ["Enable the provider in OMK configuration before use."],
+            };
+        }
+        return {
+            failureKind: "runtime",
+            remediation: ["Verify the provider runtime is installed and reachable."],
+        };
+    }
+    if (!modelOk) {
+        return {
+            failureKind: "model",
+            remediation: ["Configure a resolvable default model for this provider."],
+        };
+    }
+    return {
+        failureKind: "unknown",
+        remediation: ["Review provider doctor output for details."],
+    };
+}
+function fromDoctorStatus(status, extras) {
+    const apiKeySet = status.apiKeySet;
+    const authMethod = status.authMethod;
+    const authOk = typeof apiKeySet === "boolean"
+        ? apiKeySet
+        : authMethod === "api-key-env"
+            ? false
+            : true; // external-cli / oauth / none: auth handled outside OMK.
+    const runtimeOk = status.available && status.codexCliAvailable !== false;
+    const modelOk = hasResolvableModel(extras?.model ?? status.model);
+    const quotaOk = !QUOTA_PATTERN.test(status.reason ?? "");
+    const capabilities = status.capabilities ?? [];
+    const baseLevel = toAuthorityLevel(status.authority);
+    const declaresMcp = capabilities.includes("mcp") || capabilities.includes("tools");
+    const { failureKind, remediation } = classifyFailure({
+        runtimeOk,
+        authOk,
+        modelOk,
+        quotaOk,
+        enabled: status.enabled,
+        codexCliAvailable: status.codexCliAvailable,
+        apiKeyEnv: status.apiKeyEnv,
+    });
+    return {
+        provider: status.provider,
+        checkedAt: extras?.checkedAt ?? new Date().toISOString(),
+        runtimeOk,
+        authOk,
+        modelOk,
+        quotaOk,
+        writeAuthority: baseLevel,
+        shellAuthority: SHELL_KINDS.has(status.kind) ? baseLevel : "none",
+        mcpAuthority: declaresMcp
+            ? baseLevel
+            : baseLevel === "full" || baseLevel === "direct"
+                ? "advisory"
+                : "none",
+        failureKind,
+        remediation,
+    };
+}
+function fromDeepSeekDoctor(input, extras) {
+    const apiKeySet = input.apiKeySet;
+    const authOk = typeof apiKeySet === "boolean" ? apiKeySet : true;
+    const runtimeOk = input.available && input.enabled !== false;
+    const balanceUnavailable = input.balance?.is_available === false;
+    const quotaOk = !balanceUnavailable && !QUOTA_PATTERN.test(input.reason ?? "");
+    // DeepSeek is a known provider whose default model always resolves from the
+    // registry, so treat the model as resolvable unless an explicit override fails.
+    const modelOk = extras?.model ? hasResolvableModel(extras.model) : true;
+    const { failureKind, remediation } = classifyFailure({
+        runtimeOk,
+        authOk,
+        modelOk,
+        quotaOk,
+        enabled: input.enabled,
+    });
+    const checkedAt = extras?.checkedAt ??
+        (typeof input.checkedAt === "number" ? new Date(input.checkedAt).toISOString() : new Date().toISOString());
+    // DeepSeek participates as an advisory, read-only opportunistic worker.
+    return {
+        provider: input.provider,
+        checkedAt,
+        runtimeOk,
+        authOk,
+        modelOk,
+        quotaOk,
+        writeAuthority: "advisory",
+        shellAuthority: "none",
+        mcpAuthority: "none",
+        failureKind,
+        remediation,
+    };
+}
+/**
+ * Maps a provider doctor payload onto the shared {@link ProviderHealth} shape.
+ *
+ * @param status A {@link ProviderDoctorStatus} or DeepSeek doctor object.
+ * @param extras Optional non-sensitive context overrides.
+ */
+export function toProviderHealth(status, extras) {
+    return isDoctorStatus(status) ? fromDoctorStatus(status, extras) : fromDeepSeekDoctor(status, extras);
+}

package/dist/runtime/context-broker.d.ts

@@ -11,15 +11,24 @@ import type { RunState } from "../contracts/orchestration.js";
 import { type ContextCapsule } from './context-capsule.js';
 import type { ContextAdjustment } from "../evidence/attempt-record.js";
 import { type ContextBudgetReport } from "./context-budget-optimizer.js";
+import { type HeadroomDecision } from "./headroom-policy.js";
 export interface ContextBrokerOptions {
     readonly projectRoot?: string;
     readonly graphMemoryPath?: string;
     readonly goal?: string;
     readonly system?: string;
+    /**
+     * Model context window size in tokens. Used for headroom compaction
+     * threshold evaluation. Default: OMK_CONTEXT_WINDOW env or 200000.
+     */
+    readonly contextWindow?: number;
+}
+export interface ContextBrokerResult {
+    readonly capsule: ContextCapsule;
+    readonly report: ContextBudgetReport;
+    /** Headroom compaction decision — additive; existing consumers unaffected. */
+    readonly headroomDecision: HeadroomDecision;
 }
 export declare function createContextBroker(options?: ContextBrokerOptions): {
-    buildCapsule: (node: DagNode, state?: RunState, adjustment?: ContextAdjustment) => Promise<{
-        capsule: ContextCapsule;
-        report: ContextBudgetReport;
-    }>;
+    buildCapsule: (node: DagNode, state?: RunState, adjustment?: ContextAdjustment) => Promise<ContextBrokerResult>;
 };

package/dist/runtime/context-broker.js

@@ -4,6 +4,8 @@ import { join } from "path";
 import { mkdir, readFile, stat, writeFile } from "fs/promises";
 import { createContextBudgetOptimizer } from "./context-budget-optimizer.js";
 import { createDecisionTraceStore } from "../evidence/decision-trace.js";
+import { evaluateHeadroom } from "./headroom-policy.js";
+const DEFAULT_CONTEXT_WINDOW = 200_000;
 function resolveBudget(node) {
     const preset = node.routing?.contextBudget ?? "small";
     return CONTEXT_BUDGET_PRESETS[preset] ?? DEFAULT_CONTEXT_BUDGET;
@@ -302,7 +304,18 @@ export function createContextBroker(options = {}) {
                 attemptId: `${node.id}__${attemptId}`,
             });
         }
-        return { capsule: optimized.capsule, report: optimized.report };
+        // Evaluate headroom compaction threshold (advisory only — never blocks)
+        const resolvedContextWindow = options.contextWindow
+            ?? Number(process.env.OMK_CONTEXT_WINDOW ?? DEFAULT_CONTEXT_WINDOW);
+        const headroomDecision = evaluateHeadroom({
+            usedTokens: optimized.report.totalTokensEstimated,
+            contextWindow: resolvedContextWindow,
+        });
+        return {
+            capsule: optimized.capsule,
+            report: optimized.report,
+            headroomDecision,
+        };
     }
     return { buildCapsule };
 }