jev-layer 0.2.0 → 0.3.0

package/scripts/clean-install-smoke.mjs

@@ -8,30 +8,40 @@ import { tmpdir } from "node:os";
 
 const execFileAsync = promisify(execFile);
 const sourceRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const npmCli = process.env.npm_execpath;
+assert.ok(npmCli, "Run this smoke with npm run clean-install-smoke so npm_execpath identifies the npm CLI.");
 const stage = await mkdtemp(join(tmpdir(), "jev-clean-install-"));
 const packageRoot = join(stage, "package");
 const workspace = join(stage, "workspace");
+const installedRoot = join(workspace, "node_modules", "jev-layer");
 
 try {
   await copyDistribution(packageRoot);
-  await execFileAsync("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund"], { cwd: packageRoot, env: process.env });
+  await runNpm(packageRoot, ["install", "--ignore-scripts", "--no-audit", "--no-fund"]);
   await mkdir(workspace, { recursive: true });
   await writeFile(join(workspace, "package.json"), JSON.stringify({ name: "clean-install-workspace", private: true }, null, 2) + "\n", "utf8");
-  await execFileAsync("npm", ["install", "--ignore-scripts", "--no-audit", "--no-fund", "--no-save", packageRoot], { cwd: workspace, env: process.env });
-  await runNode(packageRoot, ["bin/jev.mjs", "install", "--project", workspace]);
-  await runNode(packageRoot, ["bin/jev.mjs", "add", "generic", "--project", workspace]);
-  const doctor = await runNode(packageRoot, ["bin/jev.mjs", "doctor", "--project", workspace]);
+  await runNpm(workspace, ["install", "--ignore-scripts", "--no-audit", "--no-fund", "--no-save", "--install-links", packageRoot]);
+  await runJev(workspace, ["install", "--project", workspace]);
+  await runJev(workspace, ["add", "generic", "--project", workspace]);
+  const doctor = await runJev(workspace, ["doctor", "--project", workspace]);
   const doctorReport = JSON.parse(doctor.stdout);
   assert.equal(doctorReport.ok, true);
+  assert.equal(doctorReport.package_root, installedRoot);
 
-  const cli = await runJev(workspace, ["cli", "--provider", "demo", "--input", join(packageRoot, "examples", "route-request.json")]);
+  const cli = await runJev(workspace, ["cli", "--provider", "demo", "--input", join(installedRoot, "examples", "route-request.json")]);
   const cliDecision = JSON.parse(cli.stdout.trim().split(/\r?\n/).at(-1));
   assert.equal(cliDecision.execution.enabled, false);
   assert.ok(cliDecision.correlation_id);
 
   const genericConfig = JSON.parse(await readFile(join(workspace, ".jev", "adapters", "generic.json"), "utf8"));
   const genericServer = genericConfig.mcpServers.jev;
-  assert.deepEqual(genericServer.args, ["mcp"]);
+  if (process.platform === "win32") {
+    assert.equal(genericServer.command, process.execPath);
+    assert.deepEqual(genericServer.args, [join(installedRoot, "bin", "jev.mjs"), "mcp"]);
+  } else {
+    assert.equal(genericServer.command, "jev");
+    assert.deepEqual(genericServer.args, ["mcp"]);
+  }
   const mcpEnv = localEnv(workspace);
   const mcp = spawn(genericServer.command, genericServer.args, {
     cwd: workspace,
@@ -88,7 +98,7 @@ try {
   });
   const decision = routed.result.structuredContent;
   assert.equal(decision.status, "selected");
-  const hostResult = await readFile(join(packageRoot, "package.json"), "utf8");
+  const hostResult = await readFile(join(installedRoot, "package.json"), "utf8");
   const recorded = await request("tools/call", {
     name: "jev_record_execution",
     arguments: {
@@ -114,7 +124,7 @@ try {
   assert.equal(records.length, 2);
   assert.deepEqual(records.map((record) => record.record_type), ["routing_case", "execution_receipt"]);
   assert.equal(records[0].correlation_id, records[1].correlation_id);
-  const replay = await runNode(packageRoot, ["scripts/replay-eval.mjs", "--provider", "demo", "--input", join(workspace, ".jev", "replay", "cases.jsonl"), "--limit", "1"]);
+  const replay = await runNode(installedRoot, ["scripts/replay-eval.mjs", "--provider", "demo", "--input", join(workspace, ".jev", "replay", "cases.jsonl"), "--limit", "1"]);
   const replayReport = JSON.parse(replay.stdout);
   assert.equal(replayReport.replayed_cases, 1);
   assert.equal(replayReport.host_execution_calls, 0);
@@ -143,8 +153,12 @@ function runNode(cwd, args) {
   return execFileAsync(process.execPath, args, { cwd, env: process.env, maxBuffer: 2 * 1024 * 1024 });
 }
 
+function runNpm(cwd, args) {
+  return runNode(cwd, [npmCli, ...args]);
+}
+
 function runJev(cwd, args) {
-  return execFileAsync("jev", args, { cwd, env: localEnv(cwd), maxBuffer: 2 * 1024 * 1024 });
+  return execFileAsync(process.execPath, [join(installedRoot, "bin", "jev.mjs"), ...args], { cwd, env: localEnv(cwd), maxBuffer: 2 * 1024 * 1024 });
 }
 
 function localEnv(workspaceRoot) {

package/scripts/mcp-receipt-smoke.mjs

@@ -4,14 +4,16 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
 
-const root = resolve(new URL("..", import.meta.url).pathname);
+const root = fileURLToPath(new URL("..", import.meta.url));
 const casesPath = join(await mkdtemp(join(tmpdir(), "jev-mcp-receipt-")), "cases.jsonl");
 const child = spawn(process.env.JEV_NODE ?? "node", [resolve(root, "src/mcp-server.mjs")], {
   cwd: root,
   env: { ...process.env, JEV_REPLAY_CASES: casesPath },
   stdio: ["pipe", "pipe", "pipe"],
 });
+const closed = new Promise((resolveExit) => child.once("close", resolveExit));
 const lines = createInterface({ input: child.stdout });
 const pending = new Map();
 lines.on("line", (line) => {
@@ -90,7 +92,7 @@ try {
   console.log(JSON.stringify({ ok: true, cases_path: casesPath, receipt }, null, 2));
 } finally {
   child.kill();
-  await new Promise((resolveExit) => child.once("close", resolveExit));
+  await closed;
 }
 
 function request(id, method, params) {

package/scripts/openrouter-choice.mjs

@@ -1,7 +1,7 @@
 import { routeRequest } from "../src/route.mjs";
 
 const endpoint = process.env.OPENROUTER_DECISIONS_ENDPOINT ?? "https://openrouter.ai/api/alpha/decisions";
-const model = process.env.OPENROUTER_DECISIONS_MODEL ?? "typesafe/jev-1.13";
+const model = process.env.OPENROUTER_DECISIONS_MODEL ?? "typesafe/jev-1.14";
 const decision = await routeRequest({
   schema_version: 1,
   harness: "jev-layer-openrouter-smoke",

package/src/browser.mjs

@@ -41,6 +41,9 @@ export function buildBrowserRequest({ goal, observation = {}, harness = "browser
     actor_permissions,
     capabilities: actions.map(toCapability),
     policy,
+    ...(observation?.screenshot ? { assets: { "jev-browser-screenshot": {
+      type: "image", format: observation.screenshot.format, data_base64: observation.screenshot.data_base64,
+    } } } : {}),
   };
 }
 export function browserActions({ goal, observation, start_url = null, progress = null }) {
@@ -159,7 +162,8 @@ export async function runBrowserFastPath({
 
   let observation;
   try {
-    observation = normalizeObservation(await executor.observe());
+    const captured = await executor.observe();
+    observation = { ...normalizeObservation(captured), ...(captured?.screenshot ? { screenshot: captured.screenshot } : {}) };
   } catch (error) {
     metrics.failures += 1;
     return finish("handoff", "browser_observation_failed", { error: message(error) });
@@ -249,7 +253,8 @@ export async function runBrowserFastPath({
       const result = await execute(routed.action);
       metrics.browser_actions += 1;
       stepTrace.executed = true;
-      const nextObservation = normalizeObservation(result?.observation ?? await executor.observe());
+      const captured = result?.observation ?? await executor.observe();
+      const nextObservation = { ...normalizeObservation(captured), ...(captured?.screenshot ? { screenshot: captured.screenshot } : {}) };
       progress = advanceProgress(progress, routed.action, observation, nextObservation, {
         status: "completed",
         result: result?.result ?? result ?? null,
@@ -309,6 +314,12 @@ function normalizeObservation(observation) {
     title: typeof observation.title === "string" ? observation.title.slice(0, 500) : null,
     visible_text: typeof observation.visible_text === "string" ? observation.visible_text.slice(0, 8_000) : "",
     targets: Array.isArray(observation.targets) ? observation.targets.slice(0, MAX_TARGETS).map(normalizeTarget).filter(Boolean) : [],
+    ...(observation.screenshot ? { screenshot: {
+      format: observation.screenshot.format,
+      width: observation.screenshot.width,
+      height: observation.screenshot.height,
+      sha256: observation.screenshot.sha256 ?? (typeof observation.screenshot.data_base64 === "string" ? sha256(observation.screenshot.data_base64) : null),
+    } } : {}),
     tabs: Array.isArray(observation.tabs) ? observation.tabs.slice(0, MAX_TABS).map(normalizeTab).filter(Boolean) : [],
     scroll: {
       up: scroll.up === true,
@@ -344,7 +355,7 @@ function normalizeProgress(progress, goal, observation) {
   const source = progress && typeof progress === "object" ? progress : {};
   return {
     goal: goal.slice(0, MAX_LABEL),
-    current_observation: observation,
+    current_observation: normalizeObservation(observation),
     executed_actions: Array.isArray(source.executed_actions) ? source.executed_actions.slice(-16).map(compactActionRecord) : [],
     used_targets: Array.isArray(source.used_targets) ? [...new Set(source.used_targets.filter((value) => typeof value === "string").slice(-32))] : [],
     blocked_actions: Array.isArray(source.blocked_actions) ? [...new Set(source.blocked_actions.filter((value) => typeof value === "string").slice(-32))] : [],
@@ -508,6 +519,7 @@ function browserStateFingerprint(observation) {
     targets: observation.targets,
     tabs: observation.tabs,
     scroll: observation.scroll,
+    screenshot: normalizeObservation(observation).screenshot ?? null,
   });
 }
 

package/src/computer.mjs

@@ -0,0 +1,196 @@
+import { createHash, randomUUID } from "node:crypto";
+import { decisionEnvelope } from "./contract.mjs";
+import { imageDimensions, normalizeImageAssets } from "./images.mjs";
+import { resolveProvider } from "./providers/index.mjs";
+import { routeRequest } from "./route.mjs";
+
+const OPERATIONS = new Set(["click", "type", "key", "scroll", "handoff"]);
+const CONSEQUENTIAL = new Set(["click", "type", "key"]);
+const ARGUMENTS = {
+  click: ["x", "y", "button"],
+  type: ["text"],
+  key: ["keys"],
+  scroll: ["direction", "amount", "x", "y"],
+  handoff: ["reason"],
+};
+
+export async function decideComputerStep(input, options = {}) {
+  const enabled = options.enabled === true || options.enabled !== false && process.env.JEV_COMPUTER_USE === "1";
+  if (!enabled) return failed(null, null, "computer_use_disabled", "Computer-use advice is disabled", options);
+
+  let request;
+  let actions;
+  let screenshot;
+  let thresholds;
+  try {
+    if (!object(input) || !text(input.goal, 8_000)) throw new TypeError("goal is required");
+    const supplied = input.observation?.screenshot;
+    if (!object(supplied)) throw new TypeError("screenshot is required");
+    const reference = randomUUID();
+    const assets = normalizeImageAssets({ [reference]: { type: "image", format: supplied.format, data_base64: supplied.data_base64 } });
+    const dimensions = imageDimensions(assets[reference]);
+    if (supplied.width !== dimensions.width || supplied.height !== dimensions.height) throw new TypeError("screenshot dimensions do not match image");
+    screenshot = {
+      ...dimensions,
+      format: assets[reference].format,
+      sha256: `sha256:${createHash("sha256").update(Buffer.from(assets[reference].data_base64, "base64")).digest("hex")}`,
+      requires_current: true,
+    };
+    if (!Array.isArray(input.actions) || input.actions.length > 32) throw new TypeError("actions must contain at most 32 candidates");
+    actions = input.actions.map((candidate) => normalizeAction(candidate, dimensions));
+    if (new Set(actions.map((candidate) => candidate.id)).size !== actions.length) throw new TypeError("action ids must be unique");
+    if (input.policy !== undefined && !object(input.policy) || options.policy !== undefined && !object(options.policy)) throw new TypeError("invalid policy");
+    const policy = { ...(input.policy ?? {}), ...(options.policy ?? {}) };
+    thresholds = {
+      visibility: policy.min_target_visibility ?? 0.9,
+      box: policy.min_box_confidence ?? 0.8,
+    };
+    if (!probability(thresholds.visibility) || thresholds.visibility === 0 || !probability(thresholds.box) || thresholds.box === 0) throw new TypeError("invalid grounding thresholds");
+    const observation = { screenshot };
+    for (const key of ["visible_text", "application"]) {
+      if (input.observation[key] !== undefined) {
+        if (!text(input.observation[key], key === "visible_text" ? 8_000 : 240, true)) throw new TypeError(`invalid ${key}`);
+        observation[key] = input.observation[key];
+      }
+    }
+    if (input.actor_permissions !== undefined && (!Array.isArray(input.actor_permissions) || input.actor_permissions.length > 32 || input.actor_permissions.some((permission) => !text(permission, 240)))) throw new TypeError("invalid actor_permissions");
+    request = {
+      schema_version: 1,
+      harness: text(input.harness, 240) ? input.harness : "computer",
+      intent: `Computer goal: ${input.goal}`,
+      context: {
+        computer: {
+          observation,
+          actions: actions.map(({ id, operation, args, target }) => ({ id, operation, args, ...(target ? { target } : {}) })),
+        },
+      },
+      assets,
+      actor_permissions: input.actor_permissions ?? [],
+      capabilities: actions.map((candidate) => ({
+        ...candidate,
+        kind: "tool",
+        name: candidate.name ?? `${candidate.operation}: ${candidate.id}`,
+        description: candidate.description ?? `${candidate.operation} ${candidate.target ?? JSON.stringify(candidate.args)}`,
+        permissions: [...new Set(["computer", ...(candidate.permissions ?? [])])],
+        risk: candidate.risk ?? (CONSEQUENTIAL.has(candidate.operation) ? "medium" : "low"),
+        policy: { ...candidate.policy, requires_confirmation: CONSEQUENTIAL.has(candidate.operation) || candidate.consequential === true || candidate.requires_confirmation === true || candidate.policy?.requires_confirmation === true },
+        execution: { mode: "host", target: candidate.id },
+      })),
+      policy,
+    };
+  } catch {
+    return failed(null, null, "invalid_input", "Computer advice requires valid bounded actions and a matching PNG/JPEG screenshot", options);
+  }
+
+  let provider;
+  try {
+    provider = resolveProvider(options.provider ?? "typesafe", options);
+  } catch {
+    return failed(request, null, "provider_error", "Computer advice provider is unavailable", options);
+  }
+  if (provider.supportsImages !== true) return failed(request, null, "unsupported_images", "Provider does not support image input", options);
+
+  let decision;
+  try {
+    decision = await routeRequest(request, { ...options, engine: "native", discovery: undefined, provider });
+  } catch {
+    return failed(request, null, "invalid_input", "Computer routing request could not be validated", options);
+  }
+  if (!["selected", "needs_confirmation"].includes(decision.status)) return { request, decision, action: null };
+  const selected = actions.find((candidate) => candidate.id === decision.selected);
+  if (!selected) return failed(request, decision, "invalid_selection", "Selected action is outside the host candidate set", options);
+  let action = { ...selected, screenshot };
+  if (selected.operation === "click" && selected.args.x === undefined) {
+    if (typeof provider.evaluate !== "function") return failed(request, decision, "grounding_unavailable", "Provider cannot ground the selected target", options);
+    let raw;
+    try {
+      raw = await provider.evaluate({
+        state: { screenshot: Object.keys(request.assets)[0], target: selected.target },
+        assets: request.assets,
+        questions: {
+          target_visible: { type: "noul", instructions: "Is the exact target described in `target` clearly visible and uniquely identifiable in `screenshot`?" },
+          target_box: { type: "box", instructions: "Find the exact target described in `target` in `screenshot`." },
+        },
+      });
+    } catch {
+      return failed(request, decision, "provider_error", "Selected target grounding failed", options);
+    }
+    const visible = raw?.answers?.target_visible;
+    const located = raw?.answers?.target_box;
+    const box = located?.box;
+    if (visible?.type !== "noul" || !probability(visible.noul) || located?.type !== "box" || !probability(located.confidence) || !object(box)
+      || ![box.left, box.right, box.top, box.bottom].every(probability) || box.left >= box.right || box.top >= box.bottom) {
+      return failed(request, decision, "malformed_grounding", "Provider returned invalid target visibility or box", options);
+    }
+    if (visible.noul < thresholds.visibility) return failed(request, decision, "target_not_visible", "Selected target is not confidently visible", options);
+    if (located.confidence < thresholds.box) return failed(request, decision, "low_grounding_confidence", "Selected target box is below the host confidence threshold", options);
+    action = {
+      ...action,
+      args: {
+        ...selected.args,
+        x: Math.min(screenshot.width - 1, Math.floor((box.left + box.right) / 2 * screenshot.width)),
+        y: Math.min(screenshot.height - 1, Math.floor((box.top + box.bottom) / 2 * screenshot.height)),
+      },
+      grounding: {
+        box: { left: box.left, right: box.right, top: box.top, bottom: box.bottom },
+        visibility: visible.noul,
+        confidence: located.confidence,
+        coordinate_space: "screenshot_pixels",
+      },
+    };
+  }
+  return { request, decision, action };
+}
+
+function normalizeAction(raw, dimensions) {
+  if (!object(raw) || !text(raw.id, 240) || raw.id !== raw.id.trim() || !OPERATIONS.has(raw.operation)) throw new TypeError("invalid action");
+  const args = raw.args ?? {};
+  if (!object(args) || Object.keys(args).some((key) => !ARGUMENTS[raw.operation].includes(key))) throw new TypeError("invalid action arguments");
+  const hasCoordinates = args.x !== undefined || args.y !== undefined;
+  if (hasCoordinates && (!Number.isInteger(args.x) || args.x < 0 || args.x >= dimensions.width || !Number.isInteger(args.y) || args.y < 0 || args.y >= dimensions.height)) throw new TypeError("coordinates must be inside screenshot");
+  if (raw.target !== undefined && !text(raw.target, 1_000)) throw new TypeError("invalid target description");
+  if (raw.operation === "click" && (!hasCoordinates && !raw.target || args.button !== undefined && !["left", "middle", "right"].includes(args.button))) throw new TypeError("invalid click");
+  if (raw.operation === "type" && !text(args.text, 8_000)) throw new TypeError("invalid text");
+  if (raw.operation === "key" && (!Array.isArray(args.keys) || args.keys.length < 1 || args.keys.length > 8 || args.keys.some((key) => !text(key, 80)))) throw new TypeError("invalid keys");
+  if (raw.operation === "scroll" && (!["up", "down", "left", "right"].includes(args.direction) || args.amount !== undefined && (!Number.isInteger(args.amount) || args.amount < 1 || args.amount > 10_000))) throw new TypeError("invalid scroll");
+  if (raw.operation === "handoff" && args.reason !== undefined && !text(args.reason, 1_000)) throw new TypeError("invalid handoff reason");
+  if (raw.permissions !== undefined && (!Array.isArray(raw.permissions) || raw.permissions.some((permission) => !text(permission, 240)))) throw new TypeError("invalid permissions");
+  for (const key of ["name", "description"]) {
+    if (raw[key] !== undefined && !text(raw[key], key === "name" ? 240 : 2_000)) throw new TypeError(`invalid ${key}`);
+  }
+  for (const key of ["available", "requires_confirmation", "consequential", "verified"]) {
+    if (raw[key] !== undefined && typeof raw[key] !== "boolean") throw new TypeError(`invalid ${key}`);
+  }
+  if (raw.policy !== undefined && (!object(raw.policy) || raw.policy.requires_confirmation !== undefined && typeof raw.policy.requires_confirmation !== "boolean")) throw new TypeError("invalid confirmation policy");
+  if (raw.availability !== undefined && (!object(raw.availability) || raw.availability.available !== undefined && typeof raw.availability.available !== "boolean")) throw new TypeError("invalid availability");
+  const action = { id: raw.id, operation: raw.operation, args: structuredClone(args) };
+  for (const key of ["target", "name", "description", "permissions", "risk", "available", "availability", "requires_confirmation", "policy", "consequential", "source", "verified", "metadata"]) {
+    if (raw[key] !== undefined) action[key] = structuredClone(raw[key]);
+  }
+  return action;
+}
+
+function failed(request, decision, type, reason, options) {
+  const fallback = { type, reason };
+  return {
+    request,
+    action: null,
+    decision: decision ? { ...decision, status: "fallback", reason, fallback } : decisionEnvelope({
+      status: "fallback", reason, fallback,
+      provider: typeof options.provider === "string" ? options.provider : options.provider?.name ?? "typesafe",
+      latencyMs: 0, candidateCount: request?.capabilities.length ?? 0, contextBytes: 0,
+    }),
+  };
+}
+
+function object(value) {
+  return value !== null && typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+
+function text(value, maximum, allowEmpty = false) {
+  return typeof value === "string" && value.length <= maximum && (allowEmpty || value.trim().length > 0);
+}
+
+function probability(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}

package/src/config.mjs

@@ -7,6 +7,7 @@ export const DEFAULT_CONFIG = Object.freeze({
   replay_cases: ".jev/replay/cases.jsonl",
   features: {
     browser_fast_path: false,
+    computer_use: false,
     supervision: false,
     context_filter: null,
   },

package/src/context-filter.mjs

@@ -1,6 +1,6 @@
 import { byteLength, stableJson } from "./contract.mjs";
 import { filterContext, normalizeRelevanceMode } from "./relevance-filter.mjs";
-const SECRET_KEY = /(token|secret|password|passwd|api[_-]?key|authorization|cookie|credential|private[_-]?key|session)/i;
+const SECRET_KEY = /(token|secret|password|passwd|api[_-]?key|authorization|cookie|credential|private[_-]?key|session|data_base64)/i;
 const MAX_STRING = 2_000;
 const MAX_DEPTH = 4;
 

package/src/contract.mjs

@@ -39,6 +39,8 @@ export function normalizeRequest(input) {
     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,

package/src/hermes-adapter.mjs

@@ -8,6 +8,7 @@
  */
 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";
@@ -51,12 +52,20 @@ async function handle({ operation, args = {}, decision = null } = {}) {
    config,
     });
     routed.decision.browser_action = routed.action
-      ? { id: routed.action.id, operation: routed.action.operation, target_id: routed.action.target_id ?? null,
-          option_id: routed.action.option_id ?? null, consequential: routed.action.consequential }
+      ? { ...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({
@@ -106,7 +115,9 @@ async function handle({ operation, args = {}, decision = null } = {}) {
 }
 
 async function persistRoutingCase(request, decision) {
-  decision._jev_request = request;
+  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 };

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);
+}