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

package/src/attachments/host-selector.ts

@@ -0,0 +1,410 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fchmodSync, fsyncSync, lstatSync, mkdirSync, openSync, rmdirSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { dlopen } from "bun:ffi";
+
+const MAX = 10 * 1024 * 1024;
+const MAX_PICKERS = 8;
+const MAX_HANDLES = 20_000;
+const STREAM_MAX = 16 * 1024 * 1024;
+const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
+type Root = "home" | "computer" | "downloads";
+type Format = "html" | "md" | "txt" | "pdf";
+export interface PickerScope {
+	readonly ownerPrincipal: string;
+	readonly principalRevision: number;
+	readonly draftId: string;
+	readonly convId: string;
+	readonly convEpoch: number;
+	readonly recipient: { readonly kind: "main" | "agent"; readonly id: string; readonly epoch: number };
+	readonly generation: string;
+}
+export interface SourceIdentity {
+	readonly device: string; readonly inode: string; readonly size: number;
+	readonly mtimeNs: string; readonly ctimeNs: string; readonly nlink: number;
+}
+interface Location { readonly root: Root; readonly segments: readonly string[] }
+export interface SelectedSource extends Location {
+	readonly name: string; readonly format: Format; readonly identity: SourceIdentity;
+}
+interface NativeEntry {
+	readonly name: string; readonly kind: "directory" | "file" | "disabled";
+	readonly selectable: boolean; readonly identity?: SourceIdentity; readonly reason?: string;
+}
+interface NativePage { readonly entries: readonly NativeEntry[]; readonly nextName?: string }
+export interface PickerEntry {
+	readonly entryToken: string; readonly kind: NativeEntry["kind"]; readonly name: string;
+	readonly relativeDisplay: string; readonly selectable: boolean; readonly size?: number; readonly reason?: string;
+}
+export interface SelectionReceipt {
+	readonly attachmentId: string; readonly state: "sealed"; readonly revision: number;
+}
+export interface SealedOriginal {
+	readonly attachmentId: string; readonly name: string; readonly format: Format;
+	readonly bytes: number; readonly sha256: string;
+}
+type Code = "invalid_picker_input" | "picker_scope_mismatch" | "picker_expired" | "picker_closed" | "invalid_token"
+	| "invalid_cursor" | "operation_conflict" | "entry_disabled" | "host_access_denied" | "file_changed"
+	| "processing_limit" | "invalid_pdf" | "native_protocol" | "seal_conflict";
+export class HostSelectorError extends Error {
+	constructor(readonly code: Code) { super(code); this.name = "HostSelectorError"; }
+}
+function fail(code: Code): never { throw new HostSelectorError(code); }
+function object(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function shape(value: unknown, required: readonly string[], optional: readonly string[] = []): Record<string, unknown> {
+	if (!object(value) || required.some(k => !(k in value)) || Object.keys(value).some(k => !required.includes(k) && !optional.includes(k))) {
+		return fail("native_protocol");
+	}
+	return value;
+}
+function component(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0 && value !== "." && value !== ".." && !/[\/\0]/u.test(value);
+}
+function identity(value: unknown): SourceIdentity {
+	const v = shape(value, ["device", "inode", "size", "mtimeNs", "ctimeNs", "nlink"]);
+	for (const [key, min, max] of [
+		["device", -2147483648n, 2147483647n], ["inode", 0n, 18446744073709551615n],
+		["mtimeNs", -9223372036854775808000000000n, 9223372036854775807999999999n],
+		["ctimeNs", -9223372036854775808000000000n, 9223372036854775807999999999n],
+	] as const) {
+		const n = v[key];
+		if (typeof n !== "string" || !/^(?:0|-?[1-9][0-9]*)$/.test(n) || n.length > 28 || BigInt(n) < min || BigInt(n) > max) fail("native_protocol");
+	}
+	if (typeof v.device !== "string" || typeof v.inode !== "string" || typeof v.mtimeNs !== "string" ||
+		typeof v.ctimeNs !== "string" || typeof v.size !== "number" || !Number.isSafeInteger(v.size) ||
+		v.size < 1 || v.size > MAX || v.nlink !== 1) return fail("native_protocol");
+	return Object.freeze({ device: v.device, inode: v.inode, size: v.size, mtimeNs: v.mtimeNs, ctimeNs: v.ctimeNs, nlink: 1 });
+}
+const sameIdentity = (a: SourceIdentity, b: SourceIdentity) => a.device === b.device && a.inode === b.inode &&
+	a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs && a.nlink === b.nlink;
+function format(name: string): Format | undefined {
+	switch (name.slice(name.lastIndexOf(".") + 1).toLowerCase()) {
+		case "html": case "htm": return "html";
+		case "md": case "markdown": return "md";
+		case "txt": return "txt";
+		case "pdf": return "pdf";
+	}
+}
+function page(value: Record<string, unknown>): NativePage {
+	shape(value, ["requestId", "type", "entries"], ["nextName"]);
+	if (!Array.isArray(value.entries) || value.entries.length > 50 || (value.nextName !== undefined && !component(value.nextName))) return fail("native_protocol");
+	let previous: string | undefined;
+	const entries = value.entries.map((raw: unknown): NativeEntry => {
+		const e = shape(raw, ["name", "kind", "selectable"], ["identity", "reason"]);
+		if (!component(e.name) || (previous !== undefined && Buffer.compare(Buffer.from(previous), Buffer.from(e.name)) >= 0)) return fail("native_protocol");
+		previous = e.name;
+		switch (e.kind) {
+			case "directory":
+				if (e.selectable !== true || e.identity !== undefined || e.reason !== undefined) return fail("native_protocol");
+				return { name: e.name, kind: "directory", selectable: true };
+			case "file":
+				if (e.selectable !== true || !format(e.name) || e.reason !== undefined) return fail("native_protocol");
+				return { name: e.name, kind: "file", selectable: true, identity: identity(e.identity) };
+			case "disabled":
+				if (e.selectable !== false || e.identity !== undefined || typeof e.reason !== "string" || !e.reason) return fail("native_protocol");
+				return { name: e.name, kind: "disabled", selectable: false, reason: e.reason };
+			default: return fail("native_protocol");
+		}
+	});
+	if (value.nextName !== undefined && (entries.length !== 50 || value.nextName !== entries.at(-1)?.name)) fail("native_protocol");
+	return { entries, ...(typeof value.nextName === "string" ? { nextName: value.nextName } : {}) };
+}
+
+/** Private host adapter; callers must supply already-authenticated human scope.
+ * No model tool, HTTP route, parser operation or runtime compiler is registered here. */
+export class NativeSelector {
+	constructor(private readonly executable: string, private readonly env: NodeJS.ProcessEnv = process.env) {}
+	list(location: Location, query: string, showHidden: boolean, afterName?: string, signal?: AbortSignal): Promise<NativePage> {
+		return this.exchange({ operation: "selector.list", root: location.root, segments: location.segments, query, showHidden,
+			...(afterName === undefined ? {} : { afterName }) }, undefined, undefined, signal).then(result => {
+			if (!result.page) return fail("native_protocol");
+			return result.page;
+		});
+	}
+	snapshot(source: SelectedSource, chunk: (bytes: Buffer) => void, signal?: AbortSignal) {
+		return this.exchange({ operation: "selector.snapshot", root: source.root, segments: source.segments,
+			expectedIdentity: source.identity }, source.identity, chunk, signal);
+	}
+	private async exchange(body: Readonly<Record<string, unknown>>, expected?: SourceIdentity,
+		onChunk?: (bytes: Buffer) => void, signal?: AbortSignal): Promise<{ readonly page?: NativePage; readonly bytes: number; readonly sha256: string }> {
+		if (signal?.aborted) return fail("picker_closed");
+		const requestId = randomUUID();
+		const child = Bun.spawn([this.executable], { env: this.env, stdin: new Blob([JSON.stringify({ version: 1, requestId, ...body })]),
+			stdout: "pipe", stderr: "pipe" });
+		let timedOut = false;
+		const timer = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, 60_000);
+		const abort = () => child.kill("SIGKILL");
+		signal?.addEventListener("abort", abort, { once: true });
+		// Drain stderr without retaining native paths or unbounded diagnostics.
+		const stderr = (async () => { for await (const _ of child.stderr) { /* intentionally discard diagnostics */ } })();
+		let total = 0, index = 0, streamBytes = 0;
+		let pending = Buffer.alloc(0);
+		let terminal = false;
+		let listing: NativePage | undefined;
+		let failure: Code | undefined;
+		let sha256 = "";
+		const hash = createHash("sha256");
+		try {
+			for await (const part of child.stdout) {
+				streamBytes += part.length;
+				if (streamBytes > STREAM_MAX) fail("processing_limit");
+				pending = Buffer.concat([pending, part]);
+				let newline: number;
+				while ((newline = pending.indexOf(10)) >= 0) {
+					const line = pending.subarray(0, newline); pending = pending.subarray(newline + 1);
+					if (terminal || line.length === 0) fail("native_protocol");
+					let raw: unknown;
+					try { raw = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(line)); }
+					catch (error) { if (error instanceof SyntaxError || error instanceof TypeError) fail("native_protocol"); throw error; }
+					if (!object(raw) || raw.requestId !== requestId) fail("native_protocol");
+					switch (raw.type) {
+						case "selector.listed":
+							if (expected) fail("native_protocol");
+							listing = page(raw); terminal = true; break;
+						case "chunk": {
+							shape(raw, ["requestId", "type", "index", "base64"]);
+							if (!expected || !onChunk || raw.index !== index++ || typeof raw.base64 !== "string" ||
+								raw.base64.length > 87_384) return fail("native_protocol");
+							const bytes = Buffer.from(raw.base64, "base64");
+							if (!bytes.length || bytes.toString("base64") !== raw.base64) fail("native_protocol");
+							total += bytes.length;
+							if (total > MAX || total > expected.size) fail("processing_limit");
+							hash.update(bytes); onChunk(bytes); break;
+						}
+						case "snapshot.complete":
+							shape(raw, ["requestId", "type", "before", "after", "bytes", "sha256"]);
+							if (!expected || !sameIdentity(identity(raw.before), expected) || !sameIdentity(identity(raw.after), expected) ||
+								total < 1 || raw.bytes !== total || total !== expected.size) fail("file_changed");
+							sha256 = hash.digest("hex");
+							if (raw.sha256 !== sha256) fail("native_protocol");
+							terminal = true; break;
+						case "error":
+							shape(raw, ["requestId", "type", "code"]);
+							switch (raw.code) {
+								case "host_access_denied": case "file_changed": case "processing_limit":
+									failure = raw.code; terminal = true; break;
+								default: fail("native_protocol");
+							}
+							break;
+						default: fail("native_protocol");
+					}
+				}
+			}
+			const exit = await child.exited;
+			if (signal?.aborted) fail("picker_closed");
+			if (timedOut) fail("processing_limit");
+			if (failure) fail(failure);
+			if (exit !== 0 || !terminal || pending.length !== 0) fail("native_protocol");
+			return { ...(listing ? { page: listing } : {}), bytes: total, sha256 };
+		} finally {
+			clearTimeout(timer); signal?.removeEventListener("abort", abort);
+			child.kill(); await child.exited; await stderr;
+		}
+	}
+}
+
+// Darwin RENAME_EXCL is an atomic no-replace rename, unlike node:fs.rename.
+// Retain the library for the lifetime of this module and pass directory descriptors.
+const libc = dlopen("/usr/lib/libSystem.B.dylib", {
+	renameatx_np: { args: ["i32", "cstring", "i32", "cstring", "u32"], returns: "i32" },
+});
+const errorCode = (error: unknown) => error instanceof Error && "code" in error ? error.code : undefined;
+// A failed seal keeps no source bytes. An original published by another writer stays.
+function discard(directory: string) {
+	try { unlinkSync(join(directory, ".partial")); }
+	catch (error) { if (errorCode(error) !== "ENOENT") throw error; }
+	try { rmdirSync(directory); }
+	catch (error) { if (errorCode(error) !== "ENOTEMPTY") throw error; }
+}
+export async function sealOriginal(runtimeHome: string, attachmentId: string, source: SelectedSource,
+	native: NativeSelector, signal?: AbortSignal, beforePublish: () => void = () => undefined): Promise<SealedOriginal> {
+	if (!UUID.test(attachmentId)) return fail("invalid_picker_input");
+	const base = join(runtimeHome, "attachments");
+	try { mkdirSync(base, { mode: 0o700 }); }
+	catch (error) { if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error; }
+	const stat = lstatSync(base);
+	if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o777) !== 0o700) fail("seal_conflict");
+	const directory = join(base, attachmentId);
+	try { mkdirSync(directory, { mode: 0o700 }); }
+	catch (error) { if (error instanceof Error && "code" in error && error.code === "EEXIST") fail("seal_conflict"); throw error; }
+	const dir = openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+	let file: number | undefined;
+	let published = false;
+	try {
+		file = openSync(join(directory, ".partial"), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+		fchmodSync(file, 0o600);
+		const descriptor = file;
+		let bytes = 0; let prefix = Buffer.alloc(0);
+		const hash = createHash("sha256");
+		const result = await native.snapshot(source, chunk => {
+			bytes += chunk.length;
+			if (bytes > MAX) fail("processing_limit");
+			if (prefix.length < 5) prefix = Buffer.concat([prefix, chunk]).subarray(0, 5);
+			hash.update(chunk);
+			let offset = 0;
+			while (offset < chunk.length) {
+				const written = writeSync(descriptor, chunk, offset, chunk.length - offset);
+				if (written <= 0) fail("host_access_denied");
+				offset += written;
+			}
+		}, signal);
+		if (bytes < 1 || bytes > MAX || result.bytes !== bytes || result.sha256 !== hash.digest("hex")) fail("file_changed");
+		if (source.format === "pdf" && !prefix.equals(Buffer.from("%PDF-"))) fail("invalid_pdf");
+		fsyncSync(file); closeSync(file); file = undefined;
+		// Synchronous check and rename form the publication boundary: no await gap.
+		if (signal?.aborted) fail("picker_closed");
+		beforePublish();
+		if (libc.symbols.renameatx_np(dir, Buffer.from(".partial\0"), dir, Buffer.from("original\0"), 0x00000004) !== 0) fail("seal_conflict");
+		published = true;
+		fsyncSync(dir);
+		return Object.freeze({ attachmentId, name: source.name, format: source.format, bytes, sha256: result.sha256 });
+	} finally {
+		if (file !== undefined) closeSync(file);
+		closeSync(dir);
+		if (!published) discard(directory);
+	}
+}
+
+interface Handle extends Location { readonly row: NativeEntry; readonly parent?: string }
+interface PickerRecord {
+	readonly scopeKey: string; readonly scope: PickerScope; readonly handles: Map<string, Handle>;
+	readonly cursors: Map<string, { readonly token: string; readonly query: string; readonly hidden: boolean; readonly after: string }>;
+	readonly abort: AbortController; closed: boolean; touched: number;
+}
+const scopeKey = (s: PickerScope) => JSON.stringify([s.ownerPrincipal, s.principalRevision, s.draftId, s.convId,
+	s.convEpoch, s.recipient.kind, s.recipient.id, s.recipient.epoch, s.generation]);
+interface Options {
+	readonly native: NativeSelector; readonly runtimeHome: string; readonly generation: string;
+	readonly current: (scope: PickerScope) => boolean; readonly now?: () => number;
+}
+/** Maps are process-generation scoped. T6 owns HTTP authentication and durable T2
+ * operation/CAS integration. resolveSelection + sealOriginal allow T2's allocated
+ * UUID to be sealed without a second snapshot or a second authorization system. */
+export class HostPicker {
+	private readonly pickers = new Map<string, PickerRecord>();
+	private readonly operations = new Map<string, { readonly fingerprint: string; readonly result: Promise<SelectionReceipt> }>();
+	constructor(private readonly options: Options) {}
+	private now() { return (this.options.now ?? Date.now)(); }
+	private scope(s: PickerScope) {
+		if (!s.ownerPrincipal || !UUID.test(s.draftId) || !s.convId || !s.recipient.id ||
+			!["main", "agent"].includes(s.recipient.kind) || ![s.principalRevision, s.convEpoch, s.recipient.epoch].every(n => Number.isSafeInteger(n) && n > 0) ||
+			s.generation !== this.options.generation || !this.options.current(s)) fail("picker_scope_mismatch");
+	}
+	private picker(s: PickerScope, id: string, retry = false) {
+		this.scope(s);
+		const p = this.pickers.get(id);
+		if (!p || p.scopeKey !== scopeKey(s)) return fail("picker_scope_mismatch");
+		if (!retry && p.closed) fail("picker_closed");
+		if (!retry && this.now() - p.touched >= 15 * 60_000) { p.abort.abort(); fail("picker_expired"); }
+		if (!retry) p.touched = this.now();
+		return p;
+	}
+	async create(s: PickerScope) {
+		this.scope(s);
+		const scope = Object.freeze({ ...s, recipient: Object.freeze({ ...s.recipient }) });
+		const p: PickerRecord = { scope, scopeKey: scopeKey(s), handles: new Map(), cursors: new Map(),
+			abort: new AbortController(), closed: false, touched: this.now() };
+		const pickerId = randomUUID();
+		const roots = (["home", "computer", "downloads"] as const).map(root => {
+			const name = root.charAt(0).toUpperCase() + root.slice(1);
+			const token = randomUUID();
+			p.handles.set(token, { root, segments: [], row: { name, kind: "directory", selectable: true } });
+			return { entryToken: token, kind: "directory" as const, name, relativeDisplay: name, selectable: true };
+		});
+		const home = roots[0], downloads = roots[2];
+		if (!home || !downloads) return fail("native_protocol");
+		let currentDirectoryToken = downloads.entryToken;
+		try { await this.options.native.list({ root: "downloads", segments: [] }, "", false, undefined, p.abort.signal); }
+		catch (error) {
+			if (!(error instanceof HostSelectorError) || error.code !== "host_access_denied") throw error;
+			await this.options.native.list({ root: "home", segments: [] }, "", false, undefined, p.abort.signal);
+			currentDirectoryToken = home.entryToken;
+		}
+		this.scope(s);
+		this.evict(s.ownerPrincipal);
+		this.pickers.set(pickerId, p);
+		return { pickerId, rootEntries: roots, currentDirectoryToken, revision: 1 };
+	}
+	async list(s: PickerScope, id: string, input: unknown) {
+		const p = this.picker(s, id);
+		if (!object(input) || Object.keys(input).some(k => !["directoryToken", "cursor", "query", "showHidden"].includes(k)) ||
+			typeof input.directoryToken !== "string" || (input.cursor !== undefined && typeof input.cursor !== "string") ||
+			(input.query !== undefined && (typeof input.query !== "string" || [...input.query].length > 200)) ||
+			(input.showHidden !== undefined && typeof input.showHidden !== "boolean")) return fail("invalid_picker_input");
+		const token = input.directoryToken;
+		const handle = p.handles.get(token);
+		if (!handle || handle.row.kind !== "directory") return fail("invalid_token");
+		const query = typeof input.query === "string" ? input.query : "", hidden = input.showHidden === true;
+		const cursor = typeof input.cursor === "string" ? p.cursors.get(input.cursor) : undefined;
+		if (input.cursor !== undefined && (!cursor || cursor.token !== token || cursor.query !== query || cursor.hidden !== hidden)) fail("invalid_cursor");
+		const result = await this.options.native.list(handle, query, hidden, cursor?.after, p.abort.signal);
+		this.picker(s, id);
+		if (p.handles.size + result.entries.length > MAX_HANDLES || p.cursors.size >= MAX_HANDLES) fail("picker_expired");
+		const entries = result.entries.map(row => {
+			const entryToken = randomUUID();
+			p.handles.set(entryToken, { root: handle.root, segments: [...handle.segments, row.name], row, parent: token });
+			return { entryToken, kind: row.kind, name: row.name, relativeDisplay: [...handle.segments, row.name].join("/"),
+				selectable: row.selectable, ...(row.identity ? { size: row.identity.size } : {}), ...(row.reason ? { reason: row.reason } : {}) };
+		});
+		let nextCursor: string | undefined;
+		if (result.nextName) {
+			nextCursor = randomUUID();
+			p.cursors.set(nextCursor, { token, query, hidden, after: result.nextName });
+		}
+		return { entries, ...(handle.parent ? { parentToken: handle.parent } : {}), ...(nextCursor ? { nextCursor } : {}) };
+	}
+	resolveSelection(s: PickerScope, id: string, token: string, retry = false): SelectedSource {
+		const p = this.picker(s, id, retry);
+		return this.selected(p, token);
+	}
+	/** The scope this principal opened the picker with; no other principal learns that it exists. */
+	scopeOf(ownerPrincipal: string, id: string): PickerScope {
+		const p = this.pickers.get(id);
+		if (!p || p.scope.ownerPrincipal !== ownerPrincipal) return fail("picker_scope_mismatch");
+		return p.scope;
+	}
+	/** Records live only for this process; expired ones go first and a principal keeps a bounded number. */
+	private evict(ownerPrincipal: string): void {
+		const mine: string[] = [];
+		for (const [id, p] of this.pickers) {
+			if (this.now() - p.touched >= 15 * 60_000) { p.abort.abort(); this.pickers.delete(id); }
+			else if (p.scope.ownerPrincipal === ownerPrincipal) mine.push(id);
+		}
+		for (const id of mine.slice(0, Math.max(0, mine.length - (MAX_PICKERS - 1)))) {
+			this.pickers.get(id)?.abort.abort();
+			this.pickers.delete(id);
+		}
+	}
+	private selected(p: PickerRecord, token: string): SelectedSource {
+		const handle = p.handles.get(token);
+		if (!handle) return fail("invalid_token");
+		const f = format(handle.row.name);
+		if (handle.row.kind !== "file" || !handle.row.selectable || !handle.row.identity || !f) return fail("entry_disabled");
+		return Object.freeze({ root: handle.root, segments: Object.freeze([...handle.segments]),
+			name: handle.row.name, format: f, identity: handle.row.identity });
+	}
+	async select(s: PickerScope, id: string, input: unknown): Promise<SelectionReceipt> {
+		if (!object(input) || Object.keys(input).some(k => !["entryToken", "operationId", "pickerId"].includes(k)) ||
+			typeof input.entryToken !== "string" || typeof input.operationId !== "string" || !UUID.test(input.operationId)) return fail("invalid_picker_input");
+		const p = this.picker(s, id, true);
+		const source = this.selected(p, input.entryToken);
+		const key = JSON.stringify([s.ownerPrincipal, s.draftId, input.operationId]);
+		const fingerprint = JSON.stringify([scopeKey(s), source]);
+		const existing = this.operations.get(key);
+		if (existing) {
+			if (existing.fingerprint !== fingerprint) fail("operation_conflict");
+			return existing.result;
+		}
+		this.picker(s, id);
+		const attachmentId = randomUUID();
+		const result = sealOriginal(this.options.runtimeHome, attachmentId, source, this.options.native, p.abort.signal,
+			() => { this.picker(s, id); }).then((): SelectionReceipt => Object.freeze({ attachmentId, state: "sealed", revision: 1 }));
+		this.operations.set(key, { fingerprint, result });
+		return result;
+	}
+	close(s: PickerScope, id: string) {
+		const p = this.picker(s, id, true); p.closed = true; p.abort.abort();
+	}
+}

package/src/attachments/managed-binding.ts

@@ -0,0 +1,83 @@
+import { createSecretKey, randomBytes, randomUUID, type KeyObject } from "node:crypto";
+import {
+	sameManagedCallIdentity, type ManagedCallBinding, type ManagedCallBindingResolver, type ManagedCallIdentity,
+	type VerifiedManagedCall,
+} from "../agent/managed-call.ts";
+import type { StoredEvent } from "../store.ts";
+
+export interface ManagedSession {
+	readonly role: "main" | "agent";
+	readonly agentId: string | null;
+	readonly convId: string;
+	readonly convEpoch: number;
+	readonly lifecycleEpoch: number;
+	readonly sessionPath: string;
+	readonly durableSessionId: string;
+}
+interface Live {
+	readonly session: ManagedSession;
+	readonly incarnation: string;
+	readonly secret: KeyObject;
+	readonly live: () => boolean;
+	readonly nonces: Set<string>;
+	inputId: string | null;
+	inputSeq: number | null;
+}
+interface InputLedger {
+	getEvent(seq: number): StoredEvent | null;
+	mainInputConsumed(input: StoredEvent): boolean;
+}
+const NONCE_LIMIT = 65_536;
+export const attachmentReadCall = (toolCallId: string) => `attachment-read:${toolCallId}`;
+export const attachmentDocumentCall = (toolCallId: string) => `attachment-document:${toolCallId}`;
+
+/**
+ * Gateway custody of per-session secrets and call nonces. Each bind rotates the secret, so a
+ * reconnect, rotation or gateway restart can never reuse an earlier incarnation's proof.
+ */
+export class ManagedBindings {
+	readonly generation = randomUUID();
+	private readonly byConv = new Map<string, Live>();
+	constructor(private readonly inputs: InputLedger) {}
+
+	bind(session: ManagedSession, live: () => boolean): { secret: string; identity: Omit<ManagedCallIdentity, "inputId" | "toolCallId" | "logicalCallId"> } {
+		const raw = randomBytes(32), incarnation = randomUUID();
+		this.byConv.set(session.convId, { session, incarnation, secret: createSecretKey(raw), live, nonces: new Set(), inputId: null, inputSeq: null });
+		return { secret: raw.toString("hex"), identity: { ...session, sessionIncarnation: incarnation, gatewayGeneration: this.generation, activationId: null } };
+	}
+	setInput(convId: string, incarnation: string, inputId: string, inputSeq: number): void {
+		const record = this.byConv.get(convId);
+		if (record?.incarnation !== incarnation) return;
+		record.inputId = inputId;
+		record.inputSeq = inputSeq;
+	}
+	retire(convId: string): void { this.byConv.delete(convId); }
+
+	private expected(record: Live, identity: ManagedCallIdentity): ManagedCallIdentity | null {
+		const document = identity.logicalCallId === attachmentDocumentCall(identity.toolCallId);
+		if (!record.live() || record.inputId === null || record.inputSeq === null || identity.inputId !== record.inputId ||
+			(!document && identity.logicalCallId !== attachmentReadCall(identity.toolCallId))) return null;
+		const input = this.inputs.getEvent(record.inputSeq);
+		// The engine resolves a document before the consumed event reaches the gateway; the input is still this session's admitted one.
+		if (input === null || (!document && !this.inputs.mainInputConsumed(input))) return null;
+		return { ...record.session, sessionIncarnation: record.incarnation, gatewayGeneration: this.generation,
+			inputId: record.inputId, toolCallId: identity.toolCallId, logicalCallId: identity.logicalCallId, activationId: null };
+	}
+	readonly resolver: ManagedCallBindingResolver = (identity): ManagedCallBinding | null => {
+		const record = this.byConv.get(identity.convId);
+		if (!record) return null;
+		const expected = this.expected(record, identity);
+		if (!expected) return null;
+		return { identity: expected, secret: record.secret, claimNonce: nonce => {
+			if (record.nonces.has(nonce) || record.nonces.size >= NONCE_LIMIT) return false;
+			record.nonces.add(nonce);
+			return true;
+		} };
+	};
+	/** Final check before content release: a newer input or rebind makes this call stale. */
+	isCurrent(call: VerifiedManagedCall): boolean {
+		const record = this.byConv.get(call.convId);
+		const expected = record && this.expected(record, call);
+		return !!expected && sameManagedCallIdentity(expected, call);
+	}
+}