zigmini 1.0.0-beta.2 → 1.1.0-beta.1

package/host/omo-bridge/agent-aside-tool.ts

@@ -0,0 +1,119 @@
+import { existsSync } from "node:fs";
+import type { AsidePermission } from "../../src/agent/aside-targets.ts";
+import type { SessionAsideTarget } from "../../src/agent/aside-target-routes.ts";
+import { ASIDE_OPERATIONS } from "../../src/agent/tool-catalog.ts";
+import { agentToolOperationId } from "../../src/agent/tool-delivery.ts";
+import { canonicalJson } from "../../src/agent/tool-permissions.ts";
+
+// 294 D1/D2: the session-side pieces agent-control wires for the zgw_aside tool and for calls the engine authority held.
+
+export const ASIDE_TOOL = "zgw_aside";
+
+/** C7 input: a closed union checked again by parseAsideRequest. No code, selector, account or host option. */
+export const ASIDE_PARAMETERS = {
+	type: "object", additionalProperties: false, required: ["operation"],
+	properties: {
+		operation: { type: "string", enum: Object.keys(ASIDE_OPERATIONS) },
+		targetHandle: { type: "string", minLength: 1, maxLength: 2048 },
+		url: { type: "string", minLength: 1, maxLength: 2048 },
+		snapshotRevision: { type: "string", minLength: 1, maxLength: 2048 },
+		ref: { type: "string", minLength: 1, maxLength: 2048 },
+		text: { type: "string", minLength: 1, maxLength: 4000 },
+	},
+} as const;
+
+export const ASIDE_DESCRIPTION = "Use the Aside browser through fixed operations. open_owned {url} opens a new work tab and returns its targetHandle; " +
+	"read/screenshot/close_owned {targetHandle}; navigate_owned {targetHandle,url}; click {targetHandle,snapshotRevision,ref}; " +
+	"fill {targetHandle,snapshotRevision,ref,text}. Refs and snapshotRevision come from the latest read of that tab.";
+
+const CONTROL = ["open_owned", "navigate", "click", "fill", "close"];
+
+/** The adapter's permission class against the catalog operations the current grant names. */
+export function asidePermits(operations: readonly string[], permission: AsidePermission): boolean {
+	if (permission === "browser.aside.read") return operations.includes("read") || operations.includes("view");
+	return CONTROL.some((operation) => operations.includes(operation));
+}
+
+/** The zgw_aside operations a policy read (/internal/agent-tools/policy) grants; anything malformed grants nothing. */
+export function asideGrantedOperations(policy: unknown): string[] {
+	const operations = (policy as { operations?: unknown } | null)?.operations;
+	const listed = operations !== null && typeof operations === "object" ? (operations as Record<string, unknown>)[ASIDE_TOOL] : undefined;
+	return Array.isArray(listed) ? listed.filter((operation): operation is string => typeof operation === "string") : [];
+}
+
+/**
+ * C1/C7: what the session does with one zgw_aside call. An operation the current grant names runs; one it does not name is
+ * held for a new owner card (the engine allows zgw_aside by name, so the session holds the rest itself); a blocked policy
+ * (missing: "deny") or an unknown operation is refused.
+ */
+export function asideCallDecision(policy: unknown, operation: unknown): "run" | "hold" | "refuse" {
+	const needed = typeof operation === "string" && Object.hasOwn(ASIDE_OPERATIONS, operation) ? ASIDE_OPERATIONS[operation]! : null;
+	if (needed === null) return "refuse";
+	if (asideGrantedOperations(policy).includes(needed)) return "run";
+	return (policy as { missing?: unknown } | null)?.missing === "hold" ? "hold" : "refuse";
+}
+
+/**
+ * The card scope of a held call on a tab this session knows: an owned work tab stays the session's own target (the gateway
+ * never carries it); a borrowed tab the owner designated keeps its gateway handle. Unknown or no handle: no scope.
+ */
+export function heldAsideScope(target: { readonly handle: string; readonly kind: "borrowed" | "owned"; readonly origin: string } | null): Record<string, string> | null {
+	if (!target) return null;
+	return { kind: target.kind === "owned" ? "owned_target" : "browser_target", targetHandle: target.handle, targetLabel: target.origin };
+}
+
+/**
+ * `aside account status` marks the active account with "*". The host confirms an account only when exactly one line is
+ * marked and signed in; otherwise it cannot tell and the adapter refuses (target_identity_unclear).
+ */
+export function parseAsideAccount(stdout: string): string | null {
+	const marked = stdout.split("\n").map((line) => /^\*\s+(u\d+)\s.*\bsigned in\b/.exec(line)?.[1]).filter((id): id is string => id !== undefined);
+	return marked.length === 1 ? marked[0]! : null;
+}
+
+export async function asideAccount(bin: string, exists: (path: string) => boolean = existsSync): Promise<string | null> {
+	if (!exists(bin)) return null;
+	const child = Bun.spawn([bin, "account", "status"], { stdin: "ignore", stdout: "pipe", stderr: "ignore", timeout: 10_000 });
+	const [stdout, code] = await Promise.all([new Response(child.stdout).text(), child.exited]);
+	return code === 0 ? parseAsideAccount(stdout) : null;
+}
+
+const text = (value: unknown): value is string => typeof value === "string" && value !== "";
+const seq = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value);
+
+/**
+ * D4: the tab the gateway carries to this session for one granted call (`zgw.aside_target`), keyed by the call's stored
+ * args. `target: null` clears the key. Only a well-formed handle of this session's own agent is accepted.
+ */
+export function carriedAsideTarget(data: unknown, agentId: string): { key: string; target: SessionAsideTarget | null } {
+	const value = data as { args?: unknown; target?: unknown } | null;
+	if (!value || typeof value !== "object" || !("args" in value)) throw new Error("aside_target_invalid");
+	const key = canonicalJson(value.args);
+	if (value.target === null) return { key, target: null };
+	const t = (value.target ?? {}) as Record<string, unknown>;
+	if (!text(t.handle) || !t.handle.startsWith("ash_") || (t.kind !== "borrowed" && t.kind !== "owned") || !text(t.host) || !text(t.account) ||
+		!text(t.targetId) || !text(t.origin) || !text(t.agentId) || !seq(t.incarnation) || !(t.selectionSeq === null || seq(t.selectionSeq))) throw new Error("aside_target_invalid");
+	if (t.agentId !== agentId) throw new Error("aside_target_agent_mismatch");
+	return { key, target: { handle: t.handle, kind: t.kind, host: t.host, account: t.account, targetId: t.targetId, origin: t.origin,
+		agentId: t.agentId, incarnation: t.incarnation, selectionSeq: t.selectionSeq } };
+}
+
+/** The stored call with the owner-bound handle; the model's own handle, if any, never overrides the owner's choice. */
+export function withCarriedTarget(params: Record<string, unknown>, target: SessionAsideTarget): Record<string, unknown> {
+	return { ...params, targetHandle: target.handle };
+}
+
+/**
+ * The engine authority ended a call with one pending result: `{"state":"permission_pending","requestId","operationId"}`.
+ * Only a result whose operation id is this call's own direct operation counts; anything else is not a held call.
+ */
+export function heldOperation(event: { readonly toolCallId: string; readonly isError: boolean; readonly result: unknown }): { operationId: string; requestId: string } | null {
+	if (!event.isError) return null;
+	const content = (event.result as { content?: unknown } | null)?.content;
+	const text = Array.isArray(content) && content.length === 1 && (content[0] as { type?: unknown })?.type === "text" ? (content[0] as { text?: unknown }).text : undefined;
+	let parsed: unknown;
+	try { parsed = JSON.parse(String(text)); } catch { return null; }
+	const value = parsed as { state?: unknown; requestId?: unknown; operationId?: unknown } | null;
+	if (value?.state !== "permission_pending" || typeof value.requestId !== "string" || value.operationId !== agentToolOperationId(event.toolCallId)) return null;
+	return { operationId: value.operationId, requestId: value.requestId };
+}

package/host/omo-bridge/agent-aside.ts

@@ -0,0 +1,522 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import {
+	ActionTickets, type AsidePermission, type AsideRefusal, type AsideRequest, type AsideTarget, AsideTargetRegistry, actionDigest, checkObservation,
+	classifyRef, isProtectedUrl, originOf, parseAsideRequest, permissionFor, snapshotRevision,
+} from "../../src/agent/aside-targets.ts";
+
+// 294 C7: host adapter for the zgw_aside tool. It runs the official `aside repl` with argv (no shell) and the
+// absolute ~/.local/bin/aside path, because the launchd PATH does not contain that folder. Each script is a fixed
+// template plus one JSON literal of values; the model never supplies code, selectors, account or host options.
+// The CLI closes the tabs a REPL process opened when that process exits, and closeTab() from another process is a
+// silent no-op, so the adapter keeps one persistent stdin-driven `aside repl --account <id>` session (294 item 15 D5).
+
+export const RESULT_PREFIX = "ZGW_ASIDE_RESULT ";
+/** Printed by the fixed session wrapper after every script, with the script's sequence number. */
+export const END_PREFIX = "ZGW_ASIDE_END ";
+const TEXT_LIMIT = 20_000;
+const IMAGE_LIMIT = 4_000_000;
+/** Per operation; below the CLI's own 120 s REPL call limit. */
+export const OP_TIMEOUT_MS = 90_000;
+const SHUTDOWN_MS = 10_000;
+
+export interface AsideRun {
+	readonly code: number;
+	readonly stdout: string;
+}
+export type AsideRunner = (bin: string, argv: readonly string[]) => Promise<AsideRun>;
+
+export function asideBin(home: string = homedir()): string {
+	return join(home, ".local/bin/aside");
+}
+
+/** One-shot runner (one process per script). It cannot own tabs; the adapter uses it only when injected as `run`. */
+export const spawnAside: AsideRunner = async (bin, argv) => {
+	const child = Bun.spawn([bin, ...argv], { stdout: "pipe", stderr: "ignore", stdin: "ignore" });
+	const stdout = await new Response(child.stdout).text();
+	return { code: await child.exited, stdout };
+};
+
+/** The parts of a long-lived `aside repl` process the session uses. */
+export interface AsideProcess {
+	readonly stdout: ReadableStream<Uint8Array>;
+	readonly exited: Promise<number>;
+	write(text: string): void;
+	end(): void;
+	kill(): void;
+}
+export type AsideSpawner = (bin: string, argv: readonly string[]) => AsideProcess;
+
+export const spawnAsideProcess: AsideSpawner = (bin, argv) => {
+	const child = Bun.spawn([bin, ...argv], { stdin: "pipe", stdout: "pipe", stderr: "ignore" });
+	return {
+		stdout: child.stdout, exited: child.exited,
+		write: (text) => { child.stdin.write(text); void child.stdin.flush(); },
+		end: () => { void child.stdin.end(); },
+		kill: () => { child.kill(); },
+	};
+};
+
+/**
+ * The REPL evaluates one input line at a time and keeps top-level bindings, so each script travels as one fixed line
+ * that runs its base64 text as a fresh async function body and always prints the end marker with its sequence number.
+ */
+export function sessionLine(script: string, seq: number): string {
+	const code = `try {\n${script}\n} catch (error) { console.log("ZGW_ASIDE_ERROR " + String(error?.message ?? error).slice(0, 300)); } finally { console.log(${JSON.stringify(END_PREFIX)} + ${seq}); }`;
+	return `await (new (async function(){}.constructor)(Buffer.from(${JSON.stringify(Buffer.from(code, "utf8").toString("base64"))}, "base64").toString("utf8")))()\n`;
+}
+
+const ANSI = /\u001b\[[0-9;]*m/g;
+
+/** One persistent CLI process. Scripts run one at a time; each waits at most `ms` after it is written. */
+class AsideSession {
+	/** Owned tabs this process opened, by handle: only this process can close them. */
+	readonly owned = new Map<string, AsideTarget>();
+	readonly exited: Promise<void>;
+	closed = false;
+	private buffer = "";
+	private seq = 0;
+	private queue: Promise<unknown> = Promise.resolve();
+	private wake: (() => void) | null = null;
+
+	constructor(readonly account: string, private readonly proc: AsideProcess) {
+		this.exited = proc.exited.then(() => this.markClosed(), () => this.markClosed());
+		void this.pump();
+	}
+
+	private markClosed(): void {
+		this.closed = true;
+		this.wake?.();
+	}
+
+	private async pump(): Promise<void> {
+		const reader = this.proc.stdout.getReader();
+		const decoder = new TextDecoder();
+		try {
+			for (;;) {
+				const { value, done } = await reader.read();
+				if (done) break;
+				this.buffer += decoder.decode(value, { stream: true });
+				this.wake?.();
+			}
+		} catch {
+			// A broken stdout pipe ends the session the same way as a closed one: the waiting script fails below.
+		}
+		// Without stdout the process is unusable; stop it so its exit marks the owned tabs lost.
+		this.proc.kill();
+		this.markClosed();
+	}
+
+	run(script: string, ms: number): Promise<AsideRun> {
+		const next = this.queue.then(() => this.send(script, ms));
+		this.queue = next;
+		return next;
+	}
+
+	private async send(script: string, ms: number): Promise<AsideRun> {
+		if (this.closed) return { code: -1, stdout: "" };
+		const marker = `${END_PREFIX}${++this.seq}`;
+		try {
+			this.proc.write(sessionLine(script, this.seq));
+		} catch {
+			this.proc.kill();
+			return { code: -1, stdout: "" };
+		}
+		let timedOut = false;
+		const timer = setTimeout(() => { timedOut = true; this.wake?.(); }, ms);
+		try {
+			const out: string[] = [];
+			for (;;) {
+				const newline = this.buffer.indexOf("\n");
+				if (newline >= 0) {
+					const line = this.buffer.slice(0, newline).replace(ANSI, "").trimEnd();
+					this.buffer = this.buffer.slice(newline + 1);
+					if (line.endsWith(marker)) return { code: 0, stdout: out.join("\n") };
+					const at = line.indexOf(RESULT_PREFIX);
+					out.push(at > 0 ? line.slice(at) : line);
+					continue;
+				}
+				if (timedOut || this.closed) {
+					// A script that outlives its limit leaves the REPL in an unknown state: end the process.
+					this.proc.kill();
+					return { code: -1, stdout: "" };
+				}
+				await new Promise<void>((resolve) => { this.wake = resolve; });
+				this.wake = null;
+			}
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+
+	async shutdown(ms: number): Promise<void> {
+		if (!this.closed) {
+			try {
+				this.proc.end();
+			} catch {
+				this.proc.kill();
+			}
+		}
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		const late = await Promise.race([this.exited.then(() => false), new Promise<boolean>((resolve) => { timer = setTimeout(() => resolve(true), ms); })]);
+		clearTimeout(timer);
+		if (late) this.proc.kill();
+	}
+}
+
+const PRELUDE = `
+const SEL = 'a[href],button,input:not([type=hidden]):not([type=password]),textarea,select,[role=button],[role=link],[contenteditable=true]';
+async function observe(id) {
+  const tab = (await listBrowserTabs()).find((t) => t.targetId === id);
+  return tab ? { targetId: tab.targetId, url: String(tab.url) } : { targetId: null, url: "" };
+}
+async function mainDocument(p, limit) {
+  return p.evaluate(({ sel, limit }) => {
+    const els = [...document.querySelectorAll(sel)].filter((e) => e.getClientRects().length > 0).slice(0, 200);
+    const items = els.map((e, i) => ({ ref: "e" + i, tag: e.tagName.toLowerCase(), role: e.getAttribute("role") || "",
+      name: (e.getAttribute("aria-label") || e.innerText || e.getAttribute("placeholder") || "").trim().slice(0, 120) }));
+    const frames = document.querySelectorAll("iframe,frame").length;
+    const text = document.body ? document.body.innerText : "";
+    return { title: document.title, text: text.slice(0, limit), textLength: text.length, items, frames };
+  }, { sel: SEL, limit });
+}
+async function elementAt(p, i) {
+  const at = await p.evaluate(({ sel, i }) => {
+    const all = [...document.querySelectorAll(sel)];
+    const shown = all.filter((e) => e.getClientRects().length > 0)[i];
+    return shown ? all.indexOf(shown) : -1;
+  }, { sel: SEL, i });
+  return at < 0 ? null : p.locator(SEL).nth(at);
+}
+function done(out) { console.log(${JSON.stringify(RESULT_PREFIX)} + JSON.stringify(out)); }
+`;
+
+const BODY = {
+	open_owned: `
+const before = new Set((await listBrowserTabs()).map((t) => t.targetId));
+await openTab(A.url);
+const fresh = (await listBrowserTabs()).filter((t) => !before.has(t.targetId));
+done(fresh.length === 1 ? { opened: { targetId: fresh[0].targetId, url: String(fresh[0].url) } } : { opened: null });`,
+	read: `
+const pre = await observe(A.targetId);
+if (pre.targetId === null) { done({ pre }); } else {
+  const p = await attachBrowserTab(A.targetId);
+  const doc = await mainDocument(p, A.limit);
+  done({ pre, doc, post: await observe(A.targetId) });
+}`,
+	screenshot: `
+const pre = await observe(A.targetId);
+if (pre.targetId === null) { done({ pre }); } else {
+  const p = await attachBrowserTab(A.targetId);
+  const doc = await mainDocument(p, 0);
+  const image = doc.frames > 0 ? null : (await p.screenshot({ type: "png" })).toString("base64");
+  done({ pre, doc, image, post: await observe(A.targetId) });
+}`,
+	navigate_owned: `
+const pre = await observe(A.targetId);
+if (pre.targetId === null) { done({ pre }); } else {
+  const p = await attachBrowserTab(A.targetId);
+  await p.goto(A.url);
+  done({ pre, post: await observe(A.targetId) });
+}`,
+	act: `
+const pre = await observe(A.targetId);
+if (pre.targetId === null || !pre.url.startsWith(A.origin + "/")) { done({ pre }); } else {
+  const p = await attachBrowserTab(A.targetId);
+  const doc = await mainDocument(p, 0);
+  if (JSON.stringify(doc.items) !== JSON.stringify(A.expected)) { done({ pre, stale: true }); } else {
+    const el = await elementAt(p, A.index);
+    if (!el) { done({ pre, stale: true }); } else {
+      if (A.text === null) await el.click(); else await el.fill(A.text);
+      done({ pre, acted: true, post: await observe(A.targetId) });
+    }
+  }
+}`,
+	close_owned: `
+const pre = await observe(A.targetId);
+if (pre.targetId === null) { done({ pre, closed: true }); } else {
+  const p = await attachBrowserTab(A.targetId);
+  await closeTab(p);
+  done({ pre, closed: (await observe(A.targetId)).targetId === null });
+}`,
+} as const;
+
+/** The whole script: a JSON literal of values followed by fixed host code. */
+export function asideScript(body: keyof typeof BODY, values: Record<string, unknown>): string {
+	return `const A = ${JSON.stringify(values)};\n${PRELUDE}${BODY[body]}`;
+}
+
+export interface AsideContext {
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly actionTicket?: string;
+}
+
+export interface AsideDeps {
+	readonly registry: AsideTargetRegistry;
+	readonly tickets: ActionTickets;
+	readonly host: string;
+	readonly gatewayOrigins: readonly string[];
+	/** The account the host confirmed with the CLI right now; null when it cannot tell. */
+	readonly confirmedAccount: () => Promise<string | null>;
+	readonly authorize: (permission: AsidePermission, target: AsideTarget | null) => boolean;
+	/** One process per script (tests and fixtures). Without it the adapter keeps one persistent session. */
+	readonly run?: AsideRunner;
+	readonly spawn?: AsideSpawner;
+	readonly timeoutMs?: number;
+	readonly bin?: string;
+	readonly exists?: (path: string) => boolean;
+}
+
+export type AsideResult =
+	| { readonly ok: true; readonly targetHandle: string; readonly [key: string]: unknown }
+	| { readonly ok: false; readonly refused: AsideRefusal; readonly targetHandle?: string };
+
+interface Item { readonly ref: string; readonly tag: string; readonly role: string; readonly name: string }
+interface Seen { readonly targetId: string | null; readonly url: string }
+
+const refuse = (refused: AsideRefusal, targetHandle?: string): AsideResult => (targetHandle ? { ok: false, refused, targetHandle } : { ok: false, refused });
+
+/** A click/fill checked for its one-shot confirmation (C8): the target and the exact element, or why it cannot run. */
+export type AsidePreparedAction =
+	| { readonly ok: true; readonly target: { readonly handle: string; readonly origin: string; readonly kind: AsideTarget["kind"] }; readonly element: { readonly tag: string; readonly role: string; readonly name: string } }
+	| { readonly ok: false; readonly refused: AsideRefusal; readonly targetHandle?: string };
+
+export class AsideAdapter {
+	private readonly snapshots = new Map<string, { revision: string; items: readonly Item[] }>();
+	private session: AsideSession | null = null;
+	/** Owned handles whose session ended: their tab can no longer be closed by this adapter. */
+	private readonly lost = new Set<string>();
+	private stopped = false;
+
+	constructor(private readonly deps: AsideDeps) {}
+
+	private sessionFor(bin: string, account: string): AsideSession {
+		if (this.stopped) throw new Error("aside_adapter_stopped");
+		const current = this.session;
+		if (current && !current.closed && current.account === account) return current;
+		if (current) {
+			this.sessionEnded(current);
+			void current.shutdown(SHUTDOWN_MS);
+		}
+		const session = new AsideSession(account, (this.deps.spawn ?? spawnAsideProcess)(bin, ["repl", "--account", account]));
+		this.session = session;
+		void session.exited.then(() => this.sessionEnded(session));
+		return session;
+	}
+
+	/** Idempotent: the tabs the ended session owned are marked lost; their next operation answers target_changed. */
+	private sessionEnded(session: AsideSession): void {
+		if (this.session === session) this.session = null;
+		for (const handle of session.owned.keys()) this.lost.add(handle);
+		session.owned.clear();
+	}
+
+	private async exec(target: AsideTarget | { readonly account: string }, body: keyof typeof BODY, values: Record<string, unknown>): Promise<Record<string, unknown> | AsideRefusal> {
+		return (await this.execWith(target, body, values)).out;
+	}
+
+	private async execWith(target: AsideTarget | { readonly account: string }, body: keyof typeof BODY, values: Record<string, unknown>): Promise<{ out: Record<string, unknown> | AsideRefusal; session: AsideSession | null }> {
+		// verify() of a missing observation always suspends and answers target_changed.
+		if ("handle" in target && this.lost.delete(target.handle)) return { out: this.verify(target, undefined) as AsideRefusal, session: null };
+		const bin = this.deps.bin ?? asideBin();
+		if (!(this.deps.exists ?? existsSync)(bin)) return { out: "aside_cli_unavailable", session: null };
+		const script = asideScript(body, values);
+		let result: AsideRun;
+		let session: AsideSession | null = null;
+		try {
+			if (this.deps.run) {
+				result = await this.deps.run(bin, ["repl", "--account", target.account, script]);
+			} else {
+				session = this.sessionFor(bin, target.account);
+				result = await session.run(script, this.deps.timeoutMs ?? OP_TIMEOUT_MS);
+				if (session.closed) this.sessionEnded(session);
+			}
+		} catch {
+			return { out: "aside_failed", session };
+		}
+		if (result.code !== 0) return { out: "aside_failed", session };
+		const line = result.stdout.split("\n").reverse().find((entry) => entry.startsWith(RESULT_PREFIX));
+		if (!line) return { out: "aside_output_invalid", session };
+		try {
+			const parsed: unknown = JSON.parse(line.slice(RESULT_PREFIX.length));
+			return { out: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : "aside_output_invalid", session };
+		} catch {
+			return { out: "aside_output_invalid", session };
+		}
+	}
+
+	private async accountOk(target: AsideTarget): Promise<boolean> {
+		return (await this.deps.confirmedAccount()) === target.account;
+	}
+
+	/** Applies the identity check to one observation; a moved or replaced tab is suspended and needs a new selection. */
+	private verify(target: AsideTarget, seen: unknown): "ok" | AsideRefusal {
+		const s = seen as Seen | undefined;
+		if (!s || typeof s.targetId !== "string") {
+			this.deps.registry.suspend(target);
+			this.snapshots.delete(target.handle);
+			return "target_changed";
+		}
+		const check = checkObservation(target, { targetId: s.targetId, url: s.url, account: target.account });
+		if (check !== "ok") {
+			this.deps.registry.suspend(target);
+			this.snapshots.delete(target.handle);
+		}
+		return check;
+	}
+
+	async invoke(ctx: AsideContext, input: unknown): Promise<AsideResult> {
+		const request = parseAsideRequest(input);
+		if ("refused" in request) return refuse(request.refused);
+		if (request.operation === "open_owned") return this.openOwned(ctx, request.url);
+		const target = this.deps.registry.resolve(request.targetHandle, ctx.agentId, ctx.incarnation);
+		if ("refused" in target) return refuse(target.refused, request.targetHandle);
+		if (!this.deps.authorize(permissionFor(request.operation), target)) return refuse("permission_denied", target.handle);
+		if ((request.operation === "navigate_owned" || request.operation === "close_owned") && target.kind !== "owned") return refuse("borrowed_target", target.handle);
+		if (!await this.accountOk(target)) {
+			this.deps.registry.suspend(target);
+			return refuse("account_changed", target.handle);
+		}
+		switch (request.operation) {
+			case "read": return this.read(target);
+			case "screenshot": return this.screenshot(target);
+			case "navigate_owned": return this.navigate(target, request.url);
+			case "close_owned": return this.close(target, "agent_request");
+			case "click": case "fill": return this.act(ctx, target, request);
+		}
+	}
+
+	/**
+	 * C8: checks a click/fill without running it and describes what it would act on, for the owner's one-shot confirmation.
+	 * The same identity, permission and snapshot checks as the action itself; the snapshot is kept for the confirmed run.
+	 */
+	prepareAction(ctx: AsideContext, input: unknown): AsidePreparedAction {
+		const request = parseAsideRequest(input);
+		if ("refused" in request) return { ok: false, refused: request.refused };
+		if (request.operation !== "click" && request.operation !== "fill") return { ok: false, refused: "invalid_input" };
+		const target = this.deps.registry.resolve(request.targetHandle, ctx.agentId, ctx.incarnation);
+		if ("refused" in target) return { ok: false, refused: target.refused, targetHandle: request.targetHandle };
+		if (!this.deps.authorize(permissionFor(request.operation), target)) return { ok: false, refused: "permission_denied", targetHandle: target.handle };
+		const kind = classifyRef(request.ref);
+		if (kind === "frame") return { ok: false, refused: "excluded_frame", targetHandle: target.handle };
+		const snapshot = this.snapshots.get(target.handle);
+		const item = kind === "main" && snapshot?.revision === request.snapshotRevision ? snapshot.items.find((entry) => entry.ref === request.ref) : undefined;
+		if (!item) return { ok: false, refused: "stale_ref", targetHandle: target.handle };
+		return { ok: true, target: { handle: target.handle, origin: target.origin, kind: target.kind }, element: { tag: item.tag, role: item.role, name: item.name } };
+	}
+
+	private async openOwned(ctx: AsideContext, url: string): Promise<AsideResult> {
+		if (isProtectedUrl(url, this.deps.gatewayOrigins)) return refuse("protected_target");
+		if (!this.deps.authorize("browser.aside.control", null)) return refuse("permission_denied");
+		const account = await this.deps.confirmedAccount();
+		if (!account) return refuse("target_identity_unclear");
+		const { out, session } = await this.execWith({ account }, "open_owned", { url });
+		if (typeof out === "string") return refuse(out);
+		const opened = out.opened as Seen | null | undefined;
+		if (!opened || typeof opened.targetId !== "string") return refuse("target_identity_unclear");
+		const target = this.deps.registry.registerOwned({ host: this.deps.host, account, targetId: opened.targetId, url, agentId: ctx.agentId, incarnation: ctx.incarnation });
+		if (session?.closed) this.lost.add(target.handle);
+		else session?.owned.set(target.handle, target);
+		if (originOf(opened.url) !== target.origin) {
+			await this.close(target, "redirected_on_open");
+			return refuse("origin_changed", target.handle);
+		}
+		return { ok: true, targetHandle: target.handle, origin: target.origin, background: "unverified_cli_default" };
+	}
+
+	private async read(target: AsideTarget): Promise<AsideResult> {
+		const out = await this.exec(target, "read", { targetId: target.targetId, limit: TEXT_LIMIT });
+		if (typeof out === "string") return refuse(out, target.handle);
+		for (const seen of [out.pre, out.post]) {
+			const check = this.verify(target, seen);
+			if (check !== "ok") return refuse(check, target.handle);
+		}
+		const doc = out.doc as { title: string; text: string; textLength: number; items: Item[]; frames: number };
+		const revision = snapshotRevision(target.targetId, (out.post as Seen).url, doc.items.map((item) => JSON.stringify(item)));
+		this.snapshots.set(target.handle, { revision, items: doc.items });
+		target.snapshotRevision = revision;
+		return { ok: true, targetHandle: target.handle, url: (out.post as Seen).url, title: doc.title, text: doc.text, complete: doc.text.length >= doc.textLength,
+			range: { start: 0, end: doc.text.length, total: doc.textLength }, excludedFrames: doc.frames, elements: doc.items, snapshotRevision: revision };
+	}
+
+	private async screenshot(target: AsideTarget): Promise<AsideResult> {
+		const out = await this.exec(target, "screenshot", { targetId: target.targetId });
+		if (typeof out === "string") return refuse(out, target.handle);
+		for (const seen of [out.pre, out.post]) {
+			const check = this.verify(target, seen);
+			if (check !== "ok") return refuse(check, target.handle);
+		}
+		const image = typeof out.image === "string" && out.image.length <= IMAGE_LIMIT ? out.image : null;
+		return image === null
+			? { ok: true, targetHandle: target.handle, view: "view_unavailable", excludedFrames: (out.doc as { frames: number }).frames }
+			: { ok: true, targetHandle: target.handle, view: "png_base64", image };
+	}
+
+	private async navigate(target: AsideTarget, url: string): Promise<AsideResult> {
+		if (isProtectedUrl(url, this.deps.gatewayOrigins)) return refuse("protected_target", target.handle);
+		const out = await this.exec(target, "navigate_owned", { targetId: target.targetId, url });
+		if (typeof out === "string") return refuse(out, target.handle);
+		const pre = this.verify(target, out.pre);
+		if (pre !== "ok") return refuse(pre, target.handle);
+		const post = out.post as Seen | undefined;
+		this.snapshots.delete(target.handle);
+		target.snapshotRevision = null;
+		if (!post || post.targetId !== target.targetId || originOf(post.url) !== originOf(url) || isProtectedUrl(post.url, this.deps.gatewayOrigins)) {
+			this.deps.registry.suspend(target);
+			return refuse("origin_changed", target.handle);
+		}
+		target.origin = originOf(url) as string;
+		return { ok: true, targetHandle: target.handle, url: post.url };
+	}
+
+	private async act(ctx: AsideContext, target: AsideTarget, request: Extract<AsideRequest, { operation: "click" | "fill" }>): Promise<AsideResult> {
+		const kind = classifyRef(request.ref);
+		if (kind === "frame") return refuse("excluded_frame", target.handle);
+		// The one-shot ticket is checked first, so a replayed ticket is refused as such even after its snapshot is gone.
+		const text = request.operation === "fill" ? request.text : null;
+		if (!this.deps.tickets.consume(ctx.actionTicket, actionDigest(target.handle, request.operation, request.ref, request.snapshotRevision, text))) {
+			return refuse("action_ticket_required", target.handle);
+		}
+		const snapshot = this.snapshots.get(target.handle);
+		if (kind !== "main" || !snapshot || snapshot.revision !== request.snapshotRevision) return refuse("stale_ref", target.handle);
+		const index = snapshot.items.findIndex((item) => item.ref === request.ref);
+		if (index < 0) return refuse("stale_ref", target.handle);
+		this.snapshots.delete(target.handle);
+		target.snapshotRevision = null;
+		const out = await this.exec(target, "act", { targetId: target.targetId, origin: target.origin, expected: snapshot.items, index, text });
+		if (typeof out === "string") return refuse(out, target.handle);
+		const pre = this.verify(target, out.pre);
+		if (pre !== "ok") return refuse(pre, target.handle);
+		if (out.acted !== true) return refuse("stale_ref", target.handle);
+		const post = this.verify(target, out.post);
+		if (post !== "ok") return refuse(post, target.handle);
+		return { ok: true, targetHandle: target.handle, acted: request.operation };
+	}
+
+	private async close(target: AsideTarget, reason: string): Promise<AsideResult> {
+		const out = await this.exec(target, "close_owned", { targetId: target.targetId });
+		const closed = typeof out !== "string" && out.closed === true;
+		this.deps.registry.recordClose(target, reason, closed ? "closed" : "close_failed");
+		if (closed) this.session?.owned.delete(target.handle);
+		this.snapshots.delete(target.handle);
+		return closed ? { ok: true, targetHandle: target.handle, closed: true } : refuse(typeof out === "string" ? out : "aside_failed", target.handle);
+	}
+
+	/** Work end, cancel, revoke, exception or restart: close every owned tab of the agent, never a borrowed one. */
+	async cleanup(agentId: string, reason: string): Promise<void> {
+		for (const target of this.deps.registry.ownedActive(agentId)) await this.close(target, reason);
+		for (const target of this.deps.registry.borrowed(agentId)) this.deps.registry.recordClose(target, reason, "kept_borrowed");
+	}
+
+	/** Adapter end (gateway stop): closes every owned tab the live session opened, then ends the CLI process. */
+	async shutdown(reason = "adapter_shutdown"): Promise<void> {
+		const session = this.session;
+		if (session) {
+			for (const target of [...session.owned.values()]) await this.close(target, reason);
+			await session.shutdown(SHUTDOWN_MS);
+		}
+		this.stopped = true;
+	}
+}