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

package/src/agent/artifacts.ts

@@ -0,0 +1,196 @@
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { MEDIA_MAX_BYTES } from "../media.ts";
+import type { Store } from "../store.ts";
+import { AgentContentError, AgentContentFiles, sourceName } from "./file-core.ts";
+import type { ArtifactSecurityHold } from "../security-allow.ts";
+import { CollaborationStoreError, collaborationNever, type AgentArtifact, type AgentArtifactStage, type CollaborationBinding, type CollaborationGate } from "./collaboration-types.ts";
+
+export interface ArtifactBytes {
+	readonly bytes: Uint8Array;
+	readonly name: string;
+	readonly mediaType: string;
+}
+export interface MaterializedArtifact {
+	readonly artifactId: string;
+	readonly requestId: string;
+	readonly path: string;
+	readonly name: string;
+	readonly sha256: string;
+	readonly bytes: number;
+	readonly origin: "collaboration-copy";
+}
+type ArtifactRead = { readonly requestId: string; readonly artifactId: string; readonly readOperationId: string };
+
+function digest(bytes: Uint8Array): string { return createHash("sha256").update(bytes).digest("hex"); }
+
+/** A byte provider consumes a claimed server stage, never a model-supplied grant or host path. */
+export type StageBytes = (stage: AgentArtifactStage) => Promise<ArtifactBytes>;
+
+/** Store owns authority and lineage. This service owns immutable bytes, not a second grant ledger. */
+export class AgentArtifacts {
+	constructor(private readonly files: AgentContentFiles, private readonly store: Store, private readonly gate: CollaborationGate) {}
+
+	private artifact(id: string): AgentArtifact {
+		const artifact = this.store.agentArtifact(id);
+		if (!artifact) throw new CollaborationStoreError("artifact_not_found", 404);
+		if (artifact.state === "trashed") throw new CollaborationStoreError("artifact_revoked", 410);
+		return artifact;
+	}
+
+	private checkBytes(artifact: Pick<AgentArtifact, "bytes" | "sha256">, bytes: Uint8Array): void {
+		if (bytes.byteLength !== artifact.bytes || digest(bytes) !== artifact.sha256) throw new CollaborationStoreError("artifact_digest_conflict");
+	}
+
+	private pathStage(stage: AgentArtifactStage): void {
+		switch (stage.source.kind) {
+			case "attachment": case "artifact": return;
+			case "agent_path": break;
+			default: return collaborationNever(stage.source);
+		}
+		const parts = stage.source.path.split(/[\\/]/);
+		if (parts.some(part => part === ".." || part === ".collaboration" || part === ".file-trash" || part === ".trash") ||
+			stage.source.path.includes("\0")) throw new CollaborationStoreError("managed_artifact_path", 403);
+		if (stage.sourceBinding.agentId !== null && (parts[0] !== "source" && parts[0] !== "outputs")) throw new CollaborationStoreError("agent_path_forbidden", 403);
+	}
+
+	/**
+	 * The caller supplies the real trusted transport/export port. Absent providers are errors in the caller,
+	 * not a successful placeholder here. Claim precedes all provider IO; seal rechecks the same grant and epochs.
+	 */
+	async stage(transferId: string, provide: StageBytes): Promise<AgentArtifact> {
+		const saved = this.store.agentStage(transferId);
+		if (!saved) throw new CollaborationStoreError("stage_not_found", 404);
+		this.pathStage(saved);
+		if (saved.state === "staged" && saved.artifactId !== null) return this.artifact(saved.artifactId);
+		const stage = this.store.claimAgentStage(transferId, saved.revision, this.gate);
+		try {
+			let supplied: ArtifactBytes;
+			let expected: string;
+			let expectedBytes: number | undefined;
+			switch (stage.source.kind) {
+				case "agent_path":
+					supplied = await provide(stage);
+					expected = stage.source.sha256;
+					break;
+				case "attachment":
+					supplied = await provide(stage);
+					expected = stage.source.origin.originalSha256;
+					expectedBytes = stage.source.origin.bytes;
+					break;
+				case "artifact": {
+					const original = this.artifact(stage.source.artifactId);
+					expected = stage.source.sha256;
+					supplied = { bytes: this.readGranted({ requestId: stage.source.requestId, artifactId: original.id, readOperationId: randomUUID() }, stage.sourceBinding),
+						name: original.originalName, mediaType: original.mediaType };
+					break;
+				}
+				default: return collaborationNever(stage.source);
+			}
+			const bytes = Buffer.from(supplied.bytes);
+			if (digest(bytes) !== expected || (expectedBytes !== undefined && bytes.byteLength !== expectedBytes)) throw new CollaborationStoreError("artifact_digest_conflict");
+			const sealed = this.seal([{ ...supplied, bytes }])[0];
+			if (!sealed) throw new CollaborationStoreError("artifact_missing");
+			return this.store.sealAgentStage({ transferId, expectedRevision: stage.revision, ...sealed }, this.gate);
+		} catch (error) {
+			// A provider or publication may have crossed an external IO boundary. Never replay it as ready.
+			const current = this.store.agentStage(transferId);
+			if (current?.state === "staging") this.store.markAgentStageUnknown(transferId, current.revision);
+			throw error;
+		}
+	}
+
+	private seal(input: readonly ArtifactBytes[]) {
+		if (input.length > 10 || input.reduce((sum, file) => sum + file.bytes.byteLength, 0) > 100 * 1024 * 1024) throw new CollaborationStoreError("result_too_large", 413);
+		// Validate the complete operation before creating its first file.
+		const batch = input.map(file => {
+			if (file.bytes.byteLength > MEDIA_MAX_BYTES) throw new CollaborationStoreError("result_too_large", 413);
+			return { ...file, name: sourceName(file.name), bytes: Buffer.from(file.bytes) };
+		});
+		return batch.map(file => {
+			const sealed = this.files.publish({ directory: [".collaboration", "artifacts"], name: randomUUID(), bytes: file.bytes, immutable: true, exact: true });
+			const readback = this.files.read([".collaboration", "artifacts", sealed.name]);
+			this.checkBytes(sealed, readback);
+			return { sha256: sealed.sha256, bytes: sealed.bytes, name: file.name, mediaType: file.mediaType, sealedName: sealed.name };
+		});
+	}
+
+	/** T4's coherent snapshot consumer supplies bytes; this method never reads a mutable outputs path. */
+	prepareResult(input: { readonly requestId: string; readonly expectedRevision: number; readonly files: readonly ArtifactBytes[] }, binding: CollaborationBinding): readonly AgentArtifact[] {
+		if (!isDeepStrictEqual(this.store.agentBinding(binding.convId), binding)) throw new CollaborationStoreError("binding_conflict");
+		const files = this.seal(input.files);
+		return this.store.prepareAgentResult({ requestId: input.requestId, expectedRevision: input.expectedRevision, files }, binding);
+	}
+
+	readGranted(input: ArtifactRead, binding: CollaborationBinding): Buffer {
+		const artifact = this.artifact(input.artifactId);
+		const reader = this.store.beginAgentArtifactRead(input, binding, this.gate);
+		try {
+			const bytes = this.files.read([".collaboration", "artifacts", artifact.sealedName]);
+			this.checkBytes(artifact, bytes);
+			this.store.claimAgentArtifactReadRelease(reader.readId, binding, this.gate);
+			return bytes;
+		} finally {
+			this.store.settleAgentArtifactReader(reader.readId, { helperStopped: true, leaseReleased: true });
+		}
+	}
+
+	/** `decide` sees the verified bytes before any release; a decision that does not release claims nothing. */
+	async readReviewed<T>(input: ArtifactRead, binding: CollaborationBinding,
+		decide: (artifact: AgentArtifact, bytes: Buffer, readId: string) => Promise<{ readonly release: boolean; readonly value: T }>): Promise<T> {
+		const artifact = this.artifact(input.artifactId);
+		const reader = this.store.beginAgentArtifactRead(input, binding, this.gate);
+		try {
+			const bytes = this.files.read([".collaboration", "artifacts", artifact.sealedName]);
+			this.checkBytes(artifact, bytes);
+			const decision = await decide(artifact, bytes, reader.readId);
+			if (decision.release) this.store.claimAgentArtifactReadRelease(reader.readId, binding, this.gate);
+			return decision.value;
+		} finally {
+			this.store.settleAgentArtifactReader(reader.readId, { helperStopped: true, leaseReleased: true });
+		}
+	}
+
+	/** The owner-allowed continuation releases exactly the reviewed representation, once. */
+	async releaseHeld<T>(hold: ArtifactSecurityHold, binding: CollaborationBinding,
+		present: (artifact: AgentArtifact, bytes: Buffer) => Promise<{ readonly sha256: string; readonly value: T }>): Promise<T> {
+		const artifact = this.artifact(hold.resourceRef.artifactId);
+		const bytes = this.files.read([".collaboration", "artifacts", artifact.sealedName]);
+		this.checkBytes(artifact, bytes);
+		const shown = await present(artifact, bytes);
+		if (artifact.sha256 !== hold.resourceRef.originalSha256 || shown.sha256 !== hold.representation.sha256) throw new CollaborationStoreError("artifact_review_stale");
+		this.store.claimArtifactRelease({ holdId: hold.id, expectedRevision: hold.revision, representation: hold.representation }, binding, this.gate);
+		const claimed = this.store.artifactSecurityHold(hold.id);
+		if (!claimed?.continuation.targetBinding) throw new CollaborationStoreError("artifact_delivery_conflict");
+		this.store.recordArtifactDelivery({ holdId: hold.id, dispatchReceiptId: claimed.continuation.dispatchReceiptId,
+			releaseReceiptId: claimed.continuation.releaseReceiptId, state: "released" }, claimed.continuation.targetBinding);
+		return shown.value;
+	}
+
+	/** Only committed ordinary copies enter knowledge. Scoped files remain outside lists and clone inputs. */
+	importSource(input: ArtifactRead, binding: CollaborationBinding): MaterializedArtifact | null {
+		const artifact = this.artifact(input.artifactId);
+		if (artifact.requestId !== input.requestId || artifact.state !== "committed") throw new CollaborationStoreError("artifact_unbound");
+		if (artifact.storageClass === "scoped_document") return null;
+		if (binding.agentId === null) throw new CollaborationStoreError("source_recipient_required", 403);
+		const bytes = this.readGranted(input, binding);
+		const saved = this.files.publish({ directory: [binding.agentId, "knowledge", "source"],
+			name: `${input.requestId.slice(0, 8)}--${artifact.originalName}`, bytes, immutable: false });
+		const manifest: MaterializedArtifact = { artifactId: artifact.id, requestId: input.requestId, path: `source/${saved.name}`,
+			name: saved.name, sha256: saved.sha256, bytes: saved.bytes, origin: "collaboration-copy" };
+		this.store.appendEvent(binding.convId, "agent.collaboration.materialized", { ...manifest, fileIdentity: saved.fileIdentity });
+		return manifest;
+	}
+
+	trash(artifactId: string): AgentArtifact {
+		const tombstone = this.store.trashAgentArtifact(artifactId);
+		try {
+			this.files.trash(tombstone.sealedName);
+		} catch (error) {
+			// A retry after the physical rename must match the original immutable bytes in Trash.
+			if (!(error instanceof AgentContentError) || error.errno !== 2) throw error;
+			this.checkBytes(tombstone, this.files.read([".collaboration", "trash", tombstone.sealedName]));
+		}
+		return tombstone;
+	}
+}

package/src/agent/aside-target-routes.ts

@@ -0,0 +1,369 @@
+import type { Database } from "bun:sqlite";
+import { createHash, randomUUID } from "node:crypto";
+import type { Decision } from "../store.ts";
+import { type AsideTarget, type AsideTargetRegistry, isProtectedUrl, originOf } from "./aside-targets.ts";
+import { access, canonicalJson, lifecycleEpoch, type AgentToolClients, type AgentToolRequestContext } from "./tool-permissions.ts";
+
+// 294 C7 (defect D4): the owner routes behind the web tab picker of a pending zgw_aside grant card.
+//   GET  /api/decisions/:id/aside-targets  lists the user's open tabs for the user's screen only (never for the model).
+//   POST /api/decisions/:id/aside-target   binds the chosen tab in the target registry and re-proposes the card.
+// The tab list comes from an injected port (the host AsideAdapter list operation, official CLI listBrowserTabs). A
+// candidate id is opaque and only valid for the decision and the listing that produced it. The client sees the
+// title and the URL without query or fragment; protected targets (gateway origins, loopback/.local/.internal,
+// credential pages, non-web pages) are never listed or bound.
+
+export const ASIDE_TOOL = "zgw_aside";
+const OWNED_OPERATIONS = new Set(["open_owned"]);
+const TITLE_LIMIT = 200;
+const LISTINGS_KEPT = 64;
+const BODY_LIMIT = 16 * 1024;
+
+export interface BrowserTab {
+	readonly targetId: string;
+	readonly url: string;
+	readonly title: string;
+}
+
+/** Host side of the picker: the AsideAdapter list operation and the confirmed CLI account. */
+export interface AsideTabPort {
+	listTabs(): Promise<readonly BrowserTab[]>;
+	/** The confirmed Aside CLI account, or null when it is not clear. */
+	account(): Promise<string | null>;
+}
+
+/** The request behind a pending zgw_aside grant card, as the ledger stored it. */
+export interface AsideGrantRequest {
+	readonly requestId: string;
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly originInputSeq: number;
+	readonly operation: string;
+	readonly toolName: string;
+	readonly scope: unknown;
+	readonly proposalDigest: string;
+	readonly state: string;
+}
+
+export type RebindResult =
+	| { readonly ok: true; readonly decision: Decision }
+	| { readonly ok: false; readonly error: "decision_conflict" | "lifecycle_changed" | "not_aside_grant"; readonly decision: Decision | null };
+
+/** Reads and re-proposes the card. SqliteAsideDecisions is the Store-connection implementation. */
+export interface AsideDecisionStore {
+	decision(id: string): Decision | null;
+	request(decisionId: string): AsideGrantRequest | null;
+	rebind(decisionId: string, input: { expectedRevision: number; expectedDigest: string; scope: Record<string, unknown> }): RebindResult;
+}
+
+const record = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+const sha256 = (text: string) => createHash("sha256").update(text).digest("hex");
+
+type RequestRow = {
+	id: string; agent_id: string; incarnation: number; origin_input_seq: number; tool_key_json: string; operation: string;
+	args_digest: string; scope_json: string; proposal_digest: string; state: string;
+};
+type DecisionRow = { revision: number; status: string; submission_id: string | null; payload: string };
+
+/**
+ * The card rebind on the Store connection (the database's only writer). Pass the Store's Database and its getDecision.
+ * The new proposal digest uses the same fields as AgentToolPermissionStore.proposal, so the owner's allow of the
+ * re-proposed card is checked by the existing answer path without change.
+ */
+export class SqliteAsideDecisions implements AsideDecisionStore {
+	constructor(private readonly db: Database, private readonly get: (id: string) => Decision | null) {}
+
+	decision(id: string): Decision | null {
+		return this.get(id);
+	}
+
+	private row(decisionId: string): RequestRow | null {
+		return this.db.query<RequestRow, [string]>(`SELECT id, agent_id, incarnation, origin_input_seq, tool_key_json, operation, args_digest,
+			scope_json, proposal_digest, state FROM agent_tool_requests WHERE decision_id = ?`).get(decisionId);
+	}
+
+	request(decisionId: string): AsideGrantRequest | null {
+		const row = this.row(decisionId);
+		if (!row) return null;
+		const toolKey = JSON.parse(row.tool_key_json) as unknown;
+		return {
+			requestId: row.id, agentId: row.agent_id, incarnation: row.incarnation, originInputSeq: row.origin_input_seq, operation: row.operation,
+			toolName: record(toolKey) && typeof toolKey.originalName === "string" ? toolKey.originalName : "", scope: JSON.parse(row.scope_json) as unknown,
+			proposalDigest: row.proposal_digest, state: row.state,
+		};
+	}
+
+	/** The request behind an invocation, for carrying its bound tab at execution (D4). The stored args are read, never changed. */
+	boundCall(invocationId: string): BoundAsideCall | null {
+		const row = this.db.query<{ agent_id: string; incarnation: number; tool_key_json: string; operation: string; args_json: string; scope_json: string }, [string]>(
+			`SELECT r.agent_id, r.incarnation, r.tool_key_json, r.operation, r.args_json, r.scope_json
+			FROM agent_tool_invocations i JOIN agent_tool_requests r ON r.id = i.request_id WHERE i.id = ?`).get(invocationId);
+		if (!row) return null;
+		const toolKey = JSON.parse(row.tool_key_json) as { originalName?: unknown } | null;
+		return { agentId: row.agent_id, incarnation: row.incarnation, operation: row.operation, args: JSON.parse(row.args_json) as unknown,
+			scope: JSON.parse(row.scope_json) as unknown, toolName: typeof toolKey?.originalName === "string" ? toolKey.originalName : "" };
+	}
+
+	rebind(decisionId: string, input: { expectedRevision: number; expectedDigest: string; scope: Record<string, unknown> }): RebindResult {
+		return this.db.transaction((): RebindResult => {
+			const current = this.db.query<DecisionRow, [string]>("SELECT revision, status, submission_id, payload FROM decisions WHERE id = ?").get(decisionId);
+			const row = this.row(decisionId);
+			if (!current || !row) return { ok: false, error: "not_aside_grant", decision: this.get(decisionId) };
+			if (current.revision !== input.expectedRevision || current.status !== "pending" || current.submission_id !== null ||
+				row.state !== "pending" || row.proposal_digest !== input.expectedDigest) return { ok: false, error: "decision_conflict", decision: this.get(decisionId) };
+			if (lifecycleEpoch(this.db, row.agent_id) !== row.incarnation) return { ok: false, error: "lifecycle_changed", decision: this.get(decisionId) };
+			const toolKey = JSON.parse(row.tool_key_json) as unknown;
+			const proposalDigest = sha256(canonicalJson({
+				agentId: row.agent_id, incarnation: row.incarnation, authorityEpoch: access(this.db, row.agent_id).authorityEpoch, toolKey,
+				operation: row.operation, scope: input.scope, argsDigest: row.args_digest,
+			}));
+			const payload = { ...(JSON.parse(current.payload) as Record<string, unknown>), scope: input.scope, proposalDigest };
+			const now = new Date().toISOString();
+			this.db.query("UPDATE agent_tool_requests SET scope_json = ?, proposal_digest = ?, revision = revision + 1 WHERE id = ?")
+				.run(canonicalJson(input.scope), proposalDigest, row.id);
+			this.db.query("UPDATE decisions SET payload = ?, revision = revision + 1, updated_at = ? WHERE id = ?").run(JSON.stringify(payload), now, decisionId);
+			return { ok: true, decision: this.get(decisionId)! };
+		}).immediate();
+	}
+}
+
+/** The parts of a granted call the deliverer needs to carry its bound tab to the session (D4). */
+export interface BoundAsideCall {
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly toolName: string;
+	readonly operation: string;
+	readonly args: unknown;
+	readonly scope: unknown;
+}
+
+/** What the session adopts under the same handle; the model never sees anything but the handle. */
+export type SessionAsideTarget = Pick<AsideTarget, "handle" | "kind" | "host" | "account" | "targetId" | "origin" | "agentId" | "incarnation" | "selectionSeq">;
+
+/**
+ * D4: the tab the owner bound to this call, resolved in the gateway registry for the call's own agent incarnation. null when
+ * the call names no bound tab (owned tabs, other tools); `unavailable` when the bound tab can no longer be used, so the
+ * call is not started.
+ */
+export function sessionAsideTarget(call: BoundAsideCall | null, registry: AsideTargetRegistry):
+	{ readonly args: unknown; readonly target: SessionAsideTarget } | { readonly unavailable: string } | null {
+	if (!call || call.toolName !== ASIDE_TOOL || OWNED_OPERATIONS.has(call.operation)) return null;
+	// A work tab the session opened itself stays in the session; only a tab the owner designated is carried.
+	if (record(call.scope) && call.scope.kind === "owned_target") return null;
+	const handle = record(call.scope) ? call.scope.targetHandle : undefined;
+	if (typeof handle !== "string" || handle === "") return null;
+	const target = registry.resolve(handle, call.agentId, call.incarnation);
+	if ("refused" in target) return { unavailable: target.refused };
+	const { kind, host, account, targetId, origin, agentId, incarnation, selectionSeq } = target;
+	return { args: call.args, target: { handle: target.handle, kind, host, account, targetId, origin, agentId, incarnation, selectionSeq } };
+}
+
+/**
+ * D4: the picker's tab port over the gateway<->bridge channel. The bridge answers `zgw_aside_tabs` with the confirmed CLI
+ * account and the open tabs from one listing; the routes ask account() then listTabs(), so both read that one answer.
+ */
+export function bridgeTabPort(command: (type: string, params: Record<string, unknown>) => Promise<unknown>): AsideTabPort {
+	let last: Promise<{ account: string | null; tabs: readonly BrowserTab[] }> | null = null;
+	const fetchTabs = async () => {
+		const answer = await command("zgw_aside_tabs", {});
+		const value = record(answer) ? answer : {};
+		const tabs = Array.isArray(value.tabs) ? value.tabs : [];
+		return {
+			account: typeof value.account === "string" && value.account !== "" ? value.account : null,
+			tabs: tabs.filter((tab): tab is Record<string, unknown> => record(tab) && typeof tab.targetId === "string" && typeof tab.url === "string")
+				.map((tab) => ({ targetId: tab.targetId as string, url: tab.url as string, title: typeof tab.title === "string" ? tab.title : "" })),
+		};
+	};
+	return {
+		account: async () => {
+			last = fetchTabs();
+			return (await last).account;
+		},
+		listTabs: async () => {
+			const pending = last ?? fetchTabs();
+			last = null;
+			return (await pending).tabs;
+		},
+	};
+}
+
+interface Listing {
+	readonly account: string;
+	readonly entries: Map<string, BrowserTab>;
+}
+
+/** The latest listing per decision (in memory). A new GET replaces it; a designation consumes it. */
+export class AsideCandidates {
+	private readonly listings = new Map<string, Listing>();
+
+	put(decisionId: string, listing: Listing): void {
+		this.listings.delete(decisionId);
+		this.listings.set(decisionId, listing);
+		if (this.listings.size > LISTINGS_KEPT) this.listings.delete(this.listings.keys().next().value!);
+	}
+
+	get(decisionId: string): Listing | undefined {
+		return this.listings.get(decisionId);
+	}
+
+	drop(decisionId: string): void {
+		this.listings.delete(decisionId);
+	}
+}
+
+export interface AsideTargetHttpDeps {
+	readonly clients: Pick<AgentToolClients, "principal">;
+	readonly decisions: AsideDecisionStore;
+	readonly tabs: AsideTabPort;
+	readonly registry: AsideTargetRegistry;
+	readonly candidates: AsideCandidates;
+	/** The local host the registry binds a target to. */
+	readonly host: string;
+	readonly gatewayOrigins: readonly string[];
+	/** The decision as the inbox shows it (DecisionService.info). */
+	readonly view: (decision: Decision) => unknown;
+	/** Publishes the re-proposed card (DecisionService.refresh). */
+	readonly changed: () => void;
+}
+
+const ROUTE = /^\/api\/decisions\/([^/]+)\/(aside-targets|aside-target)$/;
+
+export function asideTargetRoute(pathname: string): boolean {
+	return ROUTE.test(pathname);
+}
+
+const refuse = (error: string, status: number, extra: Record<string, unknown> = {}) =>
+	Response.json({ error, ...extra }, { status, headers: { "Cache-Control": "no-store" } });
+
+/** C7: only a borrowed-tab card still waiting for its tab takes a designation (an owned tab the agent opens needs none). */
+export function selectionNeeded(request: AsideGrantRequest): boolean {
+	const scope = record(request.scope) ? request.scope : {};
+	if (request.toolName !== ASIDE_TOOL && scope.kind !== "browser_target") return false;
+	if (OWNED_OPERATIONS.has(request.operation)) return false;
+	return scope.selection === "user" || typeof scope.targetHandle !== "string" || scope.targetHandle === "";
+}
+
+/** The URL the user's screen may show: origin and path, never query or fragment. */
+export function displayUrl(url: string): string | null {
+	const origin = originOf(url);
+	return origin === null ? null : `${origin}${new URL(url).pathname}`;
+}
+
+function title(tab: BrowserTab): string {
+	const text = typeof tab.title === "string" ? tab.title.trim() : "";
+	return (text || new URL(tab.url).hostname).slice(0, TITLE_LIMIT);
+}
+
+/** The scope after designation: the opaque handle, its label and origin; the user-selection marker is gone. */
+export function designatedScope(scope: unknown, handle: string, label: string, origin: string): Record<string, unknown> {
+	const { selection: _selection, targetHandle: _handle, targetId: _targetId, targetLabel: _label, targetTitle: _title, ...rest } = record(scope) ? scope : {};
+	return { ...rest, kind: "browser_target", targetHandle: handle, targetLabel: label, origin };
+}
+
+async function body(req: Request): Promise<Record<string, unknown> | null> {
+	if (Number(req.headers.get("content-length") ?? 0) > BODY_LIMIT) return null;
+	const text = await req.text();
+	if (Buffer.byteLength(text) > BODY_LIMIT) return null;
+	try {
+		const value = JSON.parse(text) as unknown;
+		return record(value) ? value : null;
+	} catch {
+		return null;
+	}
+}
+
+type Card = { decision: Decision; request: AsideGrantRequest };
+
+function card(deps: AsideTargetHttpDeps, id: string): Card | Response {
+	const decision = deps.decisions.decision(id);
+	if (!decision) return refuse("decision_not_found", 404);
+	const request = deps.decisions.request(id);
+	if (!request || !selectionNeeded(request)) return refuse("not_aside_target_card", 400);
+	if (decision.status !== "pending" || decision.submissionId !== null || request.state !== "pending") {
+		return refuse("decision_conflict", 409, { decision: deps.view(decision) });
+	}
+	return { decision, request };
+}
+
+async function listTabs(deps: AsideTargetHttpDeps): Promise<{ account: string; tabs: readonly BrowserTab[] } | Response> {
+	let account: string | null;
+	let tabs: readonly BrowserTab[];
+	try {
+		account = await deps.tabs.account();
+		tabs = await deps.tabs.listTabs();
+	} catch {
+		return refuse("aside_unavailable", 503);
+	}
+	if (!account) return refuse("target_identity_unclear", 400);
+	return { account, tabs };
+}
+
+/** Owner routes of the C7 tab picker. Same caller helper (AgentToolClients.principal) as the other owner routes. */
+export async function asideTargetHttp(req: Request, ctx: AgentToolRequestContext, deps: AsideTargetHttpDeps): Promise<Response> {
+	const route = ROUTE.exec(new URL(req.url).pathname);
+	if (!route) return refuse("not_found", 404);
+	const list = route[2] === "aside-targets";
+	if (req.method !== (list ? "GET" : "POST")) return refuse("method_not_allowed", 405);
+	const principal = deps.clients.principal(req, ctx);
+	if (principal instanceof Response) return principal;
+	let id: string;
+	try {
+		id = decodeURIComponent(route[1]!);
+	} catch {
+		return refuse("invalid_decision", 400);
+	}
+	if (list) {
+		const found = card(deps, id);
+		if (found instanceof Response) return found;
+		const listed = await listTabs(deps);
+		if (listed instanceof Response) return listed;
+		const entries = new Map<string, BrowserTab>();
+		const candidates: { id: string; title: string; url: string; origin: string }[] = [];
+		for (const tab of listed.tabs) {
+			if (typeof tab.targetId !== "string" || tab.targetId === "" || typeof tab.url !== "string") continue;
+			if (isProtectedUrl(tab.url, deps.gatewayOrigins)) continue;
+			const candidateId = `atc_${randomUUID()}`;
+			entries.set(candidateId, tab);
+			candidates.push({ id: candidateId, title: title(tab), url: displayUrl(tab.url)!, origin: originOf(tab.url)! });
+		}
+		deps.candidates.put(id, { account: listed.account, entries });
+		return Response.json({ candidates }, { headers: { "Cache-Control": "no-store" } });
+	}
+	const input = await body(req);
+	if (!input || typeof input.candidateId !== "string" || input.candidateId === "" ||
+		(input.expectedRevision !== undefined && (typeof input.expectedRevision !== "number" || !Number.isSafeInteger(input.expectedRevision))) ||
+		(input.proposalDigest !== undefined && typeof input.proposalDigest !== "string") ||
+		(input.expectedRevision === undefined && input.proposalDigest === undefined)) return refuse("invalid_request", 400);
+	const found = card(deps, id);
+	if (found instanceof Response) return found;
+	const { decision, request } = found;
+	if ((input.expectedRevision !== undefined && input.expectedRevision !== decision.revision) ||
+		(input.proposalDigest !== undefined && input.proposalDigest !== request.proposalDigest)) {
+		return refuse("decision_conflict", 409, { decision: deps.view(decision) });
+	}
+	const listing = deps.candidates.get(id);
+	const chosen = listing?.entries.get(input.candidateId);
+	if (!listing || !chosen) return refuse("unknown_candidate", 400);
+	if (isProtectedUrl(chosen.url, deps.gatewayOrigins)) return refuse("protected_target", 403);
+	// The tab must still be open on the same origin under the same CLI account as when it was listed.
+	const listed = await listTabs(deps);
+	if (listed instanceof Response) return listed;
+	if (listed.account !== listing.account) return refuse("account_changed", 410);
+	const now = listed.tabs.find((tab) => tab.targetId === chosen.targetId);
+	if (!now) return refuse("target_closed", 410);
+	if (typeof now.url !== "string" || isProtectedUrl(now.url, deps.gatewayOrigins)) return refuse("protected_target", 403);
+	if (originOf(now.url) !== originOf(chosen.url)) return refuse("target_changed", 410);
+	const target = deps.registry.designate({ host: deps.host, account: listed.account, targetId: now.targetId, url: now.url,
+		agentId: request.agentId, incarnation: request.incarnation, selectionSeq: request.originInputSeq, gatewayOrigins: deps.gatewayOrigins });
+	if ("refused" in target) return refuse(target.refused, target.refused === "protected_target" ? 403 : 400);
+	const result = deps.decisions.rebind(id, { expectedRevision: decision.revision, expectedDigest: request.proposalDigest,
+		scope: designatedScope(request.scope, target.handle, title(now), target.origin) });
+	if (!result.ok) {
+		deps.registry.suspend(target);
+		if (result.error === "lifecycle_changed") return refuse("lifecycle_changed", 410);
+		if (result.error === "not_aside_grant") return refuse("not_aside_target_card", 400);
+		return refuse("decision_conflict", 409, result.decision ? { decision: deps.view(result.decision) } : {});
+	}
+	deps.candidates.drop(id);
+	deps.changed();
+	return Response.json(deps.view(result.decision), { headers: { "Cache-Control": "no-store" } });
+}