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(protocol): extend the socket contract to v5

Shahriarcfe7641f1a1c
diff --git a/lib/actions/protocol.ts b/lib/actions/protocol.ts
index 809a670..a2c1e6e 100644
--- a/lib/actions/protocol.ts
+++ b/lib/actions/protocol.ts
@@ -1,10 +1,12 @@
import type { ToolDescriptor } from './manifest';
+import type { SkillDraft } from '@/lib/skills/format';
+import type { SiteMapDraft } from '@/lib/skills/site-map';
export const ACTION_CHANNEL = 'voicelink/action';
export const BRIDGE_CHANNEL = 'voicelink/bridge';
/** Bumped whenever the socket frames below change shape incompatibly. */
-export const SOCKET_PROTOCOL_VERSION = 3;
+export const SOCKET_PROTOCOL_VERSION = 5;
/** Loopback ports the daemon binds, in order; the extension probes the same list. */
export const DAEMON_PORTS = [8765, 8766, 8767] as const;
@@ -24,7 +26,11 @@ export type BridgeRequest =
| { channel: typeof BRIDGE_CHANNEL; op: 'disconnect' }
// Summarize a stored file: the worker reads its bytes from storage, runs the daemon
// round-trip, and writes the summary back to the file index. Only the id crosses here.
- | { channel: typeof BRIDGE_CHANNEL; op: 'analyzeFile'; fileId: string };
+ | { channel: typeof BRIDGE_CHANNEL; op: 'analyzeFile'; fileId: string }
+ // Push an uploaded skill to the daemon's skills directory, or take it back off. Same shape
+ // as `analyzeFile`: the worker owns the socket, so it reads the body from storage itself.
+ | { channel: typeof BRIDGE_CHANNEL; op: 'saveSkill'; skillId: string }
+ | { channel: typeof BRIDGE_CHANNEL; op: 'removeSkill'; skillId: string };
export type ActionResult<T = unknown> =
| { ok: true; data: T }
@@ -36,10 +42,15 @@ export type ActionResult<T = unknown> =
* panel draws — and a second copy would drift.
*/
export type RunEvent =
- /** The router picked a skill; the loop is about to start. */
- | { kind: 'started'; skill: string }
+ /**
+ * The router picked a skill; the loop is about to start. `overlays` names the site-exploration
+ * skills stacked on top of it, so the panel can show that an uploaded skill is in play.
+ */
+ | { kind: 'started'; skill: string; overlays?: string[] }
| { kind: 'text'; delta: string }
- | { kind: 'tool'; toolId: string; action: string; input: unknown }
+ // `source` is never set by the daemon: it marks a step the extension took by itself,
+ // through the local intent funnel, so the timeline can say the agent was not involved.
+ | { kind: 'tool'; toolId: string; action: string; input: unknown; source?: 'local' }
/** The action needs the user's blessing before it runs; answer with a `decision` frame. */
| { kind: 'approval'; toolId: string; action: string; input: unknown }
| { kind: 'toolResult'; toolId: string; ok: boolean; summary: string }
@@ -56,6 +67,21 @@ export type RunEvent =
*/
export type SocketAuth = { pairingToken: string } | { sessionKey: string };
+/**
+ * What the extension knows about the tab an instruction was typed against, used to decide
+ * which site-exploration skills apply. The URL only: a page controls its own title, and
+ * anything that reaches the system prompt has to be something a page cannot write.
+ */
+export interface RunContext {
+ url: string;
+ /**
+ * The tab the instruction was typed against. A mapping run pins itself to this, because it is
+ * autonomous for minutes and every action would otherwise re-resolve "the active tab" —
+ * following the user into whatever they switched to.
+ */
+ tabId?: number;
+}
+
/**
* Frames on the daemon socket. The extension dials out because an MV3 service worker
* cannot listen, so the daemon is the server and drives every invocation.
@@ -79,13 +105,15 @@ export type SocketFrame =
| { t: 'unauthorized'; reason: string; retryable: boolean }
| { t: 'describe'; id: string }
| { t: 'manifest'; id: string; tools: ToolDescriptor[] }
- | { t: 'invoke'; id: string; action: string; input?: unknown }
+ // `tabId` pins the call to one tab. Only a mapping run sets it: an autonomous multi-minute
+ // run must not follow the user into whatever tab they switch to mid-crawl.
+ | { t: 'invoke'; id: string; action: string; input?: unknown; tabId?: number }
| { t: 'result'; id: string; result: ActionResult }
| { t: 'ping'; id: string }
| { t: 'pong'; id: string }
// The agent harness. These four run the other way: the extension asks the daemon to think,
// and the daemon answers by invoking actions back down the same socket.
- | { t: 'instruct'; id: string; text: string }
+ | { t: 'instruct'; id: string; text: string; context?: RunContext }
| { t: 'cancel'; id: string }
| { t: 'decision'; id: string; toolId: string; allow: boolean }
| { t: 'reset' }
@@ -94,10 +122,46 @@ export type SocketFrame =
// answers with a `fileSummary` carrying the same `id`. `content` is base64. This runs
// outside the agent conversation — no skill, no browser tools, no single-run lock.
| { t: 'analyzeFile'; id: string; name: string; mime: string; size: number; content: string }
- | { t: 'fileSummary'; id: string; result: ActionResult<{ summary: string }> };
+ | { t: 'fileSummary'; id: string; result: ActionResult<{ summary: string }> }
+ // An uploaded skill, on its way to the daemon's skills directory. Structured fields rather
+ // than raw markdown: the daemon composes the front matter itself, so an upload can never
+ // write a field it was not offered. Both answer with `skillResult` on the same `id`.
+ | { t: 'saveSkill'; id: string; skill: SkillDraft }
+ | { t: 'deleteSkill'; id: string; name: string }
+ // Directory-form skills are removed by their own op: `deleteSkill` must never take a flat
+ // upload and a generated map of the same name down together.
+ | { t: 'deleteSiteMap'; id: string; name: string }
+ | { t: 'skillResult'; id: string; result: ActionResult<SavedSkill> }
+ // A mapping run finished and staged a skill the loader cannot yet see. The panel shows the
+ // rendered markdown; one of the next two frames decides its fate.
+ | { t: 'siteMapDraft'; id: string; draft: SiteMapDraft }
+ // `exactHost` narrows `acme.com` to the exact host mapped. The domain list itself is never
+ // sent: a caller-supplied array is a way to make a map fire on someone else's site.
+ | { t: 'activateSiteMap'; id: string; stagingId: string; exactHost?: boolean }
+ | { t: 'discardSiteMap'; id: string; stagingId: string };
+
+/** Where an uploaded skill landed on the daemon's disk. */
+export interface SavedSkill {
+ name: string;
+ /** Absolute path, so the panel can say where to go looking. Absent on delete. */
+ path?: string;
+ /** True when the write replaced an upload of the same name. */
+ replaced?: boolean;
+}
/** Frames the extension sends unprompted, rather than as a reply to a daemon request. */
-export const EXTENSION_REQUEST_FRAMES = ['instruct', 'cancel', 'decision', 'reset', 'analyzeFile'] as const;
+export const EXTENSION_REQUEST_FRAMES = [
+ 'instruct',
+ 'cancel',
+ 'decision',
+ 'reset',
+ 'analyzeFile',
+ 'saveSkill',
+ 'deleteSkill',
+ 'deleteSiteMap',
+ 'activateSiteMap',
+ 'discardSiteMap',
+] as const;
export type ExtensionRequest = Extract<SocketFrame, { t: (typeof EXTENSION_REQUEST_FRAMES)[number] }>;