jev-layer 0.1.0 → 0.3.0

package/src/contract.mjs

@@ -1,72 +1,74 @@
-import { createHash, randomUUID } from "node:crypto";
-
-export const RISK_ORDER = Object.freeze({ low: 0, medium: 1, high: 2, critical: 3 });
-export const CAPABILITY_KINDS = new Set(["skill", "tool", "mcp", "cli", "dsh", "subagent", "model"]);
-
-export function stableJson(value) {
-  return JSON.stringify(sortJson(value));
-}
-
-function sortJson(value) {
-  if (Array.isArray(value)) return value.map(sortJson);
-  if (value && typeof value === "object") {
-    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
-  }
-  return value;
-}
-
-export function sha256(value) {
-  return `sha256:${createHash("sha256").update(typeof value === "string" ? value : stableJson(value)).digest("hex")}`;
-}
-
-export function byteLength(value) {
-  return Buffer.byteLength(typeof value === "string" ? value : stableJson(value), "utf8");
-}
-
-export function normalizeRequest(input) {
-  if (!input || typeof input !== "object" || Array.isArray(input)) {
-    throw new TypeError("route request must be an object");
-  }
-  const intent = typeof input.intent === "string" ? input.intent : input.request;
-  if (typeof intent !== "string" || intent.trim() === "") {
-    throw new TypeError("route request requires a non-empty intent");
-  }
-  if (!Array.isArray(input.capabilities)) {
-    throw new TypeError("route request requires capabilities[]");
-  }
-  return {
-    schema_version: input.schema_version ?? 1,
-    harness: typeof input.harness === "string" ? input.harness : "unknown",
-    intent: intent.trim(),
-    context: input.context && typeof input.context === "object" ? input.context : {},
-    actor: typeof input.actor === "string" ? input.actor : undefined,
-    actor_permissions: Array.isArray(input.actor_permissions) ? input.actor_permissions.filter((value) => typeof value === "string") : undefined,
-    capabilities: input.capabilities,
-    policy: input.policy && typeof input.policy === "object" ? input.policy : {},
-  };
-}
-
-export function decisionEnvelope({ status, selected, reason, provider, latencyMs, candidateCount, contextBytes, candidates = [], probabilities = {}, confidence = null, rawJev = null, fallback = null, requestId = randomUUID(), correlationId = requestId, costUsd = rawJev?.usage?.cost ?? null }) {
-  return {
-    schema_version: 1,
-    correlation_id: correlationId,
-    status,
-    selected: selected ?? null,
-    confidence,
-    probabilities,
-    reason,
-    candidates,
-    fallback,
-    execution: { enabled: false, status: "not_started" },
-    raw_jev: rawJev,
-    receipt: {
-      correlation_id: correlationId,
-      request_id: requestId,
-      provider,
-      latency_ms: latencyMs,
-      cost_usd: costUsd,
-      candidate_count: candidateCount,
-      context_bytes: contextBytes,
-    },
-  };
-}
+import { createHash, randomUUID } from "node:crypto";
+
+export const RISK_ORDER = Object.freeze({ low: 0, medium: 1, high: 2, critical: 3 });
+export const CAPABILITY_KINDS = new Set(["skill", "tool", "mcp", "cli", "dsh", "subagent", "model"]);
+
+export function stableJson(value) {
+  return JSON.stringify(sortJson(value));
+}
+
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])]));
+  }
+  return value;
+}
+
+export function sha256(value) {
+  return `sha256:${createHash("sha256").update(typeof value === "string" ? value : stableJson(value)).digest("hex")}`;
+}
+
+export function byteLength(value) {
+  return Buffer.byteLength(typeof value === "string" ? value : stableJson(value), "utf8");
+}
+
+export function normalizeRequest(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new TypeError("route request must be an object");
+  }
+  const intent = typeof input.intent === "string" ? input.intent : input.request;
+  if (typeof intent !== "string" || intent.trim() === "") {
+    throw new TypeError("route request requires a non-empty intent");
+  }
+  if (!Array.isArray(input.capabilities)) {
+    throw new TypeError("route request requires capabilities[]");
+  }
+  return {
+    schema_version: input.schema_version ?? 1,
+    harness: typeof input.harness === "string" ? input.harness : "unknown",
+    intent: intent.trim(),
+    context: input.context && typeof input.context === "object" ? input.context : {},
+    assets: input.assets,
+    assets_omitted: input.assets_omitted === true,
+    actor: typeof input.actor === "string" ? input.actor : undefined,
+    actor_permissions: Array.isArray(input.actor_permissions) ? input.actor_permissions.filter((value) => typeof value === "string") : undefined,
+    capabilities: input.capabilities,
+    policy: input.policy && typeof input.policy === "object" ? input.policy : {},
+  };
+}
+
+export function decisionEnvelope({ status, selected, reason, provider, latencyMs, candidateCount, contextBytes, candidates = [], probabilities = {}, confidence = null, rawJev = null, fallback = null, requestId = randomUUID(), correlationId = requestId, costUsd = rawJev?.usage?.cost ?? null }) {
+  return {
+    schema_version: 1,
+    correlation_id: correlationId,
+    status,
+    selected: selected ?? null,
+    confidence,
+    probabilities,
+    reason,
+    candidates,
+    fallback,
+    execution: { enabled: false, status: "not_started" },
+    raw_jev: rawJev,
+    receipt: {
+      correlation_id: correlationId,
+      request_id: requestId,
+      provider,
+      latency_ms: latencyMs,
+      cost_usd: costUsd,
+      candidate_count: candidateCount,
+      context_bytes: contextBytes,
+    },
+  };
+}

package/src/discovery.mjs

@@ -1,65 +1,65 @@
-import { readFile } from "node:fs/promises";
-
-const DISCOVERY_SOURCES = Object.freeze([
-  ["skills", "skill"],
-  ["mcp", "mcp"],
-  ["cli", "cli"],
-  ["dsh", "dsh"],
-  ["tools", "tool"],
-  ["subagents", "subagent"],
-  ["models", "model"],
-]);
-
-export function discoverCapabilities(input = {}) {
-  const entries = [];
-  for (const [field, kind] of DISCOVERY_SOURCES) {
-    const values = Array.isArray(input[field]) ? input[field] : [];
-    for (const value of values) entries.push(normalizeDiscovered(value, kind, input.source ?? `${kind}-discovery`));
-  }
-  const manifests = Array.isArray(input.manifests) ? input.manifests : [];
-  for (const manifest of manifests) {
-    const values = Array.isArray(manifest?.capabilities) ? manifest.capabilities : [manifest];
-    for (const value of values) {
-      const kind = value?.kind ?? value?.type ?? manifest?.kind ?? "tool";
-      entries.push(normalizeDiscovered(value, kind, value?.source ?? manifest?.source ?? "manifest"));
-    }
-  }
-  const seen = new Set();
-  return entries.filter((entry) => {
-    if (seen.has(entry.id)) return false;
-    seen.add(entry.id);
-    return true;
-  });
-}
-
-export async function loadCapabilityManifest(path, options = {}) {
-  const parsed = JSON.parse(await readFile(path, "utf8"));
-  const manifest = Array.isArray(parsed) ? { capabilities: parsed } : parsed;
-  return discoverCapabilities({ manifests: [{ ...manifest, source: options.source ?? manifest.source ?? "manifest" }] });
-}
-
-function normalizeDiscovered(value, kind, source) {
-  if (!value || typeof value !== "object") throw new TypeError("discovered capability must be an object");
-  const id = stringValue(value.id ?? value.name, `${kind}-capability`);
-  const name = stringValue(value.name ?? value.id, id);
-  const description = stringValue(value.description ?? value.summary, `${kind} capability ${name}`);
-  const metadata = {
-    ...(value.metadata && typeof value.metadata === "object" ? value.metadata : {}),
-    [kind]: stringValue(value.target ?? value.command ?? value.name, name),
-  };
-  return {
-    ...value,
-    id,
-    kind,
-    name,
-    description,
-    source: stringValue(value.source, source),
-    verified: value.verified === true,
-    metadata,
-    available: value.available !== false && value.availability?.available !== false,
-  };
-}
-
-function stringValue(value, fallback) {
-  return typeof value === "string" && value.trim() ? value.trim() : fallback;
-}
+import { readFile } from "node:fs/promises";
+
+const DISCOVERY_SOURCES = Object.freeze([
+  ["skills", "skill"],
+  ["mcp", "mcp"],
+  ["cli", "cli"],
+  ["dsh", "dsh"],
+  ["tools", "tool"],
+  ["subagents", "subagent"],
+  ["models", "model"],
+]);
+
+export function discoverCapabilities(input = {}) {
+  const entries = [];
+  for (const [field, kind] of DISCOVERY_SOURCES) {
+    const values = Array.isArray(input[field]) ? input[field] : [];
+    for (const value of values) entries.push(normalizeDiscovered(value, kind, input.source ?? `${kind}-discovery`));
+  }
+  const manifests = Array.isArray(input.manifests) ? input.manifests : [];
+  for (const manifest of manifests) {
+    const values = Array.isArray(manifest?.capabilities) ? manifest.capabilities : [manifest];
+    for (const value of values) {
+      const kind = value?.kind ?? value?.type ?? manifest?.kind ?? "tool";
+      entries.push(normalizeDiscovered(value, kind, value?.source ?? manifest?.source ?? "manifest"));
+    }
+  }
+  const seen = new Set();
+  return entries.filter((entry) => {
+    if (seen.has(entry.id)) return false;
+    seen.add(entry.id);
+    return true;
+  });
+}
+
+export async function loadCapabilityManifest(path, options = {}) {
+  const parsed = JSON.parse(await readFile(path, "utf8"));
+  const manifest = Array.isArray(parsed) ? { capabilities: parsed } : parsed;
+  return discoverCapabilities({ manifests: [{ ...manifest, source: options.source ?? manifest.source ?? "manifest" }] });
+}
+
+function normalizeDiscovered(value, kind, source) {
+  if (!value || typeof value !== "object") throw new TypeError("discovered capability must be an object");
+  const id = stringValue(value.id ?? value.name, `${kind}-capability`);
+  const name = stringValue(value.name ?? value.id, id);
+  const description = stringValue(value.description ?? value.summary, `${kind} capability ${name}`);
+  const metadata = {
+    ...(value.metadata && typeof value.metadata === "object" ? value.metadata : {}),
+    [kind]: stringValue(value.target ?? value.command ?? value.name, name),
+  };
+  return {
+    ...value,
+    id,
+    kind,
+    name,
+    description,
+    source: stringValue(value.source, source),
+    verified: value.verified === true,
+    metadata,
+    available: value.available !== false && value.availability?.available !== false,
+  };
+}
+
+function stringValue(value, fallback) {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}

package/src/hermes-adapter.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * One-shot transport used by the Hermes plugin.
+ *
+ * This is deliberately an adapter, not an executor: it accepts a closed host
+ * request and returns bounded Jev decisions/receipts. Native Hermes retains
+ * registry lookup, approvals, execution, retries, recovery, and final output.
+ */
+import { createInterface } from "node:readline";
+import { decideBrowserStep } from "./browser.mjs";
+import { decideComputerStep } from "./computer.mjs";
+import { configuredProvider, configuredReplayPath, loadConfig } from "./config.mjs";
+import { appendExecutionReceipt, appendRoutingCase, buildExecutionReceipt, replayCasePath } from "./receipts.mjs";
+import { routeRequest } from "./route.mjs";
+import { superviseWork } from "./supervision.mjs";
+import { buildShadowCompactionReport } from "./shadow-compaction.mjs";
+import { recommendModelRoute } from "./model-routing.mjs";
+
+const { config } = await loadConfig();
+const casesPath = replayCasePath(configuredReplayPath(config));
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+for await (const line of input) {
+  if (!line.trim()) continue;
+  try {
+    const envelope = JSON.parse(line);
+    const result = await handle(envelope);
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify(fallback(error))}\n`);
+  }
+}
+
+async function handle({ operation, args = {}, decision = null } = {}) {
+  const provider = configuredProvider(config, args.provider);
+  if (operation === "route") {
+    const { provider: _provider, engine = "native", ...request } = args;
+    const result = await routeRequest(request, {
+      provider,
+      config,
+      engine,
+      contextFilterMode: request.policy?.context_filter_mode ?? config.features?.context_filter,
+    });
+    await persistRoutingCase(request, result);
+    return result;
+  }
+  if (operation === "browser_step") {
+    const { provider: _provider, enabled, ...input } = args;
+    const routed = await decideBrowserStep(input, {
+   enabled: enabled ?? config.features?.browser_fast_path,
+   provider,
+   config,
+    });
+    routed.decision.browser_action = routed.action
+      ? { ...routed.action, target_id: routed.action.target_id ?? null, option_id: routed.action.option_id ?? null }
+      : null;
+    await persistRoutingCase(routed.request, routed.decision);
+    return routed.decision;
+  }
+  if (operation === "computer_step") {
+    const { provider: _provider, enabled, ...input } = args;
+    const routed = await decideComputerStep(input, {
+      enabled: enabled ?? (process.env.JEV_COMPUTER_USE === "1" || config.features?.computer_use), provider, config,
+    });
+    routed.decision.computer_action = routed.action;
+    await persistRoutingCase(routed.request ?? { harness: input.harness ?? "computer", intent: input.goal }, routed.decision);
+    return routed.decision;
+  }
+  if (operation === "supervise") {
+    const { provider: _provider, enabled, ...input } = args;
+    return superviseWork({
+      ...input,
+      config,
+      enabled: enabled ?? config.features?.supervision,
+      provider,
+      receiptPath: casesPath,
+    });
+  }
+  if (operation === "model_route") {
+    const { provider: _provider, ...input } = args;
+    const result = await recommendModelRoute({ ...input, provider, config });
+    await persistRoutingCase({
+      schema_version: 1,
+      harness: input.harness ?? "hermes",
+      intent: input.intent,
+      context: { ...(input.context ?? {}), model_route: { mode: "shadow" } },
+      capabilities: (input.models ?? []).map((profile) => ({
+        id: profile.id,
+        kind: "model",
+        name: profile.model ?? profile.id,
+        description: profile.description ?? "",
+        source: profile.provider ?? null,
+        risk: "low",
+      })),
+      policy: input.policy ?? {},
+    }, result);
+    return result;
+  }
+  if (operation === "shadow_compaction") {
+    const { provider: _provider, ...input } = args;
+    return buildShadowCompactionReport({ ...input, provider, config });
+  }
+  if (operation === "record_execution") {
+    if (!decision || typeof decision !== "object") throw new TypeError("decision is required for record_execution");
+    if (args.correlation_id !== decision.correlation_id) throw new TypeError("correlation_id does not match the routed decision");
+    try {
+      const { record } = await appendExecutionReceipt({ path: casesPath, request: decision._jev_request ?? {}, decision, host: args });
+      return record;
+    } catch (error) {
+      const record = buildExecutionReceipt({ request: decision._jev_request ?? {}, decision, host: args });
+      return { ...record, persistence: { persisted: false, error: error instanceof Error ? error.message : String(error) } };
+    }
+  }
+  throw new TypeError(`unsupported Hermes adapter operation: ${operation}`);
+}
+
+async function persistRoutingCase(request, decision) {
+  const { assets, ...retainedRequest } = request;
+  if (Object.keys(assets ?? {}).length) retainedRequest.assets_omitted = true;
+  decision._jev_request = retainedRequest;
+  try {
+    await appendRoutingCase({ path: casesPath, request, decision });
+    decision.receipt = { ...decision.receipt, replay_case_id: decision.correlation_id, replay_persisted: true };
+  } catch (error) {
+    decision.receipt = { ...decision.receipt, replay_persisted: false,
+      replay_error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function fallback(error) {
+  const reason = error instanceof Error ? error.message : String(error);
+  return { schema_version: 1, status: "fallback", selected: null, reason,
+    fallback: { type: "adapter_error", reason }, execution: { enabled: false, status: "not_started" } };
+}

package/src/images.mjs

@@ -0,0 +1,98 @@
+const MAX_IMAGE_BYTES = 16 * 1024 * 1024;
+const MAX_BODY_BYTES = 32 * 1024 * 1024;
+
+function imageSize(bytes, format) {
+  if (format === "png") {
+    if (bytes.length < 33 || !bytes.subarray(0, 8).equals(Buffer.from("89504e470d0a1a0a", "hex"))) {
+      throw new Error("image data is not PNG");
+    }
+    let width;
+    let height;
+    let hasData = false;
+    for (let offset = 8; offset + 12 <= bytes.length;) {
+      const length = bytes.readUInt32BE(offset);
+      const type = bytes.toString("ascii", offset + 4, offset + 8);
+      if (offset + 12 + length > bytes.length) throw new Error("truncated PNG image");
+      if (offset === 8) {
+        if (type !== "IHDR" || length !== 13) throw new Error("invalid PNG header");
+        width = bytes.readUInt32BE(offset + 8);
+        height = bytes.readUInt32BE(offset + 12);
+      }
+      if (type === "acTL") throw new Error("animated PNG images are unsupported");
+      if (type === "IDAT") hasData = true;
+      offset += 12 + length;
+      if (type === "IEND") {
+        if (length !== 0 || !hasData || offset !== bytes.length) throw new Error("invalid PNG image end");
+        return { width, height };
+      }
+    }
+    throw new Error("incomplete PNG image");
+  }
+
+  if (bytes.length < 4 || bytes.readUInt16BE(0) !== 0xffd8 || bytes.readUInt16BE(bytes.length - 2) !== 0xffd9) {
+    throw new Error("image data is not a complete JPEG");
+  }
+  for (let offset = 2; offset + 4 <= bytes.length;) {
+    if (bytes[offset++] !== 0xff) throw new Error("invalid JPEG marker");
+    while (bytes[offset] === 0xff) offset += 1;
+    const marker = bytes[offset++];
+    if (marker === 0xda || marker === 0xd9) break;
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+    if (offset + 2 > bytes.length) break;
+    const length = bytes.readUInt16BE(offset);
+    if (length < 2 || offset + length > bytes.length) throw new Error("truncated JPEG image");
+    if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+      if (length < 8) throw new Error("invalid JPEG frame");
+      return { width: bytes.readUInt16BE(offset + 5), height: bytes.readUInt16BE(offset + 3) };
+    }
+    offset += length;
+  }
+  throw new Error("JPEG image has no frame dimensions");
+}
+
+// Call after normalizeImageAssets when grounding coordinates in supplied pixels.
+export function imageDimensions(asset) {
+  return imageSize(Buffer.from(asset.data_base64, "base64"), asset.format);
+}
+
+export function normalizeImageAssets(assets) {
+  if (assets === undefined) return {};
+  if (!assets || typeof assets !== "object" || Array.isArray(assets)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(assets))) {
+    throw new Error("assets must be an image reference map");
+  }
+  let referenceBytes = 0;
+  let bodyBytes = 2;
+  const normalized = [];
+  for (const [reference, asset] of Object.entries(assets)) {
+    const length = Buffer.byteLength(reference);
+    referenceBytes += length;
+    if (!reference.trim() || length > 1024 || referenceBytes > 65_536) {
+      throw new Error("image references must be nonblank, at most 1024 UTF-8 bytes each and 65536 bytes total");
+    }
+    if (!asset || typeof asset !== "object" || Array.isArray(asset)
+      || Object.keys(asset).some((key) => !["type", "format", "data_base64"].includes(key))
+      || (asset.type !== undefined && asset.type !== "image") || !["png", "jpg", "jpeg"].includes(asset.format)) {
+      throw new Error("assets accept only base64 PNG/JPG/JPEG images");
+    }
+    const data = asset.data_base64;
+    if (typeof data !== "string" || !data.length || data.length % 4 !== 0
+      || data.length > 4 * Math.ceil(MAX_IMAGE_BYTES / 3)) {
+      throw new Error("image base64 is invalid or exceeds 16 MiB decoded");
+    }
+    const padding = data.endsWith("==") ? 2 : data.endsWith("=") ? 1 : 0;
+    if (data.length / 4 * 3 - padding > MAX_IMAGE_BYTES) throw new Error("image exceeds 16 MiB decoded");
+    if (/[^A-Za-z0-9+/]/.test(data.slice(0, data.length - padding))) throw new Error("invalid image base64");
+    const bytes = Buffer.from(data, "base64");
+    if (bytes.toString("base64") !== data) throw new Error("invalid image base64");
+    const { width, height } = imageSize(bytes, asset.format);
+    if (width < 256 || height < 256 || width > 1568 || height > 1568 || width * height < 78_400) {
+      throw new Error("image dimensions must be 256..1568 pixels per side and at least 78400 pixels total");
+    }
+    const value = { type: "image", format: asset.format, data_base64: data };
+    bodyBytes += Buffer.byteLength(JSON.stringify(reference)) + Buffer.byteLength(JSON.stringify(value)) + 1 + (normalized.length ? 1 : 0);
+    if (bodyBytes > MAX_BODY_BYTES) throw new Error("image assets exceed the 32 MiB request body limit");
+    normalized.push([reference, value]);
+  }
+  return Object.fromEntries(normalized);
+}