@angelky7/dsh-browser-control 1.7.3 → 1.7.5

package/README.en.md

@@ -268,10 +268,12 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_emulate` | Switch to a device viewport (mobile / desktop / custom, v1.0.7+); v1.7.1+ adds throttling: `network` slow3g/fast3g/offline/reset + `cpuThrottlingRate` (1–20), the receipt states the applied numbers, `device:"reset"` clears them too |
 | `browser_metrics` | Read performance counters (DOM nodes / JS heap / layout & script durations, Performance.getMetrics, read-only; puts numbers behind "this page is heavy", v1.7.1+) |
 | `browser_drag` | Drag from/to a selector or viewport point: `auto` synthesizes html5 dragstart→dragover→drop for `draggable="true"` sources (no drop unless accepted), otherwise sends real mouse input (press, interpolated moves, release — sliders/canvas/sortable widgets). **Plugin-side only** over the cdp channel embedded in extension v1.7.2, v1.7.3+ |
+| `browser_audit` | Read this plugin session's in-memory audit trail — every command sent or refused (redacted params, `code`/`effectState`, duration), capped at 200 entries and wiped on restart; typed text and cookie values are redacted, eval expressions truncated. Plugin-local read, works in read-only mode (v1.7.4+) |
+| `browser_journal` | Read the **persistent journal across dsh restarts** (`<stateDir>/journal.jsonl`, last 1000 entries, grouped by run) — ask it after a restart "what was I doing in which tab"; same redaction; plugin-local disk read that works with the extension offline (v1.7.5+) |
 | `browser_cleanup` | Clean up temp files |
 | `browser_info` | Which browser and extension build is attached (run it first when debugging, v1.0.9+) |
 
-26 tools in total. `browser_wait`, `browser_find`, `browser_dialog` and `browser_info` existed inside the extension up to v1.0.8 but were never registered as tools, so the agent could not reach them; `browser_network_clear` existed in code and was simply missing from this table. `verify/verify_surface.mjs` now reconciles the extension command table, the commands the plugin calls, this table and the built bundle, so any drift fails `npm run verify`.
+28 tools in total. `browser_wait`, `browser_find`, `browser_dialog` and `browser_info` existed inside the extension up to v1.0.8 but were never registered as tools, so the agent could not reach them; `browser_network_clear` existed in code and was simply missing from this table. `verify/verify_surface.mjs` now reconciles the extension command table, the commands the plugin calls, this table and the built bundle, so any drift fails `npm run verify`.
 
 ## Architecture
 

package/README.md

@@ -261,11 +261,13 @@ curl -X POST http://127.0.0.1:9777/api/command \
 | `browser_emulate` | 切设备视口（移动 / 桌面 / 自定义，v1.0.7+）；v1.7.1 起还能限速：`network` slow3g/fast3g/offline/reset + `cpuThrottlingRate`（1–20），回执写明生效数值，`device:"reset"` 一并还原 |
 | `browser_metrics` | 读性能计数器（DOM 节点数 / JS 堆 / 布局与脚本耗时，Performance.getMetrics，只读；让「这页面很重」有数字说话，v1.7.1+） |
 | `browser_drag` | 拖拽：from/to 用选择器或视口坐标；`auto` 对 `draggable="true"` 的源走 html5 事件合成（dragstart→dragover→drop，未接受就不 drop），其余走真实鼠标输入（按下→插值移动→抬起，滑杆/画布/排序组件用这个）。**纯插件实现**（经 v1.7.2 预埋的 cdp 通道），v1.7.3+ |
+| `browser_audit` | 读本次插件会话的内存审计账本：发过/被拒的每条命令（参数脱敏、`code`/`effectState`、耗时），最多 200 条、dsh 重启即清；输入的文字与 cookie 值打码、eval 表达式截断。纯本地读，只读档下照常可用（v1.7.4+） |
+| `browser_journal` | 读**跨 dsh 重启**的持久命令账本（`<stateDir>/journal.jsonl`，最多 1000 条，按运行分组）——重启后先问它「上个会话在哪个标签页干了什么」；同样的脱敏规则；纯本地磁盘读，**扩展离线也能用**（v1.7.5+） |
 | `browser_windows` | 窗口控制：清单/开窗/改状态与几何/关整窗/跨窗挪标签（唯一能碰窗口几何的工具，v1.6.0+） |
 | `browser_cleanup` | 清理临时文件 |
 | `browser_info` | 报告实际连上的浏览器与扩展版本（排障先跑它，v1.0.9+） |
 
-共 26 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
+共 28 个工具。`browser_wait` / `browser_find` / `browser_dialog` / `browser_info` 在 v1.0.8 及以前是「扩展里已实现、但没注册成工具」，agent 调不到；`browser_network_clear` 则是代码里有、这张表漏了。这些现在由 `verify/verify_surface.mjs` 做三方对账（扩展命令表 ↔ 插件调用 ↔ 文档表 ↔ 构建产物），漂移会直接让 `npm run verify` 失败。
 
 ## 架构
 

package/lib/index.js

@@ -1,4 +1,5 @@
-import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { appendFile, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import path from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -926,6 +927,213 @@ function policyRefusal(command, flags, params) {
 	if (flags.readOnly && PAGE_MUTATING_COMMANDS.has(command) && !isReadOnlyAction) return `只读模式已开启（readOnly: true）：命令 ${command} 会往页面里插入一层接管浮层（改页面 DOM），已被拒绝，没有向浏览器发出任何操作。浮层是给用户看的提示层，不是安全边界；只读档里连这种「只是提示」的改动也一并拒绝。要开浮层请由用户关掉 readOnly，${CONFIG_HINT}不要原地重试本命令。`;
 	if (flags.readOnly && !READ_ONLY_ALLOWED.has(command) && !isReadOnlyAction) return `只读模式已开启（readOnly: true）：命令 ${command} 会改变页面或浏览器状态，已被拒绝，没有向浏览器发出任何操作。只读模式下可用的工具是读页面与读日志那几类；要放开写操作，${CONFIG_HINT}不要原地重试本命令。`;
 }
+/** 单条参数摘要上限：审计要的是形状，不是全文。 */
+const AUDIT_PARAMS_MAX_CHARS = 300;
+/** 失败描述上限。 */
+const AUDIT_ERROR_MAX_CHARS = 200;
+/** eval 表达式只留前 120 字符：里面可能有凭据。 */
+const AUDIT_EXPRESSION_MAX_CHARS = 120;
+/** 参数里这些键的值一律打码（大小写不敏感）。 */
+const SECRET_KEY = /^(token|authorization|password|passwd|secret|apikey|api_key|cookie)$/i;
+/**
+* 哪个命令的 `value` 字段是敏感内容：`input` 是往页面里打的字（可能是密码），
+* `cookies.set` 直接写凭据。其余命令的 value 字段（如果有）不动。
+*/
+const VALUE_REDACTED_COMMANDS = /* @__PURE__ */ new Set(["input", "cookies.set"]);
+function redactValue(value) {
+	return `[redacted:${typeof value === "string" ? [...value].length : 0} chars]`;
+}
+/**
+* 把一次调用的参数压成可审计的摘要：敏感键打码、特定命令的 value 打码、
+* 长表达式截断、整体限长。返回 JSON 文本——审计工具原样把它交给模型。
+*/
+function summarizeAuditParams(command, params) {
+	let text;
+	try {
+		text = JSON.stringify(params, (key, value) => {
+			if (SECRET_KEY.test(key)) return "[redacted]";
+			if (key === "value" && VALUE_REDACTED_COMMANDS.has(command)) return redactValue(value);
+			if (key === "expression" && typeof value === "string" && [...value].length > AUDIT_EXPRESSION_MAX_CHARS) return `${[...value].slice(0, AUDIT_EXPRESSION_MAX_CHARS).join("")}…[+${[...value].length - AUDIT_EXPRESSION_MAX_CHARS} chars]`;
+			return value;
+		}) ?? "{}";
+	} catch {
+		text = "[unserializable params]";
+	}
+	return [...text].length > AUDIT_PARAMS_MAX_CHARS ? `${[...text].slice(0, AUDIT_PARAMS_MAX_CHARS).join("")}…[+${[...text].length - AUDIT_PARAMS_MAX_CHARS} chars]` : text;
+}
+/** 记账器。一个桥（一个插件实例）一份；`record` 只追加，`list` 只读。 */
+var AuditLog = class {
+	entries = [];
+	nextSeq = 1;
+	now;
+	constructor(now = Date.now) {
+		this.now = now;
+	}
+	/**
+	* 记一笔。
+	* @param input - 命令、摘要与结果；seq/t 由账本自己盖，durationMs 由调用方量。
+	*/
+	record(input) {
+		const entry = {
+			seq: this.nextSeq++,
+			t: this.now(),
+			command: input.command,
+			params: input.params,
+			ok: input.ok,
+			durationMs: Math.max(0, Math.round(input.durationMs))
+		};
+		if (input.tabId !== void 0) entry.tabId = input.tabId;
+		if (input.code !== void 0) entry.code = input.code;
+		if (input.effectState !== void 0) entry.effectState = input.effectState;
+		if (input.error !== void 0) entry.error = [...input.error].length > AUDIT_ERROR_MAX_CHARS ? `${[...input.error].slice(0, AUDIT_ERROR_MAX_CHARS).join("")}…` : input.error;
+		this.entries.push(entry);
+		if (this.entries.length > 200) this.entries.splice(0, this.entries.length - 200);
+		return entry;
+	}
+	/** 现有条目数（被挤掉的不算）。 */
+	size() {
+		return this.entries.length;
+	}
+	/**
+	* 过滤并取最新的一批。
+	* @param filter - tabId / 命令子串 / sinceSeq / limit；返回按 seq 升序。
+	*/
+	list(filter = {}) {
+		let matched = this.entries;
+		if (filter.tabId !== void 0) matched = matched.filter((e) => e.tabId === filter.tabId);
+		if (filter.command !== void 0 && filter.command.length > 0) {
+			const needle = filter.command.toLowerCase();
+			matched = matched.filter((e) => e.command.toLowerCase().includes(needle));
+		}
+		if (filter.sinceSeq !== void 0) {
+			const floor = filter.sinceSeq;
+			matched = matched.filter((e) => e.seq > floor);
+		}
+		const limit = Math.min(200, Math.max(1, Math.trunc(filter.limit ?? 50)));
+		return matched.slice(Math.max(0, matched.length - limit));
+	}
+};
+//#endregion
+//#region lib/types/journal.js
+/**
+* 会话恢复（v1.7.5）：把审计账本持久化到磁盘，dsh 重启以后还查得到上一个会话做过什么。
+*
+* 为什么是文件而不是数据库：一条命令一行 JSONL，出问题时能直接打开看、能 grep、
+* 写坏了最多丢一行（读到坏行跳过，不炸整本账）。上限 1000 行，超了在**启动时**
+* 裁掉最旧的——运行中不裁剪，append 永远是纯追加。
+*
+* 隐私与审计同一套：写盘的就是 AuditLog 里那份脱敏后的摘要（输入值/cookie 值已
+* 打码），journal 层不再碰原始参数。文件在 <stateDir>/journal.jsonl，stateDir
+* 默认 ~/.dsh-browser-control，可在 profile 的 browser-bridge 配置里改。
+*/
+/** 磁盘上最多保留的条数（启动时裁剪）。 */
+const JOURNAL_MAX_LINES = 1e3;
+/** 防御性上限：正常文件远小于它；超过就只读尾巴，别为了一本账吃掉内存。 */
+const JOURNAL_MAX_BYTES = 8388608;
+function isEntry(value) {
+	if (value === null || typeof value !== "object") return false;
+	const v = value;
+	return typeof v.run === "string" && typeof v.command === "string" && typeof v.seq === "number" && typeof v.t === "number" && typeof v.params === "string" && typeof v.ok === "boolean" && typeof v.durationMs === "number";
+}
+/** 拆行并解析；坏行（截断、手改坏）跳过——一本账不能因为一行烂掉就全废。 */
+function parseLines(text) {
+	const out = [];
+	for (const line of text.split("\n")) {
+		if (line.trim().length === 0) continue;
+		try {
+			const parsed = JSON.parse(line);
+			if (isEntry(parsed)) out.push(parsed);
+		} catch {}
+	}
+	return out;
+}
+/**
+* 打开（并按需裁剪）一个 journal 目录。
+* @param stateDir - 目录（不存在会创建）；journal 文件是 `<stateDir>/journal.jsonl`。
+* @param log - 一行式日志；打开/裁剪的结论写进去。
+* @returns 带 run 编号的追加器；`close()` 等所有在途写入落盘。
+*/
+var Journal = class Journal {
+	/** 这次运行的编号：启动时刻（毫秒精度；秒级精度下两次启动同秒会撞号）。 */
+	runId;
+	file;
+	log;
+	chain = Promise.resolve();
+	warned = false;
+	constructor(file, runId, log) {
+		this.file = file;
+		this.runId = runId;
+		this.log = log;
+	}
+	static async open(stateDir, log) {
+		await mkdir(stateDir, { recursive: true });
+		const file = path.join(stateDir, "journal.jsonl");
+		let existing = [];
+		try {
+			const text = await readFile(file, "utf8");
+			existing = parseLines(text.length > JOURNAL_MAX_BYTES ? text.slice(-8388608) : text);
+		} catch {}
+		if (existing.length > 1e3) {
+			const kept = existing.slice(existing.length - JOURNAL_MAX_LINES);
+			const tmp = `${file}.tmp`;
+			await writeFile(tmp, kept.map((e) => `${JSON.stringify(e)}\n`).join(""), "utf8");
+			await rename(tmp, file);
+			log(`journal: pruned ${existing.length - kept.length} old entries (${JOURNAL_MAX_LINES} kept)`);
+		} else if (existing.length > 0) {
+			const last = existing[existing.length - 1];
+			log(`journal: restored context — ${existing.length} entries on disk, last from run ${last.run} (#${last.seq} ${last.command})`);
+		}
+		return new Journal(file, (/* @__PURE__ */ new Date()).toISOString().slice(0, 23).replace("T", " "), log);
+	}
+	/**
+	* 追加一条（异步、排队写；失败只告警一次，绝不阻塞命令路径）。
+	* @param entry - AuditLog 刚记下的条目（参数已脱敏）。
+	*/
+	append(entry) {
+		const line = `${JSON.stringify({
+			run: this.runId,
+			...entry
+		})}\n`;
+		this.chain = this.chain.then(() => appendFile(this.file, line, "utf8")).catch((error) => {
+			if (!this.warned) {
+				this.warned = true;
+				this.log(`journal: write failed — ${error instanceof Error ? error.message : String(error)}`);
+			}
+		});
+	}
+	/** 等在途写入落盘（teardown / 测试用）。 */
+	async close() {
+		await this.chain.catch(() => {});
+	}
+};
+/**
+* 读 journal 的尾部（不要求 Journal 实例——读在线程外也能工作，扩展离线也行）。
+* @param stateDir - journal 所在目录。
+* @param filter - tabId / 命令子串 / 条数（默认 50，最大 500；取最新）。
+*/
+async function readJournal(stateDir, filter = {}) {
+	let text;
+	try {
+		text = await readFile(path.join(stateDir, "journal.jsonl"), "utf8");
+	} catch {
+		return {
+			total: 0,
+			entries: []
+		};
+	}
+	if (text.length > JOURNAL_MAX_BYTES) text = text.slice(-8388608);
+	let matched = parseLines(text);
+	if (filter.tabId !== void 0) matched = matched.filter((e) => e.tabId === filter.tabId);
+	if (filter.command !== void 0 && filter.command.length > 0) {
+		const needle = filter.command.toLowerCase();
+		matched = matched.filter((e) => e.command.toLowerCase().includes(needle));
+	}
+	const limit = Math.min(500, Math.max(1, Math.trunc(filter.limit ?? 50)));
+	return {
+		total: matched.length,
+		entries: matched.slice(Math.max(0, matched.length - limit))
+	};
+}
 //#endregion
 //#region lib/types/index.js
 /**
@@ -979,6 +1187,7 @@ const Config = z.object({
 	port: z.number().step(1).min(1024).max(65535).default(9777),
 	token: z.string().default("dsh-local"),
 	shotsDir: z.string().default("dsh-browser-shots"),
+	stateDir: z.string().default(path.join(homedir(), ".dsh-browser-control")),
 	readOnly: z.boolean().default(false),
 	allowScript: z.boolean().default(true)
 });
@@ -1054,6 +1263,10 @@ var BridgeController = class {
 	lastError;
 	chain = Promise.resolve();
 	current;
+	journal;
+	journalKey = "";
+	/** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
+	audit = new AuditLog();
 	constructor(log) {
 		this.log = log;
 	}
@@ -1061,6 +1274,17 @@ var BridgeController = class {
 	get shotsDir() {
 		return this.current === void 0 ? void 0 : path.resolve(this.current.shotsDir);
 	}
+	/** 审计账本落盘目录；配置到达之前是 undefined。 */
+	get stateDir() {
+		return this.current === void 0 ? void 0 : path.resolve(this.current.stateDir);
+	}
+	/**
+	* Record one audit entry in memory and, when the journal is open, on disk.
+	* Journal appends are queued and never block the command path.
+	*/
+	recordAudit(input) {
+		this.journal?.append(this.audit.record(input));
+	}
 	/**
 	* Current policy flags. Tools that compose several commands (browser_drag
 	* runs `cdp`/`eval`) read this to refuse with a tool-level message; the
@@ -1098,6 +1322,15 @@ var BridgeController = class {
 	*/
 	requireExtensionCommand(command, since) {
 		if (this.hasExtensionCommand(command)) return;
+		this.recordAudit({
+			command,
+			params: "",
+			ok: false,
+			code: "extension_outdated",
+			effectState: "not_started",
+			error: `connected extension v${this.extensionVersion() ?? "?"} lacks ${command} (added in ${since})`,
+			durationMs: 0
+		});
 		throw extensionOutdatedError(this.extensionVersion(), command, since);
 	}
 	/**
@@ -1119,6 +1352,18 @@ var BridgeController = class {
 	}
 	async reconcileNow(config) {
 		const shotsDir = path.resolve(config.shotsDir);
+		const stateDir = path.resolve(config.stateDir);
+		if (stateDir !== this.journalKey) {
+			const previousJournal = this.journal;
+			this.journal = void 0;
+			this.journalKey = stateDir;
+			await previousJournal?.close();
+			try {
+				this.journal = await Journal.open(stateDir, this.log);
+			} catch (error) {
+				this.log(`journal: disabled — ${errorMessage(error)}`);
+			}
+		}
 		const key = config.enabled ? `${config.port}|${config.token}|${shotsDir}` : "";
 		if (key === this.serverKey) return;
 		const previous = this.server;
@@ -1159,13 +1404,40 @@ var BridgeController = class {
 	* @returns the extension's result payload verbatim.
 	*/
 	async execute(command, params, signal, timeoutMs) {
-		this.policyGate(command, params);
-		const server = this.server;
-		if (server === void 0) throw classify(command, new Error(this.lastError ?? "浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）"));
-		return server.execute(command, params, timeoutMs === void 0 ? { signal } : {
-			signal,
-			timeoutMs
-		});
+		const started = Date.now();
+		const summary = summarizeAuditParams(command, params);
+		const tabId = typeof params.tabId === "number" ? params.tabId : void 0;
+		try {
+			this.policyGate(command, params);
+			const server = this.server;
+			if (server === void 0) throw classify(command, new Error(this.lastError ?? "浏览器控制未启用 —— 在 profile 的 cordis.patch.yml 里给 browser-bridge 配 enabled: true（dsh 0.1.7+ 的宿主也会在设置 → 插件 自动列出本插件开关；0.1.2 及更早的宿主没有这张卡片，只能改配置文件）"));
+			const result = await server.execute(command, params, timeoutMs === void 0 ? { signal } : {
+				signal,
+				timeoutMs
+			});
+			this.recordAudit({
+				command,
+				tabId,
+				params: summary,
+				ok: true,
+				durationMs: Date.now() - started
+			});
+			return result;
+		} catch (error) {
+			const code = error.code;
+			const effectState = error.effectState;
+			this.recordAudit({
+				command,
+				tabId,
+				params: summary,
+				ok: false,
+				code: typeof code === "string" ? code : void 0,
+				effectState: typeof effectState === "string" ? effectState : void 0,
+				error: errorMessage(error),
+				durationMs: Date.now() - started
+			});
+			throw error;
+		}
 	}
 	/**
 	* Refuse a command the local policy forbids, before anything is sent or deleted.
@@ -1190,21 +1462,48 @@ var BridgeController = class {
 	* @returns counts and names of what was removed.
 	*/
 	async cleanup() {
-		this.policyGate("cleanup");
-		const dir = this.shotsDir;
-		if (dir === void 0) throw classify("cleanup", /* @__PURE__ */ new Error("browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录"));
+		const started = Date.now();
 		try {
-			return await cleanupArtifacts({ shotsDir: dir });
+			this.policyGate("cleanup");
+			const dir = this.shotsDir;
+			if (dir === void 0) throw classify("cleanup", /* @__PURE__ */ new Error("browser-bridge is not configured yet —— 浏览器控制尚未加载配置，无法确定清理目录"));
+			try {
+				const result = await cleanupArtifacts({ shotsDir: dir });
+				this.recordAudit({
+					command: "cleanup",
+					params: "{}",
+					ok: true,
+					durationMs: Date.now() - started
+				});
+				return result;
+			} catch (error) {
+				throw classify("cleanup", error);
+			}
 		} catch (error) {
-			throw classify("cleanup", error);
+			const code = error.code;
+			const effectState = error.effectState;
+			this.recordAudit({
+				command: "cleanup",
+				params: "{}",
+				ok: false,
+				code: typeof code === "string" ? code : void 0,
+				effectState: typeof effectState === "string" ? effectState : void 0,
+				error: errorMessage(error),
+				durationMs: Date.now() - started
+			});
+			throw error;
 		}
 	}
 	/** Stop the listener; safe to call repeatedly and during teardown. */
-	stop() {
+	async stop() {
 		const previous = this.server;
 		this.server = void 0;
 		this.serverKey = "";
-		return previous?.stop() ?? Promise.resolve();
+		await (previous?.stop() ?? Promise.resolve());
+		const journal = this.journal;
+		this.journal = void 0;
+		this.journalKey = "";
+		await journal?.close();
 	}
 };
 function errorMessage(error) {
@@ -3147,6 +3446,8 @@ function applyBrowserTools(ctx, controller) {
 		}
 	}));
 	registerDragTool(ctx, controller);
+	registerAuditTool(ctx, controller);
+	registerJournalTool(ctx, controller);
 }
 /** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
 async function cdpCall(ctrl, tabId, method, params, signal) {
@@ -3475,6 +3776,243 @@ function registerDragTool(ctx, controller) {
 		}
 	}));
 }
+function registerAuditTool(ctx, controller) {
+	ctx.tools.register(defineTool({
+		name: "browser_audit",
+		description: "Read this plugin session's in-memory audit trail: every command sent to the browser extension (and every policy/gate refusal), with redacted params, outcome code and duration. Newest last; capped at 200 entries and wiped when dsh restarts. Values typed into pages and cookie values are redacted; eval expressions are truncated. Plugin-local read — works in read-only mode.",
+		parameters: {
+			command: {
+				type: "string",
+				description: "Only entries whose command contains this substring (e.g. \"nav\", \"cookies\", \"tabs\")."
+			},
+			tabId: {
+				type: "number",
+				description: "Only entries that carried this tabId."
+			},
+			sinceSeq: {
+				type: "number",
+				description: "Only entries with seq greater than this (paging)."
+			},
+			limit: {
+				type: "number",
+				description: `Max entries to return (newest last), 1–200; default 50.`
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					total: {
+						type: "number",
+						required: true
+					},
+					shown: {
+						type: "number",
+						required: true
+					},
+					entries: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								seq: {
+									type: "number",
+									required: true
+								},
+								t: {
+									type: "number",
+									required: true
+								},
+								command: {
+									type: "string",
+									required: true
+								},
+								tabId: { type: "number" },
+								params: {
+									type: "string",
+									required: true
+								},
+								ok: {
+									type: "boolean",
+									required: true
+								},
+								code: { type: "string" },
+								effectState: { type: "string" },
+								error: { type: "string" },
+								durationMs: {
+									type: "number",
+									required: true
+								}
+							}
+						}
+					}
+				}
+			},
+			render: (_args, value) => {
+				const v = value;
+				if (v.entries.length === 0) return [{
+					type: "text",
+					text: `Audit: ${v.total} entries, none match — the trail starts when a command is executed.`
+				}];
+				const lines = v.entries.map((e) => {
+					const tab = e.tabId === void 0 ? "" : ` tab ${e.tabId}`;
+					const outcome = e.ok ? "ok" : `FAIL ${e.code ?? "error"}${e.effectState ? `/${e.effectState}` : ""}`;
+					const err = e.ok || e.error === void 0 ? "" : ` — ${e.error}`;
+					return `#${e.seq} ${formatClock(e.t)} ${e.command}${tab} ${outcome} ${e.durationMs}ms ${e.params}${err}`;
+				});
+				return [{
+					type: "text",
+					text: clampRendered(`Audit: ${v.total} entries (showing ${v.shown})\n${lines.join("\n")}`)
+				}];
+			}
+		},
+		presentCall: () => ({
+			card: "generic",
+			title: "Browser audit",
+			kind: "other"
+		}),
+		async execute(args) {
+			const entries = controller.audit.list({
+				tabId: args.tabId,
+				command: args.command,
+				sinceSeq: args.sinceSeq,
+				limit: args.limit
+			});
+			return {
+				total: controller.audit.size(),
+				shown: entries.length,
+				entries
+			};
+		}
+	}));
+}
+function registerJournalTool(ctx, controller) {
+	ctx.tools.register(defineTool({
+		name: "browser_journal",
+		description: "Read the persistent command journal across dsh restarts: every command from previous runs of this plugin (written to <stateDir>/journal.jsonl, last 1000 entries), grouped by run. Same redaction as browser_audit. Plugin-local disk read — works with the extension offline and in read-only mode, so it is the way to recover \"what was I doing\" after a restart.",
+		parameters: {
+			command: {
+				type: "string",
+				description: "Only entries whose command contains this substring."
+			},
+			tabId: {
+				type: "number",
+				description: "Only entries that carried this tabId."
+			},
+			limit: {
+				type: "number",
+				description: "Max entries to return (newest last), 1–500; default 50."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					total: {
+						type: "number",
+						required: true
+					},
+					shown: {
+						type: "number",
+						required: true
+					},
+					runs: {
+						type: "number",
+						required: true
+					},
+					entries: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								run: {
+									type: "string",
+									required: true
+								},
+								seq: {
+									type: "number",
+									required: true
+								},
+								t: {
+									type: "number",
+									required: true
+								},
+								command: {
+									type: "string",
+									required: true
+								},
+								tabId: { type: "number" },
+								params: {
+									type: "string",
+									required: true
+								},
+								ok: {
+									type: "boolean",
+									required: true
+								},
+								code: { type: "string" },
+								effectState: { type: "string" },
+								error: { type: "string" },
+								durationMs: {
+									type: "number",
+									required: true
+								}
+							}
+						}
+					}
+				}
+			},
+			render: (_args, value) => {
+				const v = value;
+				if (v.entries.length === 0) return [{
+					type: "text",
+					text: `Journal: ${v.total} entries on disk, none match — nothing recorded across runs yet.`
+				}];
+				const lines = [];
+				let run = "";
+				for (const e of v.entries) {
+					if (e.run !== run) {
+						run = e.run;
+						lines.push(`── run ${run}`);
+					}
+					const tab = e.tabId === void 0 ? "" : ` tab ${e.tabId}`;
+					const outcome = e.ok ? "ok" : `FAIL ${e.code ?? "error"}`;
+					lines.push(`#${e.seq} ${formatClock(e.t)} ${e.command}${tab} ${outcome} ${e.durationMs}ms ${e.params}`);
+				}
+				return [{
+					type: "text",
+					text: clampRendered(`Journal: ${v.total} entries in ${v.runs} run(s) (showing ${v.shown})\n${lines.join("\n")}`)
+				}];
+			}
+		},
+		presentCall: () => ({
+			card: "generic",
+			title: "Browser journal",
+			kind: "other"
+		}),
+		async execute(args) {
+			const dir = controller.stateDir;
+			if (dir === void 0) throw new Error("browser-bridge is not configured yet — the journal has no stateDir to read");
+			const { total, entries } = await readJournal(dir, {
+				command: args.command,
+				tabId: args.tabId,
+				limit: args.limit
+			});
+			return {
+				total,
+				shown: entries.length,
+				runs: new Set(entries.map((e) => e.run)).size,
+				entries
+			};
+		}
+	}));
+}
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 function apply(ctx, config) {
 	const resolved = config;