open-multi-agent-kit 0.78.7 → 0.79.1

package/dist/core/adaptive-runtime.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Adaptive runtime algorithms for the OMK hardfork.
+ *
+ * This module hosts pure, side-effect-free helpers that drive adaptive behaviour:
+ * - Headroom thresholds (when to compact / hand off before the context limit).
+ * - Topology routing (classify a task DAG into an execution topology).
+ * - Ouroboros preference detection (presence-only, never throws, no secret reads).
+ * - First-run adaptive plan generation (JSON-serializable artifact).
+ *
+ * The only non-pure helper is `writeFirstRunAdaptivePlan`, which performs an
+ * idempotent, non-fatal filesystem write of the generated plan. It is kept here
+ * so the behaviour stays unit-testable.
+ */
+/** Minimal environment shape consumed by adaptive helpers. */
+export type AdaptiveEnv = Record<string, string | undefined>;
+/** Directed edge in a task DAG. */
+export interface AdaptiveEdge {
+    from: string;
+    to: string;
+}
+export declare const DEFAULT_HEADROOM_THRESHOLD = 0.9;
+export declare const MIN_HEADROOM_THRESHOLD = 0.5;
+export declare const MAX_HEADROOM_THRESHOLD = 0.99;
+/** Whether the adaptive headroom feature is explicitly disabled via OMK_HEADROOM. */
+export declare function isHeadroomDisabled(env?: AdaptiveEnv): boolean;
+/**
+ * Resolve the adaptive headroom utilization threshold.
+ *
+ * - Default 0.90.
+ * - `OMK_HEADROOM_THRESHOLD` overrides (accepts a fraction `0.9` or percentage `90`).
+ * - Clamped to [0.5, 0.99].
+ * - Returns `0` when disabled via `OMK_HEADROOM=off|0|false|no`.
+ */
+export declare function resolveAdaptiveHeadroomThreshold(env?: AdaptiveEnv): number;
+/**
+ * Whether to invoke headroom (compact / hand off) before hitting the hard context limit.
+ * True only when the feature is enabled and utilization meets the resolved threshold.
+ */
+export declare function shouldUseHeadroomBeforeLimit(contextTokens: number, contextWindow: number, env?: AdaptiveEnv): boolean;
+export type AdaptiveTopology = "singleton" | "parallel" | "pipeline" | "map_reduce" | "hierarchical" | "dag" | "hybrid";
+export interface AdaptiveTopologyFeatures {
+    nodeCount: number;
+    edgeCount: number;
+    /** Maximum number of nodes in a single Kahn layer (parallel width). */
+    width: number;
+    /** Number of layers / longest dependency chain in node terms. */
+    criticalDepth: number;
+    /** Edges / possible edges (0 = fully parallel, 1 = fully sequential). */
+    couplingDensity: number;
+    /** width / nodeCount (inherent parallelism potential). */
+    parallelRatio: number;
+}
+export interface AdaptiveTopologyDecision {
+    topology: AdaptiveTopology;
+    features: AdaptiveTopologyFeatures;
+    /** Kahn layering; each entry is the set of node ids executable in that wave. */
+    waves: string[][];
+    reason: string;
+    hasCycle: boolean;
+}
+/**
+ * Compute structural features and an execution topology for a task DAG.
+ *
+ * Pure: uses Kahn layering with a cycle guard. Dangling edges (endpoints not in
+ * `nodes`) and duplicate edges are ignored; self loops mark the graph as cyclic.
+ */
+export declare function computeAdaptiveTopology(nodes: readonly string[], edges: readonly AdaptiveEdge[]): AdaptiveTopologyDecision;
+export type OuroborosMode = "always" | "auto" | "off";
+export interface OuroborosIndicators {
+    mcp: boolean;
+    skills: boolean;
+    binary: boolean;
+}
+export interface OuroborosPreference {
+    mode: OuroborosMode;
+    /** True when not off and at least one indicator is present. */
+    preferred: boolean;
+    /** True when any indicator is present (mcp/skills/binary). */
+    available: boolean;
+    fallback: "ouroboros" | "native";
+    indicators: OuroborosIndicators;
+    reason: string;
+}
+export interface OuroborosDetectionInput {
+    env?: AdaptiveEnv;
+    agentDir?: string;
+    cwd?: string;
+    home?: string;
+    /** Injectable existence check (defaults to fs.existsSync); used for the binary indicator. */
+    exists?: (path: string) => boolean;
+}
+/**
+ * Detect whether the Ouroboros runtime should be preferred.
+ *
+ * Presence-only: never throws, performs no secret reads. When indicators are
+ * absent the preference falls back to the native runtime.
+ */
+export declare function detectOuroborosPreference(input?: OuroborosDetectionInput): OuroborosPreference;
+export declare const ADAPTIVE_PLAN_VERSION = 1;
+export declare const DEFAULT_ADAPTIVE_RUNTIME = "omk-parallel-orchestrator";
+/** Startup DAG used to seed the first-run adaptive plan. */
+export declare const OMK_STARTUP_DAG_NODES: readonly string[];
+export declare const OMK_STARTUP_DAG_EDGES: readonly AdaptiveEdge[];
+export interface FirstRunAdaptivePlanInput {
+    nodes?: readonly string[];
+    edges?: readonly AdaptiveEdge[];
+    env?: AdaptiveEnv;
+    agentDir?: string;
+    cwd?: string;
+    home?: string;
+    runtime?: string;
+    /** Injectable clock (defaults to Date.now) for deterministic tests. */
+    now?: () => number;
+    exists?: (path: string) => boolean;
+}
+export interface FirstRunAdaptivePlan {
+    version: number;
+    runtime: string;
+    createdAt: string;
+    cwd: string | null;
+    topology: AdaptiveTopologyDecision;
+    headroom: {
+        enabled: boolean;
+        threshold: number;
+    };
+    ouroboros: OuroborosPreference;
+}
+/** Build a JSON-serializable first-run adaptive plan. Pure. */
+export declare function createFirstRunAdaptivePlan(input?: FirstRunAdaptivePlanInput): FirstRunAdaptivePlan;
+export interface WriteAdaptivePlanInput extends FirstRunAdaptivePlanInput {
+    agentDir: string;
+    /** Force rewrite even if the artifact already exists. */
+    refresh?: boolean;
+}
+export interface WriteAdaptivePlanResult {
+    path: string;
+    written: boolean;
+    plan?: FirstRunAdaptivePlan;
+    reason: "created" | "refreshed" | "exists" | "error";
+    error?: string;
+}
+/** Path of the first-run adaptive plan artifact. */
+export declare function getAdaptivePlanPath(agentDir: string): string;
+/**
+ * Idempotently write the first-run adaptive plan. Non-fatal: any error is
+ * captured in the result rather than thrown. Skips writing when the artifact
+ * already exists unless `refresh` (or `OMK_ADAPTIVE_PLAN_REFRESH=1`) is set.
+ */
+export declare function writeFirstRunAdaptivePlan(input: WriteAdaptivePlanInput): WriteAdaptivePlanResult;
+//# sourceMappingURL=adaptive-runtime.d.ts.map

package/dist/core/adaptive-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-runtime.d.ts","sourceRoot":"","sources":["../../src/core/adaptive-runtime.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Adaptive runtime algorithms for the OMK hardfork.\n *\n * This module hosts pure, side-effect-free helpers that drive adaptive behaviour:\n * - Headroom thresholds (when to compact / hand off before the context limit).\n * - Topology routing (classify a task DAG into an execution topology).\n * - Ouroboros preference detection (presence-only, never throws, no secret reads).\n * - First-run adaptive plan generation (JSON-serializable artifact).\n *\n * The only non-pure helper is `writeFirstRunAdaptivePlan`, which performs an\n * idempotent, non-fatal filesystem write of the generated plan. It is kept here\n * so the behaviour stays unit-testable.\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\n\n// ============================================================================\n// Shared types\n// ============================================================================\n\n/** Minimal environment shape consumed by adaptive helpers. */\nexport type AdaptiveEnv = Record<string, string | undefined>;\n\n/** Directed edge in a task DAG. */\nexport interface AdaptiveEdge {\n\tfrom: string;\n\tto: string;\n}\n\n// ============================================================================\n// Headroom thresholds\n// ============================================================================\n\nexport const DEFAULT_HEADROOM_THRESHOLD = 0.9;\nexport const MIN_HEADROOM_THRESHOLD = 0.5;\nexport const MAX_HEADROOM_THRESHOLD = 0.99;\n\nfunction normalizeFlag(value: string | undefined): string {\n\treturn value?.trim().toLowerCase() ?? \"\";\n}\n\n/** Whether the adaptive headroom feature is explicitly disabled via OMK_HEADROOM. */\nexport function isHeadroomDisabled(env: AdaptiveEnv = {}): boolean {\n\tconst raw = normalizeFlag(env.OMK_HEADROOM);\n\treturn raw === \"off\" || raw === \"0\" || raw === \"false\" || raw === \"no\";\n}\n\n/**\n * Resolve the adaptive headroom utilization threshold.\n *\n * - Default 0.90.\n * - `OMK_HEADROOM_THRESHOLD` overrides (accepts a fraction `0.9` or percentage `90`).\n * - Clamped to [0.5, 0.99].\n * - Returns `0` when disabled via `OMK_HEADROOM=off|0|false|no`.\n */\nexport function resolveAdaptiveHeadroomThreshold(env: AdaptiveEnv = {}): number {\n\tif (isHeadroomDisabled(env)) {\n\t\treturn 0;\n\t}\n\tlet threshold = DEFAULT_HEADROOM_THRESHOLD;\n\tconst raw = env.OMK_HEADROOM_THRESHOLD;\n\tif (raw !== undefined && raw.trim().length > 0) {\n\t\tconst parsed = Number.parseFloat(raw);\n\t\tif (Number.isFinite(parsed)) {\n\t\t\tthreshold = parsed > 1 ? parsed / 100 : parsed;\n\t\t}\n\t}\n\treturn Math.min(MAX_HEADROOM_THRESHOLD, Math.max(MIN_HEADROOM_THRESHOLD, threshold));\n}\n\n/**\n * Whether to invoke headroom (compact / hand off) before hitting the hard context limit.\n * True only when the feature is enabled and utilization meets the resolved threshold.\n */\nexport function shouldUseHeadroomBeforeLimit(\n\tcontextTokens: number,\n\tcontextWindow: number,\n\tenv: AdaptiveEnv = {},\n): boolean {\n\tconst threshold = resolveAdaptiveHeadroomThreshold(env);\n\tif (threshold <= 0) {\n\t\treturn false;\n\t}\n\tif (!Number.isFinite(contextWindow) || contextWindow <= 0) {\n\t\treturn false;\n\t}\n\tif (!Number.isFinite(contextTokens) || contextTokens < 0) {\n\t\treturn false;\n\t}\n\treturn contextTokens / contextWindow >= threshold;\n}\n\n// ============================================================================\n// Topology routing\n// ============================================================================\n\nexport type AdaptiveTopology = \"singleton\" | \"parallel\" | \"pipeline\" | \"map_reduce\" | \"hierarchical\" | \"dag\" | \"hybrid\";\n\nexport interface AdaptiveTopologyFeatures {\n\tnodeCount: number;\n\tedgeCount: number;\n\t/** Maximum number of nodes in a single Kahn layer (parallel width). */\n\twidth: number;\n\t/** Number of layers / longest dependency chain in node terms. */\n\tcriticalDepth: number;\n\t/** Edges / possible edges (0 = fully parallel, 1 = fully sequential). */\n\tcouplingDensity: number;\n\t/** width / nodeCount (inherent parallelism potential). */\n\tparallelRatio: number;\n}\n\nexport interface AdaptiveTopologyDecision {\n\ttopology: AdaptiveTopology;\n\tfeatures: AdaptiveTopologyFeatures;\n\t/** Kahn layering; each entry is the set of node ids executable in that wave. */\n\twaves: string[][];\n\treason: string;\n\thasCycle: boolean;\n}\n\n/** Routing thresholds for the OMK topology router. */\nconst THETA_OMEGA = 0.5; // parallel ratio above this -> parallel/map_reduce\nconst THETA_GAMMA = 0.6; // coupling density above this -> high coupling\nconst THETA_DELTA = 5; // node-count / depth threshold for hierarchical\n\ninterface GraphStats {\n\trootCount: number;\n\thasFanInSink: boolean;\n\thasFanOutRoot: boolean;\n\thasCycle: boolean;\n}\n\nfunction classifyTopology(\n\tfeatures: AdaptiveTopologyFeatures,\n\tstats: GraphStats,\n): { topology: AdaptiveTopology; reason: string } {\n\tconst { nodeCount, width, criticalDepth, couplingDensity, parallelRatio } = features;\n\n\tif (nodeCount === 0) {\n\t\treturn { topology: \"dag\", reason: \"empty DAG\" };\n\t}\n\tif (nodeCount === 1) {\n\t\treturn { topology: \"singleton\", reason: \"single node, no parallelism\" };\n\t}\n\tif (stats.hasCycle) {\n\t\treturn { topology: \"dag\", reason: \"cycle detected; treating as general DAG\" };\n\t}\n\n\tconst wide = parallelRatio >= THETA_OMEGA;\n\tconst highCoupling = couplingDensity >= THETA_GAMMA;\n\tconst deep = criticalDepth >= THETA_DELTA;\n\n\tif (width === 1) {\n\t\treturn { topology: \"pipeline\", reason: \"fully sequential chain (width 1)\" };\n\t}\n\tif (wide && highCoupling) {\n\t\treturn { topology: \"hybrid\", reason: \"high parallelism with high coupling (mixed signals)\" };\n\t}\n\tif (wide) {\n\t\tif (stats.rootCount <= 1 && stats.hasFanOutRoot && stats.hasFanInSink) {\n\t\t\treturn { topology: \"map_reduce\", reason: \"fan-out then fan-in with low coupling\" };\n\t\t}\n\t\treturn { topology: \"parallel\", reason: \"wide DAG with low coupling\" };\n\t}\n\tif (highCoupling) {\n\t\treturn { topology: \"pipeline\", reason: \"high coupling, sequential stages\" };\n\t}\n\tif (deep && nodeCount > THETA_DELTA) {\n\t\treturn { topology: \"hierarchical\", reason: \"deep, large dependency tree\" };\n\t}\n\treturn { topology: \"dag\", reason: \"general DAG with mixed parallelism\" };\n}\n\n/**\n * Compute structural features and an execution topology for a task DAG.\n *\n * Pure: uses Kahn layering with a cycle guard. Dangling edges (endpoints not in\n * `nodes`) and duplicate edges are ignored; self loops mark the graph as cyclic.\n */\nexport function computeAdaptiveTopology(\n\tnodes: readonly string[],\n\tedges: readonly AdaptiveEdge[],\n): AdaptiveTopologyDecision {\n\t// De-duplicate nodes while preserving input order for deterministic layering.\n\tconst orderedNodes: string[] = [];\n\tconst nodeSet = new Set<string>();\n\tfor (const node of nodes) {\n\t\tif (!nodeSet.has(node)) {\n\t\t\tnodeSet.add(node);\n\t\t\torderedNodes.push(node);\n\t\t}\n\t}\n\tconst indexOf = new Map<string, number>();\n\torderedNodes.forEach((node, index) => {\n\t\tindexOf.set(node, index);\n\t});\n\n\tconst adjacency = new Map<string, Set<string>>();\n\tconst inDegree = new Map<string, number>();\n\tconst outDegree = new Map<string, number>();\n\tfor (const node of orderedNodes) {\n\t\tadjacency.set(node, new Set());\n\t\tinDegree.set(node, 0);\n\t\toutDegree.set(node, 0);\n\t}\n\n\tlet edgeCount = 0;\n\tlet hasCycle = false;\n\tconst edgeSeen = new Set<string>();\n\tfor (const edge of edges) {\n\t\tif (!nodeSet.has(edge.from) || !nodeSet.has(edge.to)) {\n\t\t\tcontinue; // ignore dangling edges\n\t\t}\n\t\tif (edge.from === edge.to) {\n\t\t\thasCycle = true; // self loop\n\t\t\tcontinue;\n\t\t}\n\t\tconst key = `${edge.from}\\u0000${edge.to}`;\n\t\tif (edgeSeen.has(key)) {\n\t\t\tcontinue; // dedupe\n\t\t}\n\t\tedgeSeen.add(key);\n\t\tconst targets = adjacency.get(edge.from);\n\t\tif (targets && !targets.has(edge.to)) {\n\t\t\ttargets.add(edge.to);\n\t\t\tinDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);\n\t\t\toutDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1);\n\t\t\tedgeCount++;\n\t\t}\n\t}\n\n\t// Kahn layering.\n\tconst remaining = new Map(inDegree);\n\tlet frontier = orderedNodes.filter((node) => (remaining.get(node) ?? 0) === 0);\n\tconst waves: string[][] = [];\n\tlet processed = 0;\n\twhile (frontier.length > 0) {\n\t\tconst wave = [...frontier].sort((a, b) => (indexOf.get(a) ?? 0) - (indexOf.get(b) ?? 0));\n\t\twaves.push(wave);\n\t\tconst next: string[] = [];\n\t\tfor (const node of wave) {\n\t\t\tprocessed++;\n\t\t\tfor (const neighbor of adjacency.get(node) ?? []) {\n\t\t\t\tconst degree = (remaining.get(neighbor) ?? 0) - 1;\n\t\t\t\tremaining.set(neighbor, degree);\n\t\t\t\tif (degree === 0) {\n\t\t\t\t\tnext.push(neighbor);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tfrontier = next;\n\t}\n\n\tif (processed < orderedNodes.length) {\n\t\thasCycle = true;\n\t\tconst placed = new Set(waves.flat());\n\t\tconst leftover = orderedNodes.filter((node) => !placed.has(node));\n\t\tif (leftover.length > 0) {\n\t\t\twaves.push(leftover);\n\t\t}\n\t}\n\n\tconst nodeCount = orderedNodes.length;\n\tconst width = waves.reduce((max, wave) => Math.max(max, wave.length), 0);\n\tconst criticalDepth = waves.length;\n\tconst maxEdges = nodeCount > 1 ? (nodeCount * (nodeCount - 1)) / 2 : 0;\n\tconst couplingDensity = maxEdges > 0 ? Math.min(1, edgeCount / maxEdges) : 0;\n\tconst parallelRatio = nodeCount > 0 ? width / nodeCount : 0;\n\n\tconst features: AdaptiveTopologyFeatures = {\n\t\tnodeCount,\n\t\tedgeCount,\n\t\twidth,\n\t\tcriticalDepth,\n\t\tcouplingDensity,\n\t\tparallelRatio,\n\t};\n\n\tconst roots = orderedNodes.filter((node) => (inDegree.get(node) ?? 0) === 0);\n\tconst stats: GraphStats = {\n\t\trootCount: roots.length,\n\t\thasFanOutRoot: roots.some((node) => (outDegree.get(node) ?? 0) > 1),\n\t\thasFanInSink: orderedNodes.some((node) => (outDegree.get(node) ?? 0) === 0 && (inDegree.get(node) ?? 0) > 1),\n\t\thasCycle,\n\t};\n\n\tconst { topology, reason } = classifyTopology(features, stats);\n\treturn { topology, features, waves, reason, hasCycle };\n}\n\n// ============================================================================\n// Ouroboros preference detection\n// ============================================================================\n\nexport type OuroborosMode = \"always\" | \"auto\" | \"off\";\n\nexport interface OuroborosIndicators {\n\tmcp: boolean;\n\tskills: boolean;\n\tbinary: boolean;\n}\n\nexport interface OuroborosPreference {\n\tmode: OuroborosMode;\n\t/** True when not off and at least one indicator is present. */\n\tpreferred: boolean;\n\t/** True when any indicator is present (mcp/skills/binary). */\n\tavailable: boolean;\n\tfallback: \"ouroboros\" | \"native\";\n\tindicators: OuroborosIndicators;\n\treason: string;\n}\n\nexport interface OuroborosDetectionInput {\n\tenv?: AdaptiveEnv;\n\tagentDir?: string;\n\tcwd?: string;\n\thome?: string;\n\t/** Injectable existence check (defaults to fs.existsSync); used for the binary indicator. */\n\texists?: (path: string) => boolean;\n}\n\nfunction resolveOuroborosMode(env: AdaptiveEnv): OuroborosMode {\n\tconst raw = normalizeFlag(env.OMK_OUROBOROS);\n\tif (raw === \"off\" || raw === \"0\" || raw === \"false\" || raw === \"no\") {\n\t\treturn \"off\";\n\t}\n\tif (raw === \"auto\") {\n\t\treturn \"auto\";\n\t}\n\treturn \"always\"; // default, also \"always\" | \"1\" | \"true\" | \"on\" | unset\n}\n\nfunction safeExists(exists: (path: string) => boolean, path: string): boolean {\n\ttry {\n\t\treturn exists(path);\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction detectMcpIndicator(agentDir: string, exists: (path: string) => boolean): boolean {\n\tconst mcpPath = join(agentDir, \"mcp.json\");\n\tif (!safeExists(exists, mcpPath)) {\n\t\treturn false;\n\t}\n\ttry {\n\t\tconst parsed = JSON.parse(readFileSync(mcpPath, \"utf-8\")) as Record<string, unknown>;\n\t\tconst serversValue = parsed.mcpServers ?? parsed.servers ?? parsed;\n\t\tif (serversValue && typeof serversValue === \"object\") {\n\t\t\treturn Object.keys(serversValue as Record<string, unknown>).some((key) =>\n\t\t\t\tkey.toLowerCase().includes(\"ouroboros\"),\n\t\t\t);\n\t\t}\n\t\treturn false;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction detectSkillsIndicator(agentDir: string, exists: (path: string) => boolean): boolean {\n\tconst skillsDir = join(agentDir, \"skills\");\n\tif (!safeExists(exists, skillsDir)) {\n\t\treturn false;\n\t}\n\ttry {\n\t\treturn readdirSync(skillsDir).some((name) => name.toLowerCase().startsWith(\"ouroboros-\"));\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction detectBinaryIndicator(home: string, exists: (path: string) => boolean): boolean {\n\treturn safeExists(exists, join(home, \".local\", \"bin\", \"ouroboros\"));\n}\n\n/**\n * Detect whether the Ouroboros runtime should be preferred.\n *\n * Presence-only: never throws, performs no secret reads. When indicators are\n * absent the preference falls back to the native runtime.\n */\nexport function detectOuroborosPreference(input: OuroborosDetectionInput = {}): OuroborosPreference {\n\tconst env = input.env ?? {};\n\tconst exists = input.exists ?? existsSync;\n\tconst home = input.home ?? env.HOME ?? env.USERPROFILE ?? homedir();\n\tconst agentDir = input.agentDir;\n\n\tconst mode = resolveOuroborosMode(env);\n\n\tconst indicators: OuroborosIndicators = {\n\t\tmcp: agentDir ? detectMcpIndicator(agentDir, exists) : false,\n\t\tskills: agentDir ? detectSkillsIndicator(agentDir, exists) : false,\n\t\tbinary: detectBinaryIndicator(home, exists),\n\t};\n\n\tconst available = indicators.mcp || indicators.skills || indicators.binary;\n\tconst preferred = mode !== \"off\" && available;\n\tconst fallback: OuroborosPreference[\"fallback\"] = preferred ? \"ouroboros\" : \"native\";\n\n\tlet reason: string;\n\tif (mode === \"off\") {\n\t\treason = \"ouroboros disabled via OMK_OUROBOROS\";\n\t} else if (available) {\n\t\tconst present = [\n\t\t\tindicators.mcp ? \"mcp\" : undefined,\n\t\t\tindicators.skills ? \"skills\" : undefined,\n\t\t\tindicators.binary ? \"binary\" : undefined,\n\t\t].filter((value): value is string => value !== undefined);\n\t\treason = `ouroboros preferred (${present.join(\", \")})`;\n\t} else {\n\t\treason = \"ouroboros unavailable; falling back to native runtime\";\n\t}\n\n\treturn { mode, preferred, available, fallback, indicators, reason };\n}\n\n// ============================================================================\n// First-run adaptive plan\n// ============================================================================\n\nexport const ADAPTIVE_PLAN_VERSION = 1;\nexport const DEFAULT_ADAPTIVE_RUNTIME = \"omk-parallel-orchestrator\";\n\n/** Startup DAG used to seed the first-run adaptive plan. */\nexport const OMK_STARTUP_DAG_NODES: readonly string[] = [\n\t\"session_start\",\n\t\"resources_discover\",\n\t\"model_select\",\n\t\"run_loop\",\n];\n\nexport const OMK_STARTUP_DAG_EDGES: readonly AdaptiveEdge[] = [\n\t{ from: \"session_start\", to: \"resources_discover\" },\n\t{ from: \"resources_discover\", to: \"model_select\" },\n\t{ from: \"model_select\", to: \"run_loop\" },\n];\n\nexport interface FirstRunAdaptivePlanInput {\n\tnodes?: readonly string[];\n\tedges?: readonly AdaptiveEdge[];\n\tenv?: AdaptiveEnv;\n\tagentDir?: string;\n\tcwd?: string;\n\thome?: string;\n\truntime?: string;\n\t/** Injectable clock (defaults to Date.now) for deterministic tests. */\n\tnow?: () => number;\n\texists?: (path: string) => boolean;\n}\n\nexport interface FirstRunAdaptivePlan {\n\tversion: number;\n\truntime: string;\n\tcreatedAt: string;\n\tcwd: string | null;\n\ttopology: AdaptiveTopologyDecision;\n\theadroom: { enabled: boolean; threshold: number };\n\touroboros: OuroborosPreference;\n}\n\n/** Build a JSON-serializable first-run adaptive plan. Pure. */\nexport function createFirstRunAdaptivePlan(input: FirstRunAdaptivePlanInput = {}): FirstRunAdaptivePlan {\n\tconst env = input.env ?? {};\n\tconst now = input.now ?? Date.now;\n\tconst nodes = input.nodes ?? OMK_STARTUP_DAG_NODES;\n\tconst edges = input.edges ?? OMK_STARTUP_DAG_EDGES;\n\n\tconst topology = computeAdaptiveTopology(nodes, edges);\n\tconst threshold = resolveAdaptiveHeadroomThreshold(env);\n\tconst headroom = {\n\t\tenabled: threshold > 0,\n\t\tthreshold: threshold > 0 ? threshold : DEFAULT_HEADROOM_THRESHOLD,\n\t};\n\tconst ouroboros = detectOuroborosPreference({\n\t\tenv,\n\t\tagentDir: input.agentDir,\n\t\tcwd: input.cwd,\n\t\thome: input.home,\n\t\texists: input.exists,\n\t});\n\n\treturn {\n\t\tversion: ADAPTIVE_PLAN_VERSION,\n\t\truntime: input.runtime ?? DEFAULT_ADAPTIVE_RUNTIME,\n\t\tcreatedAt: new Date(now()).toISOString(),\n\t\tcwd: input.cwd ?? null,\n\t\ttopology,\n\t\theadroom,\n\t\touroboros,\n\t};\n}\n\nexport interface WriteAdaptivePlanInput extends FirstRunAdaptivePlanInput {\n\tagentDir: string;\n\t/** Force rewrite even if the artifact already exists. */\n\trefresh?: boolean;\n}\n\nexport interface WriteAdaptivePlanResult {\n\tpath: string;\n\twritten: boolean;\n\tplan?: FirstRunAdaptivePlan;\n\treason: \"created\" | \"refreshed\" | \"exists\" | \"error\";\n\terror?: string;\n}\n\n/** Path of the first-run adaptive plan artifact. */\nexport function getAdaptivePlanPath(agentDir: string): string {\n\treturn join(agentDir, \"runs\", \"adaptive-runtime-plan.json\");\n}\n\nfunction isTruthyFlag(value: string | undefined): boolean {\n\tconst raw = normalizeFlag(value);\n\treturn raw === \"1\" || raw === \"true\" || raw === \"yes\" || raw === \"on\";\n}\n\n/**\n * Idempotently write the first-run adaptive plan. Non-fatal: any error is\n * captured in the result rather than thrown. Skips writing when the artifact\n * already exists unless `refresh` (or `OMK_ADAPTIVE_PLAN_REFRESH=1`) is set.\n */\nexport function writeFirstRunAdaptivePlan(input: WriteAdaptivePlanInput): WriteAdaptivePlanResult {\n\tconst env = input.env ?? {};\n\tconst exists = input.exists ?? existsSync;\n\tconst path = getAdaptivePlanPath(input.agentDir);\n\tconst refresh = input.refresh ?? isTruthyFlag(env.OMK_ADAPTIVE_PLAN_REFRESH);\n\n\ttry {\n\t\tconst alreadyExists = safeExists(exists, path);\n\t\tif (alreadyExists && !refresh) {\n\t\t\treturn { path, written: false, reason: \"exists\" };\n\t\t}\n\t\tconst plan = createFirstRunAdaptivePlan(input);\n\t\tmkdirSync(dirname(path), { recursive: true });\n\t\twriteFileSync(path, `${JSON.stringify(plan, null, 2)}\\n`, \"utf-8\");\n\t\treturn { path, written: true, plan, reason: alreadyExists ? \"refreshed\" : \"created\" };\n\t} catch (error) {\n\t\treturn { path, written: false, reason: \"error\", error: error instanceof Error ? error.message : String(error) };\n\t}\n}\n"]}

package/dist/core/adaptive-runtime.js

@@ -0,0 +1,378 @@
+/**
+ * Adaptive runtime algorithms for the OMK hardfork.
+ *
+ * This module hosts pure, side-effect-free helpers that drive adaptive behaviour:
+ * - Headroom thresholds (when to compact / hand off before the context limit).
+ * - Topology routing (classify a task DAG into an execution topology).
+ * - Ouroboros preference detection (presence-only, never throws, no secret reads).
+ * - First-run adaptive plan generation (JSON-serializable artifact).
+ *
+ * The only non-pure helper is `writeFirstRunAdaptivePlan`, which performs an
+ * idempotent, non-fatal filesystem write of the generated plan. It is kept here
+ * so the behaviour stays unit-testable.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+// ============================================================================
+// Headroom thresholds
+// ============================================================================
+export const DEFAULT_HEADROOM_THRESHOLD = 0.9;
+export const MIN_HEADROOM_THRESHOLD = 0.5;
+export const MAX_HEADROOM_THRESHOLD = 0.99;
+function normalizeFlag(value) {
+    return value?.trim().toLowerCase() ?? "";
+}
+/** Whether the adaptive headroom feature is explicitly disabled via OMK_HEADROOM. */
+export function isHeadroomDisabled(env = {}) {
+    const raw = normalizeFlag(env.OMK_HEADROOM);
+    return raw === "off" || raw === "0" || raw === "false" || raw === "no";
+}
+/**
+ * Resolve the adaptive headroom utilization threshold.
+ *
+ * - Default 0.90.
+ * - `OMK_HEADROOM_THRESHOLD` overrides (accepts a fraction `0.9` or percentage `90`).
+ * - Clamped to [0.5, 0.99].
+ * - Returns `0` when disabled via `OMK_HEADROOM=off|0|false|no`.
+ */
+export function resolveAdaptiveHeadroomThreshold(env = {}) {
+    if (isHeadroomDisabled(env)) {
+        return 0;
+    }
+    let threshold = DEFAULT_HEADROOM_THRESHOLD;
+    const raw = env.OMK_HEADROOM_THRESHOLD;
+    if (raw !== undefined && raw.trim().length > 0) {
+        const parsed = Number.parseFloat(raw);
+        if (Number.isFinite(parsed)) {
+            threshold = parsed > 1 ? parsed / 100 : parsed;
+        }
+    }
+    return Math.min(MAX_HEADROOM_THRESHOLD, Math.max(MIN_HEADROOM_THRESHOLD, threshold));
+}
+/**
+ * Whether to invoke headroom (compact / hand off) before hitting the hard context limit.
+ * True only when the feature is enabled and utilization meets the resolved threshold.
+ */
+export function shouldUseHeadroomBeforeLimit(contextTokens, contextWindow, env = {}) {
+    const threshold = resolveAdaptiveHeadroomThreshold(env);
+    if (threshold <= 0) {
+        return false;
+    }
+    if (!Number.isFinite(contextWindow) || contextWindow <= 0) {
+        return false;
+    }
+    if (!Number.isFinite(contextTokens) || contextTokens < 0) {
+        return false;
+    }
+    return contextTokens / contextWindow >= threshold;
+}
+/** Routing thresholds for the OMK topology router. */
+const THETA_OMEGA = 0.5; // parallel ratio above this -> parallel/map_reduce
+const THETA_GAMMA = 0.6; // coupling density above this -> high coupling
+const THETA_DELTA = 5; // node-count / depth threshold for hierarchical
+function classifyTopology(features, stats) {
+    const { nodeCount, width, criticalDepth, couplingDensity, parallelRatio } = features;
+    if (nodeCount === 0) {
+        return { topology: "dag", reason: "empty DAG" };
+    }
+    if (nodeCount === 1) {
+        return { topology: "singleton", reason: "single node, no parallelism" };
+    }
+    if (stats.hasCycle) {
+        return { topology: "dag", reason: "cycle detected; treating as general DAG" };
+    }
+    const wide = parallelRatio >= THETA_OMEGA;
+    const highCoupling = couplingDensity >= THETA_GAMMA;
+    const deep = criticalDepth >= THETA_DELTA;
+    if (width === 1) {
+        return { topology: "pipeline", reason: "fully sequential chain (width 1)" };
+    }
+    if (wide && highCoupling) {
+        return { topology: "hybrid", reason: "high parallelism with high coupling (mixed signals)" };
+    }
+    if (wide) {
+        if (stats.rootCount <= 1 && stats.hasFanOutRoot && stats.hasFanInSink) {
+            return { topology: "map_reduce", reason: "fan-out then fan-in with low coupling" };
+        }
+        return { topology: "parallel", reason: "wide DAG with low coupling" };
+    }
+    if (highCoupling) {
+        return { topology: "pipeline", reason: "high coupling, sequential stages" };
+    }
+    if (deep && nodeCount > THETA_DELTA) {
+        return { topology: "hierarchical", reason: "deep, large dependency tree" };
+    }
+    return { topology: "dag", reason: "general DAG with mixed parallelism" };
+}
+/**
+ * Compute structural features and an execution topology for a task DAG.
+ *
+ * Pure: uses Kahn layering with a cycle guard. Dangling edges (endpoints not in
+ * `nodes`) and duplicate edges are ignored; self loops mark the graph as cyclic.
+ */
+export function computeAdaptiveTopology(nodes, edges) {
+    // De-duplicate nodes while preserving input order for deterministic layering.
+    const orderedNodes = [];
+    const nodeSet = new Set();
+    for (const node of nodes) {
+        if (!nodeSet.has(node)) {
+            nodeSet.add(node);
+            orderedNodes.push(node);
+        }
+    }
+    const indexOf = new Map();
+    orderedNodes.forEach((node, index) => {
+        indexOf.set(node, index);
+    });
+    const adjacency = new Map();
+    const inDegree = new Map();
+    const outDegree = new Map();
+    for (const node of orderedNodes) {
+        adjacency.set(node, new Set());
+        inDegree.set(node, 0);
+        outDegree.set(node, 0);
+    }
+    let edgeCount = 0;
+    let hasCycle = false;
+    const edgeSeen = new Set();
+    for (const edge of edges) {
+        if (!nodeSet.has(edge.from) || !nodeSet.has(edge.to)) {
+            continue; // ignore dangling edges
+        }
+        if (edge.from === edge.to) {
+            hasCycle = true; // self loop
+            continue;
+        }
+        const key = `${edge.from}\u0000${edge.to}`;
+        if (edgeSeen.has(key)) {
+            continue; // dedupe
+        }
+        edgeSeen.add(key);
+        const targets = adjacency.get(edge.from);
+        if (targets && !targets.has(edge.to)) {
+            targets.add(edge.to);
+            inDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);
+            outDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1);
+            edgeCount++;
+        }
+    }
+    // Kahn layering.
+    const remaining = new Map(inDegree);
+    let frontier = orderedNodes.filter((node) => (remaining.get(node) ?? 0) === 0);
+    const waves = [];
+    let processed = 0;
+    while (frontier.length > 0) {
+        const wave = [...frontier].sort((a, b) => (indexOf.get(a) ?? 0) - (indexOf.get(b) ?? 0));
+        waves.push(wave);
+        const next = [];
+        for (const node of wave) {
+            processed++;
+            for (const neighbor of adjacency.get(node) ?? []) {
+                const degree = (remaining.get(neighbor) ?? 0) - 1;
+                remaining.set(neighbor, degree);
+                if (degree === 0) {
+                    next.push(neighbor);
+                }
+            }
+        }
+        frontier = next;
+    }
+    if (processed < orderedNodes.length) {
+        hasCycle = true;
+        const placed = new Set(waves.flat());
+        const leftover = orderedNodes.filter((node) => !placed.has(node));
+        if (leftover.length > 0) {
+            waves.push(leftover);
+        }
+    }
+    const nodeCount = orderedNodes.length;
+    const width = waves.reduce((max, wave) => Math.max(max, wave.length), 0);
+    const criticalDepth = waves.length;
+    const maxEdges = nodeCount > 1 ? (nodeCount * (nodeCount - 1)) / 2 : 0;
+    const couplingDensity = maxEdges > 0 ? Math.min(1, edgeCount / maxEdges) : 0;
+    const parallelRatio = nodeCount > 0 ? width / nodeCount : 0;
+    const features = {
+        nodeCount,
+        edgeCount,
+        width,
+        criticalDepth,
+        couplingDensity,
+        parallelRatio,
+    };
+    const roots = orderedNodes.filter((node) => (inDegree.get(node) ?? 0) === 0);
+    const stats = {
+        rootCount: roots.length,
+        hasFanOutRoot: roots.some((node) => (outDegree.get(node) ?? 0) > 1),
+        hasFanInSink: orderedNodes.some((node) => (outDegree.get(node) ?? 0) === 0 && (inDegree.get(node) ?? 0) > 1),
+        hasCycle,
+    };
+    const { topology, reason } = classifyTopology(features, stats);
+    return { topology, features, waves, reason, hasCycle };
+}
+function resolveOuroborosMode(env) {
+    const raw = normalizeFlag(env.OMK_OUROBOROS);
+    if (raw === "off" || raw === "0" || raw === "false" || raw === "no") {
+        return "off";
+    }
+    if (raw === "auto") {
+        return "auto";
+    }
+    return "always"; // default, also "always" | "1" | "true" | "on" | unset
+}
+function safeExists(exists, path) {
+    try {
+        return exists(path);
+    }
+    catch {
+        return false;
+    }
+}
+function detectMcpIndicator(agentDir, exists) {
+    const mcpPath = join(agentDir, "mcp.json");
+    if (!safeExists(exists, mcpPath)) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(mcpPath, "utf-8"));
+        const serversValue = parsed.mcpServers ?? parsed.servers ?? parsed;
+        if (serversValue && typeof serversValue === "object") {
+            return Object.keys(serversValue).some((key) => key.toLowerCase().includes("ouroboros"));
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+function detectSkillsIndicator(agentDir, exists) {
+    const skillsDir = join(agentDir, "skills");
+    if (!safeExists(exists, skillsDir)) {
+        return false;
+    }
+    try {
+        return readdirSync(skillsDir).some((name) => name.toLowerCase().startsWith("ouroboros-"));
+    }
+    catch {
+        return false;
+    }
+}
+function detectBinaryIndicator(home, exists) {
+    return safeExists(exists, join(home, ".local", "bin", "ouroboros"));
+}
+/**
+ * Detect whether the Ouroboros runtime should be preferred.
+ *
+ * Presence-only: never throws, performs no secret reads. When indicators are
+ * absent the preference falls back to the native runtime.
+ */
+export function detectOuroborosPreference(input = {}) {
+    const env = input.env ?? {};
+    const exists = input.exists ?? existsSync;
+    const home = input.home ?? env.HOME ?? env.USERPROFILE ?? homedir();
+    const agentDir = input.agentDir;
+    const mode = resolveOuroborosMode(env);
+    const indicators = {
+        mcp: agentDir ? detectMcpIndicator(agentDir, exists) : false,
+        skills: agentDir ? detectSkillsIndicator(agentDir, exists) : false,
+        binary: detectBinaryIndicator(home, exists),
+    };
+    const available = indicators.mcp || indicators.skills || indicators.binary;
+    const preferred = mode !== "off" && available;
+    const fallback = preferred ? "ouroboros" : "native";
+    let reason;
+    if (mode === "off") {
+        reason = "ouroboros disabled via OMK_OUROBOROS";
+    }
+    else if (available) {
+        const present = [
+            indicators.mcp ? "mcp" : undefined,
+            indicators.skills ? "skills" : undefined,
+            indicators.binary ? "binary" : undefined,
+        ].filter((value) => value !== undefined);
+        reason = `ouroboros preferred (${present.join(", ")})`;
+    }
+    else {
+        reason = "ouroboros unavailable; falling back to native runtime";
+    }
+    return { mode, preferred, available, fallback, indicators, reason };
+}
+// ============================================================================
+// First-run adaptive plan
+// ============================================================================
+export const ADAPTIVE_PLAN_VERSION = 1;
+export const DEFAULT_ADAPTIVE_RUNTIME = "omk-parallel-orchestrator";
+/** Startup DAG used to seed the first-run adaptive plan. */
+export const OMK_STARTUP_DAG_NODES = [
+    "session_start",
+    "resources_discover",
+    "model_select",
+    "run_loop",
+];
+export const OMK_STARTUP_DAG_EDGES = [
+    { from: "session_start", to: "resources_discover" },
+    { from: "resources_discover", to: "model_select" },
+    { from: "model_select", to: "run_loop" },
+];
+/** Build a JSON-serializable first-run adaptive plan. Pure. */
+export function createFirstRunAdaptivePlan(input = {}) {
+    const env = input.env ?? {};
+    const now = input.now ?? Date.now;
+    const nodes = input.nodes ?? OMK_STARTUP_DAG_NODES;
+    const edges = input.edges ?? OMK_STARTUP_DAG_EDGES;
+    const topology = computeAdaptiveTopology(nodes, edges);
+    const threshold = resolveAdaptiveHeadroomThreshold(env);
+    const headroom = {
+        enabled: threshold > 0,
+        threshold: threshold > 0 ? threshold : DEFAULT_HEADROOM_THRESHOLD,
+    };
+    const ouroboros = detectOuroborosPreference({
+        env,
+        agentDir: input.agentDir,
+        cwd: input.cwd,
+        home: input.home,
+        exists: input.exists,
+    });
+    return {
+        version: ADAPTIVE_PLAN_VERSION,
+        runtime: input.runtime ?? DEFAULT_ADAPTIVE_RUNTIME,
+        createdAt: new Date(now()).toISOString(),
+        cwd: input.cwd ?? null,
+        topology,
+        headroom,
+        ouroboros,
+    };
+}
+/** Path of the first-run adaptive plan artifact. */
+export function getAdaptivePlanPath(agentDir) {
+    return join(agentDir, "runs", "adaptive-runtime-plan.json");
+}
+function isTruthyFlag(value) {
+    const raw = normalizeFlag(value);
+    return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
+/**
+ * Idempotently write the first-run adaptive plan. Non-fatal: any error is
+ * captured in the result rather than thrown. Skips writing when the artifact
+ * already exists unless `refresh` (or `OMK_ADAPTIVE_PLAN_REFRESH=1`) is set.
+ */
+export function writeFirstRunAdaptivePlan(input) {
+    const env = input.env ?? {};
+    const exists = input.exists ?? existsSync;
+    const path = getAdaptivePlanPath(input.agentDir);
+    const refresh = input.refresh ?? isTruthyFlag(env.OMK_ADAPTIVE_PLAN_REFRESH);
+    try {
+        const alreadyExists = safeExists(exists, path);
+        if (alreadyExists && !refresh) {
+            return { path, written: false, reason: "exists" };
+        }
+        const plan = createFirstRunAdaptivePlan(input);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(plan, null, 2)}\n`, "utf-8");
+        return { path, written: true, plan, reason: alreadyExists ? "refreshed" : "created" };
+    }
+    catch (error) {
+        return { path, written: false, reason: "error", error: error instanceof Error ? error.message : String(error) };
+    }
+}
+//# sourceMappingURL=adaptive-runtime.js.map

package/dist/core/adaptive-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adaptive-runtime.js","sourceRoot":"","sources":["../../src/core/adaptive-runtime.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Adaptive runtime algorithms for the OMK hardfork.\n *\n * This module hosts pure, side-effect-free helpers that drive adaptive behaviour:\n * - Headroom thresholds (when to compact / hand off before the context limit).\n * - Topology routing (classify a task DAG into an execution topology).\n * - Ouroboros preference detection (presence-only, never throws, no secret reads).\n * - First-run adaptive plan generation (JSON-serializable artifact).\n *\n * The only non-pure helper is `writeFirstRunAdaptivePlan`, which performs an\n * idempotent, non-fatal filesystem write of the generated plan. It is kept here\n * so the behaviour stays unit-testable.\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\n\n// ============================================================================\n// Shared types\n// ============================================================================\n\n/** Minimal environment shape consumed by adaptive helpers. */\nexport type AdaptiveEnv = Record<string, string | undefined>;\n\n/** Directed edge in a task DAG. */\nexport interface AdaptiveEdge {\n\tfrom: string;\n\tto: string;\n}\n\n// ============================================================================\n// Headroom thresholds\n// ============================================================================\n\nexport const DEFAULT_HEADROOM_THRESHOLD = 0.9;\nexport const MIN_HEADROOM_THRESHOLD = 0.5;\nexport const MAX_HEADROOM_THRESHOLD = 0.99;\n\nfunction normalizeFlag(value: string | undefined): string {\n\treturn value?.trim().toLowerCase() ?? \"\";\n}\n\n/** Whether the adaptive headroom feature is explicitly disabled via OMK_HEADROOM. */\nexport function isHeadroomDisabled(env: AdaptiveEnv = {}): boolean {\n\tconst raw = normalizeFlag(env.OMK_HEADROOM);\n\treturn raw === \"off\" || raw === \"0\" || raw === \"false\" || raw === \"no\";\n}\n\n/**\n * Resolve the adaptive headroom utilization threshold.\n *\n * - Default 0.90.\n * - `OMK_HEADROOM_THRESHOLD` overrides (accepts a fraction `0.9` or percentage `90`).\n * - Clamped to [0.5, 0.99].\n * - Returns `0` when disabled via `OMK_HEADROOM=off|0|false|no`.\n */\nexport function resolveAdaptiveHeadroomThreshold(env: AdaptiveEnv = {}): number {\n\tif (isHeadroomDisabled(env)) {\n\t\treturn 0;\n\t}\n\tlet threshold = DEFAULT_HEADROOM_THRESHOLD;\n\tconst raw = env.OMK_HEADROOM_THRESHOLD;\n\tif (raw !== undefined && raw.trim().length > 0) {\n\t\tconst parsed = Number.parseFloat(raw);\n\t\tif (Number.isFinite(parsed)) {\n\t\t\tthreshold = parsed > 1 ? parsed / 100 : parsed;\n\t\t}\n\t}\n\treturn Math.min(MAX_HEADROOM_THRESHOLD, Math.max(MIN_HEADROOM_THRESHOLD, threshold));\n}\n\n/**\n * Whether to invoke headroom (compact / hand off) before hitting the hard context limit.\n * True only when the feature is enabled and utilization meets the resolved threshold.\n */\nexport function shouldUseHeadroomBeforeLimit(\n\tcontextTokens: number,\n\tcontextWindow: number,\n\tenv: AdaptiveEnv = {},\n): boolean {\n\tconst threshold = resolveAdaptiveHeadroomThreshold(env);\n\tif (threshold <= 0) {\n\t\treturn false;\n\t}\n\tif (!Number.isFinite(contextWindow) || contextWindow <= 0) {\n\t\treturn false;\n\t}\n\tif (!Number.isFinite(contextTokens) || contextTokens < 0) {\n\t\treturn false;\n\t}\n\treturn contextTokens / contextWindow >= threshold;\n}\n\n// ============================================================================\n// Topology routing\n// ============================================================================\n\nexport type AdaptiveTopology = \"singleton\" | \"parallel\" | \"pipeline\" | \"map_reduce\" | \"hierarchical\" | \"dag\" | \"hybrid\";\n\nexport interface AdaptiveTopologyFeatures {\n\tnodeCount: number;\n\tedgeCount: number;\n\t/** Maximum number of nodes in a single Kahn layer (parallel width). */\n\twidth: number;\n\t/** Number of layers / longest dependency chain in node terms. */\n\tcriticalDepth: number;\n\t/** Edges / possible edges (0 = fully parallel, 1 = fully sequential). */\n\tcouplingDensity: number;\n\t/** width / nodeCount (inherent parallelism potential). */\n\tparallelRatio: number;\n}\n\nexport interface AdaptiveTopologyDecision {\n\ttopology: AdaptiveTopology;\n\tfeatures: AdaptiveTopologyFeatures;\n\t/** Kahn layering; each entry is the set of node ids executable in that wave. */\n\twaves: string[][];\n\treason: string;\n\thasCycle: boolean;\n}\n\n/** Routing thresholds for the OMK topology router. */\nconst THETA_OMEGA = 0.5; // parallel ratio above this -> parallel/map_reduce\nconst THETA_GAMMA = 0.6; // coupling density above this -> high coupling\nconst THETA_DELTA = 5; // node-count / depth threshold for hierarchical\n\ninterface GraphStats {\n\trootCount: number;\n\thasFanInSink: boolean;\n\thasFanOutRoot: boolean;\n\thasCycle: boolean;\n}\n\nfunction classifyTopology(\n\tfeatures: AdaptiveTopologyFeatures,\n\tstats: GraphStats,\n): { topology: AdaptiveTopology; reason: string } {\n\tconst { nodeCount, width, criticalDepth, couplingDensity, parallelRatio } = features;\n\n\tif (nodeCount === 0) {\n\t\treturn { topology: \"dag\", reason: \"empty DAG\" };\n\t}\n\tif (nodeCount === 1) {\n\t\treturn { topology: \"singleton\", reason: \"single node, no parallelism\" };\n\t}\n\tif (stats.hasCycle) {\n\t\treturn { topology: \"dag\", reason: \"cycle detected; treating as general DAG\" };\n\t}\n\n\tconst wide = parallelRatio >= THETA_OMEGA;\n\tconst highCoupling = couplingDensity >= THETA_GAMMA;\n\tconst deep = criticalDepth >= THETA_DELTA;\n\n\tif (width === 1) {\n\t\treturn { topology: \"pipeline\", reason: \"fully sequential chain (width 1)\" };\n\t}\n\tif (wide && highCoupling) {\n\t\treturn { topology: \"hybrid\", reason: \"high parallelism with high coupling (mixed signals)\" };\n\t}\n\tif (wide) {\n\t\tif (stats.rootCount <= 1 && stats.hasFanOutRoot && stats.hasFanInSink) {\n\t\t\treturn { topology: \"map_reduce\", reason: \"fan-out then fan-in with low coupling\" };\n\t\t}\n\t\treturn { topology: \"parallel\", reason: \"wide DAG with low coupling\" };\n\t}\n\tif (highCoupling) {\n\t\treturn { topology: \"pipeline\", reason: \"high coupling, sequential stages\" };\n\t}\n\tif (deep && nodeCount > THETA_DELTA) {\n\t\treturn { topology: \"hierarchical\", reason: \"deep, large dependency tree\" };\n\t}\n\treturn { topology: \"dag\", reason: \"general DAG with mixed parallelism\" };\n}\n\n/**\n * Compute structural features and an execution topology for a task DAG.\n *\n * Pure: uses Kahn layering with a cycle guard. Dangling edges (endpoints not in\n * `nodes`) and duplicate edges are ignored; self loops mark the graph as cyclic.\n */\nexport function computeAdaptiveTopology(\n\tnodes: readonly string[],\n\tedges: readonly AdaptiveEdge[],\n): AdaptiveTopologyDecision {\n\t// De-duplicate nodes while preserving input order for deterministic layering.\n\tconst orderedNodes: string[] = [];\n\tconst nodeSet = new Set<string>();\n\tfor (const node of nodes) {\n\t\tif (!nodeSet.has(node)) {\n\t\t\tnodeSet.add(node);\n\t\t\torderedNodes.push(node);\n\t\t}\n\t}\n\tconst indexOf = new Map<string, number>();\n\torderedNodes.forEach((node, index) => {\n\t\tindexOf.set(node, index);\n\t});\n\n\tconst adjacency = new Map<string, Set<string>>();\n\tconst inDegree = new Map<string, number>();\n\tconst outDegree = new Map<string, number>();\n\tfor (const node of orderedNodes) {\n\t\tadjacency.set(node, new Set());\n\t\tinDegree.set(node, 0);\n\t\toutDegree.set(node, 0);\n\t}\n\n\tlet edgeCount = 0;\n\tlet hasCycle = false;\n\tconst edgeSeen = new Set<string>();\n\tfor (const edge of edges) {\n\t\tif (!nodeSet.has(edge.from) || !nodeSet.has(edge.to)) {\n\t\t\tcontinue; // ignore dangling edges\n\t\t}\n\t\tif (edge.from === edge.to) {\n\t\t\thasCycle = true; // self loop\n\t\t\tcontinue;\n\t\t}\n\t\tconst key = `${edge.from}\\u0000${edge.to}`;\n\t\tif (edgeSeen.has(key)) {\n\t\t\tcontinue; // dedupe\n\t\t}\n\t\tedgeSeen.add(key);\n\t\tconst targets = adjacency.get(edge.from);\n\t\tif (targets && !targets.has(edge.to)) {\n\t\t\ttargets.add(edge.to);\n\t\t\tinDegree.set(edge.to, (inDegree.get(edge.to) ?? 0) + 1);\n\t\t\toutDegree.set(edge.from, (outDegree.get(edge.from) ?? 0) + 1);\n\t\t\tedgeCount++;\n\t\t}\n\t}\n\n\t// Kahn layering.\n\tconst remaining = new Map(inDegree);\n\tlet frontier = orderedNodes.filter((node) => (remaining.get(node) ?? 0) === 0);\n\tconst waves: string[][] = [];\n\tlet processed = 0;\n\twhile (frontier.length > 0) {\n\t\tconst wave = [...frontier].sort((a, b) => (indexOf.get(a) ?? 0) - (indexOf.get(b) ?? 0));\n\t\twaves.push(wave);\n\t\tconst next: string[] = [];\n\t\tfor (const node of wave) {\n\t\t\tprocessed++;\n\t\t\tfor (const neighbor of adjacency.get(node) ?? []) {\n\t\t\t\tconst degree = (remaining.get(neighbor) ?? 0) - 1;\n\t\t\t\tremaining.set(neighbor, degree);\n\t\t\t\tif (degree === 0) {\n\t\t\t\t\tnext.push(neighbor);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tfrontier = next;\n\t}\n\n\tif (processed < orderedNodes.length) {\n\t\thasCycle = true;\n\t\tconst placed = new Set(waves.flat());\n\t\tconst leftover = orderedNodes.filter((node) => !placed.has(node));\n\t\tif (leftover.length > 0) {\n\t\t\twaves.push(leftover);\n\t\t}\n\t}\n\n\tconst nodeCount = orderedNodes.length;\n\tconst width = waves.reduce((max, wave) => Math.max(max, wave.length), 0);\n\tconst criticalDepth = waves.length;\n\tconst maxEdges = nodeCount > 1 ? (nodeCount * (nodeCount - 1)) / 2 : 0;\n\tconst couplingDensity = maxEdges > 0 ? Math.min(1, edgeCount / maxEdges) : 0;\n\tconst parallelRatio = nodeCount > 0 ? width / nodeCount : 0;\n\n\tconst features: AdaptiveTopologyFeatures = {\n\t\tnodeCount,\n\t\tedgeCount,\n\t\twidth,\n\t\tcriticalDepth,\n\t\tcouplingDensity,\n\t\tparallelRatio,\n\t};\n\n\tconst roots = orderedNodes.filter((node) => (inDegree.get(node) ?? 0) === 0);\n\tconst stats: GraphStats = {\n\t\trootCount: roots.length,\n\t\thasFanOutRoot: roots.some((node) => (outDegree.get(node) ?? 0) > 1),\n\t\thasFanInSink: orderedNodes.some((node) => (outDegree.get(node) ?? 0) === 0 && (inDegree.get(node) ?? 0) > 1),\n\t\thasCycle,\n\t};\n\n\tconst { topology, reason } = classifyTopology(features, stats);\n\treturn { topology, features, waves, reason, hasCycle };\n}\n\n// ============================================================================\n// Ouroboros preference detection\n// ============================================================================\n\nexport type OuroborosMode = \"always\" | \"auto\" | \"off\";\n\nexport interface OuroborosIndicators {\n\tmcp: boolean;\n\tskills: boolean;\n\tbinary: boolean;\n}\n\nexport interface OuroborosPreference {\n\tmode: OuroborosMode;\n\t/** True when not off and at least one indicator is present. */\n\tpreferred: boolean;\n\t/** True when any indicator is present (mcp/skills/binary). */\n\tavailable: boolean;\n\tfallback: \"ouroboros\" | \"native\";\n\tindicators: OuroborosIndicators;\n\treason: string;\n}\n\nexport interface OuroborosDetectionInput {\n\tenv?: AdaptiveEnv;\n\tagentDir?: string;\n\tcwd?: string;\n\thome?: string;\n\t/** Injectable existence check (defaults to fs.existsSync); used for the binary indicator. */\n\texists?: (path: string) => boolean;\n}\n\nfunction resolveOuroborosMode(env: AdaptiveEnv): OuroborosMode {\n\tconst raw = normalizeFlag(env.OMK_OUROBOROS);\n\tif (raw === \"off\" || raw === \"0\" || raw === \"false\" || raw === \"no\") {\n\t\treturn \"off\";\n\t}\n\tif (raw === \"auto\") {\n\t\treturn \"auto\";\n\t}\n\treturn \"always\"; // default, also \"always\" | \"1\" | \"true\" | \"on\" | unset\n}\n\nfunction safeExists(exists: (path: string) => boolean, path: string): boolean {\n\ttry {\n\t\treturn exists(path);\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction detectMcpIndicator(agentDir: string, exists: (path: string) => boolean): boolean {\n\tconst mcpPath = join(agentDir, \"mcp.json\");\n\tif (!safeExists(exists, mcpPath)) {\n\t\treturn false;\n\t}\n\ttry {\n\t\tconst parsed = JSON.parse(readFileSync(mcpPath, \"utf-8\")) as Record<string, unknown>;\n\t\tconst serversValue = parsed.mcpServers ?? parsed.servers ?? parsed;\n\t\tif (serversValue && typeof serversValue === \"object\") {\n\t\t\treturn Object.keys(serversValue as Record<string, unknown>).some((key) =>\n\t\t\t\tkey.toLowerCase().includes(\"ouroboros\"),\n\t\t\t);\n\t\t}\n\t\treturn false;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction detectSkillsIndicator(agentDir: string, exists: (path: string) => boolean): boolean {\n\tconst skillsDir = join(agentDir, \"skills\");\n\tif (!safeExists(exists, skillsDir)) {\n\t\treturn false;\n\t}\n\ttry {\n\t\treturn readdirSync(skillsDir).some((name) => name.toLowerCase().startsWith(\"ouroboros-\"));\n\t} catch {\n\t\treturn false;\n\t}\n}\n\nfunction detectBinaryIndicator(home: string, exists: (path: string) => boolean): boolean {\n\treturn safeExists(exists, join(home, \".local\", \"bin\", \"ouroboros\"));\n}\n\n/**\n * Detect whether the Ouroboros runtime should be preferred.\n *\n * Presence-only: never throws, performs no secret reads. When indicators are\n * absent the preference falls back to the native runtime.\n */\nexport function detectOuroborosPreference(input: OuroborosDetectionInput = {}): OuroborosPreference {\n\tconst env = input.env ?? {};\n\tconst exists = input.exists ?? existsSync;\n\tconst home = input.home ?? env.HOME ?? env.USERPROFILE ?? homedir();\n\tconst agentDir = input.agentDir;\n\n\tconst mode = resolveOuroborosMode(env);\n\n\tconst indicators: OuroborosIndicators = {\n\t\tmcp: agentDir ? detectMcpIndicator(agentDir, exists) : false,\n\t\tskills: agentDir ? detectSkillsIndicator(agentDir, exists) : false,\n\t\tbinary: detectBinaryIndicator(home, exists),\n\t};\n\n\tconst available = indicators.mcp || indicators.skills || indicators.binary;\n\tconst preferred = mode !== \"off\" && available;\n\tconst fallback: OuroborosPreference[\"fallback\"] = preferred ? \"ouroboros\" : \"native\";\n\n\tlet reason: string;\n\tif (mode === \"off\") {\n\t\treason = \"ouroboros disabled via OMK_OUROBOROS\";\n\t} else if (available) {\n\t\tconst present = [\n\t\t\tindicators.mcp ? \"mcp\" : undefined,\n\t\t\tindicators.skills ? \"skills\" : undefined,\n\t\t\tindicators.binary ? \"binary\" : undefined,\n\t\t].filter((value): value is string => value !== undefined);\n\t\treason = `ouroboros preferred (${present.join(\", \")})`;\n\t} else {\n\t\treason = \"ouroboros unavailable; falling back to native runtime\";\n\t}\n\n\treturn { mode, preferred, available, fallback, indicators, reason };\n}\n\n// ============================================================================\n// First-run adaptive plan\n// ============================================================================\n\nexport const ADAPTIVE_PLAN_VERSION = 1;\nexport const DEFAULT_ADAPTIVE_RUNTIME = \"omk-parallel-orchestrator\";\n\n/** Startup DAG used to seed the first-run adaptive plan. */\nexport const OMK_STARTUP_DAG_NODES: readonly string[] = [\n\t\"session_start\",\n\t\"resources_discover\",\n\t\"model_select\",\n\t\"run_loop\",\n];\n\nexport const OMK_STARTUP_DAG_EDGES: readonly AdaptiveEdge[] = [\n\t{ from: \"session_start\", to: \"resources_discover\" },\n\t{ from: \"resources_discover\", to: \"model_select\" },\n\t{ from: \"model_select\", to: \"run_loop\" },\n];\n\nexport interface FirstRunAdaptivePlanInput {\n\tnodes?: readonly string[];\n\tedges?: readonly AdaptiveEdge[];\n\tenv?: AdaptiveEnv;\n\tagentDir?: string;\n\tcwd?: string;\n\thome?: string;\n\truntime?: string;\n\t/** Injectable clock (defaults to Date.now) for deterministic tests. */\n\tnow?: () => number;\n\texists?: (path: string) => boolean;\n}\n\nexport interface FirstRunAdaptivePlan {\n\tversion: number;\n\truntime: string;\n\tcreatedAt: string;\n\tcwd: string | null;\n\ttopology: AdaptiveTopologyDecision;\n\theadroom: { enabled: boolean; threshold: number };\n\touroboros: OuroborosPreference;\n}\n\n/** Build a JSON-serializable first-run adaptive plan. Pure. */\nexport function createFirstRunAdaptivePlan(input: FirstRunAdaptivePlanInput = {}): FirstRunAdaptivePlan {\n\tconst env = input.env ?? {};\n\tconst now = input.now ?? Date.now;\n\tconst nodes = input.nodes ?? OMK_STARTUP_DAG_NODES;\n\tconst edges = input.edges ?? OMK_STARTUP_DAG_EDGES;\n\n\tconst topology = computeAdaptiveTopology(nodes, edges);\n\tconst threshold = resolveAdaptiveHeadroomThreshold(env);\n\tconst headroom = {\n\t\tenabled: threshold > 0,\n\t\tthreshold: threshold > 0 ? threshold : DEFAULT_HEADROOM_THRESHOLD,\n\t};\n\tconst ouroboros = detectOuroborosPreference({\n\t\tenv,\n\t\tagentDir: input.agentDir,\n\t\tcwd: input.cwd,\n\t\thome: input.home,\n\t\texists: input.exists,\n\t});\n\n\treturn {\n\t\tversion: ADAPTIVE_PLAN_VERSION,\n\t\truntime: input.runtime ?? DEFAULT_ADAPTIVE_RUNTIME,\n\t\tcreatedAt: new Date(now()).toISOString(),\n\t\tcwd: input.cwd ?? null,\n\t\ttopology,\n\t\theadroom,\n\t\touroboros,\n\t};\n}\n\nexport interface WriteAdaptivePlanInput extends FirstRunAdaptivePlanInput {\n\tagentDir: string;\n\t/** Force rewrite even if the artifact already exists. */\n\trefresh?: boolean;\n}\n\nexport interface WriteAdaptivePlanResult {\n\tpath: string;\n\twritten: boolean;\n\tplan?: FirstRunAdaptivePlan;\n\treason: \"created\" | \"refreshed\" | \"exists\" | \"error\";\n\terror?: string;\n}\n\n/** Path of the first-run adaptive plan artifact. */\nexport function getAdaptivePlanPath(agentDir: string): string {\n\treturn join(agentDir, \"runs\", \"adaptive-runtime-plan.json\");\n}\n\nfunction isTruthyFlag(value: string | undefined): boolean {\n\tconst raw = normalizeFlag(value);\n\treturn raw === \"1\" || raw === \"true\" || raw === \"yes\" || raw === \"on\";\n}\n\n/**\n * Idempotently write the first-run adaptive plan. Non-fatal: any error is\n * captured in the result rather than thrown. Skips writing when the artifact\n * already exists unless `refresh` (or `OMK_ADAPTIVE_PLAN_REFRESH=1`) is set.\n */\nexport function writeFirstRunAdaptivePlan(input: WriteAdaptivePlanInput): WriteAdaptivePlanResult {\n\tconst env = input.env ?? {};\n\tconst exists = input.exists ?? existsSync;\n\tconst path = getAdaptivePlanPath(input.agentDir);\n\tconst refresh = input.refresh ?? isTruthyFlag(env.OMK_ADAPTIVE_PLAN_REFRESH);\n\n\ttry {\n\t\tconst alreadyExists = safeExists(exists, path);\n\t\tif (alreadyExists && !refresh) {\n\t\t\treturn { path, written: false, reason: \"exists\" };\n\t\t}\n\t\tconst plan = createFirstRunAdaptivePlan(input);\n\t\tmkdirSync(dirname(path), { recursive: true });\n\t\twriteFileSync(path, `${JSON.stringify(plan, null, 2)}\\n`, \"utf-8\");\n\t\treturn { path, written: true, plan, reason: alreadyExists ? \"refreshed\" : \"created\" };\n\t} catch (error) {\n\t\treturn { path, written: false, reason: \"error\", error: error instanceof Error ? error.message : String(error) };\n\t}\n}\n"]}