pi-browser-use-lite 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 本文件记录已发布版本的用户可见变更。更细的过程见 git log。破坏性变更标 **BREAKING**。
 
+## 0.2.0 — 2026-11-09
+
+- **BREAKING**：删掉 `prompt.guidelines`。默认三条规则搬进 `chrome_act` 自己的 `promptGuidelines`；跨工具的规则写 AGENTS.md。写了这个键的配置会以 `prompt: unknown key` 启动失败。
+- `/chrome` 有参数补全：输入 `/chrome ` 列子命令，`/chrome authorize ` 列 on 与 off，每项带一句说明。
+- 关掉某个工具后，系统提示里不再留下点名它的规则：此前全局规则里的三条 `chrome_act` 规则在关掉 `chrome_act` 后仍然保留。
+- **BREAKING**：删掉 `policy.background` 与 `/chrome background`。点不动页面时由输入路径自己把标签与窗口带到前台；读操作照样不打扰。写了这个键的配置会以 `policy.background: unknown key` 启动失败。
+- 输入前的可见性检查改成自救：不可见就激活标签、把窗口带到前台，仍不可见才报错并说清原因（标签非活动、窗口最小化、被盖住）。
+- `chrome_tab new` 建的新标签在自己的窗口里是活动标签，不再出现「新标签点不动」。
+- README 说清自动化窗口不聚焦地打开、第一次点击或打字会把它带到前台。
+
+## 0.1.1 — 2026-11-09
+
+- 补中文 README：`README.zh-CN.md`，英文版顶部有切换链接，npm 包同时收录两份。
+
 ## 0.1.0 — 2026-11-08
 
 首版。

package/README.md

@@ -1,5 +1,7 @@
 # pi-browser-use-lite
 
+[简体中文](README.zh-CN.md) | **English**
+
 Five `chrome_*` tools that drive your own browser: the tabs you are already logged into, with your cookies and your sessions.
 
 The package has two halves. The pi extension registers the tools and runs a local bridge on `127.0.0.1`. The companion Chrome extension polls that bridge and runs each command through `chrome.debugger`.
@@ -17,6 +19,7 @@ The package has two halves. The pi extension registers the tools and runs a loca
 Behaviour worth knowing:
 
 - Each session gets its own browser window. The tools do not touch your own tabs. The tabs the session opened are closed when the session ends.
+- That window opens unfocused. The first click or keystroke raises it, because Chrome drops input to hidden pages. Reads never raise it.
 - Input goes through trusted CDP events, so pages that reject synthetic events still react.
 - Console and network capture starts at navigation, not at the first read.
 - Every failure carries a class and a `hint` that says what to do next.
@@ -39,7 +42,7 @@ Then authorize the tools for this session:
 /chrome authorize on
 ```
 
-Authorization ends with the session. Set `policy.authorizeOnStart` to skip this step.
+Authorization ends with the session. Set `policy.authorizeOnStart` to skip this step. Type `/chrome ` and press Tab to list the subcommands.
 
 ## Configuration
 
@@ -64,8 +67,6 @@ Without the file every value is the default. A wrong type or an unknown key fail
   // Session rules
   "policy": {
     "authorizeOnStart": false,  // true = the tools work without /chrome authorize on
-    "background": true,         // true = block every focusing call, chrome_tab switch included.
-                                //        Turn it off when the model must bring a page to the front
     "closeOwnTabsOnExit": true  // close the tabs this session opened when the session ends
   },
 
@@ -89,11 +90,6 @@ Without the file every value is the default. A wrong type or an unknown key fail
     "keepNewest": 20            // older screenshots in that directory are deleted
   },
 
-  // Global rules for the system prompt. These replace the three defaults; they do not extend them
-  "prompt": {
-    "guidelines": ["chrome_act: this is the user's real browser; confirm before destructive actions."]
-  },
-
   // Tool switches and names. Keep at least one enabled; names must be unique and must not shadow a host tool
   "tools": {
     "chrome_act": { "enabled": true, "name": "chrome_act" },

package/README.zh-CN.md

@@ -0,0 +1,147 @@
+# pi-browser-use-lite
+
+**[简体中文](README.zh-CN.md)** | [English](README.md)
+
+五个 `chrome_*` 工具，操作你自己的浏览器：你已经登录的标签页、你的 cookie 和会话。
+
+包分两半。pi 扩展注册这些工具，并在 `127.0.0.1` 上跑一个本地桥。配套的 Chrome 扩展轮询这个桥，用 `chrome.debugger` 执行每条命令。
+
+## 工具
+
+| 工具 | 做什么 |
+|---|---|
+| `chrome_act` | navigate、click、type、fill、press、hover、drag、scroll、upload、eval、wait、batch |
+| `chrome_see` | 快照：refs、text、changes、full；读控制台与网络日志 |
+| `chrome_tab` | list、new、switch、close |
+| `chrome_vision` | 截视口或整页 |
+| `chrome_cdp` | 一条裸 CDP 调用，另四个盖不住的用它 |
+
+值得知道的行为：
+
+- 每个会话一个独立浏览器窗口。工具不碰你自己的标签页。会话结束时关掉本会话开的标签。
+- 这个窗口不聚焦地打开。第一次点击或打字会把它带到前台，因为 Chrome 丢掉不可见页面的输入。读操作不会打扰你。
+- 输入走可信 CDP 事件，拒绝合成事件的页面也会响应。
+- 控制台与网络抓取从导航开始，不从第一次读取开始。
+- 每次失败都带类别和一句 `hint`，说明下一步做什么。
+
+## 安装
+
+```bash
+pi install npm:pi-browser-use-lite
+```
+
+扩展就在包里。每个浏览器装一次：
+
+1. 在 pi 里运行 `/chrome status`。扩展没连上时，回复会打印要加载的目录。
+2. 打开 `chrome://extensions`，开开发者模式，点「加载已解压的扩展程序」，选那个目录。
+3. 再跑一次 `/chrome status`。`connected: yes` 表示桥看到了扩展。
+
+然后给这次会话授权：
+
+```
+/chrome authorize on
+```
+
+授权随会话结束。想省这一步，把 `policy.authorizeOnStart` 设为 true。输入 `/chrome ` 再按 Tab 列出子命令。
+
+## 配置
+
+一个 JSON 文件：`<agent dir>/pi-browser-use-lite/config.json`。agent dir 是 `PI_CODING_AGENT_DIR`，没设时是 `~/.pi/agent`。
+
+没有这个文件时全部取默认值。类型错或未知键会让启动失败，并一次列出所有坏字段。枚举值不认识时取默认值。数字越界时夹到最近的边界。下面的注释只作解释，真正的文件必须是严格 JSON。
+
+**最小配置**：不用写。五个工具在默认值下都能用。
+
+```json
+{}
+```
+
+**完整示例**：每个键都跟着默认值，以及什么时候该改。
+
+```jsonc
+{
+  // 本地桥。扩展里编译了同一个端口
+  // （browser-extension/background/transport.js）：两处一起改，然后重载扩展
+  "bridge": { "port": 17318 },
+
+  // 会话规则
+  "policy": {
+    "authorizeOnStart": false,  // true = 不用 /chrome authorize on 就能用工具
+    "closeOwnTabsOnExit": true  // 会话结束时关掉本会话开的标签
+  },
+
+  // 输入与时限
+  "input": {
+    "dragSteps": 10,            // 按下与松开之间的鼠标移动次数
+    "scrollSteps": 5            // 每次 scroll 的滚轮事件数
+  },
+  "timing": { "navigateTimeoutMs": 15000 },  // 等 load 事件的时长；navigate 调用再多给 2 秒
+
+  // 模型可见的输出
+  "output": {
+    "maxElements": 80,          // 快照元素上限
+    "textChars": 18000          // see 的 text 模式正文上限，其余带提示丢掉
+  },
+
+  // 截图
+  "screenshot": {
+    "dir": "/home/me/.pi/agent/pi-browser-use-lite/screenshots",  // 第一次用时创建
+    "format": "png",            // png | jpeg
+    "keepNewest": 20            // 这个目录里更旧的截图会被删掉
+  },
+
+  // 工具开关与名字。至少留一个启用；名字不能重复，也不能盖住宿主已有的工具
+  "tools": {
+    "chrome_act": { "enabled": true, "name": "chrome_act" },
+    "chrome_see": { "enabled": true, "name": "chrome_see" },
+    "chrome_tab": { "enabled": true, "name": "chrome_tab" },
+    "chrome_vision": { "enabled": true, "name": "chrome_vision" },
+    "chrome_cdp": { "enabled": true, "name": "chrome_cdp" }
+  },
+
+  // 按工具改内置提示。"" 清空 description 或 promptSnippet；[] 表示不加规则
+  "guidance": {
+    "chrome_act": {
+      "description": "操作用户真实的浏览器。",
+      "promptSnippet": "操作浏览器",
+      "promptGuidelines": ["chrome_act: navigate 时带上 see: refs。"]
+    }
+  }
+}
+```
+
+每个键都可选。范围与默认值在 `src/config/schema.ts`。
+
+## 文档
+
+| 文档 | 内容 |
+|---|---|
+| [ARCHITECTURE](docs/ARCHITECTURE.md) | 模块边界与 seam；改结构之前先读它 |
+| [GLOSSARY](docs/GLOSSARY.md) | 一个概念只用一个词 |
+| [Modules](docs/modules/) | 每个模块的取舍与坑 |
+| [Decisions](docs/decisions/) | 为什么是这个形状 |
+
+## 开发
+
+在仓库根执行：
+
+```bash
+pnpm -C packages/pi-browser-use-lite lint
+pnpm -C packages/pi-browser-use-lite check:imports
+pnpm -C packages/pi-browser-use-lite typecheck
+pnpm -C packages/pi-browser-use-lite test
+```
+
+端到端测试会驱动真实浏览器。把 `packages/pi-browser-use-lite/browser-extension` 加载进扩展，留一个开着的 Chromium 系浏览器，然后运行：
+
+```bash
+pnpm -C packages/pi-browser-use-lite test:e2e
+```
+
+关掉其他装了本扩展的浏览器。两份扩展会抢同一个桥，命令落到先问的那一份。
+
+桥报出的版本与扩展不同的时候，扩展会自己重载。改了扩展代码但没升版本号时，去扩展页手动重载一次。
+
+## 许可证
+
+MIT，见 [LICENSE](LICENSE)。

package/browser-extension/background/dispatch.js

@@ -71,14 +71,11 @@ export const routes = new Map([
 	],
 	[
 		"tab.new",
-		async ({ sessionKey, url, background } = {}) => ({
-			id: await createTarget({ sessionKey, url, background }),
+		async ({ sessionKey, url } = {}) => ({
+			id: await createTarget({ sessionKey, url }),
 		}),
 	],
-	[
-		"tab.activate",
-		({ tabId, background } = {}) => activateTab({ tabId, background }),
-	],
+	["tab.activate", ({ tabId } = {}) => activateTab({ tabId })],
 	["tab.close", ({ tabId } = {}) => closeTab({ tabId })],
 	[
 		"page.navigate",
@@ -205,11 +202,7 @@ function requireTabId(tabId) {
  */
 async function tabIdOf(action, params) {
 	if (params.tabId !== undefined) return requireTabId(params.tabId);
-	return targetFor({
-		sessionKey: params.sessionKey,
-		action,
-		background: true,
-	});
+	return targetFor({ sessionKey: params.sessionKey, action });
 }
 
 /** 指针层的入参：ref 换成元素中心的视口坐标，其余原样。 */

package/browser-extension/background/input/pointer.js

@@ -1,6 +1,6 @@
 /**
  * 指针事件：移动、点击、悬停、拖动、滚轮。全部走 CDP，不做 DOM 假事件回退（DEC-0007）。
- * 目标标签不可见时直接抛错：Chrome 会丢弃不可见页面的可信输入，激活标签由调用方决定。
+ * Chrome 会丢弃不可见页面的可信输入，所以每个入口先调 assertVisible：不可见就把标签与窗口提到前台。
  */
 
 import { evaluate, sendCommand } from "./debugger.js";
@@ -210,14 +210,51 @@ async function viewportCenter(tabId) {
 	return { x: center.x, y: center.y };
 }
 
+/** 聚焦之后等页面变可见的次数与间隔：Chrome 要过一个 tick 才改 visibilityState。 */
+const RAISE_TRIES = 6;
+const RAISE_WAIT_MS = 50;
+
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function visibilityState(tabId) {
+	return evaluate(tabId, "document.visibilityState");
+}
+
+/** 页面为什么不可见，用来让报错指向人能动手的地方。 */
+async function hiddenReason(tabId) {
+	const tab = await chrome.tabs.get(tabId).catch(() => undefined);
+	if (tab?.active === false) return "it is an inactive tab in its window";
+	const win =
+		tab?.windowId === undefined
+			? undefined
+			: await chrome.windows.get(tab.windowId).catch(() => undefined);
+	if (win?.state === "minimized") return "its window is minimized";
+	if (win?.state === "fullscreen")
+		return "its window is behind a full-screen window";
+	return "its window is covered by another window";
+}
+
+/**
+ * 输入前确保页面可见。不可见就先激活标签、把窗口带到前台，仍不可见才报错。
+ * 激活标签不改窗口焦点，所以这一步只在真需要可信输入时打扰用户。
+ */
 export async function assertVisible(tabId) {
-	const state = await evaluate(tabId, "document.visibilityState");
+	const state = await visibilityState(tabId);
 	if (state === "visible") return;
-	if (state === "hidden")
+	if (state !== "hidden")
 		throw new Error(
-			`page_error: tab ${tabId} is hidden; Chrome drops input to hidden pages, so bring it to the front with chrome_tab switch (turn background mode off first)`,
+			`page_error: could not read document.visibilityState for tab ${tabId}`,
 		);
+	const reason = await hiddenReason(tabId);
+	const tab = await chrome.tabs.update(tabId, { active: true });
+	await chrome.windows.update(tab.windowId, { focused: true });
+	for (let attempt = 0; attempt < RAISE_TRIES; attempt++) {
+		await sleep(RAISE_WAIT_MS);
+		if ((await visibilityState(tabId)) === "visible") return;
+	}
 	throw new Error(
-		`page_error: could not read document.visibilityState for tab ${tabId}`,
+		`page_error: tab ${tabId} is hidden because ${reason}; Chrome drops trusted input to hidden pages. Bring the window to the front, then retry`,
 	);
 }

package/browser-extension/background/tabs.js

@@ -23,17 +23,17 @@ export async function listTabs({ sessionKey } = {}) {
  * @param {object} params
  * @param {string} params.sessionKey 会话标识
  * @param {string} [params.url] 要打开的地址，缺省 about:blank
- * @param {boolean} [params.background] 为 true 时新标签不在本会话窗口里激活
  * @returns {Promise<{ id: number, active: boolean, title: string, url: string }>}
  */
-export async function newTab({ sessionKey, url, background = false } = {}) {
+export async function newTab({ sessionKey, url } = {}) {
 	requireSessionKey(sessionKey);
 	const windowId = await liveWindowId(sessionKey);
 	if (windowId !== undefined) {
+		// 新标签在自己的窗口里就是活动标签。激活标签不改变窗口焦点，不会打扰用户。
 		const tab = await chrome.tabs.create({
 			windowId,
 			url: url ?? "about:blank",
-			active: !background,
+			active: true,
 		});
 		return formatTab(await chrome.tabs.get(tab.id));
 	}
@@ -47,14 +47,12 @@ export async function newTab({ sessionKey, url, background = false } = {}) {
 }
 
 /**
- * 激活标签，并把它所在的窗口带到前台。后台模式是硬策略：直接抛错，不碰 chrome.tabs.update。
+ * 激活标签，并把它所在的窗口带到前台。
  * @param {object} params
  * @param {number} params.tabId 标签 id
- * @param {boolean} [params.background] 为 true 时拒绝激活
  * @returns {Promise<{ id: number, active: boolean, title: string, url: string }>}
  */
-export async function activateTab({ tabId, background = false } = {}) {
-	if (background) throw new Error("background mode blocks tab.activate");
+export async function activateTab({ tabId } = {}) {
 	const tab = await chrome.tabs.update(tabId, { active: true });
 	await chrome.windows.update(tab.windowId, { focused: true });
 	return formatTab(tab);

package/browser-extension/background/target.js

@@ -18,17 +18,12 @@ export const OWNED_KEY_PREFIX = "target.owned.";
  * @param {object} params
  * @param {string} params.sessionKey 会话标识
  * @param {string} [params.url] 新标签的地址
- * @param {boolean} [params.background] 为 true 时新标签不激活
  * @returns {Promise<number>} 新 target 的标签 id
  */
-export async function createTarget({
-	sessionKey,
-	url,
-	background = false,
-} = {}) {
+export async function createTarget({ sessionKey, url } = {}) {
 	requireSessionKey(sessionKey);
 
-	const tab = await newTab({ sessionKey, url, background });
+	const tab = await newTab({ sessionKey, url });
 	await writeRecord(TARGET_KEY_PREFIX + sessionKey, tab.id);
 	const owned = await readOwned(sessionKey);
 	await writeRecord(OWNED_KEY_PREFIX + sessionKey, [...owned, tab.id]);
@@ -41,14 +36,9 @@ export async function createTarget({
  * @param {string} params.sessionKey 会话标识
  * @param {string} params.action 动作名，决定能不能顺手建 target
  * @param {string} [params.url] 建新标签时的地址
- * @param {boolean} [params.background] 为 true 时新建的标签不激活
  * @returns {Promise<number>} target 标签 id
  */
-export async function targetFor({
-	sessionKey,
-	action,
-	background = false,
-} = {}) {
+export async function targetFor({ sessionKey, action } = {}) {
 	requireSessionKey(sessionKey);
 	if (!action) throw new Error("action is required");
 
@@ -59,7 +49,7 @@ export async function targetFor({
 			`no_target: no automation target for session ${sessionKey}`,
 		);
 
-	return createTarget({ sessionKey, background });
+	return createTarget({ sessionKey });
 }
 
 /**

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
 	"manifest_version": 3,
 	"name": "Pi Browser Use",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Lets Pi drive tabs in your own Chrome through a local bridge at 127.0.0.1.",
 	"permissions": [
 		"debugger",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-browser-use-lite",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Pi extension: drive your own Chrome through a companion browser extension.",
 	"keywords": ["pi-package", "pi-extension", "chrome", "browser"],
 	"type": "module",

package/src/commands/index.ts

@@ -1,5 +1,5 @@
 /**
- * `/chrome` 命令：authorize、background、status 三个子命令。
+ * `/chrome` 命令：authorize 与 status 两个子命令。
  * 命令只改会话状态与读桥的状态，不发浏览器命令；子命令文本由 {@link ChromeCommand.run} 返回。
  */
 
@@ -32,11 +32,35 @@ export const INSTALL_STEPS = [
 	"3. leave the extension enabled; it polls the bridge by itself",
 ].join("\n");
 
-const SUBCOMMANDS = [
-	"/chrome authorize on|off",
-	"/chrome background on|off",
-	"/chrome status",
-].join("\n");
+const SUBCOMMANDS = ["/chrome authorize on|off", "/chrome status"].join("\n");
+
+/** 一条参数补全。形状与 pi 的 `AutocompleteItem` 一致，命令层不引 TUI 类型。 */
+export interface ChromeCompletion {
+	value: string;
+	label: string;
+	description: string;
+}
+
+/** 整条子命令加一句说明，顺序即补全列表的顺序。 */
+const COMPLETIONS: ReadonlyArray<readonly [string, string]> = [
+	["authorize on", "unlock the tools for this session"],
+	["authorize off", "lock the tools until the next authorize on"],
+	["status", "print host, extension, authorization, bridge and target state"],
+];
+
+/**
+ * `/chrome` 的参数补全：按整条子命令做前缀匹配，打到 `authorize ` 只剩 on 与 off。
+ * 一个都没匹配上返回 null，让 pi 用它的默认补全。
+ */
+export function completeChromeArgument(
+	prefix: string,
+): ChromeCompletion[] | null {
+	const typed = prefix.trimStart();
+	const items = COMPLETIONS.filter(([value]) => value.startsWith(typed)).map(
+		([value, description]) => ({ value, label: value, description }),
+	);
+	return items.length > 0 ? items : null;
+}
 
 export function createChromeCommand(deps: ChromeCommandDeps): ChromeCommand {
 	return {
@@ -45,7 +69,6 @@ export function createChromeCommand(deps: ChromeCommandDeps): ChromeCommand {
 			if (trimmed === "") return SUBCOMMANDS;
 			const [verb, value] = trimmed.split(/\s+/);
 			if (verb === "authorize") return toggleAuthorize(deps, value);
-			if (verb === "background") return toggleBackground(deps, value);
 			if (verb === "status") return statusOf(deps);
 			return `bad_args: unknown subcommand: ${trimmed}\nhint: run /chrome for the list`;
 		},
@@ -71,17 +94,7 @@ async function toggleAuthorize(
 	return "authorized: on";
 }
 
-function toggleBackground(
-	deps: ChromeCommandDeps,
-	value: string | undefined,
-): string {
-	const on = flagOf(value);
-	if (on === undefined) return usage("background on|off");
-	deps.policy.setBackground(on);
-	return `background: ${on ? "on" : "off"}`;
-}
-
-/** 状态行：桥的四项来自 `bridge.status()`，策略两项来自会话，target 来自宿主会话状态。 */
+/** 状态行：桥的四项来自 `bridge.status()`，授权来自会话，target 来自宿主会话状态。 */
 async function statusOf(deps: ChromeCommandDeps): Promise<string> {
 	await deps.bridge.start();
 	const bridge = await deps.bridge.describe();
@@ -90,7 +103,6 @@ async function statusOf(deps: ChromeCommandDeps): Promise<string> {
 		`host: ${deps.hostVersion}`,
 		`extension: ${bridge.extensionVersion ?? "not connected"}`,
 		`authorized: ${deps.policy.authorized ? "on" : "off"}`,
-		`background: ${deps.policy.background ? "on" : "off"}`,
 		`bridge: ${bridge.mode}`,
 		`port: ${new URL(bridge.url).port}`,
 		`connected: ${bridge.connected ? "yes" : "no"}`,

package/src/config/schema.ts

@@ -68,30 +68,16 @@ export interface ResolvedConfig {
 	bridge: { port: number };
 	policy: {
 		authorizeOnStart: boolean;
-		background: boolean;
 		closeOwnTabsOnExit: boolean;
 	};
 	input: { dragSteps: number; scrollSteps: number };
 	timing: { navigateTimeoutMs: number };
 	output: { maxElements: number; textChars: number };
 	screenshot: { dir: string; format: ScreenshotFormat; keepNewest: number };
-	prompt: { guidelines: string[] };
 	tools: Record<ToolId, ToolSettings>;
 	guidance: Partial<Record<ToolId, GuidanceFields>>;
 }
 
-/**
- * 跨工具的默认规则。每条以工具名开头：两层规则平铺进系统提示后按原文去重，
- * 不加工具前缀，只有点名才看得出是哪个工具的规则。
- * 全局规则只点名 chrome_act：别的工具可以关掉，点名它们的规则放在该工具的
- * promptGuidelines 里，才能随工具一起消失（SPEC-0001「关掉的工具……规则也一起消失」）。
- */
-export const DEFAULT_PROMPT_GUIDELINES = [
-	"chrome_act: this is the user's real browser; confirm before destructive actions.",
-	"chrome_act: pass see: refs on navigate, then click the refs from that snapshot; a ref from an older page fails.",
-	"chrome_act: passing see adds a snapshot to the reply and costs extra tokens; ask for it only when the page just changed.",
-] as const;
-
 /**
  * 13 个标量字段的默认值。工具记录与文案覆盖不在其中。
  * `screenshot.dir` 跟着 agent 目录走，由 buildConfig 补，不在这里。
@@ -105,14 +91,12 @@ export const DEFAULTS: Omit<
 	bridge: { port: 17_318 },
 	policy: {
 		authorizeOnStart: false,
-		background: true,
 		closeOwnTabsOnExit: true,
 	},
 	input: { dragSteps: 10, scrollSteps: 5 },
 	timing: { navigateTimeoutMs: 15_000 },
 	output: { maxElements: 80, textChars: 18_000 },
 	screenshot: { format: "png", keepNewest: 20 },
-	prompt: { guidelines: [...DEFAULT_PROMPT_GUIDELINES] },
 };
 
 export type Raw = Record<string, unknown>;

package/src/config/validate.ts

@@ -29,7 +29,6 @@ const TOP_KEYS = [
 	"timing",
 	"output",
 	"screenshot",
-	"prompt",
 	"tools",
 	"guidance",
 ];
@@ -45,7 +44,7 @@ export function buildConfig(
 	const policy = asObject(raw.policy, "policy", errors);
 	checkUnknownKeys(
 		policy,
-		["authorizeOnStart", "background", "closeOwnTabsOnExit"],
+		["authorizeOnStart", "closeOwnTabsOnExit"],
 		"policy",
 		errors,
 	);
@@ -79,12 +78,6 @@ export function buildConfig(
 				"policy.authorizeOnStart",
 				errors,
 			),
-			background: readBoolean(
-				policy.background,
-				DEFAULTS.policy.background,
-				"policy.background",
-				errors,
-			),
 			closeOwnTabsOnExit: readBoolean(
 				policy.closeOwnTabsOnExit,
 				DEFAULTS.policy.closeOwnTabsOnExit,
@@ -155,7 +148,6 @@ export function buildConfig(
 				RANGES.keepNewest,
 			),
 		},
-		prompt: readPrompt(raw.prompt, errors),
 		tools: readTools(raw.tools, errors),
 		guidance: readGuidance(raw.guidance, errors),
 	};
@@ -222,16 +214,6 @@ function checkUnknownKeys(
 	}
 }
 
-function readPrompt(value: unknown, errors: Errors): { guidelines: string[] } {
-	const raw = asObject(value, "prompt", errors);
-	checkUnknownKeys(raw, ["guidelines"], "prompt", errors);
-	const guidelines =
-		raw.guidelines === undefined
-			? [...DEFAULTS.prompt.guidelines]
-			: readStringArray(raw.guidelines, "prompt.guidelines", errors);
-	return { guidelines };
-}
-
 function readGuidance(
 	value: unknown,
 	errors: Errors,

package/src/index.ts

@@ -8,7 +8,10 @@ import type {
 	ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Bridge } from "./bridge/index.ts";
-import { createChromeCommand } from "./commands/index.ts";
+import {
+	completeChromeArgument,
+	createChromeCommand,
+} from "./commands/index.ts";
 import { agentDir, HOST_VERSION, loadConfig } from "./config/index.ts";
 import { createSessionPolicy, type SessionPolicy } from "./policy/index.ts";
 import {
@@ -41,7 +44,8 @@ export default function piBrowserUseLite(pi: ExtensionAPI): void {
 	}
 
 	pi.registerCommand("chrome", {
-		description: "authorize, background, or report the bridge state",
+		description: "authorize the tools, or report the bridge state",
+		getArgumentCompletions: completeChromeArgument,
 		handler: async (args, ctx) => {
 			ctx.ui.notify(await chrome.run(args));
 		},
@@ -67,13 +71,6 @@ export default function piBrowserUseLite(pi: ExtensionAPI): void {
 		policy.endSession();
 		await bridge.stop();
 	});
-
-	pi.on("before_agent_start", (event) => {
-		event.systemPromptOptions.promptGuidelines = [
-			...event.systemPromptOptions.promptGuidelines,
-			...config.prompt.guidelines,
-		];
-	});
 }
 
 /**
@@ -88,7 +85,7 @@ function registerable(
 	return {
 		...tool,
 		execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
-			const denial = policy.check(actionOf(params));
+			const denial = policy.check();
 			if (denial) return errorResult(denial);
 			return await executors.execute(
 				tool.id,
@@ -119,7 +116,3 @@ function createTargetHolder(): SessionTarget {
 }
 
 /** 参数里的动作名。只有 chrome_act 与 chrome_tab 带 action，别的工具给空串。 */
-function actionOf(params: unknown): string {
-	const action = (params as { action?: unknown } | null | undefined)?.action;
-	return typeof action === "string" ? action : "";
-}

package/src/policy/index.ts

@@ -1,6 +1,6 @@
 /**
- * 策略插点：授权开关与硬背景模式。
- * 状态只在内存，随会话结束清回默认；判定不做 IO，也没有定时器。
+ * 策略插点：授权开关。
+ * 状态只在内存，随会话结束清回未授权；判定不做 IO，也没有定时器。
  */
 
 import type { ResolvedConfig } from "../config/index.ts";
@@ -18,27 +18,15 @@ const NOT_AUTHORIZED: PolicyDenial = {
 	hint: "Run /chrome authorize on",
 };
 
-/** 聚焦动作名。工具名可被 config 改名，动作名不会，所以按动作名判。 */
-const FOCUS_ACTION = "switch";
-
-const FOCUS_BLOCKED: PolicyDenial = {
-	class: "locked",
-	message: "background mode blocks tab switch",
-	hint: "Run /chrome background off",
-};
-
-/** 会话内的授权与背景模式状态。 */
+/** 会话内的授权状态。 */
 export interface SessionPolicy {
 	readonly authorized: boolean;
-	readonly background: boolean;
 	/** 授权开关。只在内存，不落盘。 */
 	authorize(on: boolean): void;
-	/** 背景模式开关。开启时不接受任何聚焦请求。 */
-	setBackground(on: boolean): void;
-	/** 会话结束：授权回到未授权，背景模式回到配置默认值。 */
+	/** 会话结束：授权回到未授权。 */
 	endSession(): void;
 	/** 插点：一次工具调用先过这里。放行返回 undefined，拒绝返回原因。 */
-	check(action?: string): PolicyDenial | undefined;
+	check(): PolicyDenial | undefined;
 }
 
 /** 造一份会话策略。`authorizeOnStart` 为真时开局即授权。 */
@@ -46,28 +34,18 @@ export function createSessionPolicy(
 	settings: ResolvedConfig["policy"],
 ): SessionPolicy {
 	let authorized = settings.authorizeOnStart;
-	let background = settings.background;
 	return {
 		get authorized() {
 			return authorized;
 		},
-		get background() {
-			return background;
-		},
 		authorize(on) {
 			authorized = on;
 		},
-		setBackground(on) {
-			background = on;
-		},
 		endSession() {
 			authorized = false;
-			background = settings.background;
 		},
-		check(action = "") {
-			if (!authorized) return NOT_AUTHORIZED;
-			if (background && action === FOCUS_ACTION) return FOCUS_BLOCKED;
-			return undefined;
+		check() {
+			return authorized ? undefined : NOT_AUTHORIZED;
 		},
 	};
 }

package/src/tools/exec/tab.ts

@@ -34,7 +34,6 @@ export async function runTab(
 		case "new": {
 			const result = (await call(ctx, "tab.new", {
 				url: params.url,
-				background: true,
 			})) as TabInfo;
 			const id = targetIdOf(result);
 			if (id !== undefined) ctx.deps.target.set(id);
@@ -45,10 +44,7 @@ export async function runTab(
 		}
 		case "switch": {
 			const tabId = await requireTab(ctx, "switch", params.tab);
-			const result = await call(ctx, "tab.activate", {
-				tabId,
-				background: false,
-			});
+			const result = await call(ctx, "tab.activate", { tabId });
 			return okResult(`ok: switch ${tabId}`, { result });
 		}
 		case "close": {

package/src/tools/index.ts

@@ -268,6 +268,9 @@ export const TOOL_SPECS = {
 			),
 		}),
 		promptGuidelines: [
+			"chrome_act: this is the user's real browser; confirm before destructive actions.",
+			"chrome_act: pass see: refs on navigate, then click the refs from that snapshot; a ref from an older page fails.",
+			"chrome_act: passing see adds a snapshot to the reply and costs extra tokens; ask for it only when the page just changed.",
 			"chrome_act: name the action first, then send only the parameters that action reads.",
 			"chrome_act: batch runs steps in order and stops at the first failure unless the step is optional.",
 		],