open-multi-agent-kit 0.96.1 → 0.97.0

package/dist/core/resource-admission.js

@@ -0,0 +1,128 @@
+import { randomUUID } from "node:crypto";
+import { computeHostResourceSnapshotDigest, effectiveAvailableMemoryBytes, } from "./host-resource-snapshot.js";
+import { DEFAULT_RESOURCE_ADMISSION_CONFIG, DEFAULT_RESOURCE_ADMISSION_THRESHOLDS, } from "./resource-admission-config.js";
+export { DEFAULT_RESOURCE_ADMISSION_CAP_TABLE, DEFAULT_RESOURCE_ADMISSION_CONFIG, DEFAULT_RESOURCE_ADMISSION_THRESHOLDS, resolveResourceAdmissionConfig, validateResourceAdmissionConfig, } from "./resource-admission-config.js";
+/**
+ * Pure resource admission policy (OMK v0.97.x roadmap §6.6-§7, M1/PR1).
+ *
+ * This module maps an immutable {@link HostResourceSnapshot} to an immutable
+ * {@link ResourceAdmissionDecision}. It is deterministic (clock and id are
+ * injectable), side-effect free, and performs no scheduler wiring — the
+ * decision only becomes scheduler authority in later milestones (M2+).
+ *
+ * Policy invariants (verified by property tests, roadmap §23.2):
+ * - Monotonic degradation (§4.4): worse memory/disk/CPU never improves
+ *   pressure and never raises a cap.
+ * - Conservative unknown handling (§4.3): a known critical fact wins; a
+ *   missing key probe (memory, disk, heap) degrades to `constrained`; only a
+ *   fully healthy snapshot is `normal`.
+ * - CPU alone never produces `critical` (§6.7): CPU pressure throttles,
+ *   while memory/disk/heap may block heavy admission.
+ * - User cap precedence (§7.3): effective caps never exceed configured caps,
+ *   and `0 = unlimited` settings are limited to the admission cap.
+ */
+export const RESOURCE_ADMISSION_VERSION = 1;
+const MIB = 1024 * 1024;
+const MIN_CAP = 1;
+const PRESSURE_RANK = { normal: 0, constrained: 1, critical: 2 };
+const RANK_TO_PRESSURE = ["normal", "constrained", "critical"];
+/** §7 action mapping: allow at normal, throttle at constrained, defer heavy work at critical. */
+const ACTION_BY_PRESSURE = {
+    normal: "allow",
+    constrained: "throttle",
+    critical: "defer-heavy",
+};
+/** Total order for pressure levels: `normal` (0) < `constrained` (1) < `critical` (2). */
+export function resourcePressureRank(pressure) {
+    return PRESSURE_RANK[pressure];
+}
+/**
+ * Derive pressure and reason codes from a snapshot (§4.3, §6.6, §6.7).
+ * Pure and monotonic: strictly worse inputs never yield a better pressure.
+ */
+export function evaluateResourcePressure(snapshot, thresholds = DEFAULT_RESOURCE_ADMISSION_THRESHOLDS) {
+    const reasons = [];
+    let rank = PRESSURE_RANK.normal;
+    const escalate = (target, reason) => {
+        reasons.push(reason);
+        rank = Math.max(rank, PRESSURE_RANK[target]);
+    };
+    const memory = effectiveAvailableMemoryBytes(snapshot);
+    if (memory !== null) {
+        if (memory < thresholds.criticalAvailableMemoryMiB * MIB) {
+            escalate("critical", "resource.memory.critical");
+        }
+        else if (memory < thresholds.constrainedAvailableMemoryMiB * MIB) {
+            escalate("constrained", "resource.memory.low");
+        }
+    }
+    const disk = snapshot.workspaceAvailableBytes;
+    if (disk !== null) {
+        if (disk < thresholds.criticalDiskFreeMiB * MIB) {
+            escalate("critical", "resource.disk.critical");
+        }
+        else if (disk < thresholds.constrainedDiskFreeMiB * MIB) {
+            escalate("constrained", "resource.disk.low");
+        }
+    }
+    const heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;
+    if (heapRatio !== null) {
+        if (heapRatio >= thresholds.criticalHeapRatio) {
+            escalate("critical", "resource.heap.critical");
+        }
+        else if (heapRatio >= thresholds.constrainedHeapRatio) {
+            escalate("constrained", "resource.heap.high");
+        }
+    }
+    // §6.7: CPU pressure only throttles; it can never be critical on its own.
+    if (snapshot.systemCpuPercent !== null && snapshot.systemCpuPercent >= thresholds.busyCpuPercent) {
+        escalate("constrained", "resource.cpu.busy");
+    }
+    // §4.3 conservative unknown handling. Key probes are the heavy-admission
+    // authorities (memory, disk, heap); a missing one degrades to constrained.
+    if (memory === null || disk === null || heapRatio === null) {
+        escalate("constrained", "resource.probe.partial");
+    }
+    // §21: any probe timeout keeps the prompt going but never reports normal.
+    if (snapshot.diagnostics.some((code) => code.endsWith(".timeout"))) {
+        escalate("constrained", "resource.probe.timeout");
+    }
+    return { pressure: RANK_TO_PRESSURE[rank] ?? "critical", reasons };
+}
+/** Map a snapshot to an immutable admission decision (§7.1-§7.3). */
+export function decideResourceAdmission(input) {
+    const config = input.config ?? DEFAULT_RESOURCE_ADMISSION_CONFIG;
+    const { pressure, reasons } = evaluateResourcePressure(input.snapshot, config.thresholds);
+    const tier = config.caps[pressure];
+    return {
+        schemaVersion: RESOURCE_ADMISSION_VERSION,
+        decisionId: input.decisionId ?? `res-adm-${randomUUID()}`,
+        snapshotDigest: computeHostResourceSnapshotDigest(input.snapshot),
+        pressure,
+        action: ACTION_BY_PRESSURE[pressure],
+        maxToolConcurrency: effectiveCap(input.configuredCaps?.maxToolConcurrency, tier.maxToolConcurrency),
+        maxParallelLanes: effectiveCap(input.configuredCaps?.maxParallelLanes, tier.maxParallelLanes),
+        maxHeavyProcesses: effectiveCap(input.configuredCaps?.maxHeavyProcesses, tier.maxHeavyProcesses),
+        reasons,
+        decidedAt: input.decidedAt ?? new Date().toISOString(),
+    };
+}
+/** Bounded hint for the model (§6.2). Carries no raw host values. */
+export function toModelResourceBudgetHint(decision) {
+    return {
+        pressure: decision.pressure,
+        maxToolConcurrency: decision.maxToolConcurrency,
+        maxParallelLanes: decision.maxParallelLanes,
+        maxHeavyProcesses: decision.maxHeavyProcesses,
+        reasons: decision.reasons,
+    };
+}
+/** §7.3: `min(configured, admission)`, where configured `0`/absent means unlimited. */
+function effectiveCap(configured, admission) {
+    const admitted = Math.max(MIN_CAP, Math.floor(admission));
+    if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+        return admitted;
+    }
+    return Math.max(MIN_CAP, Math.min(Math.floor(configured), admitted));
+}
+//# sourceMappingURL=resource-admission.js.map

package/dist/core/resource-admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-admission.js","sourceRoot":"","sources":["../../src/core/resource-admission.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport {\n\tcomputeHostResourceSnapshotDigest,\n\teffectiveAvailableMemoryBytes,\n\ttype HostResourceSnapshot,\n} from \"./host-resource-snapshot.ts\";\nimport {\n\tDEFAULT_RESOURCE_ADMISSION_CONFIG,\n\tDEFAULT_RESOURCE_ADMISSION_THRESHOLDS,\n\ttype ResourceAdmissionConfig,\n\ttype ResourceAdmissionThresholds,\n} from \"./resource-admission-config.ts\";\n\nexport type {\n\tResolvedResourceAdmissionConfig,\n\tResourceAdmissionCapTable,\n\tResourceAdmissionConfig,\n\tResourceAdmissionConfigOverrides,\n\tResourceAdmissionThresholds,\n\tResourceGovernorMode,\n\tResourcePressureCaps,\n} from \"./resource-admission-config.ts\";\nexport {\n\tDEFAULT_RESOURCE_ADMISSION_CAP_TABLE,\n\tDEFAULT_RESOURCE_ADMISSION_CONFIG,\n\tDEFAULT_RESOURCE_ADMISSION_THRESHOLDS,\n\tresolveResourceAdmissionConfig,\n\tvalidateResourceAdmissionConfig,\n} from \"./resource-admission-config.ts\";\n\n/**\n * Pure resource admission policy (OMK v0.97.x roadmap §6.6-§7, M1/PR1).\n *\n * This module maps an immutable {@link HostResourceSnapshot} to an immutable\n * {@link ResourceAdmissionDecision}. It is deterministic (clock and id are\n * injectable), side-effect free, and performs no scheduler wiring — the\n * decision only becomes scheduler authority in later milestones (M2+).\n *\n * Policy invariants (verified by property tests, roadmap §23.2):\n * - Monotonic degradation (§4.4): worse memory/disk/CPU never improves\n *   pressure and never raises a cap.\n * - Conservative unknown handling (§4.3): a known critical fact wins; a\n *   missing key probe (memory, disk, heap) degrades to `constrained`; only a\n *   fully healthy snapshot is `normal`.\n * - CPU alone never produces `critical` (§6.7): CPU pressure throttles,\n *   while memory/disk/heap may block heavy admission.\n * - User cap precedence (§7.3): effective caps never exceed configured caps,\n *   and `0 = unlimited` settings are limited to the admission cap.\n */\n\nexport const RESOURCE_ADMISSION_VERSION = 1 as const;\n\nexport type ResourcePressure = \"normal\" | \"constrained\" | \"critical\";\n\nexport type ResourceAdmissionAction = \"allow\" | \"throttle\" | \"defer-heavy\";\n\nexport type ResourceReasonCode =\n\t| \"resource.memory.low\"\n\t| \"resource.memory.critical\"\n\t| \"resource.disk.low\"\n\t| \"resource.disk.critical\"\n\t| \"resource.cpu.busy\"\n\t| \"resource.heap.high\"\n\t| \"resource.heap.critical\"\n\t| \"resource.probe.partial\"\n\t| \"resource.probe.timeout\";\n\nexport interface ResourceAdmissionDecision {\n\treadonly schemaVersion: typeof RESOURCE_ADMISSION_VERSION;\n\treadonly decisionId: string;\n\treadonly snapshotDigest: string;\n\treadonly pressure: ResourcePressure;\n\treadonly action: ResourceAdmissionAction;\n\n\treadonly maxToolConcurrency: number;\n\treadonly maxParallelLanes: number;\n\treadonly maxHeavyProcesses: number;\n\n\treadonly reasons: readonly ResourceReasonCode[];\n\treadonly decidedAt: string;\n}\n\n/** Bounded model-facing hint (§6.2). Never expose the raw snapshot to the model. */\nexport interface ModelResourceBudgetHint {\n\treadonly pressure: ResourcePressure;\n\treadonly maxToolConcurrency: number;\n\treadonly maxParallelLanes: number;\n\treadonly maxHeavyProcesses: number;\n\treadonly reasons: readonly ResourceReasonCode[];\n}\n\nconst MIB = 1024 * 1024;\nconst MIN_CAP = 1;\nconst PRESSURE_RANK: Record<ResourcePressure, number> = { normal: 0, constrained: 1, critical: 2 };\nconst RANK_TO_PRESSURE: readonly ResourcePressure[] = [\"normal\", \"constrained\", \"critical\"];\n/** §7 action mapping: allow at normal, throttle at constrained, defer heavy work at critical. */\nconst ACTION_BY_PRESSURE: Record<ResourcePressure, ResourceAdmissionAction> = {\n\tnormal: \"allow\",\n\tconstrained: \"throttle\",\n\tcritical: \"defer-heavy\",\n};\n\n/** Total order for pressure levels: `normal` (0) < `constrained` (1) < `critical` (2). */\nexport function resourcePressureRank(pressure: ResourcePressure): number {\n\treturn PRESSURE_RANK[pressure];\n}\n\nexport interface ResourcePressureEvaluation {\n\treadonly pressure: ResourcePressure;\n\treadonly reasons: readonly ResourceReasonCode[];\n}\n\n/**\n * Derive pressure and reason codes from a snapshot (§4.3, §6.6, §6.7).\n * Pure and monotonic: strictly worse inputs never yield a better pressure.\n */\nexport function evaluateResourcePressure(\n\tsnapshot: HostResourceSnapshot,\n\tthresholds: ResourceAdmissionThresholds = DEFAULT_RESOURCE_ADMISSION_THRESHOLDS,\n): ResourcePressureEvaluation {\n\tconst reasons: ResourceReasonCode[] = [];\n\tlet rank = PRESSURE_RANK.normal;\n\tconst escalate = (target: ResourcePressure, reason: ResourceReasonCode): void => {\n\t\treasons.push(reason);\n\t\trank = Math.max(rank, PRESSURE_RANK[target]);\n\t};\n\n\tconst memory = effectiveAvailableMemoryBytes(snapshot);\n\tif (memory !== null) {\n\t\tif (memory < thresholds.criticalAvailableMemoryMiB * MIB) {\n\t\t\tescalate(\"critical\", \"resource.memory.critical\");\n\t\t} else if (memory < thresholds.constrainedAvailableMemoryMiB * MIB) {\n\t\t\tescalate(\"constrained\", \"resource.memory.low\");\n\t\t}\n\t}\n\n\tconst disk = snapshot.workspaceAvailableBytes;\n\tif (disk !== null) {\n\t\tif (disk < thresholds.criticalDiskFreeMiB * MIB) {\n\t\t\tescalate(\"critical\", \"resource.disk.critical\");\n\t\t} else if (disk < thresholds.constrainedDiskFreeMiB * MIB) {\n\t\t\tescalate(\"constrained\", \"resource.disk.low\");\n\t\t}\n\t}\n\n\tconst heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;\n\tif (heapRatio !== null) {\n\t\tif (heapRatio >= thresholds.criticalHeapRatio) {\n\t\t\tescalate(\"critical\", \"resource.heap.critical\");\n\t\t} else if (heapRatio >= thresholds.constrainedHeapRatio) {\n\t\t\tescalate(\"constrained\", \"resource.heap.high\");\n\t\t}\n\t}\n\n\t// §6.7: CPU pressure only throttles; it can never be critical on its own.\n\tif (snapshot.systemCpuPercent !== null && snapshot.systemCpuPercent >= thresholds.busyCpuPercent) {\n\t\tescalate(\"constrained\", \"resource.cpu.busy\");\n\t}\n\n\t// §4.3 conservative unknown handling. Key probes are the heavy-admission\n\t// authorities (memory, disk, heap); a missing one degrades to constrained.\n\tif (memory === null || disk === null || heapRatio === null) {\n\t\tescalate(\"constrained\", \"resource.probe.partial\");\n\t}\n\t// §21: any probe timeout keeps the prompt going but never reports normal.\n\tif (snapshot.diagnostics.some((code) => code.endsWith(\".timeout\"))) {\n\t\tescalate(\"constrained\", \"resource.probe.timeout\");\n\t}\n\n\treturn { pressure: RANK_TO_PRESSURE[rank] ?? \"critical\", reasons };\n}\n\n/**\n * Existing user settings that admission must never exceed (§7.3).\n * `0` or `undefined` means \"unlimited\" and is limited to the admission cap.\n */\nexport interface ConfiguredResourceCaps {\n\treadonly maxToolConcurrency?: number;\n\treadonly maxParallelLanes?: number;\n\treadonly maxHeavyProcesses?: number;\n}\n\nexport interface ResourceAdmissionInput {\n\treadonly snapshot: HostResourceSnapshot;\n\treadonly config?: ResourceAdmissionConfig;\n\treadonly configuredCaps?: ConfiguredResourceCaps;\n\t/** Injectable for deterministic tests; defaults to a UUID-based id. */\n\treadonly decisionId?: string;\n\t/** Injectable ISO timestamp; defaults to the current time. */\n\treadonly decidedAt?: string;\n}\n\n/** Map a snapshot to an immutable admission decision (§7.1-§7.3). */\nexport function decideResourceAdmission(input: ResourceAdmissionInput): ResourceAdmissionDecision {\n\tconst config = input.config ?? DEFAULT_RESOURCE_ADMISSION_CONFIG;\n\tconst { pressure, reasons } = evaluateResourcePressure(input.snapshot, config.thresholds);\n\tconst tier = config.caps[pressure];\n\treturn {\n\t\tschemaVersion: RESOURCE_ADMISSION_VERSION,\n\t\tdecisionId: input.decisionId ?? `res-adm-${randomUUID()}`,\n\t\tsnapshotDigest: computeHostResourceSnapshotDigest(input.snapshot),\n\t\tpressure,\n\t\taction: ACTION_BY_PRESSURE[pressure],\n\t\tmaxToolConcurrency: effectiveCap(input.configuredCaps?.maxToolConcurrency, tier.maxToolConcurrency),\n\t\tmaxParallelLanes: effectiveCap(input.configuredCaps?.maxParallelLanes, tier.maxParallelLanes),\n\t\tmaxHeavyProcesses: effectiveCap(input.configuredCaps?.maxHeavyProcesses, tier.maxHeavyProcesses),\n\t\treasons,\n\t\tdecidedAt: input.decidedAt ?? new Date().toISOString(),\n\t};\n}\n\n/** Bounded hint for the model (§6.2). Carries no raw host values. */\nexport function toModelResourceBudgetHint(decision: ResourceAdmissionDecision): ModelResourceBudgetHint {\n\treturn {\n\t\tpressure: decision.pressure,\n\t\tmaxToolConcurrency: decision.maxToolConcurrency,\n\t\tmaxParallelLanes: decision.maxParallelLanes,\n\t\tmaxHeavyProcesses: decision.maxHeavyProcesses,\n\t\treasons: decision.reasons,\n\t};\n}\n\n/** §7.3: `min(configured, admission)`, where configured `0`/absent means unlimited. */\nfunction effectiveCap(configured: number | undefined, admission: number): number {\n\tconst admitted = Math.max(MIN_CAP, Math.floor(admission));\n\tif (typeof configured !== \"number\" || !Number.isFinite(configured) || configured <= 0) {\n\t\treturn admitted;\n\t}\n\treturn Math.max(MIN_CAP, Math.min(Math.floor(configured), admitted));\n}\n"]}

package/dist/core/resource-governor-format.d.ts

@@ -0,0 +1,50 @@
+import type { HostResourceSnapshot } from "./host-resource-snapshot.ts";
+import type { ResourceAdmissionDecision, ResourceGovernorMode, ResourceReasonCode } from "./resource-admission.ts";
+import type { ResolvedResourceGovernorSettings } from "./resource-governor-settings.ts";
+/** Humanize reason codes for the §19.1 summary line ("memory low, CPU busy"). */
+export declare function describeResourceReasons(reasons: readonly ResourceReasonCode[]): string;
+/** §19.1 summary block shared by `/resource` and the doctor's human output. */
+export declare function formatResourceSummaryLines(mode: ResourceGovernorMode, decision: ResourceAdmissionDecision): string[];
+/**
+ * Verbose probe details for explicit local diagnostics only (§19.1 verbose,
+ * §11.3: raw values never enter tool results or model prompts).
+ */
+export declare function formatResourceProbeLines(snapshot: HostResourceSnapshot): string[];
+/** Policy view: mode, §6.7 thresholds, §7.2 caps, and §18.1 validation errors. */
+export declare function formatResourcePolicyLines(resolved: ResolvedResourceGovernorSettings): string[];
+/** Bounded JSON schema for `omk doctor resources --json` (§19.2). */
+export interface ResourceDoctorReport {
+    readonly schemaVersion: 1;
+    readonly command: "resource_doctor";
+    readonly mode: ResourceGovernorMode;
+    readonly pressure: ResourceAdmissionDecision["pressure"];
+    readonly action: ResourceAdmissionDecision["action"];
+    readonly caps: {
+        readonly maxToolConcurrency: number;
+        readonly maxParallelLanes: number;
+        readonly maxHeavyProcesses: number;
+    };
+    readonly reasons: readonly ResourceReasonCode[];
+    readonly probeDurationMs: number;
+    readonly snapshot: {
+        readonly environment: HostResourceSnapshot["environment"];
+        readonly logicalCpuCount: number;
+        readonly effectiveAvailableMemoryMiB: number | null;
+        readonly processAvailableMemoryMiB: number | null;
+        readonly constrainedMemoryMiB: number | null;
+        readonly hostFreeMemoryMiB: number | null;
+        readonly hostTotalMemoryMiB: number | null;
+        readonly workspaceAvailableMiB: number | null;
+        readonly heapUsedRatio: number | null;
+        readonly systemCpuPercent: number | null;
+        readonly diagnostics: readonly string[];
+    };
+    readonly settingsErrors: readonly string[];
+}
+export declare function buildResourceDoctorReport(input: {
+    readonly snapshot: HostResourceSnapshot;
+    readonly decision: ResourceAdmissionDecision;
+    readonly resolved: ResolvedResourceGovernorSettings;
+    readonly probeDurationMs: number;
+}): ResourceDoctorReport;
+//# sourceMappingURL=resource-governor-format.d.ts.map

package/dist/core/resource-governor-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor-format.d.ts","sourceRoot":"","sources":["../../src/core/resource-governor-format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAExE,OAAO,KAAK,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACnH,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,iCAAiC,CAAC;AAcxF,kFAAiF;AACjF,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,GAAG,MAAM,CAKtF;AAED,gFAA+E;AAC/E,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,oBAAoB,EAAE,QAAQ,EAAE,yBAAyB,GAAG,MAAM,EAAE,CAUpH;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,EAAE,CAiBjF;AAED,qFAAkF;AAClF,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,gCAAgC,GAAG,MAAM,EAAE,CAiB9F;AAED,sEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC,UAAU,CAAC,CAAC;IACzD,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IACrD,QAAQ,CAAC,IAAI,EAAE;QACd,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;QACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;KACnC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE;QAClB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC,aAAa,CAAC,CAAC;QAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;QACpD,QAAQ,CAAC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;QAClD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;QAC7C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3C,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;QACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QACzC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;KACxC,CAAC;IACF,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAChD,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CACjC,GAAG,oBAAoB,CA+BvB","sourcesContent":["import type { HostResourceSnapshot } from \"./host-resource-snapshot.ts\";\nimport { effectiveAvailableMemoryBytes } from \"./host-resource-snapshot.ts\";\nimport type { ResourceAdmissionDecision, ResourceGovernorMode, ResourceReasonCode } from \"./resource-admission.ts\";\nimport type { ResolvedResourceGovernorSettings } from \"./resource-governor-settings.ts\";\n\nconst REASON_LABELS: Record<ResourceReasonCode, string> = {\n\t\"resource.memory.low\": \"memory low\",\n\t\"resource.memory.critical\": \"memory critical\",\n\t\"resource.disk.low\": \"disk low\",\n\t\"resource.disk.critical\": \"disk critical\",\n\t\"resource.cpu.busy\": \"CPU busy\",\n\t\"resource.heap.high\": \"heap high\",\n\t\"resource.heap.critical\": \"heap critical\",\n\t\"resource.probe.partial\": \"partial probe\",\n\t\"resource.probe.timeout\": \"probe timeout\",\n};\n\n/** Humanize reason codes for the §19.1 summary line (\"memory low, CPU busy\"). */\nexport function describeResourceReasons(reasons: readonly ResourceReasonCode[]): string {\n\tif (reasons.length === 0) {\n\t\treturn \"none\";\n\t}\n\treturn reasons.map((reason) => REASON_LABELS[reason] ?? reason).join(\", \");\n}\n\n/** §19.1 summary block shared by `/resource` and the doctor's human output. */\nexport function formatResourceSummaryLines(mode: ResourceGovernorMode, decision: ResourceAdmissionDecision): string[] {\n\treturn [\n\t\t`mode: ${mode}`,\n\t\t`pressure: ${decision.pressure}`,\n\t\t`action: ${decision.action}`,\n\t\t`tool concurrency: ${decision.maxToolConcurrency}`,\n\t\t`subagent lanes: ${decision.maxParallelLanes}`,\n\t\t`heavy processes: ${decision.maxHeavyProcesses}`,\n\t\t`reasons: ${describeResourceReasons(decision.reasons)}`,\n\t];\n}\n\n/**\n * Verbose probe details for explicit local diagnostics only (§19.1 verbose,\n * §11.3: raw values never enter tool results or model prompts).\n */\nexport function formatResourceProbeLines(snapshot: HostResourceSnapshot): string[] {\n\tconst heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;\n\tconst lines = [\n\t\t`observed at: ${snapshot.observedAt}`,\n\t\t`environment: ${snapshot.environment} (${snapshot.platform}/${snapshot.arch}, ${snapshot.logicalCpuCount} CPUs)`,\n\t\t`effective available memory: ${formatMiB(effectiveAvailableMemoryBytes(snapshot))}`,\n\t\t`  process available: ${formatMiB(snapshot.processAvailableMemoryBytes)}`,\n\t\t`  constrained limit: ${formatMiB(snapshot.constrainedMemoryBytes)}`,\n\t\t`  host free: ${formatMiB(snapshot.hostFreeMemoryBytes)} of ${formatMiB(snapshot.hostTotalMemoryBytes)}`,\n\t\t`workspace disk available: ${formatMiB(snapshot.workspaceAvailableBytes)}`,\n\t\t`heap: ${formatMiB(snapshot.heapUsedBytes)} of ${formatMiB(snapshot.heapLimitBytes)}${heapRatio === null ? \"\" : ` (${(heapRatio * 100).toFixed(1)}%)`}`,\n\t\t`system CPU: ${snapshot.systemCpuPercent === null ? \"unknown\" : `${snapshot.systemCpuPercent.toFixed(1)}%`}`,\n\t];\n\tif (snapshot.diagnostics.length > 0) {\n\t\tlines.push(`diagnostics: ${snapshot.diagnostics.join(\", \")}`);\n\t}\n\treturn lines;\n}\n\n/** Policy view: mode, §6.7 thresholds, §7.2 caps, and §18.1 validation errors. */\nexport function formatResourcePolicyLines(resolved: ResolvedResourceGovernorSettings): string[] {\n\tconst { thresholds, caps } = resolved.admission;\n\tconst lines = [\n\t\t`mode: ${resolved.mode}`,\n\t\t`probe deadline: ${resolved.maxProbeMs ?? 300} ms, CPU sample: ${resolved.cpuSampleMs ?? 180} ms`,\n\t\t`memory MiB (constrained/critical): ${thresholds.constrainedAvailableMemoryMiB}/${thresholds.criticalAvailableMemoryMiB}`,\n\t\t`disk MiB (constrained/critical): ${thresholds.constrainedDiskFreeMiB}/${thresholds.criticalDiskFreeMiB}`,\n\t\t`heap ratio (constrained/critical): ${thresholds.constrainedHeapRatio}/${thresholds.criticalHeapRatio}`,\n\t\t`busy CPU percent: ${thresholds.busyCpuPercent}`,\n\t\t`caps normal: tools ${caps.normal.maxToolConcurrency}, lanes ${caps.normal.maxParallelLanes}, heavy ${caps.normal.maxHeavyProcesses}`,\n\t\t`caps constrained: tools ${caps.constrained.maxToolConcurrency}, lanes ${caps.constrained.maxParallelLanes}, heavy ${caps.constrained.maxHeavyProcesses}`,\n\t\t`caps critical: tools ${caps.critical.maxToolConcurrency}, lanes ${caps.critical.maxParallelLanes}, heavy ${caps.critical.maxHeavyProcesses}`,\n\t];\n\tfor (const error of resolved.errors) {\n\t\tlines.push(`error: ${error}`);\n\t}\n\treturn lines;\n}\n\n/** Bounded JSON schema for `omk doctor resources --json` (§19.2). */\nexport interface ResourceDoctorReport {\n\treadonly schemaVersion: 1;\n\treadonly command: \"resource_doctor\";\n\treadonly mode: ResourceGovernorMode;\n\treadonly pressure: ResourceAdmissionDecision[\"pressure\"];\n\treadonly action: ResourceAdmissionDecision[\"action\"];\n\treadonly caps: {\n\t\treadonly maxToolConcurrency: number;\n\t\treadonly maxParallelLanes: number;\n\t\treadonly maxHeavyProcesses: number;\n\t};\n\treadonly reasons: readonly ResourceReasonCode[];\n\treadonly probeDurationMs: number;\n\treadonly snapshot: {\n\t\treadonly environment: HostResourceSnapshot[\"environment\"];\n\t\treadonly logicalCpuCount: number;\n\t\treadonly effectiveAvailableMemoryMiB: number | null;\n\t\treadonly processAvailableMemoryMiB: number | null;\n\t\treadonly constrainedMemoryMiB: number | null;\n\t\treadonly hostFreeMemoryMiB: number | null;\n\t\treadonly hostTotalMemoryMiB: number | null;\n\t\treadonly workspaceAvailableMiB: number | null;\n\t\treadonly heapUsedRatio: number | null;\n\t\treadonly systemCpuPercent: number | null;\n\t\treadonly diagnostics: readonly string[];\n\t};\n\treadonly settingsErrors: readonly string[];\n}\n\nexport function buildResourceDoctorReport(input: {\n\treadonly snapshot: HostResourceSnapshot;\n\treadonly decision: ResourceAdmissionDecision;\n\treadonly resolved: ResolvedResourceGovernorSettings;\n\treadonly probeDurationMs: number;\n}): ResourceDoctorReport {\n\tconst { snapshot, decision, resolved } = input;\n\tconst heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;\n\treturn {\n\t\tschemaVersion: 1,\n\t\tcommand: \"resource_doctor\",\n\t\tmode: resolved.mode,\n\t\tpressure: decision.pressure,\n\t\taction: decision.action,\n\t\tcaps: {\n\t\t\tmaxToolConcurrency: decision.maxToolConcurrency,\n\t\t\tmaxParallelLanes: decision.maxParallelLanes,\n\t\t\tmaxHeavyProcesses: decision.maxHeavyProcesses,\n\t\t},\n\t\treasons: decision.reasons,\n\t\tprobeDurationMs: Math.round(input.probeDurationMs),\n\t\tsnapshot: {\n\t\t\tenvironment: snapshot.environment,\n\t\t\tlogicalCpuCount: snapshot.logicalCpuCount,\n\t\t\teffectiveAvailableMemoryMiB: toMiB(effectiveAvailableMemoryBytes(snapshot)),\n\t\t\tprocessAvailableMemoryMiB: toMiB(snapshot.processAvailableMemoryBytes),\n\t\t\tconstrainedMemoryMiB: toMiB(snapshot.constrainedMemoryBytes),\n\t\t\thostFreeMemoryMiB: toMiB(snapshot.hostFreeMemoryBytes),\n\t\t\thostTotalMemoryMiB: toMiB(snapshot.hostTotalMemoryBytes),\n\t\t\tworkspaceAvailableMiB: toMiB(snapshot.workspaceAvailableBytes),\n\t\t\theapUsedRatio: heapRatio === null ? null : Number(heapRatio.toFixed(4)),\n\t\t\tsystemCpuPercent: snapshot.systemCpuPercent,\n\t\t\tdiagnostics: snapshot.diagnostics,\n\t\t},\n\t\tsettingsErrors: resolved.errors,\n\t};\n}\n\nconst MIB = 1024 * 1024;\n\nfunction toMiB(bytes: number | null): number | null {\n\treturn bytes === null ? null : Math.round(bytes / MIB);\n}\n\nfunction formatMiB(bytes: number | null): string {\n\tconst mib = toMiB(bytes);\n\treturn mib === null ? \"unknown\" : `${mib.toLocaleString()} MiB`;\n}\n"]}

package/dist/core/resource-governor-format.js

@@ -0,0 +1,113 @@
+import { effectiveAvailableMemoryBytes } from "./host-resource-snapshot.js";
+const REASON_LABELS = {
+    "resource.memory.low": "memory low",
+    "resource.memory.critical": "memory critical",
+    "resource.disk.low": "disk low",
+    "resource.disk.critical": "disk critical",
+    "resource.cpu.busy": "CPU busy",
+    "resource.heap.high": "heap high",
+    "resource.heap.critical": "heap critical",
+    "resource.probe.partial": "partial probe",
+    "resource.probe.timeout": "probe timeout",
+};
+/** Humanize reason codes for the §19.1 summary line ("memory low, CPU busy"). */
+export function describeResourceReasons(reasons) {
+    if (reasons.length === 0) {
+        return "none";
+    }
+    return reasons.map((reason) => REASON_LABELS[reason] ?? reason).join(", ");
+}
+/** §19.1 summary block shared by `/resource` and the doctor's human output. */
+export function formatResourceSummaryLines(mode, decision) {
+    return [
+        `mode: ${mode}`,
+        `pressure: ${decision.pressure}`,
+        `action: ${decision.action}`,
+        `tool concurrency: ${decision.maxToolConcurrency}`,
+        `subagent lanes: ${decision.maxParallelLanes}`,
+        `heavy processes: ${decision.maxHeavyProcesses}`,
+        `reasons: ${describeResourceReasons(decision.reasons)}`,
+    ];
+}
+/**
+ * Verbose probe details for explicit local diagnostics only (§19.1 verbose,
+ * §11.3: raw values never enter tool results or model prompts).
+ */
+export function formatResourceProbeLines(snapshot) {
+    const heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;
+    const lines = [
+        `observed at: ${snapshot.observedAt}`,
+        `environment: ${snapshot.environment} (${snapshot.platform}/${snapshot.arch}, ${snapshot.logicalCpuCount} CPUs)`,
+        `effective available memory: ${formatMiB(effectiveAvailableMemoryBytes(snapshot))}`,
+        `  process available: ${formatMiB(snapshot.processAvailableMemoryBytes)}`,
+        `  constrained limit: ${formatMiB(snapshot.constrainedMemoryBytes)}`,
+        `  host free: ${formatMiB(snapshot.hostFreeMemoryBytes)} of ${formatMiB(snapshot.hostTotalMemoryBytes)}`,
+        `workspace disk available: ${formatMiB(snapshot.workspaceAvailableBytes)}`,
+        `heap: ${formatMiB(snapshot.heapUsedBytes)} of ${formatMiB(snapshot.heapLimitBytes)}${heapRatio === null ? "" : ` (${(heapRatio * 100).toFixed(1)}%)`}`,
+        `system CPU: ${snapshot.systemCpuPercent === null ? "unknown" : `${snapshot.systemCpuPercent.toFixed(1)}%`}`,
+    ];
+    if (snapshot.diagnostics.length > 0) {
+        lines.push(`diagnostics: ${snapshot.diagnostics.join(", ")}`);
+    }
+    return lines;
+}
+/** Policy view: mode, §6.7 thresholds, §7.2 caps, and §18.1 validation errors. */
+export function formatResourcePolicyLines(resolved) {
+    const { thresholds, caps } = resolved.admission;
+    const lines = [
+        `mode: ${resolved.mode}`,
+        `probe deadline: ${resolved.maxProbeMs ?? 300} ms, CPU sample: ${resolved.cpuSampleMs ?? 180} ms`,
+        `memory MiB (constrained/critical): ${thresholds.constrainedAvailableMemoryMiB}/${thresholds.criticalAvailableMemoryMiB}`,
+        `disk MiB (constrained/critical): ${thresholds.constrainedDiskFreeMiB}/${thresholds.criticalDiskFreeMiB}`,
+        `heap ratio (constrained/critical): ${thresholds.constrainedHeapRatio}/${thresholds.criticalHeapRatio}`,
+        `busy CPU percent: ${thresholds.busyCpuPercent}`,
+        `caps normal: tools ${caps.normal.maxToolConcurrency}, lanes ${caps.normal.maxParallelLanes}, heavy ${caps.normal.maxHeavyProcesses}`,
+        `caps constrained: tools ${caps.constrained.maxToolConcurrency}, lanes ${caps.constrained.maxParallelLanes}, heavy ${caps.constrained.maxHeavyProcesses}`,
+        `caps critical: tools ${caps.critical.maxToolConcurrency}, lanes ${caps.critical.maxParallelLanes}, heavy ${caps.critical.maxHeavyProcesses}`,
+    ];
+    for (const error of resolved.errors) {
+        lines.push(`error: ${error}`);
+    }
+    return lines;
+}
+export function buildResourceDoctorReport(input) {
+    const { snapshot, decision, resolved } = input;
+    const heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;
+    return {
+        schemaVersion: 1,
+        command: "resource_doctor",
+        mode: resolved.mode,
+        pressure: decision.pressure,
+        action: decision.action,
+        caps: {
+            maxToolConcurrency: decision.maxToolConcurrency,
+            maxParallelLanes: decision.maxParallelLanes,
+            maxHeavyProcesses: decision.maxHeavyProcesses,
+        },
+        reasons: decision.reasons,
+        probeDurationMs: Math.round(input.probeDurationMs),
+        snapshot: {
+            environment: snapshot.environment,
+            logicalCpuCount: snapshot.logicalCpuCount,
+            effectiveAvailableMemoryMiB: toMiB(effectiveAvailableMemoryBytes(snapshot)),
+            processAvailableMemoryMiB: toMiB(snapshot.processAvailableMemoryBytes),
+            constrainedMemoryMiB: toMiB(snapshot.constrainedMemoryBytes),
+            hostFreeMemoryMiB: toMiB(snapshot.hostFreeMemoryBytes),
+            hostTotalMemoryMiB: toMiB(snapshot.hostTotalMemoryBytes),
+            workspaceAvailableMiB: toMiB(snapshot.workspaceAvailableBytes),
+            heapUsedRatio: heapRatio === null ? null : Number(heapRatio.toFixed(4)),
+            systemCpuPercent: snapshot.systemCpuPercent,
+            diagnostics: snapshot.diagnostics,
+        },
+        settingsErrors: resolved.errors,
+    };
+}
+const MIB = 1024 * 1024;
+function toMiB(bytes) {
+    return bytes === null ? null : Math.round(bytes / MIB);
+}
+function formatMiB(bytes) {
+    const mib = toMiB(bytes);
+    return mib === null ? "unknown" : `${mib.toLocaleString()} MiB`;
+}
+//# sourceMappingURL=resource-governor-format.js.map

package/dist/core/resource-governor-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor-format.js","sourceRoot":"","sources":["../../src/core/resource-governor-format.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAI5E,MAAM,aAAa,GAAuC;IACzD,qBAAqB,EAAE,YAAY;IACnC,0BAA0B,EAAE,iBAAiB;IAC7C,mBAAmB,EAAE,UAAU;IAC/B,wBAAwB,EAAE,eAAe;IACzC,mBAAmB,EAAE,UAAU;IAC/B,oBAAoB,EAAE,WAAW;IACjC,wBAAwB,EAAE,eAAe;IACzC,wBAAwB,EAAE,eAAe;IACzC,wBAAwB,EAAE,eAAe;CACzC,CAAC;AAEF,kFAAiF;AACjF,MAAM,UAAU,uBAAuB,CAAC,OAAsC,EAAU;IACvF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,MAAM,CAAC;IACf,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAAA,CAC3E;AAED,gFAA+E;AAC/E,MAAM,UAAU,0BAA0B,CAAC,IAA0B,EAAE,QAAmC,EAAY;IACrH,OAAO;QACN,SAAS,IAAI,EAAE;QACf,aAAa,QAAQ,CAAC,QAAQ,EAAE;QAChC,WAAW,QAAQ,CAAC,MAAM,EAAE;QAC5B,qBAAqB,QAAQ,CAAC,kBAAkB,EAAE;QAClD,mBAAmB,QAAQ,CAAC,gBAAgB,EAAE;QAC9C,oBAAoB,QAAQ,CAAC,iBAAiB,EAAE;QAChD,YAAY,uBAAuB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;KACvD,CAAC;AAAA,CACF;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAA8B,EAAY;IAClF,MAAM,SAAS,GAAG,QAAQ,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;IACxG,MAAM,KAAK,GAAG;QACb,gBAAgB,QAAQ,CAAC,UAAU,EAAE;QACrC,gBAAgB,QAAQ,CAAC,WAAW,KAAK,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,eAAe,QAAQ;QAChH,+BAA+B,SAAS,CAAC,6BAA6B,CAAC,QAAQ,CAAC,CAAC,EAAE;QACnF,wBAAwB,SAAS,CAAC,QAAQ,CAAC,2BAA2B,CAAC,EAAE;QACzE,wBAAwB,SAAS,CAAC,QAAQ,CAAC,sBAAsB,CAAC,EAAE;QACpE,gBAAgB,SAAS,CAAC,QAAQ,CAAC,mBAAmB,CAAC,OAAO,SAAS,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAAE;QACxG,6BAA6B,SAAS,CAAC,QAAQ,CAAC,uBAAuB,CAAC,EAAE;QAC1E,SAAS,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,OAAO,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE;QACvJ,eAAe,QAAQ,CAAC,gBAAgB,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE;KAC5G,CAAC;IACF,IAAI,QAAQ,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,gBAAgB,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAED,qFAAkF;AAClF,MAAM,UAAU,yBAAyB,CAAC,QAA0C,EAAY;IAC/F,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC;IAChD,MAAM,KAAK,GAAG;QACb,SAAS,QAAQ,CAAC,IAAI,EAAE;QACxB,mBAAmB,QAAQ,CAAC,UAAU,IAAI,GAAG,oBAAoB,QAAQ,CAAC,WAAW,IAAI,GAAG,KAAK;QACjG,sCAAsC,UAAU,CAAC,6BAA6B,IAAI,UAAU,CAAC,0BAA0B,EAAE;QACzH,oCAAoC,UAAU,CAAC,sBAAsB,IAAI,UAAU,CAAC,mBAAmB,EAAE;QACzG,sCAAsC,UAAU,CAAC,oBAAoB,IAAI,UAAU,CAAC,iBAAiB,EAAE;QACvG,qBAAqB,UAAU,CAAC,cAAc,EAAE;QAChD,sBAAsB,IAAI,CAAC,MAAM,CAAC,kBAAkB,WAAW,IAAI,CAAC,MAAM,CAAC,gBAAgB,WAAW,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE;QACrI,2BAA2B,IAAI,CAAC,WAAW,CAAC,kBAAkB,WAAW,IAAI,CAAC,WAAW,CAAC,gBAAgB,WAAW,IAAI,CAAC,WAAW,CAAC,iBAAiB,EAAE;QACzJ,wBAAwB,IAAI,CAAC,QAAQ,CAAC,kBAAkB,WAAW,IAAI,CAAC,QAAQ,CAAC,gBAAgB,WAAW,IAAI,CAAC,QAAQ,CAAC,iBAAiB,EAAE;KAC7I,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACrC,KAAK,CAAC,IAAI,CAAC,UAAU,KAAK,EAAE,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAgCD,MAAM,UAAU,yBAAyB,CAAC,KAKzC,EAAwB;IACxB,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC/C,MAAM,SAAS,GAAG,QAAQ,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,aAAa,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;IACxG,OAAO;QACN,aAAa,EAAE,CAAC;QAChB,OAAO,EAAE,iBAAiB;QAC1B,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,IAAI,EAAE;YACL,kBAAkB,EAAE,QAAQ,CAAC,kBAAkB;YAC/C,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;YAC3C,iBAAiB,EAAE,QAAQ,CAAC,iBAAiB;SAC7C;QACD,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,eAAe,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,eAAe,CAAC;QAClD,QAAQ,EAAE;YACT,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,eAAe,EAAE,QAAQ,CAAC,eAAe;YACzC,2BAA2B,EAAE,KAAK,CAAC,6BAA6B,CAAC,QAAQ,CAAC,CAAC;YAC3E,yBAAyB,EAAE,KAAK,CAAC,QAAQ,CAAC,2BAA2B,CAAC;YACtE,oBAAoB,EAAE,KAAK,CAAC,QAAQ,CAAC,sBAAsB,CAAC;YAC5D,iBAAiB,EAAE,KAAK,CAAC,QAAQ,CAAC,mBAAmB,CAAC;YACtD,kBAAkB,EAAE,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC;YACxD,qBAAqB,EAAE,KAAK,CAAC,QAAQ,CAAC,uBAAuB,CAAC;YAC9D,aAAa,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YACvE,gBAAgB,EAAE,QAAQ,CAAC,gBAAgB;YAC3C,WAAW,EAAE,QAAQ,CAAC,WAAW;SACjC;QACD,cAAc,EAAE,QAAQ,CAAC,MAAM;KAC/B,CAAC;AAAA,CACF;AAED,MAAM,GAAG,GAAG,IAAI,GAAG,IAAI,CAAC;AAExB,SAAS,KAAK,CAAC,KAAoB,EAAiB;IACnD,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;AAAA,CACvD;AAED,SAAS,SAAS,CAAC,KAAoB,EAAU;IAChD,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;IACzB,OAAO,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC;AAAA,CAChE","sourcesContent":["import type { HostResourceSnapshot } from \"./host-resource-snapshot.ts\";\nimport { effectiveAvailableMemoryBytes } from \"./host-resource-snapshot.ts\";\nimport type { ResourceAdmissionDecision, ResourceGovernorMode, ResourceReasonCode } from \"./resource-admission.ts\";\nimport type { ResolvedResourceGovernorSettings } from \"./resource-governor-settings.ts\";\n\nconst REASON_LABELS: Record<ResourceReasonCode, string> = {\n\t\"resource.memory.low\": \"memory low\",\n\t\"resource.memory.critical\": \"memory critical\",\n\t\"resource.disk.low\": \"disk low\",\n\t\"resource.disk.critical\": \"disk critical\",\n\t\"resource.cpu.busy\": \"CPU busy\",\n\t\"resource.heap.high\": \"heap high\",\n\t\"resource.heap.critical\": \"heap critical\",\n\t\"resource.probe.partial\": \"partial probe\",\n\t\"resource.probe.timeout\": \"probe timeout\",\n};\n\n/** Humanize reason codes for the §19.1 summary line (\"memory low, CPU busy\"). */\nexport function describeResourceReasons(reasons: readonly ResourceReasonCode[]): string {\n\tif (reasons.length === 0) {\n\t\treturn \"none\";\n\t}\n\treturn reasons.map((reason) => REASON_LABELS[reason] ?? reason).join(\", \");\n}\n\n/** §19.1 summary block shared by `/resource` and the doctor's human output. */\nexport function formatResourceSummaryLines(mode: ResourceGovernorMode, decision: ResourceAdmissionDecision): string[] {\n\treturn [\n\t\t`mode: ${mode}`,\n\t\t`pressure: ${decision.pressure}`,\n\t\t`action: ${decision.action}`,\n\t\t`tool concurrency: ${decision.maxToolConcurrency}`,\n\t\t`subagent lanes: ${decision.maxParallelLanes}`,\n\t\t`heavy processes: ${decision.maxHeavyProcesses}`,\n\t\t`reasons: ${describeResourceReasons(decision.reasons)}`,\n\t];\n}\n\n/**\n * Verbose probe details for explicit local diagnostics only (§19.1 verbose,\n * §11.3: raw values never enter tool results or model prompts).\n */\nexport function formatResourceProbeLines(snapshot: HostResourceSnapshot): string[] {\n\tconst heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;\n\tconst lines = [\n\t\t`observed at: ${snapshot.observedAt}`,\n\t\t`environment: ${snapshot.environment} (${snapshot.platform}/${snapshot.arch}, ${snapshot.logicalCpuCount} CPUs)`,\n\t\t`effective available memory: ${formatMiB(effectiveAvailableMemoryBytes(snapshot))}`,\n\t\t`  process available: ${formatMiB(snapshot.processAvailableMemoryBytes)}`,\n\t\t`  constrained limit: ${formatMiB(snapshot.constrainedMemoryBytes)}`,\n\t\t`  host free: ${formatMiB(snapshot.hostFreeMemoryBytes)} of ${formatMiB(snapshot.hostTotalMemoryBytes)}`,\n\t\t`workspace disk available: ${formatMiB(snapshot.workspaceAvailableBytes)}`,\n\t\t`heap: ${formatMiB(snapshot.heapUsedBytes)} of ${formatMiB(snapshot.heapLimitBytes)}${heapRatio === null ? \"\" : ` (${(heapRatio * 100).toFixed(1)}%)`}`,\n\t\t`system CPU: ${snapshot.systemCpuPercent === null ? \"unknown\" : `${snapshot.systemCpuPercent.toFixed(1)}%`}`,\n\t];\n\tif (snapshot.diagnostics.length > 0) {\n\t\tlines.push(`diagnostics: ${snapshot.diagnostics.join(\", \")}`);\n\t}\n\treturn lines;\n}\n\n/** Policy view: mode, §6.7 thresholds, §7.2 caps, and §18.1 validation errors. */\nexport function formatResourcePolicyLines(resolved: ResolvedResourceGovernorSettings): string[] {\n\tconst { thresholds, caps } = resolved.admission;\n\tconst lines = [\n\t\t`mode: ${resolved.mode}`,\n\t\t`probe deadline: ${resolved.maxProbeMs ?? 300} ms, CPU sample: ${resolved.cpuSampleMs ?? 180} ms`,\n\t\t`memory MiB (constrained/critical): ${thresholds.constrainedAvailableMemoryMiB}/${thresholds.criticalAvailableMemoryMiB}`,\n\t\t`disk MiB (constrained/critical): ${thresholds.constrainedDiskFreeMiB}/${thresholds.criticalDiskFreeMiB}`,\n\t\t`heap ratio (constrained/critical): ${thresholds.constrainedHeapRatio}/${thresholds.criticalHeapRatio}`,\n\t\t`busy CPU percent: ${thresholds.busyCpuPercent}`,\n\t\t`caps normal: tools ${caps.normal.maxToolConcurrency}, lanes ${caps.normal.maxParallelLanes}, heavy ${caps.normal.maxHeavyProcesses}`,\n\t\t`caps constrained: tools ${caps.constrained.maxToolConcurrency}, lanes ${caps.constrained.maxParallelLanes}, heavy ${caps.constrained.maxHeavyProcesses}`,\n\t\t`caps critical: tools ${caps.critical.maxToolConcurrency}, lanes ${caps.critical.maxParallelLanes}, heavy ${caps.critical.maxHeavyProcesses}`,\n\t];\n\tfor (const error of resolved.errors) {\n\t\tlines.push(`error: ${error}`);\n\t}\n\treturn lines;\n}\n\n/** Bounded JSON schema for `omk doctor resources --json` (§19.2). */\nexport interface ResourceDoctorReport {\n\treadonly schemaVersion: 1;\n\treadonly command: \"resource_doctor\";\n\treadonly mode: ResourceGovernorMode;\n\treadonly pressure: ResourceAdmissionDecision[\"pressure\"];\n\treadonly action: ResourceAdmissionDecision[\"action\"];\n\treadonly caps: {\n\t\treadonly maxToolConcurrency: number;\n\t\treadonly maxParallelLanes: number;\n\t\treadonly maxHeavyProcesses: number;\n\t};\n\treadonly reasons: readonly ResourceReasonCode[];\n\treadonly probeDurationMs: number;\n\treadonly snapshot: {\n\t\treadonly environment: HostResourceSnapshot[\"environment\"];\n\t\treadonly logicalCpuCount: number;\n\t\treadonly effectiveAvailableMemoryMiB: number | null;\n\t\treadonly processAvailableMemoryMiB: number | null;\n\t\treadonly constrainedMemoryMiB: number | null;\n\t\treadonly hostFreeMemoryMiB: number | null;\n\t\treadonly hostTotalMemoryMiB: number | null;\n\t\treadonly workspaceAvailableMiB: number | null;\n\t\treadonly heapUsedRatio: number | null;\n\t\treadonly systemCpuPercent: number | null;\n\t\treadonly diagnostics: readonly string[];\n\t};\n\treadonly settingsErrors: readonly string[];\n}\n\nexport function buildResourceDoctorReport(input: {\n\treadonly snapshot: HostResourceSnapshot;\n\treadonly decision: ResourceAdmissionDecision;\n\treadonly resolved: ResolvedResourceGovernorSettings;\n\treadonly probeDurationMs: number;\n}): ResourceDoctorReport {\n\tconst { snapshot, decision, resolved } = input;\n\tconst heapRatio = snapshot.heapLimitBytes > 0 ? snapshot.heapUsedBytes / snapshot.heapLimitBytes : null;\n\treturn {\n\t\tschemaVersion: 1,\n\t\tcommand: \"resource_doctor\",\n\t\tmode: resolved.mode,\n\t\tpressure: decision.pressure,\n\t\taction: decision.action,\n\t\tcaps: {\n\t\t\tmaxToolConcurrency: decision.maxToolConcurrency,\n\t\t\tmaxParallelLanes: decision.maxParallelLanes,\n\t\t\tmaxHeavyProcesses: decision.maxHeavyProcesses,\n\t\t},\n\t\treasons: decision.reasons,\n\t\tprobeDurationMs: Math.round(input.probeDurationMs),\n\t\tsnapshot: {\n\t\t\tenvironment: snapshot.environment,\n\t\t\tlogicalCpuCount: snapshot.logicalCpuCount,\n\t\t\teffectiveAvailableMemoryMiB: toMiB(effectiveAvailableMemoryBytes(snapshot)),\n\t\t\tprocessAvailableMemoryMiB: toMiB(snapshot.processAvailableMemoryBytes),\n\t\t\tconstrainedMemoryMiB: toMiB(snapshot.constrainedMemoryBytes),\n\t\t\thostFreeMemoryMiB: toMiB(snapshot.hostFreeMemoryBytes),\n\t\t\thostTotalMemoryMiB: toMiB(snapshot.hostTotalMemoryBytes),\n\t\t\tworkspaceAvailableMiB: toMiB(snapshot.workspaceAvailableBytes),\n\t\t\theapUsedRatio: heapRatio === null ? null : Number(heapRatio.toFixed(4)),\n\t\t\tsystemCpuPercent: snapshot.systemCpuPercent,\n\t\t\tdiagnostics: snapshot.diagnostics,\n\t\t},\n\t\tsettingsErrors: resolved.errors,\n\t};\n}\n\nconst MIB = 1024 * 1024;\n\nfunction toMiB(bytes: number | null): number | null {\n\treturn bytes === null ? null : Math.round(bytes / MIB);\n}\n\nfunction formatMiB(bytes: number | null): string {\n\tconst mib = toMiB(bytes);\n\treturn mib === null ? \"unknown\" : `${mib.toLocaleString()} MiB`;\n}\n"]}

package/dist/core/resource-governor-settings.d.ts

@@ -0,0 +1,56 @@
+import type { ResourceAdmissionConfig, ResourceGovernorMode } from "./resource-admission.ts";
+export { buildResourceDoctorReport, describeResourceReasons, formatResourcePolicyLines, formatResourceProbeLines, formatResourceSummaryLines, type ResourceDoctorReport, } from "./resource-governor-format.ts";
+/**
+ * Resource governor settings surface (OMK v0.97.x roadmap §18, M1/PR2).
+ *
+ * Pure translation from the additive `resourceGovernor` settings block (and
+ * the §18.2 `OMK_RESOURCE_GOVERNOR` env override) to the layer-1 admission
+ * config plus probe options. Validation follows §18.1: explicit errors over
+ * silent clamps, and invalid input fails closed to the defaults.
+ *
+ * Resolved values feed the `/resource` command, `omk doctor resources`, and
+ * the M2 prompt preflight: `observe` records decisions only, while
+ * `adaptive`/`strict` let the run lease throttle per-run tool concurrency.
+ * Lane and heavy-process caps become authoritative in later milestones.
+ */
+/** Additive settings block (§18, §29.1: absent block keeps v0.96.1 behavior). */
+export interface ResourceGovernorSettings {
+    enabled?: boolean;
+    mode?: ResourceGovernorMode;
+    maxProbeMs?: number;
+    cpuSampleMs?: number;
+    constrainedAvailableMemoryMiB?: number;
+    criticalAvailableMemoryMiB?: number;
+    constrainedDiskFreeMiB?: number;
+    criticalDiskFreeMiB?: number;
+    constrainedHeapRatio?: number;
+    criticalHeapRatio?: number;
+    busyCpuPercent?: number;
+    normalMaxToolConcurrency?: number;
+    constrainedMaxToolConcurrency?: number;
+    criticalMaxToolConcurrency?: number;
+    normalMaxParallelLanes?: number;
+    constrainedMaxParallelLanes?: number;
+    criticalMaxParallelLanes?: number;
+    normalMaxHeavyProcesses?: number;
+    constrainedMaxHeavyProcesses?: number;
+    criticalMaxHeavyProcesses?: number;
+}
+export declare const RESOURCE_GOVERNOR_MODE_ENV = "OMK_RESOURCE_GOVERNOR";
+export declare const DEFAULT_RESOURCE_GOVERNOR_MODE: ResourceGovernorMode;
+export interface ResolvedResourceGovernorSettings {
+    readonly mode: ResourceGovernorMode;
+    /** Only present when the setting is valid; the probe applies its own defaults otherwise. */
+    readonly maxProbeMs?: number;
+    readonly cpuSampleMs?: number;
+    readonly admission: ResourceAdmissionConfig;
+    /** §18.1 explicit validation errors; non-empty means defaults were applied for the failed area. */
+    readonly errors: readonly string[];
+}
+/**
+ * Resolve settings + environment into governor mode, probe options, and the
+ * admission config. Never throws; every invalid field produces an explicit
+ * error and falls back to the corresponding default (§18.1 fail-closed).
+ */
+export declare function resolveResourceGovernorSettings(settings?: ResourceGovernorSettings, env?: NodeJS.ProcessEnv): ResolvedResourceGovernorSettings;
+//# sourceMappingURL=resource-governor-settings.d.ts.map

package/dist/core/resource-governor-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor-settings.d.ts","sourceRoot":"","sources":["../../src/core/resource-governor-settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,uBAAuB,EAEvB,oBAAoB,EACpB,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EACN,yBAAyB,EACzB,uBAAuB,EACvB,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,KAAK,oBAAoB,GACzB,MAAM,+BAA+B,CAAC;AAEvC;;;;;;;;;;;;GAYG;AAEH,mFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACxC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAE5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,eAAO,MAAM,8BAA8B,EAAE,oBAAgC,CAAC;AAG9E,MAAM,WAAW,gCAAgC;IAChD,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,uBAAuB,CAAC;IAC5C,oGAAmG;IACnG,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC9C,QAAQ,CAAC,EAAE,wBAAwB,EACnC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAClC,gCAAgC,CA6ClC","sourcesContent":["import type {\n\tResourceAdmissionConfig,\n\tResourceAdmissionConfigOverrides,\n\tResourceGovernorMode,\n} from \"./resource-admission.ts\";\nimport { resolveResourceAdmissionConfig } from \"./resource-admission.ts\";\nimport { MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS } from \"./system-cpu-sampler.ts\";\n\nexport {\n\tbuildResourceDoctorReport,\n\tdescribeResourceReasons,\n\tformatResourcePolicyLines,\n\tformatResourceProbeLines,\n\tformatResourceSummaryLines,\n\ttype ResourceDoctorReport,\n} from \"./resource-governor-format.ts\";\n\n/**\n * Resource governor settings surface (OMK v0.97.x roadmap §18, M1/PR2).\n *\n * Pure translation from the additive `resourceGovernor` settings block (and\n * the §18.2 `OMK_RESOURCE_GOVERNOR` env override) to the layer-1 admission\n * config plus probe options. Validation follows §18.1: explicit errors over\n * silent clamps, and invalid input fails closed to the defaults.\n *\n * Resolved values feed the `/resource` command, `omk doctor resources`, and\n * the M2 prompt preflight: `observe` records decisions only, while\n * `adaptive`/`strict` let the run lease throttle per-run tool concurrency.\n * Lane and heavy-process caps become authoritative in later milestones.\n */\n\n/** Additive settings block (§18, §29.1: absent block keeps v0.96.1 behavior). */\nexport interface ResourceGovernorSettings {\n\tenabled?: boolean; // default: true; false forces mode \"off\"\n\tmode?: ResourceGovernorMode; // default: \"observe\" (v0.97.0-alpha rollout stage, §7.4)\n\n\tmaxProbeMs?: number; // default: 300; async probe deadline, valid 50..5000 (§18.1)\n\tcpuSampleMs?: number; // default: 180; CPU two-sample interval, valid 150..250 (§6.3)\n\n\tconstrainedAvailableMemoryMiB?: number; // default: 1536 (§6.7)\n\tcriticalAvailableMemoryMiB?: number; // default: 512\n\tconstrainedDiskFreeMiB?: number; // default: 4096\n\tcriticalDiskFreeMiB?: number; // default: 1024\n\tconstrainedHeapRatio?: number; // default: 0.75\n\tcriticalHeapRatio?: number; // default: 0.85\n\tbusyCpuPercent?: number; // default: 85\n\n\tnormalMaxToolConcurrency?: number; // default: 4 (§7.2)\n\tconstrainedMaxToolConcurrency?: number; // default: 2\n\tcriticalMaxToolConcurrency?: number; // default: 1\n\tnormalMaxParallelLanes?: number; // default: 4\n\tconstrainedMaxParallelLanes?: number; // default: 2\n\tcriticalMaxParallelLanes?: number; // default: 1\n\tnormalMaxHeavyProcesses?: number; // default: 2\n\tconstrainedMaxHeavyProcesses?: number; // default: 1\n\tcriticalMaxHeavyProcesses?: number; // default: 1\n}\n\nexport const RESOURCE_GOVERNOR_MODE_ENV = \"OMK_RESOURCE_GOVERNOR\";\nexport const DEFAULT_RESOURCE_GOVERNOR_MODE: ResourceGovernorMode = \"observe\";\nconst RESOURCE_GOVERNOR_MODES: ReadonlySet<string> = new Set([\"off\", \"observe\", \"adaptive\", \"strict\"]);\n\nexport interface ResolvedResourceGovernorSettings {\n\treadonly mode: ResourceGovernorMode;\n\t/** Only present when the setting is valid; the probe applies its own defaults otherwise. */\n\treadonly maxProbeMs?: number;\n\treadonly cpuSampleMs?: number;\n\treadonly admission: ResourceAdmissionConfig;\n\t/** §18.1 explicit validation errors; non-empty means defaults were applied for the failed area. */\n\treadonly errors: readonly string[];\n}\n\n/**\n * Resolve settings + environment into governor mode, probe options, and the\n * admission config. Never throws; every invalid field produces an explicit\n * error and falls back to the corresponding default (§18.1 fail-closed).\n */\nexport function resolveResourceGovernorSettings(\n\tsettings?: ResourceGovernorSettings,\n\tenv: NodeJS.ProcessEnv = process.env,\n): ResolvedResourceGovernorSettings {\n\tconst errors: string[] = [];\n\tconst mode = resolveMode(settings, env, errors);\n\n\tconst maxProbeMs = validateRange(settings?.maxProbeMs, \"maxProbeMs\", 50, 5000, errors);\n\tconst cpuSampleMs = validateRange(\n\t\tsettings?.cpuSampleMs,\n\t\t\"cpuSampleMs\",\n\t\tMIN_CPU_SAMPLE_MS,\n\t\tMAX_CPU_SAMPLE_MS,\n\t\terrors,\n\t);\n\n\tconst overrides: ResourceAdmissionConfigOverrides = {\n\t\tthresholds: pruneUndefined({\n\t\t\tconstrainedAvailableMemoryMiB: settings?.constrainedAvailableMemoryMiB,\n\t\t\tcriticalAvailableMemoryMiB: settings?.criticalAvailableMemoryMiB,\n\t\t\tconstrainedDiskFreeMiB: settings?.constrainedDiskFreeMiB,\n\t\t\tcriticalDiskFreeMiB: settings?.criticalDiskFreeMiB,\n\t\t\tconstrainedHeapRatio: settings?.constrainedHeapRatio,\n\t\t\tcriticalHeapRatio: settings?.criticalHeapRatio,\n\t\t\tbusyCpuPercent: settings?.busyCpuPercent,\n\t\t}),\n\t\tcaps: {\n\t\t\tnormal: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.normalMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.normalMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.normalMaxHeavyProcesses,\n\t\t\t}),\n\t\t\tconstrained: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.constrainedMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.constrainedMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.constrainedMaxHeavyProcesses,\n\t\t\t}),\n\t\t\tcritical: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.criticalMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.criticalMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.criticalMaxHeavyProcesses,\n\t\t\t}),\n\t\t},\n\t};\n\tconst admission = resolveResourceAdmissionConfig(overrides);\n\terrors.push(...admission.errors);\n\n\treturn { mode, maxProbeMs, cpuSampleMs, admission: admission.config, errors };\n}\n\nfunction resolveMode(\n\tsettings: ResourceGovernorSettings | undefined,\n\tenv: NodeJS.ProcessEnv,\n\terrors: string[],\n): ResourceGovernorMode {\n\t// §18.2/§30.1: the env override is the operator kill switch and wins.\n\tconst envMode = env[RESOURCE_GOVERNOR_MODE_ENV]?.trim();\n\tif (envMode !== undefined && envMode !== \"\") {\n\t\tif (RESOURCE_GOVERNOR_MODES.has(envMode)) {\n\t\t\treturn envMode as ResourceGovernorMode;\n\t\t}\n\t\terrors.push(`resourceGovernor.mode: invalid ${RESOURCE_GOVERNOR_MODE_ENV} value ${JSON.stringify(envMode)}`);\n\t}\n\tif (settings?.enabled === false) {\n\t\treturn \"off\";\n\t}\n\tconst configured = settings?.mode;\n\tif (configured !== undefined) {\n\t\tif (RESOURCE_GOVERNOR_MODES.has(configured)) {\n\t\t\treturn configured;\n\t\t}\n\t\terrors.push(`resourceGovernor.mode: invalid value ${JSON.stringify(configured)}`);\n\t}\n\treturn DEFAULT_RESOURCE_GOVERNOR_MODE;\n}\n\nfunction validateRange(\n\tvalue: number | undefined,\n\tfield: string,\n\tmin: number,\n\tmax: number,\n\terrors: string[],\n): number | undefined {\n\tif (value === undefined) {\n\t\treturn undefined;\n\t}\n\tif (!Number.isSafeInteger(value) || value < min || value > max) {\n\t\terrors.push(`resourceGovernor.${field}: must be an integer within [${min}, ${max}], got ${String(value)}`);\n\t\treturn undefined;\n\t}\n\treturn value;\n}\n\nfunction pruneUndefined<T extends Record<string, number | undefined>>(record: T): Partial<T> {\n\tconst pruned: Record<string, number> = {};\n\tfor (const [key, value] of Object.entries(record)) {\n\t\tif (value !== undefined) {\n\t\t\tpruned[key] = value;\n\t\t}\n\t}\n\treturn pruned as Partial<T>;\n}\n"]}

package/dist/core/resource-governor-settings.js

@@ -0,0 +1,89 @@
+import { resolveResourceAdmissionConfig } from "./resource-admission.js";
+import { MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS } from "./system-cpu-sampler.js";
+export { buildResourceDoctorReport, describeResourceReasons, formatResourcePolicyLines, formatResourceProbeLines, formatResourceSummaryLines, } from "./resource-governor-format.js";
+export const RESOURCE_GOVERNOR_MODE_ENV = "OMK_RESOURCE_GOVERNOR";
+export const DEFAULT_RESOURCE_GOVERNOR_MODE = "observe";
+const RESOURCE_GOVERNOR_MODES = new Set(["off", "observe", "adaptive", "strict"]);
+/**
+ * Resolve settings + environment into governor mode, probe options, and the
+ * admission config. Never throws; every invalid field produces an explicit
+ * error and falls back to the corresponding default (§18.1 fail-closed).
+ */
+export function resolveResourceGovernorSettings(settings, env = process.env) {
+    const errors = [];
+    const mode = resolveMode(settings, env, errors);
+    const maxProbeMs = validateRange(settings?.maxProbeMs, "maxProbeMs", 50, 5000, errors);
+    const cpuSampleMs = validateRange(settings?.cpuSampleMs, "cpuSampleMs", MIN_CPU_SAMPLE_MS, MAX_CPU_SAMPLE_MS, errors);
+    const overrides = {
+        thresholds: pruneUndefined({
+            constrainedAvailableMemoryMiB: settings?.constrainedAvailableMemoryMiB,
+            criticalAvailableMemoryMiB: settings?.criticalAvailableMemoryMiB,
+            constrainedDiskFreeMiB: settings?.constrainedDiskFreeMiB,
+            criticalDiskFreeMiB: settings?.criticalDiskFreeMiB,
+            constrainedHeapRatio: settings?.constrainedHeapRatio,
+            criticalHeapRatio: settings?.criticalHeapRatio,
+            busyCpuPercent: settings?.busyCpuPercent,
+        }),
+        caps: {
+            normal: pruneUndefined({
+                maxToolConcurrency: settings?.normalMaxToolConcurrency,
+                maxParallelLanes: settings?.normalMaxParallelLanes,
+                maxHeavyProcesses: settings?.normalMaxHeavyProcesses,
+            }),
+            constrained: pruneUndefined({
+                maxToolConcurrency: settings?.constrainedMaxToolConcurrency,
+                maxParallelLanes: settings?.constrainedMaxParallelLanes,
+                maxHeavyProcesses: settings?.constrainedMaxHeavyProcesses,
+            }),
+            critical: pruneUndefined({
+                maxToolConcurrency: settings?.criticalMaxToolConcurrency,
+                maxParallelLanes: settings?.criticalMaxParallelLanes,
+                maxHeavyProcesses: settings?.criticalMaxHeavyProcesses,
+            }),
+        },
+    };
+    const admission = resolveResourceAdmissionConfig(overrides);
+    errors.push(...admission.errors);
+    return { mode, maxProbeMs, cpuSampleMs, admission: admission.config, errors };
+}
+function resolveMode(settings, env, errors) {
+    // §18.2/§30.1: the env override is the operator kill switch and wins.
+    const envMode = env[RESOURCE_GOVERNOR_MODE_ENV]?.trim();
+    if (envMode !== undefined && envMode !== "") {
+        if (RESOURCE_GOVERNOR_MODES.has(envMode)) {
+            return envMode;
+        }
+        errors.push(`resourceGovernor.mode: invalid ${RESOURCE_GOVERNOR_MODE_ENV} value ${JSON.stringify(envMode)}`);
+    }
+    if (settings?.enabled === false) {
+        return "off";
+    }
+    const configured = settings?.mode;
+    if (configured !== undefined) {
+        if (RESOURCE_GOVERNOR_MODES.has(configured)) {
+            return configured;
+        }
+        errors.push(`resourceGovernor.mode: invalid value ${JSON.stringify(configured)}`);
+    }
+    return DEFAULT_RESOURCE_GOVERNOR_MODE;
+}
+function validateRange(value, field, min, max, errors) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        errors.push(`resourceGovernor.${field}: must be an integer within [${min}, ${max}], got ${String(value)}`);
+        return undefined;
+    }
+    return value;
+}
+function pruneUndefined(record) {
+    const pruned = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value !== undefined) {
+            pruned[key] = value;
+        }
+    }
+    return pruned;
+}
+//# sourceMappingURL=resource-governor-settings.js.map

package/dist/core/resource-governor-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-governor-settings.js","sourceRoot":"","sources":["../../src/core/resource-governor-settings.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n\tResourceAdmissionConfig,\n\tResourceAdmissionConfigOverrides,\n\tResourceGovernorMode,\n} from \"./resource-admission.ts\";\nimport { resolveResourceAdmissionConfig } from \"./resource-admission.ts\";\nimport { MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS } from \"./system-cpu-sampler.ts\";\n\nexport {\n\tbuildResourceDoctorReport,\n\tdescribeResourceReasons,\n\tformatResourcePolicyLines,\n\tformatResourceProbeLines,\n\tformatResourceSummaryLines,\n\ttype ResourceDoctorReport,\n} from \"./resource-governor-format.ts\";\n\n/**\n * Resource governor settings surface (OMK v0.97.x roadmap §18, M1/PR2).\n *\n * Pure translation from the additive `resourceGovernor` settings block (and\n * the §18.2 `OMK_RESOURCE_GOVERNOR` env override) to the layer-1 admission\n * config plus probe options. Validation follows §18.1: explicit errors over\n * silent clamps, and invalid input fails closed to the defaults.\n *\n * Resolved values feed the `/resource` command, `omk doctor resources`, and\n * the M2 prompt preflight: `observe` records decisions only, while\n * `adaptive`/`strict` let the run lease throttle per-run tool concurrency.\n * Lane and heavy-process caps become authoritative in later milestones.\n */\n\n/** Additive settings block (§18, §29.1: absent block keeps v0.96.1 behavior). */\nexport interface ResourceGovernorSettings {\n\tenabled?: boolean; // default: true; false forces mode \"off\"\n\tmode?: ResourceGovernorMode; // default: \"observe\" (v0.97.0-alpha rollout stage, §7.4)\n\n\tmaxProbeMs?: number; // default: 300; async probe deadline, valid 50..5000 (§18.1)\n\tcpuSampleMs?: number; // default: 180; CPU two-sample interval, valid 150..250 (§6.3)\n\n\tconstrainedAvailableMemoryMiB?: number; // default: 1536 (§6.7)\n\tcriticalAvailableMemoryMiB?: number; // default: 512\n\tconstrainedDiskFreeMiB?: number; // default: 4096\n\tcriticalDiskFreeMiB?: number; // default: 1024\n\tconstrainedHeapRatio?: number; // default: 0.75\n\tcriticalHeapRatio?: number; // default: 0.85\n\tbusyCpuPercent?: number; // default: 85\n\n\tnormalMaxToolConcurrency?: number; // default: 4 (§7.2)\n\tconstrainedMaxToolConcurrency?: number; // default: 2\n\tcriticalMaxToolConcurrency?: number; // default: 1\n\tnormalMaxParallelLanes?: number; // default: 4\n\tconstrainedMaxParallelLanes?: number; // default: 2\n\tcriticalMaxParallelLanes?: number; // default: 1\n\tnormalMaxHeavyProcesses?: number; // default: 2\n\tconstrainedMaxHeavyProcesses?: number; // default: 1\n\tcriticalMaxHeavyProcesses?: number; // default: 1\n}\n\nexport const RESOURCE_GOVERNOR_MODE_ENV = \"OMK_RESOURCE_GOVERNOR\";\nexport const DEFAULT_RESOURCE_GOVERNOR_MODE: ResourceGovernorMode = \"observe\";\nconst RESOURCE_GOVERNOR_MODES: ReadonlySet<string> = new Set([\"off\", \"observe\", \"adaptive\", \"strict\"]);\n\nexport interface ResolvedResourceGovernorSettings {\n\treadonly mode: ResourceGovernorMode;\n\t/** Only present when the setting is valid; the probe applies its own defaults otherwise. */\n\treadonly maxProbeMs?: number;\n\treadonly cpuSampleMs?: number;\n\treadonly admission: ResourceAdmissionConfig;\n\t/** §18.1 explicit validation errors; non-empty means defaults were applied for the failed area. */\n\treadonly errors: readonly string[];\n}\n\n/**\n * Resolve settings + environment into governor mode, probe options, and the\n * admission config. Never throws; every invalid field produces an explicit\n * error and falls back to the corresponding default (§18.1 fail-closed).\n */\nexport function resolveResourceGovernorSettings(\n\tsettings?: ResourceGovernorSettings,\n\tenv: NodeJS.ProcessEnv = process.env,\n): ResolvedResourceGovernorSettings {\n\tconst errors: string[] = [];\n\tconst mode = resolveMode(settings, env, errors);\n\n\tconst maxProbeMs = validateRange(settings?.maxProbeMs, \"maxProbeMs\", 50, 5000, errors);\n\tconst cpuSampleMs = validateRange(\n\t\tsettings?.cpuSampleMs,\n\t\t\"cpuSampleMs\",\n\t\tMIN_CPU_SAMPLE_MS,\n\t\tMAX_CPU_SAMPLE_MS,\n\t\terrors,\n\t);\n\n\tconst overrides: ResourceAdmissionConfigOverrides = {\n\t\tthresholds: pruneUndefined({\n\t\t\tconstrainedAvailableMemoryMiB: settings?.constrainedAvailableMemoryMiB,\n\t\t\tcriticalAvailableMemoryMiB: settings?.criticalAvailableMemoryMiB,\n\t\t\tconstrainedDiskFreeMiB: settings?.constrainedDiskFreeMiB,\n\t\t\tcriticalDiskFreeMiB: settings?.criticalDiskFreeMiB,\n\t\t\tconstrainedHeapRatio: settings?.constrainedHeapRatio,\n\t\t\tcriticalHeapRatio: settings?.criticalHeapRatio,\n\t\t\tbusyCpuPercent: settings?.busyCpuPercent,\n\t\t}),\n\t\tcaps: {\n\t\t\tnormal: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.normalMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.normalMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.normalMaxHeavyProcesses,\n\t\t\t}),\n\t\t\tconstrained: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.constrainedMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.constrainedMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.constrainedMaxHeavyProcesses,\n\t\t\t}),\n\t\t\tcritical: pruneUndefined({\n\t\t\t\tmaxToolConcurrency: settings?.criticalMaxToolConcurrency,\n\t\t\t\tmaxParallelLanes: settings?.criticalMaxParallelLanes,\n\t\t\t\tmaxHeavyProcesses: settings?.criticalMaxHeavyProcesses,\n\t\t\t}),\n\t\t},\n\t};\n\tconst admission = resolveResourceAdmissionConfig(overrides);\n\terrors.push(...admission.errors);\n\n\treturn { mode, maxProbeMs, cpuSampleMs, admission: admission.config, errors };\n}\n\nfunction resolveMode(\n\tsettings: ResourceGovernorSettings | undefined,\n\tenv: NodeJS.ProcessEnv,\n\terrors: string[],\n): ResourceGovernorMode {\n\t// §18.2/§30.1: the env override is the operator kill switch and wins.\n\tconst envMode = env[RESOURCE_GOVERNOR_MODE_ENV]?.trim();\n\tif (envMode !== undefined && envMode !== \"\") {\n\t\tif (RESOURCE_GOVERNOR_MODES.has(envMode)) {\n\t\t\treturn envMode as ResourceGovernorMode;\n\t\t}\n\t\terrors.push(`resourceGovernor.mode: invalid ${RESOURCE_GOVERNOR_MODE_ENV} value ${JSON.stringify(envMode)}`);\n\t}\n\tif (settings?.enabled === false) {\n\t\treturn \"off\";\n\t}\n\tconst configured = settings?.mode;\n\tif (configured !== undefined) {\n\t\tif (RESOURCE_GOVERNOR_MODES.has(configured)) {\n\t\t\treturn configured;\n\t\t}\n\t\terrors.push(`resourceGovernor.mode: invalid value ${JSON.stringify(configured)}`);\n\t}\n\treturn DEFAULT_RESOURCE_GOVERNOR_MODE;\n}\n\nfunction validateRange(\n\tvalue: number | undefined,\n\tfield: string,\n\tmin: number,\n\tmax: number,\n\terrors: string[],\n): number | undefined {\n\tif (value === undefined) {\n\t\treturn undefined;\n\t}\n\tif (!Number.isSafeInteger(value) || value < min || value > max) {\n\t\terrors.push(`resourceGovernor.${field}: must be an integer within [${min}, ${max}], got ${String(value)}`);\n\t\treturn undefined;\n\t}\n\treturn value;\n}\n\nfunction pruneUndefined<T extends Record<string, number | undefined>>(record: T): Partial<T> {\n\tconst pruned: Record<string, number> = {};\n\tfor (const [key, value] of Object.entries(record)) {\n\t\tif (value !== undefined) {\n\t\t\tpruned[key] = value;\n\t\t}\n\t}\n\treturn pruned as Partial<T>;\n}\n"]}