Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

13.1 KB
Raw Blame
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { browser, type Browser } from 'wxt/browser';
import type { FocusedElement, RunEvent } from '@/lib/actions/protocol';
import type { MonitorState } from '@/lib/monitor/events';
import type { RecordingState } from '@/lib/recordings/events';
import { SITE_MAPPER_SKILL, type SiteMapDraft } from '@/lib/skills/site-map';
import type { ToolOffer } from './code-toolkit';
import type { NewFile } from './file-store';
import type { SavedToolMeta } from './saved-tools';
import { attachPreview, notice, reduce, type RunItem } from './run-items';
import { RUN_PORT, type RunCommand, type RunMessage } from './run-port';
import { useActiveTab, type ActiveTab } from './use-active-tab';
import { useTabSessions } from './use-tab-sessions';
import type { TabSession } from './tab-sessions';

const RECONNECT_MS = 1_000;

const USER_SCRIPTS_RECHECK_MS = 2_000;

const EXTERNAL_VIEW = 'external';

export type { RunItem };

export interface SendOptions {
  agentSkillId?: string;
  focus?: FocusedElement;
  liveTools?: boolean;
}

export interface CompletedTurn {
  sessionId: string;
  runId: string;
}

const finishedCleanly = (event: RunEvent): boolean => event.kind === 'done' && event.stopReason === 'end_turn';

export interface Run {
  items: RunItem[];
  running: boolean;
  sessionId: string | null;
  /** The conversation of the tab in front, when it has one. */
  session: TabSession | null;
  sessions: TabSession[];
  /** The latest turn an agent saw through to the end, in any conversation, as it happened — never from a replay. */
  completed: CompletedTurn | null;
  send: (text: string, opts?: SendOptions) => void;
  cancel: () => void;
  decide: (toolId: string, allow: boolean, remember?: boolean) => void;
  clear: () => void;
  restore: (sessionId: string) => Promise<void>;
  focusSession: (sessionId: string) => void;
  endSession: (sessionId: string) => void;
  draft: SiteMapDraft | null;
  mapSite: () => void;
  activateMap: (exactHost?: boolean) => void;
  discardMap: () => void;
  recording: RecordingState | null;
  startRecording: (captureValues: boolean) => void;
  stopRecording: () => void;
  monitors: MonitorState[];
  stopMonitor: (monitorId: string) => void;
  /** Tools the user kept, for the `/` menu and `/remove-tools`. Metadata only, never code. */
  tools: SavedToolMeta[];
  /** Raised a second after an approved toolkit lands, asking whether to keep it. */
  toolOffer: ToolOffer | null;
  autoRunReady: boolean;
  keepTool: (slug?: string, autoRun?: boolean) => void;
  dismissTool: () => void;
  forgetTool: (id: string) => void;
  setAutoRun: (id: string, on: boolean) => void;
  runTool: (id: string) => void;
  /** Gives a file the panel has stored to the conversation of the tab in front, which reads it. */
  attachFile: (file: NewFile) => void;
  /** Puts open tabs in the conversation of the tab in front, starting one there if need be. */
  addTabs: (tabIds: number[]) => void;
  removeTab: (tabId: number) => void;
  detachFile: (fileId: string) => void;
  reanalyzeFile: (fileId: string) => void;
}

/** Follows the tab in front, unless given a tab of its own to stay on. */
export function useRun(pinned?: ActiveTab): Run {
  const [drafts, setDrafts] = useState<Record<string, SiteMapDraft>>({});
  const [recording, setRecording] = useState<RecordingState | null>(null);
  const [monitors, setMonitors] = useState<MonitorState[]>([]);
  const [offer, setOffer] = useState<ToolOffer | null>(null);
  const [tools, setTools] = useState<SavedToolMeta[]>([]);
  const [autoRunReady, setAutoRunReady] = useState(false);
  const [bySession, setBySession] = useState<Record<string, RunItem[]>>({});
  const [completed, setCompleted] = useState<CompletedTurn | null>(null);
  const port = useRef<Browser.runtime.Port | null>(null);

  const front = useActiveTab();
  const tab = pinned ?? front;
  const sessions = useTabSessions();
  const displayed = useMemo(
    () => (tab.tabId == null ? null : (sessions.find((s) => s.tabIds.includes(tab.tabId!)) ?? null)),
    [sessions, tab.tabId],
  );
  const sessionId = displayed?.sessionId ?? null;

  const write = useCallback((key: string, change: (items: RunItem[]) => RunItem[]) => {
    setBySession((previous) => ({ ...previous, [key]: change(previous[key] ?? []) }));
  }, []);

  const forget = useCallback((...keys: string[]) => {
    setBySession((previous) => {
      const next = { ...previous };
      for (const key of keys) delete next[key];
      return next;
    });
  }, []);

  useEffect(() => {
    let live = true;
    let retry: ReturnType<typeof setTimeout> | undefined;

    const connect = () => {
      if (!live) return;
      let connected: Browser.runtime.Port;
      try {
        connected = browser.runtime.connect({ name: RUN_PORT });
      } catch {
        retry = setTimeout(connect, RECONNECT_MS);
        return;
      }
      port.current = connected;

      connected.onMessage.addListener((message) => {
        const runMessage = message as RunMessage;
        if (runMessage.op === 'mapDraft') {
          setDrafts((previous) => ({ ...previous, [runMessage.sessionId ?? EXTERNAL_VIEW]: runMessage.draft }));
        } else if (runMessage.op === 'mapSettled') {
          setDrafts((previous) =>
            Object.fromEntries(Object.entries(previous).filter(([, held]) => held.stagingId !== runMessage.stagingId)),
          );
          if (!runMessage.ok && runMessage.message) {
            write(runMessage.sessionId ?? EXTERNAL_VIEW, (items) => [...items, notice('error', runMessage.message!)]);
          }
        } else if (runMessage.op === 'recording') setRecording(runMessage.state);
        else if (runMessage.op === 'monitor') {
          const state = runMessage.state;
          setMonitors((previous) => {
            const others = previous.filter((m) => m.monitorId !== state.monitorId);
            return state.phase === 'watching' ? [...others, state] : others;
          });
        } else if (runMessage.op === 'items') {
          write(runMessage.sessionId ?? EXTERNAL_VIEW, () => runMessage.items);
        } else if (runMessage.op === 'item') {
          write(runMessage.sessionId ?? EXTERNAL_VIEW, (items) => [...items, runMessage.item]);
        } else if (runMessage.op === 'preview') {
          write(runMessage.sessionId ?? EXTERNAL_VIEW, (items) => attachPreview(items, runMessage.preview));
        } else if (runMessage.op === 'toolOffer') {
          setOffer(runMessage.offer);
        } else if (runMessage.op === 'toolOfferSettled') {
          setOffer((held) => (held?.toolkitId === runMessage.toolkitId ? null : held));
        } else if (runMessage.op === 'tools') {
          setTools(runMessage.tools);
          setAutoRunReady(runMessage.autoRunReady);
        } else if (runMessage.op === 'close') {
          window.close();
        } else {
          const { sessionId: owner, runId, event } = runMessage;
          if (owner && finishedCleanly(event)) setCompleted({ sessionId: owner, runId });
          write(owner ?? EXTERNAL_VIEW, (items) => reduce(items, event));
        }
      });

      connected.onDisconnect.addListener(() => {
        if (port.current === connected) port.current = null;
        if (live) retry = setTimeout(connect, RECONNECT_MS);
      });
    };

    connect();
    return () => {
      live = false;
      clearTimeout(retry);
      const open = port.current;
      port.current = null;
      open?.disconnect();
    };
  }, [write]);

  const post = useCallback((command: RunCommand): boolean => {
    const open = port.current;
    if (!open) return false;
    try {
      open.postMessage(command);
      return true;
    } catch {
      port.current = null;
      return false;
    }
  }, []);

  useEffect(() => {
    if (sessionId) post({ op: 'replay', sessionId });
  }, [sessionId, post]);

  const awaitingUserScripts = !autoRunReady && (!!offer || tools.some((tool) => tool.autoRun));
  useEffect(() => {
    if (!awaitingUserScripts) return;
    const recheck = setInterval(() => post({ op: 'listTools' }), USER_SCRIPTS_RECHECK_MS);
    return () => clearInterval(recheck);
  }, [awaitingUserScripts, post]);

  const items = useMemo(() => {
    const own = sessionId ? (bySession[sessionId] ?? []) : [];
    const external = bySession[EXTERNAL_VIEW] ?? [];
    return external.length ? [...own, ...external] : own;
  }, [sessionId, bySession]);

  const draft = (sessionId ? drafts[sessionId] : undefined) ?? drafts[EXTERNAL_VIEW] ?? null;

  const send = useCallback(
    (text: string, opts?: SendOptions) => {
      const trimmed = text.trim();
      if (!trimmed || tab.tabId == null) return;
      post({
        op: 'instruct',
        text: trimmed,
        agentSkillId: opts?.agentSkillId,
        focus: opts?.focus,
        liveTools: opts?.liveTools,
        tab: { tabId: tab.tabId, url: tab.url, windowId: tab.windowId, title: tab.title },
      });
    },
    [post, tab],
  );

  const focusSession = useCallback((target: string) => {
    const session = sessions.find((s) => s.sessionId === target);
    if (!session) return;
    void (async () => {
      if (session.windowId >= 0) await browser.windows.update(session.windowId, { focused: true }).catch(() => undefined);
      await browser.tabs.update(session.currentTabId, { active: true }).catch(() => undefined);
    })();
  }, [sessions]);

  const restore = useCallback(
    async (target: string) => {
      if (tab.tabId == null) return;
      const live = sessions.find((s) => s.sessionId === target);
      if (live) return focusSession(target);
      post({
        op: 'restore',
        sessionId: target,
        tab: { tabId: tab.tabId, url: tab.url, windowId: tab.windowId, title: tab.title },
      });
    },
    [post, sessions, tab, focusSession],
  );

  return {
    items,
    running: displayed?.runId != null,
    sessionId,
    session: displayed,
    sessions,
    completed,
    send,
    draft,
    mapSite: useCallback(() => send(`@${SITE_MAPPER_SKILL} map this site`), [send]),
    activateMap: useCallback(
      (exactHost?: boolean) => {
        if (draft) post({ op: 'activateMap', stagingId: draft.stagingId, exactHost });
      },
      [draft, post],
    ),
    discardMap: useCallback(() => {
      if (draft) post({ op: 'discardMap', stagingId: draft.stagingId });
    }, [draft, post]),
    recording,
    startRecording: useCallback(
      (captureValues: boolean) => {
        post({ op: 'startRecording', captureValues });
      },
      [post],
    ),
    stopRecording: useCallback(() => {
      post({ op: 'stopRecording' });
    }, [post]),
    tools,
    toolOffer: offer,
    autoRunReady,
    keepTool: useCallback(
      (slug?: string, autoRun?: boolean) => {
        if (offer && tab.tabId != null) {
          post({ op: 'keepTool', toolkitId: offer.toolkitId, tabId: tab.tabId, slug, autoRun });
        }
      },
      [offer, post, tab.tabId],
    ),
    dismissTool: useCallback(() => {
      if (offer) post({ op: 'dismissTool', toolkitId: offer.toolkitId });
    }, [offer, post]),
    forgetTool: useCallback(
      (id: string) => {
        post({ op: 'forgetTool', id });
      },
      [post],
    ),
    setAutoRun: useCallback(
      (id: string, on: boolean) => {
        post({ op: 'autoRunTool', id, on });
      },
      [post],
    ),
    runTool: useCallback(
      (id: string) => {
        if (tab.tabId != null) {
          post({ op: 'runTool', id, tab: { tabId: tab.tabId, url: tab.url, windowId: tab.windowId, title: tab.title } });
        }
      },
      [post, tab],
    ),
    attachFile: useCallback(
      (file: NewFile) => {
        if (tab.tabId != null) {
          post({ op: 'attach', file, tab: { tabId: tab.tabId, url: tab.url, windowId: tab.windowId, title: tab.title } });
        }
      },
      [post, tab],
    ),
    addTabs: useCallback(
      (tabIds: number[]) => {
        if (tab.tabId != null) {
          post({ op: 'addTabs', tabIds, tab: { tabId: tab.tabId, url: tab.url, windowId: tab.windowId, title: tab.title } });
        }
      },
      [post, tab],
    ),
    removeTab: useCallback(
      (tabId: number) => {
        if (sessionId) post({ op: 'removeTab', sessionId, tabId });
      },
      [post, sessionId],
    ),
    detachFile: useCallback((fileId: string) => post({ op: 'detach', fileId }), [post]),
    reanalyzeFile: useCallback((fileId: string) => post({ op: 'reanalyze', fileId }), [post]),
    monitors,
    stopMonitor: useCallback(
      (monitorId: string) => {
        post({ op: 'stopMonitor', monitorId });
      },
      [post],
    ),
    cancel: useCallback(() => {
      if (sessionId) post({ op: 'cancel', sessionId });
    }, [post, sessionId]),
    decide: useCallback(
      (toolId: string, allow: boolean, remember?: boolean) => {
        if (sessionId) post({ op: 'decision', sessionId, toolId, allow, remember });
      },
      [post, sessionId],
    ),
    clear: useCallback(() => {
      if (!sessionId) return;
      forget(sessionId, EXTERNAL_VIEW);
      post({ op: 'endSession', sessionId });
    }, [post, sessionId, forget]),
    endSession: useCallback(
      (target: string) => {
        forget(target);
        post({ op: 'endSession', sessionId: target });
      },
      [post, forget],
    ),
    restore,
    focusSession,
  };
}