open-multi-agent-kit 0.96.0 → 0.96.2

package/dist/core/resource-observation-journal.js

@@ -0,0 +1,198 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Local-only resource observation journal (roadmap §15.1/§15.2/§20.2).
+ *
+ * A dedicated JSONL artifact under `.omk/runs/<promptRunId>/` — deliberately
+ * NOT the hash-chained run journal: §15.2 restricts raw host facts to a
+ * separate local-only artifact, and extending the run journal's closed audit
+ * union would invalidate old readers. Shard plan/transition entries stay in
+ * `workload-shards.jsonl` (they already journal there); this file carries
+ * the remaining §20.2 entries.
+ *
+ * Privacy (§15.2, §20.3, §30): facts are flat primitives only — pressure
+ * levels, caps, digests, durations, reason codes. Never raw memory/cpu
+ * numbers, hostnames, usernames, or command text. Observability is
+ * fail-open: a write/read failure degrades to diagnostics, never breaks the
+ * run (probe failure is non-fatal by contract).
+ */
+export const RESOURCE_OBSERVATION_JOURNAL_FILE = "resource-observations.jsonl";
+/** §20.2 journal entry kinds handled by this artifact. */
+export const RESOURCE_OBSERVATION_KINDS = [
+    "resource_snapshot_v1",
+    "resource_admission_v1",
+    "resource_lease_acquired_v1",
+    "resource_lease_released_v1",
+    "workload_classification_v1",
+    "workload_permit_wait_v1",
+    "workload_permit_acquired_v1",
+    "workload_permit_released_v1",
+    "prompt_settled_v1",
+    "completion_sound_result_v1",
+];
+const PROTOCOL_KIND_BY_JOURNAL_KIND = {
+    resource_snapshot_v1: "resource_snapshot.v1",
+    resource_admission_v1: "resource_admission.v1",
+    workload_classification_v1: "workload_classification.v1",
+    workload_permit_wait_v1: "workload_permit.v1",
+    workload_permit_acquired_v1: "workload_permit.v1",
+    workload_permit_released_v1: "workload_permit.v1",
+    prompt_settled_v1: "prompt_settled.v1",
+    completion_sound_result_v1: "notification_result.v1",
+};
+/**
+ * Project a journal record onto the §15.1 protocol observation surface.
+ * Lease entries are local-only operational detail and project to null.
+ */
+export function toProtocolObservation(record) {
+    const kind = PROTOCOL_KIND_BY_JOURNAL_KIND[record.kind];
+    return kind === undefined ? null : { kind, facts: record.facts };
+}
+/** §15.2: probe health and digest only — raw host values never leave the process. */
+export function snapshotObservationFacts(snapshot) {
+    return {
+        cpuProbe: snapshot.systemCpuPercent !== null,
+        memoryProbe: snapshot.processAvailableMemoryBytes !== null || snapshot.hostFreeMemoryBytes !== null,
+        heapLimitKnown: snapshot.heapLimitBytes > 0,
+    };
+}
+/** §15.2 example shape: pressure, action, and the three caps. */
+export function admissionObservationFacts(decision) {
+    return {
+        decisionId: decision.decisionId,
+        snapshotDigest: decision.snapshotDigest,
+        pressure: decision.pressure,
+        action: decision.action,
+        maxToolConcurrency: decision.maxToolConcurrency,
+        maxParallelLanes: decision.maxParallelLanes,
+        maxHeavyProcesses: decision.maxHeavyProcesses,
+    };
+}
+export function classificationObservationFacts(classification) {
+    return {
+        workloadClass: classification.workloadClass,
+        commandFamily: classification.commandFamily,
+        complexity: classification.complexity,
+        safeToAutoShard: classification.safeToAutoShard,
+        reasonCodes: classification.reasonCodes.slice(0, 8).join(","),
+    };
+}
+export function settledObservationFacts(event) {
+    return {
+        outcome: event.outcome,
+        durationMs: event.durationMs,
+        ...(event.terminationKind !== undefined ? { terminationKind: event.terminationKind } : {}),
+    };
+}
+export function soundObservationFacts(result) {
+    return {
+        backend: result.backend,
+        attempted: result.attempted,
+        success: result.success,
+        ...(result.diagnostic !== undefined ? { diagnostic: result.diagnostic.slice(0, 120) } : {}),
+    };
+}
+const MAX_LINE_BYTES = 8 * 1024;
+const MAX_RECORDS = 10_000;
+export class ResourceObservationJournal {
+    journalPath;
+    promptRunId;
+    now;
+    seq = 0;
+    disabled = false;
+    constructor(journalPath, promptRunId, now = () => new Date()) {
+        this.journalPath = journalPath;
+        this.promptRunId = promptRunId;
+        this.now = now;
+    }
+    static open(cwd, promptRunId, now) {
+        return new ResourceObservationJournal(path.join(cwd, ".omk", "runs", promptRunId, RESOURCE_OBSERVATION_JOURNAL_FILE), promptRunId, now);
+    }
+    get filePath() {
+        return this.journalPath;
+    }
+    /** Fail-open append: returns false (and stops trying) instead of throwing. */
+    record(kind, facts) {
+        if (this.disabled || this.seq >= MAX_RECORDS)
+            return false;
+        const entry = {
+            schemaVersion: 1,
+            seq: this.seq + 1,
+            kind,
+            at: this.now().toISOString(),
+            promptRunId: this.promptRunId,
+            facts,
+        };
+        const line = `${JSON.stringify(entry)}\n`;
+        if (line.length > MAX_LINE_BYTES)
+            return false;
+        try {
+            fs.mkdirSync(path.dirname(this.journalPath), { recursive: true });
+            fs.appendFileSync(this.journalPath, line, "utf8");
+            this.seq = entry.seq;
+            return true;
+        }
+        catch {
+            // Observability must never break the run; stop retrying this run.
+            this.disabled = true;
+            return false;
+        }
+    }
+    /** Fail-open load: malformed lines become diagnostics, never throws. */
+    load() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.journalPath, "utf8");
+        }
+        catch {
+            return { records: [], diagnostics: [] };
+        }
+        const records = [];
+        const diagnostics = [];
+        const lines = raw.split("\n");
+        for (let index = 0; index < lines.length && records.length < MAX_RECORDS; index++) {
+            const line = lines[index].trim();
+            if (line === "")
+                continue;
+            const parsed = parseObservationLine(line);
+            if (parsed === null) {
+                diagnostics.push(`line ${index + 1}: invalid observation record`);
+                continue;
+            }
+            records.push(parsed);
+        }
+        return { records, diagnostics };
+    }
+}
+const KIND_SET = new Set(RESOURCE_OBSERVATION_KINDS);
+function parseObservationLine(line) {
+    if (line.length > MAX_LINE_BYTES)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.schemaVersion !== 1)
+        return null;
+    if (typeof record.seq !== "number" || !Number.isSafeInteger(record.seq) || record.seq < 1)
+        return null;
+    if (typeof record.kind !== "string" || !KIND_SET.has(record.kind))
+        return null;
+    if (typeof record.at !== "string" || typeof record.promptRunId !== "string")
+        return null;
+    if (typeof record.facts !== "object" || record.facts === null || Array.isArray(record.facts))
+        return null;
+    for (const factValue of Object.values(record.facts)) {
+        const kind = typeof factValue;
+        if (factValue !== null && kind !== "string" && kind !== "number" && kind !== "boolean")
+            return null;
+    }
+    return record;
+}
+//# sourceMappingURL=resource-observation-journal.js.map

package/dist/core/resource-observation-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-observation-journal.js","sourceRoot":"","sources":["../../src/core/resource-observation-journal.ts"],"names":[],"mappings":"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","sourcesContent":["import * as fs from \"node:fs\";\nimport * as path from \"node:path\";\nimport type { CompletionSoundResult } from \"./completion-sound.ts\";\nimport type { PromptSettledEvent } from \"./prompt-settlement.ts\";\nimport type { ResourceAdmissionDecision } from \"./resource-admission.ts\";\nimport type { WorkloadClassification } from \"./workload-classifier.ts\";\n\n/**\n * Local-only resource observation journal (roadmap §15.1/§15.2/§20.2).\n *\n * A dedicated JSONL artifact under `.omk/runs/<promptRunId>/` — deliberately\n * NOT the hash-chained run journal: §15.2 restricts raw host facts to a\n * separate local-only artifact, and extending the run journal's closed audit\n * union would invalidate old readers. Shard plan/transition entries stay in\n * `workload-shards.jsonl` (they already journal there); this file carries\n * the remaining §20.2 entries.\n *\n * Privacy (§15.2, §20.3, §30): facts are flat primitives only — pressure\n * levels, caps, digests, durations, reason codes. Never raw memory/cpu\n * numbers, hostnames, usernames, or command text. Observability is\n * fail-open: a write/read failure degrades to diagnostics, never breaks the\n * run (probe failure is non-fatal by contract).\n */\n\nexport const RESOURCE_OBSERVATION_JOURNAL_FILE = \"resource-observations.jsonl\";\n\n/** §20.2 journal entry kinds handled by this artifact. */\nexport const RESOURCE_OBSERVATION_KINDS = [\n\t\"resource_snapshot_v1\",\n\t\"resource_admission_v1\",\n\t\"resource_lease_acquired_v1\",\n\t\"resource_lease_released_v1\",\n\t\"workload_classification_v1\",\n\t\"workload_permit_wait_v1\",\n\t\"workload_permit_acquired_v1\",\n\t\"workload_permit_released_v1\",\n\t\"prompt_settled_v1\",\n\t\"completion_sound_result_v1\",\n] as const;\n\nexport type ResourceObservationKind = (typeof RESOURCE_OBSERVATION_KINDS)[number];\n\nexport type ResourceObservationFacts = Readonly<Record<string, string | number | boolean | null>>;\n\nexport interface ResourceObservationRecord {\n\treadonly schemaVersion: 1;\n\treadonly seq: number;\n\treadonly kind: ResourceObservationKind;\n\treadonly at: string;\n\treadonly promptRunId: string;\n\treadonly facts: ResourceObservationFacts;\n}\n\n/** §15.1 protocol observation projection of one journal record. */\nexport interface ResourceProtocolObservation {\n\treadonly kind:\n\t\t| \"resource_snapshot.v1\"\n\t\t| \"resource_admission.v1\"\n\t\t| \"workload_classification.v1\"\n\t\t| \"workload_permit.v1\"\n\t\t| \"prompt_settled.v1\"\n\t\t| \"notification_result.v1\";\n\treadonly facts: ResourceObservationFacts;\n}\n\nconst PROTOCOL_KIND_BY_JOURNAL_KIND: Readonly<\n\tPartial<Record<ResourceObservationKind, ResourceProtocolObservation[\"kind\"]>>\n> = {\n\tresource_snapshot_v1: \"resource_snapshot.v1\",\n\tresource_admission_v1: \"resource_admission.v1\",\n\tworkload_classification_v1: \"workload_classification.v1\",\n\tworkload_permit_wait_v1: \"workload_permit.v1\",\n\tworkload_permit_acquired_v1: \"workload_permit.v1\",\n\tworkload_permit_released_v1: \"workload_permit.v1\",\n\tprompt_settled_v1: \"prompt_settled.v1\",\n\tcompletion_sound_result_v1: \"notification_result.v1\",\n};\n\n/**\n * Project a journal record onto the §15.1 protocol observation surface.\n * Lease entries are local-only operational detail and project to null.\n */\nexport function toProtocolObservation(record: ResourceObservationRecord): ResourceProtocolObservation | null {\n\tconst kind = PROTOCOL_KIND_BY_JOURNAL_KIND[record.kind];\n\treturn kind === undefined ? null : { kind, facts: record.facts };\n}\n\n/** §15.2: probe health and digest only — raw host values never leave the process. */\nexport function snapshotObservationFacts(snapshot: {\n\treadonly systemCpuPercent: number | null;\n\treadonly processAvailableMemoryBytes: number | null;\n\treadonly hostFreeMemoryBytes: number | null;\n\treadonly heapLimitBytes: number;\n}): ResourceObservationFacts {\n\treturn {\n\t\tcpuProbe: snapshot.systemCpuPercent !== null,\n\t\tmemoryProbe: snapshot.processAvailableMemoryBytes !== null || snapshot.hostFreeMemoryBytes !== null,\n\t\theapLimitKnown: snapshot.heapLimitBytes > 0,\n\t};\n}\n\n/** §15.2 example shape: pressure, action, and the three caps. */\nexport function admissionObservationFacts(decision: ResourceAdmissionDecision): ResourceObservationFacts {\n\treturn {\n\t\tdecisionId: decision.decisionId,\n\t\tsnapshotDigest: decision.snapshotDigest,\n\t\tpressure: decision.pressure,\n\t\taction: decision.action,\n\t\tmaxToolConcurrency: decision.maxToolConcurrency,\n\t\tmaxParallelLanes: decision.maxParallelLanes,\n\t\tmaxHeavyProcesses: decision.maxHeavyProcesses,\n\t};\n}\n\nexport function classificationObservationFacts(classification: WorkloadClassification): ResourceObservationFacts {\n\treturn {\n\t\tworkloadClass: classification.workloadClass,\n\t\tcommandFamily: classification.commandFamily,\n\t\tcomplexity: classification.complexity,\n\t\tsafeToAutoShard: classification.safeToAutoShard,\n\t\treasonCodes: classification.reasonCodes.slice(0, 8).join(\",\"),\n\t};\n}\n\nexport function settledObservationFacts(event: PromptSettledEvent): ResourceObservationFacts {\n\treturn {\n\t\toutcome: event.outcome,\n\t\tdurationMs: event.durationMs,\n\t\t...(event.terminationKind !== undefined ? { terminationKind: event.terminationKind } : {}),\n\t};\n}\n\nexport function soundObservationFacts(result: CompletionSoundResult): ResourceObservationFacts {\n\treturn {\n\t\tbackend: result.backend,\n\t\tattempted: result.attempted,\n\t\tsuccess: result.success,\n\t\t...(result.diagnostic !== undefined ? { diagnostic: result.diagnostic.slice(0, 120) } : {}),\n\t};\n}\n\nconst MAX_LINE_BYTES = 8 * 1024;\nconst MAX_RECORDS = 10_000;\n\nexport interface ResourceObservationLoadResult {\n\treadonly records: readonly ResourceObservationRecord[];\n\treadonly diagnostics: readonly string[];\n}\n\nexport class ResourceObservationJournal {\n\tprivate readonly journalPath: string;\n\tprivate readonly promptRunId: string;\n\tprivate readonly now: () => Date;\n\tprivate seq = 0;\n\tprivate disabled = false;\n\n\tconstructor(journalPath: string, promptRunId: string, now: () => Date = () => new Date()) {\n\t\tthis.journalPath = journalPath;\n\t\tthis.promptRunId = promptRunId;\n\t\tthis.now = now;\n\t}\n\n\tstatic open(cwd: string, promptRunId: string, now?: () => Date): ResourceObservationJournal {\n\t\treturn new ResourceObservationJournal(\n\t\t\tpath.join(cwd, \".omk\", \"runs\", promptRunId, RESOURCE_OBSERVATION_JOURNAL_FILE),\n\t\t\tpromptRunId,\n\t\t\tnow,\n\t\t);\n\t}\n\n\tget filePath(): string {\n\t\treturn this.journalPath;\n\t}\n\n\t/** Fail-open append: returns false (and stops trying) instead of throwing. */\n\trecord(kind: ResourceObservationKind, facts: ResourceObservationFacts): boolean {\n\t\tif (this.disabled || this.seq >= MAX_RECORDS) return false;\n\t\tconst entry: ResourceObservationRecord = {\n\t\t\tschemaVersion: 1,\n\t\t\tseq: this.seq + 1,\n\t\t\tkind,\n\t\t\tat: this.now().toISOString(),\n\t\t\tpromptRunId: this.promptRunId,\n\t\t\tfacts,\n\t\t};\n\t\tconst line = `${JSON.stringify(entry)}\\n`;\n\t\tif (line.length > MAX_LINE_BYTES) return false;\n\t\ttry {\n\t\t\tfs.mkdirSync(path.dirname(this.journalPath), { recursive: true });\n\t\t\tfs.appendFileSync(this.journalPath, line, \"utf8\");\n\t\t\tthis.seq = entry.seq;\n\t\t\treturn true;\n\t\t} catch {\n\t\t\t// Observability must never break the run; stop retrying this run.\n\t\t\tthis.disabled = true;\n\t\t\treturn false;\n\t\t}\n\t}\n\n\t/** Fail-open load: malformed lines become diagnostics, never throws. */\n\tload(): ResourceObservationLoadResult {\n\t\tlet raw: string;\n\t\ttry {\n\t\t\traw = fs.readFileSync(this.journalPath, \"utf8\");\n\t\t} catch {\n\t\t\treturn { records: [], diagnostics: [] };\n\t\t}\n\t\tconst records: ResourceObservationRecord[] = [];\n\t\tconst diagnostics: string[] = [];\n\t\tconst lines = raw.split(\"\\n\");\n\t\tfor (let index = 0; index < lines.length && records.length < MAX_RECORDS; index++) {\n\t\t\tconst line = lines[index].trim();\n\t\t\tif (line === \"\") continue;\n\t\t\tconst parsed = parseObservationLine(line);\n\t\t\tif (parsed === null) {\n\t\t\t\tdiagnostics.push(`line ${index + 1}: invalid observation record`);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\trecords.push(parsed);\n\t\t}\n\t\treturn { records, diagnostics };\n\t}\n}\n\nconst KIND_SET: ReadonlySet<string> = new Set(RESOURCE_OBSERVATION_KINDS);\n\nfunction parseObservationLine(line: string): ResourceObservationRecord | null {\n\tif (line.length > MAX_LINE_BYTES) return null;\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(line);\n\t} catch {\n\t\treturn null;\n\t}\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) return null;\n\tconst record = value as Record<string, unknown>;\n\tif (record.schemaVersion !== 1) return null;\n\tif (typeof record.seq !== \"number\" || !Number.isSafeInteger(record.seq) || record.seq < 1) return null;\n\tif (typeof record.kind !== \"string\" || !KIND_SET.has(record.kind)) return null;\n\tif (typeof record.at !== \"string\" || typeof record.promptRunId !== \"string\") return null;\n\tif (typeof record.facts !== \"object\" || record.facts === null || Array.isArray(record.facts)) return null;\n\tfor (const factValue of Object.values(record.facts)) {\n\t\tconst kind = typeof factValue;\n\t\tif (factValue !== null && kind !== \"string\" && kind !== \"number\" && kind !== \"boolean\") return null;\n\t}\n\treturn record as unknown as ResourceObservationRecord;\n}\n"]}

package/dist/core/resource-safety-gate.d.ts

@@ -0,0 +1,54 @@
+import type { ResourceAdmissionDecision, ResourcePressure, ResourceReasonCode } from "./resource-admission.ts";
+import type { WorkloadClassification } from "./workload-classifier.ts";
+/**
+ * Pure resource safety gate decision (OMK v0.97.x roadmap §11, M3/PR4).
+ *
+ * Maps (workload classification × admission decision) to a gate verdict.
+ * This module holds no permits and spawns nothing — the shared permit pool
+ * and the bash/launch integration consume these verdicts in the next slice.
+ *
+ * Order contract (§9.4, §22.2): command safety runs FIRST and stays
+ * authoritative. The input requires the literal `commandSafety: "allowed"`
+ * so a call site cannot even type-check unless the command already passed
+ * the safety gate; resource pressure can only throttle or defer an
+ * already-allowed command, never re-admit a blocked one.
+ *
+ * Fail-closed only where side effects matter (§4.6): heavy work and opaque
+ * complex shell are deferred at critical pressure, while light reads and
+ * bounded IO stay allowed so the agent remains usable (§21).
+ */
+export interface ResourceSafetyGateInput {
+    /** §9.4: structurally requires the command-safety gate to have allowed the command. */
+    readonly commandSafety: "allowed";
+    readonly classification: WorkloadClassification;
+    readonly decision: ResourceAdmissionDecision;
+}
+/** §11.3 structured block result. Bounded: no raw host values, paths, or identities. */
+export interface ResourcePressureBlock {
+    readonly kind: "resource_pressure";
+    readonly pressure: ResourcePressure;
+    readonly action: "defer-heavy";
+    readonly reasonCodes: readonly ResourceReasonCode[];
+    readonly requiredAction: string;
+}
+export type ResourceSafetyGateVerdict = {
+    readonly kind: "allow";
+} | {
+    readonly kind: "require-permit";
+    readonly weight: 1 | 2;
+} | {
+    readonly kind: "block";
+    readonly block: ResourcePressureBlock;
+};
+export declare const RESOURCE_PRESSURE_REQUIRED_ACTION = "Create a bounded shard plan or free resources before retrying.";
+/**
+ * Decide the §11.2 gate behavior for one already-safety-allowed command.
+ *
+ * | pressure    | light | io    | cpu      | heavy / memory | unknown complex shell |
+ * | ----------- | ----- | ----- | -------- | -------------- | --------------------- |
+ * | normal      | allow | allow | permit   | permit         | permit, no rewrite    |
+ * | constrained | allow | allow | permit 1 | permit 1       | permit 1, no rewrite  |
+ * | critical    | allow | allow | permit 1 | block/defer    | block/defer           |
+ */
+export declare function decideResourceSafetyGate(input: ResourceSafetyGateInput): ResourceSafetyGateVerdict;
+//# sourceMappingURL=resource-safety-gate.d.ts.map

package/dist/core/resource-safety-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-safety-gate.d.ts","sourceRoot":"","sources":["../../src/core/resource-safety-gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC/G,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,WAAW,uBAAuB;IACvC,wFAAuF;IACvF,QAAQ,CAAC,aAAa,EAAE,SAAS,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,sBAAsB,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;CAC7C;AAED,yFAAwF;AACxF,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACpD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,yBAAyB,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAErE,eAAO,MAAM,iCAAiC,mEAAmE,CAAC;AAElH;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,uBAAuB,GAAG,yBAAyB,CA2ClG","sourcesContent":["import type { ResourceAdmissionDecision, ResourcePressure, ResourceReasonCode } from \"./resource-admission.ts\";\nimport type { WorkloadClassification } from \"./workload-classifier.ts\";\n\n/**\n * Pure resource safety gate decision (OMK v0.97.x roadmap §11, M3/PR4).\n *\n * Maps (workload classification × admission decision) to a gate verdict.\n * This module holds no permits and spawns nothing — the shared permit pool\n * and the bash/launch integration consume these verdicts in the next slice.\n *\n * Order contract (§9.4, §22.2): command safety runs FIRST and stays\n * authoritative. The input requires the literal `commandSafety: \"allowed\"`\n * so a call site cannot even type-check unless the command already passed\n * the safety gate; resource pressure can only throttle or defer an\n * already-allowed command, never re-admit a blocked one.\n *\n * Fail-closed only where side effects matter (§4.6): heavy work and opaque\n * complex shell are deferred at critical pressure, while light reads and\n * bounded IO stay allowed so the agent remains usable (§21).\n */\n\nexport interface ResourceSafetyGateInput {\n\t/** §9.4: structurally requires the command-safety gate to have allowed the command. */\n\treadonly commandSafety: \"allowed\";\n\treadonly classification: WorkloadClassification;\n\treadonly decision: ResourceAdmissionDecision;\n}\n\n/** §11.3 structured block result. Bounded: no raw host values, paths, or identities. */\nexport interface ResourcePressureBlock {\n\treadonly kind: \"resource_pressure\";\n\treadonly pressure: ResourcePressure;\n\treadonly action: \"defer-heavy\";\n\treadonly reasonCodes: readonly ResourceReasonCode[];\n\treadonly requiredAction: string;\n}\n\nexport type ResourceSafetyGateVerdict =\n\t| { readonly kind: \"allow\" }\n\t| { readonly kind: \"require-permit\"; readonly weight: 1 | 2 }\n\t| { readonly kind: \"block\"; readonly block: ResourcePressureBlock };\n\nexport const RESOURCE_PRESSURE_REQUIRED_ACTION = \"Create a bounded shard plan or free resources before retrying.\";\n\n/**\n * Decide the §11.2 gate behavior for one already-safety-allowed command.\n *\n * | pressure    | light | io    | cpu      | heavy / memory | unknown complex shell |\n * | ----------- | ----- | ----- | -------- | -------------- | --------------------- |\n * | normal      | allow | allow | permit   | permit         | permit, no rewrite    |\n * | constrained | allow | allow | permit 1 | permit 1       | permit 1, no rewrite  |\n * | critical    | allow | allow | permit 1 | block/defer    | block/defer           |\n */\nexport function decideResourceSafetyGate(input: ResourceSafetyGateInput): ResourceSafetyGateVerdict {\n\tconst { classification, decision } = input;\n\tconst critical = decision.pressure === \"critical\";\n\n\tif (classification.workloadClass === \"light\") {\n\t\treturn { kind: \"allow\" };\n\t}\n\tif (classification.workloadClass === \"io\") {\n\t\t// Critical still allows bounded IO; the run lease already caps overall\n\t\t// tool concurrency (§11.2 \"allow with cap\").\n\t\treturn { kind: \"allow\" };\n\t}\n\tif (classification.workloadClass === \"cpu\") {\n\t\treturn { kind: \"require-permit\", weight: 1 };\n\t}\n\n\t// heavy, memory (heavy-equivalent — the §11.2 table has no softer column\n\t// for memory-bound work), and unknown workloads.\n\tconst heavyEquivalent = classification.workloadClass === \"heavy\" || classification.workloadClass === \"memory\";\n\tconst opaqueComplexShell =\n\t\tclassification.workloadClass === \"unknown\" && classification.complexity === \"complex-shell\";\n\n\tif (critical && (heavyEquivalent || opaqueComplexShell)) {\n\t\treturn {\n\t\t\tkind: \"block\",\n\t\t\tblock: {\n\t\t\t\tkind: \"resource_pressure\",\n\t\t\t\tpressure: decision.pressure,\n\t\t\t\taction: \"defer-heavy\",\n\t\t\t\treasonCodes: decision.reasons,\n\t\t\t\trequiredAction: RESOURCE_PRESSURE_REQUIRED_ACTION,\n\t\t\t},\n\t\t};\n\t}\n\tif (heavyEquivalent) {\n\t\t// §10.3: container builds may consume double weight in the permit pool.\n\t\treturn { kind: \"require-permit\", weight: classification.commandFamily === \"container-build\" ? 2 : 1 };\n\t}\n\t// unknown (simple argv or, below critical, complex shell): permit-gated so\n\t// fanout stays bounded, but never blocked outright below critical, and a\n\t// simple unknown binary stays runnable even at critical (§21: the agent\n\t// must remain usable).\n\treturn { kind: \"require-permit\", weight: 1 };\n}\n"]}

package/dist/core/resource-safety-gate.js

@@ -0,0 +1,51 @@
+export const RESOURCE_PRESSURE_REQUIRED_ACTION = "Create a bounded shard plan or free resources before retrying.";
+/**
+ * Decide the §11.2 gate behavior for one already-safety-allowed command.
+ *
+ * | pressure    | light | io    | cpu      | heavy / memory | unknown complex shell |
+ * | ----------- | ----- | ----- | -------- | -------------- | --------------------- |
+ * | normal      | allow | allow | permit   | permit         | permit, no rewrite    |
+ * | constrained | allow | allow | permit 1 | permit 1       | permit 1, no rewrite  |
+ * | critical    | allow | allow | permit 1 | block/defer    | block/defer           |
+ */
+export function decideResourceSafetyGate(input) {
+    const { classification, decision } = input;
+    const critical = decision.pressure === "critical";
+    if (classification.workloadClass === "light") {
+        return { kind: "allow" };
+    }
+    if (classification.workloadClass === "io") {
+        // Critical still allows bounded IO; the run lease already caps overall
+        // tool concurrency (§11.2 "allow with cap").
+        return { kind: "allow" };
+    }
+    if (classification.workloadClass === "cpu") {
+        return { kind: "require-permit", weight: 1 };
+    }
+    // heavy, memory (heavy-equivalent — the §11.2 table has no softer column
+    // for memory-bound work), and unknown workloads.
+    const heavyEquivalent = classification.workloadClass === "heavy" || classification.workloadClass === "memory";
+    const opaqueComplexShell = classification.workloadClass === "unknown" && classification.complexity === "complex-shell";
+    if (critical && (heavyEquivalent || opaqueComplexShell)) {
+        return {
+            kind: "block",
+            block: {
+                kind: "resource_pressure",
+                pressure: decision.pressure,
+                action: "defer-heavy",
+                reasonCodes: decision.reasons,
+                requiredAction: RESOURCE_PRESSURE_REQUIRED_ACTION,
+            },
+        };
+    }
+    if (heavyEquivalent) {
+        // §10.3: container builds may consume double weight in the permit pool.
+        return { kind: "require-permit", weight: classification.commandFamily === "container-build" ? 2 : 1 };
+    }
+    // unknown (simple argv or, below critical, complex shell): permit-gated so
+    // fanout stays bounded, but never blocked outright below critical, and a
+    // simple unknown binary stays runnable even at critical (§21: the agent
+    // must remain usable).
+    return { kind: "require-permit", weight: 1 };
+}
+//# sourceMappingURL=resource-safety-gate.js.map

package/dist/core/resource-safety-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-safety-gate.js","sourceRoot":"","sources":["../../src/core/resource-safety-gate.ts"],"names":[],"mappings":"AA0CA,MAAM,CAAC,MAAM,iCAAiC,GAAG,gEAAgE,CAAC;AAElH;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAA8B,EAA6B;IACnG,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,KAAK,UAAU,CAAC;IAElD,IAAI,cAAc,CAAC,aAAa,KAAK,OAAO,EAAE,CAAC;QAC9C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,cAAc,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3C,uEAAuE;QACvE,8CAA6C;QAC7C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC1B,CAAC;IACD,IAAI,cAAc,CAAC,aAAa,KAAK,KAAK,EAAE,CAAC;QAC5C,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;IAC9C,CAAC;IAED,4EAAyE;IACzE,iDAAiD;IACjD,MAAM,eAAe,GAAG,cAAc,CAAC,aAAa,KAAK,OAAO,IAAI,cAAc,CAAC,aAAa,KAAK,QAAQ,CAAC;IAC9G,MAAM,kBAAkB,GACvB,cAAc,CAAC,aAAa,KAAK,SAAS,IAAI,cAAc,CAAC,UAAU,KAAK,eAAe,CAAC;IAE7F,IAAI,QAAQ,IAAI,CAAC,eAAe,IAAI,kBAAkB,CAAC,EAAE,CAAC;QACzD,OAAO;YACN,IAAI,EAAE,OAAO;YACb,KAAK,EAAE;gBACN,IAAI,EAAE,mBAAmB;gBACzB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,MAAM,EAAE,aAAa;gBACrB,WAAW,EAAE,QAAQ,CAAC,OAAO;gBAC7B,cAAc,EAAE,iCAAiC;aACjD;SACD,CAAC;IACH,CAAC;IACD,IAAI,eAAe,EAAE,CAAC;QACrB,yEAAwE;QACxE,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,cAAc,CAAC,aAAa,KAAK,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvG,CAAC;IACD,2EAA2E;IAC3E,yEAAyE;IACzE,yEAAwE;IACxE,uBAAuB;IACvB,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAAA,CAC7C","sourcesContent":["import type { ResourceAdmissionDecision, ResourcePressure, ResourceReasonCode } from \"./resource-admission.ts\";\nimport type { WorkloadClassification } from \"./workload-classifier.ts\";\n\n/**\n * Pure resource safety gate decision (OMK v0.97.x roadmap §11, M3/PR4).\n *\n * Maps (workload classification × admission decision) to a gate verdict.\n * This module holds no permits and spawns nothing — the shared permit pool\n * and the bash/launch integration consume these verdicts in the next slice.\n *\n * Order contract (§9.4, §22.2): command safety runs FIRST and stays\n * authoritative. The input requires the literal `commandSafety: \"allowed\"`\n * so a call site cannot even type-check unless the command already passed\n * the safety gate; resource pressure can only throttle or defer an\n * already-allowed command, never re-admit a blocked one.\n *\n * Fail-closed only where side effects matter (§4.6): heavy work and opaque\n * complex shell are deferred at critical pressure, while light reads and\n * bounded IO stay allowed so the agent remains usable (§21).\n */\n\nexport interface ResourceSafetyGateInput {\n\t/** §9.4: structurally requires the command-safety gate to have allowed the command. */\n\treadonly commandSafety: \"allowed\";\n\treadonly classification: WorkloadClassification;\n\treadonly decision: ResourceAdmissionDecision;\n}\n\n/** §11.3 structured block result. Bounded: no raw host values, paths, or identities. */\nexport interface ResourcePressureBlock {\n\treadonly kind: \"resource_pressure\";\n\treadonly pressure: ResourcePressure;\n\treadonly action: \"defer-heavy\";\n\treadonly reasonCodes: readonly ResourceReasonCode[];\n\treadonly requiredAction: string;\n}\n\nexport type ResourceSafetyGateVerdict =\n\t| { readonly kind: \"allow\" }\n\t| { readonly kind: \"require-permit\"; readonly weight: 1 | 2 }\n\t| { readonly kind: \"block\"; readonly block: ResourcePressureBlock };\n\nexport const RESOURCE_PRESSURE_REQUIRED_ACTION = \"Create a bounded shard plan or free resources before retrying.\";\n\n/**\n * Decide the §11.2 gate behavior for one already-safety-allowed command.\n *\n * | pressure    | light | io    | cpu      | heavy / memory | unknown complex shell |\n * | ----------- | ----- | ----- | -------- | -------------- | --------------------- |\n * | normal      | allow | allow | permit   | permit         | permit, no rewrite    |\n * | constrained | allow | allow | permit 1 | permit 1       | permit 1, no rewrite  |\n * | critical    | allow | allow | permit 1 | block/defer    | block/defer           |\n */\nexport function decideResourceSafetyGate(input: ResourceSafetyGateInput): ResourceSafetyGateVerdict {\n\tconst { classification, decision } = input;\n\tconst critical = decision.pressure === \"critical\";\n\n\tif (classification.workloadClass === \"light\") {\n\t\treturn { kind: \"allow\" };\n\t}\n\tif (classification.workloadClass === \"io\") {\n\t\t// Critical still allows bounded IO; the run lease already caps overall\n\t\t// tool concurrency (§11.2 \"allow with cap\").\n\t\treturn { kind: \"allow\" };\n\t}\n\tif (classification.workloadClass === \"cpu\") {\n\t\treturn { kind: \"require-permit\", weight: 1 };\n\t}\n\n\t// heavy, memory (heavy-equivalent — the §11.2 table has no softer column\n\t// for memory-bound work), and unknown workloads.\n\tconst heavyEquivalent = classification.workloadClass === \"heavy\" || classification.workloadClass === \"memory\";\n\tconst opaqueComplexShell =\n\t\tclassification.workloadClass === \"unknown\" && classification.complexity === \"complex-shell\";\n\n\tif (critical && (heavyEquivalent || opaqueComplexShell)) {\n\t\treturn {\n\t\t\tkind: \"block\",\n\t\t\tblock: {\n\t\t\t\tkind: \"resource_pressure\",\n\t\t\t\tpressure: decision.pressure,\n\t\t\t\taction: \"defer-heavy\",\n\t\t\t\treasonCodes: decision.reasons,\n\t\t\t\trequiredAction: RESOURCE_PRESSURE_REQUIRED_ACTION,\n\t\t\t},\n\t\t};\n\t}\n\tif (heavyEquivalent) {\n\t\t// §10.3: container builds may consume double weight in the permit pool.\n\t\treturn { kind: \"require-permit\", weight: classification.commandFamily === \"container-build\" ? 2 : 1 };\n\t}\n\t// unknown (simple argv or, below critical, complex shell): permit-gated so\n\t// fanout stays bounded, but never blocked outright below critical, and a\n\t// simple unknown binary stays runnable even at critical (§21: the agent\n\t// must remain usable).\n\treturn { kind: \"require-permit\", weight: 1 };\n}\n"]}