@tickernelz/paperclip-pro-shared 2026.1025.4 → 2026.1025.6

package/dist/local-browser.js

@@ -1,50 +1,70 @@
 import { z } from "zod";
-export const LOCAL_BROWSER_PROTOCOL_VERSION = 1;
+import { LOCAL_BROWSER_ACTIONS, LOCAL_BROWSER_API_PATH_PATTERN, LOCAL_BROWSER_CLIENTS, LOCAL_BROWSER_CONTENT_SCRIPT_STATES, LOCAL_BROWSER_COOKIE_SAME_SITE, LOCAL_BROWSER_CURSOR_PATTERN, LOCAL_BROWSER_ERROR_CODES, LOCAL_BROWSER_GUARD_DEFAULTS, LOCAL_BROWSER_INTERNAL_TOOL_NAMES, LOCAL_BROWSER_KEY_ACTIONS, LOCAL_BROWSER_LIMIT_KEYS, LOCAL_BROWSER_LIMITS, LOCAL_BROWSER_MOUSE_ACTIONS, LOCAL_BROWSER_NAVIGATION_TYPES, LOCAL_BROWSER_NETWORK_BUFFER_RANGE, LOCAL_BROWSER_ORIGIN_EXEMPT_TOOL_NAMES, LOCAL_BROWSER_PERMISSION_IDS, LOCAL_BROWSER_PERMISSIONS, LOCAL_BROWSER_SITE_ACCESS, LOCAL_BROWSER_TIERS, LOCAL_BROWSER_TOOL_CAPABILITIES, LOCAL_BROWSER_TOOL_TIERS, LOCAL_BROWSER_UI_OPS, LOCAL_BROWSER_VIEWER_STATES, } from "./local-browser-contract.js";
+export * from "./local-browser-contract.js";
 export const LOCAL_BROWSER_CONNECTOR_KEY = "local-browser";
 export const LOCAL_BROWSER_SKILL_NAME = "local-browser";
 export const LOCAL_BROWSER_PAIRING_TTL_MS = 10 * 60 * 1000;
-export const LOCAL_BROWSER_CALL_TIMEOUT_MS = 30_000;
-export const LOCAL_BROWSER_SNAPSHOT_DEFAULT_NODES = 120;
-export const LOCAL_BROWSER_SNAPSHOT_MAX_NODES = 400;
-export const LOCAL_BROWSER_TEXT_DEFAULT_CHARS = 8_000;
-export const LOCAL_BROWSER_TEXT_MAX_CHARS = 40_000;
-export const LOCAL_BROWSER_SCREENSHOT_MAX_BYTES = 2 * 1024 * 1024;
-export const LOCAL_BROWSER_VIEWER_FRAME_INTERVAL_MS = 1_000;
 /** Viewer frame and input coordinates are CSS pixels of the page viewport, never device pixels. */
 export const LOCAL_BROWSER_VIEWER_COORDINATE_SPACE = "css-pixels";
-export const LOCAL_BROWSER_TIERS = ["refine", "full"];
+export const LOCAL_BROWSER_COOKIE_CAPABILITY = "cookies.v2";
+export const LOCAL_BROWSER_UPDATE_HINT = "Update the Paperclip Local Browser extension";
 export const localBrowserTierSchema = z.enum(LOCAL_BROWSER_TIERS);
-export const LOCAL_BROWSER_CLIENTS = ["chromium", "firefox"];
 export const localBrowserClientSchema = z.enum(LOCAL_BROWSER_CLIENTS);
-export const LOCAL_BROWSER_ERROR_CODES = [
-    "local_browser_not_paired",
-    "local_browser_extension_unavailable",
-    "local_browser_origin_denied",
-    "local_browser_tier_denied",
-    "local_browser_tab_missing",
-    "local_browser_ref_stale",
-    "local_browser_element_missing",
-    "local_browser_timeout",
-    "local_browser_navigation_blocked",
-    "local_browser_protocol_error",
-    "local_browser_result_too_large",
-    "local_browser_unsupported",
-];
+const permissionIdSchema = z.string().min(1).max(200);
 export const localBrowserToolErrorSchema = z
     .object({
     code: z.enum(LOCAL_BROWSER_ERROR_CODES),
     message: z.string().min(1),
     hint: z.string().min(1).optional(),
     retryable: z.boolean().optional(),
+    permissions: z.array(permissionIdSchema).max(64).optional(),
 })
     .strict();
-export const LOCAL_BROWSER_CURSOR_PATTERN = /^\d+$/;
 export const localBrowserCursorSchema = z
     .string()
     .regex(LOCAL_BROWSER_CURSOR_PATTERN, "Cursors are the decimal node offset returned by the previous snapshot");
 export const localBrowserRefSchema = z
     .string()
     .regex(/^e\d+$/, "Element refs look like e12; take a fresh snapshot when a ref is rejected");
+export const localBrowserAccessSchema = z.object({
+    siteAccess: z.enum(LOCAL_BROWSER_SITE_ACCESS),
+    granted: z.array(permissionIdSchema).max(200),
+    missing: z.array(permissionIdSchema).max(200),
+    pending: z
+        .array(z.object({
+        permission: permissionIdSchema,
+        reason: z.string().max(300),
+        tool: z.string().min(1).max(80).optional(),
+        at: z.number(),
+    }))
+        .max(50),
+});
+export const localBrowserGuardsSchema = z.object({
+    protectPaperclipTab: z.boolean().default(LOCAL_BROWSER_GUARD_DEFAULTS.protectPaperclipTab),
+    protectFocusedTab: z.boolean().default(LOCAL_BROWSER_GUARD_DEFAULTS.protectFocusedTab),
+    networkBufferSize: z
+        .number()
+        .int()
+        .min(LOCAL_BROWSER_NETWORK_BUFFER_RANGE.min)
+        .max(LOCAL_BROWSER_NETWORK_BUFFER_RANGE.max)
+        .default(LOCAL_BROWSER_GUARD_DEFAULTS.networkBufferSize),
+});
+export const localBrowserDocumentStateSchema = z.object({
+    documentId: z.string(),
+    url: z.string(),
+    readyState: z.string(),
+    visibilityState: z.string(),
+    navigationType: z.enum(LOCAL_BROWSER_NAVIGATION_TYPES),
+    restoredFromBfcache: z.boolean(),
+    wasDiscarded: z.boolean(),
+    prerendering: z.boolean(),
+    loadedAt: z.number(),
+    ageMs: z.number(),
+    requestsSinceLoad: z.number(),
+    xhrSinceLoad: z.number(),
+    stale: z.boolean(),
+    staleReasons: z.array(z.string()),
+});
 export const localBrowserTabSchema = z
     .object({
     tabId: z.number().int().nonnegative(),
@@ -53,6 +73,13 @@ export const localBrowserTabSchema = z
     url: z.string(),
     active: z.boolean(),
     status: z.string().optional(),
+    cookieStoreId: z.string().optional(),
+    containerName: z.string().optional(),
+    incognito: z.boolean().optional(),
+    discarded: z.boolean().optional(),
+    frozen: z.boolean().optional(),
+    pinned: z.boolean().optional(),
+    audible: z.boolean().optional(),
 })
     .strict();
 export const localBrowserSessionSchema = z
@@ -69,19 +96,55 @@ export const localBrowserSessionSchema = z
     lastSeenAt: z.string(),
     tabs: z.array(localBrowserTabSchema),
     controlledByViewer: z.boolean(),
+    capabilities: z.array(z.string()).default([]),
+    access: localBrowserAccessSchema.optional(),
+    guards: localBrowserGuardsSchema.optional(),
 })
     .strict();
+function limitField(key) {
+    const range = LOCAL_BROWSER_LIMITS[key];
+    return z.number().int().min(range.min).max(range.ceiling).default(range.default);
+}
+export const localBrowserLimitsSchema = z
+    .object({
+    resultMaxChars: limitField("resultMaxChars"),
+    snapshotMaxNodes: limitField("snapshotMaxNodes"),
+    readMaxChars: limitField("readMaxChars"),
+    screenshotMaxBytes: limitField("screenshotMaxBytes"),
+    transferMaxBytes: limitField("transferMaxBytes"),
+    callMaxMs: limitField("callMaxMs"),
+    networkMaxEntries: limitField("networkMaxEntries"),
+})
+    .strict();
+export const LOCAL_BROWSER_LIMIT_DEFAULTS = Object.fromEntries(LOCAL_BROWSER_LIMIT_KEYS.map((key) => [key, LOCAL_BROWSER_LIMITS[key].default]));
+export const localBrowserLimitedSchema = z.array(z.object({ field: z.string(), requested: z.number(), applied: z.number() }).strict());
+const ceiling = (key) => LOCAL_BROWSER_LIMITS[key].ceiling;
+const timeoutSchema = z.number().int().min(100).max(ceiling("callMaxMs"));
 export const localBrowserTargetSchema = z
     .object({
-    sessionId: z.string().uuid().optional(),
-    tabId: z.number().int().nonnegative().optional(),
+    sessionId: z.string().uuid().optional().describe("Paired browser session id; omit when one browser is paired"),
+    tabId: z.number().int().nonnegative().optional().describe("Tab id from local_browser_sessions; omit for the active tab"),
 })
     .strict();
+const sessionOnlySchema = z
+    .object({
+    sessionId: z.string().uuid().optional().describe("Paired browser session id; omit when one browser is paired"),
+})
+    .strict();
+export const localBrowserSessionsInputSchema = localBrowserTargetSchema;
 export const localBrowserOpenInputSchema = localBrowserTargetSchema
     .extend({
-    url: z.string().url().optional(),
-    newTab: z.boolean().optional(),
-    active: z.boolean().optional(),
+    url: z.string().url().optional().describe("Absolute http(s) URL"),
+    newTab: z.boolean().optional().describe("Accepted for compatibility; a url reuses your own tab when you have one"),
+    active: z.boolean().optional().describe("Focus the tab when opening it"),
+    cookieStoreId: z
+        .string()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Open the tab in this cookie jar, for example a Firefox container id from local_browser_context"),
+    incognito: z.boolean().optional().describe("Open in a private window; the extension must be allowed in private windows"),
+    newWindow: z.boolean().optional().describe("Open in a new window instead of a tab"),
 })
     .strict();
 export const localBrowserNavigateInputSchema = localBrowserTargetSchema
@@ -91,44 +154,41 @@ export const localBrowserNavigateInputSchema = localBrowserTargetSchema
     forward: z.boolean().optional(),
     reload: z.boolean().optional(),
     waitUntil: z.enum(["load", "domcontentloaded", "networkidle"]).optional(),
-    timeoutMs: z.number().int().min(100).max(120_000).optional(),
+    timeoutMs: timeoutSchema.optional().describe("Default 15000; capped by the company call limit"),
 })
     .strict();
 export const localBrowserSnapshotInputSchema = localBrowserTargetSchema
     .extend({
-    selector: z.string().min(1).optional(),
-    maxNodes: z.number().int().min(10).max(LOCAL_BROWSER_SNAPSHOT_MAX_NODES).optional(),
-    includeText: z.boolean().optional(),
+    selector: z.string().min(1).optional().describe("Scope the snapshot to a subtree"),
+    maxNodes: z
+        .number()
+        .int()
+        .min(10)
+        .max(ceiling("snapshotMaxNodes"))
+        .optional()
+        .describe("Default 120; capped by the company snapshot limit"),
+    includeText: z.boolean().optional().describe("Include short text content per node"),
     includeHidden: z.boolean().optional(),
-    cursor: z.string().min(1).optional(),
+    cursor: z.string().min(1).optional().describe("Continue after the previous page"),
 })
     .strict();
-export const LOCAL_BROWSER_ACTIONS = [
-    "click",
-    "dblclick",
-    "type",
-    "press",
-    "hover",
-    "focus",
-    "check",
-    "uncheck",
-    "select",
-    "scroll",
-    "scroll_into_view",
-];
 export const localBrowserActInputSchema = localBrowserTargetSchema
     .extend({
     action: z.enum(LOCAL_BROWSER_ACTIONS),
-    ref: localBrowserRefSchema.optional(),
-    selector: z.string().min(1).optional(),
-    text: z.string().optional(),
-    key: z.string().min(1).optional(),
-    value: z.string().optional(),
-    values: z.array(z.string()).max(50).optional(),
-    deltaY: z.number().optional(),
+    ref: localBrowserRefSchema.optional().describe("Element ref from the latest snapshot, for example e12"),
+    selector: z.string().min(1).optional().describe("CSS selector when you have no ref"),
+    text: z.string().optional().describe("Text for type; replaces the field value unless submit is set"),
+    key: z.string().min(1).optional().describe("Key for press, for example Enter"),
+    value: z.string().optional().describe("Option value for select"),
+    values: z.array(z.string()).max(1_000).optional().describe("Multiple option values for select"),
+    deltaY: z.number().optional().describe("Scroll distance; positive is down"),
     deltaX: z.number().optional(),
-    submit: z.boolean().optional(),
-    timeoutMs: z.number().int().min(100).max(60_000).optional(),
+    submit: z.boolean().optional().describe("Press Enter after typing"),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Act even when another element covers the target; use after a refusal that says the element is covered"),
+    timeoutMs: timeoutSchema.optional(),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -149,7 +209,13 @@ export const localBrowserReadInputSchema = localBrowserTargetSchema
     .extend({
     selector: z.string().min(1).optional(),
     format: z.enum(["text", "markdown", "html"]).optional(),
-    maxChars: z.number().int().min(200).max(LOCAL_BROWSER_TEXT_MAX_CHARS).optional(),
+    maxChars: z
+        .number()
+        .int()
+        .min(200)
+        .max(ceiling("readMaxChars"))
+        .optional()
+        .describe("Default 8000; capped by the company read limit"),
 })
     .strict();
 export const localBrowserScreenshotInputSchema = localBrowserTargetSchema
@@ -164,20 +230,19 @@ export const localBrowserWaitInputSchema = localBrowserTargetSchema
     text: z.string().min(1).optional(),
     urlIncludes: z.string().min(1).optional(),
     idle: z.boolean().optional(),
-    timeoutMs: z.number().int().min(100).max(120_000).optional(),
+    timeoutMs: timeoutSchema.optional().describe("Default 10000; capped by the company call limit"),
 })
     .strict();
 export const localBrowserEvaluateInputSchema = localBrowserTargetSchema
     .extend({
-    expression: z.string().min(1),
+    expression: z.string().min(1).describe("An expression or a function body; return a JSON-serializable value"),
     world: z.enum(["main", "isolated"]).optional(),
     awaitPromise: z.boolean().optional(),
-    timeoutMs: z.number().int().min(100).max(60_000).optional(),
+    timeoutMs: timeoutSchema.optional(),
 })
     .strict();
-export const LOCAL_BROWSER_COOKIE_SAME_SITE = ["no_restriction", "lax", "strict", "unspecified"];
-export const LOCAL_BROWSER_COOKIE_CAPABILITY = "cookies.v2";
 const localBrowserDomainPattern = /^\.?(?!-)[a-z0-9-]{1,63}(?:\.(?!-)[a-z0-9-]{1,63})*\.?$/i;
+const COOKIE_ENTRY_KEYS = ["domain", "path", "secure", "httpOnly", "sameSite", "expirationDate", "storeId", "session"];
 const localBrowserCookieEntrySchema = z
     .object({
     name: z.string().min(1),
@@ -187,7 +252,8 @@ const localBrowserCookieEntrySchema = z
     secure: z.boolean().optional(),
     httpOnly: z.boolean().optional(),
     sameSite: z.enum(LOCAL_BROWSER_COOKIE_SAME_SITE).optional(),
-    expirationDate: z.number().positive().optional(),
+    expirationDate: z.number().positive().optional().describe("Seconds since the Unix epoch; omit for a session cookie"),
+    session: z.boolean().optional().describe("true writes a session cookie that ends with the browser; omit expirationDate"),
     storeId: z.string().min(1).optional(),
 })
     .strict();
@@ -201,13 +267,14 @@ export const localBrowserStorageInputSchema = localBrowserTargetSchema
         .min(1)
         .max(253)
         .regex(localBrowserDomainPattern, "domain must be a bare host name, without a scheme, wildcard or path")
-        .optional(),
-    allDomains: z.boolean().optional(),
-    storeId: z.string().min(1).optional(),
+        .optional()
+        .describe("Bare host such as example.com or .example.com; includes subdomains"),
+    allDomains: z.boolean().optional().describe("Whole cookie jar; needs confirmAll with op clear"),
+    storeId: z.string().min(1).optional().describe("Cookie store for reads and the default for writes"),
     name: z.string().min(1).optional(),
-    limit: z.number().int().min(1).max(500).optional(),
+    limit: z.number().int().min(1).max(100_000).optional().describe("Maximum cookies returned by get; default all"),
     confirmAll: z.boolean().optional(),
-    entries: z.array(localBrowserCookieEntrySchema).max(200).optional(),
+    entries: z.array(localBrowserCookieEntrySchema).max(1_000).optional(),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -218,7 +285,7 @@ export const localBrowserStorageInputSchema = localBrowserTargetSchema
             }
         }
         for (const [index, entry] of (value.entries ?? []).entries()) {
-            for (const key of ["domain", "path", "secure", "httpOnly", "sameSite", "expirationDate", "storeId"]) {
+            for (const key of COOKIE_ENTRY_KEYS) {
                 if (entry[key] !== undefined) {
                     ctx.addIssue({ code: "custom", path: ["entries", index, key], message: key + " applies to cookies only" });
                 }
@@ -226,6 +293,15 @@ export const localBrowserStorageInputSchema = localBrowserTargetSchema
         }
         return;
     }
+    for (const [index, entry] of (value.entries ?? []).entries()) {
+        if (entry.session === true && entry.expirationDate !== undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["entries", index, "expirationDate"],
+                message: "A session cookie has no expirationDate",
+            });
+        }
+    }
     if (value.limit !== undefined && value.op !== "get") {
         ctx.addIssue({ code: "custom", path: ["limit"], message: "limit is for get only" });
     }
@@ -257,8 +333,21 @@ export const localBrowserStorageInputSchema = localBrowserTargetSchema
 export const localBrowserNetworkInputSchema = localBrowserTargetSchema
     .extend({
     op: z.enum(["list", "clear"]),
-    limit: z.number().int().min(1).max(200).optional(),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(ceiling("networkMaxEntries"))
+        .optional()
+        .describe("Maximum requests returned; capped by the company network limit"),
     includeBodies: z.boolean().optional(),
+    includeHeaders: z.boolean().optional().describe("Return request and response headers; default true"),
+    since: z.number().nonnegative().optional().describe("Only requests that started at or after this epoch millisecond"),
+    types: z
+        .array(z.string().min(1).max(40))
+        .max(40)
+        .optional()
+        .describe("Resource types to keep, for example xmlhttprequest, fetch, document, script"),
     urlIncludes: z.string().min(1).optional(),
     method: z.string().min(1).optional(),
 })
@@ -267,7 +356,7 @@ export const localBrowserUploadInputSchema = localBrowserTargetSchema
     .extend({
     ref: localBrowserRefSchema.optional(),
     selector: z.string().min(1).optional(),
-    attachmentIds: z.array(z.string().uuid()).min(1).max(20),
+    attachmentIds: z.array(z.string().uuid()).min(1).max(100),
 })
     .strict();
 export const localBrowserDownloadInputSchema = localBrowserTargetSchema
@@ -279,279 +368,191 @@ export const localBrowserDownloadInputSchema = localBrowserTargetSchema
 export const localBrowserCloseInputSchema = localBrowserTargetSchema
     .extend({ closeSession: z.boolean().optional() })
     .strict();
+export const localBrowserContextInputSchema = localBrowserTargetSchema
+    .extend({
+    cookies: z.boolean().optional().describe("List the tab's cookies without their values; default true"),
+})
+    .strict();
+export const localBrowserPermissionIdSchema = z.enum(LOCAL_BROWSER_PERMISSION_IDS);
+export const localBrowserPermissionsInputSchema = sessionOnlySchema
+    .extend({
+    op: z.enum(["status", "request"]),
+    permissions: z
+        .array(localBrowserPermissionIdSchema)
+        .min(1)
+        .max(40)
+        .optional()
+        .describe("Permission ids to request, from the missing list of op status"),
+    reason: z.string().min(1).max(300).optional().describe("One sentence the user sees next to the request"),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    if (value.op === "request" && !value.permissions?.length) {
+        ctx.addIssue({ code: "custom", path: ["permissions"], message: "request needs permissions; call op status to see what is missing" });
+    }
+    if (value.op === "status" && value.permissions !== undefined) {
+        ctx.addIssue({ code: "custom", path: ["permissions"], message: "permissions is for op request only" });
+    }
+});
+export const localBrowserApiInputSchema = sessionOnlySchema
+    .extend({
+    path: z
+        .string()
+        .max(200)
+        .regex(LOCAL_BROWSER_API_PATH_PATTERN, "path is a dotted browser API name such as history.search")
+        .describe("Browser extension API function, for example history.search or tabs.query"),
+    args: z.array(z.unknown()).max(20).optional().describe("Arguments passed to the function, as JSON"),
+})
+    .strict();
+export const localBrowserUiInputSchema = z.object({ op: z.enum(LOCAL_BROWSER_UI_OPS) }).strict();
+export const localBrowserNetworkRequestSchema = z.object({
+    requestHeaders: z.record(z.string(), z.string()).optional(),
+    responseHeaders: z.record(z.string(), z.string()).optional(),
+    hasCookie: z.boolean(),
+    hasAuthorization: z.boolean(),
+    fromCache: z.boolean().optional(),
+    initiator: z.string().optional(),
+    error: z.string().optional(),
+    documentId: z.string().optional(),
+});
+export const localBrowserNetworkCaptureSchema = z.object({
+    mode: z.enum(["continuous", "window"]),
+    since: z.number(),
+    windowMs: z.number().optional(),
+});
+export const localBrowserCookieSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    domain: z.string(),
+    path: z.string(),
+    secure: z.boolean(),
+    httpOnly: z.boolean(),
+    sameSite: z.string(),
+    session: z.boolean(),
+    expirationDate: z.number().optional(),
+    hostOnly: z.boolean(),
+    storeId: z.string(),
+    partitionKey: z.unknown().optional(),
+});
+export const localBrowserContextResultSchema = z.object({
+    tab: localBrowserTabSchema,
+    container: z.object({
+        cookieStoreId: z.string(),
+        name: z.string().optional(),
+        color: z.string().optional(),
+        isDefault: z.boolean(),
+    }),
+    cookies: z.object({
+        storeId: z.string(),
+        url: z.string(),
+        count: z.number(),
+        items: z.array(z.object({
+            name: z.string(),
+            domain: z.string(),
+            path: z.string(),
+            session: z.boolean(),
+            expirationDate: z.number().optional(),
+            httpOnly: z.boolean(),
+            secure: z.boolean(),
+            sameSite: z.string(),
+            hostOnly: z.boolean(),
+        })),
+    }),
+    document: localBrowserDocumentStateSchema.nullable(),
+    contentScript: z.enum(LOCAL_BROWSER_CONTENT_SCRIPT_STATES),
+    network: z.object({
+        capturing: z.boolean(),
+        lastRequestAt: z.number().optional(),
+        requestsSinceLoad: z.number().optional(),
+    }),
+    access: localBrowserAccessSchema,
+});
+export const localBrowserPermissionsResultSchema = z.object({
+    granted: z.array(z.string()),
+    missing: z.array(z.string()),
+    pending: localBrowserAccessSchema.shape.pending,
+    siteAccess: z.enum(LOCAL_BROWSER_SITE_ACCESS),
+    requested: z.array(z.string()).optional(),
+    alreadyGranted: z.array(z.string()).optional(),
+    note: z.string(),
+});
+export const localBrowserApiResultSchema = z.object({ value: z.unknown(), type: z.string() });
+const ORIGIN_EXEMPT = new Set(LOCAL_BROWSER_ORIGIN_EXEMPT_TOOL_NAMES);
+function defineTool(name, description, schema) {
+    const { $schema: _schema, ...inputSchema } = z.toJSONSchema(schema, { io: "input" });
+    return {
+        name,
+        description,
+        schema,
+        inputSchema,
+        tier: LOCAL_BROWSER_TOOL_TIERS[name],
+        capability: LOCAL_BROWSER_TOOL_CAPABILITIES[name] ?? null,
+        originExempt: ORIGIN_EXEMPT.has(name),
+    };
+}
 const targetHint = "Omit sessionId when exactly one browser is paired; omit tabId to use the active tab.";
 export const LOCAL_BROWSER_TOOLS = [
-    {
-        name: "local_browser_sessions",
-        description: `List the paired browsers and their open tabs. ${targetHint} Start here when you do not know the current tab.`,
-        inputSchema: { type: "object", properties: {}, additionalProperties: false },
-        tier: "refine",
-    },
-    {
-        name: "local_browser_open",
-        description: "Open a URL in the user's real browser. It reuses the tab you already opened for this work, and creates one only when you have none, so repeated opens never pile up tabs. Never navigates the tab the user is looking at or the Paperclip tab itself.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string", description: "Paired browser session id" },
-                tabId: { type: "integer", description: "Target this tab instead of your own; refused for the tab the user is looking at and for the Paperclip tab" },
-                url: { type: "string", description: "Absolute http(s) URL" },
-                newTab: { type: "boolean", description: "Accepted for compatibility; a url reuses your own tab when you have one" },
-                active: { type: "boolean", description: "Focus the tab when opening it" },
-            },
-            additionalProperties: false,
-        },
-        tier: "refine",
-    },
-    {
-        name: "local_browser_navigate",
-        description: "Navigate the current tab: pass url, or one of back, forward, reload. Prefer this over local_browser_open when the tab is already on the site you need. Refused for the tab the user is looking at and for the Paperclip tab itself; call local_browser_open for those.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                url: { type: "string" },
-                back: { type: "boolean" },
-                forward: { type: "boolean" },
-                reload: { type: "boolean" },
-                waitUntil: { type: "string", enum: ["load", "domcontentloaded", "networkidle"] },
-                timeoutMs: { type: "integer", description: "Default 15000, max 120000" },
-            },
-            additionalProperties: false,
-        },
-        tier: "refine",
-    },
-    {
-        name: "local_browser_snapshot",
-        description: "Read the page as a compact accessibility tree where every interactive element has a ref like e12. This is the primary way to see a page: call it after every navigation or click, then pass those refs to local_browser_act. Output is capped; pass cursor from the previous result to continue.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                selector: { type: "string", description: "Scope the snapshot to a subtree" },
-                maxNodes: { type: "integer", description: "Default 120, max 400" },
-                includeText: { type: "boolean", description: "Include short text content per node" },
-                includeHidden: { type: "boolean" },
-                cursor: { type: "string", description: "Continue after the previous page" },
-            },
-            additionalProperties: false,
-        },
-        tier: "refine",
-    },
-    {
-        name: "local_browser_act",
-        description: "Do one thing on the page: click, dblclick, type, press, hover, focus, check, uncheck, select, scroll, scroll_into_view. Target an element with ref from the latest snapshot, or a CSS selector. After a click or press that changes the page, take a new snapshot because old refs go stale.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                action: {
-                    type: "string",
-                    enum: ["click", "dblclick", "type", "press", "hover", "focus", "check", "uncheck", "select", "scroll", "scroll_into_view"],
-                },
-                ref: { type: "string", description: "Element ref from the latest snapshot, for example e12" },
-                selector: { type: "string", description: "CSS selector when you have no ref" },
-                text: { type: "string", description: "Text for type; replaces the field value unless submit is set" },
-                key: { type: "string", description: "Key for press, for example Enter" },
-                value: { type: "string", description: "Option value for select" },
-                values: { type: "array", items: { type: "string" }, description: "Multiple option values for select" },
-                deltaY: { type: "number", description: "Scroll distance; positive is down" },
-                deltaX: { type: "number" },
-                submit: { type: "boolean", description: "Press Enter after typing" },
-                timeoutMs: { type: "integer" },
-            },
-            additionalProperties: false,
-        },
-        tier: "refine",
-    },
-    {
-        name: "local_browser_read",
-        description: "Extract text, markdown or html from the page or one element. Use this instead of a snapshot when you need the content itself rather than the controls. Output is capped at maxChars; the result says when it was truncated.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                selector: { type: "string" },
-                format: { type: "string", enum: ["text", "markdown", "html"] },
-                maxChars: { type: "integer", description: "Default 8000, max 40000" },
-            },
-            additionalProperties: false,
-        },
-        tier: "refine",
-    },
-    {
-        name: "local_browser_screenshot",
-        description: "Capture the visible tab, or one element, as an image attachment for the human. Use it for visual checks, layout problems and canvas or image content that a snapshot cannot describe.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                selector: { type: "string" },
-                fullPage: { type: "boolean" },
-            },
-            additionalProperties: false,
-        },
-        tier: "refine",
-    },
-    {
-        name: "local_browser_wait",
-        description: "Wait for a condition before acting: a selector appears, text appears, the URL contains a string, or the page is idle. Prefer this over repeating snapshots in a loop.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                selector: { type: "string" },
-                text: { type: "string" },
-                urlIncludes: { type: "string" },
-                idle: { type: "boolean" },
-                timeoutMs: { type: "integer", description: "Default 10000, max 120000" },
-            },
-            additionalProperties: false,
-        },
-        tier: "refine",
-    },
-    {
-        name: "local_browser_evaluate",
-        description: "Run JavaScript in the page and return its value as JSON. Full-power tier only. The page is the user's real browser: read what you need, do not exfiltrate credentials, and prefer snapshot and act for ordinary interaction.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                expression: { type: "string", description: "An expression or a function body; return a JSON-serializable value" },
-                world: { type: "string", enum: ["main", "isolated"] },
-                awaitPromise: { type: "boolean" },
-                timeoutMs: { type: "integer" },
-            },
-            required: ["expression"],
-            additionalProperties: false,
-        },
-        tier: "full",
-    },
-    {
-        name: "local_browser_storage",
-        description: "Read or write cookies, localStorage or sessionStorage for the page. Cookies can be scoped by url, by domain (includes subdomains) or with allDomains for the whole jar, and can be written with domain, path, secure, httpOnly, sameSite and expiry. Full-power tier only. Never print secret values into the task; report only what the task needs.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                kind: { type: "string", enum: ["cookies", "local", "session"] },
-                op: { type: "string", enum: ["get", "set", "clear"] },
-                url: { type: "string" },
-                domain: { type: "string", description: "Bare host such as example.com or .example.com; includes subdomains" },
-                allDomains: { type: "boolean", description: "Whole cookie jar; needs confirmAll with op clear" },
-                storeId: { type: "string", description: "Cookie store for reads and the default for writes" },
-                name: { type: "string" },
-                limit: { type: "integer", description: "Maximum cookies returned by get (default 200)" },
-                confirmAll: { type: "boolean" },
-                entries: {
-                    type: "array",
-                    items: {
-                        type: "object",
-                        properties: {
-                            name: { type: "string" },
-                            value: { type: "string" },
-                            domain: { type: "string" },
-                            path: { type: "string" },
-                            secure: { type: "boolean" },
-                            httpOnly: { type: "boolean" },
-                            sameSite: { type: "string", enum: [...LOCAL_BROWSER_COOKIE_SAME_SITE] },
-                            expirationDate: { type: "number", description: "Seconds since the Unix epoch; omit for a session cookie" },
-                            storeId: { type: "string" },
-                        },
-                        required: ["name", "value"],
-                        additionalProperties: false,
-                    },
-                },
-            },
-            required: ["kind", "op"],
-            additionalProperties: false,
-        },
-        tier: "full",
-    },
-    {
-        name: "local_browser_network",
-        description: "List recent network requests of the tab, optionally with response bodies. Full-power tier only. Use it to diagnose a failing call instead of guessing from the page.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                op: { type: "string", enum: ["list", "clear"] },
-                limit: { type: "integer", description: "Default 50, max 200" },
-                includeBodies: { type: "boolean" },
-                urlIncludes: { type: "string" },
-                method: { type: "string" },
-            },
-            required: ["op"],
-            additionalProperties: false,
-        },
-        tier: "full",
-    },
-    {
-        name: "local_browser_upload",
-        description: "Attach files from the task to a file input on the page. Full-power tier only. Pass attachmentIds from the task's attachments.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                ref: { type: "string" },
-                selector: { type: "string" },
-                attachmentIds: { type: "array", items: { type: "string" } },
-            },
-            required: ["attachmentIds"],
-            additionalProperties: false,
-        },
-        tier: "full",
-    },
-    {
-        name: "local_browser_download",
-        description: "List the tab's downloads, or save one into the task as an attachment. Full-power tier only.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                op: { type: "string", enum: ["list", "save"] },
-                downloadId: { type: "integer" },
-            },
-            required: ["op"],
-            additionalProperties: false,
-        },
-        tier: "full",
-    },
-    {
-        name: "local_browser_close",
-        description: "Close a tab, or the whole paired browser session, when you are done. Closing a session does not sign the user out; it disconnects Paperclip from that browser.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                sessionId: { type: "string" },
-                tabId: { type: "integer" },
-                closeSession: { type: "boolean" },
-            },
-            additionalProperties: false,
-        },
-        tier: "refine",
-    },
+    defineTool("local_browser_sessions", "List the paired browsers with their open tabs, capabilities, granted permissions and guards. " + targetHint + " Start here when you do not know the current tab.", localBrowserSessionsInputSchema),
+    defineTool("local_browser_open", "Open a URL in the user's real browser. It reuses the tab you already opened for this work and creates one only when you have none, so repeated opens never pile up tabs. Pass cookieStoreId to open in a container or another cookie jar, incognito for a private window, newWindow for a separate window. Never navigates the tab the user is looking at or the Paperclip tab itself. Returns the tab and a first snapshot.", localBrowserOpenInputSchema),
+    defineTool("local_browser_navigate", "Navigate the current tab: pass url, or one of back, forward, reload. Prefer this over local_browser_open when the tab is already on the site you need. Refused for the tab the user is looking at and for the Paperclip tab itself; call local_browser_open for those.", localBrowserNavigateInputSchema),
+    defineTool("local_browser_snapshot", "Read the page as a compact accessibility tree where every interactive element has a ref like e12. This is the primary way to see a page: call it after every navigation or click, then pass those refs to local_browser_act. Pass cursor from the previous result to continue. The result carries document; when document.stale is true, reload before you trust it.", localBrowserSnapshotInputSchema),
+    defineTool("local_browser_act", "Do one thing on the page: click, dblclick, type, press, hover, focus, check, uncheck, select, scroll, scroll_into_view. Target an element with ref from the latest snapshot, or a CSS selector. Pass force to act on an element another element covers. After a click or press that changes the page, take a new snapshot because old refs go stale.", localBrowserActInputSchema),
+    defineTool("local_browser_read", "Extract text, markdown or html from the page or one element. Use this instead of a snapshot when you need the content itself rather than the controls. The result says when it was truncated and carries document state.", localBrowserReadInputSchema),
+    defineTool("local_browser_screenshot", "Capture the visible tab, or one element, as an image attachment for the human. Use it for visual checks, layout problems and canvas or image content that a snapshot cannot describe.", localBrowserScreenshotInputSchema),
+    defineTool("local_browser_wait", "Wait for a condition before acting: a selector appears, text appears, the URL contains a string, or the page is idle. Prefer this over repeating snapshots in a loop.", localBrowserWaitInputSchema),
+    defineTool("local_browser_evaluate", "Run JavaScript in the page and return its value as JSON. Full tier only. The page is the user's real browser: read what you need, do not exfiltrate credentials, and prefer snapshot and act for ordinary interaction.", localBrowserEvaluateInputSchema),
+    defineTool("local_browser_storage", "Read or write cookies, localStorage or sessionStorage. Cookies can be scoped by url, by domain (includes subdomains) or with allDomains for the whole jar, and each cookie reports session, expirationDate, httpOnly, secure, sameSite, hostOnly, storeId and partitionKey. Full tier only. Never print secret values into the task; report only what the task needs.", localBrowserStorageInputSchema),
+    defineTool("local_browser_network", "List the requests the tab made, with request and response headers, status, timing and optionally bodies. Capture runs continuously, so pass since or urlIncludes to narrow it. Full tier only. Use it to diagnose a failing call instead of guessing from the page.", localBrowserNetworkInputSchema),
+    defineTool("local_browser_upload", "Attach files from the task to a file input on the page. Full tier only. Pass attachmentIds from the task's attachments.", localBrowserUploadInputSchema),
+    defineTool("local_browser_download", "List the tab's downloads, or save one into the task as an attachment. Full tier only.", localBrowserDownloadInputSchema),
+    defineTool("local_browser_close", "Close a tab, or the whole paired browser session, when you are done. Closing a session does not sign the user out; it disconnects Paperclip from that browser.", localBrowserCloseInputSchema),
+    defineTool("local_browser_context", "Probe one tab before you work in it: its container and cookie jar, the cookies for its URL without values, whether the page is stale or came back from the back-forward cache, whether the content script is connected, network capture state and the browser permissions. Call it when a page behaves oddly or before cookie and network work.", localBrowserContextInputSchema),
+    defineTool("local_browser_permissions", "See which browser permissions the extension has, or ask the user for missing ones. op request cannot grant anything by itself: it shows the request in the extension, and you must tell the user to press Allow there. Call op status again after the user answers.", localBrowserPermissionsInputSchema),
+    defineTool("local_browser_api", "Call any browser extension API function directly, for example history.search, bookmarks.search, tabs.query or windows.getAll, and get its result as JSON. Full tier only. A function whose permission is missing fails with local_browser_permission_required; the extension's own storage is off limits.", localBrowserApiInputSchema),
 ];
 export const LOCAL_BROWSER_TOOL_NAMES = LOCAL_BROWSER_TOOLS.map((tool) => tool.name);
 export const LOCAL_BROWSER_FULL_TIER_TOOL_NAMES = LOCAL_BROWSER_TOOLS.filter((tool) => tool.tier === "full").map((tool) => tool.name);
+const TOOLS_BY_NAME = new Map(LOCAL_BROWSER_TOOLS.map((tool) => [tool.name, tool]));
+const INTERNAL_TOOLS = new Set(LOCAL_BROWSER_INTERNAL_TOOL_NAMES);
+export function localBrowserTool(name) {
+    return TOOLS_BY_NAME.get(name) ?? null;
+}
+export function localBrowserIsInternalTool(name) {
+    return INTERNAL_TOOLS.has(name);
+}
 export function localBrowserToolRequiresFullTier(name) {
-    return LOCAL_BROWSER_FULL_TIER_TOOL_NAMES.includes(name);
+    return TOOLS_BY_NAME.get(name)?.tier === "full";
+}
+export function localBrowserPermissionsForClient(client) {
+    return LOCAL_BROWSER_PERMISSIONS.filter((permission) => permission[client] !== "unsupported");
 }
 export const localBrowserSettingsSchema = z
     .object({
     tier: localBrowserTierSchema.default("refine"),
     allowedOrigins: z.array(z.string().min(1)).max(200).default([]),
+    limits: localBrowserLimitsSchema.prefault({}),
+})
+    .strict();
+function limitRange(key) {
+    const range = LOCAL_BROWSER_LIMITS[key];
+    return z.number().int().min(range.min).max(range.ceiling).optional();
+}
+export const localBrowserSettingsUpdateSchema = z
+    .object({
+    tier: localBrowserTierSchema.optional(),
+    allowedOrigins: z.array(z.string().min(1)).max(200).optional(),
+    limits: z
+        .object({
+        resultMaxChars: limitRange("resultMaxChars"),
+        snapshotMaxNodes: limitRange("snapshotMaxNodes"),
+        readMaxChars: limitRange("readMaxChars"),
+        screenshotMaxBytes: limitRange("screenshotMaxBytes"),
+        transferMaxBytes: limitRange("transferMaxBytes"),
+        callMaxMs: limitRange("callMaxMs"),
+        networkMaxEntries: limitRange("networkMaxEntries"),
+    })
+        .strict()
+        .optional(),
 })
     .strict();
 export function localBrowserOriginOf(rawUrl) {
@@ -586,8 +587,6 @@ export function localBrowserOriginAllowed(settings, rawUrl) {
         return normalized.toLowerCase() === origin.toLowerCase();
     });
 }
-export const LOCAL_BROWSER_MOUSE_ACTIONS = ["move", "down", "up"];
-export const LOCAL_BROWSER_KEY_ACTIONS = ["down", "up"];
 export const localBrowserInputSchema = z.discriminatedUnion("kind", [
     z
         .object({
@@ -622,6 +621,7 @@ export const localBrowserInputSchema = z.discriminatedUnion("kind", [
     })
         .strict(),
 ]);
+const viewerStateSchema = z.enum(LOCAL_BROWSER_VIEWER_STATES);
 export const localBrowserViewerFrameEventSchema = z
     .object({
     type: z.literal("frame"),
@@ -634,7 +634,7 @@ export const localBrowserViewerFrameEventSchema = z
 export const localBrowserViewerStateEventSchema = z
     .object({
     type: z.literal("state"),
-    state: z.enum(["connected", "viewer_unavailable", "agent_streaming", "agent_idle", "disconnected"]),
+    state: viewerStateSchema,
     tabId: z.number().int().nonnegative().optional(),
     message: z.string().max(400).optional(),
 })
@@ -670,17 +670,33 @@ export const localBrowserStateEventSchema = z
     event: z.literal("state"),
     data: z
         .object({
-        state: z.enum(["connected", "viewer_unavailable", "agent_streaming", "agent_idle", "disconnected"]),
+        state: viewerStateSchema,
         tabId: z.number().int().nonnegative().optional(),
         message: z.string().max(400).optional(),
     })
         .strict(),
 })
     .strict();
+export const localBrowserAccessEventSchema = z
+    .object({
+    type: z.literal("event"),
+    event: z.literal("access"),
+    data: localBrowserAccessSchema,
+})
+    .strict();
+export const localBrowserGuardsEventSchema = z
+    .object({
+    type: z.literal("event"),
+    event: z.literal("guards"),
+    data: localBrowserGuardsSchema,
+})
+    .strict();
 export const localBrowserExtensionEventFrameSchema = z.discriminatedUnion("event", [
     localBrowserTabsEventSchema,
     localBrowserFrameEventSchema,
     localBrowserStateEventSchema,
+    localBrowserAccessEventSchema,
+    localBrowserGuardsEventSchema,
 ]);
 export const LOCAL_BROWSER_PAIRING_CODE_LENGTH = 8;
 export const localBrowserPairingStartSchema = z
@@ -697,10 +713,47 @@ export const localBrowserPairingStartResultSchema = z
 })
     .strict();
 export const localBrowserBridgeFrameSchema = z.discriminatedUnion("type", [
-    z.object({ type: z.literal("hello"), protocol: z.number().int(), client: localBrowserClientSchema, clientVersion: z.string(), label: z.string(), profileName: z.string().nullable(), tabs: z.array(localBrowserTabSchema), capabilities: z.array(z.string().min(1).max(40)).max(20).optional() }).strict(),
-    z.object({ type: z.literal("hello_ack"), sessionId: z.string().uuid(), sessionToken: z.string(), tier: localBrowserTierSchema, allowedOrigins: z.array(z.string()) }).strict(),
-    z.object({ type: z.literal("call"), id: z.string(), tool: z.string(), args: z.unknown() }).strict(),
-    z.object({ type: z.literal("result"), id: z.string(), ok: z.boolean(), result: z.unknown().optional(), error: localBrowserToolErrorSchema.optional() }).strict(),
+    z
+        .object({
+        type: z.literal("hello"),
+        protocol: z.number().int(),
+        client: localBrowserClientSchema,
+        clientVersion: z.string(),
+        label: z.string(),
+        profileName: z.string().nullable(),
+        tabs: z.array(localBrowserTabSchema),
+        capabilities: z.array(z.string().min(1).max(40)).max(40).optional(),
+        access: localBrowserAccessSchema.optional().catch(undefined),
+        guards: localBrowserGuardsSchema.optional().catch(undefined),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("hello_ack"),
+        sessionId: z.string().uuid(),
+        sessionToken: z.string(),
+        tier: localBrowserTierSchema,
+        allowedOrigins: z.array(z.string()),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("call"),
+        id: z.string(),
+        tool: z.string(),
+        args: z.unknown(),
+        budgetMs: z.number().int().positive().optional(),
+    })
+        .strict(),
+    z
+        .object({
+        type: z.literal("result"),
+        id: z.string(),
+        ok: z.boolean(),
+        result: z.unknown().optional(),
+        error: localBrowserToolErrorSchema.optional(),
+    })
+        .strict(),
     z.object({ type: z.literal("event"), event: z.string(), data: z.unknown() }).strict(),
     z.object({ type: z.literal("ping"), at: z.string() }).strict(),
     z.object({ type: z.literal("pong"), at: z.string() }).strict(),