@arnilo/prism-tools 0.0.0-stage → 0.13.1

package/browser/src/downloads.ts

@@ -0,0 +1,253 @@
+/**
+ * Bounded download quarantine: stream → hash/MIME/name metadata → host release approval.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir, open, rm } from "node:fs/promises";
+import { basename, isAbsolute, join, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { BrowserError } from "./errors.js";
+import type { ResolvedBrowserLimits } from "./limits.js";
+import type { PlaywrightDownload } from "./types.js";
+
+export interface BrowserDownloadOptions {
+  /** Absolute quarantine directory (typically sandbox `/downloads` on host or bind). */
+  readonly quarantine: string;
+  /** Per-file byte cap override (still clamped by resolved limits). */
+  readonly maxBytes?: number;
+  /**
+   * Host callback required before a quarantined download may leave quarantine.
+   * Returning false keeps the file quarantined (and eligible for cleanup).
+   */
+  readonly approveRelease?: (meta: DownloadMetadata) => boolean | Promise<boolean>;
+}
+
+export interface DownloadMetadata {
+  readonly downloadId: string;
+  readonly suggestedName: string;
+  readonly safeName: string;
+  readonly quarantinePath: string;
+  readonly url: string;
+  readonly bytes: number;
+  readonly sha256: string;
+  readonly mimeType?: string;
+  readonly released: boolean;
+}
+
+export interface DownloadBudget {
+  count: number;
+  aggregateBytes: number;
+  readonly items: Map<string, DownloadMetadata & { released: boolean }>;
+}
+
+export function createDownloadBudget(): DownloadBudget {
+  return { count: 0, aggregateBytes: 0, items: new Map() };
+}
+
+export function sanitizeDownloadName(name: string): string {
+  const base = basename(name || "download.bin").replace(/[\u0000-\u001f\u007f]/g, "");
+  const cleaned = base.replace(/[^A-Za-z0-9._-]+/g, "_").replace(/^\.+/, "");
+  const trimmed = cleaned.slice(0, 128) || "download.bin";
+  if (trimmed === "." || trimmed === ".." || trimmed.includes("/") || trimmed.includes("\\")) {
+    return "download.bin";
+  }
+  return trimmed;
+}
+
+function sniffMime(buf: Buffer): string | undefined {
+  if (buf.length >= 8 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+    return "image/png";
+  }
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return "image/jpeg";
+  if (buf.length >= 4 && buf.toString("ascii", 0, 4) === "%PDF") return "application/pdf";
+  if (buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4b) return "application/zip";
+  return undefined;
+}
+
+async function* boundedChunks(
+  source: AsyncIterable<unknown>,
+  caps: {
+    perFileCap: number;
+    aggregateCap: number;
+    aggregateUsed: number;
+    signal?: AbortSignal;
+    onHead: (buf: Buffer) => void;
+    onBytes: (n: number) => void;
+    hash: { update(buf: Buffer): void };
+  },
+): AsyncGenerator<Buffer> {
+  let bytes = 0;
+  let sawHead = false;
+  for await (const chunk of source) {
+    if (caps.signal?.aborted) {
+      throw new BrowserError("ERR_PRISM_BROWSER", "download aborted");
+    }
+    const buf = Buffer.isBuffer(chunk) ? chunk : chunk instanceof Uint8Array ? Buffer.from(chunk) : Buffer.from(String(chunk));
+    bytes += buf.byteLength;
+    if (bytes > caps.perFileCap) {
+      throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `download exceeds maxDownloadBytes ${caps.perFileCap}`);
+    }
+    if (caps.aggregateUsed + bytes > caps.aggregateCap) {
+      throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `download exceeds maxDownloadAggregateBytes ${caps.aggregateCap}`);
+    }
+    if (!sawHead) {
+      caps.onHead(buf.subarray(0, Math.min(buf.byteLength, 16)));
+      sawHead = true;
+    }
+    caps.hash.update(buf);
+    caps.onBytes(bytes);
+    yield buf;
+  }
+}
+
+export async function quarantineDownload(
+  download: PlaywrightDownload,
+  options: BrowserDownloadOptions,
+  limits: ResolvedBrowserLimits,
+  budget: DownloadBudget,
+  signal?: AbortSignal,
+): Promise<DownloadMetadata> {
+  if (!isAbsolute(options.quarantine)) {
+    throw new BrowserError("ERR_PRISM_BROWSER_INPUT", "downloads.quarantine must be absolute");
+  }
+  if (budget.count >= limits.maxDownloads) {
+    try {
+      await download.cancel?.();
+    } catch {
+      /* ignore */
+    }
+    throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `maxDownloads ${limits.maxDownloads} exceeded`);
+  }
+
+  const perFileCap = Math.min(options.maxBytes ?? limits.maxDownloadBytes, limits.maxDownloadBytes);
+  await mkdir(options.quarantine, { recursive: true, mode: 0o700 });
+
+  const downloadId = `dl_${randomBytes(8).toString("hex")}`;
+  const suggested = sanitizeDownloadName(download.suggestedFilename?.() ?? "download.bin");
+  const safeName = `${downloadId}_${suggested}`;
+  const quarantineRoot = resolve(options.quarantine);
+  const quarantinePath = resolve(join(quarantineRoot, safeName));
+  if (!quarantinePath.startsWith(`${quarantineRoot}/`) && quarantinePath !== quarantineRoot) {
+    throw new BrowserError("ERR_PRISM_BROWSER_ARTIFACT", "quarantine path escaped root");
+  }
+
+  const hash = createHash("sha256");
+  let bytes = 0;
+  let head: Buffer | undefined;
+  const url = (() => {
+    try {
+      return download.url().slice(0, 2_048);
+    } catch {
+      return "";
+    }
+  })();
+
+  try {
+    const stream = typeof download.createReadStream === "function" ? await download.createReadStream() : null;
+    if (stream) {
+      await pipeline(
+        Readable.from(
+          boundedChunks(stream as AsyncIterable<unknown>, {
+            perFileCap,
+            aggregateCap: limits.maxDownloadAggregateBytes,
+            aggregateUsed: budget.aggregateBytes,
+            signal,
+            onHead: (buf) => {
+              head = buf;
+            },
+            onBytes: (n) => {
+              bytes = n;
+            },
+            hash,
+          }),
+        ),
+        createWriteStream(quarantinePath, { mode: 0o600, flags: "wx" }),
+      );
+    } else if (typeof download.saveAs === "function") {
+      await download.saveAs(quarantinePath);
+      const handle = await open(quarantinePath, "r");
+      try {
+        const stat = await handle.stat();
+        bytes = stat.size;
+        if (bytes > perFileCap || budget.aggregateBytes + bytes > limits.maxDownloadAggregateBytes) {
+          await rm(quarantinePath, { force: true });
+          throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", "download exceeds byte budget");
+        }
+        const buf = Buffer.alloc(64 * 1024);
+        let remaining = bytes;
+        while (remaining > 0) {
+          const { bytesRead } = await handle.read(buf, 0, Math.min(buf.length, remaining), null);
+          if (bytesRead <= 0) break;
+          if (!head) head = buf.subarray(0, Math.min(bytesRead, 16));
+          hash.update(buf.subarray(0, bytesRead));
+          remaining -= bytesRead;
+        }
+      } finally {
+        await handle.close();
+      }
+    } else {
+      throw new BrowserError("ERR_PRISM_BROWSER", "Download stream API unavailable");
+    }
+  } catch (error) {
+    await rm(quarantinePath, { force: true }).catch(() => undefined);
+    try {
+      await download.cancel?.();
+    } catch {
+      /* ignore */
+    }
+    if (error instanceof BrowserError) throw error;
+    throw new BrowserError(
+      "ERR_PRISM_BROWSER_ARTIFACT",
+      `download quarantine failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const meta: DownloadMetadata = {
+    downloadId,
+    suggestedName: suggested,
+    safeName,
+    quarantinePath,
+    url,
+    bytes,
+    sha256: hash.digest("hex"),
+    mimeType: head ? sniffMime(head) : undefined,
+    released: false,
+  };
+  budget.count += 1;
+  budget.aggregateBytes += bytes;
+  budget.items.set(downloadId, { ...meta, released: false });
+  return meta;
+}
+
+export async function releaseDownload(
+  downloadId: string,
+  options: BrowserDownloadOptions,
+  budget: DownloadBudget,
+): Promise<DownloadMetadata> {
+  const item = budget.items.get(downloadId);
+  if (!item) {
+    throw new BrowserError("ERR_PRISM_BROWSER_STATE", `Unknown downloadId ${downloadId}`);
+  }
+  if (item.released) return item;
+  if (!options.approveRelease) {
+    throw new BrowserError("ERR_PRISM_BROWSER_ARTIFACT", "download release requires host approveRelease callback");
+  }
+  const ok = await options.approveRelease(item);
+  if (!ok) {
+    throw new BrowserError("ERR_PRISM_BROWSER_ARTIFACT", "host denied download release");
+  }
+  const released = { ...item, released: true };
+  budget.items.set(downloadId, released);
+  return released;
+}
+
+export async function cleanupDownloads(budget: DownloadBudget): Promise<void> {
+  for (const item of budget.items.values()) {
+    if (item.released) continue;
+    await rm(item.quarantinePath, { force: true }).catch(() => undefined);
+  }
+  budget.items.clear();
+  budget.count = 0;
+  budget.aggregateBytes = 0;
+}

package/browser/src/errors.ts

@@ -0,0 +1,31 @@
+/** Stable browser-package errors. Messages stay bounded and omit storage/secrets. */
+
+export type BrowserErrorCode =
+  | "ERR_PRISM_BROWSER"
+  | "ERR_PRISM_BROWSER_LIMIT"
+  | "ERR_PRISM_BROWSER_STATE"
+  | "ERR_PRISM_BROWSER_TARGET"
+  | "ERR_PRISM_BROWSER_CLOSED"
+  | "ERR_PRISM_BROWSER_INPUT"
+  | "ERR_PRISM_BROWSER_NETWORK"
+  | "ERR_PRISM_BROWSER_ARTIFACT"
+  | "ERR_PRISM_BROWSER_CDP_UNAVAILABLE"
+  | "ERR_PRISM_BROWSER_CDP";
+
+export class BrowserError extends Error {
+  readonly code: BrowserErrorCode;
+
+  constructor(code: BrowserErrorCode, message: string) {
+    super(truncateMessage(message));
+    this.name = "BrowserError";
+    this.code = code;
+  }
+}
+
+const MAX_ERROR_BYTES = 1_024;
+
+function truncateMessage(message: string): string {
+  const buf = Buffer.from(message, "utf8");
+  if (buf.byteLength <= MAX_ERROR_BYTES) return message;
+  return `${buf.subarray(0, MAX_ERROR_BYTES).toString("utf8")}…`;
+}

package/browser/src/evaluate.ts

@@ -0,0 +1,101 @@
+/**
+ * Bounded page-context evaluation via CDP Runtime.evaluate (0.1.4, plan 016 Task 4).
+ * Expression bytes and result bytes are capped; result is JSON-serializable by
+ * construction (returnByValue) or surfaced as a bounded exception description.
+ */
+import { cdpRuntimeEvaluate } from "./cdp.js";
+import { BrowserError } from "./errors.js";
+import type { PlaywrightCdpSession } from "./types.js";
+
+export interface EvaluateOutcome {
+  /** JSON-serializable evaluated value (bounded by maxEvaluateResultBytes). */
+  readonly value?: unknown;
+  /** Bounded exception description when evaluation threw or was unserializable. */
+  readonly exception?: string;
+  /** The serialized result was truncated to the byte cap. */
+  readonly truncated?: boolean;
+}
+
+export interface EvaluateBounds {
+  readonly maxActionInputBytes: number;
+  readonly actionTimeoutMs: number;
+  readonly maxEvaluateResultBytes: number;
+}
+
+const MAX_EXCEPTION_DESCRIPTION_BYTES = 2_048;
+
+export async function evaluateInPage(
+  session: PlaywrightCdpSession,
+  input: { expression: string; awaitPromise?: boolean; timeoutMs?: number },
+  bounds: EvaluateBounds,
+): Promise<EvaluateOutcome> {
+  if (typeof input.expression !== "string" || !input.expression) {
+    throw new BrowserError("ERR_PRISM_BROWSER_INPUT", "evaluate requires a non-empty expression");
+  }
+  if (Buffer.byteLength(input.expression, "utf8") > bounds.maxActionInputBytes) {
+    throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `expression exceeds maxActionInputBytes ${bounds.maxActionInputBytes}`);
+  }
+  const timeout = clampTimeout(input.timeoutMs, bounds.actionTimeoutMs);
+
+  const response = await cdpRuntimeEvaluate(session, {
+    expression: input.expression,
+    awaitPromise: input.awaitPromise === true,
+    returnByValue: true,
+    userGesture: true,
+    timeout,
+  });
+
+  if (response.exceptionDetails) {
+    return { exception: describeException(response.exceptionDetails) };
+  }
+  const raw = response.result?.value;
+  if (raw === undefined) return { value: undefined };
+  const { json, truncated } = boundedJson(raw, bounds.maxEvaluateResultBytes);
+  return { value: json, ...(truncated ? { truncated: true } : {}) };
+}
+
+function describeException(details: {
+  readonly text?: string;
+  readonly url?: string;
+  readonly lineNumber?: number;
+  readonly columnNumber?: number;
+  readonly exception?: { readonly description?: string };
+}): string {
+  const description =
+    details.exception?.description && details.exception.description.length > 0
+      ? details.exception.description
+      : (details.text ?? "unknown exception");
+  const bounded = truncateUtf8(description, MAX_EXCEPTION_DESCRIPTION_BYTES);
+  const where = details.url && details.lineNumber !== undefined ? ` at ${details.url}:${details.lineNumber + 1}` : "";
+  return `${bounded}${where}`;
+}
+
+/** JSON-serialize with a byte cap; truncation marks the result, never throws. */
+export function boundedJson(value: unknown, maxBytes: number): { json: unknown; truncated: boolean } {
+  let text: string;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    return { json: String(value), truncated: false };
+  }
+  if (text === undefined) return { json: undefined, truncated: false };
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) {
+    // Round-trip back to a real value; the parse is safe (stringify just succeeded).
+    return { json: JSON.parse(text) as unknown, truncated: false };
+  }
+  return { json: truncateUtf8(text, maxBytes), truncated: true };
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.byteLength <= maxBytes) return text;
+  return `${buf.subarray(0, maxBytes).toString("utf8")}…`;
+}
+
+function clampTimeout(value: number | undefined, hard: number): number {
+  if (value === undefined) return hard;
+  if (!Number.isSafeInteger(value) || value < 1 || value > hard) {
+    throw new BrowserError("ERR_PRISM_BROWSER_LIMIT", `timeoutMs must be 1..${hard}`);
+  }
+  return value;
+}

package/browser/src/index.ts

@@ -0,0 +1,129 @@
+/**
+ * `@arnilo/prism-tools/browser` — the first-party browser automation tools as a package.
+ *
+ * The default export registers the six exclusive model-facing tools from `createBrowserTools`
+ * (`browser_open`, `browser_snapshot`, `browser_act`, `browser_close`, `browser_evaluate`,
+ * `browser_observe`), each declaring its `effects` for the host approval hook. `playwright-core`
+ * is imported dynamically in `setup` and used to launch the run-owned browser; when it is missing
+ * (or the launch fails) the package registers nothing and writes a `warn` status note. The
+ * manager and the launched browser are closed in `onDispose`.
+ *
+ * Egress is fail-closed: without a `containedProxy` attestation every external request is denied,
+ * and `allowOrigins` narrows navigation to an explicit origin allowlist. Blocked schemes, loopback,
+ * private, link-local, and ULA destinations are denied inside the manager, so they hold under any
+ * approval mode.
+ *
+ * ```ts
+ * import toolsBrowser from "@arnilo/prism-tools/browser";
+ * import { createAgent } from "@arnilo/prism";
+ *
+ * const agent = await createAgent({ model, packages: [toolsBrowser({ headless: true, allowOrigins: ["https://example.com"] })] });
+ * ```
+ */
+import { fileURLToPath } from "node:url";
+import { definePackage, type PackageInstance, type ToolDefinition } from "@arnilo/prism";
+import manifest from "../../package.json" with { type: "json" };
+
+import { type ToolsBrowserConfig, toolsBrowserConfigSchema } from "./config.js";
+import { createBrowserManager } from "./manager.js";
+import type { BrowserNetworkPolicy } from "./network.js";
+import { createBrowserTools } from "./tools.js";
+import type { PlaywrightBrowser } from "./types.js";
+
+// The moved 0.12 surface keeps its names, now behind one entry point.
+export * from "./browser.js";
+export type { ToolsBrowserConfig, ToolsBrowserProxyConfig } from "./config.js";
+export { toolsBrowserConfigSchema } from "./config.js";
+
+/** The subset of `playwright-core` the package uses; kept structural so the peer stays optional. */
+interface PlaywrightChromium {
+  launch(options: { readonly headless?: boolean; readonly executablePath?: string; readonly channel?: string }): Promise<PlaywrightBrowser>;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Normalize `allowOrigins` entries to origins and deny every other origin. */
+function originPolicy(allowOrigins: readonly string[]): BrowserNetworkPolicy["validateUrl"] {
+  const allowed = new Set(
+    allowOrigins.map((origin) => {
+      try {
+        return new URL(origin).origin;
+      } catch {
+        return origin;
+      }
+    }),
+  );
+  return (url: URL): boolean => allowed.has(url.origin);
+}
+
+function networkPolicyOf(config: ToolsBrowserConfig): BrowserNetworkPolicy {
+  const policy: BrowserNetworkPolicy = {
+    ...(config.containedProxy !== undefined ? { containedProxyAttestation: config.containedProxy } : {}),
+    ...(config.allowLoopback === true ? { allowLoopback: true } : {}),
+    ...(config.allowPrivateHosts === true ? { allowPrivateHosts: true } : {}),
+  };
+  if (config.allowOrigins !== undefined && config.allowOrigins.length > 0) {
+    return { ...policy, validateUrl: originPolicy(config.allowOrigins) };
+  }
+  return policy;
+}
+
+const definition = definePackage<ToolsBrowserConfig>({
+  name: "@arnilo/prism-tools/browser",
+  version: manifest.version,
+  description: "Six exclusive browser tools over Playwright with declared effects, fail-closed egress policy, and artifact quarantine.",
+  requires: { api: 1 },
+  config: toolsBrowserConfigSchema,
+  setup: async (prism) => {
+    // Registered first: `requiresTools` hides the skill when playwright-core is missing or the launch fails.
+    prism.skills.addDir(fileURLToPath(new URL("../skills", import.meta.url)));
+    let chromium: PlaywrightChromium;
+    try {
+      ({ chromium } = (await import("playwright-core")) as unknown as { chromium: PlaywrightChromium });
+    } catch (error) {
+      prism.status.note("warn", `browser: playwright-core is not installed (${errorMessage(error)})`);
+      return;
+    }
+
+    const launchOptions: { headless: boolean; executablePath?: string; channel?: string } = {
+      headless: prism.config.headless ?? true,
+    };
+    if (prism.config.executablePath !== undefined) launchOptions.executablePath = prism.config.executablePath;
+    if (prism.config.channel !== undefined) launchOptions.channel = prism.config.channel;
+
+    let browser: PlaywrightBrowser;
+    try {
+      browser = await chromium.launch(launchOptions);
+    } catch (error) {
+      prism.status.note("warn", `browser: launch failed (${errorMessage(error)})`);
+      return;
+    }
+
+    const uploadRoots = prism.config.uploadRoots;
+    const quarantine = prism.config.quarantine;
+    const manager = createBrowserManager({
+      browser,
+      networkPolicy: networkPolicyOf(prism.config),
+      cdp: { mode: prism.config.cdp ?? "auto" },
+      ...(uploadRoots !== undefined && uploadRoots.length > 0 ? { uploads: { roots: uploadRoots } } : {}),
+      ...(quarantine !== undefined ? { downloads: { quarantine } } : {}),
+    });
+    const tools: readonly ToolDefinition[] = createBrowserTools({ manager });
+    for (const tool of tools) prism.tools.register(tool);
+
+    prism.onDispose(async () => {
+      await manager.close();
+      await browser.close?.();
+    });
+  },
+});
+
+/** The package definition. Pass config through `packageConfig` or use {@link toolsBrowser}. */
+export default definition;
+
+/** The package with config baked in, for `packages: [toolsBrowser({ headless })]`. */
+export function toolsBrowser(config: ToolsBrowserConfig = {}): PackageInstance {
+  return definition(config);
+}