@aitne/daemon 0.1.8 → 0.1.9

package/dist/services/browser-history/automation/browser-task-tools/schemas.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Zod schemas for the 11 `mcp__aitne-browser__*` tools —
+ * BROWSER_TASK_REDESIGN_PLAN.md §5.
+ *
+ * Pure. No I/O. Each tool's runtime body imports its own schema from
+ * here so the tests can assert validation behaviour without booting a
+ * Playwright context. The SDK consumes the Zod schema directly via
+ * `tool(name, description, schemaObject, handler)` per the
+ * `@anthropic-ai/claude-agent-sdk` shape — the schema OBJECT (not the
+ * Zod wrapper) is what we pass.
+ *
+ * §14.9 — `wait_for` MUST NOT carry a JS predicate. The schema below
+ * declares `selector`, `urlPattern`, `timeoutMs` only — passing `fn`
+ * / `predicate` triggers a Zod "unrecognised key" because we use
+ * `.strict()`. A future regression that drops `.strict()` is caught
+ * by the peer test.
+ *
+ * 100% coverage gate.
+ */
+import { z } from "zod";
+/** Selector union shared by `click` / `type`. The runner translates a
+ *  `selector` to `page.locator(value)` and `coords` to
+ *  `page.mouse.click(x, y)`. Coords are last-resort for canvas / non-
+ *  DOM widgets. */
+export declare const selectorOrCoordsSchema: z.ZodUnion<readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"selector">;
+    value: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"coords">;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+}, z.core.$strict>]>;
+export type SelectorOrCoords = z.infer<typeof selectorOrCoordsSchema>;
+export declare const navigateArgsSchema: {
+    url: z.ZodString;
+};
+export declare const navigateArgsZod: z.ZodObject<{
+    url: z.ZodString;
+}, z.core.$strict>;
+export type NavigateArgs = z.infer<typeof navigateArgsZod>;
+export declare const screenshotArgsSchema: {
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const screenshotArgsZod: z.ZodObject<{
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ScreenshotArgs = z.infer<typeof screenshotArgsZod>;
+export declare const domSnapshotArgsSchema: {
+    maxNodes: z.ZodOptional<z.ZodNumber>;
+};
+export declare const domSnapshotArgsZod: z.ZodObject<{
+    maxNodes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type DomSnapshotArgs = z.infer<typeof domSnapshotArgsZod>;
+export declare const clickArgsSchema: {
+    target: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"selector">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"coords">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strict>]>;
+};
+export declare const clickArgsZod: z.ZodObject<{
+    target: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"selector">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"coords">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strict>]>;
+}, z.core.$strict>;
+export type ClickArgs = z.infer<typeof clickArgsZod>;
+export declare const typeArgsSchema: {
+    target: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"selector">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"coords">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strict>]>;
+    text: z.ZodString;
+    replaceExisting: z.ZodOptional<z.ZodBoolean>;
+};
+export declare const typeArgsZod: z.ZodObject<{
+    target: z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodLiteral<"selector">;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"coords">;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strict>]>;
+    text: z.ZodString;
+    replaceExisting: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type TypeArgs = z.infer<typeof typeArgsZod>;
+/** Allowlisted set of keys — narrow on purpose. The runner forwards
+ *  the literal string to `page.keyboard.press(...)`. */
+export declare const PRESS_KEY_ALLOWED: readonly ["Enter", "Tab", "Escape", "Backspace", "Delete", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Home", "End", "PageUp", "PageDown"];
+export type PressKeyName = (typeof PRESS_KEY_ALLOWED)[number];
+export declare const pressKeyArgsSchema: {
+    key: z.ZodEnum<{
+        Enter: "Enter";
+        Tab: "Tab";
+        Escape: "Escape";
+        Backspace: "Backspace";
+        Delete: "Delete";
+        ArrowUp: "ArrowUp";
+        ArrowDown: "ArrowDown";
+        ArrowLeft: "ArrowLeft";
+        ArrowRight: "ArrowRight";
+        Home: "Home";
+        End: "End";
+        PageUp: "PageUp";
+        PageDown: "PageDown";
+    }>;
+};
+export declare const pressKeyArgsZod: z.ZodObject<{
+    key: z.ZodEnum<{
+        Enter: "Enter";
+        Tab: "Tab";
+        Escape: "Escape";
+        Backspace: "Backspace";
+        Delete: "Delete";
+        ArrowUp: "ArrowUp";
+        ArrowDown: "ArrowDown";
+        ArrowLeft: "ArrowLeft";
+        ArrowRight: "ArrowRight";
+        Home: "Home";
+        End: "End";
+        PageUp: "PageUp";
+        PageDown: "PageDown";
+    }>;
+}, z.core.$strict>;
+export type PressKeyArgs = z.infer<typeof pressKeyArgsZod>;
+export declare const waitForArgsSchema: {
+    selector: z.ZodOptional<z.ZodString>;
+    urlPattern: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+};
+export declare const waitForArgsZod: z.ZodObject<{
+    selector: z.ZodOptional<z.ZodString>;
+    urlPattern: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type WaitForArgs = z.infer<typeof waitForArgsZod>;
+export declare const extractArgsSchema: {
+    selector: z.ZodOptional<z.ZodString>;
+    queryHint: z.ZodString;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+};
+export declare const extractArgsZod: z.ZodObject<{
+    selector: z.ZodOptional<z.ZodString>;
+    queryHint: z.ZodString;
+    maxChars: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ExtractArgs = z.infer<typeof extractArgsZod>;
+export declare const askUserArgsSchema: {
+    question: z.ZodString;
+    contextSummary: z.ZodString;
+    screenshotKey: z.ZodOptional<z.ZodString>;
+};
+export declare const askUserArgsZod: z.ZodObject<{
+    question: z.ZodString;
+    contextSummary: z.ZodString;
+    screenshotKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AskUserArgs = z.infer<typeof askUserArgsZod>;
+export declare const yieldForClarificationArgsSchema: {
+    clarificationId: z.ZodString;
+};
+export declare const yieldForClarificationArgsZod: z.ZodObject<{
+    clarificationId: z.ZodString;
+}, z.core.$strict>;
+export type YieldForClarificationArgs = z.infer<typeof yieldForClarificationArgsZod>;
+export declare const finishArgsSchema: {
+    report: z.ZodString;
+    screenshotKeys: z.ZodArray<z.ZodString>;
+};
+export declare const finishArgsZod: z.ZodObject<{
+    report: z.ZodString;
+    screenshotKeys: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type FinishArgs = z.infer<typeof finishArgsZod>;
+/** Tool-name catalogue. Exported so the runner's `allowedToolsOverride`
+ *  list and the agent profile cross-reference cannot drift. */
+export declare const BROWSER_TASK_TOOL_NAMES: readonly ["navigate", "screenshot", "dom_snapshot", "click", "type", "press_key", "wait_for", "extract", "ask_user", "yield_for_clarification", "finish"];
+export type BrowserTaskToolName = (typeof BROWSER_TASK_TOOL_NAMES)[number];
+/** MCP server name (matches §5: `aitne-browser`). Tools surface as
+ *  `mcp__aitne-browser__<name>` per the SDK convention. */
+export declare const BROWSER_TASK_MCP_SERVER_NAME = "aitne-browser";
+/** Fully-qualified tool name builder. Mirrors
+ *  `sdk-observations-server.ts:OBSERVATIONS_MCP_TOOL_NAME`. */
+export declare function browserTaskToolFqn(name: BrowserTaskToolName): string;
+/** The full set of FQ tool names — `allowedToolsOverride` for the
+ *  sub-agent's SDK session pins exactly this list. */
+export declare const BROWSER_TASK_TOOL_FQNS: readonly string[];

package/dist/services/browser-history/automation/browser-task-tools/schemas.js

@@ -0,0 +1,248 @@
+/**
+ * Zod schemas for the 11 `mcp__aitne-browser__*` tools —
+ * BROWSER_TASK_REDESIGN_PLAN.md §5.
+ *
+ * Pure. No I/O. Each tool's runtime body imports its own schema from
+ * here so the tests can assert validation behaviour without booting a
+ * Playwright context. The SDK consumes the Zod schema directly via
+ * `tool(name, description, schemaObject, handler)` per the
+ * `@anthropic-ai/claude-agent-sdk` shape — the schema OBJECT (not the
+ * Zod wrapper) is what we pass.
+ *
+ * §14.9 — `wait_for` MUST NOT carry a JS predicate. The schema below
+ * declares `selector`, `urlPattern`, `timeoutMs` only — passing `fn`
+ * / `predicate` triggers a Zod "unrecognised key" because we use
+ * `.strict()`. A future regression that drops `.strict()` is caught
+ * by the peer test.
+ *
+ * 100% coverage gate.
+ */
+import { z } from "zod";
+import { EXTRACT_PER_CALL_DEFAULT_CHARS, EXTRACT_PER_CALL_MAX_CHARS, } from "./extract-cap.js";
+/** Selector union shared by `click` / `type`. The runner translates a
+ *  `selector` to `page.locator(value)` and `coords` to
+ *  `page.mouse.click(x, y)`. Coords are last-resort for canvas / non-
+ *  DOM widgets. */
+export const selectorOrCoordsSchema = z
+    .union([
+    z
+        .object({
+        kind: z.literal("selector"),
+        value: z.string().min(1).max(1024),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("coords"),
+        x: z.number().int().min(0).max(10_000),
+        y: z.number().int().min(0).max(10_000),
+    })
+        .strict(),
+])
+    .describe("Either a CSS / aria selector ({kind:'selector', value:'#submit-btn'}) "
+    + "or absolute viewport coordinates ({kind:'coords', x:120, y:340}). "
+    + "Selectors are PREFERRED — coords are last-resort for canvas / non-DOM widgets.");
+// ── 1. navigate ──────────────────────────────────────────────────────────
+export const navigateArgsSchema = {
+    url: z
+        .string()
+        .url()
+        .max(4096)
+        .describe("Absolute URL to navigate to. Rejected when outside the task's effective "
+        + "allowlist (returns {ok:false, blockedByAllowlist:true}) or on a "
+        + "payment-path pattern (rejected unconditionally)."),
+};
+export const navigateArgsZod = z.object(navigateArgsSchema).strict();
+// ── 2. screenshot ────────────────────────────────────────────────────────
+export const screenshotArgsSchema = {
+    fullPage: z
+        .boolean()
+        .optional()
+        .describe("When true, capture the full scrollable height. Default false — viewport only."),
+};
+export const screenshotArgsZod = z.object(screenshotArgsSchema).strict();
+// ── 3. dom_snapshot ──────────────────────────────────────────────────────
+export const domSnapshotArgsSchema = {
+    maxNodes: z
+        .number()
+        .int()
+        .min(1)
+        .max(5000)
+        .optional()
+        .describe("Cap on aria-tree node count. Default 1500 — large enough for most pages, "
+        + "small enough that the truncated serialisation stays under 32 KB."),
+};
+export const domSnapshotArgsZod = z.object(domSnapshotArgsSchema).strict();
+// ── 4. click ────────────────────────────────────────────────────────────
+export const clickArgsSchema = {
+    target: selectorOrCoordsSchema,
+};
+export const clickArgsZod = z.object(clickArgsSchema).strict();
+// ── 5. type ──────────────────────────────────────────────────────────────
+export const typeArgsSchema = {
+    target: selectorOrCoordsSchema,
+    text: z
+        .string()
+        .max(8192)
+        .describe("Text to type into the target. Capped at 8 KB — long-form composition "
+        + "should be split into multiple calls."),
+    replaceExisting: z
+        .boolean()
+        .optional()
+        .describe("When true, clear the field before typing (page.fill). Default false — "
+        + "appends keystrokes (page.type)."),
+};
+export const typeArgsZod = z.object(typeArgsSchema).strict();
+// ── 6. press_key ─────────────────────────────────────────────────────────
+/** Allowlisted set of keys — narrow on purpose. The runner forwards
+ *  the literal string to `page.keyboard.press(...)`. */
+export const PRESS_KEY_ALLOWED = [
+    "Enter",
+    "Tab",
+    "Escape",
+    "Backspace",
+    "Delete",
+    "ArrowUp",
+    "ArrowDown",
+    "ArrowLeft",
+    "ArrowRight",
+    "Home",
+    "End",
+    "PageUp",
+    "PageDown",
+];
+export const pressKeyArgsSchema = {
+    key: z
+        .enum(PRESS_KEY_ALLOWED)
+        .describe("Key name. Closed set — arbitrary key codes are not allowed; if the "
+        + "site requires a key outside this set, use a different interaction."),
+};
+export const pressKeyArgsZod = z.object(pressKeyArgsSchema).strict();
+// ── 7. wait_for ──────────────────────────────────────────────────────────
+// §14.9 — no JS predicate. The shape below declares selector /
+// urlPattern / timeoutMs only. `.strict()` rejects `fn` / `predicate`
+// / `evaluate` keys with a clear "unrecognised key" error.
+export const waitForArgsSchema = {
+    selector: z
+        .string()
+        .min(1)
+        .max(1024)
+        .optional()
+        .describe("CSS / aria selector to wait for (visible)."),
+    urlPattern: z
+        .string()
+        .min(1)
+        .max(1024)
+        .optional()
+        .describe("Glob or regex string to wait for the page URL to match. "
+        + "Forwarded to Playwright page.waitForURL."),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(100)
+        .max(30_000)
+        .optional()
+        .describe("Wall-clock timeout (default 10 000). Returns {matched:false} on timeout."),
+};
+export const waitForArgsZod = z
+    .object(waitForArgsSchema)
+    .strict()
+    .refine((v) => v.selector !== undefined || v.urlPattern !== undefined || v.timeoutMs !== undefined, {
+    message: "wait_for requires at least one of: selector, urlPattern, timeoutMs",
+});
+// ── 8. extract ───────────────────────────────────────────────────────────
+export const extractArgsSchema = {
+    selector: z
+        .string()
+        .min(1)
+        .max(1024)
+        .optional()
+        .describe("CSS / aria selector scoping the extract. Omit for full-page innerText."),
+    queryHint: z
+        .string()
+        .min(1)
+        .max(512)
+        .describe("Short natural-language description of WHAT you want to read. Surfaced in "
+        + "the audit row so a triager can tell `extract` calls apart."),
+    maxChars: z
+        .number()
+        .int()
+        .min(1)
+        .max(EXTRACT_PER_CALL_MAX_CHARS)
+        .optional()
+        .describe(`Per-call cap. Default ${EXTRACT_PER_CALL_DEFAULT_CHARS}, max ${EXTRACT_PER_CALL_MAX_CHARS}.`),
+};
+export const extractArgsZod = z.object(extractArgsSchema).strict();
+// ── 9. ask_user ──────────────────────────────────────────────────────────
+export const askUserArgsSchema = {
+    question: z
+        .string()
+        .min(1)
+        .max(512)
+        .describe("One-sentence question the user should answer."),
+    contextSummary: z
+        .string()
+        .min(1)
+        .max(2048)
+        .describe("Short statement of where you are and what options you can pick from — "
+        + "displayed under the question in DM."),
+    screenshotKey: z
+        .string()
+        .min(1)
+        .max(256)
+        .optional()
+        .describe("Relative filename returned by a prior `screenshot` call. The runner "
+        + "attaches the image to the DM."),
+};
+export const askUserArgsZod = z.object(askUserArgsSchema).strict();
+// ── 10. yield_for_clarification ──────────────────────────────────────────
+export const yieldForClarificationArgsSchema = {
+    clarificationId: z
+        .string()
+        .uuid()
+        .describe("Identifier returned by the prior `ask_user` call."),
+};
+export const yieldForClarificationArgsZod = z
+    .object(yieldForClarificationArgsSchema)
+    .strict();
+// ── 11. finish ───────────────────────────────────────────────────────────
+export const finishArgsSchema = {
+    report: z
+        .string()
+        .min(1)
+        .max(8192)
+        .describe("Markdown summary the user reads in DM. State what you did, what the "
+        + "outcome was, and link any captured screenshots by key."),
+    screenshotKeys: z
+        .array(z.string().min(1).max(256))
+        .max(50)
+        .describe("Ordered list of screenshot filenames the user should review. Empty "
+        + "list is acceptable when the report stands alone."),
+};
+export const finishArgsZod = z.object(finishArgsSchema).strict();
+/** Tool-name catalogue. Exported so the runner's `allowedToolsOverride`
+ *  list and the agent profile cross-reference cannot drift. */
+export const BROWSER_TASK_TOOL_NAMES = [
+    "navigate",
+    "screenshot",
+    "dom_snapshot",
+    "click",
+    "type",
+    "press_key",
+    "wait_for",
+    "extract",
+    "ask_user",
+    "yield_for_clarification",
+    "finish",
+];
+/** MCP server name (matches §5: `aitne-browser`). Tools surface as
+ *  `mcp__aitne-browser__<name>` per the SDK convention. */
+export const BROWSER_TASK_MCP_SERVER_NAME = "aitne-browser";
+/** Fully-qualified tool name builder. Mirrors
+ *  `sdk-observations-server.ts:OBSERVATIONS_MCP_TOOL_NAME`. */
+export function browserTaskToolFqn(name) {
+    return `mcp__${BROWSER_TASK_MCP_SERVER_NAME}__${name}`;
+}
+/** The full set of FQ tool names — `allowedToolsOverride` for the
+ *  sub-agent's SDK session pins exactly this list. */
+export const BROWSER_TASK_TOOL_FQNS = BROWSER_TASK_TOOL_NAMES.map((n) => browserTaskToolFqn(n));

package/dist/services/browser-history/automation/browser-task-tools/screenshot-output.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Pure helpers for the `screenshot` tool —
+ * BROWSER_TASK_REDESIGN_PLAN.md §5 / §14.7.
+ *
+ * Two concerns:
+ *
+ *   1. Output envelope — PNG bytes must land at ≤ 1 MB after a
+ *      JPEG re-encode fallback. The pure layer decides whether the
+ *      original PNG fits (`shouldKeepPng`) and, if not, what the
+ *      fallback JPEG quality should be.
+ *   2. §14.7 hostname denylist check — when a screenshot was captured
+ *      against a host that lives in `HOSTNAME_DENYLIST`, the runner
+ *      MUST drop the file synchronously and emit a `pa_alert` because
+ *      the CDP layer should already have blocked the navigation.
+ *      `decideHostnameRetention` is the pure decision the runner reads
+ *      before persisting the bytes.
+ *
+ * Pure — no FS, no DB, no clock, no Playwright. The I/O wrapper in
+ * the tool body composes these helpers with the real screenshot
+ * call.
+ *
+ * 100% coverage gate per §14.12 ("Screenshot auto-deletion").
+ */
+/** §5 — PNG cap. ≤ 1 MB returned to the agent (multimodal cost
+ *  bound). Larger captures fall back to JPEG via `chooseFallbackQuality`. */
+export declare const SCREENSHOT_PNG_CAP_BYTES: number;
+/** Smallest JPEG quality we'll try. Below this the output is too
+ *  lossy to use for confirm screenshots; the runner returns a
+ *  truncated image with a clear `truncated:true` flag. */
+export declare const SCREENSHOT_JPEG_MIN_QUALITY = 40;
+/** Default JPEG quality if the PNG was over budget. */
+export declare const SCREENSHOT_JPEG_DEFAULT_QUALITY = 75;
+export type ScreenshotSizeDecision = {
+    kind: "keep_png";
+} | {
+    kind: "fallback_jpeg";
+    quality: number;
+} | {
+    kind: "truncate";
+    reason: "still_too_large";
+};
+/**
+ * Decide what to do with a fresh capture's byte buffer. The runner
+ * always tries PNG first; this helper picks the next step when the
+ * PNG is over the 1 MB cap.
+ *
+ * `pngBytes` is the size of the original PNG in bytes. The function
+ * does NOT touch the buffer itself — it returns the decision and
+ * the runner does the actual re-encode.
+ */
+export declare function decideScreenshotSize(pngBytes: number): ScreenshotSizeDecision;
+/** Second-pass decision: given JPEG-encoded bytes from the fallback,
+ *  decide whether to ship them or step the quality down once more. */
+export declare function decideJpegRetry(jpegBytes: number, previousQuality: number): ScreenshotSizeDecision;
+export type HostnameRetentionDecision = {
+    kind: "retain";
+} | {
+    kind: "drop_and_alert";
+    deniedHostname: string;
+};
+/**
+ * §14.7 — auto-delete screenshots whose hostname is on the *user-managed*
+ * hostname denylist (the same `runtime-settings.browserTaskHostnameDenylist`
+ * the CDP layer consults). A match here means the CDP layer should
+ * already have blocked the navigation — the screenshot reaching the
+ * trace store is a defence-in-depth gap; the runner deletes the file
+ * synchronously, writes an
+ * `agent_actions(action_type='browser_task_screenshot_dropped')` row,
+ * and queues a `pa_alert`. With an empty user list (default), this
+ * helper always retains.
+ *
+ * Tolerant of malformed URLs — non-string / unparseable values
+ * retain (the upstream layers are responsible for shape validation;
+ * this helper's job is the hostname check).
+ */
+export declare function decideHostnameRetention(pageUrl: string, hostnameDenylist?: ReadonlyArray<RegExp>): HostnameRetentionDecision;

package/dist/services/browser-history/automation/browser-task-tools/screenshot-output.js

@@ -0,0 +1,101 @@
+/**
+ * Pure helpers for the `screenshot` tool —
+ * BROWSER_TASK_REDESIGN_PLAN.md §5 / §14.7.
+ *
+ * Two concerns:
+ *
+ *   1. Output envelope — PNG bytes must land at ≤ 1 MB after a
+ *      JPEG re-encode fallback. The pure layer decides whether the
+ *      original PNG fits (`shouldKeepPng`) and, if not, what the
+ *      fallback JPEG quality should be.
+ *   2. §14.7 hostname denylist check — when a screenshot was captured
+ *      against a host that lives in `HOSTNAME_DENYLIST`, the runner
+ *      MUST drop the file synchronously and emit a `pa_alert` because
+ *      the CDP layer should already have blocked the navigation.
+ *      `decideHostnameRetention` is the pure decision the runner reads
+ *      before persisting the bytes.
+ *
+ * Pure — no FS, no DB, no clock, no Playwright. The I/O wrapper in
+ * the tool body composes these helpers with the real screenshot
+ * call.
+ *
+ * 100% coverage gate per §14.12 ("Screenshot auto-deletion").
+ */
+import { matchesHostnameDenylist } from "../egress-denylist.js";
+/** §5 — PNG cap. ≤ 1 MB returned to the agent (multimodal cost
+ *  bound). Larger captures fall back to JPEG via `chooseFallbackQuality`. */
+export const SCREENSHOT_PNG_CAP_BYTES = 1 * 1024 * 1024;
+/** Smallest JPEG quality we'll try. Below this the output is too
+ *  lossy to use for confirm screenshots; the runner returns a
+ *  truncated image with a clear `truncated:true` flag. */
+export const SCREENSHOT_JPEG_MIN_QUALITY = 40;
+/** Default JPEG quality if the PNG was over budget. */
+export const SCREENSHOT_JPEG_DEFAULT_QUALITY = 75;
+/**
+ * Decide what to do with a fresh capture's byte buffer. The runner
+ * always tries PNG first; this helper picks the next step when the
+ * PNG is over the 1 MB cap.
+ *
+ * `pngBytes` is the size of the original PNG in bytes. The function
+ * does NOT touch the buffer itself — it returns the decision and
+ * the runner does the actual re-encode.
+ */
+export function decideScreenshotSize(pngBytes) {
+    if (!Number.isFinite(pngBytes) || pngBytes < 0) {
+        return { kind: "truncate", reason: "still_too_large" };
+    }
+    if (pngBytes <= SCREENSHOT_PNG_CAP_BYTES) {
+        return { kind: "keep_png" };
+    }
+    // Sliding quality — for very large screenshots a lower default
+    // pays off; pages under 4 MB usually fit at quality 75, larger
+    // pages drop to 60.
+    const quality = pngBytes > 4 * 1024 * 1024 ? 60 : SCREENSHOT_JPEG_DEFAULT_QUALITY;
+    return { kind: "fallback_jpeg", quality };
+}
+/** Second-pass decision: given JPEG-encoded bytes from the fallback,
+ *  decide whether to ship them or step the quality down once more. */
+export function decideJpegRetry(jpegBytes, previousQuality) {
+    if (!Number.isFinite(jpegBytes) || jpegBytes < 0) {
+        return { kind: "truncate", reason: "still_too_large" };
+    }
+    if (jpegBytes <= SCREENSHOT_PNG_CAP_BYTES) {
+        return { kind: "fallback_jpeg", quality: previousQuality };
+    }
+    const next = previousQuality - 15;
+    if (next < SCREENSHOT_JPEG_MIN_QUALITY) {
+        return { kind: "truncate", reason: "still_too_large" };
+    }
+    return { kind: "fallback_jpeg", quality: next };
+}
+/**
+ * §14.7 — auto-delete screenshots whose hostname is on the *user-managed*
+ * hostname denylist (the same `runtime-settings.browserTaskHostnameDenylist`
+ * the CDP layer consults). A match here means the CDP layer should
+ * already have blocked the navigation — the screenshot reaching the
+ * trace store is a defence-in-depth gap; the runner deletes the file
+ * synchronously, writes an
+ * `agent_actions(action_type='browser_task_screenshot_dropped')` row,
+ * and queues a `pa_alert`. With an empty user list (default), this
+ * helper always retains.
+ *
+ * Tolerant of malformed URLs — non-string / unparseable values
+ * retain (the upstream layers are responsible for shape validation;
+ * this helper's job is the hostname check).
+ */
+export function decideHostnameRetention(pageUrl, hostnameDenylist) {
+    if (typeof pageUrl !== "string" || pageUrl.length === 0) {
+        return { kind: "retain" };
+    }
+    let parsed;
+    try {
+        parsed = new URL(pageUrl);
+    }
+    catch {
+        return { kind: "retain" };
+    }
+    if (matchesHostnameDenylist(parsed.hostname, hostnameDenylist)) {
+        return { kind: "drop_and_alert", deniedHostname: parsed.hostname };
+    }
+    return { kind: "retain" };
+}