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

package/src/agent/aside-targets.ts

@@ -0,0 +1,215 @@
+import { createHash, randomUUID } from "node:crypto";
+
+// 294 C7: server-side registry of Aside browser targets for registered agents. The model only ever sees an opaque
+// targetHandle. A handle is bound to the local host, the confirmed CLI account, the CDP targetId (the official CLI
+// exposes no other tab generation token, so a recreated tab gets a new targetId and never inherits a handle), the
+// allowed origin, and the owning agent incarnation. Borrowed tabs are user-designated; owned tabs are opened by the
+// adapter and closed by it.
+
+export type AsideOperation = "open_owned" | "read" | "screenshot" | "navigate_owned" | "click" | "fill" | "close_owned";
+export type AsidePermission = "browser.aside.read" | "browser.aside.control";
+
+export type AsideRequest =
+	| { readonly operation: "open_owned"; readonly url: string }
+	| { readonly operation: "read" | "screenshot" | "close_owned"; readonly targetHandle: string }
+	| { readonly operation: "navigate_owned"; readonly targetHandle: string; readonly url: string }
+	| { readonly operation: "click"; readonly targetHandle: string; readonly snapshotRevision: string; readonly ref: string }
+	| { readonly operation: "fill"; readonly targetHandle: string; readonly snapshotRevision: string; readonly ref: string; readonly text: string };
+
+export type AsideRefusal =
+	| "invalid_input" | "protected_target" | "unknown_target" | "target_closed" | "target_suspended" | "target_changed"
+	| "origin_changed" | "account_changed" | "target_identity_unclear" | "borrowed_target" | "stale_ref" | "excluded_frame"
+	| "permission_denied" | "action_ticket_required" | "aside_cli_unavailable" | "aside_output_invalid" | "aside_failed";
+
+export interface AsideTarget {
+	readonly handle: string;
+	readonly kind: "borrowed" | "owned";
+	readonly host: string;
+	readonly account: string;
+	readonly targetId: string;
+	origin: string;
+	readonly agentId: string;
+	readonly incarnation: number;
+	readonly selectionSeq: number | null;
+	state: "active" | "suspended" | "closed";
+	snapshotRevision: string | null;
+}
+
+export interface CleanupReceipt {
+	readonly handle: string;
+	readonly targetId: string;
+	readonly reason: string;
+	readonly outcome: "closed" | "close_failed" | "kept_borrowed";
+	readonly at: string;
+}
+
+const FIELDS: Record<AsideOperation, readonly string[]> = {
+	open_owned: ["url"],
+	read: ["targetHandle"],
+	screenshot: ["targetHandle"],
+	close_owned: ["targetHandle"],
+	navigate_owned: ["targetHandle", "url"],
+	click: ["targetHandle", "snapshotRevision", "ref"],
+	fill: ["targetHandle", "snapshotRevision", "ref", "text"],
+};
+const TEXT_LIMIT = 4000;
+
+/** Validates the model input as the closed union. Any extra key (code, selector, account, host, ...) is refused. */
+export function parseAsideRequest(input: unknown): AsideRequest | { readonly refused: "invalid_input" } {
+	if (!input || typeof input !== "object" || Array.isArray(input)) return { refused: "invalid_input" };
+	const record = input as Record<string, unknown>;
+	const operation = record.operation;
+	if (typeof operation !== "string" || !Object.hasOwn(FIELDS, operation)) return { refused: "invalid_input" };
+	const fields = FIELDS[operation as AsideOperation];
+	for (const key of Object.keys(record)) if (key !== "operation" && !fields.includes(key)) return { refused: "invalid_input" };
+	for (const key of fields) {
+		const value = record[key];
+		if (typeof value !== "string" || value.length === 0) return { refused: "invalid_input" };
+		if (key === "text" ? value.length > TEXT_LIMIT : value.length > 2048) return { refused: "invalid_input" };
+	}
+	return record as unknown as AsideRequest;
+}
+
+export function permissionFor(operation: AsideOperation): AsidePermission {
+	return operation === "read" || operation === "screenshot" ? "browser.aside.read" : "browser.aside.control";
+}
+
+/** Normalized http(s) origin, or null for anything else (about:, chrome:, file:, data:, javascript:, aside:, ...). */
+export function originOf(url: string): string | null {
+	let parsed: URL;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return null;
+	}
+	if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return null;
+	return parsed.origin;
+}
+
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "0.0.0.0"]);
+const CREDENTIAL_PATH = /\/(login|signin|sign-in|logout|password|passwords|oauth|authorize|2fa|mfa|security|credentials?)(\/|$|\?)/i;
+
+/** Gateway origins, loopback/internal admin URLs and credential pages are never model targets. */
+export function isProtectedUrl(url: string, gatewayOrigins: readonly string[]): boolean {
+	const origin = originOf(url);
+	if (origin === null) return true;
+	if (gatewayOrigins.includes(origin)) return true;
+	const host = new URL(url).hostname;
+	if (LOOPBACK.has(host) || LOOPBACK.has(`[${host}]`) || host.endsWith(".local") || host.endsWith(".internal")) return true;
+	return CREDENTIAL_PATH.test(new URL(url).pathname);
+}
+
+/** A main-document ref the host produced (e<n>). Frame-prefixed refs (f<n>e<n>) are iframe content and are refused. */
+export function classifyRef(ref: string): "main" | "frame" | "invalid" {
+	if (/^e\d{1,5}$/.test(ref)) return "main";
+	if (/^f\d{1,5}e\d{1,5}$/.test(ref)) return "frame";
+	return "invalid";
+}
+
+export interface Observation {
+	readonly targetId: string;
+	readonly url: string;
+	readonly account: string;
+}
+
+/** Compares what the CLI reported with the bound target. Checked before and after every read and action. */
+export function checkObservation(target: AsideTarget, observed: Observation): "ok" | "target_changed" | "origin_changed" | "account_changed" {
+	if (observed.account !== target.account) return "account_changed";
+	if (observed.targetId !== target.targetId) return "target_changed";
+	if (originOf(observed.url) !== target.origin) return "origin_changed";
+	return "ok";
+}
+
+export function snapshotRevision(targetId: string, url: string, elements: readonly string[]): string {
+	return createHash("sha256").update(JSON.stringify([targetId, url, elements])).digest("hex").slice(0, 16);
+}
+
+export class AsideTargetRegistry {
+	private readonly targets = new Map<string, AsideTarget>();
+	readonly receipts: CleanupReceipt[] = [];
+
+	constructor(private readonly now: () => Date = () => new Date()) {}
+
+	/** Binds a user-selected open tab. Only the handle goes to the model; the tab list stays on the user's screen. */
+	designate(input: { host: string; account: string; targetId: string; url: string; agentId: string; incarnation: number; selectionSeq: number;
+		gatewayOrigins: readonly string[] }): AsideTarget | { readonly refused: AsideRefusal } {
+		if (!input.account || !input.targetId || !input.host) return { refused: "target_identity_unclear" };
+		if (isProtectedUrl(input.url, input.gatewayOrigins)) return { refused: "protected_target" };
+		return this.add("borrowed", input, input.selectionSeq);
+	}
+
+	/**
+	 * D4: a target the gateway registry bound (C7 picker), carried to the session that executes the granted call under the
+	 * same handle. A handle this registry already knows keeps its own record, so a suspension or close here is never undone.
+	 */
+	adopt(input: Pick<AsideTarget, "handle" | "kind" | "host" | "account" | "targetId" | "origin" | "agentId" | "incarnation" | "selectionSeq">): AsideTarget {
+		const known = this.targets.get(input.handle);
+		if (known) return known;
+		const target: AsideTarget = { ...input, state: "active", snapshotRevision: null };
+		this.targets.set(target.handle, target);
+		return target;
+	}
+
+	registerOwned(input: { host: string; account: string; targetId: string; url: string; agentId: string; incarnation: number }): AsideTarget {
+		return this.add("owned", input, null);
+	}
+
+	private add(kind: AsideTarget["kind"], input: { host: string; account: string; targetId: string; url: string; agentId: string; incarnation: number },
+		selectionSeq: number | null): AsideTarget {
+		const origin = originOf(input.url);
+		if (origin === null) throw new Error("aside_target_origin_invalid");
+		const target: AsideTarget = { handle: `ash_${randomUUID()}`, kind, host: input.host, account: input.account, targetId: input.targetId, origin,
+			agentId: input.agentId, incarnation: input.incarnation, selectionSeq, state: "active", snapshotRevision: null };
+		this.targets.set(target.handle, target);
+		return target;
+	}
+
+	/** The target for this agent incarnation, or why it cannot be used. Another agent's handle is unknown to this one. */
+	resolve(handle: string, agentId: string, incarnation: number): AsideTarget | { readonly refused: AsideRefusal } {
+		const target = this.targets.get(handle);
+		if (!target || target.agentId !== agentId || target.incarnation !== incarnation) return { refused: "unknown_target" };
+		if (target.state === "closed") return { refused: "target_closed" };
+		if (target.state === "suspended") return { refused: "target_suspended" };
+		return target;
+	}
+
+	/** Keeps the record and marks it suspended; a new selection is needed to continue. */
+	suspend(target: AsideTarget): void {
+		target.state = "suspended";
+		target.snapshotRevision = null;
+	}
+
+	recordClose(target: AsideTarget, reason: string, outcome: CleanupReceipt["outcome"]): void {
+		if (outcome === "closed") target.state = "closed";
+		this.receipts.push({ handle: target.handle, targetId: target.targetId, reason, outcome, at: this.now().toISOString() });
+	}
+
+	ownedActive(agentId: string): AsideTarget[] {
+		return [...this.targets.values()].filter((target) => target.agentId === agentId && target.kind === "owned" && target.state !== "closed");
+	}
+
+	borrowed(agentId: string): AsideTarget[] {
+		return [...this.targets.values()].filter((target) => target.agentId === agentId && target.kind === "borrowed");
+	}
+}
+
+/** One-shot external action tickets (C8). The adapter consumes a ticket at start; a second start with it is refused. */
+export class ActionTickets {
+	private readonly open = new Map<string, string>();
+
+	issue(digest: string): string {
+		const ticket = `act_${randomUUID()}`;
+		this.open.set(ticket, digest);
+		return ticket;
+	}
+
+	consume(ticket: string | undefined, digest: string): boolean {
+		if (!ticket || this.open.get(ticket) !== digest) return false;
+		this.open.delete(ticket);
+		return true;
+	}
+}
+
+export function actionDigest(handle: string, operation: "click" | "fill", ref: string, revision: string, text: string | null): string {
+	return createHash("sha256").update(JSON.stringify([handle, operation, ref, revision, text])).digest("hex");
+}

package/src/agent/collaboration-admission.ts

@@ -0,0 +1,47 @@
+import type { Store } from "../store.ts";
+import type { AgentFileStore } from "./files.ts";
+import { mergeAgentDefinition } from "./definition.ts";
+import { CollaborationStoreError, type AgentRequest, type CollaborationGate, type CollaborationPermissionOutcome } from "./collaboration-types.ts";
+
+export type CollaborationAuthority =
+	| { readonly mode: "standalone" }
+	| { readonly mode: "authority"; readonly provider?: Extract<CollaborationGate, { mode: "authority" }> };
+
+/** One policy seam for HTTP admission and subsequent Hub dispatch; it never owns authority or sessions. */
+export class CollaborationAdmission {
+	constructor(private readonly store: Store, private readonly files: AgentFileStore,
+		private readonly authority: CollaborationAuthority = { mode: "standalone" }) {}
+
+	gate(request?: AgentRequest): CollaborationGate {
+		const authority = this.authority;
+		if (authority.mode === "authority" && !authority.provider) throw new CollaborationStoreError("authority_adapter_required", 503);
+		const provider = authority.mode === "authority" ? authority.provider : undefined;
+		return { ...(provider ?? { mode: "standalone" }), assertAccess: (tx, source, target) => {
+			provider?.assertAccess(tx, source, target);
+			const sender = request ? request.requesterAgent : source.agentId;
+			const recipient = request?.targetAgent ?? target.agentId;
+			if (sender !== null) {
+				const fields = mergeAgentDefinition(this.files.read(sender), this.files.readDefaults()).fields;
+				const collaboration = fields.collaboration;
+				if (typeof collaboration !== "object" || collaboration === null || !("targets" in collaboration) ||
+					!Array.isArray(collaboration.targets) || !collaboration.targets.includes(recipient)) throw new CollaborationStoreError("target_forbidden");
+				if (request && this.store.ensureAgentLifecycle(sender) !== request.requesterLifecycleEpoch) throw new CollaborationStoreError("lifecycle_conflict");
+				if (request && provider) {
+					const access = provider.access(tx, sender);
+					if (access.accessState !== "open") throw new CollaborationStoreError("agent_access_blocked", 403);
+					if (access.authorityEpoch !== request.requesterAuthorityEpoch) throw new CollaborationStoreError("authority_epoch_mismatch");
+				}
+			}
+			return undefined;
+		} };
+	}
+
+	permission(outcome: CollaborationPermissionOutcome) {
+		const gate = this.gate();
+		if (gate.mode !== "authority") throw new CollaborationStoreError("authority_adapter_required", 503);
+		const request = this.store.getAgentRequest(outcome.collaborationRequestId);
+		const binding = request && this.store.agentBinding(request.targetConv);
+		if (!binding) throw new CollaborationStoreError("permission_outcome_conflict");
+		return this.store.dispatchCollaborationPermission(outcome, binding, gate);
+	}
+}

package/src/agent/collaboration-read.ts

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+import { NativeDocumentError, readNativeDocument, type NativeDocumentBuild, type NativeDocumentResult, type NativeTextCursor } from "../attachments/document-reader.ts";
+import type { AttachmentFormat } from "../attachments/types.ts";
+import type { ArtifactSecurityHold } from "../security-allow.ts";
+import { CollaborationStoreError, collaborationDigest, type AgentArtifact } from "./collaboration-types.ts";
+
+export type ArtifactReadArguments = ArtifactSecurityHold["readArguments"];
+/**
+ * One release to a peer: the response, the texts the message security check scans, the reviewed representation, and
+ * the pages whose text layer the reader could not provide (nothing of them was scanned; the caller holds them).
+ */
+export interface PresentedRead {
+	readonly body: Record<string, unknown>;
+	readonly texts: readonly string[];
+	readonly representation: Pick<ArtifactSecurityHold["representation"], "sha256" | "view" | "range" | "coverageDigest">;
+	readonly unscannedPages: readonly number[];
+}
+
+type PageRepresentation = NativeDocumentResult["coverage"]["pages"][number]["representation"];
+/** The page classes whose content the text check could read; a page the reader classifies as rendered-only, or does not classify, was not scanned. */
+const SCANNED_PAGE: ReadonlySet<PageRepresentation> = new Set<PageRepresentation>(["native-text", "ocr-text", "verified-blank"]);
+/**
+ * The pages of a rendered range that no text check covered. The reader's text operation labels an image-only page
+ * native-text with an empty layer, so the per-page class comes from document.inspect, which reports rendered-image for
+ * a page without a text layer; such a page is held fail-closed, never released unchecked.
+ */
+export function unscannedPages(rendered: NativeDocumentResult["coverage"], inspected: NativeDocumentResult["coverage"]): number[] {
+	const classes = new Map<number, PageRepresentation>(inspected.pages.map(page => [page.page, page.representation]));
+	return rendered.pages.map(page => page.page).filter(page => {
+		const seen = classes.get(page);
+		return seen === undefined || !SCANNED_PAGE.has(seen);
+	});
+}
+
+const sha = (value: string | Uint8Array): string => createHash("sha256").update(value).digest("hex");
+const MAX_TEXT_SCAN_CHUNKS = 64;
+
+function format(artifact: AgentArtifact): AttachmentFormat | null {
+	const type = artifact.mediaType.split(";")[0]!.trim().toLowerCase(), name = artifact.originalName.toLowerCase();
+	if (type === "application/pdf" || name.endsWith(".pdf")) return "pdf";
+	if (type === "text/markdown" || name.endsWith(".md")) return "md";
+	if (type === "text/html" || name.endsWith(".html") || name.endsWith(".htm")) return "html";
+	if (type.startsWith("text/") || name.endsWith(".txt")) return "txt";
+	return null;
+}
+const encode = (value: object): string => Buffer.from(JSON.stringify(value)).toString("base64url");
+function decode(raw: string | undefined, artifact: AgentArtifact, view: "text" | "pages"): Record<string, unknown> | undefined {
+	if (raw === undefined) return undefined;
+	let value: unknown;
+	try { value = JSON.parse(Buffer.from(raw, "base64url").toString("utf8")); }
+	catch { throw new CollaborationStoreError("invalid_cursor", 400); }
+	if (typeof value !== "object" || value === null || Array.isArray(value) || (value as Record<string, unknown>).v !== view ||
+		(value as Record<string, unknown>).originalSha256 !== artifact.sha256) throw new CollaborationStoreError("invalid_cursor", 400);
+	return value as Record<string, unknown>;
+}
+function readerError(error: unknown): never {
+	if (!(error instanceof NativeDocumentError)) throw error;
+	switch (error.code) {
+		case "native_reader_unavailable": throw new CollaborationStoreError("native_reader_unavailable", 503);
+		case "invalid_cursor": case "invalid_document_options": throw new CollaborationStoreError(error.code, 400);
+		default: throw new CollaborationStoreError(error.code, 409);
+	}
+}
+
+/**
+ * Produces what files.read releases. Raw bytes are scanned whole (the download route hands the extension every byte);
+ * text and pages come only from the 293 native document reader, and pages are scanned through the text layer of the
+ * same pages. Nothing here releases: the caller checks `texts` and claims or holds.
+ */
+export async function presentArtifactRead(input: { readonly artifact: AgentArtifact; readonly bytes: Buffer; readonly args: ArtifactReadArguments;
+	readonly reader: NativeDocumentBuild | null | undefined }): Promise<PresentedRead> {
+	const { artifact, bytes, args } = input;
+	const ids = { artifactId: artifact.id, requestId: args.requestId };
+	if (args.view === undefined) {
+		return { body: { ...ids, sha256: artifact.sha256, bytes: bytes.length, preview: bytes.subarray(0, 32768).toString("utf8"), truncated: bytes.length > 32768 },
+			texts: [bytes.toString("utf8")], unscannedPages: [],
+			representation: { sha256: artifact.sha256, view: "raw", range: { start: 0, end: bytes.length }, coverageDigest: collaborationDigest({ bytes: bytes.length }) } };
+	}
+	const selected = format(artifact);
+	if (selected === null || (args.view === "pages" && selected !== "pdf")) throw new CollaborationStoreError("view_unavailable", 400);
+	const reader = input.reader;
+	if (!reader) throw new CollaborationStoreError("native_reader_unavailable", 503);
+	const context = { signal: new AbortController().signal, isCurrent: () => true };
+	const read = (operation: "document.text" | "document.pages" | "document.inspect", options: Record<string, unknown>): Promise<NativeDocumentResult> =>
+		readNativeDocument(reader, { original: bytes, operation, options: { format: selected, ...options } }, context).catch(readerError);
+	if (args.view === "text") {
+		const cursor = decode(args.cursor, artifact, "text");
+		const native: NativeTextCursor | undefined = cursor && { originalSha256: artifact.sha256, representationSha256: String(cursor.representationSha256), offset: Number(cursor.offset) };
+		const result = await read("document.text", { ...(args.limit === undefined ? {} : { lineLimit: args.limit }), ...(native ? { cursor: native } : {}) });
+		const texts = result.content.flatMap(item => item.type === "text" ? [item.text] : []);
+		const range = result.textRange ?? { start: 0, end: texts.join("").length };
+		return { body: { ...ids, sha256: artifact.sha256, view: "text", coverage: result.coverage, content: result.content,
+			...(result.nextCursor ? { nextCursor: encode({ v: "text", originalSha256: artifact.sha256, representationSha256: result.nextCursor.representationSha256, offset: result.nextCursor.offset }) } : {}) },
+		texts, unscannedPages: [], representation: { sha256: sha(JSON.stringify(result.content)), view: "text", range: { start: range.start, end: range.end }, coverageDigest: collaborationDigest(result.coverage) } };
+	}
+	const cursor = decode(args.cursor, artifact, "pages");
+	const firstPage = cursor ? Number(cursor.page) : 1, pageLimit = args.limit ?? 2;
+	const result = await read("document.pages", { firstPage, pageLimit });
+	const count = result.coverage.pages.length, next = firstPage + count;
+	// Rendered page images cannot be scanned as text; their selectable text layer is, chunk by chunk, for exactly these pages.
+	const texts: string[] = [];
+	let layer: NativeTextCursor | undefined;
+	for (let chunk = 0; ; chunk++) {
+		if (chunk === MAX_TEXT_SCAN_CHUNKS) throw new CollaborationStoreError("processing_limit", 409);
+		const part = await read("document.text", { firstPage, pageLimit: Math.max(count, 1), ...(layer ? { cursor: layer } : {}) });
+		texts.push(...part.content.flatMap(item => item.type === "text" ? [item.text] : []));
+		if (!part.nextCursor) break;
+		layer = part.nextCursor;
+	}
+	// A page without a text layer (document.inspect: rendered-image) was not scanned at all: the caller holds it, never releases it unchecked.
+	const inspected = await read("document.inspect", {});
+	return { body: { ...ids, sha256: artifact.sha256, view: "pages", coverage: result.coverage, content: result.content,
+		...(next <= result.coverage.totalPages ? { nextCursor: encode({ v: "pages", originalSha256: artifact.sha256, page: next }) } : {}) },
+	texts, unscannedPages: unscannedPages(result.coverage, inspected.coverage),
+	representation: { sha256: sha(JSON.stringify([artifact.sha256, firstPage, pageLimit, result.coverage, texts])), view: "pages",
+		range: { start: firstPage, end: firstPage + count - 1 }, coverageDigest: collaborationDigest(result.coverage) } };
+}

package/src/agent/collaboration-session.ts

@@ -0,0 +1,196 @@
+import { createSecretKey, randomBytes, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import type { Hub } from "../hub.ts";
+import type { Store } from "../store.ts";
+import type { ArtifactSecurityHold } from "../security-allow.ts";
+import { OmoCommandError } from "../omo/client.ts";
+import { CollaborationStoreError, collaborationDigest, type CollaborationBinding, type AgentRequest, type CollaborationGate, type CollaborationPermissionOutcome, type AgentActivation } from "./collaboration-types.ts";
+import { parseManagedCallIdentity, sameManagedCallIdentity, verifyManagedCall,
+	type ManagedCallIdentity, type ManagedCallRequest } from "./managed-call.ts";
+
+export const collaborationRecord = (value: unknown): value is Record<string, unknown> =>
+	value !== null && typeof value === "object" && !Array.isArray(value);
+export const collaborationText = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+export type CollaborationLifecycle = {
+	readonly bind: (conv: string, inputId: string, dispatch?: CollaborationDispatch) => Promise<void>;
+	readonly gate: (request: AgentRequest) => CollaborationGate;
+	readonly permission: (outcome: CollaborationPermissionOutcome) => AgentActivation;
+	/** Supplied only by the actual registered document/owner adapter; absence is not authority. */
+	readonly artifactRead: (hold: ArtifactSecurityHold) => CollaborationGate;
+	readonly retire: (conv?: string) => void;
+};
+export type CollaborationDispatch = {
+	readonly activationId: string | null;
+	readonly requestId: string | null;
+	readonly rootId: string | null;
+	readonly read?: { readonly continuationId: string; readonly arguments: ArtifactSecurityHold["readArguments"] };
+	readonly claim: (binding: CollaborationBinding) => void;
+};
+type Session = {
+	readonly lease: NonNullable<ReturnType<Hub["collaborationSession"]>>;
+	readonly identity: ManagedCallIdentity;
+	readonly binding: CollaborationBinding;
+	readonly requestId: string | null;
+	readonly rootId: string | null;
+	readonly secret: ReturnType<typeof createSecretKey>;
+	readonly nonces: Set<string>;
+};
+const reject: (code: string) => never = code => { throw new CollaborationStoreError(code, 403); };
+
+/** Gateway-owned secrets and nonce claims share the same lifetime as the actual Hub session lease. */
+export class CollaborationSessions {
+	private readonly sessions = new Map<string, Session>();
+	constructor(private readonly hub: Pick<Hub, "collaborationSession">, private readonly store: Store) {}
+	retire(conv?: string): void {
+		if (conv === undefined) this.sessions.clear();
+		else this.sessions.delete(conv);
+	}
+	assertCurrent(session: Session): void {
+		if (this.sessions.get(session.binding.convId) !== session || !session.lease.current() ||
+			!isDeepStrictEqual(this.store.agentBinding(session.binding.convId), session.binding)) reject("binding_mismatch");
+	}
+	async bind(conv: string, inputId: string, dispatch?: CollaborationDispatch): Promise<void> {
+		this.retire(conv);
+		const lease = this.hub.collaborationSession(conv);
+		if (!lease) throw new CollaborationStoreError("collaboration_session_unavailable", 503);
+		const [state, runtime, listed] = await Promise.all([
+			lease.rpc("get_state"), lease.rpc("extension_request", { name: "zgw.agent_collaboration_runtime" }),
+			lease.rpc("list_sessions", { include_all: true, include_workers: true }),
+		]);
+		if (!lease.current() || !collaborationRecord(state) || state.sessionId !== lease.durableId ||
+			state.sessionFile !== lease.sessionPath || !collaborationRecord(runtime) ||
+			!collaborationText(runtime.definitionSha) || !collaborationText(runtime.fingerprint) ||
+			!this.listed(listed, lease)) reject("native_binding_unavailable");
+		const binding: CollaborationBinding = Object.freeze({
+			convId: conv, agentId: lease.agentId, lifecycleEpoch: lease.agentId === null ? 1 : this.store.ensureAgentLifecycle(lease.agentId),
+			inputId, activationId: dispatch?.activationId ?? null, sessionPath: lease.sessionPath, durableSessionId: lease.durableId,
+			gatewayGeneration: lease.generation, definitionSha: runtime.definitionSha, ownerInputRevision: lease.ownerInputRevision,
+			...(dispatch?.read ? { readContinuationId: dispatch.read.continuationId } : {}),
+		});
+		const identity = parseManagedCallIdentity({
+			role: lease.agentId === null ? "main" : "agent", agentId: lease.agentId, convId: conv,
+			convEpoch: lease.convEpoch, lifecycleEpoch: binding.lifecycleEpoch,
+			sessionPath: lease.sessionPath, durableSessionId: lease.durableId, sessionIncarnation: lease.incarnation,
+			gatewayGeneration: lease.generation, inputId, activationId: binding.activationId, toolCallId: "binding", logicalCallId: "binding",
+		});
+		const bytes = randomBytes(32);
+		const session: Session = { lease, identity, binding, requestId: dispatch?.requestId ?? null, rootId: dispatch?.rootId ?? null,
+			secret: createSecretKey(bytes), nonces: new Set() };
+		const reservationId = dispatch ? randomUUID() : undefined;
+		let reserved = false;
+		try {
+			const bound = await lease.rpc("extension_request", { name: "zgw.agent_collaboration_bind",
+				data: { identity, binding, secret: bytes.toString("hex"), requestId: session.requestId, rootId: session.rootId, inputEvidence: "client_entry",
+					...(reservationId ? { reservationId } : {}), ...(dispatch?.read ? { read: { operation: "read", ...dispatch.read.arguments } } : {}) } })
+				.catch((error: unknown) => {
+					// The runtime applied another definition after the handshake read: a definite refusal, never unknown delivery.
+					if (error instanceof OmoCommandError && error.code === "version_conflict") throw new CollaborationStoreError("version_conflict", 409);
+					throw error;
+				});
+			reserved = reservationId !== undefined;
+			if (!lease.current() || !collaborationRecord(bound) || !this.matchesBase(bound, identity)) reject("native_binding_unavailable");
+			if (dispatch) dispatch.claim(binding);
+			else this.store.recordAgentBinding(binding);
+			if (reservationId) {
+				const armed = await lease.rpc("extension_request", { name: "zgw.agent_collaboration_reservation",
+					data: { action: "arm", reservationId, identity } });
+				if (!lease.current() || !collaborationRecord(armed) || armed.inputId !== inputId || armed.state !== "armed") reject("native_binding_unavailable");
+			}
+			this.sessions.set(conv, session);
+		} catch (error) {
+			// A callback can throw after committing. Query Store evidence rather than trusting callback completion.
+			const activation = binding.activationId === null ? null : this.store.getAgentActivation(binding.activationId);
+			const read = binding.readContinuationId === undefined ? null : this.store.nextArtifactReadInput(conv)?.hold;
+			const unclaimed = activation ? activation.state === "queued" && activation.binding === null && activation.inputId === inputId :
+				read?.continuation.id === binding.readContinuationId && read?.continuation.state === "queued" &&
+					read.continuation.targetBinding === null && read.continuation.dispatchReceiptId === null;
+			if (reservationId && reserved && unclaimed) {
+				const released = await lease.rpc("extension_request", { name: "zgw.agent_collaboration_reservation",
+					data: { action: "release", reservationId, identity } });
+				if (!collaborationRecord(released) || released.inputId !== inputId || released.state !== "released") reject("native_binding_unavailable");
+			}
+			throw error;
+		} finally { bytes.fill(0); }
+	}
+	private listed(value: unknown, lease: Session["lease"]): boolean {
+		return collaborationRecord(value) && Array.isArray(value.sessions) && value.sessions.some((row: unknown) =>
+			collaborationRecord(row) && row.sessionId === lease.sessionId && row.sessionPath === lease.sessionPath && row.status === "open");
+	}
+	private matchesBase(value: Record<string, unknown>, identity: ManagedCallIdentity): boolean {
+		return Object.entries(identity).every(([key, field]) => value[key] === field);
+	}
+	async authenticate(request: ManagedCallRequest & { readonly proof: unknown; readonly logicalPayload: unknown }) {
+		if (!collaborationRecord(request.proof)) return reject("invalid_proof");
+		const selector = parseManagedCallIdentity(request.proof.identity);
+		const session = this.sessions.get(selector.convId);
+		if (!session) return reject("binding_mismatch");
+		this.assertCurrent(session);
+		const [listed, native, state, transcript] = await Promise.all([
+			session.lease.rpc("list_sessions", { include_all: true, include_workers: true }),
+			session.lease.rpc("extension_request", { name: "zgw.agent_collaboration_identity" }),
+			session.lease.rpc("get_state"), session.lease.rpc("get_entries"),
+		]);
+		this.assertCurrent(session);
+		if (!this.listed(listed, session.lease) || !collaborationRecord(native) ||
+			!this.matchesBase(native, session.identity) || native.consumed !== true ||
+			!collaborationRecord(state) || state.sessionId !== session.identity.durableSessionId ||
+			state.sessionFile !== session.identity.sessionPath) return reject("native_binding_mismatch");
+		// Follow the actual active branch to the last consumed input. Tool names/ordinals come from native entries.
+		if (!collaborationRecord(transcript) || !Array.isArray(transcript.entries) || !collaborationText(transcript.leafId)) return reject("native_invocation_missing");
+		const entries = new Map(transcript.entries.filter(collaborationRecord).filter(e => collaborationText(e.id)).map(e => [e.id, e]));
+		const seen = new Set<string>();
+		let cursor: unknown = transcript.leafId, logical: string | undefined, anchored = false;
+		while (collaborationText(cursor) && !seen.has(cursor)) {
+			seen.add(cursor);
+			const entry = entries.get(cursor);
+			if (!entry || !collaborationText(entry.id)) break;
+			const message = entry.message;
+			if (entry.type === "message" && collaborationRecord(message)) {
+				if (message.role === "user") {
+					anchored = message.clientInputId === session.identity.inputId && native.inputEntryId === entry.id;
+					break;
+				}
+				if (message.role === "assistant" && Array.isArray(message.content)) {
+					const ordinal = message.content.findIndex((part: unknown) => collaborationRecord(part) &&
+						part.type === "toolCall" && part.id === selector.toolCallId &&
+						part.name === `zgw_agent_${request.operation.split(".")[0]}`);
+					if (ordinal >= 0 && logical === undefined) logical = JSON.stringify([session.identity.durableSessionId, entry.id, ordinal]);
+				}
+			}
+			cursor = entry.parentId;
+		}
+		if (!anchored || !logical) return reject("native_invocation_missing");
+		const identity = parseManagedCallIdentity({ ...session.identity, toolCallId: selector.toolCallId, logicalCallId: logical });
+		const verified = verifyManagedCall(request, candidate => {
+			this.assertCurrent(session);
+			if (!sameManagedCallIdentity(candidate, identity)) return null;
+			return { identity, secret: session.secret, claimNonce: nonce => {
+				this.assertCurrent(session);
+				if (session.nonces.has(nonce)) return false;
+				session.nonces.add(nonce); return true;
+			} };
+		});
+		// Preserve the accepted native submission key. A rotated alias is unknown, never a fresh execution.
+		const operationKey = JSON.stringify([identity.durableSessionId, identity.toolCallId, request.operation]);
+		const payloadSha = collaborationDigest(request.logicalPayload);
+		const mappings = this.store.eventsAfter(identity.convId, 0).filter(event => event.type === "agent.collaboration.call" && collaborationRecord(event.data));
+		const prior = mappings.find(event => collaborationRecord(event.data) && event.data.logicalCallId === logical && event.data.operation === request.operation);
+		const wire = mappings.find(event => collaborationRecord(event.data) && event.data.operationKey === operationKey);
+		if (wire && (!collaborationRecord(wire.data) || wire.data.logicalCallId !== logical)) throw new CollaborationStoreError("logical_call_unknown");
+		if (prior && collaborationRecord(prior.data) && prior.data.payloadSha !== payloadSha) throw new CollaborationStoreError("submission_conflict");
+		if (prior && (!collaborationRecord(prior.data) || prior.data.operationKey !== operationKey ||
+			prior.data.inputId !== identity.inputId || prior.data.incarnation !== identity.sessionIncarnation)) {
+			throw new CollaborationStoreError("logical_call_unknown");
+		}
+		let operationId: string;
+		if (prior) {
+			if (!collaborationRecord(prior.data) || !collaborationText(prior.data.operationId)) throw new CollaborationStoreError("logical_call_unknown");
+			operationId = prior.data.operationId;
+		} else operationId = randomUUID();
+		if (!prior) this.store.appendEvent(identity.convId, "agent.collaboration.call", {
+			logicalCallId: logical, operation: request.operation, operationKey, operationId, payloadSha, inputId: identity.inputId, incarnation: identity.sessionIncarnation,
+		});
+		return { verified, binding: session.binding, requestId: session.requestId, rootId: session.rootId,
+			operationKey, operationId, assertCurrent: () => this.assertCurrent(session) };
+	}
+}