@mind-harness/mh-browser 0.1.5 → 0.2.0

package/lib/index.js

@@ -3,12 +3,12 @@ import z from "@deepseek-ai/schemastery";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import { isDeepStrictEqual } from "node:util";
 import { HarnessError, createUserMessage } from "@deepseek-ai/dsh-llm";
-import { z as z$1 } from "zod";
+import { assertSupportedJsonSchema, defineTool, validateJsonSchemaValue } from "@deepseek-ai/dsh-tools";
 import { createHash, randomUUID } from "node:crypto";
+import { parse } from "yaml";
 import { constants, readFileSync } from "node:fs";
 import { lstat, mkdir, open, readFile, realpath, unlink, writeFile } from "node:fs/promises";
-import { parse } from "yaml";
-import { assertSupportedJsonSchema, defineTool, validateJsonSchemaValue } from "@deepseek-ai/dsh-tools";
+import { z as z$1 } from "zod";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { chromium } from "playwright";
 import { fileURLToPath } from "node:url";
@@ -16,502 +16,21 @@ import { UserQuestionError } from "@deepseek-ai/dsh-user-questions";
 //#region lib/types/config.js
 const browserConfig = z.object({
 	presence: z.object({ maxBytes: z.number().step(1).min(1).required().description("Most bytes of page text one presence reminder may carry.") }).required().description("Pages kept in context across steps."),
-	browser: z.union([
-		"chrome",
-		"msedge",
-		"chromium"
-	]).default("chrome").description("Which installed browser to drive. chromium is the one Playwright downloads."),
-	profileDir: z.string().description("Browser profile directory, kept between runs. Defaults to mh/profiles/<dsh profile>/browser under the dsh home."),
-	headless: z.boolean().default(false).description("Run the browser without a window.")
-});
-/**
-* Browser profile directory when the configuration names none. Each dsh profile gets its own:
-* a browser profile directory admits one running browser, so two dsh profiles sharing one
-* cannot both start.
-*/
-function defaultProfileDir(profile, home = resolveDshHome()) {
-	return profile === void 0 ? join(home, "mh", "browser") : join(home, "mh", "profiles", profile.name, "browser");
-}
-//#endregion
-//#region lib/types/presence/record.js
-/** Structured presence record carried on a message source. The model sees the rendered text, not this. */
-const PRESENCE_SOURCES = [
-	"person via sidebar",
-	"cwd reference",
-	"model"
-];
-//#endregion
-//#region lib/types/presence/fold.js
-function initPresenceLog() {
-	return {
-		committed: [],
-		inbox: {
-			"next-step": [],
-			"next-turn": []
-		},
-		discarded: [],
-		visible: false,
-		hidden: false,
-		shown: [],
-		ops: []
-	};
-}
-function applyPresenceLog(state, event) {
-	if (event.type === "compaction/summary") {
-		if (!state.visible && state.shown.length === 0) return state;
-		return {
-			...state,
-			visible: false,
-			hidden: true,
-			shown: []
-		};
-	}
-	if (event.type === "user/message") {
-		const carried = carriedOf(event.data, `history:${String(event.seq)}`);
-		if (carried === void 0) return state;
-		return {
-			...state,
-			committed: applyRecord(state.committed, carried.record, "committed"),
-			inbox: {
-				"next-step": state.inbox["next-step"].map((item) => item?.id === carried.id ? null : item),
-				"next-turn": state.inbox["next-turn"].map((item) => item?.id === carried.id ? null : item)
-			},
-			discarded: [],
-			visible: true,
-			hidden: false,
-			shown: [...state.shown, textDigest(event.data)],
-			ops: []
-		};
-	}
-	if (event.type === "agent/inbox/discarded") {
-		const carried = carriedOf(event.data, `discarded:${String(event.seq)}`);
-		if (carried === void 0) return state;
-		return {
-			...state,
-			discarded: [...state.discarded, carried]
-		};
-	}
-	if (event.type === "agent/inbox/spliced") return applySplice(state, event);
-	if (event.type === "tool/result") return applyReceipts(state, event);
-	return state;
-}
-/** The folded set, with pending reminders and unannounced receipts on top. */
-function presenceSet(state) {
-	let pages = state.committed;
-	for (const carried of [
-		...state.inbox["next-turn"],
-		...state.inbox["next-step"],
-		...state.discarded
-	]) if (carried !== null) pages = applyRecord(pages, carried.record, "pending");
-	const removals = [];
-	for (const op of state.ops) {
-		const index = pages.findIndex((page) => page.url === op.url);
-		if (op.op === "remove") {
-			if (index < 0) continue;
-			pages = pages.toSpliced(index, 1);
-			removals.push(op);
-			continue;
-		}
-		if (index >= 0) continue;
-		pages = [...pages, {
-			url: op.url,
-			source: "model",
-			state: "pending",
-			order: pages.length
-		}];
-	}
-	return {
-		pages,
-		removals
-	};
-}
-/** The text of a reminder, as `shown` records it. */
-function textDigest(message) {
-	return createHash("sha256").update(textOf$3(message)).digest("hex");
-}
-function applySplice(state, event) {
-	const data = record$3(event.data);
-	const target = data.target === "next-turn" ? "next-turn" : "next-step";
-	const start = typeof data.start === "number" ? data.start : 0;
-	const removedCount = typeof data.removedCount === "number" ? data.removedCount : 0;
-	const slots = (Array.isArray(data.inserted) ? data.inserted : []).map((item, index) => carriedOf(item, `splice:${String(event.seq)}:${String(index)}`));
-	const list = state.inbox[target];
-	const removed = list.slice(start, start + removedCount).filter((item) => item !== null);
-	if (removedCount === 0 && slots.length === 0) return state;
-	const next = [
-		...list.slice(0, start),
-		...slots.map((slot) => slot ?? null),
-		...list.slice(start + removedCount)
-	];
-	const announced = slots.some((slot) => slot !== void 0);
-	return {
-		...state,
-		inbox: {
-			...state.inbox,
-			[target]: next
-		},
-		discarded: data.outcome === "canceled" ? [...state.discarded, ...removed] : state.discarded,
-		ops: announced ? [] : state.ops
-	};
-}
-function applyReceipts(state, event) {
-	const data = record$3(event.data);
-	if (record$3(data.message).isError === true) return state;
-	const meta = record$3(data.meta);
-	if (meta.by !== "mh-browser" || meta.action !== "presence" || !Array.isArray(meta.receipts)) return state;
-	const ops = [];
-	for (const item of meta.receipts) {
-		const row = record$3(item);
-		if (typeof row.url !== "string" || row.url === "") continue;
-		if (row.receipt === "added (pending)") ops.push({
-			op: "put",
-			url: row.url
-		});
-		if (row.receipt === "removed (pending)") ops.push({
-			op: "remove",
-			url: row.url
-		});
-	}
-	return ops.length === 0 ? state : {
-		...state,
-		ops: [...state.ops, ...ops]
-	};
-}
-function applyRecord(pages, record, state) {
-	if (record.kind === "baseline") {
-		const next = [];
-		for (const entry of record.entries) {
-			if (entry.op === "removed") continue;
-			next.push(heldFrom(entry, state, next.length));
-		}
-		return next;
-	}
-	const next = pages.map((page) => ({ ...page }));
-	for (const entry of record.entries) {
-		if (entry.op === "removed") {
-			const index = next.findIndex((page) => page.url === entry.url);
-			if (index >= 0) next.splice(index, 1);
-			continue;
-		}
-		const index = next.findIndex((page) => page.url === entry.url);
-		const held = heldFrom(entry, state, index >= 0 ? next[index]?.order ?? index : next.length);
-		if (index >= 0) next[index] = held;
-		else next.push(held);
-	}
-	return next;
-}
-function heldFrom(entry, state, order) {
-	const absent = entry.op === "absent";
-	return {
-		url: entry.url,
-		source: entry.source,
-		state,
-		order,
-		seen: absent ? { absent: entry.reason ?? "" } : {
-			digest: entry.digest,
-			observedAt: entry.observedAt,
-			...entry.version === void 0 ? {} : { version: entry.version },
-			...entry.id === void 0 ? {} : { id: entry.id }
-		}
-	};
-}
-/** A `user/message` event's data is the message itself. */
-function carriedOf(data, fallbackId) {
-	const message = record$3(data);
-	const source = record$3(message.source);
-	if (source.kind !== "mh-browser") return void 0;
-	const presence = record$3(source.presence);
-	const kind = presence.kind;
-	if (kind !== "baseline" && kind !== "delta") return void 0;
-	const entries = Array.isArray(presence.entries) ? presence.entries.flatMap((item) => entryOf$1(item)) : [];
-	return {
-		id: typeof message.id === "string" && message.id !== "" ? message.id : fallbackId,
-		record: {
-			kind,
-			entries,
-			...presence.replaces === true ? { replaces: true } : {}
-		}
-	};
-}
-function entryOf$1(value) {
-	const row = record$3(value);
-	const op = row.op;
-	if (op !== "present" && op !== "added" && op !== "changed" && op !== "absent" && op !== "removed") return [];
-	const url = typeof row.url === "string" ? row.url : "";
-	if (url === "") return [];
-	const source = isSource(row.source) ? row.source : "model";
-	const version = typeof row.version === "string" ? row.version : void 0;
-	const id = typeof row.id === "string" && row.id !== "" ? row.id : void 0;
-	const reason = typeof row.reason === "string" ? row.reason : void 0;
-	return [{
-		op,
-		url,
-		source,
-		observedAt: typeof row.observedAt === "string" ? row.observedAt : "",
-		digest: typeof row.digest === "string" ? row.digest : "",
-		...version === void 0 ? {} : { version },
-		...id === void 0 ? {} : { id },
-		...reason === void 0 ? {} : { reason }
-	}];
-}
-function textOf$3(value) {
-	const content = record$3(value).content;
-	if (!Array.isArray(content)) return "";
-	return content.map((block) => record$3(block).text).filter((text) => typeof text === "string").join("\n");
-}
-function isSource(value) {
-	return typeof value === "string" && PRESENCE_SOURCES.includes(value);
-}
-function record$3(value) {
-	if (value !== null && typeof value === "object" && !Array.isArray(value)) return value;
-	return {};
-}
-//#endregion
-//#region lib/types/types.js
-/** Public browser types. Playwright types stay inside the service. */
-var MhBrowserError = class extends Error {
-	code;
-	page;
-	constructor(code, message, page) {
-		super(message);
-		this.name = "MhBrowserError";
-		this.code = code;
-		if (page !== void 0) this.page = page;
-	}
-};
-/** Owner of the person's own window. It belongs to no Session. */
-const PERSON_OWNER = "person";
-const UNKNOWN_TAB = "UNKNOWN_TAB";
-const UNKNOWN_TAB_REASON = "no such tab in this session";
-/**
-* Internal: a wait ended because its signal aborted. A tool never reports it:
-* a stopped call ends as the tool runtime's abort, a takeover as `TAKEN_OVER`.
-*/
-const INTERRUPTED = "INTERRUPTED";
-/** The browser did not start or could not be restarted. */
-const BROWSER_UNAVAILABLE = "BROWSER_UNAVAILABLE";
-function unknownTab() {
-	return {
-		url: "",
-		reason: UNKNOWN_TAB_REASON
-	};
-}
-//#endregion
-//#region lib/types/tools/session.js
-/** dsh shows the model only the message, so the message starts with the code. */
-var BrowserToolError = class extends HarnessError {
-	reason;
-	constructor(code, reason) {
-		super(`${code}: ${reason}`, code);
-		this.name = "BrowserToolError";
-		this.reason = reason;
-	}
-};
-const NO_WORKSPACE_REASON$1 = "this session has no working directory";
-/**
-* The session of this tool call. Also records its title for the tab group.
-* No title service, or no title yet, records an empty one.
-*/
-function sessionFor(ctx, exec) {
-	const session = sessionOf(exec);
-	const titles = ctx.get("sessionTitle");
-	ctx.mhBrowser.noteSessionTitle(session.id, titles?.get(session.session)?.title ?? "");
-	return session;
-}
-/** A title written after the last tool call still reaches the tab group. */
-function followSessionTitles(ctx) {
-	ctx.on("session/event", (session, event) => {
-		const { type, data } = event;
-		if (type !== "session/title" || typeof data !== "object" || data === null) return;
-		const title = data.title;
-		if (typeof title === "string") ctx.mhBrowser.noteSessionTitle(session.id, title);
-	});
-}
-function sessionOf(exec) {
-	const session = exec.agent?.session;
-	if (session === void 0) throw new BrowserToolError("NO_SESSION", "browser tools run only inside an agent session");
-	const cwd = session.header.cwd;
-	return cwd === void 0 ? {
-		id: session.id,
-		session
-	} : {
-		id: session.id,
-		cwd,
-		session
-	};
-}
-/**
-* Where this session may write a download. With dsh's sandbox policy loaded,
-* its mode decides: `read-only` writes nothing, otherwise the policy's
-* workspace root. Without it, the session cwd.
-*/
-function writeTarget(ctx, session) {
-	const policy = ctx.get("sandboxPolicy");
-	if (policy === void 0) return session.cwd === void 0 ? {
-		denied: NO_WORKSPACE_REASON$1,
-		code: "NO_WORKSPACE"
-	} : { root: session.cwd };
-	const resolved = policy.resolve({ session: session.session });
-	if (resolved.mode === "read-only") return {
-		denied: "[sandbox: file access denied under read-only mode]",
-		code: "SANDBOX_DENIED"
-	};
-	return { root: resolved.workspaceRoot };
-}
-function rethrow(error, detail) {
-	if (error instanceof MhBrowserError || error instanceof BrowserToolError) {
-		const reason = error instanceof BrowserToolError ? error.reason : error.message;
-		throw new BrowserToolError(error.code, detail === void 0 ? reason : `${reason}\n${detail}`);
-	}
-	throw error;
-}
-//#endregion
-//#region lib/types/tools/paths.js
-/** Resolve upload paths and reject anything outside the session's cwd. */
-async function filesInWorkspace(cwd, files) {
-	if (cwd === void 0) throw new BrowserToolError("NO_WORKSPACE", NO_WORKSPACE_REASON$1);
-	const root = await realpath(cwd);
-	const resolved = [];
-	for (const file of files) {
-		const abs = isAbsolute(file) ? file : resolve(cwd, file);
-		let real;
-		try {
-			real = await realpath(abs);
-		} catch {
-			throw new BrowserToolError("INVALID_ARGS", `no such file: ${file}`);
-		}
-		const fromRoot = relative(root, real);
-		if (fromRoot.startsWith("..") || isAbsolute(fromRoot)) throw new BrowserToolError("OUTSIDE_WORKSPACE", `${file} is outside the session workspace`);
-		resolved.push(real);
-	}
-	return resolved;
-}
-/** Refuse a filename that leaves the session's write root, without creating it. */
-async function assertInside(target, filename) {
-	await place(target, filename);
-}
-/**
-* Write `filename` under the session's write root. A path that leaves the
-* root is refused, through a symbolic link as well: the deepest existing
-* directory is checked before any is created, and the file itself is not
-* followed if it is a link.
-*/
-async function writeInside(target, filename, data) {
-	const file = await place(target, filename);
-	assertUnder(file.root, await realpath(await deepestExisting(dirname(file.file))), filename);
-	await mkdir(dirname(file.file), { recursive: true });
-	const parent = await realpath(dirname(file.file));
-	assertUnder(file.root, parent, filename);
-	const placed = resolve(parent, basename(file.file));
-	let handle;
-	try {
-		handle = await open(placed, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW);
-	} catch (error) {
-		if (error.code === "ELOOP") throw new BrowserToolError("OUTSIDE_WORKSPACE", `${filename} is outside the session workspace`);
-		throw error;
-	}
-	try {
-		await handle.writeFile(data);
-	} finally {
-		await handle.close();
-	}
-	const bytes = typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
-	return {
-		path: relative(file.root, placed),
-		bytes
-	};
-}
-function assertUnder(root, path, filename) {
-	const fromRoot = relative(root, path);
-	if (fromRoot.startsWith("..") || isAbsolute(fromRoot)) throw new BrowserToolError("OUTSIDE_WORKSPACE", `${filename} is outside the session workspace`);
-}
-async function deepestExisting(path) {
-	for (let current = path;; current = dirname(current)) try {
-		await lstat(current);
-		return current;
-	} catch {
-		if (dirname(current) === current) return current;
-	}
-}
-async function place(target, filename) {
-	if ("denied" in target) throw new BrowserToolError(target.code, target.denied);
-	if (filename.trim() === "") throw new BrowserToolError("INVALID_ARGS", "filename: give a path inside the workspace");
-	const root = await realpath(target.root).catch(() => target.root);
-	const abs = isAbsolute(filename) ? filename : resolve(root, filename);
-	const direct = relative(root, abs);
-	if (direct.startsWith("..") || isAbsolute(direct)) throw new BrowserToolError("OUTSIDE_WORKSPACE", `${filename} is outside the session workspace`);
-	return {
-		root,
-		file: abs
-	};
-}
-//#endregion
-//#region lib/types/tools/attachments.js
-function initAttachments() {
-	return { refs: {} };
-}
-/** Attachments reach the model in user messages and tool results. */
-function applyAttachments(state, event) {
-	if (event.type !== "user/message" && event.type !== "tool/result") return state;
-	const found = {};
-	visit(event.data, 0, found);
-	const ids = Object.keys(found).filter((id) => state.refs[id] === void 0);
-	if (ids.length === 0) return state;
-	const refs = { ...state.refs };
-	for (const id of ids) refs[id] = found[id];
-	return { refs };
-}
+	browser: z.union([
+		"chrome",
+		"msedge",
+		"chromium"
+	]).default("chrome").description("Which installed browser to drive. chromium is the one Playwright downloads."),
+	profileDir: z.string().description("Browser profile directory, kept between runs. Defaults to mh/profiles/<dsh profile>/browser under the dsh home."),
+	headless: z.boolean().default(false).description("Run the browser without a window.")
+});
 /**
-* Host paths for upload values. A value naming an attachment that appeared in
-* this session resolves through the attachment provider; anything else is a
-* path that must resolve inside the session cwd.
+* Browser profile directory when the configuration names none. Each dsh profile gets its own:
+* a browser profile directory admits one running browser, so two dsh profiles sharing one
+* cannot both start.
 */
-async function uploadPaths(ctx, seen, cwd, values) {
-	const paths = [];
-	for (const value of values) {
-		const id = attachmentIdOf(value);
-		const found = id === void 0 ? void 0 : seen.refs[id];
-		if (found !== void 0) {
-			paths.push(hostPath(ctx, found));
-			continue;
-		}
-		if (typeof value !== "string") throw new BrowserToolError("INVALID_INPUT", "attachment reference is not in this session");
-		paths.push(...await filesInWorkspace(cwd, [value]));
-	}
-	return paths;
-}
-function hostPath(ctx, found) {
-	let host;
-	try {
-		host = found.kind === "image" ? ctx.attachments.imageHostPath(found.ref) : ctx.attachments.fileHostPath(found.ref);
-	} catch (error) {
-		throw new BrowserToolError("INVALID_INPUT", error instanceof Error ? error.message : String(error));
-	}
-	if (host === void 0) throw new BrowserToolError("INVALID_INPUT", "attachment has no host path");
-	return host;
-}
-function attachmentIdOf(value) {
-	if (typeof value === "string") return value;
-	if (value !== null && typeof value === "object") {
-		const id = value.attachmentId;
-		if (typeof id === "string") return id;
-	}
-}
-function visit(value, depth, found) {
-	if (depth > 12 || value === null || typeof value !== "object") return;
-	if (Array.isArray(value)) {
-		for (const item of value) visit(item, depth + 1, found);
-		return;
-	}
-	const row = value;
-	if (typeof row.attachmentId === "string" && typeof row.bytes === "number") {
-		const kind = typeof row.width === "number" && typeof row.mediaType === "string" ? "image" : "file";
-		if (kind === "image" || typeof row.name === "string") found[row.attachmentId] = {
-			kind,
-			ref: row
-		};
-	}
-	for (const item of Object.values(row)) visit(item, depth + 1, found);
+function defaultProfileDir(profile, home = resolveDshHome()) {
+	return profile === void 0 ? join(home, "mh", "browser") : join(home, "mh", "profiles", profile.name, "browser");
 }
 //#endregion
 //#region lib/types/representation/agent-view.js
@@ -906,25 +425,272 @@ function pageBody(view) {
 	if (view.status !== void 0) return `The site answered HTTP ${String(view.status)}; the ${view.mediaType} body is not shown.`;
 	return "Not an HTML page; use browser_download to save it into the workspace.";
 }
-function versionOf$1(view) {
-	const representation = view.representation;
-	if (representation.kind === "agent-view") return representation.version;
-	return representation.agentView?.version;
+function versionOf$1(view) {
+	const representation = view.representation;
+	if (representation.kind === "agent-view") return representation.version;
+	return representation.agentView?.version;
+}
+function digestOf$1(view) {
+	if (view.representation.kind !== "agent-view") return void 0;
+	return representationDigest(view.representation.text);
+}
+function idOf(view) {
+	if (view.representation.kind !== "agent-view") return void 0;
+	return agentViewId(view.representation.text, view.url);
+}
+function attr$1(name, value) {
+	return ` ${name}="${escapeAttr(value)}"`;
+}
+function formatSeconds(seconds) {
+	const rounded = Math.round(seconds * 10) / 10;
+	return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+}
+//#endregion
+//#region lib/types/types.js
+/** Public browser types. Playwright types stay inside the service. */
+var MhBrowserError = class extends Error {
+	code;
+	page;
+	constructor(code, message, page) {
+		super(message);
+		this.name = "MhBrowserError";
+		this.code = code;
+		if (page !== void 0) this.page = page;
+	}
+};
+/** Owner of the person's own window. It belongs to no Session. */
+const PERSON_OWNER = "person";
+const UNKNOWN_TAB = "UNKNOWN_TAB";
+const UNKNOWN_TAB_REASON = "no such tab in this session";
+/**
+* Internal: a wait ended because its signal aborted. A tool never reports it:
+* a stopped call ends as the tool runtime's abort, a takeover as `TAKEN_OVER`.
+*/
+const INTERRUPTED = "INTERRUPTED";
+/** The browser did not start or could not be restarted. */
+const BROWSER_UNAVAILABLE = "BROWSER_UNAVAILABLE";
+function unknownTab() {
+	return {
+		url: "",
+		reason: UNKNOWN_TAB_REASON
+	};
+}
+//#endregion
+//#region lib/types/tools/session.js
+/** dsh shows the model only the message, so the message starts with the code. */
+var BrowserToolError = class extends HarnessError {
+	reason;
+	constructor(code, reason) {
+		super(`${code}: ${reason}`, code);
+		this.name = "BrowserToolError";
+		this.reason = reason;
+	}
+};
+const NO_WORKSPACE_REASON$1 = "this session has no working directory";
+/**
+* The session of this tool call. Also records its title for the tab group.
+* No title service, or no title yet, records an empty one.
+*/
+function sessionFor(ctx, exec) {
+	const session = sessionOf(exec);
+	const titles = ctx.get("sessionTitle");
+	ctx.mhBrowser.noteSessionTitle(session.id, titles?.get(session.session)?.title ?? "");
+	return session;
+}
+/** A title written after the last tool call still reaches the tab group. */
+function followSessionTitles(ctx) {
+	ctx.on("session/event", (session, event) => {
+		const { type, data } = event;
+		if (type !== "session/title" || typeof data !== "object" || data === null) return;
+		const title = data.title;
+		if (typeof title === "string") ctx.mhBrowser.noteSessionTitle(session.id, title);
+	});
+}
+function sessionOf(exec) {
+	const session = exec.agent?.session;
+	if (session === void 0) throw new BrowserToolError("NO_SESSION", "browser tools run only inside an agent session");
+	const cwd = session.header.cwd;
+	return cwd === void 0 ? {
+		id: session.id,
+		session
+	} : {
+		id: session.id,
+		cwd,
+		session
+	};
+}
+/**
+* Where this session may write a download. With dsh's sandbox policy loaded,
+* its mode decides: `read-only` writes nothing, otherwise the policy's
+* workspace root. Without it, the session cwd.
+*/
+function writeTarget(ctx, session) {
+	const policy = ctx.get("sandboxPolicy");
+	if (policy === void 0) return session.cwd === void 0 ? {
+		denied: NO_WORKSPACE_REASON$1,
+		code: "NO_WORKSPACE"
+	} : { root: session.cwd };
+	const resolved = policy.resolve({ session: session.session });
+	if (resolved.mode === "read-only") return {
+		denied: "[sandbox: file access denied under read-only mode]",
+		code: "SANDBOX_DENIED"
+	};
+	return { root: resolved.workspaceRoot };
+}
+function rethrow(error, detail) {
+	if (error instanceof MhBrowserError || error instanceof BrowserToolError) {
+		const reason = error instanceof BrowserToolError ? error.reason : error.message;
+		throw new BrowserToolError(error.code, detail === void 0 ? reason : `${reason}\n${detail}`);
+	}
+	throw error;
+}
+//#endregion
+//#region lib/types/tools/paths.js
+/** Resolve upload paths and reject anything outside the session's cwd. */
+async function filesInWorkspace(cwd, files) {
+	if (cwd === void 0) throw new BrowserToolError("NO_WORKSPACE", NO_WORKSPACE_REASON$1);
+	const root = await realpath(cwd);
+	const resolved = [];
+	for (const file of files) {
+		const abs = isAbsolute(file) ? file : resolve(cwd, file);
+		let real;
+		try {
+			real = await realpath(abs);
+		} catch {
+			throw new BrowserToolError("INVALID_ARGS", `no such file: ${file}`);
+		}
+		const fromRoot = relative(root, real);
+		if (fromRoot.startsWith("..") || isAbsolute(fromRoot)) throw new BrowserToolError("OUTSIDE_WORKSPACE", `${file} is outside the session workspace`);
+		resolved.push(real);
+	}
+	return resolved;
+}
+/** Refuse a filename that leaves the session's write root, without creating it. */
+async function assertInside(target, filename) {
+	await place(target, filename);
+}
+/**
+* Write `filename` under the session's write root. A path that leaves the
+* root is refused, through a symbolic link as well: the deepest existing
+* directory is checked before any is created, and the file itself is not
+* followed if it is a link.
+*/
+async function writeInside(target, filename, data) {
+	const file = await place(target, filename);
+	assertUnder(file.root, await realpath(await deepestExisting(dirname(file.file))), filename);
+	await mkdir(dirname(file.file), { recursive: true });
+	const parent = await realpath(dirname(file.file));
+	assertUnder(file.root, parent, filename);
+	const placed = resolve(parent, basename(file.file));
+	let handle;
+	try {
+		handle = await open(placed, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW);
+	} catch (error) {
+		if (error.code === "ELOOP") throw new BrowserToolError("OUTSIDE_WORKSPACE", `${filename} is outside the session workspace`);
+		throw error;
+	}
+	try {
+		await handle.writeFile(data);
+	} finally {
+		await handle.close();
+	}
+	const bytes = typeof data === "string" ? Buffer.byteLength(data) : data.byteLength;
+	return {
+		path: relative(file.root, placed),
+		bytes
+	};
+}
+function assertUnder(root, path, filename) {
+	const fromRoot = relative(root, path);
+	if (fromRoot.startsWith("..") || isAbsolute(fromRoot)) throw new BrowserToolError("OUTSIDE_WORKSPACE", `${filename} is outside the session workspace`);
+}
+async function deepestExisting(path) {
+	for (let current = path;; current = dirname(current)) try {
+		await lstat(current);
+		return current;
+	} catch {
+		if (dirname(current) === current) return current;
+	}
+}
+async function place(target, filename) {
+	if ("denied" in target) throw new BrowserToolError(target.code, target.denied);
+	if (filename.trim() === "") throw new BrowserToolError("INVALID_ARGS", "filename: give a path inside the workspace");
+	const root = await realpath(target.root).catch(() => target.root);
+	const abs = isAbsolute(filename) ? filename : resolve(root, filename);
+	const direct = relative(root, abs);
+	if (direct.startsWith("..") || isAbsolute(direct)) throw new BrowserToolError("OUTSIDE_WORKSPACE", `${filename} is outside the session workspace`);
+	return {
+		root,
+		file: abs
+	};
+}
+//#endregion
+//#region lib/types/tools/attachments.js
+function initAttachments() {
+	return { refs: {} };
 }
-function digestOf$1(view) {
-	if (view.representation.kind !== "agent-view") return void 0;
-	return representationDigest(view.representation.text);
+/** Attachments reach the model in user messages and tool results. */
+function applyAttachments(state, event) {
+	if (event.type !== "user/message" && event.type !== "tool/result") return state;
+	const found = {};
+	visit(event.data, 0, found);
+	const ids = Object.keys(found).filter((id) => state.refs[id] === void 0);
+	if (ids.length === 0) return state;
+	const refs = { ...state.refs };
+	for (const id of ids) refs[id] = found[id];
+	return { refs };
 }
-function idOf(view) {
-	if (view.representation.kind !== "agent-view") return void 0;
-	return agentViewId(view.representation.text, view.url);
+/**
+* Host paths for upload values. A value naming an attachment that appeared in
+* this session resolves through the attachment provider; anything else is a
+* path that must resolve inside the session cwd.
+*/
+async function uploadPaths(ctx, seen, cwd, values) {
+	const paths = [];
+	for (const value of values) {
+		const id = attachmentIdOf(value);
+		const found = id === void 0 ? void 0 : seen.refs[id];
+		if (found !== void 0) {
+			paths.push(hostPath(ctx, found));
+			continue;
+		}
+		if (typeof value !== "string") throw new BrowserToolError("INVALID_INPUT", "attachment reference is not in this session");
+		paths.push(...await filesInWorkspace(cwd, [value]));
+	}
+	return paths;
 }
-function attr$1(name, value) {
-	return ` ${name}="${escapeAttr(value)}"`;
+function hostPath(ctx, found) {
+	let host;
+	try {
+		host = found.kind === "image" ? ctx.attachments.imageHostPath(found.ref) : ctx.attachments.fileHostPath(found.ref);
+	} catch (error) {
+		throw new BrowserToolError("INVALID_INPUT", error instanceof Error ? error.message : String(error));
+	}
+	if (host === void 0) throw new BrowserToolError("INVALID_INPUT", "attachment has no host path");
+	return host;
 }
-function formatSeconds(seconds) {
-	const rounded = Math.round(seconds * 10) / 10;
-	return Number.isInteger(rounded) ? String(rounded) : rounded.toFixed(1);
+function attachmentIdOf(value) {
+	if (typeof value === "string") return value;
+	if (value !== null && typeof value === "object") {
+		const id = value.attachmentId;
+		if (typeof id === "string") return id;
+	}
+}
+function visit(value, depth, found) {
+	if (depth > 12 || value === null || typeof value !== "object") return;
+	if (Array.isArray(value)) {
+		for (const item of value) visit(item, depth + 1, found);
+		return;
+	}
+	const row = value;
+	if (typeof row.attachmentId === "string" && typeof row.bytes === "number") {
+		const kind = typeof row.width === "number" && typeof row.mediaType === "string" ? "image" : "file";
+		if (kind === "image" || typeof row.name === "string") found[row.attachmentId] = {
+			kind,
+			ref: row
+		};
+	}
+	for (const item of Object.values(row)) visit(item, depth + 1, found);
 }
 //#endregion
 //#region lib/types/tools/delivery.js
@@ -1027,18 +793,18 @@ function urlsIn(text) {
 	return [...new Set(found)];
 }
 function fromTool(event) {
-	const data = record$2(event.data);
-	const message = record$2(data.message);
+	const data = record$3(event.data);
+	const message = record$3(data.message);
 	const callId = readString(message.toolCallId);
-	const text = textOf$2(message.content);
+	const text = textOf$3(message.content);
 	if (message.isError === true) return void 0;
-	const meta = record$2(data.meta);
+	const meta = record$3(data.meta);
 	if (meta.by !== "mh-browser") return void 0;
 	const pages = meta.pages;
 	if (!Array.isArray(pages)) return void 0;
 	const deliveries = [];
 	for (const page of pages) {
-		const row = record$2(page);
+		const row = record$3(page);
 		if (row.representation === "header" || readString(row.reason) !== void 0) continue;
 		const url = readString(row.url);
 		if (url === void 0) continue;
@@ -1064,21 +830,21 @@ function fromTool(event) {
 	};
 }
 function fromPresence(event) {
-	const message = record$2(event.data);
-	const source = record$2(message.source);
+	const message = record$3(event.data);
+	const source = record$3(message.source);
 	if (source.kind !== "mh-browser") return void 0;
-	const entries = record$2(source.presence).entries;
+	const entries = record$3(source.presence).entries;
 	if (!Array.isArray(entries)) return void 0;
 	const deliveries = [];
 	for (const entry of entries) {
-		const row = record$2(entry);
+		const row = record$3(entry);
 		if (row.op === "removed" || row.op === "absent") continue;
 		const url = readString(row.url);
 		if (url === void 0) continue;
 		const digest = readString(row.digest);
 		const version = readString(row.version);
 		const id = readString(row.id);
-		const body = digest === void 0 ? void 0 : shownBody(textOf$2(message.content), url);
+		const body = digest === void 0 ? void 0 : shownBody(textOf$3(message.content), url);
 		deliveries.push({
 			url,
 			seq: event.seq,
@@ -1091,7 +857,7 @@ function fromPresence(event) {
 	}
 	return {
 		deliveries,
-		text: textOf$2(message.content)
+		text: textOf$3(message.content)
 	};
 }
 const OMITTED_BODY = /* @__PURE__ */ new Set([
@@ -1136,11 +902,11 @@ function attrOf(header, name) {
 	if (value === void 0 || value === "") return void 0;
 	return value.replace(/&quot;/g, "\"").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&#10;/g, "\n").replace(/&#13;/g, "\r").replace(/&#9;/g, "	").replace(/&amp;/g, "&");
 }
-function textOf$2(content) {
+function textOf$3(content) {
 	if (!Array.isArray(content)) return "";
 	const parts = [];
 	for (const block of content) {
-		const text = readString(record$2(block).text);
+		const text = readString(record$3(block).text);
 		if (text !== void 0) parts.push(text);
 	}
 	return parts.join("\n");
@@ -1157,7 +923,7 @@ function sameUrl(left, right) {
 		return false;
 	}
 }
-function record$2(value) {
+function record$3(value) {
 	if (value !== null && typeof value === "object" && !Array.isArray(value)) return value;
 	return {};
 }
@@ -1172,9 +938,9 @@ function initTabLog() {
 function applyTabLog(state, event) {
 	const cleared = event.type === "compaction/summary" || event.type === "compaction/prune" || event.surfaceOp === "replace";
 	if (event.type !== "tool/result") return cleared ? withoutSnap(state) : state;
-	const meta = record$1(record$1(event.data).meta);
+	const meta = record$2(record$2(event.data).meta);
 	if (meta.by !== "mh-browser") return cleared ? withoutSnap(state) : state;
-	const named = Array.isArray(meta.pages) ? meta.pages.map((page) => record$1(page).tab).filter(isTabId) : [];
+	const named = Array.isArray(meta.pages) ? meta.pages.map((page) => record$2(page).tab).filter(isTabId) : [];
 	const closed = Array.isArray(meta.closed) ? meta.closed.filter((note) => typeof note === "string").map(tabOfNote) : [];
 	const next = new Set(state.open);
 	for (const tab of named) next.add(tab);
@@ -1225,11 +991,11 @@ function withoutSnap(state) {
 	return rest;
 }
 function snapOf(value) {
-	const snap = record$1(value);
+	const snap = record$2(value);
 	if (!Array.isArray(snap.tabs)) return void 0;
 	return {
 		tabs: snap.tabs.flatMap((item) => {
-			const row = record$1(item);
+			const row = record$2(item);
 			if (typeof row.id !== "string" || typeof row.url !== "string") return [];
 			return [{
 				id: row.id,
@@ -1242,71 +1008,10 @@ function snapOf(value) {
 		closed: Array.isArray(snap.closed) ? snap.closed.filter((note) => typeof note === "string") : []
 	};
 }
-function record$1(value) {
+function record$2(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
 //#endregion
-//#region lib/types/projections.js
-/** Host-only folds over the session log; every read of what the log says goes through these. */
-function registerProjections(ctx) {
-	ctx.sessionProjections.register({
-		key: "mhBrowserDeliveries",
-		stateVersion: 2,
-		stateSchema: plainObject(["deliveries", "tokens"]),
-		init: initDeliveries,
-		apply: (state, event) => applyDelivery(state, {
-			seq: event.seq,
-			type: event.type,
-			data: event.data,
-			..."surfaceOp" in event && event.surfaceOp !== void 0 ? { surfaceOp: event.surfaceOp } : {}
-		})
-	});
-	ctx.sessionProjections.register({
-		key: "mhBrowserPresence",
-		stateVersion: 1,
-		stateSchema: plainObject([
-			"committed",
-			"inbox",
-			"discarded",
-			"shown",
-			"ops"
-		]),
-		init: initPresenceLog,
-		apply: (state, event) => applyPresenceLog(state, event)
-	});
-	ctx.sessionProjections.register({
-		key: "mhBrowserAttachments",
-		stateVersion: 1,
-		stateSchema: plainObject(["refs"]),
-		init: initAttachments,
-		apply: (state, event) => applyAttachments(state, event)
-	});
-	ctx.sessionProjections.register({
-		key: "mhBrowserTabs",
-		stateVersion: 2,
-		stateSchema: plainObject(["open"]),
-		init: initTabLog,
-		apply: (state, event) => applyTabLog(state, event)
-	});
-}
-/** Fails closed when the registry or a unit is not active. */
-function logReader(ctx) {
-	const read = (session, key) => {
-		const state = ctx.sessionProjections.stateOf(session, key);
-		if (state === void 0) throw new Error(`mh-browser cannot read ${key}: its session projection is not registered`);
-		return state;
-	};
-	return {
-		deliveries: (session) => read(session, "mhBrowserDeliveries"),
-		presence: (session) => read(session, "mhBrowserPresence"),
-		attachments: (session) => read(session, "mhBrowserAttachments"),
-		tabs: (session) => read(session, "mhBrowserTabs")
-	};
-}
-function plainObject(keys) {
-	return z$1.custom((value) => value !== null && typeof value === "object" && keys.every((key) => key in value));
-}
-//#endregion
 //#region lib/types/tools/page-ops.js
 const IMAGE_VALUE = {
 	type: "object",
@@ -1805,8 +1510,7 @@ const OPS = [
 		})
 	}
 ];
-function pageOperationTools(ctx) {
-	const reader = logReader(ctx);
+function pageOperationTools(ctx, reader) {
 	return OPS.map((spec) => defineOperation(ctx, reader, spec));
 }
 function defineOperation(ctx, reader, spec) {
@@ -1877,9 +1581,9 @@ function defineOperation(ctx, reader, spec) {
 }
 /** Probe the path before the action, then write the result the model would have been shown. */
 async function saveResult(target, filename, view) {
-	return writeInside(target, filename, view.shot?.bytes ?? textOf$1(view));
+	return writeInside(target, filename, view.shot?.bytes ?? textOf$2(view));
 }
-function textOf$1(view) {
+function textOf$2(view) {
 	if (view.summary !== void 0 && view.summary !== "") return view.detail === void 0 || view.detail === "" ? view.summary : `${view.summary}\n${view.detail}`;
 	return view.representation.text;
 }
@@ -1892,72 +1596,306 @@ function tabOf(reader, session, tab) {
 function string(value) {
 	return typeof value === "string" ? value : "";
 }
-function stringList$1(value) {
-	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+function stringList$1(value) {
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function optionalString(args, key) {
+	return typeof args[key] === "string" ? { element: args[key] } : {};
+}
+function optional(key, value) {
+	return typeof value === "string" ? { [key]: value } : {};
+}
+function fieldsOf(value) {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((item) => {
+		if (item === null || typeof item !== "object") return [];
+		const row = item;
+		const type = row.type;
+		if (type !== "textbox" && type !== "checkbox" && type !== "radio" && type !== "combobox" && type !== "slider") return [];
+		return [{
+			target: string(row.target),
+			...typeof row.element === "string" ? { element: row.element } : {},
+			name: string(row.name),
+			type,
+			value: string(row.value)
+		}];
+	});
+}
+function callIdOf(exec) {
+	return String(exec.callId);
+}
+function imageValue(ref) {
+	return {
+		attachmentId: ref.attachmentId,
+		mediaType: ref.mediaType,
+		bytes: ref.bytes,
+		width: ref.width,
+		height: ref.height,
+		...ref.name === void 0 ? {} : { name: ref.name },
+		...ref.originalDimensions === void 0 ? {} : { originalDimensions: { ...ref.originalDimensions } }
+	};
+}
+function imageRef(value) {
+	return {
+		attachmentId: value.attachmentId,
+		mediaType: value.mediaType,
+		bytes: value.bytes,
+		width: value.width,
+		height: value.height,
+		...value.name === void 0 ? {} : { name: value.name },
+		...value.originalDimensions === void 0 ? {} : { originalDimensions: { ...value.originalDimensions } }
+	};
+}
+async function saveShot(ctx, view) {
+	const shot = view.shot;
+	if (shot === void 0) return void 0;
+	try {
+		return await ctx.attachments.saveImage({
+			data: shot.bytes,
+			mediaType: shot.mediaType,
+			name: `${view.tab ?? "page"}.${shot.mediaType.slice(6)}`
+		});
+	} catch (error) {
+		ctx.logger.warn("saving the screenshot failed: %o", error);
+		return;
+	}
+}
+function isModifier(value) {
+	return value === "Alt" || value === "Control" || value === "ControlOrMeta" || value === "Meta" || value === "Shift";
+}
+//#endregion
+//#region lib/types/presence/record.js
+/** Structured presence record carried on a message source. The model sees the rendered text, not this. */
+const PRESENCE_SOURCES = [
+	"person via sidebar",
+	"cwd reference",
+	"model"
+];
+//#endregion
+//#region lib/types/presence/fold.js
+function initPresenceLog() {
+	return {
+		committed: [],
+		inbox: {
+			"next-step": [],
+			"next-turn": []
+		},
+		discarded: [],
+		visible: false,
+		hidden: false,
+		shown: [],
+		ops: []
+	};
+}
+function applyPresenceLog(state, event) {
+	if (event.type === "compaction/summary") {
+		if (!state.visible && state.shown.length === 0) return state;
+		return {
+			...state,
+			visible: false,
+			hidden: true,
+			shown: []
+		};
+	}
+	if (event.type === "user/message") {
+		const carried = carriedOf(event.data, `history:${String(event.seq)}`);
+		if (carried === void 0) return state;
+		return {
+			...state,
+			committed: applyRecord(state.committed, carried.record, "committed"),
+			inbox: {
+				"next-step": state.inbox["next-step"].map((item) => item?.id === carried.id ? null : item),
+				"next-turn": state.inbox["next-turn"].map((item) => item?.id === carried.id ? null : item)
+			},
+			discarded: [],
+			visible: true,
+			hidden: false,
+			shown: [...state.shown, textDigest(event.data)],
+			ops: []
+		};
+	}
+	if (event.type === "agent/inbox/discarded") {
+		const carried = carriedOf(event.data, `discarded:${String(event.seq)}`);
+		if (carried === void 0) return state;
+		return {
+			...state,
+			discarded: [...state.discarded, carried]
+		};
+	}
+	if (event.type === "agent/inbox/spliced") return applySplice(state, event);
+	if (event.type === "tool/result") return applyReceipts(state, event);
+	return state;
+}
+/** The folded set, with pending reminders and unannounced receipts on top. */
+function presenceSet(state) {
+	let pages = state.committed;
+	for (const carried of [
+		...state.inbox["next-turn"],
+		...state.inbox["next-step"],
+		...state.discarded
+	]) if (carried !== null) pages = applyRecord(pages, carried.record, "pending");
+	const removals = [];
+	for (const op of state.ops) {
+		const index = pages.findIndex((page) => page.url === op.url);
+		if (op.op === "remove") {
+			if (index < 0) continue;
+			pages = pages.toSpliced(index, 1);
+			removals.push(op);
+			continue;
+		}
+		if (index >= 0) continue;
+		pages = [...pages, {
+			url: op.url,
+			source: "model",
+			state: "pending",
+			order: pages.length
+		}];
+	}
+	return {
+		pages,
+		removals
+	};
 }
-function optionalString(args, key) {
-	return typeof args[key] === "string" ? { element: args[key] } : {};
+/** The text of a reminder, as `shown` records it. */
+function textDigest(message) {
+	return createHash("sha256").update(textOf$1(message)).digest("hex");
 }
-function optional(key, value) {
-	return typeof value === "string" ? { [key]: value } : {};
+function applySplice(state, event) {
+	const data = record$1(event.data);
+	const target = data.target === "next-turn" ? "next-turn" : "next-step";
+	const start = typeof data.start === "number" ? data.start : 0;
+	const removedCount = typeof data.removedCount === "number" ? data.removedCount : 0;
+	const slots = (Array.isArray(data.inserted) ? data.inserted : []).map((item, index) => carriedOf(item, `splice:${String(event.seq)}:${String(index)}`));
+	const list = state.inbox[target];
+	const removed = list.slice(start, start + removedCount).filter((item) => item !== null);
+	if (removedCount === 0 && slots.length === 0) return state;
+	const next = [
+		...list.slice(0, start),
+		...slots.map((slot) => slot ?? null),
+		...list.slice(start + removedCount)
+	];
+	const announced = slots.some((slot) => slot !== void 0);
+	return {
+		...state,
+		inbox: {
+			...state.inbox,
+			[target]: next
+		},
+		discarded: data.outcome === "canceled" ? [...state.discarded, ...removed] : state.discarded,
+		ops: announced ? [] : state.ops
+	};
 }
-function fieldsOf(value) {
-	if (!Array.isArray(value)) return [];
-	return value.flatMap((item) => {
-		if (item === null || typeof item !== "object") return [];
-		const row = item;
-		const type = row.type;
-		if (type !== "textbox" && type !== "checkbox" && type !== "radio" && type !== "combobox" && type !== "slider") return [];
-		return [{
-			target: string(row.target),
-			...typeof row.element === "string" ? { element: row.element } : {},
-			name: string(row.name),
-			type,
-			value: string(row.value)
-		}];
-	});
+function applyReceipts(state, event) {
+	const data = record$1(event.data);
+	if (record$1(data.message).isError === true) return state;
+	const meta = record$1(data.meta);
+	if (meta.by !== "mh-browser" || meta.action !== "presence" || !Array.isArray(meta.receipts)) return state;
+	const ops = [];
+	for (const item of meta.receipts) {
+		const row = record$1(item);
+		if (typeof row.url !== "string" || row.url === "") continue;
+		if (row.receipt === "added (pending)") ops.push({
+			op: "put",
+			url: row.url
+		});
+		if (row.receipt === "removed (pending)") ops.push({
+			op: "remove",
+			url: row.url
+		});
+	}
+	return ops.length === 0 ? state : {
+		...state,
+		ops: [...state.ops, ...ops]
+	};
 }
-function callIdOf(exec) {
-	return String(exec.callId);
+function applyRecord(pages, record, state) {
+	if (record.kind === "baseline") {
+		const next = [];
+		for (const entry of record.entries) {
+			if (entry.op === "removed") continue;
+			next.push(heldFrom(entry, state, next.length));
+		}
+		return next;
+	}
+	const next = pages.map((page) => ({ ...page }));
+	for (const entry of record.entries) {
+		if (entry.op === "removed") {
+			const index = next.findIndex((page) => page.url === entry.url);
+			if (index >= 0) next.splice(index, 1);
+			continue;
+		}
+		const index = next.findIndex((page) => page.url === entry.url);
+		const held = heldFrom(entry, state, index >= 0 ? next[index]?.order ?? index : next.length);
+		if (index >= 0) next[index] = held;
+		else next.push(held);
+	}
+	return next;
 }
-function imageValue(ref) {
+function heldFrom(entry, state, order) {
+	const absent = entry.op === "absent";
 	return {
-		attachmentId: ref.attachmentId,
-		mediaType: ref.mediaType,
-		bytes: ref.bytes,
-		width: ref.width,
-		height: ref.height,
-		...ref.name === void 0 ? {} : { name: ref.name },
-		...ref.originalDimensions === void 0 ? {} : { originalDimensions: { ...ref.originalDimensions } }
+		url: entry.url,
+		source: entry.source,
+		state,
+		order,
+		seen: absent ? { absent: entry.reason ?? "" } : {
+			digest: entry.digest,
+			observedAt: entry.observedAt,
+			...entry.version === void 0 ? {} : { version: entry.version },
+			...entry.id === void 0 ? {} : { id: entry.id }
+		}
 	};
 }
-function imageRef(value) {
+/** A `user/message` event's data is the message itself. */
+function carriedOf(data, fallbackId) {
+	const message = record$1(data);
+	const source = record$1(message.source);
+	if (source.kind !== "mh-browser") return void 0;
+	const presence = record$1(source.presence);
+	const kind = presence.kind;
+	if (kind !== "baseline" && kind !== "delta") return void 0;
+	const entries = Array.isArray(presence.entries) ? presence.entries.flatMap((item) => entryOf$1(item)) : [];
 	return {
-		attachmentId: value.attachmentId,
-		mediaType: value.mediaType,
-		bytes: value.bytes,
-		width: value.width,
-		height: value.height,
-		...value.name === void 0 ? {} : { name: value.name },
-		...value.originalDimensions === void 0 ? {} : { originalDimensions: { ...value.originalDimensions } }
+		id: typeof message.id === "string" && message.id !== "" ? message.id : fallbackId,
+		record: {
+			kind,
+			entries,
+			...presence.replaces === true ? { replaces: true } : {}
+		}
 	};
 }
-async function saveShot(ctx, view) {
-	const shot = view.shot;
-	if (shot === void 0) return void 0;
-	try {
-		return await ctx.attachments.saveImage({
-			data: shot.bytes,
-			mediaType: shot.mediaType,
-			name: `${view.tab ?? "page"}.${shot.mediaType.slice(6)}`
-		});
-	} catch (error) {
-		ctx.logger.warn("saving the screenshot failed: %o", error);
-		return;
-	}
+function entryOf$1(value) {
+	const row = record$1(value);
+	const op = row.op;
+	if (op !== "present" && op !== "added" && op !== "changed" && op !== "absent" && op !== "removed") return [];
+	const url = typeof row.url === "string" ? row.url : "";
+	if (url === "") return [];
+	const source = isSource(row.source) ? row.source : "model";
+	const version = typeof row.version === "string" ? row.version : void 0;
+	const id = typeof row.id === "string" && row.id !== "" ? row.id : void 0;
+	const reason = typeof row.reason === "string" ? row.reason : void 0;
+	return [{
+		op,
+		url,
+		source,
+		observedAt: typeof row.observedAt === "string" ? row.observedAt : "",
+		digest: typeof row.digest === "string" ? row.digest : "",
+		...version === void 0 ? {} : { version },
+		...id === void 0 ? {} : { id },
+		...reason === void 0 ? {} : { reason }
+	}];
 }
-function isModifier(value) {
-	return value === "Alt" || value === "Control" || value === "ControlOrMeta" || value === "Meta" || value === "Shift";
+function textOf$1(value) {
+	const content = record$1(value).content;
+	if (!Array.isArray(content)) return "";
+	return content.map((block) => record$1(block).text).filter((text) => typeof text === "string").join("\n");
+}
+function isSource(value) {
+	return typeof value === "string" && PRESENCE_SOURCES.includes(value);
+}
+function record$1(value) {
+	if (value !== null && typeof value === "object" && !Array.isArray(value)) return value;
+	return {};
 }
 //#endregion
 //#region lib/types/presence/notice.js
@@ -1983,8 +1921,7 @@ const BROWSER_TOOLS = /* @__PURE__ */ new Set([
 * the reminder after the claimed input. `await next()` runs first, so a
 * caller that puts pages and then returns `next()` is folded into this step.
 */
-function registerPresence(ctx) {
-	const reader = logReader(ctx);
+function registerPresence(ctx, reader) {
 	const tails = /* @__PURE__ */ new WeakMap();
 	const stepTouches = /* @__PURE__ */ new WeakMap();
 	const executionTouches = /* @__PURE__ */ new Map();
@@ -2012,8 +1949,7 @@ function registerPresence(ctx) {
 		});
 	};
 	const stepIsOpen = (session) => {
-		const boundary = ctx.sessionProjections.stateOf(session, "turnBoundary");
-		if (boundary === void 0) throw new Error("mh-browser requires the turnBoundary session projection");
+		const boundary = ctx.agents.turnBoundaryOf(session);
 		return boundary.openTurnStartSeq !== null && boundary.lastStepBoundary?.kind === "start" && boundary.lastStepBoundary.seq > boundary.openTurnStartSeq;
 	};
 	const project = (touch) => {
@@ -2239,6 +2175,58 @@ function canonical$1(url) {
 	}
 }
 //#endregion
+//#region lib/types/projections.js
+/** Host-only folds over the session log; every read of what the log says goes through these. */
+async function registerProjections(ctx) {
+	return readerFrom(await ctx.sessionProjections.register({
+		key: "mhBrowserDeliveries",
+		stateVersion: 2,
+		stateSchema: plainObject(["deliveries", "tokens"]),
+		init: initDeliveries,
+		apply: (state, event) => applyDelivery(state, {
+			seq: event.seq,
+			type: event.type,
+			data: event.data,
+			..."surfaceOp" in event && event.surfaceOp !== void 0 ? { surfaceOp: event.surfaceOp } : {}
+		})
+	}), await ctx.sessionProjections.register({
+		key: "mhBrowserPresence",
+		stateVersion: 1,
+		stateSchema: plainObject([
+			"committed",
+			"inbox",
+			"discarded",
+			"shown",
+			"ops"
+		]),
+		init: initPresenceLog,
+		apply: (state, event) => applyPresenceLog(state, event)
+	}), await ctx.sessionProjections.register({
+		key: "mhBrowserAttachments",
+		stateVersion: 1,
+		stateSchema: plainObject(["refs"]),
+		init: initAttachments,
+		apply: (state, event) => applyAttachments(state, event)
+	}), await ctx.sessionProjections.register({
+		key: "mhBrowserTabs",
+		stateVersion: 2,
+		stateSchema: plainObject(["open"]),
+		init: initTabLog,
+		apply: (state, event) => applyTabLog(state, event)
+	}));
+}
+function readerFrom(deliveries, presence, attachments, tabs) {
+	return {
+		deliveries: (session) => deliveries.stateOf(session),
+		presence: (session) => presence.stateOf(session),
+		attachments: (session) => attachments.stateOf(session),
+		tabs: (session) => tabs.stateOf(session)
+	};
+}
+function plainObject(keys) {
+	return z$1.custom((value) => value !== null && typeof value === "object" && keys.every((key) => key in value));
+}
+//#endregion
 //#region lib/types/presence/book.js
 /** In-memory presence set for one process. The log is the source of a set that outlives the process. */
 var PresenceBook = class {
@@ -2952,6 +2940,15 @@ function missingExecutable(error) {
 	return /ENOENT|doesn.t exist|Executable doesn't exist|not found/i.test(message);
 }
 /**
+* Playwright appends `--no-sandbox` unless this is true, and branded Chrome
+* then warns that stability and security will suffer. An installed browser
+* sandboxes on every platform. Playwright's own Chromium does too, except on
+* Linux, where that build has no usable sandbox helper and would fail to start.
+*/
+function chromiumSandboxEnabled(browser, platform = process.platform) {
+	return platform !== "linux" || browser !== "chromium";
+}
+/**
 * One persistent context for the whole process. `chromium` omits `channel`
 * so Playwright uses its own browser; the others use a local install.
 * A missing browser is reported and not downloaded.
@@ -2962,6 +2959,7 @@ async function launchBrowser(options) {
 		return await chromium.launchPersistentContext(options.profileDir, {
 			headless: options.headless,
 			acceptDownloads: true,
+			chromiumSandbox: chromiumSandboxEnabled(options.browser),
 			...options.headless ? {} : {
 				ignoreDefaultArgs: ["--disable-extensions"],
 				args: ["--enable-unsafe-extension-debugging", "--keep-alive-for-test"]
@@ -6589,8 +6587,7 @@ function stopped(signal) {
 //#region lib/types/tools/download.js
 const DOWNLOAD = ["Download one file into the session workspace's downloads/ directory, then read it with bash or fs.", "Use it for a file that requires login: the browser sends the session's cookies, bash does not."].join(" ");
 const URL$2 = "The file address: from a page shown to you, from the principal, or one you composed. An address that cannot be fetched returns download-error and writes nothing. An existing name under downloads/ gets a numeric suffix.";
-function browserDownloadTool(ctx) {
-	const reader = logReader(ctx);
+function browserDownloadTool(ctx, reader) {
 	return defineTool({
 		name: "browser_download",
 		description: DOWNLOAD,
@@ -6667,13 +6664,12 @@ function browserDownloadTool(ctx) {
 const HANDOVER = [
 	"Hand the browser to the person and wait until they hand it back.",
 	"The person can take over a tab at any time; that stops the action in progress on that tab, and a tab they have touched stays with them until they hand it back. Other tabs keep working.",
-	"Call it instead of filling or submitting a login form, a Memory login or consent form, or any form that issues credentials, and whenever only the person can continue."
+	"Call it instead of filling or submitting a login form, a Mind Harness login or consent form, or any form that issues credentials, and whenever only the person can continue."
 ].join(" ");
 const REASON = "The sentence the person sees on the handover card, unchanged.";
 const TAB = "Tab id of the human page to show the person, copied from a page element's tab attribute. Omit it to hand over without naming a tab; that does not pick the latest result. A page with an Agent View has no tab until you open it with snapshot.";
 const ABORT = Symbol("abort");
-function browserHandoverTool(ctx) {
-	const reader = logReader(ctx);
+function browserHandoverTool(ctx, reader) {
 	return defineTool({
 		name: "browser_handover",
 		description: HANDOVER,
@@ -6809,8 +6805,7 @@ const PAGE = "The url attribute of a page element in a tool result or a presence
 const NAME = "Action name copied from that page's Agent View actions.";
 const ITEM = "Item id copied from an item block, as a string. Required when the action's scope is item; omit it for a resource action.";
 const INPUT = "Only fields declared by that action's inputSchema; omit it when the action declares none. A field with contentEncoding binary takes a path inside the session cwd or an attachment reference.";
-function browserInvokeTool(ctx) {
-	const reader = logReader(ctx);
+function browserInvokeTool(ctx, reader) {
 	return defineTool({
 		name: "browser_invoke",
 		description: INVOKE,
@@ -6929,8 +6924,7 @@ const PAGES = "The pages to read, 1 to 8, each returned in order as its own elem
 const URL$1 = "The address to read: from a page shown to you, from the principal, or one you composed; opening a composed address is how it is checked before you use it elsewhere.";
 const WAIT = "Optional wait after the document loads for text to appear or disappear, or for time seconds; at least one must be set. If not met, the page is still returned and waited says so.";
 const SNAPSHOT = "Ask for the human page: open a tab and return its snapshot, for page operations and handover. A page without an Agent View already does.";
-function browserOpenTool(ctx) {
-	const reader = logReader(ctx);
+function browserOpenTool(ctx, reader) {
 	return defineTool({
 		name: "browser_open",
 		description: OPEN,
@@ -7054,8 +7048,7 @@ const PRESENCE = [
 ].join(" ");
 const PUT = "Addresses to keep: from a page shown to you, a presence reminder, or the principal; at most 8. A page that cannot be read shows as absent in the next presence reminder. At least one of put and remove is required.";
 const REMOVE = "Addresses to stop keeping, copied from a presence reminder; at most 8.";
-function browserPresenceTool(ctx) {
-	const reader = logReader(ctx);
+function browserPresenceTool(ctx, reader) {
 	return defineTool({
 		name: "browser_presence",
 		description: PRESENCE,
@@ -7132,14 +7125,14 @@ function line(receipt) {
 }
 //#endregion
 //#region lib/types/tools/register.js
-function registerBrowserTools(ctx) {
+function registerBrowserTools(ctx, reader) {
 	followSessionTitles(ctx);
-	ctx.tools.register(browserOpenTool(ctx));
-	for (const tool of pageOperationTools(ctx)) ctx.tools.register(tool);
-	ctx.tools.register(browserInvokeTool(ctx));
-	ctx.tools.register(browserDownloadTool(ctx));
-	ctx.tools.register(browserPresenceTool(ctx));
-	ctx.tools.register(browserHandoverTool(ctx));
+	ctx.tools.register(browserOpenTool(ctx, reader));
+	for (const tool of pageOperationTools(ctx, reader)) ctx.tools.register(tool);
+	ctx.tools.register(browserInvokeTool(ctx, reader));
+	ctx.tools.register(browserDownloadTool(ctx, reader));
+	ctx.tools.register(browserPresenceTool(ctx, reader));
+	ctx.tools.register(browserHandoverTool(ctx, reader));
 }
 //#endregion
 //#region lib/types/index.js
@@ -7148,10 +7141,11 @@ const inject = [
 	"tools",
 	"userQuestions",
 	"attachments",
-	"sessionProjections"
+	"sessionProjections",
+	"agents"
 ];
 const Config = browserConfig;
-function apply(ctx, config) {
+async function apply(ctx, config) {
 	ctx.plugin({
 		name: "mh-browser-slot",
 		inject: ["browserUse", "mhBrowser"],
@@ -7159,14 +7153,14 @@ function apply(ctx, config) {
 			inner.browserUse.register("mh-browser");
 		}
 	});
-	ctx.plugin(MhBrowserService, config);
-	ctx.plugin({
+	await ctx.plugin(MhBrowserService, config);
+	await ctx.plugin({
 		name: "mh-browser-runtime",
 		inject: ["mhBrowser", ...inject],
-		apply(inner) {
-			registerProjections(inner);
-			registerBrowserTools(inner);
-			registerPresence(inner);
+		async apply(inner) {
+			const reader = await registerProjections(inner);
+			registerBrowserTools(inner, reader);
+			registerPresence(inner, reader);
 		}
 	});
 }