nexakit 0.0.0-stage → 0.2.0

package/src/client-selective-config.js

@@ -0,0 +1,195 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+import { copyInertJson, copyBytes } from "./client-output-json.js";
+import { hash } from "./client-runtime-core.js";
+
+export const SELECTIVE_ID = "https://agent-toolkit.local/schemas/agent-client-selective-config.schema.json";
+export const SELECTORS = Object.freeze({ "personal-settings": Object.freeze(["hooks", "apiKeyHelper", "disableAllHooks"]), "global-state": Object.freeze(["mcpServers"]) });
+class ScanFailure extends Error { constructor(code) { super(code); this.code = code; } }
+const fail = code => { throw new ScanFailure(code); };
+const white = cp => cp === 32 || cp === 9 || cp === 10 || cp === 13;
+const digit = cp => cp >= 48 && cp <= 57;
+const utf8Width = cp => cp < 128 ? 1 : cp < 2048 ? 2 : cp < 65536 ? 3 : 4;
+
+/** Incremental byte grammar. Discarded values never become strings/objects. */
+export function createSelectiveConfigParser(schema, sourceId, limits) {
+  const s = copyInertJson(schema), l = copyInertJson(limits);
+  if (s.$id !== SELECTIVE_ID || typeof sourceId !== "string" || !Object.hasOwn(SELECTORS, sourceId)) throw Error("Unsupported selective contract");
+  const ajv = new Ajv2020({ strict: true }); ajv.addSchema(s);
+  const validLimits = ajv.compile({ $ref: SELECTIVE_ID + "#/$defs/limits" });
+  const validReport = ajv.compile({ $ref: SELECTIVE_ID + "#/$defs/report" });
+  if (!validLimits(l) || l.blockBytes > l.maxBytes) throw Error("Invalid selective limits");
+  const names = SELECTORS[sourceId];
+  const fields = names.map(name => ({ name, present: false, type: null, empty: null, booleanValue: null }));
+  let stack = [], root = "start", token = null, bytes = 0, nodes = 0, keys = 0, peakDepth = 0, peakKeyDigests = 0, digests = 0;
+  let utfLeft = 0, utfValue = 0, utfMin = 0, error = null, closed = false;
+
+  function item() { if (++nodes > l.maxNodes) fail("selective-node-limit"); }
+  function completeValue() {
+    if (!stack.length) { root = "end"; return; }
+    const f = stack.at(-1); f.items++; f.phase = "comma-or-end"; f.selector = null;
+  }
+  function beginValue(cp, tag) {
+    item();
+    const type = cp === 123 ? "object" : cp === 91 ? "array" : cp === 34 ? "string" : cp === 116 || cp === 102 ? "boolean" : cp === 110 ? "null" : cp === 45 || digit(cp) ? "number" : null;
+    if (!type) fail("selective-invalid-json");
+    if (tag) { tag.present = true; tag.type = type; }
+    if (type === "object" || type === "array") {
+      const f = { type, phase: type === "object" ? "key-or-end" : "value-or-end", items: 0, selector: null, tag, keys: new Set() };
+      stack.push(f); peakDepth = Math.max(peakDepth, stack.length);
+      if (stack.length > l.maxDepth) fail("selective-depth-limit");
+    } else if (type === "string") beginString(false, tag);
+    else if (type === "number") token = { kind: "number", phase: cp === 45 ? "minus" : cp === 48 ? "zero" : "integer", tag };
+    else token = { kind: "literal", word: cp === 116 ? "true" : cp === 102 ? "false" : "null", index: 1, tag };
+  }
+  function beginString(key, tag) {
+    token = { kind: "string", key, tag, escape: false, hexLeft: 0, hex: 0, high: null, needSlash: false, needU: false,
+      count: 0, keyBytes: 0, candidates: key && stack.length === 1 ? [...names] : [], digest: key ? createHash("sha256") : null };
+  }
+  function emitStringCodepoint(t, cp) {
+    if (t.key) {
+      t.keyBytes += utf8Width(cp); if (t.keyBytes > l.maxKeyBytes) fail("selective-key-bytes-limit");
+      // Only names are hashed transiently. No hash or textual decoding of values.
+      t.digest.update(Buffer.from(String.fromCodePoint(cp), "utf8"));
+      t.candidates = t.candidates.filter(n => t.count < n.length && n.charCodeAt(t.count) === cp);
+    }
+    t.count++; // String values are counted, never concatenated or decoded to text.
+  }
+  function endString(t) {
+    if (t.high !== null) fail("selective-invalid-unicode");
+    if (t.key) {
+      const f = stack.at(-1), fingerprint = t.digest.digest("hex");
+      if (f.keys.has(fingerprint)) fail("selective-duplicate-key");
+      if (++keys > l.maxKeys) fail("selective-key-limit");
+      f.keys.add(fingerprint); digests++; peakKeyDigests = Math.max(peakKeyDigests, digests);
+      const selected = t.candidates.find(n => n.length === t.count);
+      f.selector = selected ? fields.find(v => v.name === selected) : null; f.phase = "colon";
+    } else { if (t.tag) t.tag.empty = t.count === 0; completeValue(); }
+    token = null;
+  }
+  function stringChar(cp) {
+    const t = token;
+    if (t.needSlash) { if (cp !== 92) fail("selective-invalid-unicode"); t.needSlash = false; t.needU = true; return; }
+    if (t.needU) { if (cp !== 117) fail("selective-invalid-unicode"); t.needU = false; t.hexLeft = 4; t.hex = 0; return; }
+    if (t.hexLeft) {
+      const n = cp >= 48 && cp <= 57 ? cp - 48 : cp >= 65 && cp <= 70 ? cp - 55 : cp >= 97 && cp <= 102 ? cp - 87 : -1;
+      if (n < 0) fail("selective-invalid-json"); t.hex = t.hex * 16 + n;
+      if (--t.hexLeft === 0) {
+        const u = t.hex;
+        if (t.high !== null) {
+          if (u < 0xdc00 || u > 0xdfff) fail("selective-invalid-unicode");
+          const value = 0x10000 + (t.high - 0xd800) * 1024 + u - 0xdc00; t.high = null; emitStringCodepoint(t, value);
+        } else if (u >= 0xd800 && u <= 0xdbff) { t.high = u; t.needSlash = true; }
+        else if (u >= 0xdc00 && u <= 0xdfff) fail("selective-invalid-unicode");
+        else emitStringCodepoint(t, u);
+      } return;
+    }
+    if (t.escape) {
+      t.escape = false;
+      if (cp === 117) { t.hexLeft = 4; t.hex = 0; return; }
+      const escaped = { 34: 34, 92: 92, 47: 47, 98: 8, 102: 12, 110: 10, 114: 13, 116: 9 };
+      if (!Object.hasOwn(escaped, cp)) fail("selective-invalid-json"); emitStringCodepoint(t, escaped[cp]); return;
+    }
+    if (cp === 34) endString(t);
+    else if (cp === 92) t.escape = true;
+    else { if (cp < 32) fail("selective-invalid-json"); emitStringCodepoint(t, cp); }
+  }
+  function numberChar(cp) {
+    const t = token, p = t.phase;
+    if (p === "minus") { if (!digit(cp)) fail("selective-invalid-json"); t.phase = cp === 48 ? "zero" : "integer"; return true; }
+    if (p === "zero" || p === "integer" || p === "fraction") {
+      if (digit(cp)) { if (p === "zero") fail("selective-invalid-json"); return true; }
+      if (cp === 46 && p !== "fraction") { t.phase = "dot"; return true; }
+      if (cp === 101 || cp === 69) { t.phase = "exponent"; return true; }
+      return false;
+    }
+    if (p === "dot") { if (!digit(cp)) fail("selective-invalid-json"); t.phase = "fraction"; return true; }
+    if (p === "exponent") { if (cp === 43 || cp === 45) { t.phase = "exponent-sign"; return true; } if (!digit(cp)) fail("selective-invalid-json"); t.phase = "exponent-digits"; return true; }
+    if (p === "exponent-sign") { if (!digit(cp)) fail("selective-invalid-json"); t.phase = "exponent-digits"; return true; }
+    if (p === "exponent-digits") return digit(cp);
+    fail("selective-invalid-json");
+  }
+  function closeContainer(cp) {
+    const f = stack.at(-1);
+    if (cp !== (f.type === "object" ? 125 : 93)) fail("selective-invalid-json");
+    if (f.tag) f.tag.empty = f.items === 0;
+    digests -= f.keys.size; stack.pop(); completeValue();
+  }
+  function grammar(cp) {
+    if (token) {
+      if (token.kind === "string") { stringChar(cp); return; }
+      if (token.kind === "literal") {
+        const t = token;
+        if (cp !== t.word.charCodeAt(t.index++)) fail("selective-invalid-json");
+        if (t.index === t.word.length) {
+          if (t.tag?.name === "disableAllHooks" && t.word !== "null") t.tag.booleanValue = t.word === "true";
+          token = null; completeValue();
+        } return;
+      }
+      if (numberChar(cp)) return;
+      token = null; completeValue(); // Re-process the number's delimiter below.
+    }
+    if (white(cp)) return;
+    if (root === "end") fail("selective-invalid-json");
+    if (!stack.length) { if (cp !== 123) fail("selective-root-object-required"); root = "running"; beginValue(cp, null); return; }
+    const f = stack.at(-1);
+    if (f.phase === "key-or-end" || f.phase === "key-only") {
+      if (cp === 125 && f.phase === "key-or-end") { closeContainer(cp); return; }
+      if (cp !== 34) fail("selective-invalid-json"); item(); beginString(true, null); return;
+    }
+    if (f.phase === "colon") { if (cp !== 58) fail("selective-invalid-json"); f.phase = "value"; return; }
+    if (f.phase === "value-or-end" && cp === 93) { closeContainer(cp); return; }
+    if (f.phase === "value" || f.phase === "value-or-end" || f.phase === "value-only") { beginValue(cp, f.selector); return; }
+    if (f.phase === "comma-or-end") {
+      if (cp === 44) f.phase = f.type === "object" ? "key-only" : "value-only";
+      else closeContainer(cp);
+      return;
+    }
+    fail("selective-invalid-json");
+  }
+  function byte(b) {
+    if (utfLeft) {
+      if ((b & 0xc0) !== 0x80) fail("selective-invalid-utf8"); utfValue = utfValue * 64 + (b & 63);
+      if (--utfLeft === 0) {
+        if (utfValue < utfMin || utfValue > 0x10ffff || utfValue >= 0xd800 && utfValue <= 0xdfff) fail("selective-invalid-utf8");
+        grammar(utfValue);
+      } return;
+    }
+    if (b < 128) grammar(b);
+    else if (b >= 0xc2 && b <= 0xdf) { utfLeft = 1; utfValue = b & 31; utfMin = 128; }
+    else if (b >= 0xe0 && b <= 0xef) { utfLeft = 2; utfValue = b & 15; utfMin = 2048; }
+    else if (b >= 0xf0 && b <= 0xf4) { utfLeft = 3; utfValue = b & 7; utfMin = 65536; }
+    else fail("selective-invalid-utf8");
+  }
+  function abandon(e) { error = e instanceof ScanFailure ? e.code : "selective-block-invalid"; stack = []; token = null; digests = 0; }
+  function report(final = false) {
+    const ok = final && error === null && root === "end";
+    const output = { scope: "selective-local-structure-only", sourceId, state: ok ? "observed" : error ? "invalid" : "incomplete",
+      provenance: "provided-bytes-structure", fields: ok ? copyInertJson(fields) : [], projectionSha256: ok ? hash({ sourceId, fields }) : null,
+      inferenceRequested: false, nativeExecuted: false, runtimeReady: false, verifiedAdmission: false,
+      externalBillingVerified: false, effectiveControlsVerified: false,
+      stats: { bytes, nodes, keys, peakDepth, peakKeyDigests, retainedRawBytes: 0, retainedValueTextBytes: 0 },
+      reasons: [ok ? "selective-observed" : error ?? "selective-incomplete"] };
+    if (!validReport(output)) throw Error("Selective report invariant failed");
+    return output;
+  }
+  return Object.freeze({
+    push(input) {
+      if (closed || error) return report(false);
+      try {
+        if (types.isProxy(input) || !types.isUint8Array(input)) fail("selective-block-invalid");
+        const b = copyBytes(input, l.blockBytes); bytes += b.length;
+        if (bytes > l.maxBytes) fail("selective-byte-limit");
+        for (let i = 0; i < b.length; i++) byte(b[i]);
+      } catch (e) { abandon(e); }
+      return report(false);
+    },
+    finish() {
+      if (closed) { abandon(new ScanFailure("selective-closed")); return report(false); }
+      closed = true;
+      if (!error && (utfLeft || token || stack.length || root !== "end")) abandon(new ScanFailure("selective-truncated"));
+      return report(true);
+    }
+  });
+}

package/src/client-selective-files.js

@@ -0,0 +1,126 @@
+import { IS_WINDOWS, warnPlatformPermissions } from './platform.js';
+import fs from "node:fs/promises";
+import path from "node:path";
+import { constants } from "node:fs";
+import { types } from "node:util";
+import Ajv2020 from "ajv/dist/2020.js";
+import { copyInertJson } from "./client-output-json.js";
+import { hash } from "./client-runtime-core.js";
+import { createSelectiveConfigParser, SELECTIVE_ID } from "./client-selective-config.js";
+
+const permits = new WeakMap();
+class ReadFailure extends Error { constructor(code) { super(code); this.code = code; } }
+const fail = code => { throw new ReadFailure(code); };
+const monoMs = () => Number(process.hrtime.bigint() / 1000000n);
+const statIdentity = s => [s.dev, s.ino, s.uid, s.gid, s.mode, s.nlink, s.size, s.mtimeMs, s.ctimeMs];
+const equal = (a, b) => JSON.stringify(statIdentity(a)) === JSON.stringify(statIdentity(b));
+const safePath = p => typeof p === "string" && path.isAbsolute(p) && path.normalize(p) === p && !/[\x00-\x1f\x7f]/.test(p);
+
+// Only trusted orchestration can turn the human's exact-path approval into a handle.
+export function createSelectiveReadPermit(configuration) {
+  const h = Object.freeze(Object.create(null)); permits.set(h, { binding: hash(copyInertJson(configuration)), used: false, live: true }); return h;
+}
+export function revokeSelectiveReadPermit(h) { const p = permits.get(h); if (p) p.live = false; }
+
+/** Reads exactly two approved sources. No settings edits, clients or account queries. */
+export function createSelectiveFileReader(schema, configuration, authorization, dependencies = {}) {
+  const s = copyInertJson(schema), cfg = copyInertJson(configuration);
+  if (s.$id !== SELECTIVE_ID) throw Error("Unsupported selective schema");
+  const ajv = new Ajv2020({ strict: true }); ajv.addSchema(s); const limitsValid = ajv.compile({ $ref: SELECTIVE_ID + "#/$defs/limits" });
+  const reportValid = ajv.compile({ $ref: SELECTIVE_ID + "#/$defs/fileReport" });
+  if (Object.keys(cfg).sort().join() !== "aggregateBytes,limits,sources,timeoutMs" || !limitsValid(cfg.limits) || cfg.limits.blockBytes > cfg.limits.maxBytes ||
+      !Number.isSafeInteger(cfg.timeoutMs) || cfg.timeoutMs < 1 || cfg.timeoutMs > 30000 || !Number.isSafeInteger(cfg.aggregateBytes) || cfg.aggregateBytes < 1 || cfg.aggregateBytes > 2097152 ||
+      !Array.isArray(cfg.sources) || cfg.sources.length !== 2 || cfg.sources[0].sourceId !== "personal-settings" || cfg.sources[1].sourceId !== "global-state" ||
+      cfg.sources.some(e => Object.keys(e).sort().join() !== "path,sourceId" || !safePath(e.path)) || cfg.sources[0].path === cfg.sources[1].path) throw Error("Invalid selective file configuration");
+  const io = { ...fs, ...dependencies.io }, mono = dependencies.monotonic ?? monoMs, checkpoint = dependencies.checkpoint ?? (async () => {});
+  const uid = process.getuid?.(); let invoked = false;
+  const clock = () => { const n = mono(); if (!Number.isFinite(n) || n < 0) fail("selective-clock-unavailable"); return n; };
+  const errorCode = e => e instanceof ReadFailure ? e.code : "selective-file-unconfirmed";
+  async function physical(name) {
+    let curr = path.parse(name).root; const identities = [];
+    const parts = name.slice(curr.length).split(path.sep).filter(Boolean);
+    if (parts.length > 64) fail("selective-path-unsafe");
+    for (const [i, part] of parts.entries()) {
+      curr = path.join(curr, part); const st = await io.lstat(curr);
+      if (st.isSymbolicLink() || i < parts.length - 1 && !st.isDirectory()) fail("selective-path-unsafe");
+      if (i < parts.length - 1) identities.push([st.dev, st.ino, st.uid, st.mode]);
+    }
+    return identities;
+  }
+  function allowed(st) {
+    if (!st.isFile() || st.isSymbolicLink() || (!IS_WINDOWS && st.uid !== uid) || st.nlink !== 1 || (!IS_WINDOWS && st.mode & 0o022)) fail("selective-file-unsafe");
+    if (st.size > cfg.limits.maxBytes) fail("selective-file-limit");
+  }
+  return Object.freeze({ async run(...args) {
+    const r = { scope: "selective-local-structure-only", state: "blocked", sources: [],
+      inferenceRequested: false, nativeExecuted: false, runtimeReady: false, verifiedAdmission: false,
+      externalBillingVerified: false, effectiveControlsVerified: false, bytesRead: 0, elapsedMs: 0, reasons: [] };
+    const observations = []; let began, claimed = false, activeSource = null;
+    try {
+      began = clock();
+      if (invoked) fail("selective-permit-unavailable"); invoked = true;
+      const p = !types.isProxy(authorization) && permits.get(authorization);
+      if (!p || !p.live || p.used || p.binding !== hash(cfg)) fail("selective-permit-unavailable");
+      p.used = true; claimed = true;
+      if (args.length) fail("selective-input-forbidden");
+      if (!IS_WINDOWS && !Number.isInteger(uid)) fail("selective-owner-unavailable");
+      warnPlatformPermissions();
+      const budget = () => { if (!p.live || dependencies.signal?.aborted) fail("selective-canceled"); if (clock() - began >= cfg.timeoutMs) fail("selective-deadline"); };
+      for (const source of cfg.sources) {
+        activeSource = source.sourceId; budget();
+        let before;
+        try { before = await io.lstat(source.path); } catch (e) { if (e.code === "ENOENT") fail("selective-source-missing"); throw e; }
+        const parents = await physical(source.path); allowed(before);
+        const parser = createSelectiveConfigParser(s, source.sourceId, cfg.limits);
+        const h = await io.open(source.path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const buffer = Buffer.alloc(cfg.limits.blockBytes); let read = 0, projection;
+        try {
+          if (!equal(before, await h.stat())) fail("selective-file-changed");
+          await checkpoint("opened", source.sourceId);
+          for (;;) {
+            budget();
+            const remaining = Math.min(cfg.limits.maxBytes - read, cfg.aggregateBytes - r.bytesRead);
+            if (remaining <= 0) {
+              if (read !== before.size) fail("selective-read-limit"); break;
+            }
+            const { bytesRead } = await h.read(buffer, 0, Math.min(buffer.length, remaining), read);
+            if (!bytesRead) break;
+            read += bytesRead; r.bytesRead += bytesRead;
+            const partial = parser.push(buffer.subarray(0, bytesRead)); buffer.fill(0);
+            if (partial.state === "invalid") fail(partial.reasons[0]);
+            await checkpoint("block-read", source.sourceId);
+          }
+          projection = parser.finish();
+          if (projection.state !== "observed") fail(projection.reasons[0]);
+          budget(); await checkpoint("before-revalidate", source.sourceId);
+          const after = await h.stat(), named = await io.lstat(source.path); allowed(after); allowed(named);
+          if (read !== before.size || !equal(before, after) || !equal(after, named) || JSON.stringify(parents) !== JSON.stringify(await physical(source.path))) fail("selective-file-changed");
+          budget();
+        } finally { buffer.fill(0); await h.close(); }
+        budget(); // A delayed close cannot turn an over-deadline source into evidence.
+        // Bytes scanner cannot claim an installation observation. Only this IO
+        // wrapper attaches local provenance after full descriptor revalidation.
+        r.sources.push({ sourceId: source.sourceId, state: "observed", provenance: "local-structure-observation", fields: projection.fields,
+          projectionSha256: projection.projectionSha256, stats: projection.stats });
+        observations.push({ sourceId: source.sourceId, dev: before.dev, ino: before.ino, uid: before.uid, mode: before.mode & 4095,
+          size: before.size, mtimeMs: before.mtimeMs, ctimeMs: before.ctimeMs });
+        activeSource = null;
+      }
+      r.state = "observed"; r.reasons = ["selective-local-observed"];
+    } catch (e) {
+      const code = errorCode(e); r.state = code === "selective-source-missing" ? "incomplete" : "blocked"; r.reasons = [code];
+      if (activeSource) r.sources.push({ sourceId: activeSource, state: r.state, provenance: "pending", fields: [], projectionSha256: null, stats: null });
+    } finally {
+      if (claimed) revokeSelectiveReadPermit(authorization);
+      if (began !== undefined) {
+        try {
+          r.elapsedMs = Math.max(0, Math.ceil(clock() - began));
+          if (r.elapsedMs > cfg.timeoutMs) { r.state = "blocked"; r.reasons = ["selective-deadline"]; }
+        }
+        catch { r.state = "blocked"; r.reasons = ["selective-clock-unavailable"]; }
+      }
+    }
+    if (!reportValid(r)) throw Error("Selective file report invariant failed");
+    return { report: r, privateObservations: observations };
+  } });
+}

package/src/client-supervised-codes.js

@@ -0,0 +1,32 @@
+// Closed non-sensitive diagnostics shared with the independent S2 schema.
+export const REASON_CODES = Object.freeze([
+  "byte-limit", "duplicate-json-key", "event-json-limit",
+  "invalid-byte-input", "invalid-event-object", "invalid-json",
+  "invalid-unicode", "invalid-utf8", "json-number-precision-loss",
+  "metadata-limit", "non-finite-json-number", "non-json-metadata",
+  "store-created-resource-unusable", "store-directory-replaced", "store-file-limit",
+  "store-invalid-parent", "store-io-failed", "store-residual-resource",
+  "store-resource-changed", "store-resource-exists", "store-resource-replaced",
+  "store-short-write", "store-symlink-path", "store-unsafe-resource",
+  "supervised-after-terminal", "supervised-budget-consumed", "supervised-budget-reserved",
+  "supervised-canceled", "supervised-canceled-before-reservation", "supervised-canceled-before-start",
+  "supervised-clock-unavailable", "supervised-consumer-required", "supervised-deadline",
+  "supervised-deadline-before-start", "supervised-descendants-live", "supervised-empty-reservation",
+  "supervised-event-binding-mismatch", "supervised-event-chain-mismatch", "supervised-event-gap",
+  "supervised-event-limit", "supervised-exit-failed", "supervised-fixture-completed",
+  "supervised-fixture-directory-unsafe", "supervised-fixture-source-unsafe", "supervised-forbidden-event",
+  "supervised-group-unconfirmed", "supervised-incompatible-limits", "supervised-incomplete-protocol",
+  "supervised-invalid-claim", "supervised-invalid-completion", "supervised-invalid-deadline",
+  "supervised-invalid-event", "supervised-invalid-identity", "supervised-invalid-observation",
+  "supervised-invalid-processReport", "supervised-invalid-receipt", "supervised-invalid-report",
+  "supervised-invalid-request", "supervised-invalid-reservation", "supervised-invalid-start",
+  "supervised-invalid-transition", "supervised-line-limit", "supervised-local-error",
+  "supervised-local-result", "supervised-output-limit", "supervised-platform-not-admitted",
+  "supervised-process-error", "supervised-receipt-mismatch", "supervised-reconciliation-required",
+  "supervised-reservation-changed", "supervised-result-recorded", "supervised-root-not-temporary",
+  "supervised-signal-unconfirmed", "supervised-spawn-failed", "supervised-start-record-unconfirmed",
+  "supervised-stderr-error", "supervised-stderr-invalid-utf8", "supervised-stderr-limit",
+  "supervised-stdin-error", "supervised-stdout-error", "supervised-unconfirmed-terminal",
+  "supervised-unterminated-line", "supervised-workspace-cleanup-required", "supervised-workspace-parent-unsafe",
+  "supervised-write-not-confirmed", "synthetic-result", "unsafe-json-key",
+]);

package/src/client-supervised-contract.js

@@ -0,0 +1,52 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import { types } from "node:util";
+import { copyBytes, decode, parseEventJson, copyInertJson, fail, ParseFailure } from "./client-output-json.js";
+import { hash, same } from "./client-runtime-core.js";
+import { REASON_CODES } from "./client-supervised-codes.js";
+
+export { hash, same, fail, ParseFailure, copyInertJson };
+export const LOCAL_ID = "https://agent-toolkit.local/schemas/agent-client-supervised-local.schema.json";
+export const FIXTURE_IDS = Object.freeze(["success", "split-utf8", "environment", "silent", "blocked-stdin", "closed-stdin", "failure", "stdout-overflow", "stderr-overflow", "stderr-invalid", "long-line", "event-overflow", "invalid-utf8", "forbidden-event", "duplicate-json", "after-terminal", "unterminated", "incomplete", "ignore-term", "parent-child", "child-after-parent"]);
+export const terminalStates = new Set(["completed-for-review", "failed", "canceled", "timed-out", "indeterminate"]);
+export const zeroMetrics = () => ({ spawnAttempts: 0, mainStartsObserved: 0, stdoutBytes: 0, stderrBytes: 0, events: 0, elapsedMs: 0, terminationConfirmed: false });
+export const taskKey = i => hash({ projectId: i.projectId, taskId: i.taskId });
+export const monotonicMs = () => Number(process.hrtime.bigint() / 1_000_000n);
+export const errorCode = e => e instanceof ParseFailure && REASON_CODES.includes(e.code) ? e.code : "supervised-local-error";
+
+export function createSupervisedContract(schema) {
+  const s = copyInertJson(schema);
+  if (s.$id !== LOCAL_ID || !same(s.$defs.fixtureId.enum, FIXTURE_IDS) || !same(s.$defs.reasons.items.enum, REASON_CODES)) throw Error("Unsupported supervised local schema");
+  const ajv = new Ajv2020({ strict: true, allErrors: true });
+  ajv.addFormat("date-time", { type: "string", validate: v => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/.test(v) && Number.isFinite(Date.parse(v)) && new Date(v).toISOString() === v.replace(/Z$/, ".000Z") });
+  ajv.addSchema(s);
+  const v = Object.fromEntries(["identity", "request", "event", "receipt", "processReport", "report", "observation"].map(k => [k, ajv.compile({ $ref: `${LOCAL_ID}#/$defs/${k}` })]));
+  function json(value) {
+    if (types.isProxy(value)) fail("non-json-metadata");
+    const obj = typeof value === "string" || types.isUint8Array(value)
+      ? parseEventJson(decode(copyBytes(value, 131072))) : copyInertJson(value);
+    const bytes = copyBytes(JSON.stringify(obj), 131072);
+    // Strict string and Unicode validation for nested metadata too.
+    return copyInertJson(parseEventJson(decode(bytes)));
+  }
+  const validate = (name, input) => { const obj = json(input); if (!v[name](obj)) fail("supervised-invalid-" + name); return obj; };
+  return Object.freeze({
+    request(input) {
+      const d = validate("request", input), l = d.limits;
+      if (l.graceMs + l.confirmationMs >= l.timeoutMs || l.maxLineBytes > l.maxOutputBytes) fail("supervised-incompatible-limits");
+      copyBytes(d.inputText, l.maxInputBytes);
+      return d;
+    },
+    identity: input => validate("identity", input),
+    event: input => validate("event", input),
+    receipt: input => validate("receipt", input),
+    processReport(input) {
+      const r = validate("processReport", input);
+      if (r.fixtureExecuted !== (r.metrics.mainStartsObserved === 1) || r.metrics.mainStartsObserved > r.metrics.spawnAttempts ||
+          r.state === "completed-for-review" && (!r.fixtureExecuted || !r.exitObserved || !r.pipesClosed ||
+            r.groupObservation !== "absent" || !r.metrics.terminationConfirmed)) fail("supervised-invalid-processReport");
+      return r;
+    },
+    report: input => validate("report", input),
+    observation: input => validate("observation", input)
+  });
+}

package/src/client-supervised-coordinator.js

@@ -0,0 +1,36 @@
+import { supportsLocalPosix } from "./client-local-platform.js";
+import { createSupervisedStore } from "./client-supervised-store.js";
+import { createSupervisedSupervisor } from "./client-supervised-supervisor.js";
+import { createSupervisedContract, monotonicMs, errorCode, fail } from "./client-supervised-contract.js";
+
+/** Only trusted local harnesses invoke this; no CLI or native-client adapter. */
+export function createSupervisedCoordinator(schema, configuration, dependencies = {}) {
+  const contract = createSupervisedContract(schema), store = createSupervisedStore(schema, configuration, dependencies.store);
+  const supervise = createSupervisedSupervisor(schema, dependencies.supervisor);
+  return async function coordinate(input, { signal } = {}) {
+    const mono = dependencies.supervisor?.monotonic ?? monotonicMs;
+    const beganAt = mono();
+    const r = { scope: "fixture-only", state: "not-started", fixtureExecuted: false, nativeExecuted: false,
+      runtimeReady: false, verifiedAdmission: false, actualModelCalls: null, fixtureModelCalls: 0,
+      internalCallCeiling: null, remoteCancellationVerified: false, process: null, storage: null, elapsedMs: 0, reasons: [] };
+    try {
+      const d = contract.request(input);
+      if (!supportsLocalPosix(process.platform)) fail("supervised-platform-not-admitted");
+      if (signal?.aborted) fail("supervised-canceled-before-reservation");
+      const storage = await store.withReservation(d, async handle => {
+        const p = await supervise(handle, d, { signal, beganAt });
+        r.process = p; r.fixtureExecuted = p.fixtureExecuted; r.state = p.state;
+        return p;
+      });
+      r.storage = { state: storage.state, durability: storage.durability, reasons: storage.reasons };
+      r.reasons = [...new Set([...(r.process?.reasons ?? []), ...storage.reasons])].sort();
+      if (storage.state === "reconciliation-required") r.state = "indeterminate";
+      r.elapsedMs = Math.max(0, Math.ceil(mono() - beganAt));
+      if (r.elapsedMs > d.limits.timeoutMs) {
+        r.state = "indeterminate"; r.reasons = [...new Set([...r.reasons, "supervised-deadline"])].sort();
+      }
+    } catch (e) { r.reasons = [errorCode(e)]; }
+    r.elapsedMs = Math.max(r.elapsedMs, Math.max(0, Math.ceil(mono() - beganAt)));
+    return contract.report(r);
+  };
+}

package/src/client-supervised-permit.js

@@ -0,0 +1,20 @@
+// Independent S2 capabilities: trusted code only, never JSON or a C2 handle.
+const permits = new WeakMap();
+export function createSupervisedPermit(binding, claim, started) {
+  const h = Object.freeze(Object.create(null));
+  permits.set(h, { binding, claim, started, live: true, used: false });
+  return h;
+}
+export function revokeSupervisedPermit(h) { const p = permits.get(h); if (p) p.live = false; }
+export async function claimSupervisedPermit(h, binding) {
+  const p = permits.get(h);
+  if (!p || !p.live || p.used) throw Error("Supervised permit unavailable");
+  p.used = true;
+  if (p.binding !== binding) throw Error("Supervised permit binding mismatch");
+  await p.claim();
+  if (!p.live) throw Error("Supervised permit unavailable");
+  return Object.freeze({ started: async () => {
+    if (!p.live || p.startedUsed) throw Error("Supervised observation unavailable");
+    p.startedUsed = true; return p.started();
+  } });
+}

package/src/client-supervised-protocol.js

@@ -0,0 +1,37 @@
+import { decode, parseEventJson, fail } from "./client-output-json.js";
+
+/** S2 protocol is synthetic and versioned separately; raw data is discarded. */
+export function createSupervisedProtocol(limits) {
+  let bytes = 0, events = 0, pending = Buffer.alloc(0), state = "initial";
+  function line(input) {
+    if (state === "terminal") fail("supervised-after-terminal");
+    if (++events > limits.maxEvents) fail("supervised-event-limit");
+    const e = parseEventJson(decode(input.at(-1) === 13 ? input.subarray(0, -1) : input));
+    if (e.s !== 2) fail("supervised-invalid-event");
+    const keys = Object.keys(e).sort().join(",");
+    if (e.type === "start" && state === "initial" && keys === "s,type") state = "running";
+    else if (e.type === "data" && state === "running" && keys === "s,text,type" && typeof e.text === "string") { /* No capture retained. */ }
+    else if (e.type === "end" && state === "running" && keys === "ok,s,type" && e.ok === true) state = "terminal";
+    else fail("supervised-forbidden-event");
+  }
+  return Object.freeze({
+    push(chunk) {
+      bytes += chunk.length;
+      if (bytes > limits.maxOutputBytes) fail("supervised-output-limit");
+      let start = 0;
+      for (let i = 0; i < chunk.length; i++) if (chunk[i] === 10) {
+        const size = pending.length + i - start;
+        if (size > limits.maxLineBytes) fail("supervised-line-limit");
+        line(Buffer.concat([pending, chunk.subarray(start, i)], size));
+        pending = Buffer.alloc(0); start = i + 1;
+      }
+      if (pending.length + chunk.length - start > limits.maxLineBytes) fail("supervised-line-limit");
+      pending = Buffer.concat([pending, chunk.subarray(start)]);
+    },
+    finish() {
+      if (pending.length) fail("supervised-unterminated-line");
+      if (state !== "terminal") fail("supervised-incomplete-protocol");
+    },
+    counts: () => ({ stdoutBytes: bytes, events, retainedLineBytes: pending.length })
+  });
+}