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

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

@@ -0,0 +1,385 @@
+import { createHash, createSecretKey, randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isDeepStrictEqual } from "node:util";
+import { collaborationDigest, type CollaborationBinding } from "../../src/agent/collaboration-types.ts";
+import { parseManagedCallIdentity, type ManagedCallIdentity, type ManagedCallProof, type ManagedCallRequest } from "../../src/agent/managed-call.ts";
+import { runtimePaths } from "../../src/runtime/paths.ts";
+import { buildManagedCallProof, type ManagedNativeContext } from "./managed-call.ts";
+export { CollaborationSnapshots } from "./agent-collaboration-files.ts";
+
+export type SnapshotCall = { readonly requestId: string; readonly requestRevision: number; readonly operationKey: string; readonly bindingDigest: string; readonly paths: readonly string[] };
+export type SnapshotTicket = { readonly operationKey: string; readonly requestId: string; readonly requestRevision: number; readonly binding: CollaborationBinding };
+export type SealedOutput = { readonly path: string; readonly sealedName: string; readonly sha256: string; readonly bytes: number; readonly mediaType: string; readonly name: string };
+export type SnapshotError = "invalid_snapshot" | "snapshot_conflict" | "binding_conflict" | "request_blocked" | "read_only_continuation" |
+	"agent_knowledge_locked" | "snapshot_not_quiescent" | "file_not_found" | "file_changed" | "file_not_regular" | "file_linked" |
+	"path_forbidden" | "file_too_large" | "snapshot_io_failed" | "snapshot_unknown";
+export type SnapshotResult = { readonly ok: true; readonly snapshotKey: string; readonly requestId: string; readonly bindingDigest: string; readonly files: readonly SealedOutput[] } |
+	{ readonly ok: false; readonly error: SnapshotError };
+export interface SnapshotPort { snapshot(requestId: string, paths: readonly string[]): Promise<SnapshotResult> }
+export interface CollaborationInvocation extends ManagedCallRequest { readonly proof: ManagedCallProof; readonly signal?: AbortSignal; readonly contentType?: string }
+export type StageFile = { readonly bytes: Uint8Array; readonly path: string; readonly name: string; readonly mediaType: string };
+export interface CollaborationTool {
+	readonly name: string; readonly label: string; readonly description: string; readonly parameters: unknown;
+	readonly serverPinned?: boolean;
+	execute(id: string, params: Record<string, unknown>, signal: AbortSignal | undefined, update: unknown, ctx: unknown): Promise<unknown>;
+}
+export interface CollaborationApi {
+	readonly sessionKind: string; readonly sessionContext: Readonly<Record<string, string>>;
+	readonly rpc: { handle(name: string, handler: (data: unknown) => unknown): void };
+	registerTool(tool: CollaborationTool): void;
+}
+type Native = ManagedNativeContext & { readonly sessionManager: ManagedNativeContext["sessionManager"] & { getEntries(): readonly unknown[] } };
+type Bound = {
+	readonly identity: ManagedCallIdentity; readonly binding: CollaborationBinding;
+	readonly requestId: string | null; readonly rootId: string | null; readonly secret: ReturnType<typeof createSecretKey>;
+	readonly read: Readonly<Record<string, unknown>> | null;
+	readonly inputEvidence: "native_event" | "client_entry";
+	readonly reservationId?: string;
+};
+export class CollaborationExtensionError extends Error {
+	constructor(readonly code: string) { super(code); this.name = "CollaborationExtensionError"; }
+}
+export const record = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === "object" && !Array.isArray(v);
+const text = (v: unknown): v is string => typeof v === "string" && v.length > 0;
+const integer = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+const fail = (code: string): never => { throw new CollaborationExtensionError(code); };
+/** The SDK is a runtime boundary; retain its guarded getters and original manager, never a cloned context. */
+function isNative(value: unknown): value is Native {
+	if (!record(value) || !record(value.sessionManager)) return false;
+	const manager = value.sessionManager;
+	return typeof manager.getSessionId === "function" && typeof manager.getSessionFile === "function" && typeof manager.getEntries === "function";
+}
+function native(value: unknown): Native { return isNative(value) ? value : fail("native_context_mismatch"); }
+const string = { type: "string", minLength: 1 };
+const strings = { type: "array", items: string, maxItems: 10, uniqueItems: true };
+const specs = {
+	request: { fields: { agentId: string, kind: { enum: ["task", "question"] }, text: string, files: strings, retryOf: string }, required: ["agentId", "kind", "text"] },
+	result: { fields: { requestId: string, status: { enum: ["completed", "failed"] }, text: string, outputs: strings }, required: ["requestId", "status", "text"] },
+	requests: { fields: { requestId: string }, required: [] },
+	cancel: { fields: { requestId: string, expectedRevision: { type: "integer", minimum: 0 }, reason: string }, required: ["requestId", "expectedRevision", "reason"] },
+	files: { fields: { operation: { enum: ["stage", "list", "read"] }, agentId: string, path: string, attachmentId: string,
+		scopedArtifact: { type: "object", properties: { requestId: string, artifactId: string }, required: ["requestId", "artifactId"], additionalProperties: false },
+		requestId: string, artifactId: string, view: { enum: ["text", "pages"] }, cursor: string, limit: { type: "integer", minimum: 1 } }, required: ["operation"] },
+} as const;
+type Operation = keyof typeof specs;
+const OPERATIONS = ["request", "result", "requests", "cancel", "files"] as const;
+export const COLLABORATION_TOOLS = OPERATIONS.map(name => `zgw_agent_${name}`);
+function payload(operation: Operation, p: Record<string, unknown>): void {
+	const spec = specs[operation];
+	if (Object.keys(p).some(k => !Object.hasOwn(spec.fields, k)) || spec.required.some(k => !Object.hasOwn(p, k))) fail("invalid_payload");
+	for (const [key, value] of Object.entries(p)) {
+		if (["files", "outputs"].includes(key)) {
+			if (!Array.isArray(value) || value.length > 10 || !value.every(text) || new Set(value).size !== value.length) fail("invalid_payload");
+		} else if (["expectedRevision", "limit"].includes(key)) {
+			if (!integer(value) || (key === "limit" && value === 0)) fail("invalid_payload");
+		} else if (key === "scopedArtifact") {
+			if (!record(value) || Object.keys(value).length !== 2 || !text(value.requestId) || !text(value.artifactId)) fail("invalid_payload");
+		} else if (!text(value)) fail("invalid_payload");
+	}
+	if (typeof p.text === "string" && Buffer.byteLength(p.text) > 65536) fail("payload_too_large");
+	if (operation === "request" && p.kind !== "task" && p.kind !== "question") fail("invalid_payload");
+	if (operation === "result" && p.status !== "completed" && p.status !== "failed") fail("invalid_payload");
+	if (operation !== "files") return;
+	const fields = p.operation === "stage" ? ["operation", "agentId", "path", "attachmentId", "scopedArtifact"] :
+		p.operation === "list" ? ["operation", "requestId"] : p.operation === "read" ? ["operation", "requestId", "artifactId", "view", "cursor", "limit"] : [];
+	if (Object.keys(p).some(k => !fields.includes(k))) fail("invalid_payload");
+	switch (p.operation) {
+		case "stage": if (!text(p.agentId) || ["path", "attachmentId", "scopedArtifact"].filter(k => Object.hasOwn(p, k)).length !== 1) fail("invalid_payload"); break;
+		case "list": if (!text(p.requestId)) fail("invalid_payload"); break;
+		case "read": if (!text(p.requestId) || !text(p.artifactId) || (p.view !== undefined && p.view !== "text" && p.view !== "pages")) fail("invalid_payload"); break;
+		default: fail("invalid_payload");
+	}
+}
+async function transport(call: CollaborationInvocation): Promise<unknown> {
+	const token = readFileSync(runtimePaths().omoTokenFile, "utf8").trim();
+	const base = process.env.ZGW_WORK_URL ?? `http://127.0.0.1:${process.env.ZGW_PORT ?? "8700"}`;
+	const response = await fetch(new URL(call.route, base), { method: call.method, redirect: "error",
+		headers: { authorization: `Bearer ${token}`, "content-type": call.contentType ?? "application/json", "x-zgw-managed-proof": JSON.stringify(call.proof) },
+		...(call.method === "GET" ? {} : { body: Buffer.from(call.body) }),
+		signal: call.signal ? AbortSignal.any([call.signal, AbortSignal.timeout(15000)]) : AbortSignal.timeout(15000) });
+	// Only 200 carries artifact bytes; a held read answers 202 with its JSON receipt.
+	if (response.status === 200 && call.method === "GET") {
+		const bytes = Buffer.from(await response.arrayBuffer());
+		return { artifactId: response.headers.get("x-zgw-artifact-id"), requestId: response.headers.get("x-zgw-request-id"),
+			bytes: bytes.length, sha256: createHash("sha256").update(bytes).digest("hex"),
+			preview: bytes.subarray(0, 32768).toString("utf8"), truncated: bytes.length > 32768 };
+	}
+	const result: unknown = await response.json();
+	if (!response.ok) fail(`collaboration_http_${response.status}`);
+	return result;
+}
+/** One controller per actual extension API. Public metadata selects registration, never authority. */
+const registrations = new WeakMap<object, CollaborationControl>();
+export function registerAgentCollaboration(api: CollaborationApi, send: (call: CollaborationInvocation) => Promise<unknown> = transport): CollaborationControl | undefined {
+	const role = api.sessionContext.zgw_role;
+	if (api.sessionKind !== "interactive" || (role !== "main" && role !== "agent") || (role === "agent" && !api.sessionContext.zgw_agent)) return;
+	const existing = registrations.get(api);
+	if (existing) return existing;
+	const control = new CollaborationControl(role, send);
+	registrations.set(api, control);
+	api.rpc.handle("zgw.agent_collaboration_identity", () => control.identity());
+	api.rpc.handle("zgw.agent_collaboration_runtime", () => control.runtimeInfo());
+	api.rpc.handle("zgw.agent_collaboration_bind", data => control.bind(data));
+	api.rpc.handle("zgw.agent_collaboration_reservation", data => control.reservation(data));
+	api.rpc.handle("zgw.agent_collaboration_revoke", () => { control.revoke(); return { revoked: true }; });
+	api.rpc.handle("zgw.agent_snapshot", data => control.takeSnapshot(data));
+	for (const op of OPERATIONS) {
+		const spec = specs[op];
+		api.registerTool({ name: `zgw_agent_${op}`, label: `Agent ${op}`, description: `Submit or inspect an explicitly bound collaboration ${op}.`,
+			parameters: { type: "object", properties: spec.fields, required: spec.required, additionalProperties: false },
+			execute: (id, params, signal, _update, ctx) => control.execute({ id, params, signal, ctx, operation: op }) });
+	}
+	return control;
+}
+// allow: SIZE_OK - T5 may only extend HTTP/path-stage consumption here; moving the T4 capability lifecycle is outside its ownership.
+/** State changes retire the exact captured capability, including calls already waiting in a file queue. */
+export class CollaborationControl {
+	private stageFile: ((path: string, ctx: unknown, signal: AbortSignal | undefined) => Promise<StageFile>) | undefined;
+	installStage(handler: (path: string, ctx: unknown, signal: AbortSignal | undefined) => Promise<StageFile>): void { this.stageFile = handler; }
+	private runtime: Native | undefined;
+	private bound: Bound | undefined;
+	private consumed = false;
+	private consumedEntry: string | undefined;
+	private readonly retiredClientInputs = new Set<string>();
+	private readonly reservations = new Map<string, { readonly identity: ManagedCallIdentity; readonly bound: Bound; state: "reserved" | "armed" | "released" }>();
+	private readonly releasedInputs = new Map<string, ManagedCallIdentity>();
+	private retiredPeer = false;
+	private snapshotHandler: ((data: unknown) => Promise<SnapshotResult>) | undefined;
+	private fileActivity = () => 0;
+	private frozen: { readonly operationKey: string; readonly payloadSha: string; readonly paths: readonly string[] } | undefined;
+	private snapshot = { definitionSha: "", fingerprint: "" };
+	constructor(readonly role: "main" | "agent", private readonly send: (call: CollaborationInvocation) => Promise<unknown>) {}
+	installSnapshots(handler: (data: unknown) => Promise<SnapshotResult>, activity: () => number): void { this.snapshotHandler = handler; this.fileActivity = activity; }
+	takeSnapshot(data: unknown): Promise<SnapshotResult> {
+		return this.snapshotHandler ? this.snapshotHandler(data) : Promise.resolve({ ok: false, error: "snapshot_not_quiescent" });
+	}
+	start(ctx: unknown): void { this.revoke(); this.runtime = native(ctx); }
+	applied(snapshot: { readonly definitionSha: string; readonly fingerprint: string }): void { this.snapshot = Object.freeze({ ...snapshot }); }
+	runtimeInfo() {
+		const ctx = this.runtime;
+		const model = ctx && "model" in ctx && record(ctx.model) ? ctx.model : undefined;
+		return { ...this.snapshot, ownedInFlight: this.fileActivity(), model: model && { provider: model.provider, modelId: model.id },
+			thinking: ctx && "thinkingLevel" in ctx ? ctx.thinkingLevel : undefined };
+	}
+	identity() { return this.bound ? { ...this.bound.identity, appliedSha: this.snapshot.definitionSha, snapshotFingerprint: this.snapshot.fingerprint,
+		consumed: this.consumed, inputEntryId: this.consumedEntry, ownedInFlight: this.fileActivity() } : null; }
+	bind(data: unknown) {
+		const runtime = this.runtime;
+		if (!runtime || !record(data) || !record(data.binding) || !text(data.secret) || !/^[a-f0-9]{64}$/.test(data.secret) ||
+			!(data.requestId === null || text(data.requestId)) || !(data.rootId === null || text(data.rootId))) return fail("invalid_binding");
+		const identity = parseManagedCallIdentity(data.identity);
+		const reservationId = data.reservationId;
+		if (reservationId !== undefined && (!text(reservationId) || this.reservations.has(reservationId))) return fail("binding_conflict");
+		const reusable = this.releasedInputs.get(identity.inputId);
+		if (reusable && (!text(reservationId) || !isDeepStrictEqual(reusable, identity))) return fail("binding_conflict");
+		if (data.inputEvidence !== undefined && data.inputEvidence !== "client_entry") return fail("invalid_binding");
+		if (data.inputEvidence === "client_entry" && (this.retiredClientInputs.has(identity.inputId) ||
+			this.bound?.identity.inputId === identity.inputId)) return fail("binding_conflict");
+		const b = data.binding;
+		if (data.inputEvidence === "client_entry" && (identity.activationId !== null || b.readContinuationId !== undefined) &&
+			!text(reservationId)) return fail("reservation_required");
+		if (reservationId !== undefined && (data.inputEvidence !== "client_entry" ||
+			(identity.activationId === null && b.readContinuationId === undefined))) return fail("invalid_binding");
+		if (identity.role !== this.role || identity.sessionPath !== runtime.sessionManager.getSessionFile() ||
+			identity.durableSessionId !== runtime.sessionManager.getSessionId()) return fail("native_context_mismatch");
+		for (const key of ["convId", "agentId", "lifecycleEpoch", "inputId", "activationId", "sessionPath", "durableSessionId", "gatewayGeneration"] as const) {
+			if (identity[key] !== b[key]) return fail("binding_conflict");
+		}
+		if (!text(b.definitionSha) || b.definitionSha !== this.snapshot.definitionSha) return fail("version_conflict");
+		if (!integer(b.ownerInputRevision) || (b.readContinuationId !== undefined && !text(b.readContinuationId))) return fail("invalid_binding");
+		if (b.readContinuationId !== undefined) {
+			if (!record(data.read) || data.read.operation !== "read") return fail("invalid_binding");
+			payload("files", data.read);
+		}
+		const binding: CollaborationBinding = Object.freeze({ convId: identity.convId, agentId: identity.agentId, lifecycleEpoch: identity.lifecycleEpoch,
+			inputId: identity.inputId, activationId: identity.activationId, sessionPath: identity.sessionPath, durableSessionId: identity.durableSessionId,
+			gatewayGeneration: identity.gatewayGeneration, definitionSha: b.definitionSha, ownerInputRevision: b.ownerInputRevision,
+			...(typeof b.readContinuationId === "string" ? { readContinuationId: b.readContinuationId } : {}) });
+		this.revoke();
+		this.retiredPeer = false;
+		this.bound = Object.freeze({ identity, binding, requestId: data.requestId, rootId: data.rootId,
+			read: record(data.read) ? Object.freeze(structuredClone(data.read)) : null, secret: createSecretKey(Buffer.from(data.secret, "hex")),
+			inputEvidence: data.inputEvidence === "client_entry" ? "client_entry" : "native_event",
+			...(text(reservationId) ? { reservationId } : {}) });
+		if (text(reservationId)) {
+			this.reservations.set(reservationId, { identity, bound: this.bound, state: "reserved" });
+			this.releasedInputs.delete(identity.inputId);
+		}
+		return this.identity();
+	}
+	/** Only an exact, unarmed reservation can be released. An empty transcript is not enough. */
+	reservation(data: unknown) {
+		if (!record(data) || !text(data.reservationId) || !this.runtime) return fail("reservation_conflict");
+		const saved = this.reservations.get(data.reservationId);
+		const identity = parseManagedCallIdentity(data.identity);
+		if (!saved || !isDeepStrictEqual(saved.identity, identity) || identity.sessionPath !== this.runtime.sessionManager.getSessionFile() ||
+			identity.durableSessionId !== this.runtime.sessionManager.getSessionId()) return fail("reservation_conflict");
+		switch (data.action) {
+			case "arm":
+				if (saved.state !== "reserved" || this.bound !== saved.bound || this.retiredClientInputs.has(identity.inputId)) return fail("reservation_conflict");
+				saved.state = "armed";
+				return { inputId: identity.inputId, state: saved.state };
+			case "release":
+				if (saved.state !== "reserved") return fail("reservation_conflict");
+				if (this.runtime.sessionManager.getEntries().some(entry => record(entry) && entry.type === "message" &&
+					record(entry.message) && entry.message.clientInputId === identity.inputId)) return fail("reservation_conflict");
+				if (this.bound === saved.bound) this.revoke();
+				saved.state = "released";
+				this.releasedInputs.set(identity.inputId, identity);
+				this.retiredClientInputs.delete(identity.inputId);
+				return { inputId: identity.inputId, state: saved.state };
+			default: return fail("reservation_conflict");
+		}
+	}
+	input(event: unknown): boolean {
+		if (this.bound?.inputEvidence === "client_entry" && !this.consumed) return this.isPeer();
+		if (record(event) && this.bound && event.inputId === this.bound.identity.inputId) { this.consumed = true; return true; }
+		this.revoke(); this.retiredPeer = false; return false;
+	}
+	revoke(): void {
+		if (this.bound?.inputEvidence === "client_entry") this.retiredClientInputs.add(this.bound.identity.inputId);
+		this.retiredPeer = this.isPeer(); this.bound = undefined; this.consumed = false; this.consumedEntry = undefined; this.frozen = undefined;
+	}
+	settle(): void { this.revoke(); }
+	/** Tool admission runs after native persisted the real input and assistant tool call. */
+	observeClientInput(): void {
+		const bound = this.bound, runtime = this.runtime;
+		if (!bound || bound.inputEvidence !== "client_entry" || !runtime) return;
+		const manager = runtime.sessionManager;
+		if (!("getLeafId" in manager) || typeof manager.getLeafId !== "function") return fail("native_context_mismatch");
+		let cursor: unknown = manager.getLeafId();
+		const entries = new Map(manager.getEntries().filter(record).map(entry => [entry.id, entry]));
+		const seen = new Set<string>();
+		while (text(cursor) && !seen.has(cursor)) {
+			seen.add(cursor);
+			const entry = entries.get(cursor);
+			if (!entry) break;
+			if (entry.type === "message" && record(entry.message) && entry.message.role === "user") {
+				if (entry.message.clientInputId !== bound.identity.inputId || !text(entry.id)) return fail("native_input_mismatch");
+				this.consumed = true; this.consumedEntry = entry.id; return;
+			}
+			cursor = entry.parentId;
+		}
+		return fail("native_input_mismatch");
+	}
+	capture() {
+		const bound = this.bound;
+		if (!bound || !this.consumed) return fail("binding_missing");
+		this.assertReservationArmed();
+		return { ...bound, assertCurrent: () => {
+			if (this.bound !== bound || !this.consumed) fail("binding_missing");
+		}, assertWritable: () => {
+			if (this.bound !== bound || !this.consumed) fail("binding_missing");
+			if (bound.binding.readContinuationId) fail("read_only_continuation");
+			if (this.frozen) fail("request_blocked");
+		} };
+	}
+	captureNative(ctx: unknown) {
+		if (native(ctx).sessionManager !== this.runtime?.sessionManager) return fail("native_context_mismatch");
+		return this.capture();
+	}
+	isPeer(): boolean { return this.retiredPeer || Boolean(this.bound?.identity.activationId || this.bound?.binding.readContinuationId); }
+	private assertReservationArmed(): void {
+		if (this.bound?.reservationId && this.reservations.get(this.bound.reservationId)?.state !== "armed") fail("binding_unarmed");
+	}
+	assertGeneralTool(): void {
+		if (this.retiredPeer && !this.bound) fail("binding_missing");
+		this.assertReservationArmed();
+		if (this.bound?.binding.readContinuationId) fail("read_only_continuation");
+		if (this.frozen) fail("request_blocked");
+	}
+	snapshotCapture(call: SnapshotCall) {
+		const captured = this.capture(), frozen = this.frozen;
+		if (!frozen || call.requestId !== captured.requestId || call.operationKey !== frozen.operationKey ||
+			call.bindingDigest !== collaborationDigest(captured.binding)) return fail("binding_conflict");
+		if (!integer(call.requestRevision) || !isDeepStrictEqual(call.paths, frozen.paths)) return fail("snapshot_conflict");
+		if (captured.binding.readContinuationId) return fail("read_only_continuation");
+		return captured;
+	}
+	private clientInvocation(ctx: Native, id: string, operation: Operation): string | undefined {
+		const bound = this.bound;
+		if (bound?.inputEvidence !== "client_entry") return undefined;
+		const manager = ctx.sessionManager;
+		if (manager !== this.runtime?.sessionManager || !("getLeafId" in manager) || typeof manager.getLeafId !== "function") return fail("native_context_mismatch");
+		let cursor: unknown = manager.getLeafId(), logical: string | undefined;
+		const seen = new Set<string>(), entries = new Map(manager.getEntries().filter(record).map(entry => [entry.id, entry]));
+		while (text(cursor) && !seen.has(cursor)) {
+			seen.add(cursor);
+			const entry = entries.get(cursor);
+			if (!entry || !text(entry.id)) break;
+			const message = entry.message;
+			if (entry.type === "message" && record(message)) {
+				if (message.role === "user") {
+					if (!logical || message.clientInputId !== bound.identity.inputId) return fail("native_input_mismatch");
+					this.consumed = true; this.consumedEntry = entry.id;
+					return logical;
+				}
+				if (message.role === "assistant" && Array.isArray(message.content)) {
+					const ordinal = message.content.findIndex((part: unknown) => record(part) && part.type === "toolCall" &&
+						part.id === id && part.name === `zgw_agent_${operation}`);
+					if (ordinal >= 0 && logical === undefined) logical = JSON.stringify([bound.identity.durableSessionId, entry.id, ordinal]);
+				}
+			}
+			cursor = entry.parentId;
+		}
+		return fail("native_invocation_missing");
+	}
+	async execute(call: { readonly id: string; readonly params: Record<string, unknown>; readonly signal: AbortSignal | undefined; readonly ctx: unknown; readonly operation: Operation }): Promise<unknown> {
+		payload(call.operation, call.params);
+		const ctx = native(call.ctx);
+		const clientLogical = this.clientInvocation(ctx, call.id, call.operation);
+		const capture = this.capture();
+		if (call.signal?.aborted || ctx.sessionManager !== this.runtime?.sessionManager) return fail("native_context_mismatch");
+		if (capture.binding.readContinuationId && !(call.operation === "files" && isDeepStrictEqual(call.params, capture.read))) return fail("read_only_continuation");
+		const operationKey = JSON.stringify([capture.identity.durableSessionId, call.id, call.operation]);
+		if (this.frozen && (call.operation !== "result" || operationKey !== this.frozen.operationKey ||
+			collaborationDigest(call.params) !== this.frozen.payloadSha)) return fail("request_blocked");
+		if (call.operation === "request" && ((this.role === "agent" && (call.params.kind !== "question" || call.params.retryOf !== undefined)) ||
+			call.params.agentId === capture.identity.agentId || (capture.identity.activationId !== null && capture.requestId === null))) return fail("request_forbidden");
+		if (call.operation === "result" && (capture.requestId === null || call.params.requestId !== capture.requestId)) return fail("binding_conflict");
+		let logical = clientLogical;
+		for (const entry of clientLogical ? [] : ctx.sessionManager.getEntries()) {
+			if (!record(entry) || !text(entry.id) || entry.type !== "message" || !record(entry.message) || entry.message.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
+			const ordinal = entry.message.content.findIndex((item: unknown) => record(item) && item.type === "toolCall" && item.id === call.id && item.name === `zgw_agent_${call.operation}`);
+			if (ordinal >= 0) logical = JSON.stringify([capture.identity.durableSessionId, entry.id, ordinal]);
+		}
+		if (!logical) return fail("native_invocation_missing");
+		const identity = parseManagedCallIdentity({ ...capture.identity, toolCallId: call.id, logicalCallId: logical });
+		const operation = call.operation === "files" ? `files.${call.params.operation}` : call.operation;
+		let staged: StageFile | undefined;
+		if (operation === "files.stage" && typeof call.params.path === "string") {
+			if (!this.stageFile) return fail("collaboration_files_not_ready");
+			staged = await this.stageFile(call.params.path, ctx, call.signal);
+			capture.assertCurrent();
+		}
+		const envelope = JSON.stringify({ operation, sourceSessionPath: identity.sessionPath, toolCallId: call.id,
+			payload: staged ? { ...call.params, path: staged.path } : call.params,
+			context: { requestId: capture.requestId, rootId: capture.rootId, binding: capture.binding } });
+		let body = new TextEncoder().encode(envelope), route = "/internal/agent-collaboration", contentType = "application/json";
+		if (staged) {
+			const form = new FormData();
+			form.set("metadata", envelope); form.set("file", new Blob([Buffer.from(staged.bytes)], { type: staged.mediaType }), staged.name);
+			const encoded = new Request("http://localhost/", { method: "POST", body: form });
+			contentType = encoded.headers.get("content-type") ?? fail("invalid_payload");
+			body = new Uint8Array(await encoded.arrayBuffer());
+			route += "/files";
+		}
+		let method = "POST";
+		if (operation === "files.read" && call.params.view === undefined && typeof call.params.artifactId === "string" && typeof call.params.requestId === "string") {
+			method = "GET"; body = new Uint8Array();
+			route = `/internal/agent-collaboration/artifacts/${encodeURIComponent(call.params.artifactId)}?requestId=${encodeURIComponent(call.params.requestId)}`;
+		}
+		const request = { method, route, operation, body };
+		const proof = buildManagedCallProof({ native: ctx, nativeInstance: ctx.sessionManager, identity, secret: capture.secret,
+			currentIdentity: () => { capture.assertCurrent(); return identity; } }, { ...request, nonce: randomBytes(32).toString("hex") });
+		if (call.operation === "result") this.frozen = { operationKey, payloadSha: collaborationDigest(call.params),
+			paths: Array.isArray(call.params.outputs) ? call.params.outputs.filter(text) : [] };
+		const abort = () => { if (this.bound?.binding === capture.binding) this.revoke(); };
+		call.signal?.addEventListener("abort", abort, { once: true });
+		try {
+			const result = await this.send({ ...request, proof, contentType, ...(call.signal ? { signal: call.signal } : {}) });
+			capture.assertCurrent();
+			return { content: [{ type: "text", text: JSON.stringify(result) }], details: result };
+		} finally { call.signal?.removeEventListener("abort", abort); }
+	}
+}