@haseebeqx/pi-safari 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haseeb Annadamban
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# pi-safari
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Six bounded Safari tools for Pi, backed by **Apple’s built-in local Safari MCP server**. The extension manages the MCP connection and launches `/usr/bin/safaridriver --mcp`, communicating over standard input/output.
+
+Already using an MCP-capable client? [You can also use Apple’s Safari MCP server directly, without this extension](#use-safari-mcp-directly-without-this-extension).
+
+## Requirements and installation
+
+- macOS with **Safari 27 or later** and Node **22.19+**.
+- In Safari → Settings → Advanced, enable **Show features for web developers**.
+- In Safari → Settings → Developer, enable **Allow remote automation and external agents**. Complete any connection approval Safari presents yourself.
+- Install from npm with `pi install npm:@haseebeqx/pi-safari`, then reload/restart Pi. For a local checkout, use `pi install /absolute/path/to/pi-safari` or try it temporarily with `pi -e ./src/index.ts` from this repository.
+- The package ships TypeScript source; no build step or separate MCP configuration is needed. Pi supplies its host dependencies. Development is checked against Pi 1.2.0; compatibility with every Pi version is not guaranteed.
+
+Enable Safari’s MCP automation permission as described above; the package leaves system settings unchanged. Fresh automation browsing state is supported and expected: do not rely on normal Safari tabs, profile cookies, or existing logins being available. Apple documents isolated windows for WebDriver; the exact scope exposed by MCP is managed by Safari and should not be inferred from a normal Safari window.
+
+Apple documents the integration in [Connecting an AI agent to Safari](https://developer.apple.com/documentation/safari-developer-tools/connecting-an-ai-agent-to-safari) and describes the [Safari MCP server](https://webkit.org/blog/18136/introducing-the-safari-mcp-server-for-web-developers/). Safari MCP runs locally; page observations passed to Pi may subsequently be sent to the model provider configured in Pi.
+
+## Tools
+
+- `safari_tabs {}` lists at most 100 tabs exposed by the automation session, returning `targetId` and `epoch`, plus available URL/title metadata. No page bodies.
+- `safari_open {"url":"https://example.com/"}` creates a **new automation tab**, waits up to approximately 12 seconds for the exact normalized URL to finish loading, and returns its target. Redirects and URL rewrites fail closed. Existing tabs are never navigated.
+- `safari_search {"query":"Safari automation","maxResults":5,"region":"us-en","time":"m"}` searches DuckDuckGo HTML in a **new tab** and returns ranked, deduplicated `{rank,title,url,snippet}` results plus the search URL, `truncated` and `cleanup` outcome (no reusable target). Defaults: 5 results, worldwide (`wt-wt`), any time. Limits: 1–500 query characters (no control characters), 1–10 results.
+- `safari_close {"targetId":"page-…","epoch":"…"}` closes exactly that automation tab, rejecting stale epochs. An absent tab returns `already-absent`; close is never retried.
+- `safari_read {"targetId":"page-…","epoch":"…","maxChars":8000,"maxLinks":20}` extracts body `innerText` and visible link hrefs from that explicit tab. Defaults are 8000 characters/20 links; maxima are 12000/40. Includes truncation flags.
+- `safari_follow_link {"targetId":"page-…","epoch":"…","expectedUrl":"https://example.com/","selector":"a.more"}` checks the exact source URL, extracts the href of exactly one visible matching `a[href]`, validates HTTP(S), and opens it in a **new tab**. It never invokes click handlers, submits forms, or navigates the source.
+
+Use the exact target and epoch returned by tabs/open; do not invent them. Read a page before following a CSS-selected link, and supply its returned source URL. Output is capped at 48 KiB of JSON; reduce read limits if escaping causes an oversized-result error.
+
+### Search controls and limitations
+
+`region` is one of `wt-wt`, `us-en`, `uk-en`, `ca-en`, `au-en`, `de-de`, `fr-fr`, `in-en`, `jp-jp`. It sets DuckDuckGo's `kl` region preference, not a strict country/language restriction. `time` is `any`, `d`, `w`, `m`, or `y` (past day/week/month/year), using the provider's `df` filter. Ranking and filter enforcement belong to DuckDuckGo; no custom sorting, arbitrary provider parameters, strict site restriction, safe-search override, or pagination is promised. Query operators can be typed as query text but their semantics are provider-controlled.
+
+The URL is constructed deterministically; no form is submitted and no result is clicked or fetched. Fixed selectors inspect the first 100 result containers, skip recognized ads/hidden or unsafe links, unwrap recognized DuckDuckGo result redirects, and deduplicate canonical URL strings. Ranks are contiguous provider DOM order after filtering, not independent relevance scores. Titles/snippets are limited to 300/600 characters, URLs to 2048. `truncated` means more eligible results or the 100-container scan bound was reached; text fields can also be shortened. Empty output does **not** prove no matches: challenges, blocked requests or changed provider markup may yield no recognized results. There is no challenge bypass or automatic retry. Redirects/URL rewrites fail closed, including provider changes. Search queries go to DuckDuckGo; returned content remains untrusted. No live provider test is part of the automated suite.
+
+### Tab lifecycle
+
+Open/follow operations leave tabs open until the agent calls `safari_close` (or you close them). Search automatically closes only the tab identified by its own create reply, after extracting results and on readiness/extraction failures. It returns `cleanup.status`: `closed`, `already-absent`, `failed`, `unidentified`, or `skipped-retired-epoch`. Search never returns a usable target. Errors retain the original failure as cause and append cleanup outcome.
+
+Cleanup has a separate three-second budget and may run after cancellation only while the original connection epoch remains current. An interrupted driver request retires its epoch; cleanup never reconnects using that old handle. A lost/malformed create reply can leave an unidentified tab; no list-difference guessing, create replay, or unrelated-tab closure is attempted. Failed/unconfirmed cleanup and retired connections may leave residual tabs: relist for manual cleanup before retrying. Shutdown stops the driver, not a tab-closing routine; Safari controls session teardown.
+
+Handles are scoped to a persistent driver connection. A disconnect, cancellation that interrupts a driver request, shutdown, or five minutes of inactivity retires that connection; relist tabs afterward. Do not reuse a saved epoch after reconnection.
+
+## Safety and limits
+
+The Pi-facing surface supports bounded read/extract/open/close. Internally the adapter allows just six Apple MCP tools: tab listing, tab creation, explicit tab switching, tab closing by handle, page information, and JavaScript evaluation with fixed package-generated read/readiness/link/search scripts. The model cannot supply JavaScript or invoke Apple’s broader interaction, navigation, screenshot, or network-inspection tools through this package. Extraction excludes frames and shadow roots. It does not modify source DOM, use identity markers, or claim ownership of pages.
+
+Operations are serialized per Pi extension instance, with a 20-second work deadline (plus up to three seconds for search cleanup), cancellation, a 256-KiB transport response limit, protocol negotiation, required-tool discovery and a `close_tab` input-schema check, and session-scoped handles. A failed or cancelled create is **never retried automatically**. A tab may already exist when a timeout is reported; inspect tabs before retrying. Failed opens and smoke tests leave their tabs open for manual inspection. Shutdown stops the driver process, not a sequence of tab-close commands; Safari controls its session lifecycle.
+
+Safari’s MCP extraction APIs operate on a current browsing context. The adapter selects an explicit handle before extraction and checks URLs and tab presence afterward. These are best-effort stale-read checks: same-URL reloads/replacements, a context switch to another page with the same URL, live DOM changes, or external interference may go undetected. Tab handles do not identify documents or authorize mutation. Concurrent independent Pi sessions are not coordinated by this package.
+
+Web content is untrusted data. Opening a URL can have server-side effects, including in accounts signed into within the automation session. Safari’s isolation does not make every visited website or requested action safe.
+
+## Development and verification
+
+```sh
+npm ci --ignore-scripts
+npm run check
+```
+
+`npm run check` runs the unit tests, TypeScript check and npm tarball dry-run assertions; it never starts Safari. The same checks run before `npm publish`. Host Pi and TypeBox packages are peer dependencies, also pinned as development dependencies for reproducible local checks. Automated tests mock the driver’s JSON-RPC stream and execute the actual extraction scripts in VM/DOM fixtures. They cover handshake compatibility, bounds, malformed replies, stale targets, cancellation, serialization, redirect rejection, and creation without replay.
+
+An explicit real-Safari smoke test opens two disposable local fixture tabs, exercises `safari_tabs`, `safari_open`, `safari_read` and `safari_follow_link` (not `safari_close` or external search), checks visibility and preservation of the source URL, and leaves the tabs open:
+
+```sh
+PI_SAFARI_LIVE_TEST=1 npm run test:safari
+```
+
+Requires informed manual enablement of Safari remote automation. It does not change settings, sign into sites, or navigate/close existing tabs. The local fixture server stops when the test finishes.
+
+### Validation boundaries
+
+Automated fixtures do not establish live Safari or DuckDuckGo reliability. The opt-in smoke test does not validate search or tab closing. Manual checks still needed for a release include clean permission setup/denial, Safari restart/disconnect and idle expiry, tab replacement/reordering, concurrent Pi clients, authentication within automation state, and Safari updates. Required-tool discovery does not validate every Apple tool schema; changes to Safari APIs or provider markup can break operations.
+
+## Use Safari MCP directly (without this extension)
+
+If your AI client supports local MCP servers over **stdio**, you can connect to Apple’s Safari MCP server without installing Pi or this extension.
+
+1. Use macOS with **Safari 27 or later** and enable both Safari developer settings listed in [Requirements and installation](#requirements-and-installation). Complete any Safari connection approval yourself.
+2. Add a server to your client’s MCP configuration with command `/usr/bin/safaridriver` and argument `--mcp`. For clients using the common `mcpServers` JSON format:
+
+   ```json
+   {
+     "mcpServers": {
+       "safari": {
+         "command": "/usr/bin/safaridriver",
+         "args": ["--mcp"]
+       }
+     }
+   }
+   ```
+
+3. Reload your client’s MCP configuration (or restart the client), then enable the Safari tools it discovers. Your client launches the server and manages the stdio connection; you do not need to run it separately in a terminal.
+
+Configuration file locations and formats vary by client; consult your client’s MCP setup instructions. Node and this npm package are not required for direct use. See Apple’s [Connecting an AI agent to Safari](https://developer.apple.com/documentation/safari-developer-tools/connecting-an-ai-agent-to-safari) for the official setup guide.
+
+Direct connections expose Apple’s tools, **not** this extension’s `safari_*` interface or its bounds and safety checks. Review your client’s tool permissions before allowing browser actions. Do not assume normal Safari tabs or logins are available; page content sent to your AI client may be forwarded to its model provider.
+
+## License
+
+[MIT](LICENSE).

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@haseebeqx/pi-safari",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Safari automation tools for Pi using Apple's built-in local MCP server",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "scripts/smoke.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "typebox": "1.3.27"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm test && npm run typecheck",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/extraction.ts

@@ -0,0 +1,26 @@
+export const MAX_OUTPUT = 48 * 1024;
+export function bound(value: unknown): string {
+  const text = JSON.stringify(value);
+  if (Buffer.byteLength(text) > MAX_OUTPUT) throw new Error('Safari output exceeded 48 KiB; request smaller limits.');
+  return text;
+}
+export function webURL(url: string): string {
+  const u = new URL(url);
+  if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password || url.length > 8192) throw new Error('Only HTTP(S) URLs without embedded credentials are allowed.');
+  return u.href;
+}
+
+export function readyJS(expectedUrl: string): string {
+  return `location.href===${JSON.stringify(expectedUrl)} && document.readyState==='complete'`;
+}
+// This script only extracts data. It never clicks, dispatches events, sets markers,
+// or navigates the source context, regardless of its provenance or replacement.
+export function linkJS(selector: string, expectedUrl: string): string {
+  if (selector.length < 1 || selector.length > 500) throw new Error('CSS selector must be 1..500 characters.');
+  webURL(expectedUrl);
+  return `JSON.stringify((()=>{if(location.href!==${JSON.stringify(expectedUrl)})throw Error('Page URL changed; read again');const es=document.querySelectorAll(${JSON.stringify(selector)});if(es.length!==1)throw Error('Selector must match exactly one element');const e=es[0];if(!e.matches('a[href]'))throw Error('Selector must match a link');if(!e.getClientRects().length||getComputedStyle(e).visibility!=='visible'||getComputedStyle(e).display==='none')throw Error('Link hidden');const u=new URL(e.href);if(!/^https?:$/.test(u.protocol)||u.username||u.password)throw Error('Only HTTP(S) links without credentials are allowed');return {href:u.href}})())`;
+}
+export function readJS(chars: number, links: number): string {
+  if (!Number.isInteger(chars) || chars < 1 || chars > 12000 || !Number.isInteger(links) || links < 0 || links > 40) throw new Error('maxChars must be 1..12000; maxLinks must be 0..40.');
+  return `JSON.stringify((()=>{const text=document.body?.innerText||''; const links=Array.from(document.querySelectorAll('a[href]')).filter(a=>a.getClientRects().length&&getComputedStyle(a).visibility==='visible'&&getComputedStyle(a).display!=='none'); return {url:location.href.slice(0,2048),title:document.title.slice(0,300),readyState:document.readyState,text:text.slice(0,${chars}),textTruncated:text.length>${chars},links:links.slice(0,${links}).map((a,index)=>({index,text:(a.innerText||a.textContent||'').slice(0,120),href:a.href.slice(0,1024)})),linksTruncated:links.length>${links}}})())`;
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+import { Type } from 'typebox';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Safari } from './safari.ts';
+import { bound } from './extraction.ts';
+import { REGIONS, TIMES } from './search.ts';
+
+const Target = {
+  targetId: Type.String({ minLength: 1, maxLength: 200, description: 'Opaque Safari tab handle from safari_tabs/open' }),
+  epoch: Type.String({ minLength: 1, maxLength: 100, description: 'Connection epoch returned with the target; relist after disconnect' }),
+};
+function result(data: unknown) {
+  return { content: [{ type: 'text' as const, text: bound(data) }], details: undefined };
+}
+export default function(pi: ExtensionAPI) {
+  const safari = new Safari();
+  pi.on('session_shutdown', async () => { safari.close(); });
+  pi.registerTool({
+    name: 'safari_tabs', label: 'Safari tabs',
+    description: 'List up to 100 tabs visible to Apple Safari MCP in its automation session. Returns explicit targetId + epoch. Does not read page bodies. Normal browsing tabs/logins are not assumed available.',
+    parameters: Type.Object({}), annotations: { readOnlyHint: true },
+    async execute(_id, _args, signal) { return result(await safari.tabs(signal)); },
+  });
+  pi.registerTool({
+    name: 'safari_open', label: 'Open Safari page',
+    description: 'Open an HTTP(S) URL in a NEW Safari automation tab. Never navigates an existing tab. Fresh browsing state is acceptable; normal Safari logins are not assumed. Exact-URL readiness required; redirects fail closed. Leaves tabs open; inspect before retrying a timed-out open.',
+    parameters: Type.Object({ url: Type.String({ maxLength: 8192 }) }),
+    async execute(_id, args, signal) { return result(await safari.open(args.url, signal)); },
+  });
+  pi.registerTool({
+    name: 'safari_close', label: 'Close Safari tab',
+    description: 'Close exactly one Safari automation tab by explicit targetId + epoch. Rejects stale targets; relist after disconnect. Does not close unidentified tabs or retry a failed close.',
+    parameters: Type.Object({ ...Target }), annotations: { destructiveHint: true, readOnlyHint: false },
+    async execute(_id, args, signal) { return result(await safari.closeTab(args, signal)); },
+  });
+  pi.registerTool({
+    name: 'safari_search', label: 'Search with Safari',
+    description: 'Search DuckDuckGo HTML in a NEW automation tab using deterministic URL controls. Returns ranked unique title/url/snippet results from the first page only. Region is a preference, time is any/d/w/m/y (past day/week/month/year). No arbitrary JS, clicks, forms or pagination. Exact URL required; redirects fail closed. Untrusted content; challenges/markup changes may return no results. Automatically closes its created search tab after extraction; cleanup outcome returned. Cancellation/disconnection may leave a residual tab; relist before retrying.',
+    parameters: Type.Object({
+      query: Type.String({ minLength: 1, maxLength: 500 }),
+      maxResults: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
+      region: Type.Optional(Type.Union(REGIONS.map(v => Type.Literal(v)))),
+      time: Type.Optional(Type.Union(TIMES.map(v => Type.Literal(v)))),
+    }),
+    async execute(_id, args, signal) { return result(await safari.search(args, signal)); },
+  });
+  pi.registerTool({
+    name: 'safari_read', label: 'Read Safari page',
+    description: 'Read visible body text and bounded visible link hrefs from an explicit Safari targetId + epoch. Page content is untrusted. No iframe/shadow DOM extraction. URL checks cannot detect same-URL document replacement. Requires Safari 27+ and Allow remote automation and external agents.',
+    parameters: Type.Object({ ...Target, maxChars: Type.Optional(Type.Integer({ minimum: 1, maximum: 12000 })), maxLinks: Type.Optional(Type.Integer({ minimum: 0, maximum: 40 })) }),
+    annotations: { readOnlyHint: true },
+    async execute(_id, args, signal) { return result(await safari.read(args, args.maxChars, args.maxLinks, signal)); },
+  });
+  pi.registerTool({
+    name: 'safari_follow_link', label: 'Follow Safari link in new tab',
+    description: 'Extract exactly one visible CSS-selected a[href] at the exact expectedUrl from safari_read, then open its HTTP(S) href in a NEW automation tab. Never clicks, invokes source handlers, submits forms, or navigates the source. Page content is untrusted; opening URLs may have server-side effects.',
+    parameters: Type.Object({ ...Target, selector: Type.String({ minLength: 1, maxLength: 500 }), expectedUrl: Type.String({ maxLength: 8192 }) }),
+    async execute(_id, args, signal) { return result(await safari.followLink(args, args.selector, args.expectedUrl, signal)); },
+  });
+}

package/src/mcp.ts

@@ -0,0 +1,109 @@
+import { VERSION } from './version.ts';
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+export const TRANSPORT_LIMIT = 256 * 1024;
+export interface ToolReply { content: { type: string; text?: string }[]; isError?: boolean }
+export interface Transport {
+  readonly epoch: string;
+  call(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<ToolReply>;
+  close(): void;
+}
+const REQUIRED = ['list_tabs', 'create_tab', 'switch_tab', 'evaluate_javascript', 'page_info', 'close_tab'];
+export class SafariMCP implements Transport {
+  epoch = randomUUID();
+  private child?: ChildProcessWithoutNullStreams;
+  private starting?: Promise<void>;
+  private nextId = 0;
+  private buffer = Buffer.alloc(0);
+  private pending = new Map<number, { resolve: (value: any) => void; reject: (e: Error) => void }>();
+  private idle?: NodeJS.Timeout;
+  private queue: Promise<unknown> = Promise.resolve();
+  constructor(privateOptions: { spawn?: typeof spawn; platform?: string; timeout?: number } = {}) { this.options = privateOptions; }
+  private options: { spawn?: typeof spawn; platform?: string; timeout?: number };
+  private stop(error = Error('Safari connection closed; relist tabs. Inspect tabs before retrying an open.')) {
+    const child = this.child; this.child = undefined; this.starting = undefined;
+    clearTimeout(this.idle); this.buffer = Buffer.alloc(0); this.epoch = randomUUID();
+    for (const p of this.pending.values()) p.reject(error); this.pending.clear();
+    child?.kill('SIGTERM');
+  }
+  close() { this.stop(); }
+  private async start() {
+    if (this.starting) return this.starting;
+    this.starting = (async () => {
+      if ((this.options.platform ?? process.platform) !== 'darwin') throw Error('Safari MCP requires macOS and Safari 27+.');
+      const child = (this.options.spawn ?? spawn)('/usr/bin/safaridriver', ['--mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
+      this.child = child;
+      // Keep the extension from holding Pi open; an idle connection is retired.
+      child.unref();
+      child.stdin.on('error', () => { if (this.child === child) this.stop(Error('Safari MCP input disconnected.')); });
+      child.stdout.on('error', () => { if (this.child === child) this.stop(Error('Safari MCP output disconnected.')); });
+      child.stderr.on('error', () => {});
+      child.stderr.on('data', () => {}); // Never log page or driver payloads.
+      child.on('error', () => { if (this.child === child) this.stop(Error('Cannot start Safari MCP. Requires Safari 27+ and Allow remote automation and external agents.')); });
+      child.on('exit', () => { if (this.child === child) this.stop(Error('Safari MCP disconnected; enable Allow remote automation and external agents, then relist tabs.')); });
+      child.stdout.on('data', (chunk: Buffer) => {
+        if (this.child !== child) return;
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        if (this.buffer.length > TRANSPORT_LIMIT) return this.stop(Error('Safari MCP response exceeded 256 KiB.'));
+        let end: number;
+        while ((end = this.buffer.indexOf(10)) !== -1) {
+          const line = this.buffer.subarray(0, end).toString('utf8'); this.buffer = this.buffer.subarray(end + 1);
+          if (!line.trim()) continue;
+          try {
+            const m = JSON.parse(line);
+            if (m.jsonrpc !== '2.0' || typeof m !== 'object') throw Error();
+            if (m.id === undefined) continue; // Server notifications.
+            const p = this.pending.get(m.id);
+            if (!p || (Object.hasOwn(m, 'result') === Object.hasOwn(m, 'error'))) throw Error();
+            this.pending.delete(m.id);
+            // Avoid echoing arbitrary driver/page error payloads into model output.
+            if (m.error) p.reject(Error('Safari MCP rejected the request. Check Safari permissions and session state.'));
+            else p.resolve(m.result);
+          } catch { this.stop(Error('Malformed or mismatched Safari MCP reply.')); return; }
+        }
+      });
+      const hello = await this.rpc('initialize', { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'pi-safari', version: VERSION } });
+      if (hello?.protocolVersion !== '2024-11-05' || hello?.serverInfo?.name !== 'Safari' || !hello?.capabilities?.tools) throw Error('Incompatible Safari MCP protocol.');
+      this.write({ jsonrpc: '2.0', method: 'notifications/initialized' });
+      const tools = await this.rpc('tools/list', {});
+      if (!Array.isArray(tools?.tools) || REQUIRED.some(name => !tools.tools.some((t: { name: string }) => t.name === name))) throw Error('Safari MCP is missing required tools; update Safari.');
+      const close = tools.tools.find((t: any) => t.name === 'close_tab')?.inputSchema;
+      if (close?.type !== 'object' || close.properties?.handle?.type !== 'string' || !Array.isArray(close.required) || !close.required.includes('handle') || close.required.some((key: string) => key !== 'handle')) throw Error('Incompatible Safari close_tab schema.');
+    })();
+    try { await this.starting; } catch (e) { this.stop(); throw e; }
+  }
+  private write(message: unknown) {
+    if (!this.child) throw Error('Safari MCP unavailable');
+    const child = this.child;
+    child.stdin.write(JSON.stringify(message) + '\n', e => { if (e && this.child === child) this.stop(Error('Safari MCP write failed.')); });
+  }
+  private rpc(method: string, params: unknown): Promise<any> {
+    const id = ++this.nextId;
+    return new Promise((resolve, reject) => { this.pending.set(id, { resolve, reject }); try { this.write({ jsonrpc: '2.0', id, method, params }); } catch (e) { this.pending.delete(id); reject(e); } });
+  }
+  call(name: string, args: Record<string, unknown>, signal?: AbortSignal): Promise<ToolReply> {
+    if (!REQUIRED.includes(name)) return Promise.reject(Error('Unsupported internal Safari operation.'));
+    const next = this.queue.then(async () => {
+      if (signal?.aborted) throw Error('Safari operation cancelled.');
+      clearTimeout(this.idle);
+      const abort = () => this.stop(Error('Safari deadline/cancellation; relist tabs and inspect before retrying an open.'));
+      const timer = setTimeout(abort, this.options.timeout ?? 20000);
+      signal?.addEventListener('abort', abort, { once: true });
+      try {
+        await this.start();
+        const reply = await this.rpc('tools/call', { name, arguments: args });
+        if (!reply || !Array.isArray(reply.content) || reply.content.some((c: any) => c?.type !== 'text' || typeof c.text !== 'string')) throw Error('Invalid Safari tool result.');
+        if (reply.isError) throw Error('Safari operation failed. Check remote automation permission and relist tabs; inspect before retrying an open.');
+        return reply as ToolReply;
+      } finally {
+        clearTimeout(timer); signal?.removeEventListener('abort', abort);
+        this.idle = setTimeout(() => this.close(), 5 * 60_000); this.idle.unref();
+      }
+    });
+    this.queue = next.catch(() => {}); return next;
+  }
+}
+export function toolJSON(reply: ToolReply): any {
+  if (reply.content.length !== 1 || typeof reply.content[0].text !== 'string') throw Error('Expected a single JSON Safari result.');
+  try { return JSON.parse(reply.content[0].text); } catch { throw Error('Safari returned an unexpected result format.'); }
+}

package/src/safari.ts

@@ -0,0 +1,163 @@
+import { searchRequest, searchJS, validateSearch, type SearchOptions } from './search.ts';
+import { SafariMCP, toolJSON, type Transport } from './mcp.ts';
+import { bound, webURL, readJS, linkJS, readyJS } from './extraction.ts';
+export interface Target { targetId: string; epoch: string }
+const HANDLE = /^[A-Za-z0-9_-]{1,200}$/;
+export class Safari {
+  private queue: Promise<unknown> = Promise.resolve();
+  private transport: Transport;
+  constructor(transport: Transport = new SafariMCP()) { this.transport = transport; }
+  close() { this.transport.close(); }
+  serial<T>(fn: () => Promise<T>): Promise<T> { const next = this.queue.then(fn); this.queue = next.catch(() => {}); return next; }
+  private operation<T>(fn: (signal: AbortSignal) => Promise<T>, signal?: AbortSignal): Promise<T> {
+    return this.serial(async () => {
+      if (signal?.aborted) throw Error('Safari operation cancelled.');
+      const deadline = AbortSignal.timeout(20000);
+      const combined = signal ? AbortSignal.any([signal, deadline]) : deadline;
+      return fn(combined);
+    });
+  }
+  private async call(name: string, args: Record<string, unknown>, signal: AbortSignal): Promise<any> {
+    if (signal.aborted) throw Error('Safari deadline/cancellation; inspect tabs before retrying an open.');
+    return toolJSON(await this.transport.call(name, args, signal));
+  }
+  private async list(signal: AbortSignal): Promise<{ handle: string; url?: string; title?: string }[]> {
+    const tabs = await this.call('list_tabs', {}, signal);
+    if (!Array.isArray(tabs) || tabs.some(t => !t || typeof t.handle !== 'string' || !HANDLE.test(t.handle) || (t.url !== undefined && typeof t.url !== 'string') || (t.title !== undefined && typeof t.title !== 'string')) || new Set(tabs.map(t => t.handle)).size !== tabs.length) throw Error('Invalid Safari tab list.');
+    return tabs;
+  }
+  private target(t: Target) {
+    if (typeof t?.targetId !== 'string' || !HANDLE.test(t.targetId) || typeof t.epoch !== 'string' || t.epoch !== this.transport.epoch) throw Error('Invalid or stale Safari target; use targetId and epoch from safari_tabs/open.');
+  }
+  private async select(t: Target, signal: AbortSignal) {
+    this.target(t);
+    if (!(await this.list(signal)).some(tab => tab.handle === t.targetId)) throw Error('Safari target closed or unavailable; relist tabs.');
+    this.target(t); // A reconnect invalidates the old epoch even if a handle is reused.
+    // Safari returns a plain-text acknowledgement for switch_tab.
+    // The transport still validates its envelope and isError flag.
+    await this.transport.call('switch_tab', { handle: t.targetId }, signal);
+    this.target(t);
+  }
+  private async closeTarget(t: Target, signal: AbortSignal) {
+    this.target(t);
+    const exists = (await this.list(signal)).some(tab => tab.handle === t.targetId);
+    this.target(t);
+    if (!exists) return { status: 'already-absent' as const };
+    if (signal.aborted) throw Error('Safari close cancelled.');
+    // Apple's close_tab takes a handle and returns an acknowledgement, not JSON.
+    await this.transport.call('close_tab', { handle: t.targetId }, signal);
+    this.target(t);
+    return { status: 'closed' as const };
+  }
+  closeTab(t: Target, signal?: AbortSignal) {
+    return this.operation(s => this.closeTarget(t, s), signal);
+  }
+  private async cleanupSearch(t?: Target) {
+    if (!t) return { status: 'unidentified' as const, note: 'No identified created tab; inspect tabs before retrying.' };
+    if (t.epoch !== this.transport.epoch) return { status: 'skipped-retired-epoch' as const, note: 'Connection retired; relist tabs for manual cleanup.' };
+    try {
+      // Bounded cleanup may finish after cancellation, but never reconnects a retired target.
+      return await this.closeTarget(t, AbortSignal.timeout(3000));
+    } catch {
+      return { status: 'failed' as const, note: 'Cleanup unconfirmed; relist tabs before manual cleanup or retrying.' };
+    }
+  }
+  private async evaluate(expression: string, signal: AbortSignal): Promise<any> {
+    const value = await this.call('evaluate_javascript', { expression: `return (${expression});` }, signal);
+    if (typeof value !== 'string') throw Error('Unexpected Safari extraction result.');
+    try { return JSON.parse(value); } catch { throw Error('Invalid Safari extraction JSON.'); }
+  }
+  tabs(signal?: AbortSignal) {
+    return this.operation(async s => {
+      const tabs = await this.list(s);
+      const result = { tabs: tabs.slice(0, 100).map(t => ({ targetId: t.handle, epoch: this.transport.epoch, ...(t.url === undefined ? {} : { url: t.url.slice(0, 2048) }), ...(t.title === undefined ? {} : { title: t.title.slice(0, 300) }) })), truncated: tabs.length > 100 };
+      bound(result); return result;
+    }, signal);
+  }
+  private async create(url: string, signal: AbortSignal, identified?: (t: Target) => void) {
+    const normalized = webURL(url);
+    const epoch = this.transport.epoch;
+    const created = await this.call('create_tab', { url: normalized }, signal);
+    if (typeof created?.handle !== 'string' || !HANDLE.test(created.handle)) throw Error('Cannot identify created tab; inspect tabs before retrying.');
+    const t = { targetId: created.handle, epoch };
+    identified?.(t);
+    const deadline = Date.now() + 12000;
+    while (Date.now() < deadline) {
+      await this.select(t, signal);
+      const info = await this.call('page_info', {}, signal);
+      if (typeof info?.url !== 'string') throw Error('Invalid Safari page info.');
+      if (info.url !== normalized && info.url !== 'about:blank') throw Error('Redirect or URL rewrite rejected; tab left open. Inspect tabs before retrying.');
+      if (info.url === normalized) {
+        const ready = await this.call('evaluate_javascript', { expression: `return (${readyJS(normalized)});` }, signal);
+        if (ready === true) { this.target(t); return { ...t, url: normalized, note: 'New automation tab. No ownership or document identity guarantee. Tab left open.' }; }
+      }
+      await new Promise<void>((resolve, reject) => {
+        const abort = () => { clearTimeout(timer); reject(Error('Safari operation cancelled; tab may remain open.')); };
+        const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve(); }, 200);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted) abort();
+      });
+    }
+    throw Error('Requested URL did not become ready; tab left open. Inspect tabs before retrying.');
+  }
+  open(url: string, signal?: AbortSignal) { webURL(url); return this.operation(s => this.create(url, s), signal); }
+  private async observe(t: Target, expression: string, signal: AbortSignal) {
+    await this.select(t, signal);
+    const before = await this.call('page_info', {}, signal);
+    if (typeof before?.url !== 'string') throw Error('Invalid Safari page info.');
+    webURL(before.url);
+    const data = await this.evaluate(expression, signal);
+    const after = await this.call('page_info', {}, signal);
+    this.target(t);
+    if (before.url !== after?.url || !(await this.list(signal)).some(tab => tab.handle === t.targetId && tab.url === before.url)) throw Error('Page changed during extraction; read again.');
+    this.target(t); bound(data);
+    return { data, url: before.url };
+  }
+  read(t: Target, chars = 8000, links = 20, signal?: AbortSignal) {
+    const expression = readJS(chars, links);
+    return this.operation(async s => {
+      const { data, url } = await this.observe(t, expression, s);
+      if (!data || data.url !== url.slice(0, 2048) || typeof data.text !== 'string' || data.text.length > chars || typeof data.title !== 'string' || data.title.length > 300 || !Array.isArray(data.links) || data.links.length > links || typeof data.textTruncated !== 'boolean' || typeof data.linksTruncated !== 'boolean') throw Error('Invalid Safari read result.');
+      const result = { ...data, targetId: t.targetId, epoch: t.epoch, identity: 'URL checks only; same-URL document replacement and live DOM changes may go undetected.' };
+      bound(result); return result;
+    }, signal);
+  }
+  search(options: SearchOptions, signal?: AbortSignal) {
+    const request = searchRequest(options);
+    const expression = searchJS(request.url, request.maxResults);
+    return this.operation(async s => {
+      let created: Target | undefined;
+      let result;
+      try {
+        const tab = await this.create(request.url, s, t => { created = t; });
+        const { data, url } = await this.observe(tab, expression, s);
+        if (url !== request.url) throw Error('Search URL changed.');
+        result = { ...request, ...validateSearch(data, request.url, request.maxResults), note: 'Untrusted provider ranking/content; first HTML page only. Empty results may indicate a challenge or changed markup. URL checks do not guarantee document identity.' };
+        bound(result);
+        if (s.aborted) throw Error('Safari search cancelled.');
+      } catch (error) {
+        const cleanup = await this.cleanupSearch(created);
+        // Retain the primary error (including its cause) when cleanup also fails.
+        const failure = new Error(`${error instanceof Error ? error.message : 'Safari search failed.'} Search cleanup: ${cleanup.status}.${'note' in cleanup ? ` ${cleanup.note}` : ''}`, { cause: error });
+        Object.assign(failure, { cleanup });
+        throw failure;
+      }
+      const cleanup = await this.cleanupSearch(created);
+      if (s.aborted) {
+        const failure = new Error(`Safari search cancelled. Search cleanup: ${cleanup.status}.`);
+        Object.assign(failure, { cleanup });
+        throw failure;
+      }
+      // Search results never advertise a usable target, even if cleanup is unconfirmed.
+      return { ...result, cleanup };
+    }, signal);
+  }
+  followLink(t: Target, selector: string, expectedUrl: string, signal?: AbortSignal) {
+    const expression = linkJS(selector, expectedUrl);
+    return this.operation(async s => {
+      const { data, url } = await this.observe(t, expression, s);
+      if (url !== expectedUrl || typeof data?.href !== 'string') throw Error('Source URL changed or invalid link result; read again.');
+      return this.create(webURL(data.href), s);
+    }, signal);
+  }
+}

package/src/search.ts

@@ -0,0 +1,51 @@
+import { webURL } from './extraction.ts';
+
+// DuckDuckGo HTML's documented URL controls; deliberately not arbitrary provider parameters.
+export const REGIONS = ['wt-wt', 'us-en', 'uk-en', 'ca-en', 'au-en', 'de-de', 'fr-fr', 'in-en', 'jp-jp'] as const;
+export const TIMES = ['any', 'd', 'w', 'm', 'y'] as const;
+export interface SearchOptions { query: string; maxResults?: number; region?: string; time?: string }
+export function searchRequest(options: SearchOptions) {
+  const { query, maxResults = 5, region = 'wt-wt', time = 'any' } = options;
+  if (typeof query !== 'string' || !query.trim() || query.length > 500 || /[\u0000-\u001f\u007f]/.test(query)) throw Error('Search query must be 1..500 characters without control characters.');
+  if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 10) throw Error('maxResults must be 1..10.');
+  if (!(REGIONS as readonly string[]).includes(region) || !(TIMES as readonly string[]).includes(time)) throw Error('Unsupported search region or time filter.');
+  const url = new URL('https://html.duckduckgo.com/html/');
+  url.searchParams.set('q', query.trim()); url.searchParams.set('kl', region);
+  if (time !== 'any') url.searchParams.set('df', time);
+  return { query: query.trim(), maxResults, region, time, url: url.href };
+}
+export interface SearchResult { rank: number; title: string; url: string; snippet: string }
+export function validateSearch(data: any, expectedUrl: string, maxResults: number): { results: SearchResult[]; truncated: boolean } {
+  if (!data || data.url !== expectedUrl || !Array.isArray(data.results) || data.results.length > maxResults || typeof data.truncated !== 'boolean') throw Error('Invalid Safari search result.');
+  const seen = new Set<string>();
+  for (const [i, r] of data.results.entries()) {
+    if (!r || r.rank !== i + 1 || typeof r.title !== 'string' || !r.title.trim() || r.title.length > 300 || typeof r.snippet !== 'string' || r.snippet.length > 600 || typeof r.url !== 'string' || r.url.length > 2048 || webURL(r.url) !== r.url || seen.has(r.url)) throw Error('Invalid Safari search entry.');
+    seen.add(r.url);
+  }
+  return { results: data.results, truncated: data.truncated };
+}
+// Fixed, read-only selectors. No raw query, arbitrary selector, click, form or provider script execution.
+export function searchJS(expectedUrl: string, maxResults: number): string {
+  webURL(expectedUrl);
+  if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > 10) throw Error('maxResults must be 1..10.');
+  return `JSON.stringify((()=>{
+    if(location.href!==${JSON.stringify(expectedUrl)})throw Error('Search URL changed');
+    const visible=e=>e&&e.getClientRects().length&&getComputedStyle(e).visibility==='visible'&&getComputedStyle(e).display!=='none';
+    const text=(e,n)=>(e?.innerText||'').replace(/\\s+/g,' ').trim().slice(0,n);
+    const nodes=document.querySelectorAll('.result'); const results=[]; const seen=new Set(); let truncated=nodes.length>100;
+    for(const node of Array.from(nodes).slice(0,100)){
+      if(!visible(node)||node.matches('.result--ad'))continue;
+      const a=node.querySelector('a.result__a[href]'); if(!visible(a))continue;
+      let u; try {
+        u=new URL(a.href,location.href);
+        if(u.protocol==='https:'&&['duckduckgo.com','html.duckduckgo.com'].includes(u.hostname)&&u.pathname==='/l/'&&u.searchParams.has('uddg'))u=new URL(u.searchParams.get('uddg'));
+      }catch{continue;}
+      if(!/^https?:$/.test(u.protocol)||u.username||u.password||u.href.length>2048||['duckduckgo.com','html.duckduckgo.com'].includes(u.hostname)||seen.has(u.href))continue;
+      const title=text(a,300); if(!title)continue; seen.add(u.href);
+      if(results.length===${maxResults}){truncated=true;break;}
+      const snippet=node.querySelector('.result__snippet');
+      results.push({rank:results.length+1,title,url:u.href,snippet:visible(snippet)?text(snippet,600):''});
+    }
+    return {url:location.href,results,truncated};
+  })())`;
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = '0.1.0';