@agent-native/core 0.93.0 → 0.94.0

package/corpus/core/src/integrations/computer-supervision-store.ts

@@ -0,0 +1,423 @@
+import type { DbExec } from "../db/client.js";
+import {
+  getDbExec,
+  intType,
+  isPostgres,
+  retryOnDdlRace,
+} from "../db/client.js";
+import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
+import {
+  assertValidComputerCommandEnvelope,
+  ComputerSupervisionError,
+  computerOperationRequiresApproval,
+} from "./computer-supervision.js";
+import { getRemoteDeviceForOwner } from "./remote-devices-store.js";
+import { serializeBoundedRemoteJson } from "./remote-json-safety.js";
+import type {
+  ComputerApprovalScope,
+  ComputerCommandEnvelope,
+  ComputerOperationClass,
+} from "./remote-types.js";
+
+export type ComputerApprovalStatus =
+  | "pending"
+  | "approved"
+  | "denied"
+  | "consumed"
+  | "expired";
+
+export interface ComputerApprovalRecord {
+  id: string;
+  ownerEmail: string;
+  orgId: string | null;
+  deviceId: string;
+  taskId: string;
+  runId: string;
+  operationClass: ComputerOperationClass;
+  scope: ComputerApprovalScope;
+  actionHash: string;
+  status: ComputerApprovalStatus;
+  decisionResult: Record<string, unknown> | null;
+  decidedBy: string | null;
+  decidedAt: number | null;
+  expiresAt: number;
+  consumedAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+let _initPromise: Promise<void> | undefined;
+
+export async function ensureComputerApprovalStore(): Promise<void> {
+  if (!_initPromise) {
+    _initPromise = (async () => {
+      const createSql = `CREATE TABLE IF NOT EXISTS integration_computer_approvals (
+  id TEXT PRIMARY KEY,
+  owner_email TEXT NOT NULL,
+  org_id TEXT,
+  device_id TEXT NOT NULL,
+  task_id TEXT NOT NULL,
+  run_id TEXT NOT NULL,
+  operation_class TEXT NOT NULL,
+  approval_scope TEXT NOT NULL,
+  action_hash TEXT NOT NULL,
+  status TEXT NOT NULL,
+  decision_result_json TEXT,
+  decided_by TEXT,
+  decided_at ${intType()},
+  expires_at ${intType()} NOT NULL,
+  consumed_at ${intType()},
+  created_at ${intType()} NOT NULL,
+  updated_at ${intType()} NOT NULL
+)`;
+      if (isPostgres()) {
+        await ensureTableExists("integration_computer_approvals", createSql);
+        await ensureIndexExists(
+          "idx_computer_approvals_owner",
+          `CREATE INDEX IF NOT EXISTS idx_computer_approvals_owner ON integration_computer_approvals(owner_email, org_id, updated_at)`,
+        );
+        await ensureIndexExists(
+          "idx_computer_approvals_binding",
+          `CREATE INDEX IF NOT EXISTS idx_computer_approvals_binding ON integration_computer_approvals(device_id, task_id, run_id, action_hash)`,
+        );
+        return;
+      }
+      const client = getDbExec();
+      await retryOnDdlRace(() => client.execute(createSql));
+      await retryOnDdlRace(() =>
+        client.execute(
+          `CREATE INDEX IF NOT EXISTS idx_computer_approvals_owner ON integration_computer_approvals(owner_email, org_id, updated_at)`,
+        ),
+      );
+      await retryOnDdlRace(() =>
+        client.execute(
+          `CREATE INDEX IF NOT EXISTS idx_computer_approvals_binding ON integration_computer_approvals(device_id, task_id, run_id, action_hash)`,
+        ),
+      );
+    })().catch((error) => {
+      _initPromise = undefined;
+      throw error;
+    });
+  }
+  return _initPromise;
+}
+
+export async function createComputerApprovalRequest(input: {
+  ownerEmail: string;
+  orgId?: string | null;
+  deviceId: string;
+  envelope: ComputerCommandEnvelope;
+}): Promise<ComputerApprovalRecord> {
+  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",
+    );
+  }
+  await ensureComputerApprovalStore();
+  const envelope = await assertValidComputerCommandEnvelope(input.envelope);
+  const now = Date.now();
+  const id = `computer-approval-${now}-${randomHex(8)}`;
+  await getDbExec().execute({
+    sql: `INSERT INTO integration_computer_approvals
+      (id, owner_email, org_id, device_id, task_id, run_id, operation_class,
+       approval_scope, action_hash, status, decision_result_json, decided_by,
+       decided_at, expires_at, consumed_at, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    args: [
+      id,
+      input.ownerEmail,
+      input.orgId ?? null,
+      input.deviceId,
+      envelope.taskId,
+      envelope.runId,
+      envelope.operationClass,
+      envelope.approval.scope,
+      envelope.approval.actionHash,
+      "pending",
+      null,
+      null,
+      null,
+      envelope.leaseExpiresAt,
+      null,
+      now,
+      now,
+    ],
+  });
+  const approval = await getComputerApprovalForOwner({
+    id,
+    ownerEmail: input.ownerEmail,
+    orgId: input.orgId,
+  });
+  if (!approval) throw new Error("computer approval insert failed");
+  return approval;
+}
+
+export async function decideComputerApproval(input: {
+  id: string;
+  ownerEmail: string;
+  orgId?: string | null;
+  actionHash: string;
+  decision: "approved" | "denied";
+  decidedBy: string;
+  result?: Record<string, unknown> | null;
+}): Promise<ComputerApprovalRecord | null> {
+  await ensureComputerApprovalStore();
+  const now = Date.now();
+  const resultJson = serializeDecisionResult(input.result);
+  const result = await getDbExec().execute({
+    sql: `UPDATE integration_computer_approvals
+          SET status = ?, decision_result_json = ?, decided_by = ?,
+              decided_at = ?, updated_at = ?
+          WHERE id = ? AND owner_email = ?
+            AND ((org_id IS NULL AND ? IS NULL) OR org_id = ?)
+            AND action_hash = ? AND status = 'pending' AND expires_at > ?`,
+    args: [
+      input.decision,
+      resultJson,
+      input.decidedBy.slice(0, 240),
+      now,
+      now,
+      input.id,
+      input.ownerEmail,
+      input.orgId ?? null,
+      input.orgId ?? null,
+      input.actionHash,
+      now,
+    ],
+  });
+  if (affectedRows(result) === 0) return null;
+  return getComputerApprovalForOwner(input);
+}
+
+export async function getComputerApprovalForOwner(input: {
+  id: string;
+  ownerEmail: string;
+  orgId?: string | null;
+}): Promise<ComputerApprovalRecord | null> {
+  await ensureComputerApprovalStore();
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT * FROM integration_computer_approvals
+          WHERE id = ? AND owner_email = ?
+            AND ((org_id IS NULL AND ? IS NULL) OR org_id = ?)
+          LIMIT 1`,
+    args: [
+      input.id,
+      input.ownerEmail,
+      input.orgId ?? null,
+      input.orgId ?? null,
+    ],
+  });
+  return rows[0] ? rowToApproval(rows[0] as Record<string, unknown>) : null;
+}
+
+export async function listComputerApprovalsForOwner(input: {
+  ownerEmail: string;
+  orgId?: string | null;
+  deviceId?: string;
+  taskId?: string;
+  runId?: string;
+  status?: ComputerApprovalStatus;
+  limit?: number;
+}): Promise<ComputerApprovalRecord[]> {
+  await ensureComputerApprovalStore();
+  const clauses = [
+    "owner_email = ?",
+    "((org_id IS NULL AND ? IS NULL) OR org_id = ?)",
+  ];
+  const args: Array<string | number | null> = [
+    input.ownerEmail,
+    input.orgId ?? null,
+    input.orgId ?? null,
+  ];
+  if (input.deviceId) {
+    clauses.push("device_id = ?");
+    args.push(input.deviceId);
+  }
+  if (input.taskId) {
+    clauses.push("task_id = ?");
+    args.push(input.taskId);
+  }
+  if (input.runId) {
+    clauses.push("run_id = ?");
+    args.push(input.runId);
+  }
+  if (input.status) {
+    clauses.push("status = ?");
+    args.push(input.status);
+  }
+  args.push(Math.max(1, Math.min(input.limit ?? 100, 250)));
+  const { rows } = await getDbExec().execute({
+    sql: `SELECT * FROM integration_computer_approvals
+          WHERE ${clauses.join(" AND ")}
+          ORDER BY updated_at DESC
+          LIMIT ?`,
+    args,
+  });
+  return rows.map((row) => rowToApproval(row as Record<string, unknown>));
+}
+
+/**
+ * Authorizes an operation immediately before it is enqueued. Callers should
+ * pass their transaction handle so one-shot approval consumption and command
+ * insertion commit atomically.
+ */
+export async function authorizeComputerOperation(
+  input: {
+    ownerEmail: string;
+    orgId?: string | null;
+    deviceId: string;
+    envelope: ComputerCommandEnvelope;
+    now?: number;
+  },
+  client: DbExec = getDbExec(),
+): Promise<void> {
+  const now = input.now ?? Date.now();
+  if (input.envelope.leaseExpiresAt <= now) {
+    throw new ComputerSupervisionError(
+      "expired-lease",
+      "Computer operation lease has expired",
+    );
+  }
+  if (!computerOperationRequiresApproval(input.envelope.operationClass)) return;
+  const approvalId = input.envelope.approval.id;
+  if (!approvalId) {
+    throw new ComputerSupervisionError(
+      "approval-required",
+      "Computer control requires an approved action binding",
+    );
+  }
+  const { rows } = await client.execute({
+    sql: `SELECT * FROM integration_computer_approvals
+          WHERE id = ? AND owner_email = ?
+            AND ((org_id IS NULL AND ? IS NULL) OR org_id = ?)
+            AND device_id = ? AND task_id = ? AND run_id = ?
+          LIMIT 1`,
+    args: [
+      approvalId,
+      input.ownerEmail,
+      input.orgId ?? null,
+      input.orgId ?? null,
+      input.deviceId,
+      input.envelope.taskId,
+      input.envelope.runId,
+    ],
+  });
+  if (!rows[0]) {
+    throw new ComputerSupervisionError(
+      "approval-mismatch",
+      "Computer approval does not belong to this owner, device, task, and run",
+    );
+  }
+  const approval = rowToApproval(rows[0] as Record<string, unknown>);
+  if (
+    approval.actionHash !== input.envelope.approval.actionHash ||
+    approval.operationClass !== input.envelope.operationClass ||
+    approval.scope !== input.envelope.approval.scope
+  ) {
+    throw new ComputerSupervisionError(
+      "approval-mismatch",
+      "Computer approval does not match the requested action",
+    );
+  }
+  if (approval.expiresAt <= now) {
+    await client.execute({
+      sql: `UPDATE integration_computer_approvals
+            SET status = 'expired', updated_at = ?
+            WHERE id = ? AND status IN ('pending', 'approved')`,
+      args: [now, approval.id],
+    });
+    throw new ComputerSupervisionError(
+      "approval-denied",
+      "Computer approval has expired",
+    );
+  }
+  if (approval.status !== "approved") {
+    throw new ComputerSupervisionError(
+      approval.status === "consumed" ? "replay" : "approval-denied",
+      approval.status === "consumed"
+        ? "One-shot computer approval has already been consumed"
+        : "Computer action is not approved",
+    );
+  }
+  if (approval.scope !== "once") return;
+  const result = await client.execute({
+    sql: `UPDATE integration_computer_approvals
+          SET status = 'consumed', consumed_at = ?, updated_at = ?
+          WHERE id = ? AND status = 'approved'`,
+    args: [now, now, approval.id],
+  });
+  if (affectedRows(result) === 0) {
+    throw new ComputerSupervisionError(
+      "replay",
+      "One-shot computer approval has already been consumed",
+    );
+  }
+}
+
+function rowToApproval(row: Record<string, unknown>): ComputerApprovalRecord {
+  return {
+    id: String(row.id),
+    ownerEmail: String(row.owner_email),
+    orgId: row.org_id == null ? null : String(row.org_id),
+    deviceId: String(row.device_id),
+    taskId: String(row.task_id),
+    runId: String(row.run_id),
+    operationClass: row.operation_class as ComputerOperationClass,
+    scope: row.approval_scope as ComputerApprovalScope,
+    actionHash: String(row.action_hash),
+    status: row.status as ComputerApprovalStatus,
+    decisionResult: parseRecord(row.decision_result_json),
+    decidedBy: row.decided_by == null ? null : String(row.decided_by),
+    decidedAt: row.decided_at == null ? null : Number(row.decided_at),
+    expiresAt: Number(row.expires_at),
+    consumedAt: row.consumed_at == null ? null : Number(row.consumed_at),
+    createdAt: Number(row.created_at),
+    updatedAt: Number(row.updated_at),
+  };
+}
+
+function serializeDecisionResult(
+  result: Record<string, unknown> | null | undefined,
+): string | null {
+  if (!result) return null;
+  return serializeBoundedRemoteJson(result, {
+    label: "Computer approval result",
+    maxBytes: 8_192,
+  });
+}
+
+function parseRecord(value: unknown): Record<string, unknown> | null {
+  if (value == null) return null;
+  try {
+    const parsed = JSON.parse(String(value));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function affectedRows(result: {
+  rowsAffected?: number;
+  rows?: unknown[];
+}): number {
+  return (
+    result.rowsAffected ??
+    Number((result as { rowCount?: unknown }).rowCount ?? 0)
+  );
+}
+
+function randomHex(byteLength: number): string {
+  const bytes = new Uint8Array(byteLength);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes)
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}

package/corpus/core/src/integrations/computer-supervision.ts

@@ -0,0 +1,213 @@
+import type {
+  ComputerCommandEnvelope,
+  ComputerOperationClass,
+} from "./remote-types.js";
+
+const OPERATION_CLASSES = new Set<ComputerOperationClass>([
+  "browser.observe",
+  "browser.control",
+  "desktop.observe",
+  "desktop.control",
+]);
+const APPROVAL_SCOPES = new Set(["once", "run", "task"] as const);
+const MAX_ACTION_BYTES = 32_768;
+const MAX_LEASE_MS = 24 * 60 * 60_000;
+
+export class ComputerSupervisionError extends Error {
+  constructor(
+    public readonly code:
+      | "invalid-envelope"
+      | "expired-lease"
+      | "action-hash-mismatch"
+      | "approval-required"
+      | "approval-denied"
+      | "approval-mismatch"
+      | "replay",
+    message: string,
+  ) {
+    super(message);
+    this.name = "ComputerSupervisionError";
+  }
+}
+
+export function computerOperationRequiresApproval(
+  operationClass: ComputerOperationClass,
+): boolean {
+  return operationClass.endsWith(".control");
+}
+
+export async function computeComputerActionHash(
+  envelope: Pick<
+    ComputerCommandEnvelope,
+    "version" | "taskId" | "runId" | "sequence" | "operationClass" | "action"
+  >,
+): Promise<string> {
+  const canonical = stableJson({
+    version: envelope.version,
+    taskId: envelope.taskId,
+    runId: envelope.runId,
+    sequence: envelope.sequence,
+    operationClass: envelope.operationClass,
+    action: envelope.action,
+  });
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(canonical),
+  );
+  return Array.from(new Uint8Array(digest))
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+export async function assertValidComputerCommandEnvelope(
+  value: unknown,
+  options?: { now?: number },
+): Promise<ComputerCommandEnvelope> {
+  if (!isRecord(value)) {
+    throw invalid("Computer command envelope must be an object");
+  }
+  if (value.version !== 1) {
+    throw invalid("Unsupported computer command envelope version");
+  }
+  const taskId = boundedString(value.taskId, "taskId", 200);
+  const runId = boundedString(value.runId, "runId", 200);
+  const idempotencyKey = boundedString(
+    value.idempotencyKey,
+    "idempotencyKey",
+    200,
+  );
+  if (!Number.isSafeInteger(value.sequence) || Number(value.sequence) < 0) {
+    throw invalid("sequence must be a non-negative safe integer");
+  }
+  if (!OPERATION_CLASSES.has(value.operationClass as ComputerOperationClass)) {
+    throw invalid("Unknown computer operation class");
+  }
+  if (!isRecord(value.action)) {
+    throw invalid("action must be an object");
+  }
+  boundedString(value.action.type, "action.type", 120);
+  const actionJson = stableJson(value.action);
+  if (new TextEncoder().encode(actionJson).byteLength > MAX_ACTION_BYTES) {
+    throw invalid("Computer action exceeds the 32 KiB metadata limit");
+  }
+  if (!isRecord(value.approval)) {
+    throw invalid("approval binding is required");
+  }
+  if (!APPROVAL_SCOPES.has(value.approval.scope as any)) {
+    throw invalid("Unknown computer approval scope");
+  }
+  const actionHash = boundedString(
+    value.approval.actionHash,
+    "approval.actionHash",
+    64,
+  ).toLowerCase();
+  if (!/^[a-f0-9]{64}$/.test(actionHash)) {
+    throw invalid("approval.actionHash must be a SHA-256 hex digest");
+  }
+  const approvalId =
+    value.approval.id == null
+      ? null
+      : boundedString(value.approval.id, "approval.id", 240);
+  if (!Number.isSafeInteger(value.issuedAt) || Number(value.issuedAt) < 0) {
+    throw invalid("issuedAt must be a valid epoch timestamp");
+  }
+  if (
+    !Number.isSafeInteger(value.leaseExpiresAt) ||
+    Number(value.leaseExpiresAt) < 0
+  ) {
+    throw invalid("leaseExpiresAt must be a valid epoch timestamp");
+  }
+  const now = options?.now ?? Date.now();
+  const issuedAt = Number(value.issuedAt);
+  const leaseExpiresAt = Number(value.leaseExpiresAt);
+  if (leaseExpiresAt <= now || leaseExpiresAt <= issuedAt) {
+    throw new ComputerSupervisionError(
+      "expired-lease",
+      "Computer operation lease has expired",
+    );
+  }
+  if (leaseExpiresAt - issuedAt > MAX_LEASE_MS) {
+    throw invalid("Computer operation lease cannot exceed 24 hours");
+  }
+
+  const envelope: ComputerCommandEnvelope = {
+    version: 1,
+    taskId,
+    runId,
+    sequence: Number(value.sequence),
+    idempotencyKey,
+    operationClass: value.operationClass as ComputerOperationClass,
+    action: value.action as ComputerCommandEnvelope["action"],
+    approval: {
+      id: approvalId,
+      scope: value.approval
+        .scope as ComputerCommandEnvelope["approval"]["scope"],
+      actionHash,
+    },
+    issuedAt,
+    leaseExpiresAt,
+  };
+  const expectedHash = await computeComputerActionHash(envelope);
+  if (expectedHash !== actionHash) {
+    throw new ComputerSupervisionError(
+      "action-hash-mismatch",
+      "Computer operation does not match its approved action hash",
+    );
+  }
+  return envelope;
+}
+
+function stableJson(value: unknown): string {
+  const seen = new Set<object>();
+  const normalize = (entry: unknown, depth: number): unknown => {
+    if (depth > 12) throw invalid("Computer action is nested too deeply");
+    if (
+      entry === null ||
+      typeof entry === "string" ||
+      typeof entry === "boolean"
+    ) {
+      if (
+        typeof entry === "string" &&
+        (/^data:/i.test(entry) || looksLikeLargeBase64(entry))
+      ) {
+        throw invalid("Binary or data URL payloads are not allowed");
+      }
+      return entry;
+    }
+    if (typeof entry === "number" && Number.isFinite(entry)) return entry;
+    if (Array.isArray(entry)) {
+      return entry.map((item) => normalize(item, depth + 1));
+    }
+    if (!isRecord(entry)) {
+      throw invalid("Computer actions must contain only JSON values");
+    }
+    if (seen.has(entry)) throw invalid("Computer action contains a cycle");
+    seen.add(entry);
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(entry).sort()) {
+      result[key] = normalize(entry[key], depth + 1);
+    }
+    seen.delete(entry);
+    return result;
+  };
+  return JSON.stringify(normalize(value, 0));
+}
+
+function looksLikeLargeBase64(value: string): boolean {
+  return value.length > 512 && /^[A-Za-z0-9+/]+={0,2}$/.test(value);
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function boundedString(value: unknown, name: string, max: number): string {
+  if (typeof value !== "string" || !value.trim() || value.length > max) {
+    throw invalid(`${name} must be a non-empty string of at most ${max} chars`);
+  }
+  return value.trim();
+}
+
+function invalid(message: string): ComputerSupervisionError {
+  return new ComputerSupervisionError("invalid-envelope", message);
+}

package/corpus/core/src/integrations/index.ts

@@ -43,11 +43,32 @@ export {
 } from "./plugin.js";
 
 export {
+  getRemoteComputerCapabilities,
   listRemoteDevicesForOwner,
   revokeRemoteDeviceForOwner,
   unregisterRemoteDevice,
 } from "./remote-devices-store.js";
-export { listRemoteCommandsForOwner } from "./remote-commands-store.js";
+export {
+  claimNextComputerCommand,
+  enqueueComputerCommand,
+  listRemoteCommandsForOwner,
+} from "./remote-commands-store.js";
+export {
+  assertValidComputerCommandEnvelope,
+  computeComputerActionHash,
+  computerOperationRequiresApproval,
+  ComputerSupervisionError,
+} from "./computer-supervision.js";
+export {
+  authorizeComputerOperation,
+  createComputerApprovalRequest,
+  decideComputerApproval,
+  getComputerApprovalForOwner,
+  listComputerApprovalsForOwner,
+  type ComputerApprovalRecord,
+  type ComputerApprovalStatus,
+} from "./computer-supervision-store.js";
+export { insertRemoteLiveViewEvents } from "./remote-run-events-store.js";
 export {
   listRemotePushNotificationsForOwner,
   listRemotePushRegistrationsForOwner,
@@ -57,10 +78,17 @@ export {
   upsertRemotePushRegistration,
 } from "./remote-push-store.js";
 export type {
+  ComputerApprovalScope,
+  ComputerCommandAction,
+  ComputerCommandEnvelope,
+  ComputerOperationClass,
   PublicRemotePushRegistration,
   PublicRemoteDevice,
+  RemoteComputerCapabilities,
   RemoteCommand,
   RemoteDevice,
+  RemoteDeviceMetadata,
+  RemoteLiveViewEvent,
   RemotePushNotification,
   RemotePushRegistration,
   RemoteRunEvent,