@agent-native/core 0.93.0 → 0.94.0

package/corpus/core/src/integrations/remote-commands-store.ts

@@ -4,8 +4,30 @@ import {
   isPostgres,
   retryOnDdlRace,
 } from "../db/client.js";
-import { ensureTableExists, ensureIndexExists } from "../db/ddl-guard.js";
+import {
+  ensureColumnExists,
+  ensureTableExists,
+  ensureIndexExists,
+} from "../db/ddl-guard.js";
+import {
+  authorizeComputerOperation,
+  ensureComputerApprovalStore,
+} from "./computer-supervision-store.js";
+import {
+  assertValidComputerCommandEnvelope,
+  ComputerSupervisionError,
+} from "./computer-supervision.js";
+import {
+  getRemoteComputerCapabilities,
+  getRemoteDeviceForOwner,
+} from "./remote-devices-store.js";
+import {
+  assertNoBinaryPayload,
+  serializeBoundedRemoteJson,
+} from "./remote-json-safety.js";
 import type {
+  ComputerCommandEnvelope,
+  ComputerOperationClass,
   RemoteCommand,
   RemoteCommandKind,
   RemoteCommandStatus,
@@ -41,6 +63,14 @@ async function ensureTable(): Promise<void> {
   result_json TEXT,
   platform TEXT,
   external_thread_id TEXT,
+  computer_task_id TEXT,
+  computer_run_id TEXT,
+  computer_sequence ${intType()},
+  idempotency_key TEXT,
+  operation_class TEXT,
+  approval_scope TEXT,
+  action_hash TEXT,
+  lease_expires_at ${intType()},
   attempts ${intType()} NOT NULL DEFAULT 0,
   next_check_at ${intType()} NOT NULL,
   claimed_at ${intType()},
@@ -53,6 +83,7 @@ async function ensureTable(): Promise<void> {
       if (isPostgres()) {
         // PG guard: probe via information_schema, only issue DDL if missing, bounded lock_timeout
         await ensureTableExists("integration_remote_commands", createSql);
+        await ensureComputerCommandColumns();
         await ensureIndexExists(
           "idx_remote_commands_device_status_next",
           `CREATE INDEX IF NOT EXISTS idx_remote_commands_device_status_next ON integration_remote_commands(device_id, status, next_check_at)`,
@@ -61,16 +92,19 @@ async function ensureTable(): Promise<void> {
           "idx_remote_commands_owner",
           `CREATE INDEX IF NOT EXISTS idx_remote_commands_owner ON integration_remote_commands(owner_email, org_id)`,
         );
+        await ensureComputerCommandIndexes();
         return;
       }
 
       // SQLite: keep existing behavior
       await retryOnDdlRace(() => client.execute(createSql));
+      await ensureComputerCommandColumns();
       await retryOnDdlRace(() =>
         client.execute(
           `CREATE INDEX IF NOT EXISTS idx_remote_commands_device_status_next ON integration_remote_commands(device_id, status, next_check_at)`,
         ),
       );
+      await ensureComputerCommandIndexes();
       await retryOnDdlRace(() =>
         client.execute(
           `CREATE INDEX IF NOT EXISTS idx_remote_commands_owner ON integration_remote_commands(owner_email, org_id)`,
@@ -86,17 +120,22 @@ async function ensureTable(): Promise<void> {
 }
 
 function rowToCommand(row: Record<string, unknown>): RemoteCommand {
+  const params = parseJson(row.params_json, {});
   return {
     id: row.id as string,
     deviceId: row.device_id as string,
     ownerEmail: row.owner_email as string,
     orgId: (row.org_id as string | null) ?? null,
     kind: row.kind as RemoteCommandKind,
-    params: parseJson(row.params_json, {}),
+    params,
     status: row.status as RemoteCommandStatus,
     result: parseJson(row.result_json, null),
     platform: (row.platform as string | null) ?? null,
     externalThreadId: (row.external_thread_id as string | null) ?? null,
+    computerOperation:
+      row.kind === "computer-operation"
+        ? ((params as { envelope?: ComputerCommandEnvelope })?.envelope ?? null)
+        : null,
     attempts: Number(row.attempts ?? 0),
     nextCheckAt: Number(row.next_check_at ?? 0),
     claimedAt: row.claimed_at == null ? null : Number(row.claimed_at as number),
@@ -108,6 +147,48 @@ function rowToCommand(row: Record<string, unknown>): RemoteCommand {
   };
 }
 
+async function ensureComputerCommandColumns(): Promise<void> {
+  const columns: Array<[string, string]> = [
+    ["computer_task_id", "TEXT"],
+    ["computer_run_id", "TEXT"],
+    ["computer_sequence", intType()],
+    ["idempotency_key", "TEXT"],
+    ["operation_class", "TEXT"],
+    ["approval_scope", "TEXT"],
+    ["action_hash", "TEXT"],
+    ["lease_expires_at", intType()],
+  ];
+  for (const [name, definition] of columns) {
+    const sql = `ALTER TABLE integration_remote_commands ADD COLUMN${isPostgres() ? " IF NOT EXISTS" : ""} ${name} ${definition}`;
+    if (isPostgres()) {
+      await ensureColumnExists("integration_remote_commands", name, sql);
+      continue;
+    }
+    try {
+      await retryOnDdlRace(() => getDbExec().execute(sql));
+    } catch (error) {
+      if (!isDuplicateColumnError(error)) throw error;
+    }
+  }
+}
+
+async function ensureComputerCommandIndexes(): Promise<void> {
+  const indexes = [
+    [
+      "idx_remote_commands_computer_sequence",
+      `CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_commands_computer_sequence ON integration_remote_commands(device_id, computer_task_id, computer_run_id, computer_sequence)`,
+    ],
+    [
+      "idx_remote_commands_idempotency",
+      `CREATE UNIQUE INDEX IF NOT EXISTS idx_remote_commands_idempotency ON integration_remote_commands(device_id, idempotency_key)`,
+    ],
+  ] as const;
+  for (const [name, sql] of indexes) {
+    if (isPostgres()) await ensureIndexExists(name, sql);
+    else await retryOnDdlRace(() => getDbExec().execute(sql));
+  }
+}
+
 export function isRemoteCommandKind(
   value: unknown,
 ): value is RemoteCommandKind {
@@ -127,6 +208,12 @@ export async function enqueueRemoteCommand(input: {
   externalThreadId?: string | null;
   nextCheckAt?: number;
 }): Promise<RemoteCommand> {
+  if (input.kind === "computer-operation") {
+    throw new ComputerSupervisionError(
+      "invalid-envelope",
+      "Computer operations must use enqueueComputerCommand",
+    );
+  }
   await ensureTable();
   const client = getDbExec();
   const now = Date.now();
@@ -160,6 +247,96 @@ export async function enqueueRemoteCommand(input: {
   return command;
 }
 
+export async function enqueueComputerCommand(input: {
+  deviceId: string;
+  ownerEmail: string;
+  orgId?: string | null;
+  envelope: ComputerCommandEnvelope;
+  platform?: string | null;
+}): Promise<RemoteCommand> {
+  const envelope = await assertValidComputerCommandEnvelope(input.envelope);
+  const device = await getRemoteDeviceForOwner({
+    id: input.deviceId,
+    ownerEmail: input.ownerEmail,
+    orgId: input.orgId,
+  });
+  if (!device || device.status !== "active") {
+    throw new ComputerSupervisionError(
+      "approval-mismatch",
+      "Computer device does not belong to this owner and organization",
+    );
+  }
+  const capabilities = getRemoteComputerCapabilities(device);
+  const [surface, mode] = envelope.operationClass.split(".") as [
+    "browser" | "desktop",
+    "observe" | "control",
+  ];
+  if (capabilities?.[surface]?.[mode] !== true) {
+    throw new ComputerSupervisionError(
+      "approval-denied",
+      `Remote device did not advertise ${envelope.operationClass}`,
+    );
+  }
+  await ensureTable();
+  await ensureComputerApprovalStore();
+  const client = getDbExec();
+  const insert = async (tx: typeof client): Promise<string> => {
+    await authorizeComputerOperation({ ...input, envelope }, tx);
+    const now = Date.now();
+    const id = `remote-command-${now}-${randomHex(8)}`;
+    try {
+      await tx.execute({
+        sql: `INSERT INTO integration_remote_commands
+          (id, device_id, owner_email, org_id, kind, params_json, status,
+           result_json, platform, external_thread_id, computer_task_id,
+           computer_run_id, computer_sequence, idempotency_key, operation_class,
+           approval_scope, action_hash, lease_expires_at, attempts, next_check_at,
+           created_at, updated_at)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+        args: [
+          id,
+          input.deviceId,
+          input.ownerEmail,
+          input.orgId ?? null,
+          "computer-operation",
+          JSON.stringify({ envelope }),
+          "pending",
+          null,
+          input.platform ?? null,
+          null,
+          envelope.taskId,
+          envelope.runId,
+          envelope.sequence,
+          envelope.idempotencyKey,
+          envelope.operationClass,
+          envelope.approval.scope,
+          envelope.approval.actionHash,
+          envelope.leaseExpiresAt,
+          0,
+          now,
+          now,
+          now,
+        ],
+      });
+    } catch (error) {
+      if (isUniqueConstraintError(error)) {
+        throw new ComputerSupervisionError(
+          "replay",
+          "Computer operation sequence or idempotency key was already used",
+        );
+      }
+      throw error;
+    }
+    return id;
+  };
+  const id = client.transaction
+    ? await client.transaction((tx) => insert(tx))
+    : await insert(client);
+  const command = await getRemoteCommand(id);
+  if (!command) throw new Error("computer command insert failed");
+  return command;
+}
+
 export async function getRemoteCommand(
   id: string,
 ): Promise<RemoteCommand | null> {
@@ -209,6 +386,7 @@ export async function claimNextRemoteCommand(
     sql: `SELECT id FROM integration_remote_commands
           WHERE device_id = ?
             AND status = 'pending'
+            AND kind <> 'computer-operation'
             AND next_check_at <= ?
           ORDER BY created_at ASC
           LIMIT 1`,
@@ -240,6 +418,116 @@ export async function claimNextRemoteCommand(
   return command;
 }
 
+export async function claimNextComputerCommand(input: {
+  deviceId: string;
+  ownerEmail: string;
+  orgId?: string | null;
+  operationClasses?: ComputerOperationClass[];
+  now?: number;
+}): Promise<RemoteCommand | null> {
+  await ensureTable();
+  if (input.operationClasses?.length === 0) return null;
+  const client = getDbExec();
+  const now = input.now ?? Date.now();
+  const operationClassClause = input.operationClasses?.length
+    ? ` AND operation_class IN (${input.operationClasses.map(() => "?").join(", ")})`
+    : "";
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM integration_remote_commands
+          WHERE device_id = ? AND owner_email = ?
+            AND ((org_id IS NULL AND ? IS NULL) OR org_id = ?)
+            AND kind = 'computer-operation' AND status = 'pending'
+            AND next_check_at <= ?${operationClassClause}
+          ORDER BY computer_sequence ASC, created_at ASC
+          LIMIT 1`,
+    args: [
+      input.deviceId,
+      input.ownerEmail,
+      input.orgId ?? null,
+      input.orgId ?? null,
+      now,
+      ...(input.operationClasses ?? []),
+    ],
+  });
+  if (!rows[0]) return null;
+  const candidate = rowToCommand(rows[0] as Record<string, unknown>);
+  try {
+    const envelope = await assertValidComputerCommandEnvelope(
+      candidate.computerOperation,
+      { now },
+    );
+    const row = rows[0] as Record<string, unknown>;
+    if (
+      envelope.taskId !== row.computer_task_id ||
+      envelope.runId !== row.computer_run_id ||
+      envelope.sequence !== Number(row.computer_sequence) ||
+      envelope.idempotencyKey !== row.idempotency_key ||
+      envelope.operationClass !== row.operation_class ||
+      envelope.approval.scope !== row.approval_scope ||
+      envelope.approval.actionHash !== row.action_hash ||
+      envelope.leaseExpiresAt !== Number(row.lease_expires_at)
+    ) {
+      throw new ComputerSupervisionError(
+        "action-hash-mismatch",
+        "Stored computer command binding does not match its envelope",
+      );
+    }
+  } catch (error) {
+    await client.execute({
+      sql: `UPDATE integration_remote_commands
+            SET status = 'failed', error_message = ?, completed_at = ?, updated_at = ?
+            WHERE id = ? AND device_id = ? AND owner_email = ?
+              AND ((org_id IS NULL AND ? IS NULL) OR org_id = ?)
+              AND status = 'pending'`,
+      args: [
+        error instanceof Error
+          ? error.message.slice(0, 2000)
+          : "Invalid computer operation",
+        now,
+        now,
+        candidate.id,
+        input.deviceId,
+        input.ownerEmail,
+        input.orgId ?? null,
+        input.orgId ?? null,
+      ],
+    });
+    return null;
+  }
+
+  const result = await client.execute({
+    sql: isPostgres()
+      ? `UPDATE integration_remote_commands
+          SET status = 'claimed', attempts = attempts + 1, claimed_at = ?, updated_at = ?
+          WHERE id = ? AND device_id = ? AND owner_email = ?
+            AND ((org_id IS NULL AND ? IS NULL) OR org_id = ?)
+            AND status = 'pending' AND lease_expires_at > ?
+          RETURNING *`
+      : `UPDATE integration_remote_commands
+          SET status = 'claimed', attempts = attempts + 1, claimed_at = ?, updated_at = ?
+          WHERE id = ? AND device_id = ? AND owner_email = ?
+            AND ((org_id IS NULL AND ? IS NULL) OR org_id = ?)
+            AND status = 'pending' AND lease_expires_at > ?`,
+    args: [
+      now,
+      now,
+      candidate.id,
+      input.deviceId,
+      input.ownerEmail,
+      input.orgId ?? null,
+      input.orgId ?? null,
+      now,
+    ],
+  });
+  if (isPostgres()) {
+    const row = result.rows?.[0];
+    return row ? rowToCommand(row as Record<string, unknown>) : null;
+  }
+  if (affectedRows(result) === 0) return null;
+  const command = await getRemoteCommand(candidate.id);
+  return command?.status === "claimed" ? command : null;
+}
+
 export async function updateRemoteCommandResult(input: {
   deviceId: string;
   commandId: string;
@@ -252,7 +540,15 @@ export async function updateRemoteCommandResult(input: {
   const now = Date.now();
   const completedAt = TERMINAL_STATUSES.has(input.status) ? now : null;
   const resultJson =
-    input.result === undefined ? undefined : JSON.stringify(input.result);
+    input.result === undefined
+      ? undefined
+      : serializeBoundedRemoteJson(input.result, {
+          label: "Remote command result",
+          maxBytes: 256_000,
+        });
+  if (input.errorMessage) {
+    assertNoBinaryPayload(input.errorMessage, "Remote command error");
+  }
 
   await client.execute({
     sql: `UPDATE integration_remote_commands
@@ -357,3 +653,38 @@ function randomHex(byteLength: number): string {
     .map((byte) => byte.toString(16).padStart(2, "0"))
     .join("");
 }
+
+function affectedRows(result: {
+  rowsAffected?: number;
+  rows?: unknown[];
+}): number {
+  return (
+    result.rowsAffected ??
+    Number((result as { rowCount?: unknown }).rowCount ?? 0)
+  );
+}
+
+function isDuplicateColumnError(error: unknown): boolean {
+  const code = String((error as { code?: unknown })?.code ?? "");
+  const message = String((error as { message?: unknown })?.message ?? error)
+    .toLowerCase()
+    .trim();
+  return (
+    code === "42701" ||
+    message.includes("duplicate column") ||
+    message.includes("already exists")
+  );
+}
+
+function isUniqueConstraintError(error: unknown): boolean {
+  const code = String((error as { code?: unknown })?.code ?? "");
+  const message = String((error as { message?: unknown })?.message ?? error)
+    .toLowerCase()
+    .trim();
+  return (
+    code === "23505" ||
+    code === "2067" ||
+    message.includes("unique constraint") ||
+    message.includes("duplicate key")
+  );
+}

package/corpus/core/src/integrations/remote-devices-store.ts

@@ -9,7 +9,12 @@ import {
   ensureIndexExists,
   ensureTableExists,
 } from "../db/ddl-guard.js";
-import type { PublicRemoteDevice, RemoteDevice } from "./remote-types.js";
+import type {
+  PublicRemoteDevice,
+  RemoteComputerCapabilities,
+  RemoteDevice,
+  RemoteDeviceMetadata,
+} from "./remote-types.js";
 
 let _initPromise: Promise<void> | undefined;
 
@@ -136,10 +141,7 @@ function rowToDevice(row: Record<string, unknown>): RemoteDevice {
     platform: (row.platform as string | null) ?? null,
     appVersion: (row.app_version as string | null) ?? null,
     hostName: (row.host_name as string | null) ?? null,
-    metadata: parseJson(row.metadata_json, null) as Record<
-      string,
-      unknown
-    > | null,
+    metadata: parseJson(row.metadata_json, null) as RemoteDeviceMetadata | null,
     deviceTokenHash: row.device_token_hash as string,
     lastSeenAt:
       row.last_seen_at == null ? null : Number(row.last_seen_at as number),
@@ -168,6 +170,14 @@ export function toPublicRemoteDevice(device: RemoteDevice): PublicRemoteDevice {
   };
 }
 
+export function getRemoteComputerCapabilities(
+  device: Pick<RemoteDevice, "metadata">,
+): RemoteComputerCapabilities | null {
+  const value = device.metadata?.computerCapabilities;
+  if (!value || typeof value !== "object") return null;
+  return normalizeComputerCapabilities(value);
+}
+
 export async function createRemoteDevice(input: {
   ownerEmail: string;
   orgId?: string | null;
@@ -175,7 +185,7 @@ export async function createRemoteDevice(input: {
   platform?: string | null;
   appVersion?: string | null;
   hostName?: string | null;
-  metadata?: Record<string, unknown> | null;
+  metadata?: RemoteDeviceMetadata | null;
 }): Promise<{ device: RemoteDevice; token: string }> {
   await ensureTable();
   const client = getDbExec();
@@ -197,7 +207,7 @@ export async function createRemoteDevice(input: {
       sanitizeOptionalString(input.platform, 80),
       sanitizeOptionalString(input.appVersion, 120),
       sanitizeOptionalString(input.hostName, 200),
-      input.metadata ? JSON.stringify(input.metadata) : null,
+      serializeRemoteDeviceMetadata(input.metadata),
       tokenHash,
       now,
       "active",
@@ -316,7 +326,7 @@ export async function updateRemoteDeviceDetails(input: {
   platform?: string | null;
   appVersion?: string | null;
   hostName?: string | null;
-  metadata?: Record<string, unknown> | null;
+  metadata?: RemoteDeviceMetadata | null;
 }): Promise<RemoteDevice | null> {
   await ensureTable();
   const now = Date.now();
@@ -340,7 +350,7 @@ export async function updateRemoteDeviceDetails(input: {
   }
   if (input.metadata !== undefined) {
     updates.push("metadata_json = ?");
-    args.push(input.metadata ? JSON.stringify(input.metadata) : null);
+    args.push(serializeRemoteDeviceMetadata(input.metadata));
   }
   if (updates.length === 0) return getRemoteDevice(input.id);
 
@@ -420,6 +430,55 @@ function parseJson(value: unknown, fallback: unknown): unknown {
   }
 }
 
+function serializeRemoteDeviceMetadata(
+  metadata: RemoteDeviceMetadata | null | undefined,
+): string | null {
+  if (!metadata) return null;
+  const normalized: RemoteDeviceMetadata = { ...metadata };
+  if (metadata.computerCapabilities !== undefined) {
+    normalized.computerCapabilities = normalizeComputerCapabilities(
+      metadata.computerCapabilities,
+    );
+  }
+  const json = JSON.stringify(normalized);
+  if (new TextEncoder().encode(json).byteLength > 32_768) {
+    throw new Error("Remote device metadata exceeds 32 KiB");
+  }
+  if (/"data:[^"]*"/i.test(json) || looksLikeLargeBase64(json)) {
+    throw new Error("Remote device metadata cannot contain binary payloads");
+  }
+  return json;
+}
+
+function normalizeComputerCapabilities(
+  value: RemoteComputerCapabilities,
+): RemoteComputerCapabilities {
+  const result: RemoteComputerCapabilities = {};
+  if (value.browser && typeof value.browser === "object") {
+    result.browser = {
+      observe: value.browser.observe === true,
+      control: value.browser.control === true,
+      provider: sanitizeOptionalString(value.browser.provider, 120),
+      version: sanitizeOptionalString(value.browser.version, 120),
+    };
+  }
+  if (value.desktop && typeof value.desktop === "object") {
+    result.desktop = {
+      observe: value.desktop.observe === true,
+      control: value.desktop.control === true,
+      accessibility: value.desktop.accessibility === true,
+      screenCapture: value.desktop.screenCapture === true,
+      provider: sanitizeOptionalString(value.desktop.provider, 120),
+      version: sanitizeOptionalString(value.desktop.version, 120),
+    };
+  }
+  return result;
+}
+
+function looksLikeLargeBase64(value: string): boolean {
+  return value.length > 4_096 && /[A-Za-z0-9+/]{4_096,}={0,2}/.test(value);
+}
+
 function randomHex(byteLength: number): string {
   const bytes = new Uint8Array(byteLength);
   globalThis.crypto.getRandomValues(bytes);

package/corpus/core/src/integrations/remote-json-safety.ts

@@ -0,0 +1,127 @@
+const DATA_URL_PATTERN = /data:[a-z][^;,]{0,100}[;,]/i;
+const BASE64_PREFIX_PATTERN = /(?:^|[,;])base64,/i;
+const MAX_TRAVERSAL_DEPTH = 20;
+const MAX_TRAVERSAL_NODES = 25_000;
+const BINARY_FIELD_NAMES = new Set([
+  "base64",
+  "dataurl",
+  "image",
+  "imagebase64",
+  "imagedata",
+  "imagebytes",
+  "screenshot",
+  "screenshotbase64",
+  "screenshotdata",
+  "bytes",
+  "buffer",
+]);
+
+export function serializeBoundedRemoteJson(
+  value: unknown,
+  options: { label: string; maxBytes: number },
+): string {
+  assertNoBinaryPayload(value, options.label);
+  let json: string | undefined;
+  try {
+    json = JSON.stringify(value);
+  } catch {
+    throw new Error(`${options.label} must contain only serializable JSON`);
+  }
+  if (json === undefined) {
+    throw new Error(`${options.label} must contain a JSON value`);
+  }
+  const bytes = new TextEncoder().encode(json).byteLength;
+  if (bytes > options.maxBytes) {
+    throw new Error(`${options.label} exceeds ${options.maxBytes} JSON bytes`);
+  }
+  return json;
+}
+
+export function assertNoBinaryPayload(value: unknown, label: string): void {
+  let visited = 0;
+  const seen = new Set<object>();
+  const visit = (entry: unknown, depth: number, key?: string): void => {
+    visited++;
+    if (visited > MAX_TRAVERSAL_NODES || depth > MAX_TRAVERSAL_DEPTH) {
+      throw new Error(`${label} is too deeply nested or complex`);
+    }
+    if (typeof entry === "string") {
+      const trimmed = entry.trim();
+      if (
+        DATA_URL_PATTERN.test(trimmed) ||
+        BASE64_PREFIX_PATTERN.test(trimmed) ||
+        looksLikeBase64(trimmed) ||
+        (isBinaryFieldName(key) && trimmed.length > 0)
+      ) {
+        throw new Error(
+          `${label} cannot contain screenshots, images, base64, or data URLs`,
+        );
+      }
+      return;
+    }
+    if (
+      entry == null ||
+      typeof entry === "number" ||
+      typeof entry === "boolean"
+    ) {
+      return;
+    }
+    if (
+      typeof entry === "bigint" ||
+      typeof entry === "function" ||
+      typeof entry === "symbol" ||
+      typeof entry === "undefined"
+    ) {
+      throw new Error(`${label} must contain only serializable JSON`);
+    }
+    if (ArrayBuffer.isView(entry) || entry instanceof ArrayBuffer) {
+      throw new Error(`${label} cannot contain binary buffers`);
+    }
+    if (typeof Blob !== "undefined" && entry instanceof Blob) {
+      throw new Error(`${label} cannot contain binary blobs`);
+    }
+    if (typeof entry !== "object") return;
+    if (seen.has(entry)) {
+      throw new Error(`${label} must not contain circular values`);
+    }
+    seen.add(entry);
+    if (Array.isArray(entry)) {
+      if (isBinaryFieldName(key) && entry.length > 0) {
+        throw new Error(`${label} cannot contain binary arrays`);
+      }
+      for (const item of entry) visit(item, depth + 1, key);
+      seen.delete(entry);
+      return;
+    }
+    const record = entry as Record<string, unknown>;
+    if (record.type === "Buffer" && Array.isArray(record.data)) {
+      throw new Error(`${label} cannot contain serialized buffers`);
+    }
+    for (const [childKey, child] of Object.entries(record)) {
+      if (isBinaryFieldName(childKey) && child != null) {
+        throw new Error(
+          `${label} cannot contain screenshots, images, base64, or data URLs`,
+        );
+      }
+      visit(child, depth + 1, childKey);
+    }
+    seen.delete(entry);
+  };
+  visit(value, 0);
+}
+
+function isBinaryFieldName(key: string | undefined): boolean {
+  if (!key) return false;
+  const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+  return BINARY_FIELD_NAMES.has(normalized);
+}
+
+function looksLikeBase64(value: string): boolean {
+  if (value.length < 512) return false;
+  const compact = value.replace(/[\r\n]/g, "");
+  return (
+    compact.length >= 512 &&
+    compact.length % 4 === 0 &&
+    /^[A-Za-z0-9+/]+={0,2}$/.test(compact)
+  );
+}