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.

feat(bridge): stream run events to extension pages over a port

Shahriar8000a6b2a700
diff --git a/lib/bridge/run-port.ts b/lib/bridge/run-port.ts
new file mode 100644
index 0000000..896b0d2
--- /dev/null
+++ b/lib/bridge/run-port.ts
@@ -0,0 +1,100 @@
+import { browser, type Browser } from 'wxt/browser';
+import type { RunEvent } from '@/lib/actions/protocol';
+import { cancelRun, onRunEvent, resetConversation, sendDecision, sendInstruction } from './socket';
+
+export const RUN_PORT = 'voicelink/run';
+
+/**
+ * How long a run keeps going after the last extension page stops watching. Long enough for the
+ * popup to hand off to the side panel it just opened, short enough that nothing drives the
+ * browser unobserved for meaningfully longer than that.
+ */
+const UNWATCHED_GRACE_MS = 10_000;
+
+/** Extension page → background worker. */
+export type RunCommand =
+ | { op: 'instruct'; text: string }
+ | { op: 'cancel' }
+ | { op: 'decision'; toolId: string; allow: boolean }
+ | { op: 'reset' };
+
+/** Background worker → extension pages. */
+export type RunMessage =
+ | { op: 'event'; runId: string; event: RunEvent }
+ /** Sent on connect, and whenever a run starts or ends, so a late page knows where it stands. */
+ | { op: 'active'; runId: string | null };
+
+const ports = new Set<Browser.runtime.Port>();
+let activeRunId: string | null = null;
+let unwatchedTimer: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * Bridge the daemon's run events to whichever extension pages are open. A one-shot
+ * `sendMessage` would be wrong here — text arrives token by token, so the panel holds a port.
+ */
+export function serveRunPorts(): void {
+ onRunEvent((runId, event) => {
+ if (event.kind === 'done' || event.kind === 'error') setActiveRun(null);
+ broadcast({ op: 'event', runId, event });
+ });
+
+ browser.runtime.onConnect.addListener((port) => {
+ if (port.name !== RUN_PORT) return;
+ ports.add(port);
+ clearTimeout(unwatchedTimer);
+ post(port, { op: 'active', runId: activeRunId });
+
+ port.onMessage.addListener((message) => handle(message as RunCommand));
+ port.onDisconnect.addListener(() => {
+ ports.delete(port);
+ if (ports.size === 0 && activeRunId) scheduleUnwatchedCancel();
+ });
+ });
+}
+
+function handle(command: RunCommand): void {
+ switch (command.op) {
+ case 'instruct':
+ // One run at a time: the daemon rejects a second, but not starting it is clearer.
+ if (activeRunId) return;
+ setActiveRun(sendInstruction(command.text));
+ return;
+ case 'cancel':
+ if (activeRunId) cancelRun(activeRunId);
+ return;
+ case 'decision':
+ if (activeRunId) sendDecision(activeRunId, command.toolId, command.allow);
+ return;
+ case 'reset':
+ resetConversation();
+ return;
+ }
+}
+
+function setActiveRun(runId: string | null): void {
+ activeRunId = runId;
+ if (runId) clearTimeout(unwatchedTimer);
+ broadcast({ op: 'active', runId });
+}
+
+function scheduleUnwatchedCancel(): void {
+ clearTimeout(unwatchedTimer);
+ unwatchedTimer = setTimeout(() => {
+ if (ports.size > 0 || !activeRunId) return;
+ cancelRun(activeRunId);
+ setActiveRun(null);
+ }, UNWATCHED_GRACE_MS);
+}
+
+function broadcast(message: RunMessage): void {
+ for (const port of ports) post(port, message);
+}
+
+function post(port: Browser.runtime.Port, message: RunMessage): void {
+ try {
+ port.postMessage(message);
+ } catch {
+ // The page went away between the disconnect event and this send.
+ ports.delete(port);
+ }
+}
diff --git a/lib/bridge/use-run.ts b/lib/bridge/use-run.ts
new file mode 100644
index 0000000..c80531c
--- /dev/null
+++ b/lib/bridge/use-run.ts
@@ -0,0 +1,134 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { browser, type Browser } from 'wxt/browser';
+import type { RunEvent } from '@/lib/actions/protocol';
+import { RUN_PORT, type RunCommand, type RunMessage } from './run-port';
+
+/** One rendered row of the transcript. Tool rows mutate in place as their result arrives. */
+export type RunItem =
+ | { kind: 'user'; id: string; text: string }
+ | { kind: 'assistant'; id: string; text: string }
+ | { kind: 'notice'; id: string; tone: 'info' | 'error'; text: string }
+ | {
+ kind: 'tool';
+ id: string;
+ action: string;
+ input: unknown;
+ summary?: string;
+ ok?: boolean;
+ /** True while the run is blocked waiting for the user to allow or deny this call. */
+ awaiting?: boolean;
+ };
+
+export interface Run {
+ items: RunItem[];
+ running: boolean;
+ send: (text: string) => void;
+ cancel: () => void;
+ decide: (toolId: string, allow: boolean) => void;
+ clear: () => void;
+}
+
+/**
+ * Live view of the agent, for an extension page. Holds a port to the background worker, which
+ * owns the daemon socket — pages come and go, the connection does not.
+ */
+export function useRun(): Run {
+ const [items, setItems] = useState<RunItem[]>([]);
+ const [running, setRunning] = useState(false);
+ const port = useRef<Browser.runtime.Port | null>(null);
+
+ useEffect(() => {
+ const connected = browser.runtime.connect({ name: RUN_PORT });
+ port.current = connected;
+
+ connected.onMessage.addListener((message) => {
+ const runMessage = message as RunMessage;
+ if (runMessage.op === 'active') setRunning(runMessage.runId !== null);
+ else setItems((previous) => reduce(previous, runMessage.event));
+ });
+ // The worker can be torn down; a page that outlives it must not hold a dead port.
+ connected.onDisconnect.addListener(() => {
+ if (port.current === connected) port.current = null;
+ });
+
+ return () => {
+ port.current = null;
+ connected.disconnect();
+ };
+ }, []);
+
+ const post = useCallback((command: RunCommand) => port.current?.postMessage(command), []);
+
+ const send = useCallback(
+ (text: string) => {
+ const trimmed = text.trim();
+ if (!trimmed) return;
+ setItems((previous) => [...previous, { kind: 'user', id: nextId(), text: trimmed }]);
+ setRunning(true);
+ post({ op: 'instruct', text: trimmed });
+ },
+ [post],
+ );
+
+ const clear = useCallback(() => {
+ setItems([]);
+ post({ op: 'reset' });
+ }, [post]);
+
+ return {
+ items,
+ running,
+ send,
+ cancel: useCallback(() => post({ op: 'cancel' }), [post]),
+ decide: useCallback(
+ (toolId: string, allow: boolean) => {
+ setItems((previous) => patchTool(previous, toolId, { awaiting: false }));
+ post({ op: 'decision', toolId, allow });
+ },
+ [post],
+ ),
+ clear,
+ };
+}
+
+function reduce(items: RunItem[], event: RunEvent): RunItem[] {
+ switch (event.kind) {
+ case 'started':
+ return [...items, { kind: 'notice', id: nextId(), tone: 'info', text: `Loaded skill: ${event.skill}` }];
+
+ case 'text': {
+ // Deltas append to the assistant row still being written; a tool call between two
+ // paragraphs closes the first one, so the next delta starts a fresh row.
+ const last = items.at(-1);
+ if (last?.kind === 'assistant') {
+ return [...items.slice(0, -1), { ...last, text: last.text + event.delta }];
+ }
+ return [...items, { kind: 'assistant', id: nextId(), text: event.delta }];
+ }
+
+ case 'tool':
+ return [...items, { kind: 'tool', id: event.toolId, action: event.action, input: event.input }];
+
+ case 'approval':
+ return patchTool(items, event.toolId, { awaiting: true });
+
+ case 'toolResult':
+ return patchTool(items, event.toolId, { ok: event.ok, summary: event.summary, awaiting: false });
+
+ case 'done':
+ // `end_turn` is the ordinary ending and needs no announcement; anything else does.
+ return event.stopReason === 'end_turn'
+ ? items
+ : [...items, { kind: 'notice', id: nextId(), tone: 'info', text: `Stopped: ${event.stopReason}` }];
+
+ case 'error':
+ return [...items, { kind: 'notice', id: nextId(), tone: 'error', text: `${event.code}: ${event.message}` }];
+ }
+}
+
+function patchTool(items: RunItem[], toolId: string, patch: Partial<Extract<RunItem, { kind: 'tool' }>>): RunItem[] {
+ return items.map((item) => (item.kind === 'tool' && item.id === toolId ? { ...item, ...patch } : item));
+}
+
+let counter = 0;
+const nextId = () => `item-${counter++}`;
diff --git a/lib/bridge/use-stored-files.ts b/lib/bridge/use-stored-files.ts
new file mode 100644
index 0000000..a1a2854
--- /dev/null
+++ b/lib/bridge/use-stored-files.ts
@@ -0,0 +1,32 @@
+import { useEffect, useState } from 'react';
+import { browser } from 'wxt/browser';
+import { FILES_INDEX_KEY, type StoredFileMeta } from './file-store';
+
+/**
+ * The stored-file index, kept live through `storage.local.onChanged` so it stays in sync across
+ * extension pages and re-renders pending→ready as the background writes each file's summary back.
+ */
+export function useStoredFiles(): StoredFileMeta[] {
+ const [files, setFiles] = useState<StoredFileMeta[]>([]);
+
+ useEffect(() => {
+ let live = true;
+ void browser.storage.local.get(FILES_INDEX_KEY).then((stored) => {
+ const list = stored[FILES_INDEX_KEY];
+ if (live && Array.isArray(list)) setFiles(list as StoredFileMeta[]);
+ });
+ const listener = (changes: Record<string, { newValue?: unknown }>) => {
+ if (FILES_INDEX_KEY in changes) {
+ const next = changes[FILES_INDEX_KEY].newValue;
+ setFiles(Array.isArray(next) ? (next as StoredFileMeta[]) : []);
+ }
+ };
+ browser.storage.local.onChanged.addListener(listener);
+ return () => {
+ live = false;
+ browser.storage.local.onChanged.removeListener(listener);
+ };
+ }, []);
+
+ return files;
+}