@angelky7/dsh-browser-control 1.7.2 → 1.7.4

package/lib/index.js

@@ -926,6 +926,92 @@ 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/index.js
 /**
@@ -1054,6 +1140,8 @@ var BridgeController = class {
 	lastError;
 	chain = Promise.resolve();
 	current;
+	/** 操作审计账本（内存环形缓冲，200 条；命令层记录，见 audit.ts 顶部注释）。 */
+	audit = new AuditLog();
 	constructor(log) {
 		this.log = log;
 	}
@@ -1061,6 +1149,17 @@ var BridgeController = class {
 	get shotsDir() {
 		return this.current === void 0 ? void 0 : path.resolve(this.current.shotsDir);
 	}
+	/**
+	* Current policy flags. Tools that compose several commands (browser_drag
+	* runs `cdp`/`eval`) read this to refuse with a tool-level message; the
+	* per-command gate in execute() stays as the enforcement backstop.
+	*/
+	get policy() {
+		return {
+			readOnly: this.current?.readOnly === true,
+			allowScript: this.current?.allowScript !== false
+		};
+	}
 	/** Version the connected extension reported in its hello frame, if any. */
 	extensionVersion() {
 		return this.server?.status.hello?.version;
@@ -1087,6 +1186,15 @@ var BridgeController = class {
 	*/
 	requireExtensionCommand(command, since) {
 		if (this.hasExtensionCommand(command)) return;
+		this.audit.record({
+			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);
 	}
 	/**
@@ -1148,13 +1256,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.audit.record({
+				command,
+				tabId,
+				params: summary,
+				ok: true,
+				durationMs: Date.now() - started
+			});
+			return result;
+		} catch (error) {
+			const code = error.code;
+			const effectState = error.effectState;
+			this.audit.record({
+				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.
@@ -1179,13 +1314,36 @@ 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.audit.record({
+					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.audit.record({
+				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. */
@@ -3135,6 +3293,448 @@ function applyBrowserTools(ctx, controller) {
 			return await controller.execute("metrics", params, exec.signal);
 		}
 	}));
+	registerDragTool(ctx, controller);
+	registerAuditTool(ctx, controller);
+}
+/** One CDP round-trip over the embedded `cdp` passthrough (extension v1.7.2+). */
+async function cdpCall(ctrl, tabId, method, params, signal) {
+	return await ctrl.execute("cdp", {
+		method,
+		params,
+		tabId
+	}, signal);
+}
+function dragTargetArgs(selector, x, y, side) {
+	const hasSel = typeof selector === "string" && selector.length > 0;
+	const hasX = typeof x === "number" && Number.isFinite(x);
+	const hasY = typeof y === "number" && Number.isFinite(y);
+	if (hasSel && (hasX || hasY)) throw new Error(`${side}: give either "${side}" (CSS selector) or "${side}X"/"${side}Y" coordinates, not both`);
+	if (!hasSel && !(hasX && hasY)) throw new Error(`${side}: needs a CSS selector ("${side}") or both "${side}X" and "${side}Y" coordinates`);
+	if (hasSel) return { selector };
+	return {
+		x,
+		y
+	};
+}
+/**
+* Resolve a drag endpoint. Selector endpoints become viewport coordinates via
+* the CDP DOM domain — no page JavaScript, so mouse mode also works with
+* `allowScript: false`. Top document only; cross-origin iframes are a later
+* iteration.
+*/
+async function resolveDragPoint(ctrl, tabId, target, signal) {
+	if (target.selector === void 0) return {
+		x: target.x,
+		y: target.y
+	};
+	const selector = target.selector;
+	const rootId = (await cdpCall(ctrl, tabId, "DOM.getDocument", { depth: 0 }, signal))?.root?.nodeId;
+	if (typeof rootId !== "number") throw new Error("DOM.getDocument returned no root node");
+	const nodeId = (await cdpCall(ctrl, tabId, "DOM.querySelector", {
+		nodeId: rootId,
+		selector
+	}, signal))?.nodeId ?? 0;
+	if (nodeId === 0) throw new Error(`no element matches selector ${JSON.stringify(selector)} (top document only)`);
+	await cdpCall(ctrl, tabId, "DOM.scrollIntoViewIfNeeded", { nodeId }, signal);
+	let box;
+	try {
+		box = await cdpCall(ctrl, tabId, "DOM.getBoxModel", { nodeId }, signal);
+	} catch (error) {
+		throw new Error(`cannot measure ${JSON.stringify(selector)} — hidden, zero-size or detached? (${error instanceof Error ? error.message : String(error)})`);
+	}
+	const q = box?.model?.content;
+	if (!Array.isArray(q) || q.length < 8) throw new Error(`DOM.getBoxModel returned no quad for ${JSON.stringify(selector)}`);
+	return {
+		selector,
+		x: (q[0] + q[2] + q[4] + q[6]) / 4,
+		y: (q[1] + q[3] + q[5] + q[7]) / 4,
+		width: typeof box?.model?.width === "number" ? box.model.width : Math.hypot(q[2] - q[0], q[3] - q[1]),
+		height: typeof box?.model?.height === "number" ? box.model.height : Math.hypot(q[4] - q[2], q[5] - q[3]),
+		nodeId
+	};
+}
+/** Whether the source declares the native HTML5 `draggable` attribute. */
+async function sourceIsDraggable(ctrl, tabId, nodeId, signal) {
+	const attrs = await cdpCall(ctrl, tabId, "DOM.getAttributes", { nodeId }, signal);
+	const list = Array.isArray(attrs?.attributes) ? attrs.attributes.map(String) : [];
+	const at = list.indexOf("draggable");
+	return at >= 0 && list[at + 1] === "true";
+}
+/**
+* Synthesize a native-order HTML5 drag in the page: dragstart on the source,
+* dragenter/dragover on the target, drop only when dragover was prevented
+* (the browser's own rule), dragend on the source, all sharing one DataTransfer.
+* Untrusted events — pages that gate on `event.isTrusted` will ignore them,
+* which the tool description states instead of pretending otherwise.
+*/
+function html5DragExpression(fromSelector, to) {
+	const toExpr = to.selector !== void 0 ? `document.querySelector(${JSON.stringify(to.selector)})` : `document.elementFromPoint(${to.x}, ${to.y})`;
+	return `(() => {
+  const src = document.querySelector(${JSON.stringify(fromSelector)});
+  if (!src) return { error: 'no element matches from selector ' + ${JSON.stringify(fromSelector)} };
+  const dst = ${toExpr};
+  if (!dst) return { error: 'target element not found' };
+  const dt = new DataTransfer();
+  const log = [];
+  const sr = src.getBoundingClientRect();
+  const dr = dst.getBoundingClientRect();
+  const sx = sr.left + sr.width / 2, sy = sr.top + sr.height / 2;
+  const tx = dr.left + dr.width / 2, ty = dr.top + dr.height / 2;
+  const fire = (type, target, cx, cy) => {
+    const ev = new DragEvent(type, { bubbles: true, cancelable: true, composed: true, dataTransfer: dt, clientX: cx, clientY: cy });
+    target.dispatchEvent(ev);
+    log.push({ type, defaultPrevented: ev.defaultPrevented });
+    return ev.defaultPrevented;
+  };
+  const startCancelled = fire('dragstart', src, sx, sy);
+  let dragenterDefaultPrevented = false, overPrevented = false, dropFired = false, dropPrevented = false;
+  if (!startCancelled) {
+    dragenterDefaultPrevented = fire('dragenter', dst, tx, ty);
+    overPrevented = fire('dragover', dst, tx, ty);
+    if (overPrevented) {
+      dropFired = true;
+      dropPrevented = fire('drop', dst, tx, ty);
+    }
+  }
+  fire('dragend', src, sx, sy);
+  return { startCancelled, dragenterDefaultPrevented, overPrevented, dropFired, dropPrevented, events: log.length, log };
+})()`;
+}
+function roundDragPoint(p) {
+	const out = {
+		x: Math.round(p.x * 100) / 100,
+		y: Math.round(p.y * 100) / 100
+	};
+	if (p.selector !== void 0) out.selector = p.selector;
+	if (p.width !== void 0) out.width = Math.round(p.width * 100) / 100;
+	if (p.height !== void 0) out.height = Math.round(p.height * 100) / 100;
+	return out;
+}
+function registerDragTool(ctx, controller) {
+	ctx.tools.register(defineTool({
+		name: "browser_drag",
+		description: "Drag a page element or point onto another with real input. mode \"mouse\" sends trusted press→moves→release input via CDP (canvas, sliders, sortable widgets); mode \"html5\" synthesizes dragstart/dragover/drop in the page for [draggable] elements and needs page scripting; \"auto\" (default) picks html5 only when the source declares draggable=\"true\". Endpoints are CSS selectors (top document) or fromX/fromY + toX/toY viewport coordinates. Needs browser extension v1.7.2+ (embedded cdp channel).",
+		parameters: {
+			from: {
+				type: "string",
+				description: "CSS selector of the drag source; use fromX/fromY instead for raw coordinates."
+			},
+			to: {
+				type: "string",
+				description: "CSS selector of the drop target; use toX/toY instead for raw coordinates."
+			},
+			fromX: {
+				type: "number",
+				description: "Viewport x of the drag start point (with fromY)."
+			},
+			fromY: {
+				type: "number",
+				description: "Viewport y of the drag start point (with fromX)."
+			},
+			toX: {
+				type: "number",
+				description: "Viewport x of the drop point (with toY)."
+			},
+			toY: {
+				type: "number",
+				description: "Viewport y of the drop point (with toX)."
+			},
+			tabId: {
+				type: "number",
+				description: "Target tab; defaults to the active tab."
+			},
+			mode: {
+				type: "string",
+				description: "\"auto\" (default), \"mouse\" or \"html5\" — see the tool description."
+			},
+			steps: {
+				type: "number",
+				description: "Intermediate mouse moves in mouse mode, 1–50 (default 12)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					tabId: {
+						type: "number",
+						required: true
+					},
+					mode: {
+						type: "string",
+						required: true
+					},
+					from: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							selector: { type: "string" },
+							x: { type: "number" },
+							y: { type: "number" },
+							width: { type: "number" },
+							height: { type: "number" }
+						}
+					},
+					to: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							selector: { type: "string" },
+							x: { type: "number" },
+							y: { type: "number" },
+							width: { type: "number" },
+							height: { type: "number" }
+						}
+					},
+					steps: { type: "number" },
+					dispatched: { type: "number" },
+					startCancelled: { type: "boolean" },
+					dragenterDefaultPrevented: { type: "boolean" },
+					overPrevented: { type: "boolean" },
+					dropFired: { type: "boolean" },
+					dropPrevented: { type: "boolean" },
+					events: { type: "number" },
+					elapsedMs: {
+						type: "number",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => {
+				const v = value;
+				const d = (p) => p?.selector !== void 0 ? p.selector : `(${p?.x ?? "?"},${p?.y ?? "?"})`;
+				if (v.mode === "mouse") return [{
+					type: "text",
+					text: `Tab ${v.tabId}: dragged ${d(v.from)} → ${d(v.to)} with mouse input (${v.steps} steps, ${v.dispatched} dispatches, ${v.elapsedMs}ms)`
+				}];
+				const verdict = v.startCancelled === true ? "dragstart was cancelled by the page — nothing dropped" : v.overPrevented === true ? v.dropPrevented === true ? "drop fired and was handled" : "drop fired but no drop handler ran" : "target did not accept the drop (no dragover preventDefault)";
+				return [{
+					type: "text",
+					text: `Tab ${v.tabId}: dragged ${d(v.from)} → ${d(v.to)} with html5 events (${v.events} events, ${v.elapsedMs}ms) — ${verdict}`
+				}];
+			}
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: `Drag ${args.from ?? `(${args.fromX},${args.fromY})`} → ${args.to ?? `(${args.toX},${args.toY})`}`,
+			kind: "other"
+		}),
+		async execute(args, exec) {
+			const mode = args.mode === void 0 ? "auto" : args.mode;
+			if (mode !== "auto" && mode !== "mouse" && mode !== "html5") throw new Error(`mode must be "auto", "mouse" or "html5" — got ${JSON.stringify(mode)}`);
+			const from = dragTargetArgs(args.from, args.fromX, args.fromY, "from");
+			const to = dragTargetArgs(args.to, args.toX, args.toY, "to");
+			controller.requireExtensionCommand("cdp", "1.7.2");
+			if (controller.policy.readOnly) throw new Error("browser_drag changes page state and read-only mode is on — turn readOnly off in the browser-bridge config to drag");
+			let tabId = args.tabId;
+			if (tabId === void 0) {
+				const listing = await controller.execute("tabs.list", {}, exec.signal);
+				if (typeof listing?.activeTabId !== "number") throw new Error("could not resolve the active tab — pass tabId explicitly");
+				tabId = listing.activeTabId;
+			}
+			const started = Date.now();
+			let resolvedMode = mode === "auto" ? "mouse" : mode;
+			let source;
+			if (mode !== "html5") source = await resolveDragPoint(controller, tabId, from, exec.signal);
+			if (mode === "auto" && source?.nodeId !== void 0 && await sourceIsDraggable(controller, tabId, source.nodeId, exec.signal)) resolvedMode = "html5";
+			if (resolvedMode === "mouse") {
+				const target = await resolveDragPoint(controller, tabId, to, exec.signal);
+				const steps = Math.min(50, Math.max(1, Math.trunc(typeof args.steps === "number" ? args.steps : 12)));
+				const sx = source.x, sy = source.y, tx = target.x, ty = target.y;
+				const dispatch = async (params) => {
+					await cdpCall(controller, tabId, "Input.dispatchMouseEvent", params, exec.signal);
+				};
+				await dispatch({
+					type: "mouseMoved",
+					x: sx,
+					y: sy,
+					button: "none",
+					buttons: 0
+				});
+				await dispatch({
+					type: "mousePressed",
+					x: sx,
+					y: sy,
+					button: "left",
+					buttons: 1,
+					clickCount: 1
+				});
+				for (let i = 1; i <= steps; i++) {
+					const f = i / steps;
+					await dispatch({
+						type: "mouseMoved",
+						x: sx + (tx - sx) * f,
+						y: sy + (ty - sy) * f,
+						button: "left",
+						buttons: 1
+					});
+				}
+				await dispatch({
+					type: "mouseReleased",
+					x: tx,
+					y: ty,
+					button: "left",
+					buttons: 0,
+					clickCount: 1
+				});
+				await dispatch({
+					type: "mouseMoved",
+					x: tx,
+					y: ty,
+					button: "none",
+					buttons: 0
+				});
+				return {
+					tabId,
+					mode: "mouse",
+					from: roundDragPoint(source),
+					to: roundDragPoint(target),
+					steps,
+					dispatched: steps + 4,
+					elapsedMs: Date.now() - started
+				};
+			}
+			if (from.selector === void 0) throw new Error("html5 mode needs a CSS selector for \"from\" (a point has no draggable element)");
+			if (!controller.policy.allowScript) throw new Error("html5 drag synthesizes DOM events and needs page scripting — allowScript is off; use mode:\"mouse\" or re-enable the script switch");
+			const raw = await controller.execute("eval", {
+				expression: html5DragExpression(from.selector, to),
+				tabId
+			}, exec.signal);
+			const outcome = raw?.value;
+			if (outcome === void 0 || typeof outcome !== "object") throw new Error("html5 drag expression returned no outcome — page may have navigated mid-drag");
+			if (typeof outcome.error === "string") throw new Error(outcome.error);
+			return {
+				tabId: typeof raw?.tabId === "number" ? raw.tabId : tabId,
+				mode: "html5",
+				from: from.selector !== void 0 ? { selector: from.selector } : roundDragPoint(from),
+				to: to.selector !== void 0 ? { selector: to.selector } : {
+					x: to.x,
+					y: to.y
+				},
+				startCancelled: outcome.startCancelled === true,
+				dragenterDefaultPrevented: outcome.dragenterDefaultPrevented === true,
+				overPrevented: outcome.overPrevented === true,
+				dropFired: outcome.dropFired === true,
+				dropPrevented: outcome.dropPrevented === true,
+				events: typeof outcome.events === "number" ? outcome.events : 0,
+				elapsedMs: Date.now() - started
+			};
+		}
+	}));
+}
+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
+			};
+		}
+	}));
 }
 /** Cordis plugin entry: wire the settings-driven lifecycle plus the model-facing tools. */
 function apply(ctx, config) {