open-multi-agent-kit 0.96.1 → 0.96.2

package/dist/core/host-resource-probe.js

@@ -0,0 +1,126 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as v8 from "node:v8";
+import { DEFAULT_CPU_SAMPLE_MS, MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS, sampleSystemCpuPercent, } from "./system-cpu-sampler.js";
+export { DEFAULT_CPU_SAMPLE_MS, MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS };
+export const DEFAULT_MAX_PROBE_MS = 300;
+export const MIN_MAX_PROBE_MS = 50;
+export const MAX_MAX_PROBE_MS = 5000;
+export function defaultProbeIo() {
+    return {
+        platform: () => process.platform,
+        arch: () => process.arch,
+        cpuCount: () => os.cpus().length,
+        availableMemory: () => (typeof process.availableMemory === "function" ? process.availableMemory() : null),
+        constrainedMemory: () => (typeof process.constrainedMemory === "function" ? process.constrainedMemory() : null),
+        totalmem: () => os.totalmem(),
+        freemem: () => os.freemem(),
+        rssBytes: () => process.memoryUsage().rss,
+        heapStatistics: () => {
+            const stats = v8.getHeapStatistics();
+            return { heapUsedBytes: stats.used_heap_size, heapLimitBytes: stats.heap_size_limit };
+        },
+        statfs: async (target) => {
+            const stats = await fs.promises.statfs(target, { bigint: true });
+            return { bavail: stats.bavail, bsize: stats.bsize };
+        },
+        sampleSystemCpuPercent: (sampleMs) => sampleSystemCpuPercent({ sampleMs }),
+        osRelease: () => os.release(),
+        fileExists: (target) => fs.existsSync(target),
+    };
+}
+/** Coarse environment hint (§4.1). Never an admission authority; `unknown` on any probe error. */
+export function detectEnvironment(io) {
+    try {
+        if (io.platform() === "linux") {
+            if (/microsoft/i.test(io.osRelease())) {
+                return "wsl";
+            }
+            if (io.fileExists("/.dockerenv") || io.fileExists("/run/.containerenv")) {
+                return "container";
+            }
+        }
+        return "native";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Race `run()` against a hard deadline. Never rejects. The bounded deadline
+ * timer is intentionally ref'd (see module doc) and cleared once settled, so
+ * no timer outlives the probe.
+ */
+export async function raceDeadline(run, deadlineMs) {
+    let timer = null;
+    try {
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve("timeout"), Math.max(1, deadlineMs));
+        });
+        const work = Promise.resolve()
+            .then(run)
+            .then((value) => ({ value, timedOut: false, failed: false }), () => ({ value: null, timedOut: false, failed: true }));
+        const settled = await Promise.race([work, timeout]);
+        if (settled === "timeout") {
+            return { value: null, timedOut: true, failed: false };
+        }
+        return settled;
+    }
+    finally {
+        if (timer !== null) {
+            clearTimeout(timer);
+        }
+    }
+}
+/** `bavail * bsize` with BigInt overflow clamped to `Number.MAX_SAFE_INTEGER` (§6.5). */
+export function bigintProductToSafeNumber(a, b) {
+    if (a < 0n || b < 0n) {
+        return null;
+    }
+    const product = a * b;
+    const max = BigInt(Number.MAX_SAFE_INTEGER);
+    return Number(product > max ? max : product);
+}
+export function guardValue(read, fallback) {
+    try {
+        return read();
+    }
+    catch {
+        return fallback;
+    }
+}
+export function probePositiveNumber(read, diagnostics, code) {
+    try {
+        const value = read();
+        // Values above MAX_SAFE_INTEGER are "no limit" sentinels, not real byte
+        // counts — observed on WSL where process.constrainedMemory() reports the
+        // cgroup u64 max (2^64). §6.4: unclear OS semantics degrade to a
+        // diagnostic instead of entering the candidate set.
+        if (typeof value !== "number" || !Number.isFinite(value) || value <= 0 || value > Number.MAX_SAFE_INTEGER) {
+            diagnostics.push(code);
+            return null;
+        }
+        return value;
+    }
+    catch {
+        diagnostics.push(code);
+        return null;
+    }
+}
+export function probePositiveInteger(read, diagnostics, code) {
+    const value = probePositiveNumber(read, diagnostics, code);
+    return value === null ? null : Math.floor(value);
+}
+export function sanitizeNonNegative(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return null;
+    }
+    return value;
+}
+export function clampInteger(value, fallback, min, max) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return fallback;
+    }
+    return Math.floor(Math.max(min, Math.min(max, value)));
+}
+//# sourceMappingURL=host-resource-probe.js.map

package/dist/core/host-resource-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-resource-probe.js","sourceRoot":"","sources":["../../src/core/host-resource-probe.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from \"node:fs\";\nimport * as os from \"node:os\";\nimport * as v8 from \"node:v8\";\nimport {\n\tDEFAULT_CPU_SAMPLE_MS,\n\tMAX_CPU_SAMPLE_MS,\n\tMIN_CPU_SAMPLE_MS,\n\tsampleSystemCpuPercent,\n} from \"./system-cpu-sampler.ts\";\n\nexport { DEFAULT_CPU_SAMPLE_MS, MAX_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS };\n\n/** Diagnostic hint only — admission authority comes from measured values (§4.1). */\nexport type HostEnvironment = \"native\" | \"wsl\" | \"container\" | \"unknown\";\n\n/** Injectable probe sources for deterministic, fault-injectable tests. */\nexport interface HostResourceProbeIo {\n\treadonly platform: () => NodeJS.Platform;\n\treadonly arch: () => string;\n\treadonly cpuCount: () => number;\n\treadonly availableMemory: () => number | null | undefined;\n\treadonly constrainedMemory: () => number | null | undefined;\n\treadonly totalmem: () => number;\n\treadonly freemem: () => number;\n\treadonly rssBytes: () => number;\n\treadonly heapStatistics: () => { readonly heapUsedBytes: number; readonly heapLimitBytes: number };\n\treadonly statfs: (target: string) => Promise<{ readonly bavail: bigint; readonly bsize: bigint }>;\n\treadonly sampleSystemCpuPercent: (sampleMs: number) => Promise<number | null>;\n\treadonly osRelease: () => string;\n\treadonly fileExists: (target: string) => boolean;\n}\n\nexport type HostResourceProbeOptions = {\n\t/** Workspace directory for the disk probe. Used for measurement only; never recorded. */\n\tcwd?: string;\n\t/** Hard preflight deadline for async probes; default 300 ms, clamped `[50, 5000]` (§6.3, §18.1). */\n\tmaxProbeMs?: number;\n\t/** CPU two-sample interval; clamped `[150, 250]` ms (§6.3). */\n\tcpuSampleMs?: number;\n\t/** Injectable clock for a deterministic `observedAt`. */\n\tnow?: () => Date;\n\t/** Partial probe source overrides; unspecified sources use real process/OS reads. */\n\tio?: Partial<HostResourceProbeIo>;\n};\n\nexport const DEFAULT_MAX_PROBE_MS = 300;\nexport const MIN_MAX_PROBE_MS = 50;\nexport const MAX_MAX_PROBE_MS = 5000;\n\nexport function defaultProbeIo(): HostResourceProbeIo {\n\treturn {\n\t\tplatform: () => process.platform,\n\t\tarch: () => process.arch,\n\t\tcpuCount: () => os.cpus().length,\n\t\tavailableMemory: () => (typeof process.availableMemory === \"function\" ? process.availableMemory() : null),\n\t\tconstrainedMemory: () => (typeof process.constrainedMemory === \"function\" ? process.constrainedMemory() : null),\n\t\ttotalmem: () => os.totalmem(),\n\t\tfreemem: () => os.freemem(),\n\t\trssBytes: () => process.memoryUsage().rss,\n\t\theapStatistics: () => {\n\t\t\tconst stats = v8.getHeapStatistics();\n\t\t\treturn { heapUsedBytes: stats.used_heap_size, heapLimitBytes: stats.heap_size_limit };\n\t\t},\n\t\tstatfs: async (target) => {\n\t\t\tconst stats = await fs.promises.statfs(target, { bigint: true });\n\t\t\treturn { bavail: stats.bavail, bsize: stats.bsize };\n\t\t},\n\t\tsampleSystemCpuPercent: (sampleMs) => sampleSystemCpuPercent({ sampleMs }),\n\t\tosRelease: () => os.release(),\n\t\tfileExists: (target) => fs.existsSync(target),\n\t};\n}\n\n/** Coarse environment hint (§4.1). Never an admission authority; `unknown` on any probe error. */\nexport function detectEnvironment(io: HostResourceProbeIo): HostEnvironment {\n\ttry {\n\t\tif (io.platform() === \"linux\") {\n\t\t\tif (/microsoft/i.test(io.osRelease())) {\n\t\t\t\treturn \"wsl\";\n\t\t\t}\n\t\t\tif (io.fileExists(\"/.dockerenv\") || io.fileExists(\"/run/.containerenv\")) {\n\t\t\t\treturn \"container\";\n\t\t\t}\n\t\t}\n\t\treturn \"native\";\n\t} catch {\n\t\treturn \"unknown\";\n\t}\n}\n\ntype DeadlineResult<T> = { readonly value: T | null; readonly timedOut: boolean; readonly failed: boolean };\n\n/**\n * Race `run()` against a hard deadline. Never rejects. The bounded deadline\n * timer is intentionally ref'd (see module doc) and cleared once settled, so\n * no timer outlives the probe.\n */\nexport async function raceDeadline<T>(run: () => Promise<T>, deadlineMs: number): Promise<DeadlineResult<T>> {\n\tlet timer: ReturnType<typeof setTimeout> | null = null;\n\ttry {\n\t\tconst timeout = new Promise<\"timeout\">((resolve) => {\n\t\t\ttimer = setTimeout(() => resolve(\"timeout\"), Math.max(1, deadlineMs));\n\t\t});\n\t\tconst work = Promise.resolve()\n\t\t\t.then(run)\n\t\t\t.then(\n\t\t\t\t(value): DeadlineResult<T> => ({ value, timedOut: false, failed: false }),\n\t\t\t\t(): DeadlineResult<T> => ({ value: null, timedOut: false, failed: true }),\n\t\t\t);\n\t\tconst settled = await Promise.race([work, timeout]);\n\t\tif (settled === \"timeout\") {\n\t\t\treturn { value: null, timedOut: true, failed: false };\n\t\t}\n\t\treturn settled;\n\t} finally {\n\t\tif (timer !== null) {\n\t\t\tclearTimeout(timer);\n\t\t}\n\t}\n}\n\n/** `bavail * bsize` with BigInt overflow clamped to `Number.MAX_SAFE_INTEGER` (§6.5). */\nexport function bigintProductToSafeNumber(a: bigint, b: bigint): number | null {\n\tif (a < 0n || b < 0n) {\n\t\treturn null;\n\t}\n\tconst product = a * b;\n\tconst max = BigInt(Number.MAX_SAFE_INTEGER);\n\treturn Number(product > max ? max : product);\n}\n\nexport function guardValue<T>(read: () => T, fallback: T): T {\n\ttry {\n\t\treturn read();\n\t} catch {\n\t\treturn fallback;\n\t}\n}\n\nexport function probePositiveNumber(\n\tread: () => number | null | undefined,\n\tdiagnostics: string[],\n\tcode: string,\n): number | null {\n\ttry {\n\t\tconst value = read();\n\t\t// Values above MAX_SAFE_INTEGER are \"no limit\" sentinels, not real byte\n\t\t// counts — observed on WSL where process.constrainedMemory() reports the\n\t\t// cgroup u64 max (2^64). §6.4: unclear OS semantics degrade to a\n\t\t// diagnostic instead of entering the candidate set.\n\t\tif (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0 || value > Number.MAX_SAFE_INTEGER) {\n\t\t\tdiagnostics.push(code);\n\t\t\treturn null;\n\t\t}\n\t\treturn value;\n\t} catch {\n\t\tdiagnostics.push(code);\n\t\treturn null;\n\t}\n}\n\nexport function probePositiveInteger(read: () => number, diagnostics: string[], code: string): number | null {\n\tconst value = probePositiveNumber(read, diagnostics, code);\n\treturn value === null ? null : Math.floor(value);\n}\n\nexport function sanitizeNonNegative(value: number | undefined): number | null {\n\tif (typeof value !== \"number\" || !Number.isFinite(value) || value < 0) {\n\t\treturn null;\n\t}\n\treturn value;\n}\n\nexport function clampInteger(value: unknown, fallback: number, min: number, max: number): number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value)) {\n\t\treturn fallback;\n\t}\n\treturn Math.floor(Math.max(min, Math.min(max, value)));\n}\n"]}

package/dist/core/host-resource-snapshot.d.ts

@@ -0,0 +1,54 @@
+import { DEFAULT_MAX_PROBE_MS, type HostEnvironment, type HostResourceProbeIo, type HostResourceProbeOptions, MAX_MAX_PROBE_MS, MIN_MAX_PROBE_MS } from "./host-resource-probe.ts";
+export { DEFAULT_MAX_PROBE_MS, MAX_MAX_PROBE_MS, MIN_MAX_PROBE_MS };
+export type { HostEnvironment, HostResourceProbeIo, HostResourceProbeOptions };
+/**
+ * Host resource snapshot probe (OMK v0.97.x roadmap §6, M1/PR1).
+ *
+ * The snapshot is an immutable operational fact captured before a prompt run.
+ * It is observability-first in this layer: no admission or scheduler behavior
+ * changes here (that wiring lands in later milestones).
+ *
+ * Invariants enforced by this module:
+ * - Never throws: every probe source is individually guarded and a failure
+ *   degrades to `null` plus a bounded diagnostic code (roadmap §2.1, §21).
+ * - Bounded latency: async probes race a hard deadline (default 300 ms,
+ *   roadmap §6.3). Deadline timers stay ref'd while the probe is awaited so
+ *   the returned promise always settles even when it is the only pending
+ *   work in the process (headless CLI probes), and are cleared on settle.
+ * - Privacy boundary (roadmap §6.2): the snapshot carries only numeric
+ *   capacity facts, platform/arch, a coarse environment hint, and bounded
+ *   diagnostic codes. No username, hostname, paths, env dump, mounts,
+ *   network interfaces, machine identifiers, or file contents.
+ */
+export declare const HOST_RESOURCE_SNAPSHOT_VERSION: 1;
+export interface HostResourceSnapshot {
+    readonly schemaVersion: typeof HOST_RESOURCE_SNAPSHOT_VERSION;
+    readonly observedAt: string;
+    readonly platform: NodeJS.Platform;
+    readonly arch: string;
+    readonly logicalCpuCount: number;
+    readonly processAvailableMemoryBytes: number | null;
+    readonly constrainedMemoryBytes: number | null;
+    readonly hostTotalMemoryBytes: number | null;
+    readonly hostFreeMemoryBytes: number | null;
+    readonly processRssBytes: number;
+    readonly heapUsedBytes: number;
+    readonly heapLimitBytes: number;
+    readonly systemCpuPercent: number | null;
+    readonly workspaceAvailableBytes: number | null;
+    readonly environment: HostEnvironment;
+    readonly diagnostics: readonly string[];
+}
+/**
+ * Capture a host resource snapshot. Resolves within roughly `maxProbeMs` and
+ * never rejects; unavailable sources yield `null` fields plus diagnostics.
+ */
+export declare function captureHostResourceSnapshot(options?: HostResourceProbeOptions): Promise<HostResourceSnapshot>;
+/**
+ * §6.4 effective memory: the minimum of the known positive candidates
+ * (process available, constrained, host free), or `null` when none is known.
+ */
+export declare function effectiveAvailableMemoryBytes(snapshot: HostResourceSnapshot): number | null;
+/** Stable content digest of a snapshot (used as `snapshotDigest` in admission decisions). */
+export declare function computeHostResourceSnapshotDigest(snapshot: HostResourceSnapshot): string;
+//# sourceMappingURL=host-resource-snapshot.d.ts.map

package/dist/core/host-resource-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-resource-snapshot.d.ts","sourceRoot":"","sources":["../../src/core/host-resource-snapshot.ts"],"names":[],"mappings":"AACA,OAAO,EAIN,oBAAoB,EAIpB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAE7B,gBAAgB,EAEhB,gBAAgB,EAKhB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;AACpE,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,CAAC;AAE/E;;;;;;;;;;;;;;;;;;GAkBG;AAEH,eAAO,MAAM,8BAA8B,GAAa,CAAC;AAEzD,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,aAAa,EAAE,OAAO,8BAA8B,CAAC;IAC9D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC,QAAQ,CAAC,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD,QAAQ,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhD,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA+FnH;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,GAAG,IAAI,CAU3F;AAED,6FAA6F;AAC7F,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,CAoBxF","sourcesContent":["import { createHash } from \"node:crypto\";\nimport {\n\tbigintProductToSafeNumber,\n\tclampInteger,\n\tDEFAULT_CPU_SAMPLE_MS,\n\tDEFAULT_MAX_PROBE_MS,\n\tdefaultProbeIo,\n\tdetectEnvironment,\n\tguardValue,\n\ttype HostEnvironment,\n\ttype HostResourceProbeIo,\n\ttype HostResourceProbeOptions,\n\tMAX_CPU_SAMPLE_MS,\n\tMAX_MAX_PROBE_MS,\n\tMIN_CPU_SAMPLE_MS,\n\tMIN_MAX_PROBE_MS,\n\tprobePositiveInteger,\n\tprobePositiveNumber,\n\traceDeadline,\n\tsanitizeNonNegative,\n} from \"./host-resource-probe.ts\";\n\nexport { DEFAULT_MAX_PROBE_MS, MAX_MAX_PROBE_MS, MIN_MAX_PROBE_MS };\nexport type { HostEnvironment, HostResourceProbeIo, HostResourceProbeOptions };\n\n/**\n * Host resource snapshot probe (OMK v0.97.x roadmap §6, M1/PR1).\n *\n * The snapshot is an immutable operational fact captured before a prompt run.\n * It is observability-first in this layer: no admission or scheduler behavior\n * changes here (that wiring lands in later milestones).\n *\n * Invariants enforced by this module:\n * - Never throws: every probe source is individually guarded and a failure\n *   degrades to `null` plus a bounded diagnostic code (roadmap §2.1, §21).\n * - Bounded latency: async probes race a hard deadline (default 300 ms,\n *   roadmap §6.3). Deadline timers stay ref'd while the probe is awaited so\n *   the returned promise always settles even when it is the only pending\n *   work in the process (headless CLI probes), and are cleared on settle.\n * - Privacy boundary (roadmap §6.2): the snapshot carries only numeric\n *   capacity facts, platform/arch, a coarse environment hint, and bounded\n *   diagnostic codes. No username, hostname, paths, env dump, mounts,\n *   network interfaces, machine identifiers, or file contents.\n */\n\nexport const HOST_RESOURCE_SNAPSHOT_VERSION = 1 as const;\n\nexport interface HostResourceSnapshot {\n\treadonly schemaVersion: typeof HOST_RESOURCE_SNAPSHOT_VERSION;\n\treadonly observedAt: string;\n\treadonly platform: NodeJS.Platform;\n\treadonly arch: string;\n\treadonly logicalCpuCount: number;\n\n\treadonly processAvailableMemoryBytes: number | null;\n\treadonly constrainedMemoryBytes: number | null;\n\treadonly hostTotalMemoryBytes: number | null;\n\treadonly hostFreeMemoryBytes: number | null;\n\n\treadonly processRssBytes: number;\n\treadonly heapUsedBytes: number;\n\treadonly heapLimitBytes: number;\n\n\treadonly systemCpuPercent: number | null;\n\treadonly workspaceAvailableBytes: number | null;\n\n\treadonly environment: HostEnvironment;\n\treadonly diagnostics: readonly string[];\n}\n\n/**\n * Capture a host resource snapshot. Resolves within roughly `maxProbeMs` and\n * never rejects; unavailable sources yield `null` fields plus diagnostics.\n */\nexport async function captureHostResourceSnapshot(options?: HostResourceProbeOptions): Promise<HostResourceSnapshot> {\n\tconst io: HostResourceProbeIo = { ...defaultProbeIo(), ...options?.io };\n\tconst maxProbeMs = clampInteger(options?.maxProbeMs, DEFAULT_MAX_PROBE_MS, MIN_MAX_PROBE_MS, MAX_MAX_PROBE_MS);\n\tconst cpuSampleMs = clampInteger(options?.cpuSampleMs, DEFAULT_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS, MAX_CPU_SAMPLE_MS);\n\tconst diagnostics: string[] = [];\n\n\tconst observedAt = guardValue(() => (options?.now?.() ?? new Date()).toISOString(), new Date(0).toISOString());\n\tconst platform = guardValue<NodeJS.Platform>(() => io.platform(), \"linux\");\n\tconst arch = guardValue(() => io.arch(), \"unknown\");\n\tconst logicalCpuCount = Math.max(\n\t\t1,\n\t\tprobePositiveInteger(() => io.cpuCount(), diagnostics, \"probe.cpu-count.unavailable\") ?? 1,\n\t);\n\n\t// Memory semantics note (§6.4): `process.availableMemory()` is free memory\n\t// still available to the process; `process.constrainedMemory()` is the OS\n\t// limit (0 when unknown, and on some platforms it includes current RSS).\n\t// We record raw values and never subtract RSS from them, so the min-known\n\t// policy stays conservative without double subtraction.\n\tconst processAvailableMemoryBytes = probePositiveNumber(\n\t\t() => io.availableMemory(),\n\t\tdiagnostics,\n\t\t\"probe.available-memory.unavailable\",\n\t);\n\tconst constrainedMemoryBytes = probePositiveNumber(\n\t\t() => io.constrainedMemory(),\n\t\tdiagnostics,\n\t\t\"probe.constrained-memory.unavailable\",\n\t);\n\tconst hostTotalMemoryBytes = probePositiveNumber(\n\t\t() => io.totalmem(),\n\t\tdiagnostics,\n\t\t\"probe.host-total-memory.unavailable\",\n\t);\n\tconst hostFreeMemoryBytes = probePositiveNumber(\n\t\t() => io.freemem(),\n\t\tdiagnostics,\n\t\t\"probe.host-free-memory.unavailable\",\n\t);\n\n\tconst processRssBytes = probePositiveNumber(() => io.rssBytes(), diagnostics, \"probe.rss.unavailable\") ?? 0;\n\tconst heap = guardValue(() => io.heapStatistics(), null);\n\tif (heap === null) {\n\t\tdiagnostics.push(\"probe.heap.unavailable\");\n\t}\n\tconst heapUsedBytes = sanitizeNonNegative(heap?.heapUsedBytes) ?? 0;\n\tconst heapLimitBytes = sanitizeNonNegative(heap?.heapLimitBytes) ?? 0;\n\n\t// Async probes share one deadline and run concurrently so total preflight\n\t// wall time stays ~= maxProbeMs (roadmap §24: p95 <= 300 ms).\n\tconst [disk, cpu] = await Promise.all([\n\t\traceDeadline(() => io.statfs(options?.cwd ?? guardValue(() => process.cwd(), \".\")), maxProbeMs),\n\t\traceDeadline(() => io.sampleSystemCpuPercent(cpuSampleMs), maxProbeMs),\n\t]);\n\n\tlet workspaceAvailableBytes: number | null = null;\n\tif (disk.timedOut) {\n\t\tdiagnostics.push(\"probe.disk.timeout\");\n\t} else if (disk.failed || disk.value === null) {\n\t\tdiagnostics.push(\"probe.disk.unavailable\");\n\t} else {\n\t\t// §6.5: bavail (unprivileged-available), never bfree; clamp before Number().\n\t\tworkspaceAvailableBytes = bigintProductToSafeNumber(disk.value.bavail, disk.value.bsize);\n\t\tif (workspaceAvailableBytes === null) {\n\t\t\tdiagnostics.push(\"probe.disk.unavailable\");\n\t\t}\n\t}\n\n\tlet systemCpuPercent: number | null = null;\n\tif (cpu.timedOut) {\n\t\tdiagnostics.push(\"probe.cpu.timeout\");\n\t} else if (cpu.failed || cpu.value === null || !Number.isFinite(cpu.value)) {\n\t\tdiagnostics.push(\"probe.cpu.unavailable\");\n\t} else {\n\t\tsystemCpuPercent = Math.max(0, Math.min(100, cpu.value));\n\t}\n\n\treturn {\n\t\tschemaVersion: HOST_RESOURCE_SNAPSHOT_VERSION,\n\t\tobservedAt,\n\t\tplatform,\n\t\tarch,\n\t\tlogicalCpuCount,\n\t\tprocessAvailableMemoryBytes,\n\t\tconstrainedMemoryBytes,\n\t\thostTotalMemoryBytes,\n\t\thostFreeMemoryBytes,\n\t\tprocessRssBytes,\n\t\theapUsedBytes,\n\t\theapLimitBytes,\n\t\tsystemCpuPercent,\n\t\tworkspaceAvailableBytes,\n\t\tenvironment: detectEnvironment(io),\n\t\tdiagnostics,\n\t};\n}\n\n/**\n * §6.4 effective memory: the minimum of the known positive candidates\n * (process available, constrained, host free), or `null` when none is known.\n */\nexport function effectiveAvailableMemoryBytes(snapshot: HostResourceSnapshot): number | null {\n\tconst candidates = [\n\t\tsnapshot.processAvailableMemoryBytes,\n\t\tsnapshot.constrainedMemoryBytes,\n\t\tsnapshot.hostFreeMemoryBytes,\n\t].filter((value): value is number => typeof value === \"number\" && Number.isFinite(value) && value > 0);\n\tif (candidates.length === 0) {\n\t\treturn null;\n\t}\n\treturn Math.min(...candidates);\n}\n\n/** Stable content digest of a snapshot (used as `snapshotDigest` in admission decisions). */\nexport function computeHostResourceSnapshotDigest(snapshot: HostResourceSnapshot): string {\n\tconst canonical = JSON.stringify([\n\t\tsnapshot.schemaVersion,\n\t\tsnapshot.observedAt,\n\t\tsnapshot.platform,\n\t\tsnapshot.arch,\n\t\tsnapshot.logicalCpuCount,\n\t\tsnapshot.processAvailableMemoryBytes,\n\t\tsnapshot.constrainedMemoryBytes,\n\t\tsnapshot.hostTotalMemoryBytes,\n\t\tsnapshot.hostFreeMemoryBytes,\n\t\tsnapshot.processRssBytes,\n\t\tsnapshot.heapUsedBytes,\n\t\tsnapshot.heapLimitBytes,\n\t\tsnapshot.systemCpuPercent,\n\t\tsnapshot.workspaceAvailableBytes,\n\t\tsnapshot.environment,\n\t\tsnapshot.diagnostics,\n\t]);\n\treturn createHash(\"sha256\").update(canonical, \"utf8\").digest(\"hex\");\n}\n"]}

package/dist/core/host-resource-snapshot.js

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+import { bigintProductToSafeNumber, clampInteger, DEFAULT_CPU_SAMPLE_MS, DEFAULT_MAX_PROBE_MS, defaultProbeIo, detectEnvironment, guardValue, MAX_CPU_SAMPLE_MS, MAX_MAX_PROBE_MS, MIN_CPU_SAMPLE_MS, MIN_MAX_PROBE_MS, probePositiveInteger, probePositiveNumber, raceDeadline, sanitizeNonNegative, } from "./host-resource-probe.js";
+export { DEFAULT_MAX_PROBE_MS, MAX_MAX_PROBE_MS, MIN_MAX_PROBE_MS };
+/**
+ * Host resource snapshot probe (OMK v0.97.x roadmap §6, M1/PR1).
+ *
+ * The snapshot is an immutable operational fact captured before a prompt run.
+ * It is observability-first in this layer: no admission or scheduler behavior
+ * changes here (that wiring lands in later milestones).
+ *
+ * Invariants enforced by this module:
+ * - Never throws: every probe source is individually guarded and a failure
+ *   degrades to `null` plus a bounded diagnostic code (roadmap §2.1, §21).
+ * - Bounded latency: async probes race a hard deadline (default 300 ms,
+ *   roadmap §6.3). Deadline timers stay ref'd while the probe is awaited so
+ *   the returned promise always settles even when it is the only pending
+ *   work in the process (headless CLI probes), and are cleared on settle.
+ * - Privacy boundary (roadmap §6.2): the snapshot carries only numeric
+ *   capacity facts, platform/arch, a coarse environment hint, and bounded
+ *   diagnostic codes. No username, hostname, paths, env dump, mounts,
+ *   network interfaces, machine identifiers, or file contents.
+ */
+export const HOST_RESOURCE_SNAPSHOT_VERSION = 1;
+/**
+ * Capture a host resource snapshot. Resolves within roughly `maxProbeMs` and
+ * never rejects; unavailable sources yield `null` fields plus diagnostics.
+ */
+export async function captureHostResourceSnapshot(options) {
+    const io = { ...defaultProbeIo(), ...options?.io };
+    const maxProbeMs = clampInteger(options?.maxProbeMs, DEFAULT_MAX_PROBE_MS, MIN_MAX_PROBE_MS, MAX_MAX_PROBE_MS);
+    const cpuSampleMs = clampInteger(options?.cpuSampleMs, DEFAULT_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS, MAX_CPU_SAMPLE_MS);
+    const diagnostics = [];
+    const observedAt = guardValue(() => (options?.now?.() ?? new Date()).toISOString(), new Date(0).toISOString());
+    const platform = guardValue(() => io.platform(), "linux");
+    const arch = guardValue(() => io.arch(), "unknown");
+    const logicalCpuCount = Math.max(1, probePositiveInteger(() => io.cpuCount(), diagnostics, "probe.cpu-count.unavailable") ?? 1);
+    // Memory semantics note (§6.4): `process.availableMemory()` is free memory
+    // still available to the process; `process.constrainedMemory()` is the OS
+    // limit (0 when unknown, and on some platforms it includes current RSS).
+    // We record raw values and never subtract RSS from them, so the min-known
+    // policy stays conservative without double subtraction.
+    const processAvailableMemoryBytes = probePositiveNumber(() => io.availableMemory(), diagnostics, "probe.available-memory.unavailable");
+    const constrainedMemoryBytes = probePositiveNumber(() => io.constrainedMemory(), diagnostics, "probe.constrained-memory.unavailable");
+    const hostTotalMemoryBytes = probePositiveNumber(() => io.totalmem(), diagnostics, "probe.host-total-memory.unavailable");
+    const hostFreeMemoryBytes = probePositiveNumber(() => io.freemem(), diagnostics, "probe.host-free-memory.unavailable");
+    const processRssBytes = probePositiveNumber(() => io.rssBytes(), diagnostics, "probe.rss.unavailable") ?? 0;
+    const heap = guardValue(() => io.heapStatistics(), null);
+    if (heap === null) {
+        diagnostics.push("probe.heap.unavailable");
+    }
+    const heapUsedBytes = sanitizeNonNegative(heap?.heapUsedBytes) ?? 0;
+    const heapLimitBytes = sanitizeNonNegative(heap?.heapLimitBytes) ?? 0;
+    // Async probes share one deadline and run concurrently so total preflight
+    // wall time stays ~= maxProbeMs (roadmap §24: p95 <= 300 ms).
+    const [disk, cpu] = await Promise.all([
+        raceDeadline(() => io.statfs(options?.cwd ?? guardValue(() => process.cwd(), ".")), maxProbeMs),
+        raceDeadline(() => io.sampleSystemCpuPercent(cpuSampleMs), maxProbeMs),
+    ]);
+    let workspaceAvailableBytes = null;
+    if (disk.timedOut) {
+        diagnostics.push("probe.disk.timeout");
+    }
+    else if (disk.failed || disk.value === null) {
+        diagnostics.push("probe.disk.unavailable");
+    }
+    else {
+        // §6.5: bavail (unprivileged-available), never bfree; clamp before Number().
+        workspaceAvailableBytes = bigintProductToSafeNumber(disk.value.bavail, disk.value.bsize);
+        if (workspaceAvailableBytes === null) {
+            diagnostics.push("probe.disk.unavailable");
+        }
+    }
+    let systemCpuPercent = null;
+    if (cpu.timedOut) {
+        diagnostics.push("probe.cpu.timeout");
+    }
+    else if (cpu.failed || cpu.value === null || !Number.isFinite(cpu.value)) {
+        diagnostics.push("probe.cpu.unavailable");
+    }
+    else {
+        systemCpuPercent = Math.max(0, Math.min(100, cpu.value));
+    }
+    return {
+        schemaVersion: HOST_RESOURCE_SNAPSHOT_VERSION,
+        observedAt,
+        platform,
+        arch,
+        logicalCpuCount,
+        processAvailableMemoryBytes,
+        constrainedMemoryBytes,
+        hostTotalMemoryBytes,
+        hostFreeMemoryBytes,
+        processRssBytes,
+        heapUsedBytes,
+        heapLimitBytes,
+        systemCpuPercent,
+        workspaceAvailableBytes,
+        environment: detectEnvironment(io),
+        diagnostics,
+    };
+}
+/**
+ * §6.4 effective memory: the minimum of the known positive candidates
+ * (process available, constrained, host free), or `null` when none is known.
+ */
+export function effectiveAvailableMemoryBytes(snapshot) {
+    const candidates = [
+        snapshot.processAvailableMemoryBytes,
+        snapshot.constrainedMemoryBytes,
+        snapshot.hostFreeMemoryBytes,
+    ].filter((value) => typeof value === "number" && Number.isFinite(value) && value > 0);
+    if (candidates.length === 0) {
+        return null;
+    }
+    return Math.min(...candidates);
+}
+/** Stable content digest of a snapshot (used as `snapshotDigest` in admission decisions). */
+export function computeHostResourceSnapshotDigest(snapshot) {
+    const canonical = JSON.stringify([
+        snapshot.schemaVersion,
+        snapshot.observedAt,
+        snapshot.platform,
+        snapshot.arch,
+        snapshot.logicalCpuCount,
+        snapshot.processAvailableMemoryBytes,
+        snapshot.constrainedMemoryBytes,
+        snapshot.hostTotalMemoryBytes,
+        snapshot.hostFreeMemoryBytes,
+        snapshot.processRssBytes,
+        snapshot.heapUsedBytes,
+        snapshot.heapLimitBytes,
+        snapshot.systemCpuPercent,
+        snapshot.workspaceAvailableBytes,
+        snapshot.environment,
+        snapshot.diagnostics,
+    ]);
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+//# sourceMappingURL=host-resource-snapshot.js.map

package/dist/core/host-resource-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-resource-snapshot.js","sourceRoot":"","sources":["../../src/core/host-resource-snapshot.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport {\n\tbigintProductToSafeNumber,\n\tclampInteger,\n\tDEFAULT_CPU_SAMPLE_MS,\n\tDEFAULT_MAX_PROBE_MS,\n\tdefaultProbeIo,\n\tdetectEnvironment,\n\tguardValue,\n\ttype HostEnvironment,\n\ttype HostResourceProbeIo,\n\ttype HostResourceProbeOptions,\n\tMAX_CPU_SAMPLE_MS,\n\tMAX_MAX_PROBE_MS,\n\tMIN_CPU_SAMPLE_MS,\n\tMIN_MAX_PROBE_MS,\n\tprobePositiveInteger,\n\tprobePositiveNumber,\n\traceDeadline,\n\tsanitizeNonNegative,\n} from \"./host-resource-probe.ts\";\n\nexport { DEFAULT_MAX_PROBE_MS, MAX_MAX_PROBE_MS, MIN_MAX_PROBE_MS };\nexport type { HostEnvironment, HostResourceProbeIo, HostResourceProbeOptions };\n\n/**\n * Host resource snapshot probe (OMK v0.97.x roadmap §6, M1/PR1).\n *\n * The snapshot is an immutable operational fact captured before a prompt run.\n * It is observability-first in this layer: no admission or scheduler behavior\n * changes here (that wiring lands in later milestones).\n *\n * Invariants enforced by this module:\n * - Never throws: every probe source is individually guarded and a failure\n *   degrades to `null` plus a bounded diagnostic code (roadmap §2.1, §21).\n * - Bounded latency: async probes race a hard deadline (default 300 ms,\n *   roadmap §6.3). Deadline timers stay ref'd while the probe is awaited so\n *   the returned promise always settles even when it is the only pending\n *   work in the process (headless CLI probes), and are cleared on settle.\n * - Privacy boundary (roadmap §6.2): the snapshot carries only numeric\n *   capacity facts, platform/arch, a coarse environment hint, and bounded\n *   diagnostic codes. No username, hostname, paths, env dump, mounts,\n *   network interfaces, machine identifiers, or file contents.\n */\n\nexport const HOST_RESOURCE_SNAPSHOT_VERSION = 1 as const;\n\nexport interface HostResourceSnapshot {\n\treadonly schemaVersion: typeof HOST_RESOURCE_SNAPSHOT_VERSION;\n\treadonly observedAt: string;\n\treadonly platform: NodeJS.Platform;\n\treadonly arch: string;\n\treadonly logicalCpuCount: number;\n\n\treadonly processAvailableMemoryBytes: number | null;\n\treadonly constrainedMemoryBytes: number | null;\n\treadonly hostTotalMemoryBytes: number | null;\n\treadonly hostFreeMemoryBytes: number | null;\n\n\treadonly processRssBytes: number;\n\treadonly heapUsedBytes: number;\n\treadonly heapLimitBytes: number;\n\n\treadonly systemCpuPercent: number | null;\n\treadonly workspaceAvailableBytes: number | null;\n\n\treadonly environment: HostEnvironment;\n\treadonly diagnostics: readonly string[];\n}\n\n/**\n * Capture a host resource snapshot. Resolves within roughly `maxProbeMs` and\n * never rejects; unavailable sources yield `null` fields plus diagnostics.\n */\nexport async function captureHostResourceSnapshot(options?: HostResourceProbeOptions): Promise<HostResourceSnapshot> {\n\tconst io: HostResourceProbeIo = { ...defaultProbeIo(), ...options?.io };\n\tconst maxProbeMs = clampInteger(options?.maxProbeMs, DEFAULT_MAX_PROBE_MS, MIN_MAX_PROBE_MS, MAX_MAX_PROBE_MS);\n\tconst cpuSampleMs = clampInteger(options?.cpuSampleMs, DEFAULT_CPU_SAMPLE_MS, MIN_CPU_SAMPLE_MS, MAX_CPU_SAMPLE_MS);\n\tconst diagnostics: string[] = [];\n\n\tconst observedAt = guardValue(() => (options?.now?.() ?? new Date()).toISOString(), new Date(0).toISOString());\n\tconst platform = guardValue<NodeJS.Platform>(() => io.platform(), \"linux\");\n\tconst arch = guardValue(() => io.arch(), \"unknown\");\n\tconst logicalCpuCount = Math.max(\n\t\t1,\n\t\tprobePositiveInteger(() => io.cpuCount(), diagnostics, \"probe.cpu-count.unavailable\") ?? 1,\n\t);\n\n\t// Memory semantics note (§6.4): `process.availableMemory()` is free memory\n\t// still available to the process; `process.constrainedMemory()` is the OS\n\t// limit (0 when unknown, and on some platforms it includes current RSS).\n\t// We record raw values and never subtract RSS from them, so the min-known\n\t// policy stays conservative without double subtraction.\n\tconst processAvailableMemoryBytes = probePositiveNumber(\n\t\t() => io.availableMemory(),\n\t\tdiagnostics,\n\t\t\"probe.available-memory.unavailable\",\n\t);\n\tconst constrainedMemoryBytes = probePositiveNumber(\n\t\t() => io.constrainedMemory(),\n\t\tdiagnostics,\n\t\t\"probe.constrained-memory.unavailable\",\n\t);\n\tconst hostTotalMemoryBytes = probePositiveNumber(\n\t\t() => io.totalmem(),\n\t\tdiagnostics,\n\t\t\"probe.host-total-memory.unavailable\",\n\t);\n\tconst hostFreeMemoryBytes = probePositiveNumber(\n\t\t() => io.freemem(),\n\t\tdiagnostics,\n\t\t\"probe.host-free-memory.unavailable\",\n\t);\n\n\tconst processRssBytes = probePositiveNumber(() => io.rssBytes(), diagnostics, \"probe.rss.unavailable\") ?? 0;\n\tconst heap = guardValue(() => io.heapStatistics(), null);\n\tif (heap === null) {\n\t\tdiagnostics.push(\"probe.heap.unavailable\");\n\t}\n\tconst heapUsedBytes = sanitizeNonNegative(heap?.heapUsedBytes) ?? 0;\n\tconst heapLimitBytes = sanitizeNonNegative(heap?.heapLimitBytes) ?? 0;\n\n\t// Async probes share one deadline and run concurrently so total preflight\n\t// wall time stays ~= maxProbeMs (roadmap §24: p95 <= 300 ms).\n\tconst [disk, cpu] = await Promise.all([\n\t\traceDeadline(() => io.statfs(options?.cwd ?? guardValue(() => process.cwd(), \".\")), maxProbeMs),\n\t\traceDeadline(() => io.sampleSystemCpuPercent(cpuSampleMs), maxProbeMs),\n\t]);\n\n\tlet workspaceAvailableBytes: number | null = null;\n\tif (disk.timedOut) {\n\t\tdiagnostics.push(\"probe.disk.timeout\");\n\t} else if (disk.failed || disk.value === null) {\n\t\tdiagnostics.push(\"probe.disk.unavailable\");\n\t} else {\n\t\t// §6.5: bavail (unprivileged-available), never bfree; clamp before Number().\n\t\tworkspaceAvailableBytes = bigintProductToSafeNumber(disk.value.bavail, disk.value.bsize);\n\t\tif (workspaceAvailableBytes === null) {\n\t\t\tdiagnostics.push(\"probe.disk.unavailable\");\n\t\t}\n\t}\n\n\tlet systemCpuPercent: number | null = null;\n\tif (cpu.timedOut) {\n\t\tdiagnostics.push(\"probe.cpu.timeout\");\n\t} else if (cpu.failed || cpu.value === null || !Number.isFinite(cpu.value)) {\n\t\tdiagnostics.push(\"probe.cpu.unavailable\");\n\t} else {\n\t\tsystemCpuPercent = Math.max(0, Math.min(100, cpu.value));\n\t}\n\n\treturn {\n\t\tschemaVersion: HOST_RESOURCE_SNAPSHOT_VERSION,\n\t\tobservedAt,\n\t\tplatform,\n\t\tarch,\n\t\tlogicalCpuCount,\n\t\tprocessAvailableMemoryBytes,\n\t\tconstrainedMemoryBytes,\n\t\thostTotalMemoryBytes,\n\t\thostFreeMemoryBytes,\n\t\tprocessRssBytes,\n\t\theapUsedBytes,\n\t\theapLimitBytes,\n\t\tsystemCpuPercent,\n\t\tworkspaceAvailableBytes,\n\t\tenvironment: detectEnvironment(io),\n\t\tdiagnostics,\n\t};\n}\n\n/**\n * §6.4 effective memory: the minimum of the known positive candidates\n * (process available, constrained, host free), or `null` when none is known.\n */\nexport function effectiveAvailableMemoryBytes(snapshot: HostResourceSnapshot): number | null {\n\tconst candidates = [\n\t\tsnapshot.processAvailableMemoryBytes,\n\t\tsnapshot.constrainedMemoryBytes,\n\t\tsnapshot.hostFreeMemoryBytes,\n\t].filter((value): value is number => typeof value === \"number\" && Number.isFinite(value) && value > 0);\n\tif (candidates.length === 0) {\n\t\treturn null;\n\t}\n\treturn Math.min(...candidates);\n}\n\n/** Stable content digest of a snapshot (used as `snapshotDigest` in admission decisions). */\nexport function computeHostResourceSnapshotDigest(snapshot: HostResourceSnapshot): string {\n\tconst canonical = JSON.stringify([\n\t\tsnapshot.schemaVersion,\n\t\tsnapshot.observedAt,\n\t\tsnapshot.platform,\n\t\tsnapshot.arch,\n\t\tsnapshot.logicalCpuCount,\n\t\tsnapshot.processAvailableMemoryBytes,\n\t\tsnapshot.constrainedMemoryBytes,\n\t\tsnapshot.hostTotalMemoryBytes,\n\t\tsnapshot.hostFreeMemoryBytes,\n\t\tsnapshot.processRssBytes,\n\t\tsnapshot.heapUsedBytes,\n\t\tsnapshot.heapLimitBytes,\n\t\tsnapshot.systemCpuPercent,\n\t\tsnapshot.workspaceAvailableBytes,\n\t\tsnapshot.environment,\n\t\tsnapshot.diagnostics,\n\t]);\n\treturn createHash(\"sha256\").update(canonical, \"utf8\").digest(\"hex\");\n}\n"]}

package/dist/core/prompt-settlement.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).
+ *
+ * `agent_end` is NOT final (§16.1): provider retries, compaction retries,
+ * durable-goal continuations, steering/follow-up queues, shards, and child
+ * subagents may still run. `prompt_settled` fires only when the reducer's
+ * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the
+ * M4 completion sound, notifications) must treat it as a UX signal, never a
+ * correctness signal (§3 non-goals).
+ *
+ * The reducer is a pure function over an immutable state (§16.5). Shard and
+ * child counters are wired by M5/M6; they participate in the contract now so
+ * those slices only add signal call sites.
+ */
+export type PromptSettlementOutcome = "completed" | "failed" | "aborted";
+/** §16.2 prompt run identity. */
+export interface PromptRunRef {
+    readonly promptRunId: string;
+    readonly sessionId: string;
+    readonly startedAt: string;
+    readonly lineageId?: string;
+}
+/** §16.3 settlement contract. */
+export interface PromptSettledEvent {
+    readonly type: "prompt_settled";
+    readonly promptRunId: string;
+    readonly outcome: PromptSettlementOutcome;
+    readonly durationMs: number;
+    readonly terminationKind?: string;
+}
+/** §16.5 coordinator state. */
+export interface PromptSettlementState {
+    readonly promptRunId: string;
+    readonly startedAtEpochMs: number;
+    readonly activeProviderAttempts: number;
+    readonly activeTools: number;
+    readonly activeShards: number;
+    readonly activeChildren: number;
+    readonly queuedContinuations: number;
+    readonly terminal?: {
+        readonly outcome: PromptSettlementOutcome;
+        readonly terminationKind?: string;
+    };
+    readonly emitted: boolean;
+}
+export type PromptSettlementSignal = {
+    readonly kind: "provider_attempt";
+    readonly delta: 1 | -1;
+} | {
+    readonly kind: "tool";
+    readonly delta: 1 | -1;
+} | {
+    readonly kind: "shard";
+    readonly delta: 1 | -1;
+} | {
+    readonly kind: "child";
+    readonly delta: 1 | -1;
+} | {
+    readonly kind: "continuation";
+    readonly delta: 1 | -1;
+} | {
+    readonly kind: "terminal";
+    readonly outcome: PromptSettlementOutcome;
+    readonly terminationKind?: string;
+} | {
+    readonly kind: "emitted";
+};
+export declare function createPromptSettlementState(promptRunId: string, startedAtEpochMs: number): PromptSettlementState;
+/** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */
+export declare function reducePromptSettlement(state: PromptSettlementState, signal: PromptSettlementSignal): PromptSettlementState;
+/** §16.4: every condition must hold before `prompt_settled` may emit. */
+export declare function shouldEmitPromptSettled(state: PromptSettlementState): boolean;
+/**
+ * Build the event when (and only when) §16.4 holds, marking the state
+ * emitted so the same sequence can never yield a second event.
+ */
+export declare function settlePromptIfReady(state: PromptSettlementState, nowEpochMs: number): {
+    readonly state: PromptSettlementState;
+    readonly event: PromptSettledEvent | null;
+};
+//# sourceMappingURL=prompt-settlement.d.ts.map

package/dist/core/prompt-settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-settlement.d.ts","sourceRoot":"","sources":["../../src/core/prompt-settlement.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).\n *\n * `agent_end` is NOT final (§16.1): provider retries, compaction retries,\n * durable-goal continuations, steering/follow-up queues, shards, and child\n * subagents may still run. `prompt_settled` fires only when the reducer's\n * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the\n * M4 completion sound, notifications) must treat it as a UX signal, never a\n * correctness signal (§3 non-goals).\n *\n * The reducer is a pure function over an immutable state (§16.5). Shard and\n * child counters are wired by M5/M6; they participate in the contract now so\n * those slices only add signal call sites.\n */\n\nexport type PromptSettlementOutcome = \"completed\" | \"failed\" | \"aborted\";\n\n/** §16.2 prompt run identity. */\nexport interface PromptRunRef {\n\treadonly promptRunId: string;\n\treadonly sessionId: string;\n\treadonly startedAt: string;\n\treadonly lineageId?: string;\n}\n\n/** §16.3 settlement contract. */\nexport interface PromptSettledEvent {\n\treadonly type: \"prompt_settled\";\n\treadonly promptRunId: string;\n\treadonly outcome: PromptSettlementOutcome;\n\treadonly durationMs: number;\n\treadonly terminationKind?: string;\n}\n\n/** §16.5 coordinator state. */\nexport interface PromptSettlementState {\n\treadonly promptRunId: string;\n\treadonly startedAtEpochMs: number;\n\treadonly activeProviderAttempts: number;\n\treadonly activeTools: number;\n\treadonly activeShards: number;\n\treadonly activeChildren: number;\n\treadonly queuedContinuations: number;\n\treadonly terminal?: {\n\t\treadonly outcome: PromptSettlementOutcome;\n\t\treadonly terminationKind?: string;\n\t};\n\treadonly emitted: boolean;\n}\n\nexport type PromptSettlementSignal =\n\t| { readonly kind: \"provider_attempt\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"tool\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"shard\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"child\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"continuation\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"terminal\"; readonly outcome: PromptSettlementOutcome; readonly terminationKind?: string }\n\t| { readonly kind: \"emitted\" };\n\nexport function createPromptSettlementState(promptRunId: string, startedAtEpochMs: number): PromptSettlementState {\n\treturn {\n\t\tpromptRunId,\n\t\tstartedAtEpochMs,\n\t\tactiveProviderAttempts: 0,\n\t\tactiveTools: 0,\n\t\tactiveShards: 0,\n\t\tactiveChildren: 0,\n\t\tqueuedContinuations: 0,\n\t\temitted: false,\n\t};\n}\n\n/** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */\nexport function reducePromptSettlement(\n\tstate: PromptSettlementState,\n\tsignal: PromptSettlementSignal,\n): PromptSettlementState {\n\tswitch (signal.kind) {\n\t\tcase \"provider_attempt\":\n\t\t\treturn { ...state, activeProviderAttempts: clampCount(state.activeProviderAttempts + signal.delta) };\n\t\tcase \"tool\":\n\t\t\treturn { ...state, activeTools: clampCount(state.activeTools + signal.delta) };\n\t\tcase \"shard\":\n\t\t\treturn { ...state, activeShards: clampCount(state.activeShards + signal.delta) };\n\t\tcase \"child\":\n\t\t\treturn { ...state, activeChildren: clampCount(state.activeChildren + signal.delta) };\n\t\tcase \"continuation\":\n\t\t\treturn { ...state, queuedContinuations: clampCount(state.queuedContinuations + signal.delta) };\n\t\tcase \"terminal\":\n\t\t\t// First terminal outcome wins; later reclassification never flips it (§15.3).\n\t\t\tif (state.terminal !== undefined) {\n\t\t\t\treturn state;\n\t\t\t}\n\t\t\treturn { ...state, terminal: { outcome: signal.outcome, terminationKind: signal.terminationKind } };\n\t\tcase \"emitted\":\n\t\t\treturn { ...state, emitted: true };\n\t\tdefault: {\n\t\t\tconst exhaustive: never = signal;\n\t\t\treturn exhaustive;\n\t\t}\n\t}\n}\n\n/** §16.4: every condition must hold before `prompt_settled` may emit. */\nexport function shouldEmitPromptSettled(state: PromptSettlementState): boolean {\n\treturn (\n\t\tstate.terminal !== undefined &&\n\t\t!state.emitted &&\n\t\tstate.activeProviderAttempts === 0 &&\n\t\tstate.activeTools === 0 &&\n\t\tstate.activeShards === 0 &&\n\t\tstate.activeChildren === 0 &&\n\t\tstate.queuedContinuations === 0\n\t);\n}\n\n/**\n * Build the event when (and only when) §16.4 holds, marking the state\n * emitted so the same sequence can never yield a second event.\n */\nexport function settlePromptIfReady(\n\tstate: PromptSettlementState,\n\tnowEpochMs: number,\n): { readonly state: PromptSettlementState; readonly event: PromptSettledEvent | null } {\n\tif (!shouldEmitPromptSettled(state) || state.terminal === undefined) {\n\t\treturn { state, event: null };\n\t}\n\tconst event: PromptSettledEvent = {\n\t\ttype: \"prompt_settled\",\n\t\tpromptRunId: state.promptRunId,\n\t\toutcome: state.terminal.outcome,\n\t\tdurationMs: Math.max(0, nowEpochMs - state.startedAtEpochMs),\n\t\t...(state.terminal.terminationKind !== undefined ? { terminationKind: state.terminal.terminationKind } : {}),\n\t};\n\treturn { state: reducePromptSettlement(state, { kind: \"emitted\" }), event };\n}\n\nfunction clampCount(value: number): number {\n\treturn Math.max(0, value);\n}\n"]}

package/dist/core/prompt-settlement.js

@@ -0,0 +1,84 @@
+/**
+ * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).
+ *
+ * `agent_end` is NOT final (§16.1): provider retries, compaction retries,
+ * durable-goal continuations, steering/follow-up queues, shards, and child
+ * subagents may still run. `prompt_settled` fires only when the reducer's
+ * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the
+ * M4 completion sound, notifications) must treat it as a UX signal, never a
+ * correctness signal (§3 non-goals).
+ *
+ * The reducer is a pure function over an immutable state (§16.5). Shard and
+ * child counters are wired by M5/M6; they participate in the contract now so
+ * those slices only add signal call sites.
+ */
+export function createPromptSettlementState(promptRunId, startedAtEpochMs) {
+    return {
+        promptRunId,
+        startedAtEpochMs,
+        activeProviderAttempts: 0,
+        activeTools: 0,
+        activeShards: 0,
+        activeChildren: 0,
+        queuedContinuations: 0,
+        emitted: false,
+    };
+}
+/** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */
+export function reducePromptSettlement(state, signal) {
+    switch (signal.kind) {
+        case "provider_attempt":
+            return { ...state, activeProviderAttempts: clampCount(state.activeProviderAttempts + signal.delta) };
+        case "tool":
+            return { ...state, activeTools: clampCount(state.activeTools + signal.delta) };
+        case "shard":
+            return { ...state, activeShards: clampCount(state.activeShards + signal.delta) };
+        case "child":
+            return { ...state, activeChildren: clampCount(state.activeChildren + signal.delta) };
+        case "continuation":
+            return { ...state, queuedContinuations: clampCount(state.queuedContinuations + signal.delta) };
+        case "terminal":
+            // First terminal outcome wins; later reclassification never flips it (§15.3).
+            if (state.terminal !== undefined) {
+                return state;
+            }
+            return { ...state, terminal: { outcome: signal.outcome, terminationKind: signal.terminationKind } };
+        case "emitted":
+            return { ...state, emitted: true };
+        default: {
+            const exhaustive = signal;
+            return exhaustive;
+        }
+    }
+}
+/** §16.4: every condition must hold before `prompt_settled` may emit. */
+export function shouldEmitPromptSettled(state) {
+    return (state.terminal !== undefined &&
+        !state.emitted &&
+        state.activeProviderAttempts === 0 &&
+        state.activeTools === 0 &&
+        state.activeShards === 0 &&
+        state.activeChildren === 0 &&
+        state.queuedContinuations === 0);
+}
+/**
+ * Build the event when (and only when) §16.4 holds, marking the state
+ * emitted so the same sequence can never yield a second event.
+ */
+export function settlePromptIfReady(state, nowEpochMs) {
+    if (!shouldEmitPromptSettled(state) || state.terminal === undefined) {
+        return { state, event: null };
+    }
+    const event = {
+        type: "prompt_settled",
+        promptRunId: state.promptRunId,
+        outcome: state.terminal.outcome,
+        durationMs: Math.max(0, nowEpochMs - state.startedAtEpochMs),
+        ...(state.terminal.terminationKind !== undefined ? { terminationKind: state.terminal.terminationKind } : {}),
+    };
+    return { state: reducePromptSettlement(state, { kind: "emitted" }), event };
+}
+function clampCount(value) {
+    return Math.max(0, value);
+}
+//# sourceMappingURL=prompt-settlement.js.map

package/dist/core/prompt-settlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-settlement.js","sourceRoot":"","sources":["../../src/core/prompt-settlement.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Prompt settlement coordinator (OMK v0.97.x roadmap §16, M4/PR6).\n *\n * `agent_end` is NOT final (§16.1): provider retries, compaction retries,\n * durable-goal continuations, steering/follow-up queues, shards, and child\n * subagents may still run. `prompt_settled` fires only when the reducer's\n * §16.4 conditions all hold, exactly once per promptRunId. Consumers (the\n * M4 completion sound, notifications) must treat it as a UX signal, never a\n * correctness signal (§3 non-goals).\n *\n * The reducer is a pure function over an immutable state (§16.5). Shard and\n * child counters are wired by M5/M6; they participate in the contract now so\n * those slices only add signal call sites.\n */\n\nexport type PromptSettlementOutcome = \"completed\" | \"failed\" | \"aborted\";\n\n/** §16.2 prompt run identity. */\nexport interface PromptRunRef {\n\treadonly promptRunId: string;\n\treadonly sessionId: string;\n\treadonly startedAt: string;\n\treadonly lineageId?: string;\n}\n\n/** §16.3 settlement contract. */\nexport interface PromptSettledEvent {\n\treadonly type: \"prompt_settled\";\n\treadonly promptRunId: string;\n\treadonly outcome: PromptSettlementOutcome;\n\treadonly durationMs: number;\n\treadonly terminationKind?: string;\n}\n\n/** §16.5 coordinator state. */\nexport interface PromptSettlementState {\n\treadonly promptRunId: string;\n\treadonly startedAtEpochMs: number;\n\treadonly activeProviderAttempts: number;\n\treadonly activeTools: number;\n\treadonly activeShards: number;\n\treadonly activeChildren: number;\n\treadonly queuedContinuations: number;\n\treadonly terminal?: {\n\t\treadonly outcome: PromptSettlementOutcome;\n\t\treadonly terminationKind?: string;\n\t};\n\treadonly emitted: boolean;\n}\n\nexport type PromptSettlementSignal =\n\t| { readonly kind: \"provider_attempt\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"tool\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"shard\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"child\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"continuation\"; readonly delta: 1 | -1 }\n\t| { readonly kind: \"terminal\"; readonly outcome: PromptSettlementOutcome; readonly terminationKind?: string }\n\t| { readonly kind: \"emitted\" };\n\nexport function createPromptSettlementState(promptRunId: string, startedAtEpochMs: number): PromptSettlementState {\n\treturn {\n\t\tpromptRunId,\n\t\tstartedAtEpochMs,\n\t\tactiveProviderAttempts: 0,\n\t\tactiveTools: 0,\n\t\tactiveShards: 0,\n\t\tactiveChildren: 0,\n\t\tqueuedContinuations: 0,\n\t\temitted: false,\n\t};\n}\n\n/** Pure reducer (§16.5). Counters clamp at zero; terminal and emitted are latching. */\nexport function reducePromptSettlement(\n\tstate: PromptSettlementState,\n\tsignal: PromptSettlementSignal,\n): PromptSettlementState {\n\tswitch (signal.kind) {\n\t\tcase \"provider_attempt\":\n\t\t\treturn { ...state, activeProviderAttempts: clampCount(state.activeProviderAttempts + signal.delta) };\n\t\tcase \"tool\":\n\t\t\treturn { ...state, activeTools: clampCount(state.activeTools + signal.delta) };\n\t\tcase \"shard\":\n\t\t\treturn { ...state, activeShards: clampCount(state.activeShards + signal.delta) };\n\t\tcase \"child\":\n\t\t\treturn { ...state, activeChildren: clampCount(state.activeChildren + signal.delta) };\n\t\tcase \"continuation\":\n\t\t\treturn { ...state, queuedContinuations: clampCount(state.queuedContinuations + signal.delta) };\n\t\tcase \"terminal\":\n\t\t\t// First terminal outcome wins; later reclassification never flips it (§15.3).\n\t\t\tif (state.terminal !== undefined) {\n\t\t\t\treturn state;\n\t\t\t}\n\t\t\treturn { ...state, terminal: { outcome: signal.outcome, terminationKind: signal.terminationKind } };\n\t\tcase \"emitted\":\n\t\t\treturn { ...state, emitted: true };\n\t\tdefault: {\n\t\t\tconst exhaustive: never = signal;\n\t\t\treturn exhaustive;\n\t\t}\n\t}\n}\n\n/** §16.4: every condition must hold before `prompt_settled` may emit. */\nexport function shouldEmitPromptSettled(state: PromptSettlementState): boolean {\n\treturn (\n\t\tstate.terminal !== undefined &&\n\t\t!state.emitted &&\n\t\tstate.activeProviderAttempts === 0 &&\n\t\tstate.activeTools === 0 &&\n\t\tstate.activeShards === 0 &&\n\t\tstate.activeChildren === 0 &&\n\t\tstate.queuedContinuations === 0\n\t);\n}\n\n/**\n * Build the event when (and only when) §16.4 holds, marking the state\n * emitted so the same sequence can never yield a second event.\n */\nexport function settlePromptIfReady(\n\tstate: PromptSettlementState,\n\tnowEpochMs: number,\n): { readonly state: PromptSettlementState; readonly event: PromptSettledEvent | null } {\n\tif (!shouldEmitPromptSettled(state) || state.terminal === undefined) {\n\t\treturn { state, event: null };\n\t}\n\tconst event: PromptSettledEvent = {\n\t\ttype: \"prompt_settled\",\n\t\tpromptRunId: state.promptRunId,\n\t\toutcome: state.terminal.outcome,\n\t\tdurationMs: Math.max(0, nowEpochMs - state.startedAtEpochMs),\n\t\t...(state.terminal.terminationKind !== undefined ? { terminationKind: state.terminal.terminationKind } : {}),\n\t};\n\treturn { state: reducePromptSettlement(state, { kind: \"emitted\" }), event };\n}\n\nfunction clampCount(value: number): number {\n\treturn Math.max(0, value);\n}\n"]}