@oh-my-pi/pi-coding-agent 14.5.11 → 14.5.12

package/src/export/html/template.js

@@ -1078,17 +1078,24 @@
         return html;
       }
 
-      function renderPuppeteer(name, args, result, ctx) {
+      function renderBrowser(name, args, result, ctx) {
         const action = str(args.action) || '?';
+        const tabName = str(args.name);
         const badges = [];
+        if (tabName) badges.push('name=' + tabName);
         if (args.url) badges.push(String(args.url));
-        if (args.selector) badges.push('selector=' + args.selector);
-        if (args.element_id != null) badges.push('id=' + args.element_id);
-        let head = '<span class="tool-name">puppeteer</span> <span class="tool-badge">' + escapeHtml(action) + '</span>';
+        if (args.app && typeof args.app === 'object') {
+          if (args.app.path) badges.push('app=' + shortenPath(String(args.app.path)));
+          else if (args.app.cdp_url) badges.push('cdp=' + String(args.app.cdp_url));
+        }
+        if (args.all) badges.push('all');
+        if (args.kill) badges.push('kill');
+        let head = '<span class="tool-name">browser</span> <span class="tool-badge">' + escapeHtml(action) + '</span>';
         for (const b of badges) head += ' <span class="tool-badge">' + escapeHtml(String(b)) + '</span>';
         let html = '<div class="tool-header">' + head + '</div>';
-        if (args.script) html += codeBlock(String(args.script), 'javascript');
-        if (args.text) html += '<div class="tool-output"><div>' + escapeHtml(String(args.text)) + '</div></div>';
+        if (action === 'run' && args.code) {
+          html += codeBlock(String(args.code), 'javascript');
+        }
         if (result) {
           html += ctx.renderResultImages();
           const output = ctx.getResultText();
@@ -1277,7 +1284,8 @@
         web_search: renderWebSearch,
         fetch: renderFetch,
         debug: renderDebug,
-        puppeteer: renderPuppeteer,
+        puppeteer: renderBrowser,
+        browser: renderBrowser,
         inspect_image: renderInspectImage,
         generate_image: renderGenerateImage,
         ask: renderAsk,

package/src/ipy/gateway-coordinator.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import { createServer } from "node:net";
 import * as path from "node:path";
+import { Process } from "@oh-my-pi/pi-natives";
 import { getAgentDir, isEnoent, logger, procmgr } from "@oh-my-pi/pi-utils";
 import type { Subprocess } from "bun";
 import { Settings } from "../config/settings";
@@ -300,7 +301,7 @@ async function startGatewayProcess(
 
 async function killGateway(pid: number, context: string): Promise<void> {
 	try {
-		await procmgr.terminate({ target: pid });
+		await Process.fromPid(pid)?.terminate();
 	} catch (err) {
 		logger.warn("Failed to kill shared gateway process", {
 			error: err instanceof Error ? err.message : String(err),

package/src/prompts/tools/atom.md

@@ -36,7 +36,7 @@ Lid=       blank the anchored line's content but KEEP the line (results in an em
 - To insert ABOVE a line, you **MUST** use `^Lid` then `+TEXT`. To insert above line 1, you **MUST** use `^` (BOF) then `+TEXT`. To insert below a line, you **MUST** use `@Lid` then `+TEXT`.
 - Multiple `---PATH` sections **MAY** appear in one input; each section is applied in order.
 - `!rm` / `!mv DEST` **MUST NOT** be combined with line edits in the same section.
-- Lids contain a content hash. If a line has changed since you read it, the tool rejects the edit and shows the current content; you **MUST** re-read and retry with fresh Lids. Small drift (≤5 lines) where the original hash still matches a nearby line auto-rebases with a warning. Larger shifts may show a hash-only candidate, but two-letter hashes collide; verify surrounding content or re-read before using it.
+- Lids contain a content hash. If a line has changed since you read it, the tool rejects the edit and shows the current content; you **MUST** re-read and retry with fresh Lids.
 - After `+TEXT` (or `+`) the cursor advances past the inserted line, so consecutive `+TEXT` ops stack in order. After `Lid=TEXT` the cursor sits on the modified anchor; after `-Lid` it sits on the slot the deleted line vacated. You **MUST** use a fresh `@Lid` / `^Lid` / `^` / `$` to reposition.
 - The tool is syntax-blind: it will not check brackets, indentation, table column counts, or fence integrity. You **MUST** verify indentation-sensitive or structured files after editing (Python, Markdown tables/fences).
 - A section whose PATH does not yet exist creates the file from your `+TEXT` lines (use `^` or `$` then `+TEXT…`). No separate "create file" op is needed.
@@ -83,7 +83,7 @@ Lid=       blank the anchored line's content but KEEP the line (results in an em
 \	return (name || DEF).trim().toUpperCase();
 \}
 
-# Replace a block with a longer multi-line block, including blank lines (canonical form for refactors)
+# Replace one contiguous block when the existing lines themselves change; the replacement may have more/fewer lines than the selected range
 ---a.ts
 {{hrefr 3}}..{{hrefr 6}}=/** Format a display label, falling back to DEF when empty. */
 \export function label(name: string): string {
@@ -139,6 +139,7 @@ $
 - Current/added preview lines include fresh `LINE+hash|content` anchors. Removed preview lines show deleted content and **MUST NOT** be reused as anchors.
 - You **MUST** emit only lines that change. You **MUST NOT** echo unchanged context; the anchor implies position.
 - You **MUST NOT** write `Lid=<sameTextThatIsAlreadyOnThatLine>`; the tool reports a no-op (no change applied). Emit `Lid=TEXT` only when TEXT differs.
+- You **MUST NOT** use `Lid=<originalLineContent>` + `\continuations` as an "insert after" idiom. That form is a *replacement*: its first line lands at the anchor, and its continuations push the original next line down. When the anchor is a closing brace and your continuations also end in `}`, the original line below — often itself `}` (a sibling block, mod, or impl closer) — sits adjacent to yours and you ship a duplicate `}`. For pure insertion, use `@Lid` + `+TEXT…` (after) or `^Lid` + `+TEXT…` (before). Never re-state the anchor's content as the first line of a replacement.
 - A line of the form `Lid|content` (a Lid, then `|`, then text, with NO leading `+`/`-`/`^`/`@`/`\`/`=`/`..`) is **FORBIDDEN**. That shape only appears in `read`/`grep` output as an anchor for *you*; it is never an edit op. If you copy a `Lid|content` line verbatim from a read into a patch, you have made an error — every edit op must start with `+`, `-`, `^`, `@`, `\`, `$`, `!`, or a Lid immediately followed by `=` or `..`.
 - To replace a contiguous block with new content, the canonical form is `LidA..LidB=FIRST_LINE` + `\NEXT_LINE…`. You **MUST NOT** write the old block and then the new block — that is unified-diff thinking and the tool does not understand it. If you find yourself emitting pre-image lines (with or without operators) before your new content, STOP and rewrite the section as a single range-replace.
 - TEXT after `=`, `+`, or `\` includes leading whitespace verbatim. You **MUST NOT** trim or re-indent it.

package/src/prompts/tools/browser.md

@@ -1,25 +1,70 @@
-Navigates, clicks, types, scrolls, drags, queries DOM content, and captures screenshots.
+Drives a real Chromium tab with full puppeteer access via JS execution.
 
 <instruction>
-- For fetching static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL — it returns clean reader-mode text without spinning up a browser. Use this tool only when you need JS execution, authentication, or interactive actions.
-- `"open"` starts a headless session (or implicitly on first action); `"goto"` navigates to `url`; `"close"` releases the browser
-- `"observe"` captures a numbered accessibility snapshot — prefer `click_id`/`type_id`/`fill_id` using returned `element_id` values; flags: `include_all`, `viewport_only`
-- `"click"`, `"type"`, `"fill"`, `"press"`, `"scroll"`, `"drag"` for selector-based interactions — prefer ARIA/text selectors (`p-aria/[name="Sign in"]`, `p-text/Continue`) over brittle CSS
-- `"click_id"`, `"type_id"`, `"fill_id"` to interact with observed elements without selectors
-- `"wait_for_selector"` before interacting when the page is dynamic
-- `"evaluate"` runs a JS expression in page context
-- `"get_text"`, `"get_html"`, `"get_attribute"` for DOM queries — batch via `args: [{ selector, attribute? }]`
-- `"extract_readable"` returns reader-mode content; `format`: `"markdown"` (default) or `"text"`
-- `"screenshot"` captures images (optionally with `selector`); can save to disk via `path`
+- For fetching static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL — reader-mode text without spinning up a browser. Use this tool when you need JS execution, authentication, or interactive actions.
+- Three actions only:
+  - `open` — acquire (or reuse) a named tab. `name` defaults to `"main"`. Optional `url` navigates after the tab is ready. Optional `viewport` sets dimensions. Optional `dialogs: "accept" | "dismiss"` auto-handles `alert`/`confirm`/`beforeunload` so navigation/clicks don't hang (default: leave dialogs unhandled — page hangs until caller wires `page.on('dialog', …)`).
+  - `close` — release a tab by `name`, or every tab with `all: true`. For spawned-app browsers, set `kill: true` to terminate the process tree (default leaves it running).
+  - `run` — execute JS against an existing tab. The `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The function's return value is JSON-stringified into the tool result; multiple `display(value)` calls accumulate text/images.
+- Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.
+- Browser kinds, selected by the `app` field on `open`:
+  - default (no `app`) → headless Chromium with stealth patches.
+  - `app.path` → spawn an absolute binary (Electron/CDP). If a running instance already exposes a CDP port, it is reused; otherwise stale instances are killed and a fresh one is spawned. No stealth patches — never tamper with a real desktop app.
+  - `app.cdp_url` → connect to an existing CDP endpoint (e.g. `http://127.0.0.1:9222`).
+  - `app.target` (with `path`/`cdp_url`) — substring matched against url+title to pick a BrowserWindow when the app exposes several.
+- Inside `run`, `tab` exposes high-level helpers; reach for `page` (raw puppeteer Page) when you need anything they don't cover. Available helpers:
+  - `tab.goto(url, { waitUntil? })` — clears the element cache and navigates.
+  - `tab.observe({ includeAll?, viewportOnly? })` — accessibility snapshot. Returns `{ url, title, viewport, scroll, elements: [{ id, role, name, value, states, … }] }`. Element ids are stable until the next observe/goto.
+  - `tab.id(n)` — resolves an element id from the most recent observe to a real `ElementHandle` you can `.click()`, `.type()`, etc.
+  - `tab.click(selector)` / `tab.type(selector, text)` / `tab.fill(selector, value)` / `tab.press(key, { selector? })` / `tab.scroll(dx, dy)` — selector-based actions.
+  - `tab.waitFor(selector)` — waits until the selector is attached, returns the resolved `ElementHandle` for chaining (e.g. `const btn = await tab.waitFor('text/Submit'); await btn.click();`).
+  - `tab.drag(from, to)` — drag from one point to another. Each endpoint is either a selector string (drag center-to-center) or a `{ x, y }` viewport-coordinate point (e.g. for canvases, sliders).
+  - `tab.scrollIntoView(selector)` — scroll the matching element to the center of the viewport (use before clicking off-screen elements).
+  - `tab.select(selector, …values)` — set the selected option(s) on a `<select>`. Returns the values that ended up selected. `tab.fill` does **NOT** work for selects.
+  - `tab.uploadFile(selector, …filePaths)` — attach files to an `<input type="file">`. Paths resolve relative to cwd.
+  - `tab.waitForUrl(pattern, { timeout? })` — pattern is a substring or `RegExp`. Polls `location.href` so it works for SPA pushState navigations, not just real navigations. Returns the matched URL.
+  - `tab.waitForResponse(pattern, { timeout? })` — pattern is a substring, `RegExp`, or `(response) => boolean`. Returns the raw puppeteer `HTTPResponse` (call `.text()` / `.json()` / `.status()` / `.headers()` on it).
+  - `tab.evaluate(fn, …args)` — sugar for `page.evaluate` with the abort signal already wired. Use this instead of dropping to `page.evaluate` for ad-hoc DOM reads.
+  - `tab.screenshot({ selector?, fullPage?, save?, silent? })` — auto-attaches the image to the tool output unless `silent: true`. Saves full-res to `save` (or `browser.screenshotDir` setting) and a downscaled copy to the model.
+  - `tab.extract(format = "markdown")` — Readability-extracted page content.
+- Selectors accept CSS as well as puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`. Playwright-style `p-aria/[name="…"]`, `p-text/…`, etc. are normalized.
+- Default to `tab.observe()` over `tab.screenshot()` for understanding page state. Screenshot only when visual appearance matters.
 </instruction>
 
 <critical>
-**You **MUST** default to `observe`, not `screenshot`.**
-- `observe` is cheaper, faster, and returns structured data — use it to understand page state, find elements, and plan interactions.
-- You **SHOULD** only use `screenshot` when visual appearance matters (verifying layout, debugging CSS, capturing a visual artifact for the user).
-- You **MUST NOT** screenshot just to "see what's on the page" — `observe` gives you that with element IDs you can act on immediately.
+- You **MUST** call `open` before `run`. `run` does not implicitly create a tab.
+- You **MUST NOT** screenshot just to "see what's on the page" — `tab.observe()` returns structured data with element ids you can act on immediately.
+- After a `tab.goto()` or any navigation, prior element ids from `tab.observe()` are invalidated. Re-observe before referencing them.
+- `code` runs with full Node access. Treat it as your code, not sandboxed code.
 </critical>
 
+<examples>
+# Open a tab and read structured page data
+`{"action":"open","name":"docs","url":"https://example.com"}`
+`{"action":"run","name":"docs","code":"const obs = await tab.observe(); display(obs); return obs.elements.length;"}`
+
+# Click an observed element by id
+`{"action":"run","name":"docs","code":"const obs = await tab.observe(); const link = obs.elements.find(e => e.role === 'link' && e.name === 'Sign in'); assert(link, 'Sign in link missing'); await (await tab.id(link.id)).click();"}`
+
+# Save a full-page screenshot to disk
+`{"action":"run","name":"docs","code":"await tab.screenshot({ fullPage: true, save: 'screenshot.png' });"}`
+
+# Fill and submit a form via selectors
+`{"action":"run","name":"docs","code":"await tab.fill('input[name=email]', 'me@example.com'); await tab.click('text/Continue');"}`
+
+# Attach to an existing Electron app
+`{"action":"open","name":"cursor","app":{"path":"/Applications/Cursor.app/Contents/MacOS/Cursor"}}`
+
+# Close one tab (browser stays alive if other tabs reference it)
+`{"action":"close","name":"docs"}`
+
+# Close every tab; leave spawned apps running
+`{"action":"close","all":true}`
+
+# Close every tab and kill spawned-app processes too
+`{"action":"close","all":true,"kill":true}`
+</examples>
+
 <output>
-Text for navigation/DOM queries, images for screenshots.
+Per call: any `display(value)` outputs (text/images) followed by the JSON-stringified return value of the `code` function. `run` always produces at least a status line.
 </output>

package/src/session/agent-session.ts

@@ -52,16 +52,8 @@ import {
 	parseRateLimitReason,
 	streamSimple,
 } from "@oh-my-pi/pi-ai";
-import { killTree, MacOSPowerAssertion } from "@oh-my-pi/pi-natives";
-import {
-	abortableSleep,
-	getAgentDbPath,
-	isEnoent,
-	logger,
-	prompt,
-	Snowflake,
-	setNativeKillTree,
-} from "@oh-my-pi/pi-utils";
+import { MacOSPowerAssertion } from "@oh-my-pi/pi-natives";
+import { abortableSleep, getAgentDbPath, isEnoent, logger, prompt, Snowflake } from "@oh-my-pi/pi-utils";
 import type { AsyncJob, AsyncJobManager } from "../async";
 import type { Rule } from "../capability/rule";
 import { MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
@@ -580,8 +572,6 @@ export class AgentSession {
 	}
 
 	constructor(config: AgentSessionConfig) {
-		setNativeKillTree(killTree);
-
 		this.agent = config.agent;
 		this.sessionManager = config.sessionManager;
 		this.settings = config.settings;

package/src/tools/browser/attach.ts

@@ -0,0 +1,175 @@
+import * as net from "node:net";
+import { Process, ProcessStatus } from "@oh-my-pi/pi-natives";
+import type { Browser, Page } from "puppeteer-core";
+import { ToolError, throwIfAborted } from "../tool-errors";
+
+export const ATTACH_TARGET_SKIP_PATTERN =
+	/request[\s_-]?handler|devtools|background[\s_-]?(?:page|host)|service[\s_-]?worker/i;
+
+/**
+ * Allocate an unused TCP port on 127.0.0.1 by binding to port 0 and reading
+ * back the kernel-assigned port. There's a small race between close and the
+ * subsequent bind in the launched app, but Chromium's listener will retry.
+ */
+export async function findFreeCdpPort(): Promise<number> {
+	const { promise, resolve, reject } = Promise.withResolvers<number>();
+	const server = net.createServer();
+	server.unref();
+	server.once("error", reject);
+	server.listen(0, "127.0.0.1", () => {
+		const addr = server.address();
+		if (addr && typeof addr === "object" && typeof addr.port === "number") {
+			const port = addr.port;
+			server.close(closeErr => (closeErr ? reject(closeErr) : resolve(port)));
+		} else {
+			server.close();
+			reject(new Error("Failed to allocate ephemeral CDP port"));
+		}
+	});
+	return promise;
+}
+
+/** Poll `${cdpUrl}/json/version` until it responds with 200, with abort + timeout support. */
+export async function waitForCdp(cdpUrl: string, timeoutMs: number, signal?: AbortSignal): Promise<void> {
+	const deadline = Date.now() + timeoutMs;
+	let lastErr: unknown;
+	const probeUrl = `${cdpUrl.replace(/\/+$/, "")}/json/version`;
+	while (Date.now() < deadline) {
+		throwIfAborted(signal);
+		const probeTimeout = AbortSignal.timeout(2000);
+		const probeSignal = signal ? AbortSignal.any([signal, probeTimeout]) : probeTimeout;
+		try {
+			const res = await fetch(probeUrl, { signal: probeSignal });
+			if (res.ok) {
+				await res.body?.cancel();
+				return;
+			}
+			lastErr = new Error(`HTTP ${res.status}`);
+			await res.body?.cancel();
+		} catch (err) {
+			if (signal?.aborted) throwIfAborted(signal);
+			lastErr = err;
+		}
+		await Bun.sleep(150);
+	}
+	throw new ToolError(
+		`Timed out waiting for CDP endpoint ${cdpUrl}${lastErr instanceof Error ? `: ${lastErr.message}` : ""}`,
+	);
+}
+
+/**
+ * Pull a `--remote-debugging-port=<n>` value out of an argv array (Chromium
+ * accepts both `--flag=value` and `--flag value`). Returns null if absent or
+ * malformed.
+ */
+export function findCdpPortInArgs(args: string[]): number | null {
+	for (const arg of args) {
+		const m = /^--remote-debugging-port=(\d+)$/.exec(arg);
+		if (m) {
+			const port = Number.parseInt(m[1]!, 10);
+			if (Number.isFinite(port) && port > 0) return port;
+		}
+	}
+	for (let i = 0; i < args.length - 1; i++) {
+		if (args[i] === "--remote-debugging-port") {
+			const port = Number.parseInt(args[i + 1]!, 10);
+			if (Number.isFinite(port) && port > 0) return port;
+		}
+	}
+	return null;
+}
+
+/** One-shot probe: returns true when `/json/version` answers 200 within the timeout. */
+export async function probeCdpAt(port: number, signal?: AbortSignal): Promise<boolean> {
+	const probeTimeout = AbortSignal.timeout(1500);
+	const probeSignal = signal ? AbortSignal.any([signal, probeTimeout]) : probeTimeout;
+	try {
+		const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: probeSignal });
+		await res.body?.cancel();
+		return res.ok;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * If any running instance of `exe` was launched with `--remote-debugging-port`
+ * and that endpoint actually answers, return it so attach can reuse it instead
+ * of killing and respawning. Idempotent re-attaches are the common case.
+ */
+export async function findReusableCdp(
+	exe: string,
+	signal?: AbortSignal,
+): Promise<{ cdpUrl: string; pid: number } | null> {
+	const candidates = Process.fromPath(exe).filter(p => p.status() === ProcessStatus.Running);
+	for (const proc of candidates) {
+		let args: string[];
+		try {
+			args = proc.args();
+		} catch {
+			continue;
+		}
+		const port = findCdpPortInArgs(args);
+		if (port === null) continue;
+		if (await probeCdpAt(port, signal)) {
+			return { cdpUrl: `http://127.0.0.1:${port}`, pid: proc.pid };
+		}
+	}
+	return null;
+}
+
+/**
+ * Pick the best page target on an attached browser. Without a matcher, prefer
+ * a page that doesn't look like a helper window (devtools, request handler,
+ * background pages); with a matcher, return the first url+title substring hit.
+ */
+export async function pickElectronTarget(browser: Browser, matcher?: string): Promise<Page> {
+	const pages = await browser.pages();
+	if (!pages.length) {
+		throw new ToolError("No page targets available on the attached browser");
+	}
+	const enriched = await Promise.all(
+		pages.map(async page => ({
+			page,
+			url: page.url(),
+			title: ((await page.title().catch(() => "")) ?? "").trim(),
+		})),
+	);
+	if (matcher) {
+		const needle = matcher.toLowerCase();
+		const hit = enriched.find(p => p.url.toLowerCase().includes(needle) || p.title.toLowerCase().includes(needle));
+		if (hit) return hit.page;
+		const summary = enriched.map(p => `- ${p.title || "(untitled)"}  ${p.url}`).join("\n");
+		throw new ToolError(`No page target matched ${JSON.stringify(matcher)}. Available pages:\n${summary}`);
+	}
+	return (
+		enriched.find(p => !ATTACH_TARGET_SKIP_PATTERN.test(p.url) && !ATTACH_TARGET_SKIP_PATTERN.test(p.title))?.page ??
+		enriched[0]!.page
+	);
+}
+
+/**
+ * SIGTERM the process tree, wait briefly, then SIGKILL anything still alive.
+ * Single-process variant for our own spawned children.
+ */
+export async function gracefulKillTreeOnce(pid: number, gracePeriodMs = 2000): Promise<void> {
+	const process = Process.fromPid(pid);
+	if (!process) return;
+	await process.terminate({ gracefulMs: gracePeriodMs, timeoutMs: 500 });
+}
+
+/**
+ * Multi-process variant for attach: find every PID running `executablePath`
+ * (single-instance apps may keep an orphan around) and tear them all down.
+ */
+export async function killExistingByPath(executablePath: string, signal?: AbortSignal): Promise<number> {
+	const processes = Process.fromPath(executablePath);
+	if (!processes.length) return 0;
+	const results = await Promise.all(
+		processes.map(async process => {
+			throwIfAborted(signal);
+			return await process.terminate({ gracefulMs: 3000, timeoutMs: 1000 });
+		}),
+	);
+	return results.length;
+}