safari-pilot 0.1.0

package/dist/tools/wait.js

@@ -0,0 +1,182 @@
+const DEFAULT_TIMEOUT_MS = 10000;
+const DEFAULT_POLL_INTERVAL_MS = 250;
+const NETWORK_IDLE_QUIET_MS = 500;
+/**
+ * Build the JS snippet that checks a condition and returns true/false.
+ */
+function buildConditionJs(condition, value) {
+    switch (condition) {
+        case 'selector':
+            return `return document.querySelector(${JSON.stringify(value)}) !== null`;
+        case 'selectorHidden':
+            return `return document.querySelector(${JSON.stringify(value)}) === null`;
+        case 'text':
+            return `return document.body && document.body.textContent.includes(${JSON.stringify(value)})`;
+        case 'textGone':
+            return `return !document.body || !document.body.textContent.includes(${JSON.stringify(value)})`;
+        case 'urlMatch':
+            return `return location.href.includes(${JSON.stringify(value)})`;
+        case 'networkidle': {
+            // Track in-flight XHR/fetch count and resolve when quiet for NETWORK_IDLE_QUIET_MS.
+            // The JS returns true once there has been no XHR/fetch activity for the threshold.
+            return `
+(function() {
+  if (!window.__safariPilotNetworkIdleSetup) {
+    window.__safariPilotNetworkIdleSetup = true;
+    window.__safariPilotInflight = 0;
+    window.__safariPilotLastActivity = Date.now();
+    const origOpen = XMLHttpRequest.prototype.open;
+    const origSend = XMLHttpRequest.prototype.send;
+    XMLHttpRequest.prototype.send = function() {
+      window.__safariPilotInflight++;
+      window.__safariPilotLastActivity = Date.now();
+      this.addEventListener('loadend', function() {
+        window.__safariPilotInflight = Math.max(0, window.__safariPilotInflight - 1);
+        window.__safariPilotLastActivity = Date.now();
+      });
+      return origSend.apply(this, arguments);
+    };
+    const origFetch = window.fetch;
+    window.fetch = function() {
+      window.__safariPilotInflight++;
+      window.__safariPilotLastActivity = Date.now();
+      return origFetch.apply(this, arguments).finally(function() {
+        window.__safariPilotInflight = Math.max(0, window.__safariPilotInflight - 1);
+        window.__safariPilotLastActivity = Date.now();
+      });
+    };
+  }
+  return window.__safariPilotInflight === 0 && (Date.now() - window.__safariPilotLastActivity) >= ${NETWORK_IDLE_QUIET_MS};
+})()
+`.trim();
+        }
+        case 'function':
+            // value is a JS function body — evaluate and return its truthy result
+            return `return (function() { ${value} })()`;
+        default:
+            return 'return false';
+    }
+}
+export class WaitTools {
+    engine;
+    constructor(engine) {
+        this.engine = engine;
+    }
+    // ── Public API ──────────────────────────────────────────────────────────────
+    getDefinitions() {
+        return [
+            {
+                name: 'safari_wait_for',
+                description: 'Wait for a condition to be met in the specified tab before proceeding. ' +
+                    'Polls the page at configurable intervals until the condition is satisfied or the timeout expires. ' +
+                    'Supports waiting for DOM selectors, text content, URL patterns, network idle, and custom JS functions.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        tabUrl: { type: 'string', description: 'Current URL of the tab to poll' },
+                        condition: {
+                            type: 'string',
+                            enum: ['selector', 'selectorHidden', 'text', 'textGone', 'urlMatch', 'networkidle', 'function'],
+                            description: 'The condition to wait for: ' +
+                                '"selector" — element matching CSS selector exists; ' +
+                                '"selectorHidden" — element has disappeared; ' +
+                                '"text" — text appears in page body; ' +
+                                '"textGone" — text is absent from page body; ' +
+                                '"urlMatch" — current URL contains the pattern; ' +
+                                '"networkidle" — no XHR/fetch activity for 500 ms; ' +
+                                '"function" — custom JS function body returns truthy',
+                        },
+                        value: {
+                            type: 'string',
+                            description: 'The CSS selector, text, URL pattern, or JS function body depending on condition',
+                        },
+                        timeout: {
+                            type: 'number',
+                            description: 'Maximum time to wait in milliseconds',
+                            default: DEFAULT_TIMEOUT_MS,
+                        },
+                        pollInterval: {
+                            type: 'number',
+                            description: 'How often to check the condition in milliseconds',
+                            default: DEFAULT_POLL_INTERVAL_MS,
+                        },
+                    },
+                    required: ['tabUrl', 'condition'],
+                },
+                requirements: {},
+            },
+        ];
+    }
+    getHandler(name) {
+        switch (name) {
+            case 'safari_wait_for':
+                return (p) => this.handleWaitFor(p);
+            default:
+                throw new Error(`WaitTools: unknown tool "${name}"`);
+        }
+    }
+    // ── Handlers ────────────────────────────────────────────────────────────────
+    async handleWaitFor(params) {
+        const wallStart = Date.now();
+        const tabUrl = params['tabUrl'];
+        const condition = params['condition'];
+        const value = typeof params['value'] === 'string' ? params['value'] : '';
+        const timeout = typeof params['timeout'] === 'number' ? params['timeout'] : DEFAULT_TIMEOUT_MS;
+        const pollInterval = typeof params['pollInterval'] === 'number' ? params['pollInterval'] : DEFAULT_POLL_INTERVAL_MS;
+        const conditionJs = buildConditionJs(condition, value);
+        let met = false;
+        let timedOut = false;
+        while (true) {
+            const elapsed = Date.now() - wallStart;
+            if (elapsed >= timeout) {
+                timedOut = true;
+                break;
+            }
+            const result = await this.executeJsInTab(tabUrl, conditionJs);
+            if (result === true) {
+                met = true;
+                break;
+            }
+            // Sleep for the poll interval — but cap it so we don't overshoot the timeout.
+            const remaining = timeout - (Date.now() - wallStart);
+            if (remaining <= 0) {
+                timedOut = true;
+                break;
+            }
+            await sleep(Math.min(pollInterval, remaining));
+        }
+        const elapsed = Date.now() - wallStart;
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ met, elapsed, timedOut }) }],
+            metadata: { engine: 'applescript', degraded: false, latencyMs: elapsed },
+        };
+    }
+    // ── Private helpers ─────────────────────────────────────────────────────────
+    /**
+     * Execute JS in a tab and return the raw boolean/truthy result.
+     * Returns false on engine failure or unparseable output.
+     */
+    async executeJsInTab(tabUrl, jsCode) {
+        const script = this.engine.buildTabScript(tabUrl, jsCode);
+        const result = await this.engine.execute(script);
+        if (!result.ok || !result.value)
+            return false;
+        const raw = result.value.trim();
+        // AppleScript returns 'true'/'false' as strings; also handle JSON booleans
+        if (raw === 'true')
+            return true;
+        if (raw === 'false')
+            return false;
+        try {
+            return Boolean(JSON.parse(raw));
+        }
+        catch {
+            return Boolean(raw);
+        }
+    }
+}
+// ── Module-level helpers ─────────────────────────────────────────────────────
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=wait.js.map

package/dist/tools/wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../../src/tools/wait.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,85 @@
+export type Engine = 'extension' | 'daemon' | 'applescript';
+export interface EngineCapabilities {
+    shadowDom: boolean;
+    cspBypass: boolean;
+    dialogIntercept: boolean;
+    networkIntercept: boolean;
+    cookieHttpOnly: boolean;
+    framesCrossOrigin: boolean;
+    latencyMs: number;
+}
+export interface ToolRequirements {
+    requiresShadowDom?: boolean;
+    requiresCspBypass?: boolean;
+    requiresDialogIntercept?: boolean;
+    requiresNetworkIntercept?: boolean;
+    requiresCookieHttpOnly?: boolean;
+    requiresFramesCrossOrigin?: boolean;
+    prefersFastLatency?: boolean;
+}
+export interface EngineResult {
+    ok: boolean;
+    value?: string;
+    error?: EngineError;
+    elapsed_ms: number;
+}
+export interface EngineError {
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+export interface ToolError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    hints: string[];
+    context: {
+        engine: Engine;
+        url: string;
+        selector?: string;
+        elapsed_ms: number;
+    };
+    cause_chain?: string[];
+}
+export interface ToolResponse {
+    content: Array<{
+        type: 'text' | 'image';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    metadata: {
+        engine: Engine;
+        degraded: boolean;
+        degradedReason?: string;
+        latencyMs: number;
+        tabUrl?: string;
+    };
+}
+export type TabId = number;
+export interface TabInfo {
+    tabId: TabId;
+    url: string;
+    title: string;
+    windowId: number;
+    isPrivate: boolean;
+    ownedByAgent: boolean;
+    isActive: boolean;
+}
+export interface DomainPolicy {
+    domain: string;
+    trust: 'trusted' | 'untrusted' | 'unknown';
+    privateWindow: boolean;
+    extensionAllowed: boolean;
+    maxActionsPerMinute: number;
+}
+export interface AuditEntry {
+    timestamp: string;
+    tool: string;
+    tabUrl: string;
+    engine: Engine;
+    params: Record<string, unknown>;
+    result: 'ok' | 'error';
+    elapsed_ms: number;
+    session: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/extension/background.js

@@ -0,0 +1,294 @@
+// background.js — Extension Service Worker
+// Handles native messaging to the Safari app extension handler via
+// browser.runtime.sendNativeMessage, routes commands from content scripts,
+// manages cookie/DNR APIs, and tracks active tabs.
+
+(function () {
+  'use strict';
+
+  // ─── Constants ──────────────────────────────────────────────────────────────
+
+  // Bundle ID of the containing macOS app — Safari routes
+  // sendNativeMessage calls to the app's web extension handler.
+  const APP_BUNDLE_ID = 'com.safari-pilot.app';
+  const POLL_INTERVAL_MS = 200;
+
+  // ─── State ────────────────────────────────────────────────────────────────
+
+  let isConnected = false;
+  const activeTabs = new Map(); // tabId → { url, status }
+  let pollTimerId = null;
+
+  // ─── Native Messaging (sendNativeMessage-based) ───────────────────────────
+
+  /**
+   * Send a message to the native extension handler and return the response.
+   * Uses browser.runtime.sendNativeMessage (request/response per call).
+   */
+  function sendNativeRequest(message) {
+    return browser.runtime.sendNativeMessage(APP_BUNDLE_ID, message);
+  }
+
+  /**
+   * Poll the native handler for pending commands from the daemon.
+   * If a command is returned, route it to the content script,
+   * collect the result, and send it back via native messaging.
+   */
+  async function pollForCommands() {
+    try {
+      const response = await sendNativeRequest({ type: 'poll' });
+
+      if (response && response.command && response.command !== null) {
+        const cmd = response.command;
+        await executeAndReturnResult(cmd);
+      }
+    } catch (e) {
+      console.warn('[SafariPilot] Poll error:', e);
+    }
+  }
+
+  /**
+   * Execute a command received from the daemon (via poll) and send the
+   * result back through the native handler.
+   */
+  async function executeAndReturnResult(cmd) {
+    const commandId = cmd.id;
+
+    try {
+      let result;
+
+      if (cmd.script) {
+        // Route script execution to the active tab's content script
+        const tabs = await browser.tabs.query({
+          active: true,
+          currentWindow: true,
+        });
+        const tabId = tabs[0]?.id;
+
+        if (tabId != null) {
+          const responses = await browser.tabs.sendMessage(tabId, {
+            type: 'SAFARI_PILOT_COMMAND',
+            method: 'execute_script',
+            params: { script: cmd.script },
+          });
+          result = responses;
+        } else {
+          result = { ok: false, error: { message: 'No active tab' } };
+        }
+      } else {
+        result = { ok: true, value: null };
+      }
+
+      await sendNativeRequest({
+        type: 'result',
+        id: commandId,
+        result: result,
+      });
+    } catch (err) {
+      // Send error result back so the daemon doesn't hang
+      try {
+        await sendNativeRequest({
+          type: 'result',
+          id: commandId,
+          result: { ok: false, error: { message: err.message } },
+        });
+      } catch (sendErr) {
+        console.error('[SafariPilot] Failed to send error result:', sendErr);
+      }
+    }
+  }
+
+  // ─── Poll Loop ────────────────────────────────────────────────────────────
+
+  function startPolling() {
+    if (pollTimerId != null) return;
+    pollTimerId = setInterval(pollForCommands, POLL_INTERVAL_MS);
+    console.log('[SafariPilot] Polling started');
+  }
+
+  function stopPolling() {
+    if (pollTimerId != null) {
+      clearInterval(pollTimerId);
+      pollTimerId = null;
+      console.log('[SafariPilot] Polling stopped');
+    }
+  }
+
+  // ─── Cookie Operations ────────────────────────────────────────────────────
+
+  async function handleCookieGet(params) {
+    const result = await browser.cookies.get({
+      url: params.url,
+      name: params.name,
+      storeId: params.storeId,
+    });
+    return { ok: true, value: result };
+  }
+
+  async function handleCookieSet(params) {
+    const result = await browser.cookies.set({
+      url: params.url,
+      name: params.name,
+      value: params.value,
+      domain: params.domain,
+      path: params.path ?? '/',
+      secure: params.secure ?? false,
+      httpOnly: params.httpOnly ?? false,
+      sameSite: params.sameSite,
+      expirationDate: params.expirationDate,
+      storeId: params.storeId,
+    });
+    return { ok: true, value: result };
+  }
+
+  async function handleCookieRemove(params) {
+    const result = await browser.cookies.remove({
+      url: params.url,
+      name: params.name,
+      storeId: params.storeId,
+    });
+    return { ok: true, value: result };
+  }
+
+  async function handleCookieGetAll(params) {
+    const result = await browser.cookies.getAll({
+      url: params.url,
+      domain: params.domain,
+      name: params.name,
+      path: params.path,
+      secure: params.secure,
+      storeId: params.storeId,
+    });
+    return { ok: true, value: result };
+  }
+
+  // ─── Declarative Net Request Operations ───────────────────────────────────
+
+  async function handleDnrAddRule(params) {
+    await browser.declarativeNetRequest.updateDynamicRules({
+      addRules: [params.rule],
+      removeRuleIds: [],
+    });
+    return { ok: true, value: { added: true, ruleId: params.rule?.id } };
+  }
+
+  async function handleDnrRemoveRule(params) {
+    await browser.declarativeNetRequest.updateDynamicRules({
+      addRules: [],
+      removeRuleIds: [params.ruleId],
+    });
+    return { ok: true, value: { removed: true, ruleId: params.ruleId } };
+  }
+
+  // ─── execute_in_main (forward to content script) ──────────────────────────
+
+  async function handleExecuteInMain(message, sender) {
+    const tabId = sender?.tab?.id;
+    if (tabId == null) {
+      return { ok: false, error: { message: 'No tab context available' } };
+    }
+
+    try {
+      const [result] = await browser.tabs.sendMessage(tabId, {
+        type: 'SAFARI_PILOT_COMMAND',
+        method: message.method,
+        params: message.params ?? {},
+      });
+      return result ?? { ok: true, value: null };
+    } catch (err) {
+      return { ok: false, error: { message: err.message } };
+    }
+  }
+
+  // ─── Command Router ────────────────────────────────────────────────────────
+
+  async function handleCommand(message, sender) {
+    const { command, params } = message;
+
+    try {
+      switch (command) {
+        case 'execute_in_main':
+          return await handleExecuteInMain(message, sender);
+
+        case 'cookie_get':
+          return await handleCookieGet(params ?? {});
+
+        case 'cookie_set':
+          return await handleCookieSet(params ?? {});
+
+        case 'cookie_remove':
+          return await handleCookieRemove(params ?? {});
+
+        case 'cookie_get_all':
+          return await handleCookieGetAll(params ?? {});
+
+        case 'dnr_add_rule':
+          return await handleDnrAddRule(params ?? {});
+
+        case 'dnr_remove_rule':
+          return await handleDnrRemoveRule(params ?? {});
+
+        default:
+          return {
+            ok: false,
+            error: { message: `Unknown command: ${command}` },
+          };
+      }
+    } catch (err) {
+      return {
+        ok: false,
+        error: { message: err.message, name: err.name },
+      };
+    }
+  }
+
+  // ─── Runtime Message Listener ─────────────────────────────────────────────
+
+  browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
+    // Health check
+    if (message && message.type === 'ping') {
+      sendResponse({ ok: true, type: 'pong', extensionVersion: '0.1.0' });
+      return false;
+    }
+
+    // Command dispatch from content-isolated.js
+    if (message && message.type === 'SAFARI_PILOT_COMMAND') {
+      handleCommand(message, sender).then(sendResponse);
+      return true; // Keep message channel open for async response
+    }
+
+    return false;
+  });
+
+  // ─── Tab Tracking ─────────────────────────────────────────────────────────
+
+  browser.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
+    if (changeInfo.status) {
+      activeTabs.set(tabId, {
+        url: tab.url ?? activeTabs.get(tabId)?.url,
+        status: changeInfo.status,
+      });
+    }
+  });
+
+  browser.tabs.onRemoved.addListener((tabId) => {
+    activeTabs.delete(tabId);
+  });
+
+  // ─── Initialization ────────────────────────────────────────────────────────
+
+  // Send status check on startup to register as connected
+  sendNativeRequest({ type: 'status' })
+    .then((response) => {
+      if (response && response.connected) {
+        isConnected = true;
+        console.log('[SafariPilot] Native handler connected, version:', response.version);
+      }
+    })
+    .catch((err) => {
+      console.warn('[SafariPilot] Initial status check failed:', err);
+    });
+
+  // Start polling for daemon commands
+  startPolling();
+})();

package/extension/content-isolated.js

@@ -0,0 +1,80 @@
+// content-isolated.js — ISOLATED world
+// This script CANNOT be modified by page JS. It serves as a trusted relay.
+//
+// Role: Secure bridge between the background service worker and the MAIN world
+// content script. Page JavaScript operates in a separate context and cannot
+// read or tamper with this script's state or the browser extension API.
+//
+// Message flow:
+//   Background (runtime.sendMessage)
+//     → ISOLATED world (browser.runtime.onMessage)
+//       → MAIN world (window.postMessage with type SAFARI_PILOT_CMD)
+//         → ISOLATED world (window.addEventListener 'message' SAFARI_PILOT_RESPONSE)
+//           → Background (sendResponse callback)
+
+(() => {
+  'use strict';
+
+  let nextRequestId = 0;
+  const pendingRequests = new Map();
+
+  // ─── MAIN World → ISOLATED World ──────────────────────────────────────────
+  // Receive responses from the MAIN world content script.
+  // Only process messages from the same window (blocks cross-frame injection).
+
+  window.addEventListener('message', (event) => {
+    if (event.source !== window) return;
+    if (event.data?.type !== 'SAFARI_PILOT_RESPONSE') return;
+
+    const { requestId, ok, value, error } = event.data;
+    const pending = pendingRequests.get(requestId);
+    if (!pending) return;
+
+    pendingRequests.delete(requestId);
+    if (ok) {
+      pending.resolve(value);
+    } else {
+      pending.reject(error);
+    }
+  });
+
+  // ─── Background → ISOLATED World ──────────────────────────────────────────
+  // Receive commands from the background service worker via runtime messaging.
+  // Returns true to indicate async sendResponse (keeps message channel open).
+
+  browser.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+    if (message.type !== 'SAFARI_PILOT_COMMAND') return false;
+
+    const requestId = `sp_${++nextRequestId}_${Date.now()}`;
+
+    const promise = new Promise((resolve, reject) => {
+      pendingRequests.set(requestId, { resolve, reject });
+
+      // Forward to MAIN world. Use window.location.origin (never '*') per spec.
+      window.postMessage(
+        {
+          type: 'SAFARI_PILOT_CMD',
+          requestId,
+          method: message.method,
+          params: message.params ?? {},
+        },
+        window.location.origin
+      );
+
+      // Timeout: MAIN world has 10 s to respond before we fail the request
+      setTimeout(() => {
+        if (pendingRequests.has(requestId)) {
+          pendingRequests.delete(requestId);
+          reject({ message: 'MAIN world timeout', code: 'TIMEOUT' });
+        }
+      }, 10_000);
+    });
+
+    promise.then(
+      value => sendResponse({ ok: true, value }),
+      error => sendResponse({ ok: false, error })
+    );
+
+    return true; // Keep the message channel open for async sendResponse
+  });
+})();