pi-web-access 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -2,7 +2,65 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [0.7.0] - 2026-02-03
+
+### Added
+- **Multi-provider web search**: `web_search` now supports Perplexity, Gemini API (with Google Search grounding), and Gemini Web (cookie auth) as search providers. New `provider` parameter (`auto`, `perplexity`, `gemini`) controls selection. In `auto` mode (default): Perplexity → Gemini API → Gemini Web. Backwards-compatible — existing Perplexity users see no change.
+- **Gemini API grounded search**: Structured citations via `groundingMetadata` with source URIs and text-to-source mappings. Google proxy URLs are resolved via HEAD redirects. Configured via `GEMINI_API_KEY` or `geminiApiKey` in config.
+- **Gemini Web search**: Zero-config web search for users signed into Google in Chrome. Prompt instructs Gemini to cite sources; URLs extracted from markdown response.
+- **Gemini extraction fallback**: When `fetch_content` fails (HTTP 403/429, Readability fails, network errors), automatically retries via Gemini URL Context API then Gemini Web extraction. Each has an independent 60s timeout. Handles SPAs, JS-heavy pages, and anti-bot protections.
+- **Local video file analysis**: `fetch_content` accepts file paths to video files (MP4, MOV, WebM, AVI, etc.). Detected by path prefix (`/`, `./`, `../`, `file://`), validated by extension and 50MB limit. Two-tier fallback: Gemini API (resumable upload via Files API with proper MIME types, poll-until-active and cleanup) → Gemini Web (free, cookie auth).
+- **Video prompt parameter**: `fetch_content` gains optional `prompt` parameter for asking specific questions about video content. Threads through YouTube and local video extraction. Without prompt, uses default extraction (transcript + visual descriptions).
+- **Video thumbnails**: YouTube results include the video thumbnail (fetched from `img.youtube.com`). Local video results include a frame extracted via ffmpeg (at ~1 second). Returned as image content parts alongside text — the agent sees the thumbnail as vision context.
+- **Configurable frame extraction**: `frames` parameter (1-12) on `fetch_content` for pulling visual frames from YouTube or local video. Works in five modes: frames alone (sample across entire video), single timestamp (one frame), single+frames (N frames at 5s intervals), range (default 6 frames), range+frames (N frames across the range). Endpoint-inclusive distribution with 5-second minimum spacing.
+- **Video duration in responses**: Frame extraction results include the video duration for context.
+- `searchProvider` config option in `~/.pi/web-search.json` for global provider default
+- `video` config section: `enabled`, `preferredModel`, `maxSizeMB`
+
+### Changed
+- `PerplexityResponse` renamed to `SearchResponse` (shared interface for all search providers)
+- Extracted HTTP pipeline from `extractContent` into `extractViaHttp` for cleaner Gemini fallback orchestration
+- `getApiKey()`, `API_BASE`, `DEFAULT_MODEL` exported from `gemini-api.ts` for use by search and URL Context modules
+- `isPerplexityAvailable()` added to `perplexity.ts` as non-throwing API key check
+- Content-type routing in `extract.ts`: only `text/html` and `application/xhtml+xml` go through Readability; all other text types (`text/markdown`, `application/json`, `text/csv`, etc.) returned directly. Fixes the OpenAI cookbook `.md` URL that returned "Untitled (30 chars)".
+- Title extraction for non-HTML content: `extractTextTitle()` pulls from markdown `#`/`##` headings, falls back to URL filename
+- Combined `yt-dlp --print duration -g` call fetches stream URL and duration in a single invocation, reused across all frame extraction paths via `streamInfo` passthrough
+- Shared helpers in `utils.ts` (`formatSeconds`, error mapping) eliminate circular imports and duplication across youtube-extract.ts and video-extract.ts
+
+### Fixed
+- `fetch_content` TUI rendered `undefined/undefined URLs` during progress updates (renderResult didn't handle `isPartial`, now shows a progress bar like `web_search` does)
+- RSC extractor produced malformed markdown for `<pre><code>` blocks (backticks inside fenced code blocks) -- extremely common on Next.js documentation pages
+- Multi-URL fetch failures rendered in green "success" color even when 0 URLs succeeded (now red)
+- `web_search` queries parameter described as "parallel" in schema but execution is sequential (changed to "batch"; `urls` correctly remains "parallel")
+- Proper error propagation for frame extraction: missing binaries (yt-dlp, ffmpeg, ffprobe), private/age-restricted/region-blocked videos, expired stream URLs (403), timestamp-exceeds-duration, and timeouts all produce specific user-facing messages instead of silent nulls
+- `isTimeoutError` now detects `execFileSync` timeouts via the `killed` flag (SIGTERM from timeout was previously unrecognized)
+- Float video durations (e.g. 15913.7s from yt-dlp) no longer produce out-of-range timestamps — durations are floored before computing frame positions
+- `parseTimestamp` consistently floors results across both bare-number ("90.5" → 90) and colon ("1:30.5" → 90) paths — previously the colon path returned floats
+- YouTube thumbnail assignment no longer sets `null` on the optional `thumbnail` field when fetch fails (was a type mismatch; now only assigned on success)
+
+### New files
+- `gemini-search.ts` -- search routing + Gemini Web/API search providers with grounding
+- `gemini-url-context.ts` -- URL Context API extraction + Gemini Web extraction fallback
+- `video-extract.ts` -- local video file detection, Gemini Web/API analysis with Files API upload
+- `utils.ts` -- shared formatting and error helpers for frame extraction
+
+## [0.6.0] - 2026-02-02
+
+### Added
+- YouTube video understanding in `fetch_content` via three-tier fallback chain:
+  - **Gemini Web** (primary): reads Chrome session cookies from macOS Keychain + SQLite, authenticates to gemini.google.com, sends YouTube URL via StreamGenerate endpoint. Full visual + audio understanding with timestamps. Zero config needed if signed into Google in Chrome.
+  - **Gemini API** (secondary): direct REST calls with `GEMINI_API_KEY`. YouTube URLs passed as `file_data.file_uri`. Configure via `GEMINI_API_KEY` env var or `geminiApiKey` in `~/.pi/web-search.json`.
+  - **Perplexity** (fallback): uses existing `searchWithPerplexity` for a topic summary when neither Gemini path is available. Output labeled as "Summary (via Perplexity)" so the agent knows it's not a full transcript.
+- YouTube URL detection for all common formats: `/watch?v=`, `youtu.be/`, `/shorts/`, `/live/`, `/embed/`, `/v/`, `m.youtube.com`
+- Configurable via `~/.pi/web-search.json` under `youtube` key (`enabled`, `preferredModel`)
+- Actionable error messages when extraction fails (directs user to sign into Chrome or set API key)
+- YouTube URLs no longer fall through to HTTP/Readability (which returns garbage); returns error instead
+
+### New files
+- `chrome-cookies.ts` -- macOS Chrome cookie extraction using Node builtins (`node:crypto`, `node:sqlite`, `child_process`)
+- `gemini-web.ts` -- Gemini Web client ported from surf's gemini-client.cjs (cookie auth, StreamGenerate, model fallback)
+- `gemini-api.ts` -- Gemini REST API client (generateContent, file upload/processing/cleanup for Phase 2)
+- `youtube-extract.ts` -- YouTube extraction orchestrator with three-tier fallback and activity logging
 
 ## [0.5.1] - 2026-02-02
 

package/README.md

@@ -4,7 +4,7 @@
 
 # Pi Web Access
 
-An extension for [Pi coding agent](https://github.com/badlogic/pi-mono/) that gives Pi web capabilities: search via Perplexity AI, fetch and extract content from URLs, clone GitHub repos for local exploration, and read PDFs.
+An extension for [Pi coding agent](https://github.com/badlogic/pi-mono/) that gives Pi web capabilities: search via Perplexity AI or Gemini, fetch and extract content from URLs, clone GitHub repos for local exploration, read PDFs, understand YouTube videos, and analyze local video files.
 
 ```typescript
 web_search({ query: "TypeScript best practices 2025" })
@@ -17,31 +17,42 @@ fetch_content({ url: "https://docs.example.com/guide" })
 pi install npm:pi-web-access
 ```
 
-Add your Perplexity API key:
+Configure at least one search provider:
 
 ```bash
-# Option 1: Environment variable
-export PERPLEXITY_API_KEY="pplx-..."
+# Option 1: Sign into gemini.google.com in Chrome (free, zero config)
 
-# Option 2: Config file
+# Option 2: Gemini API key
+echo '{"geminiApiKey": "AIza..."}' > ~/.pi/web-search.json
+
+# Option 3: Perplexity API key
 echo '{"perplexityApiKey": "pplx-..."}' > ~/.pi/web-search.json
 ```
 
-Get a key at https://perplexity.ai/settings/api
+All three work simultaneously. In `auto` mode (default), the extension tries Perplexity first, then Gemini API, then Gemini Web.
 
 **Requires:** Pi v0.37.3+
 
+**Optional dependencies** for video frame extraction:
+
+```bash
+brew install ffmpeg   # frame extraction, video thumbnails, local video duration
+brew install yt-dlp   # YouTube frame extraction (stream URL + duration lookup)
+```
+
+Without these, video content analysis (transcripts via Gemini) still works. The binaries are only needed for extracting visual frames from videos. `ffprobe` (bundled with ffmpeg) is used for local video duration lookup when sampling frames across an entire video.
+
 ## Tools
 
 ### web_search
 
-Search the web via Perplexity AI. Returns synthesized answer with source citations.
+Search the web via Perplexity AI or Gemini. Returns synthesized answer with source citations.
 
 ```typescript
 // Single query
 web_search({ query: "rust async programming" })
 
-// Multiple queries (parallel)
+// Multiple queries (batch)
 web_search({ queries: ["query 1", "query 2"] })
 
 // With options
@@ -52,12 +63,17 @@ web_search({
   domainFilter: ["github.com"] // Prefix with - to exclude
 })
 
+// Explicit provider
+web_search({ query: "...", provider: "gemini" })  // auto, perplexity, gemini
+
 // Fetch full page content (async)
 web_search({ query: "...", includeContent: true })
 ```
 
 When `includeContent: true`, sources are fetched in the background. Agent receives notification when ready.
 
+Provider selection in `auto` mode: Perplexity (if key configured) → Gemini API (if key configured, uses Google Search grounding) → Gemini Web (if signed into Chrome). Gemini API returns structured citations with source mappings. Gemini Web returns markdown with embedded links.
+
 ### fetch_content
 
 Fetch URL(s) and extract readable content as markdown.
@@ -93,6 +109,63 @@ fetch_content({ url: "https://github.com/big/repo", forceClone: true })
 
 Repos over 350MB get a lightweight API-based view instead of a full clone. Commit SHA URLs are also handled via the API. Clones are cached for the session -- multiple files from the same repo share one clone, but clones are wiped on session change/shutdown and re-cloned as needed.
 
+**YouTube videos:** YouTube URLs are automatically detected and processed via Gemini for full video understanding (visual + audio + transcript). Three-tier fallback:
+
+```typescript
+// Returns transcript with timestamps, visual descriptions, chapter markers
+fetch_content({ url: "https://youtube.com/watch?v=dQw4w9WgXcQ" })
+
+// Ask a specific question about the video
+fetch_content({ url: "https://youtube.com/watch?v=abc", prompt: "What libraries are imported?" })
+```
+
+1. **Gemini Web** (primary) -- reads your Chrome session cookies. Zero config if you're signed into Google.
+2. **Gemini API** (secondary) -- uses `GEMINI_API_KEY` env var or `geminiApiKey` in config.
+3. **Perplexity** (fallback) -- topic summary when neither Gemini path is available.
+
+YouTube results include the video thumbnail as an image content part, so the agent receives visual context alongside the transcript.
+
+Handles all YouTube URL formats: `/watch?v=`, `youtu.be/`, `/shorts/`, `/live/`, `/embed/`, `/v/`, `m.youtube.com`. Playlist-only URLs fall through to normal extraction.
+
+**Local video files:** Pass a file path to analyze video content via Gemini. Supports MP4, MOV, WebM, AVI, and other common formats. Max 50MB (configurable).
+
+```typescript
+// Analyze a screen recording
+fetch_content({ url: "/path/to/recording.mp4" })
+
+// Ask about specific content in the video
+fetch_content({ url: "./demo.mov", prompt: "What error message appears on screen?" })
+```
+
+Two-tier fallback: Gemini API (needs key, proper Files API with MIME types) → Gemini Web (free, needs Chrome login). File paths are detected by prefix (`/`, `./`, `../`, `file://`). If ffmpeg is installed, a frame from the video is included as a thumbnail image alongside the analysis.
+
+**Video frame extraction (YouTube + local):** Use `timestamp` and/or `frames` to pull visuals for scanning.
+
+```typescript
+// Single frame at an exact time
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41" })
+
+// Range scan (default 6 frames)
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00" })
+
+// Custom density across a range
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00", frames: 3 })
+
+// N frames at 5s intervals starting from a single timestamp
+fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41", frames: 5 })
+
+// Whole-video sampling (no timestamp)
+fetch_content({ url: "https://youtube.com/watch?v=abc", frames: 6 })
+```
+
+The same `timestamp`/`frames` syntax works with local file paths (e.g. `/path/to/video.mp4`).
+
+Requirements: YouTube frame extraction needs `yt-dlp` + `ffmpeg`. Local video frames need `ffmpeg` (and `ffprobe`, bundled with ffmpeg, for whole-video sampling).
+
+Common errors include missing binaries, private/age-restricted videos, region blocks, live streams, expired stream URLs (403), and timestamps beyond the video duration.
+
+**Gemini extraction fallback:** When Readability fails or a site blocks bot traffic (403, 429), the extension automatically retries via Gemini URL Context (API) or Gemini Web. This handles SPAs, JS-heavy pages, and anti-bot protections that the HTTP pipeline can't.
+
 **PDF handling:** When fetching a PDF URL, the extension extracts text and saves it as a markdown file in `~/Downloads/`. The agent can then use `read` to access specific sections without loading 200K+ chars into context.
 
 ### get_search_content
@@ -161,7 +234,11 @@ Browse stored search results interactively.
 ### fetch_content routing
 
 ```
-fetch_content(url)
+fetch_content(url_or_path, prompt?)
+       │
+       ├── Local video file? ──→ Gemini API → Gemini Web
+       │                              ↓
+       │                         Video analysis (prompt forwarded)
        │
        ├── github.com code URL? ──→ Clone repo (gh/git --depth 1)
        │                                    │
@@ -177,30 +254,41 @@ fetch_content(url)
        │                           Return content + local
        │                           path for read/bash
        │
+       ├── YouTube URL? ──→ Gemini Web → Gemini API → Perplexity
+       │                         ↓              (prompt forwarded)
+       │                    Transcript + visual descriptions
+       │
        ├── PDF? ──→ unpdf → Save to ~/Downloads/
        │
-       ├── Plain text? ──→ Return directly
+       ├── Plain text/markdown/JSON? ──→ Return directly
        │
        └── HTML ──→ Readability → Markdown
                          │
                     [if fails]
                          ↓
                     RSC Parser → Markdown
+                         │
+                    [if all fail]
+                         ↓
+                    Gemini URL Context → Gemini Web extraction
 ```
 
-### web_search with includeContent
+### web_search routing
 
 ```
-Agent Request → Perplexity API → Synthesized Answer + Citations
-                                         ↓
-                              [if includeContent: true]
-                                         ↓
-                              Background Fetch (3 concurrent)
-                              (uses same routing as above)
-                                         ↓
-                              Agent Notification (triggerTurn)
+web_search(query, provider?)
+       │
+       ├── provider = "perplexity" ──→ Perplexity API
+       ├── provider = "gemini"     ──→ Gemini API → Gemini Web
+       └── provider = "auto"
+              ├── Perplexity key? ──→ Perplexity API
+              ├── Gemini API key? ──→ Gemini API (grounded search)
+              ├── Chrome cookies? ──→ Gemini Web (grounded search)
+              └── Error
 ```
 
+When `includeContent: true`, sources are fetched in the background using the fetch_content routing above, and the agent receives a notification when ready.
+
 ## Configuration
 
 All config lives in `~/.pi/web-search.json`:
@@ -208,16 +296,29 @@ All config lives in `~/.pi/web-search.json`:
 ```json
 {
   "perplexityApiKey": "pplx-...",
+  "geminiApiKey": "AIza...",
+  "searchProvider": "auto",
   "githubClone": {
     "enabled": true,
     "maxRepoSizeMB": 350,
     "cloneTimeoutSeconds": 30,
     "clonePath": "/tmp/pi-github-repos"
+  },
+  "youtube": {
+    "enabled": true,
+    "preferredModel": "gemini-2.5-flash"
+  },
+  "video": {
+    "enabled": true,
+    "preferredModel": "gemini-2.5-flash",
+    "maxSizeMB": 50
   }
 }
 ```
 
-All `githubClone` fields are optional with the defaults shown above. Set `"enabled": false` to disable GitHub cloning entirely and fall through to normal HTML extraction.
+All fields are optional. `GEMINI_API_KEY` and `PERPLEXITY_API_KEY` env vars take precedence over config file values. Set `"enabled": false` under `githubClone`, `youtube`, or `video` to disable those features.
+
+`searchProvider` controls `web_search` default: `"auto"` (Perplexity → Gemini API → Gemini Web), `"perplexity"`, or `"gemini"` (API → Web).
 
 ## Rate Limits
 
@@ -231,7 +332,15 @@ All `githubClone` fields are optional with the defaults shown above. Set `"enabl
 |------|---------|
 | `index.ts` | Extension entry, tool definitions, commands, widget |
 | `perplexity.ts` | Perplexity API client, rate limiting |
-| `extract.ts` | URL fetching, content extraction routing |
+| `gemini-search.ts` | Gemini search providers (Web + API with grounding), search routing |
+| `extract.ts` | URL/file path routing, HTTP extraction, Gemini fallback orchestration |
+| `gemini-url-context.ts` | Gemini URL Context + Web extraction fallbacks |
+| `video-extract.ts` | Local video file detection, upload, Gemini Web/API analysis |
+| `youtube-extract.ts` | YouTube URL detection, three-tier extraction orchestrator |
+| `chrome-cookies.ts` | macOS Chrome cookie extraction (Keychain + SQLite) |
+| `gemini-web.ts` | Gemini Web client (cookie auth, StreamGenerate) |
+| `gemini-api.ts` | Gemini REST API client (generateContent, file upload) |
+| `utils.ts` | Shared formatting (`formatSeconds`) and error helpers for frame extraction |
 | `github-extract.ts` | GitHub URL parser, clone cache, content generation |
 | `github-api.ts` | GitHub API fallback for oversized repos and commit SHAs |
 | `pdf-extract.ts` | PDF text extraction, saves to markdown |
@@ -242,12 +351,16 @@ All `githubClone` fields are optional with the defaults shown above. Set `"enabl
 
 ## Limitations
 
-- Content extraction works best on article-style pages
-- Heavy JS sites may not extract well (no browser rendering), though Next.js App Router pages with RSC flight data are supported
+- Content extraction works best on article-style pages; JS-heavy sites fall back to Gemini extraction when available
+- Gemini extraction fallback requires either a Gemini API key or Chrome login to Google
 - PDFs are extracted as text (no OCR for scanned documents)
 - Max response size: 20MB for PDFs, 5MB for HTML
 - Max inline content: 30,000 chars per URL (larger content stored for retrieval via get_search_content)
 - GitHub cloning requires `gh` CLI for private repos (public repos fall back to `git clone`)
 - GitHub branch names with slashes (e.g. `feature/foo`) may resolve the wrong file path; the clone still succeeds and the agent can navigate manually
 - Non-code GitHub URLs (issues, PRs, wiki, etc.) fall through to normal Readability extraction
+- YouTube extraction via Gemini Web requires macOS (Chrome cookie decryption is OS-specific); other platforms fall through to Gemini API or Perplexity
+- YouTube private/age-restricted videos may fail on all paths
+- Gemini can process videos up to ~1 hour at default resolution; longer videos may be truncated
+- First-time Chrome cookie access may trigger a macOS Keychain permission dialog
 - Requires Pi restart after config file changes

package/chrome-cookies.ts

@@ -0,0 +1,240 @@
+import { execFile } from "node:child_process";
+import { pbkdf2Sync, createDecipheriv } from "node:crypto";
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir, homedir, platform } from "node:os";
+import { join } from "node:path";
+
+export type CookieMap = Record<string, string>;
+
+const GOOGLE_ORIGINS = [
+	"https://gemini.google.com",
+	"https://accounts.google.com",
+	"https://www.google.com",
+];
+
+const ALL_COOKIE_NAMES = new Set([
+	"__Secure-1PSID",
+	"__Secure-1PSIDTS",
+	"__Secure-1PSIDCC",
+	"__Secure-1PAPISID",
+	"NID",
+	"AEC",
+	"SOCS",
+	"__Secure-BUCKET",
+	"__Secure-ENID",
+	"SID",
+	"HSID",
+	"SSID",
+	"APISID",
+	"SAPISID",
+	"__Secure-3PSID",
+	"__Secure-3PSIDTS",
+	"__Secure-3PAPISID",
+	"SIDCC",
+]);
+
+const CHROME_COOKIES_PATH = join(
+	homedir(),
+	"Library/Application Support/Google/Chrome/Default/Cookies",
+);
+
+export async function getGoogleCookies(): Promise<{ cookies: CookieMap; warnings: string[] } | null> {
+	if (platform() !== "darwin") return null;
+	if (!existsSync(CHROME_COOKIES_PATH)) return null;
+
+	const warnings: string[] = [];
+
+	const password = await readKeychainPassword();
+	if (!password) {
+		warnings.push("Could not read Chrome Safe Storage password from Keychain");
+		return { cookies: {}, warnings };
+	}
+
+	const key = pbkdf2Sync(password, "saltysalt", 1003, 16, "sha1");
+	const tempDir = mkdtempSync(join(tmpdir(), "pi-chrome-cookies-"));
+
+	try {
+		const tempDb = join(tempDir, "Cookies");
+		copyFileSync(CHROME_COOKIES_PATH, tempDb);
+		copySidecar(CHROME_COOKIES_PATH, tempDb, "-wal");
+		copySidecar(CHROME_COOKIES_PATH, tempDb, "-shm");
+
+		const metaVersion = await readMetaVersion(tempDb);
+		const stripHash = metaVersion >= 24;
+
+		const hosts = GOOGLE_ORIGINS.map((o) => new URL(o).hostname);
+		const rows = await queryCookieRows(tempDb, hosts);
+		if (!rows) {
+			warnings.push("Failed to query Chrome cookie database");
+			return { cookies: {}, warnings };
+		}
+
+		const cookies: CookieMap = {};
+		for (const row of rows) {
+			const name = row.name as string;
+			if (!ALL_COOKIE_NAMES.has(name)) continue;
+			if (cookies[name]) continue;
+
+			let value = typeof row.value === "string" && row.value.length > 0 ? row.value : null;
+			if (!value) {
+				const encrypted = row.encrypted_value;
+				if (encrypted instanceof Uint8Array) {
+					value = decryptCookieValue(encrypted, key, stripHash);
+				}
+			}
+			if (value) cookies[name] = value;
+		}
+
+		return { cookies, warnings };
+	} finally {
+		rmSync(tempDir, { recursive: true, force: true });
+	}
+}
+
+function decryptCookieValue(encrypted: Uint8Array, key: Buffer, stripHash: boolean): string | null {
+	const buf = Buffer.from(encrypted);
+	if (buf.length < 3) return null;
+
+	const prefix = buf.subarray(0, 3).toString("utf8");
+	if (!/^v\d\d$/.test(prefix)) return null;
+
+	const ciphertext = buf.subarray(3);
+	if (!ciphertext.length) return "";
+
+	try {
+		const iv = Buffer.alloc(16, 0x20);
+		const decipher = createDecipheriv("aes-128-cbc", key, iv);
+		decipher.setAutoPadding(false);
+		const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+		const unpadded = removePkcs7Padding(plaintext);
+		const bytes = stripHash && unpadded.length >= 32 ? unpadded.subarray(32) : unpadded;
+		const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		let i = 0;
+		while (i < decoded.length && decoded.charCodeAt(i) < 0x20) i++;
+		return decoded.slice(i);
+	} catch {
+		return null;
+	}
+}
+
+function removePkcs7Padding(buf: Buffer): Buffer {
+	if (!buf.length) return buf;
+	const padding = buf[buf.length - 1];
+	if (!padding || padding > 16) return buf;
+	return buf.subarray(0, buf.length - padding);
+}
+
+function readKeychainPassword(): Promise<string | null> {
+	return new Promise((resolve) => {
+		execFile(
+			"security",
+			["find-generic-password", "-w", "-a", "Chrome", "-s", "Chrome Safe Storage"],
+			{ timeout: 5000 },
+			(err, stdout) => {
+				if (err) { resolve(null); return; }
+				resolve(stdout.trim() || null);
+			},
+		);
+	});
+}
+
+let sqliteModule: typeof import("node:sqlite") | null = null;
+
+async function importSqlite(): Promise<typeof import("node:sqlite") | null> {
+	if (sqliteModule) return sqliteModule;
+	const orig = process.emitWarning.bind(process);
+	process.emitWarning = ((warning: string | Error, ...args: unknown[]) => {
+		const msg = typeof warning === "string" ? warning : warning?.message ?? "";
+		if (msg.includes("SQLite is an experimental feature")) return;
+		return (orig as Function)(warning, ...args);
+	}) as typeof process.emitWarning;
+	try {
+		sqliteModule = await import("node:sqlite");
+		return sqliteModule;
+	} catch {
+		return null;
+	} finally {
+		process.emitWarning = orig;
+	}
+}
+
+function supportsReadBigInts(): boolean {
+	const [major, minor] = process.versions.node.split(".").map(Number);
+	if (major > 24) return true;
+	if (major < 24) return false;
+	return minor >= 4;
+}
+
+async function readMetaVersion(dbPath: string): Promise<number> {
+	const sqlite = await importSqlite();
+	if (!sqlite) return 0;
+	const opts: Record<string, unknown> = { readOnly: true };
+	if (supportsReadBigInts()) opts.readBigInts = true;
+	const db = new sqlite.DatabaseSync(dbPath, opts);
+	try {
+		const rows = db.prepare("SELECT value FROM meta WHERE key = 'version'").all() as Array<Record<string, unknown>>;
+		const val = rows[0]?.value;
+		if (typeof val === "number") return Math.floor(val);
+		if (typeof val === "bigint") return Number(val);
+		if (typeof val === "string") return parseInt(val, 10) || 0;
+		return 0;
+	} catch {
+		return 0;
+	} finally {
+		db.close();
+	}
+}
+
+async function queryCookieRows(
+	dbPath: string,
+	hosts: string[],
+): Promise<Array<Record<string, unknown>> | null> {
+	const sqlite = await importSqlite();
+	if (!sqlite) return null;
+
+	const clauses: string[] = [];
+	for (const host of hosts) {
+		for (const candidate of expandHosts(host)) {
+			const esc = candidate.replaceAll("'", "''");
+			clauses.push(`host_key = '${esc}'`);
+			clauses.push(`host_key = '.${esc}'`);
+			clauses.push(`host_key LIKE '%.${esc}'`);
+		}
+	}
+	const where = clauses.join(" OR ");
+
+	const opts: Record<string, unknown> = { readOnly: true };
+	if (supportsReadBigInts()) opts.readBigInts = true;
+	const db = new sqlite.DatabaseSync(dbPath, opts);
+	try {
+		return db
+			.prepare(
+				`SELECT name, value, host_key, encrypted_value FROM cookies WHERE (${where}) ORDER BY expires_utc DESC`,
+			)
+			.all() as Array<Record<string, unknown>>;
+	} catch {
+		return null;
+	} finally {
+		db.close();
+	}
+}
+
+function expandHosts(host: string): string[] {
+	const parts = host.split(".").filter(Boolean);
+	if (parts.length <= 1) return [host];
+	const candidates = new Set<string>();
+	candidates.add(host);
+	for (let i = 1; i <= parts.length - 2; i++) {
+		const c = parts.slice(i).join(".");
+		if (c) candidates.add(c);
+	}
+	return Array.from(candidates);
+}
+
+function copySidecar(srcDb: string, targetDb: string, suffix: string): void {
+	const sidecar = `${srcDb}${suffix}`;
+	if (!existsSync(sidecar)) return;
+	try {
+		copyFileSync(sidecar, `${targetDb}${suffix}`);
+	} catch {}
+}