1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
/**
* pi-browser-harness — browser control extension for pi.
*
* Gives pi agents full control of a real Chrome browser via CDP.
* Connects to the user's running Chrome (chrome://inspect/#remote-debugging),
* registers browser_* tools, and injects browser control guidance into the
* system prompt.
*
* Install:
* pi install npm:pi-browser-harness
* # or copy to .pi/extensions/pi-browser-harness/
*
* Commands:
* /browser-setup — guided setup wizard
* /browser-status — show client status and current page
* /browser-reload-daemon — restart the browser client
*
* Flags:
* --browser-namespace <name> — override namespace (default: auto)
* --browser-debug-clicks — enable debug click overlay
*/
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
import { type BrowserClient, createBrowserClient } from "./client";
import { getBrowserSystemPrompt } from "./prompt";
import { registerSetupCommand } from "./setup";
import { type BrowserState, defaultState, persistState, restoreState } from "./state";
import { registerAllTools } from "./registry";
import { cleanupTempDirs } from "./util/truncate";
import { createDaemonTransport } from "./cdp/daemon-transport";
export default function browserHarnessExtension(pi: ExtensionAPI): void {
const flagNs = pi.getFlag("browser-namespace") as string | undefined;
const namespace = flagNs ?? `pi-${Math.random().toString(36).slice(2, 10)}`;
let state: BrowserState = defaultState(namespace);
let client: BrowserClient | null = null;
let toolsRegistered = false;
pi.registerFlag("browser-namespace", {
description: "Browser daemon namespace. Default: auto-generated",
type: "string",
});
pi.registerFlag("browser-debug-clicks", {
description: "Enable debug click overlay (saves annotated screenshots to /tmp)",
type: "boolean",
default: false,
});
pi.registerCommand("browser-status", {
description: "Show browser connection status and current page",
handler: async (_args, ctx) => {
if (!client) {
ctx.ui.notify("Browser client not started. Run /browser-setup first.", "warning");
return;
}
const s = client.status();
const lines = [
`Browser: ${s.alive ? "🟢 Connected" : "🔴 Disconnected"}`,
`Session: ${s.sessionId ?? "none"}`,
];
if (s.remoteBrowserId) lines.push(`Browser ID: ${s.remoteBrowserId}`);
if (s.alive) {
const info = await client.pageInfo();
if (info.success) {
if ("dialog" in info.data) {
lines.push(`\n⚠️ Dialog open: ${info.data.dialog.type} — "${info.data.dialog.message}"`);
} else {
lines.push(
`\nCurrent Page:`,
` URL: ${info.data.url}`,
` Title: ${info.data.title}`,
` Viewport: ${info.data.width}x${info.data.height}`,
);
}
}
}
ctx.ui.notify(lines.join("\n"), "info");
},
});
pi.registerCommand("browser-reload-daemon", {
description: "Restart the browser client",
handler: async (_args, ctx) => {
if (!client) {
ctx.ui.notify("Browser client not started.", "warning");
return;
}
ctx.ui.notify("Restarting browser client...", "info");
await client.stop();
const r = await client.start();
if (r.success) {
ctx.ui.notify("Browser client restarted ✓", "info");
} else {
ctx.ui.notify(`Restart failed: ${r.error.message}`, "error");
}
},
});
pi.on("session_start", async (_event, ctx) => {
state = restoreState(ctx, state.namespace);
// Create the client lazily on first session. The daemon transport
// is created but NOT connected — that only happens when the user
// runs /browser-setup or a browser tool call finds an existing socket.
// This means zero Chrome prompts for non-browser pi sessions.
if (!client) {
const transport = createDaemonTransport(state.namespace);
const initialOwnership: { ownedTargetIds?: ReadonlyArray<string>; harnessWindowTargetId?: string } = {};
if (state.ownedTargetIds !== undefined) initialOwnership.ownedTargetIds = state.ownedTargetIds;
if (state.harnessWindowTargetId !== undefined) initialOwnership.harnessWindowTargetId = state.harnessWindowTargetId;
client = createBrowserClient({
namespace: state.namespace,
transport,
...(Object.keys(initialOwnership).length > 0 ? { initialOwnership } : {}),
onOwnershipChange: (snap) => {
state = {
...state,
ownedTargetIds: snap.ownedTargetIds,
...(snap.harnessWindowTargetId !== undefined
? { harnessWindowTargetId: snap.harnessWindowTargetId }
: {}),
};
// Ownership changes can fire from CDP events at any time,
// including after session replacement when pi's ctx is stale.
// Persistence is best-effort — failure must not crash the event consumer.
// ponytail: try/catch is the simplest guard against stale-ctx.
try { persistState(pi, state); } catch { /* stale ctx — safe to ignore */ }
},
});
}
// Do NOT call client.start() here — browser control is on-demand.
// The first browser tool call or /browser-setup triggers the actual
// daemon socket connection and Chrome prompt.
if (!toolsRegistered) {
registerAllTools(pi, client);
toolsRegistered = true;
}
registerSetupCommand(pi, client);
ctx.ui.setStatus(
"browser",
client.status().alive ? "🟢 Browser connected" : "🔴 Browser — run /browser-setup",
);
});
pi.on("session_shutdown", async () => {
persistState(pi, state);
if (client) {
try {
// Detach from the page target (removes the "Chrome is being controlled"
// banner) but keep the transport alive for the next session.
await client.detach();
} catch (e) {
console.warn("[pi-browser-harness] client.detach() failed during shutdown:", e);
}
// ponytail: keep the transport alive across sessions.
// Do NOT call client.stop() or null out client — the daemon connection
// persists and eliminates the per-session "Allow Remote Debugging" prompt.
// Only Chrome restart or daemon death triggers a new prompt.
}
await cleanupTempDirs();
});
pi.on("session_tree", async (_event, ctx) => {
state = restoreState(ctx, client?.namespace);
persistState(pi, state);
});
pi.on("before_agent_start", async (event) => {
if (!client || !client.status().alive) {
return {
systemPrompt:
event.systemPrompt +
`\n\n## Browser Control\n\nBrowser tools (browser_*) are available but the browser is not connected. Run /browser-setup.`,
};
}
return { systemPrompt: event.systemPrompt + getBrowserSystemPrompt() };
});
}
|
