@lobu/cli 7.0.0 → 7.2.0

package/dist/config/loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpE,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAY3C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAE9C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,KAAK,EAAE,MAAM,eAAe,aAAa,GAAG,EAAE;YAC9C,OAAO,EAAE,CAAC,gCAAgC,CAAC;SAC5C,CAAC;IACJ,CAAC;IAED,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,GAAG,CAA4B,CAAC;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,KAAK,EAAE,0BAA0B,eAAe,EAAE;YAClD,OAAO,EAAE,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;SAC5D,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CACrC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CACvD,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,WAAW,eAAe,EAAE,EAAE,OAAO,EAAE,CAAC;IAC1D,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,MAA8B;IAE9B,OAAO,OAAO,IAAI,MAAM,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpE,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAY3C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IAE9C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,KAAK,EAAE,MAAM,eAAe,aAAa,GAAG,EAAE;YAC9C,OAAO,EAAE,CAAC,gCAAgC,CAAC;SAC5C,CAAC;IACJ,CAAC;IAED,IAAI,MAA+B,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,GAAG,CAA4B,CAAC;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,KAAK,EAAE,0BAA0B,UAAU,EAAE;YAC7C,OAAO,EAAE,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;SAC5D,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CACrC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CACvD,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,WAAW,UAAU,EAAE,EAAE,OAAO,EAAE,CAAC;IACrD,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,MAA8B;IAE9B,OAAO,OAAO,IAAI,MAAM,CAAC;AAC3B,CAAC"}

package/dist/connectors/README.md

@@ -520,7 +520,6 @@ This means edits to `.ts` files in `connectors/` take effect on the next sync wi
 | `github` | oauth/env_keys | issues, PRs, comments, discussions | create/close/reopen issues, PRs |
 | `glassdoor` | none | reviews | - |
 | `gmaps` | env_keys | reviews | - |
-| `google_photos` | browser (CDP) | photos | - |
 | `google_play` | none | reviews | - |
 | `hackernews` | none | stories, comments | - |
 | `ios_appstore` | none | reviews | - |

package/dist/connectors/apple_photos.ts

@@ -0,0 +1,178 @@
+/**
+ * Apple Photos Connector (V1 runtime) — Lobu Mac app.
+ *
+ * Runs on a Mac advertising the `photos` capability. The bridge holds the
+ * `NSPhotoLibraryUsageDescription` Info.plist string and prompts the user via
+ * TCC the first time a job is claimed. Once granted, PhotoKit exposes the
+ * user's local Photos library — which is mirrored from iCloud Photos when
+ * that's enabled — including the rich metadata Google's Photos Library API
+ * does NOT expose: location (lat/lng), people (Apple's on-device face
+ * recognition), albums, captions, keywords, and Vision OCR text.
+ *
+ * One feed in v1:
+ *
+ * - `library`: every PHAsset in the user's library, with stable origin ids
+ *   derived from the asset's localIdentifier. Re-runs upsert by origin id.
+ *
+ * v1 ingests metadata + remote references (asset_local_id, asset_cloud_id,
+ * source_url for the photos.apple.com deep link). The actual image bytes
+ * are NOT embedded in events; future connector actions (`fetch_thumbnail`,
+ * `fetch_original`) will let an agent pull bytes on demand via the Mac
+ * worker.
+ *
+ * The connector DEFINITION here is the source of truth for shape; EXECUTION
+ * lives in the Mac app's PhotosSyncService, which polls /api/workers/* with
+ * `photos: true` and streams events back through the standard worker
+ * protocol — same `runs` lifecycle as every other device-bound connector.
+ *
+ * The TS sync()/execute() are safety stubs: if a server-side worker somehow
+ * bypassed the capability gate (`required_capability='photos'`), the run
+ * throws immediately instead of silently producing zero events.
+ */
+
+import {
+  type ActionResult,
+  type ConnectorDefinition,
+  ConnectorRuntime,
+  type SyncContext,
+  type SyncResult,
+} from '@lobu/connector-sdk';
+
+const BRIDGE_ONLY_MESSAGE =
+  'apple.photos runs only on a worker advertising capability "photos" (Lobu Mac app with Photos permission). ' +
+  'This run was claimed by a worker without that capability — check connector_definitions.required_capability and the poll-time capability filter.';
+
+export default class ApplePhotosConnector extends ConnectorRuntime {
+  readonly definition: ConnectorDefinition = {
+    key: 'apple.photos',
+    name: 'Apple Photos',
+    description:
+      'Sync your Photos library (local or iCloud-mirrored) from the Lobu Mac app. ' +
+      'Includes location, people, albums, captions, keywords, and Vision OCR text — ' +
+      'data Google Photos\' API does not expose.',
+    version: '0.1.0',
+    faviconDomain: 'apple.com',
+    requiredCapability: 'photos',
+    runtime: {
+      platforms: ['macos'],
+      scopes: ['date', 'location', 'people', 'albums', 'captions', 'keywords', 'ocr'],
+    },
+    authSchema: {
+      methods: [{ type: 'none' }],
+    },
+    feeds: {
+      library: {
+        key: 'library',
+        name: 'Library',
+        description:
+          'Every photo in your library. Each event carries the photo\'s metadata ' +
+          '(date taken, location, people, albums, captions, OCR text) plus stable ' +
+          'asset identifiers so agents can fetch the image bytes on demand.',
+        configSchema: {
+          type: 'object',
+          properties: {
+            backfill_days: {
+              type: 'integer',
+              minimum: 1,
+              maximum: 36500,
+              default: 3650,
+              description:
+                'How many days back the bridge backfills on a fresh sync. Default 10 years; ' +
+                'incremental runs only re-query the modification window since last_sync_at.',
+            },
+            include_screenshots: {
+              type: 'boolean',
+              default: true,
+              description: 'Include screenshots (PHAssetMediaSubtype.photoScreenshot).',
+            },
+            include_videos: {
+              type: 'boolean',
+              default: false,
+              description: 'Include video assets in addition to photos.',
+            },
+          },
+        },
+        eventKinds: {
+          photo: {
+            description:
+              'A single photo (or video, if enabled) from the user\'s Apple Photos library. ' +
+              'v1 (this PR) populates: asset_local_id, media_type, media_subtypes, ' +
+              'date_taken, date_modified, width, height, duration_s, latitude/longitude/altitude_m, ' +
+              'albums, is_favorite, is_hidden — everything PhotoKit\'s public API exposes. ' +
+              'v2 will add: asset_cloud_id, place_name (reverse geocoding), people, ' +
+              'keywords, caption, ocr_text — all of which require direct reads against ' +
+              'the Photos.sqlite bundle (FDA + schema-pinned, osxphotos-style). ' +
+              'Schema allows nulls so v1 events validate cleanly.',
+            metadataSchema: {
+              type: 'object',
+              required: ['source', 'origin_id', 'asset_local_id'],
+              properties: {
+                source: { type: 'string', const: 'apple_photos' },
+                origin_id: { type: 'string' },
+                asset_local_id: {
+                  type: 'string',
+                  description: 'PHAsset.localIdentifier — stable per-device handle.',
+                },
+                asset_cloud_id: {
+                  type: ['string', 'null'],
+                  description: 'iCloud asset id when synced via iCloud Photos.',
+                },
+                media_type: {
+                  type: 'string',
+                  enum: ['image', 'video', 'audio', 'unknown'],
+                },
+                media_subtypes: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'PHAssetMediaSubtype flags: live, hdr, screenshot, panorama, portrait, etc.',
+                },
+                date_taken: { type: ['string', 'null'], format: 'date-time' },
+                date_modified: { type: ['string', 'null'], format: 'date-time' },
+                width: { type: ['integer', 'null'] },
+                height: { type: ['integer', 'null'] },
+                duration_s: {
+                  type: ['number', 'null'],
+                  description: 'Duration in seconds — videos and Live Photos only.',
+                },
+                latitude: { type: ['number', 'null'] },
+                longitude: { type: ['number', 'null'] },
+                altitude_m: { type: ['number', 'null'] },
+                place_name: {
+                  type: ['string', 'null'],
+                  description:
+                    'Reverse-geocoded human-readable place from CLGeocoder when available offline.',
+                },
+                people: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Named-person tags from Apple\'s on-device face recognition.',
+                },
+                albums: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'User album names this asset belongs to.',
+                },
+                keywords: {
+                  type: 'array',
+                  items: { type: 'string' },
+                },
+                caption: { type: ['string', 'null'] },
+                is_favorite: { type: 'boolean' },
+                is_hidden: { type: 'boolean' },
+              },
+            },
+          },
+        },
+      },
+    },
+  };
+
+  async sync(_ctx: SyncContext): Promise<SyncResult> {
+    throw new Error(BRIDGE_ONLY_MESSAGE);
+  }
+
+  async execute(): Promise<ActionResult> {
+    throw new Error(BRIDGE_ONLY_MESSAGE);
+  }
+}

package/dist/connectors/browser-scraper-utils.ts

@@ -82,6 +82,82 @@ export function validateCookieNotExpired(
 // URL validation
 // -----------------------------------------------------------------------------
 
+/**
+ * Validates a URL is safe for server-side fetching.
+ * Blocks private/internal network addresses to prevent SSRF attacks.
+ *
+ * Returns silently when the URL is safe; throws with a descriptive message
+ * otherwise. Connectors that fetch URLs derived from remote/untrusted input
+ * (sitemaps, HN story links, RSS feeds configured by users, etc.) MUST call
+ * this at the trust boundary before issuing the request.
+ */
+export function validatePublicUrl(url: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: ${url}`);
+  }
+
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`URL must use http: or https: protocol, got ${parsed.protocol}`);
+  }
+
+  const hostname = parsed.hostname.toLowerCase();
+
+  // Block localhost variants
+  if (hostname === 'localhost' || hostname === '[::1]' || hostname.endsWith('.localhost')) {
+    throw new Error(`URL must not point to localhost: ${hostname}`);
+  }
+
+  // IPv4 private/loopback/link-local/cloud-metadata/CGNAT ranges
+  const ipv4Match = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (ipv4Match) {
+    const [, a, b] = ipv4Match.map(Number);
+    if (
+      a === 127 || // loopback
+      a === 10 || // private
+      (a === 172 && b >= 16 && b <= 31) || // private
+      (a === 192 && b === 168) || // private
+      (a === 169 && b === 254) || // link-local incl. 169.254.169.254 cloud metadata
+      (a === 100 && b >= 64 && b <= 127) || // CGNAT 100.64.0.0/10
+      a === 0
+    ) {
+      throw new Error(`URL must not point to a private/internal IP address: ${hostname}`);
+    }
+  }
+
+  // IPv6 private ranges (bracketed notation)
+  if (hostname.startsWith('[')) {
+    const ipv6 = hostname.slice(1, -1).toLowerCase();
+    // Link-local fe80::/10 covers fe80:..fec0: (first byte 1111 1110 1x).
+    const linkLocalPrefix = /^fe[89ab][0-9a-f]?:/;
+    // Multicast ff00::/8 — any address starting with ff.
+    const multicastPrefix = /^ff[0-9a-f]{2}:/;
+    if (
+      ipv6 === '::1' ||
+      linkLocalPrefix.test(ipv6) ||
+      multicastPrefix.test(ipv6) ||
+      ipv6.startsWith('fc') || // unique local fc00::/7
+      ipv6.startsWith('fd') ||
+      ipv6 === '::' ||
+      ipv6.startsWith('::ffff:') // IPv4-mapped IPv6
+    ) {
+      throw new Error(`URL must not point to a private/internal IPv6 address: ${hostname}`);
+    }
+  }
+
+  // Common internal hostnames
+  if (
+    hostname.endsWith('.internal') ||
+    hostname.endsWith('.local') ||
+    hostname.endsWith('.corp') ||
+    hostname.endsWith('.lan')
+  ) {
+    throw new Error(`URL must not point to an internal hostname: ${hostname}`);
+  }
+}
+
 /**
  * Validate that a URL is well-formed, uses HTTPS, and belongs to the expected
  * domain (hostname ends with `expectedDomain`).

package/dist/connectors/chrome.ts

@@ -0,0 +1,351 @@
+/**
+ * Chrome Connector — Owletto for Chrome only.
+ *
+ * One connector per paired Chrome profile. The cloud-side definition is
+ * pure metadata; all execution happens in the extension's service worker
+ * (apps/chrome/background.js: dispatchToolRun) against the user's signed-in
+ * Chrome via chrome.debugger + chrome.scripting + chrome.tabs.
+ *
+ * Surface:
+ *
+ *   feeds.open_tabs
+ *     Auto-wired snapshot feed. The extension emits one event per open tab
+ *     each sync cycle. Cheap and read-only.
+ *
+ *   actions.navigate
+ *     Page.navigate the target tab (default: a fresh background tab; opt
+ *     out via open_in_new_tab=false) to `url`.
+ *
+ *   actions.get_accessibility_tree
+ *     Inject the bundled accessibility-tree.js content script and return a
+ *     structured snapshot of the visible interactive nodes, each with a
+ *     stable {frame_id, document_epoch, ref_id} that subsequent
+ *     click_ref/type_ref calls can target. Sensitive fields (password,
+ *     one-time-code, credit-card autocomplete) are redacted in the page
+ *     before the snapshot leaves it.
+ *
+ *   actions.click_ref / actions.type_ref
+ *     Act on a ref returned by get_accessibility_tree, in the same tab,
+ *     using chrome.debugger Input.dispatchMouseEvent / dispatchKeyEvent /
+ *     insertText. Refs become stale on navigation or DOM replacement; the
+ *     extension surfaces a clear error and the caller re-snapshots.
+ *
+ *   actions.wait_for_selector
+ *     Poll the page for a CSS selector via Runtime.evaluate. Returns when
+ *     it appears or rejects on timeout (default 10s).
+ *
+ *   actions.screenshot
+ *     Page.captureScreenshot. PNG, base64-encoded.
+ *
+ *   actions.evaluate
+ *     Runtime.evaluate(expression). Returns the JSON-serialised result.
+ *     Last-resort escape hatch — prefer ref-based actions because the
+ *     script string is harder to audit.
+ *
+ * The connector author writes a normal server-side sync() that sequences
+ * these actions through `ctx.chrome.<tool>(args)` (helper added in a
+ * later PR — for v1 the actions are reachable directly via the run
+ * scheduling API). No bespoke executor code lives in the extension; new
+ * connectors compose existing tools.
+ *
+ * URL allowlist: each connector that runs on top of this dispatcher
+ * declares `allowedOrigins` on its own definition. The extension refuses
+ * any tool call whose target URL is outside the allowlist.
+ *
+ * Required worker capability is `browser.debugger`.
+ *
+ * Cloud-side `sync()` / `execute()` throw — actual work happens in the
+ * extension's service worker.
+ */
+
+import {
+  type ActionResult,
+  type ConnectorDefinition,
+  ConnectorRuntime,
+  type SyncContext,
+  type SyncResult,
+} from '@lobu/connector-sdk';
+
+const BRIDGE_ONLY =
+  'chrome runs only on a worker advertising capability "browser.debugger" (Owletto for Chrome).';
+
+const tabIdSchema = {
+  type: 'integer',
+  description: 'Tab to act on. Defaults to the run-scoped scratch tab.',
+} as const;
+
+const refIdSchema = {
+  type: 'object',
+  required: ['document_epoch', 'ref_id'],
+  properties: {
+    document_epoch: { type: 'integer' },
+    ref_id: { type: 'integer' },
+  },
+  description:
+    'Element reference returned by a prior get_accessibility_tree call on the same tab + document. frame_id is reserved for future iframe support; v1 dispatches against the main frame.',
+} as const;
+
+export default class ChromeConnector extends ConnectorRuntime {
+  readonly definition: ConnectorDefinition = {
+    key: 'chrome',
+    name: 'Chrome',
+    description:
+      'Paired Chrome profile. Tab snapshots + a fixed set of typed browser actions (navigate, click, type, wait, screenshot, accessibility snapshot, evaluate) that connectors compose without shipping per-connector code into the extension.',
+    version: '0.2.0',
+    faviconDomain: 'google.com',
+    requiredCapability: 'browser.debugger',
+    runtime: { platforms: ['chrome-extension'] as unknown as ['macos'] },
+    authSchema: { methods: [{ type: 'none' }] },
+    feeds: {
+      open_tabs: {
+        key: 'open_tabs',
+        name: 'Open tabs',
+        description: 'Snapshot of the tabs currently open in this Chrome profile.',
+        configSchema: { type: 'object', properties: {} },
+        eventKinds: {
+          tab_snapshot: {
+            description: 'One row per tab observed in the active poll cycle.',
+            metadataSchema: {
+              type: 'object',
+              required: ['source', 'origin_id', 'url'],
+              properties: {
+                source: { type: 'string', const: 'chrome_tabs' },
+                origin_id: { type: 'string' },
+                url: { type: 'string', format: 'uri' },
+                title: { type: 'string' },
+                window_id: { type: 'integer' },
+                active: { type: 'boolean' },
+              },
+            },
+          },
+        },
+      },
+      tab_events: {
+        key: 'tab_events',
+        name: 'Tab events',
+        description:
+          'Live stream of tab creates / closes / URL changes / focus changes. Each event has a timestamp, so this is the lossless "browsing timeline" companion to the open_tabs snapshot. No extra permission required (baseline `tabs`).',
+        configSchema: { type: 'object', properties: {} },
+        eventKinds: {
+          tab_event: {
+            description:
+              'One row per tab lifecycle event. event_type is one of: created, removed, updated, activated.',
+            metadataSchema: {
+              type: 'object',
+              required: ['source', 'origin_id', 'event_type'],
+              properties: {
+                source: { type: 'string', const: 'chrome_tab_events' },
+                origin_id: { type: 'string' },
+                event_type: {
+                  enum: ['created', 'removed', 'updated', 'activated'],
+                },
+                tab_id: { type: 'integer' },
+                url: { type: 'string' },
+                title: { type: 'string' },
+                window_id: { type: 'integer' },
+                from_url: {
+                  type: 'string',
+                  description: 'For updated events, the URL the tab was on before the change.',
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+    actions: {
+      navigate: {
+        key: 'navigate',
+        name: 'Navigate',
+        description: 'Open a URL in a fresh background tab (default) or an existing tab.',
+        requiresApproval: false,
+        inputSchema: {
+          type: 'object',
+          required: ['url'],
+          properties: {
+            url: { type: 'string', format: 'uri' },
+            tab_id: tabIdSchema,
+            open_in_new_tab: {
+              type: 'boolean',
+              description: 'Default true. Opt out for active-tab control.',
+            },
+            wait_for_load: {
+              type: 'boolean',
+              description:
+                'Wait for Page.frameStoppedLoading on the main frame before returning. Default true.',
+            },
+          },
+        },
+        outputSchema: {
+          type: 'object',
+          properties: {
+            tab_id: { type: 'integer' },
+            current_url: { type: 'string' },
+            title: { type: 'string' },
+          },
+        },
+      },
+      get_accessibility_tree: {
+        key: 'get_accessibility_tree',
+        name: 'Get accessibility tree',
+        description:
+          'Return a structured snapshot of the visible interactive elements on the page, with stable refs for click_ref/type_ref. Sensitive fields are redacted.',
+        requiresApproval: false,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            tab_id: tabIdSchema,
+            filter: {
+              enum: ['interactive', 'visible', 'all'],
+              description: 'Default "interactive". "all" is for debugging only.',
+            },
+          },
+        },
+        outputSchema: {
+          type: 'object',
+          properties: {
+            document_epoch: { type: 'integer' },
+            current_url: { type: 'string' },
+            title: { type: 'string' },
+            tree: { type: 'array' },
+          },
+        },
+      },
+      click_ref: {
+        key: 'click_ref',
+        name: 'Click element by ref',
+        description:
+          'Dispatch a mouse click on the element identified by a ref from a prior accessibility snapshot of the same tab + document.',
+        requiresApproval: false,
+        inputSchema: {
+          type: 'object',
+          required: ['ref'],
+          properties: {
+            ref: refIdSchema,
+            tab_id: tabIdSchema,
+            button: {
+              enum: ['left', 'right', 'middle'],
+              description: 'Default "left".',
+            },
+            click_count: {
+              type: 'integer',
+              minimum: 1,
+              maximum: 3,
+              description: 'Default 1. Use 2 for double-click, 3 for triple-click.',
+            },
+          },
+        },
+      },
+      type_ref: {
+        key: 'type_ref',
+        name: 'Type into element by ref',
+        description:
+          'Focus the element identified by a ref and dispatch keystrokes to enter the given text. Existing value is replaced by default.',
+        requiresApproval: false,
+        inputSchema: {
+          type: 'object',
+          required: ['ref', 'text'],
+          properties: {
+            ref: refIdSchema,
+            tab_id: tabIdSchema,
+            text: { type: 'string' },
+            clear_first: {
+              type: 'boolean',
+              description: 'Default true. Selects all + deletes before typing.',
+            },
+          },
+        },
+      },
+      wait_for_selector: {
+        key: 'wait_for_selector',
+        name: 'Wait for selector',
+        description:
+          'Poll the page for the first match of a CSS selector and return when it appears.',
+        requiresApproval: false,
+        inputSchema: {
+          type: 'object',
+          required: ['selector'],
+          properties: {
+            selector: { type: 'string' },
+            tab_id: tabIdSchema,
+            timeout_ms: {
+              type: 'integer',
+              minimum: 100,
+              maximum: 60_000,
+              description: 'Default 10000.',
+            },
+          },
+        },
+      },
+      screenshot: {
+        key: 'screenshot',
+        name: 'Screenshot',
+        description: 'Capture the visible viewport as a PNG.',
+        requiresApproval: false,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            tab_id: tabIdSchema,
+          },
+        },
+        outputSchema: {
+          type: 'object',
+          properties: {
+            data_url: {
+              type: 'string',
+              description: 'data:image/png;base64,... — caller decodes.',
+            },
+            width: { type: 'integer' },
+            height: { type: 'integer' },
+          },
+        },
+      },
+      close_tab: {
+        key: 'close_tab',
+        name: 'Close tab',
+        description:
+          'Close a tab the extension created for this connector. Required at the end of any multi-step session — tabs the extension owned across navigate / get_accessibility_tree / click_ref / etc. are NOT auto-disposed (that would break the natural flow). A reaper closes orphaned owned tabs after 30 minutes.',
+        requiresApproval: false,
+        inputSchema: {
+          type: 'object',
+          required: ['tab_id'],
+          properties: { tab_id: { type: 'integer' } },
+        },
+      },
+      evaluate: {
+        key: 'evaluate',
+        name: 'Evaluate JS',
+        description:
+          'Last-resort escape hatch: run a JS expression with Runtime.evaluate and return the JSON-serialised result. Prefer ref-based actions when possible — scripts are harder to audit.',
+        requiresApproval: false,
+        inputSchema: {
+          type: 'object',
+          required: ['expression'],
+          properties: {
+            expression: { type: 'string' },
+            tab_id: tabIdSchema,
+            await_promise: {
+              type: 'boolean',
+              description: 'Default true.',
+            },
+          },
+        },
+        outputSchema: {
+          type: 'object',
+          properties: {
+            value: {},
+            exception: { type: 'string' },
+          },
+        },
+      },
+    },
+  };
+
+  async sync(_ctx: SyncContext): Promise<SyncResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+
+  async execute(): Promise<ActionResult> {
+    throw new Error(BRIDGE_ONLY);
+  }
+}