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

package/src/agent/collaboration-types.ts

@@ -0,0 +1,258 @@
+import { createHash } from "node:crypto";
+import type { Database } from "bun:sqlite";
+
+export type AgentRequestState = "queued" | "running" | "waiting_peer" | "waiting_owner" | "result_preparing" |
+	"completed" | "failed" | "interrupted" | "cancel_requested" | "cancelled" | "unresolved_delivery" | "version_conflict";
+export type AgentDelivery = "queued" | "attempted" | "acknowledged" | "consumed" | "rejected" | "unknown";
+export type AgentStageState = "awaiting_transfer_authority" | "ready" | "staging" | "staged" | "denied" | "cancelled" | "invalidated" | "unknown";
+export interface CollaborationBinding {
+	readonly convId: string;
+	readonly agentId: string | null;
+	readonly lifecycleEpoch: number;
+	readonly inputId: string;
+	readonly activationId: string | null;
+	readonly sessionPath: string;
+	readonly durableSessionId: string;
+	readonly gatewayGeneration: string;
+	readonly definitionSha: string;
+	readonly ownerInputRevision: number;
+	readonly readContinuationId?: string;
+}
+export interface CollaborationTarget {
+	readonly agentId: string;
+	readonly convId: string;
+	readonly lifecycleEpoch: number;
+}
+export interface AgentAccessView {
+	readonly agentId: string;
+	readonly lifecycleEpoch: number;
+	readonly accessState: "open" | "blocked";
+	readonly authorityEpoch: number;
+	readonly policyRevision: number;
+}
+/** Synchronous providers run under the Store writer transaction, never across HTTP/helper waits. */
+export type CollaborationGate = {
+	readonly assertAccess: (tx: Database, source: CollaborationBinding, target: CollaborationTarget) => undefined;
+	readonly assertSelectedExportEligible?: (tx: Database, receipt: AttachmentOrigin) => undefined;
+	readonly assertTransferAuthority?: (tx: Database, stage: AgentArtifactStage) => undefined;
+} & (
+	| { readonly mode: "standalone" }
+	| { readonly mode: "authority"; readonly access: (tx: Database, agentId: string) => AgentAccessView;
+		readonly permissionOutcome?: (tx: Database, decisionId: string) => CollaborationPermissionOutcome | null }
+);
+export interface AgentRequestInput {
+	readonly toolCallId: string;
+	readonly targetAgentId: string;
+	readonly kind: "task" | "question";
+	readonly text: string;
+	readonly files: readonly string[];
+	readonly retryOf?: string;
+}
+export interface AgentRequest {
+	readonly id: string;
+	readonly rootId: string;
+	readonly parentId: string | null;
+	readonly requesterConv: string;
+	readonly requesterAgent: string | null;
+	readonly targetConv: string;
+	readonly targetAgent: string;
+	readonly requesterLifecycleEpoch: number;
+	readonly targetLifecycleEpoch: number;
+	readonly requesterAuthorityEpoch?: number;
+	readonly recipientAuthorityEpoch?: number;
+	readonly kind: AgentRequestInput["kind"];
+	readonly payload: AgentRequestInput;
+	readonly payloadSha: string;
+	readonly submissionKey: string;
+	readonly fingerprint: string;
+	readonly state: AgentRequestState;
+	readonly revision: number;
+	readonly createdAt: string;
+	readonly resultId: string | null;
+	readonly cancelReason: string | null;
+}
+export interface AgentActivation {
+	readonly id: string;
+	readonly requestId: string;
+	readonly direction: "request" | "reply" | "owner_answer";
+	readonly ordinal: number;
+	readonly inputId: string;
+	readonly inputSeq: number;
+	readonly targetConv: string;
+	readonly binding: CollaborationBinding | null;
+	readonly state: AgentDelivery;
+	readonly revision: number;
+	readonly consumedEntry: string | null;
+	readonly quiesced: boolean;
+}
+export interface AgentReceipt {
+	readonly requestId: string;
+	readonly state: AgentRequestState;
+	readonly revision: number;
+}
+/** A cancel receipt also reports the state of every descendant request after the cancel. */
+export interface AgentCancelReceipt extends AgentReceipt {
+	readonly children: readonly AgentReceipt[];
+}
+export interface AgentResultInput {
+	readonly requestId: string;
+	readonly expectedRevision: number;
+	readonly toolCallId: string;
+	readonly outcome: "completed" | "failed";
+	readonly text: string;
+	readonly artifacts: readonly string[];
+}
+export interface AgentResult {
+	readonly id: string;
+	readonly requestId: string;
+	readonly activationId: string;
+	readonly submissionKey: string;
+	readonly payloadSha: string;
+	readonly text: string;
+	readonly outcome: "completed" | "failed";
+	readonly manifest: readonly AgentArtifact[];
+	readonly committedAt: string;
+}
+export interface AttachmentOrigin {
+	readonly attachmentId: string;
+	readonly sourceGrantId: string;
+	readonly sourceGrantRevision: number;
+	readonly originMessageSeq: number;
+	readonly sourceConvId: string;
+	readonly sourceRecipientId: string;
+	readonly sourceConvEpoch: number;
+	readonly sourceRecipientEpoch: number;
+	readonly originalSha256: string;
+	readonly bytes: number;
+	readonly format: string;
+	readonly name: string;
+}
+export type TransferAuthority =
+	| { readonly kind: "owner_decision"; readonly decisionId: string; readonly decisionRevision: number; readonly submissionId: string; readonly scopeDigest: string; readonly transferId: string }
+	| { readonly kind: "tool_policy"; readonly authorityId: string; readonly revision: number; readonly policyRevision: number; readonly authorityEpoch: number; readonly scopeDigest: string; readonly actionTicketId?: string };
+export type StageSource =
+	| { readonly kind: "agent_path"; readonly path: string; readonly sha256: string }
+	| { readonly kind: "attachment"; readonly origin: AttachmentOrigin }
+	| { readonly kind: "artifact"; readonly requestId: string; readonly artifactId: string; readonly grantId: string; readonly grantRevision: number; readonly sha256: string };
+export interface AgentStageInput {
+	readonly transferId?: string;
+	readonly operationKey: string;
+	readonly source: StageSource;
+	readonly target: CollaborationTarget;
+	readonly ownerPrincipalRef: string;
+	readonly authority: TransferAuthority | null;
+}
+export interface AgentArtifactStage extends AgentStageInput {
+	readonly transferId: string;
+	readonly payloadSha: string;
+	readonly scopeDigest: string;
+	readonly sourceBinding: CollaborationBinding;
+	readonly sourceAuthorityEpoch?: number;
+	readonly targetAuthorityEpoch?: number;
+	readonly originRequestId: string | null;
+	readonly decisionId: string | null;
+	readonly decisionRevision: number | null;
+	readonly continuationId: string;
+	readonly state: AgentStageState;
+	readonly revision: number;
+	readonly artifactId: string | null;
+	readonly exportReceipt: AttachmentOrigin | null;
+	readonly errorCode: string | null;
+}
+export interface ArtifactProvenance {
+	readonly transferId: string | null;
+	readonly originAttachment?: AttachmentOrigin;
+	readonly sourceArtifactId?: string;
+	readonly sourceArtifactGrantRevision?: number;
+	readonly parentTransferId?: string;
+	readonly transferAuthorityRef: TransferAuthority | null;
+	readonly targetAgentId: string;
+	readonly targetConvId: string;
+	readonly targetLifecycleEpoch: number;
+	readonly sourceInputId: string;
+	readonly sourceActivationId: string | null;
+	readonly requestId: string | null;
+	readonly rootId: string | null;
+	readonly producedBy?: { readonly requestId: string; readonly activationId: string; readonly producerConv: string };
+	readonly inputArtifactIds?: readonly string[];
+}
+export interface AgentArtifact {
+	readonly id: string;
+	readonly producerConv: string;
+	readonly requestId: string | null;
+	readonly resultId?: string;
+	readonly sha256: string;
+	readonly bytes: number;
+	readonly mediaType: string;
+	readonly originalName: string;
+	readonly sealedName: string;
+	readonly state: "staged" | "committed" | "trashed";
+	readonly lifecycleEpoch: number;
+	readonly storageClass: "source_copy" | "scoped_document";
+	readonly stageOperationKey: string;
+	readonly stagePayloadSha: string;
+	readonly provenance: ArtifactProvenance;
+}
+export interface ArtifactGrant {
+	readonly grantId: string;
+	readonly artifactId: string;
+	readonly granteeConv: string;
+	readonly requestId: string;
+	readonly permission: "read" | "transfer";
+	readonly revoked: boolean;
+	readonly revision: number;
+	readonly granteeLifecycleEpoch: number;
+	readonly recipientAuthorityEpoch?: number;
+}
+export interface CollaborationPermissionOutcome {
+	readonly decisionId: string;
+	readonly decisionRevision: number;
+	readonly outcome: "allowed" | "denied" | "cancelled";
+	readonly logicalOperationId: string;
+	readonly continuationId: string;
+	readonly collaborationRequestId: string;
+	readonly blockedActivationId: string;
+	readonly originInputSeq: number;
+	readonly lifecycleEpoch: number;
+	readonly authorityEpoch: number;
+	readonly policyRevision: number;
+}
+export type CollaborationIntent =
+	| { readonly origin: "agent_collaboration"; readonly requestId: string; readonly activationId: string; readonly direction: AgentActivation["direction"]; readonly messageSeq: number }
+	| { readonly origin: "collaboration_stage"; readonly transferId: string; readonly continuationId: string }
+	| { readonly origin: "agent_tool_permission"; readonly outcome: CollaborationPermissionOutcome }
+	| { readonly origin: "collaboration_artifact_read"; readonly holdId: string; readonly readOperationId: string; readonly continuationId: string; readonly reviewedScopeDigest: string };
+
+export class CollaborationStoreError extends Error {
+	constructor(readonly code: string, readonly status: 400 | 403 | 404 | 409 | 410 | 413 | 503 = 409) { super(code); }
+}
+export function collaborationDigest(value: unknown): string {
+	// All callers provide named internal DTOs; recursively sort keys without semantic text normalization.
+	const canonical = (input: unknown): unknown => {
+		if (Array.isArray(input)) return input.map(canonical);
+		if (typeof input !== "object" || input === null) return input;
+		return Object.fromEntries(Object.entries(input).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)]));
+	};
+	return createHash("sha256").update(JSON.stringify(canonical(value))).digest("hex");
+}
+/**
+ * Final request states, defined once: nothing re-runs them automatically and no later transition rewrites them.
+ * unresolved_delivery is not final: only an evidence recheck resolves it, and it is never retried automatically.
+ */
+export const AGENT_REQUEST_FINAL_STATES = ["completed", "failed", "cancelled", "interrupted", "version_conflict"] as const satisfies readonly AgentRequestState[];
+/** The final states as a SQL list literal for `state IN ...` / `state NOT IN ...`, including the partial unique index. */
+export const AGENT_REQUEST_FINAL_SQL = `(${AGENT_REQUEST_FINAL_STATES.map(state => `'${state}'`).join(",")})`;
+export function agentRequestTerminal(state: AgentRequestState): boolean {
+	return (AGENT_REQUEST_FINAL_STATES as readonly AgentRequestState[]).includes(state);
+}
+/** A final original that only an explicit main/operator retryOf may follow with a new request; completed is never retried. */
+export function agentRequestRetryable(state: AgentRequestState): boolean {
+	return agentRequestTerminal(state) && state !== "completed";
+}
+export function collaborationNever(value: never): never {
+	throw new CollaborationStoreError("invalid_variant", 400);
+}
+export function collaborationStageDecision(decision: { readonly payload: unknown }): boolean {
+	const payload = decision.payload;
+	return typeof payload === "object" && payload !== null && "purpose" in payload && payload.purpose === "collaboration_attachment_transfer";
+}

package/src/agent/collaboration.ts

@@ -0,0 +1,399 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import type { Hub } from "../hub.ts";
+import { maintenanceAuth } from "../maintenance.ts";
+import { OmoCommandError } from "../omo/client.ts";
+import type { Store } from "../store.ts";
+import { join } from "node:path";
+import { AgentArtifacts } from "./artifacts.ts";
+import { AgentContentError, AgentContentFiles } from "./file-core.ts";
+import type { AgentFileStore } from "./files.ts";
+import { ManagedCallError } from "./managed-call.ts";
+import { CollaborationStoreError, collaborationDigest, collaborationNever, type AgentArtifact, type CollaborationGate } from "./collaboration-types.ts";
+import { CollaborationSessions, collaborationRecord as record, collaborationText as text } from "./collaboration-session.ts";
+import { CollaborationAdmission, type CollaborationAuthority } from "./collaboration-admission.ts";
+import { testCrashPoint } from "../test-crash.ts";
+import type { NativeDocumentBuild } from "../attachments/document-reader.ts";
+import type { ArtifactReviewSummary, ArtifactSecurityHold } from "../security-allow.ts";
+import { presentArtifactRead, type ArtifactReadArguments, type PresentedRead } from "./collaboration-read.ts";
+
+const invalid = (): never => { throw new CollaborationStoreError("invalid_payload", 400); };
+function keys(value: unknown, allowed: readonly string[]): Record<string, unknown> {
+	if (!record(value) || Object.keys(value).some(key => !allowed.includes(key))) return invalid();
+	return value;
+}
+function string(value: unknown): string { return text(value) ? value : invalid(); }
+function strings(value: unknown): readonly string[] {
+	if (value === undefined) return [];
+	if (!Array.isArray(value) || !value.every(text) || new Set(value).size !== value.length) return invalid();
+	if (value.length > 10) throw new CollaborationStoreError("request_too_large", 413);
+	return value;
+}
+function integer(value: unknown): number { return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : invalid(); }
+type Payload =
+	| { readonly operation: "request"; readonly agentId: string; readonly kind: "task" | "question"; readonly text: string; readonly files: readonly string[]; readonly retryOf?: string }
+	| { readonly operation: "requests"; readonly requestId?: string }
+	| { readonly operation: "cancel"; readonly requestId: string; readonly expectedRevision: number; readonly reason: string }
+	| { readonly operation: "result"; readonly requestId: string; readonly status: "completed" | "failed"; readonly text: string; readonly outputs: readonly string[] }
+	| { readonly operation: "files.stage"; readonly agentId: string; readonly source: { readonly kind: "path"; readonly path: string } | { readonly kind: "attachment"; readonly id: string } | { readonly kind: "artifact"; readonly requestId: string; readonly id: string } }
+	| { readonly operation: "files.list"; readonly requestId: string }
+	| { readonly operation: "files.read"; readonly requestId: string; readonly artifactId: string; readonly view?: "text" | "pages"; readonly cursor?: string; readonly limit?: number };
+function parse(operation: unknown, value: unknown): Payload {
+	switch (operation) {
+		case "request": {
+			const p = keys(value, ["agentId", "kind", "text", "files", "retryOf"]);
+			if (p.kind !== "task" && p.kind !== "question") return invalid();
+			return { operation, agentId: string(p.agentId), kind: p.kind, text: string(p.text), files: strings(p.files),
+				...(p.retryOf === undefined ? {} : { retryOf: string(p.retryOf) }) };
+		}
+		case "requests": {
+			const p = keys(value, ["requestId"]);
+			return { operation, ...(p.requestId === undefined ? {} : { requestId: string(p.requestId) }) };
+		}
+		case "cancel": {
+			const p = keys(value, ["requestId", "expectedRevision", "reason"]);
+			return { operation, requestId: string(p.requestId), expectedRevision: integer(p.expectedRevision), reason: string(p.reason) };
+		}
+		case "result": {
+			const p = keys(value, ["requestId", "status", "text", "outputs"]);
+			if (p.status !== "completed" && p.status !== "failed") return invalid();
+			return { operation, requestId: string(p.requestId), status: p.status, text: string(p.text), outputs: strings(p.outputs) };
+		}
+		case "files.stage": {
+			const p = keys(value, ["operation", "agentId", "path", "attachmentId", "scopedArtifact"]);
+			if (p.operation !== "stage" || ["path", "attachmentId", "scopedArtifact"].filter(k => p[k] !== undefined).length !== 1) return invalid();
+			const agentId = string(p.agentId);
+			if (p.path !== undefined) return { operation, agentId, source: { kind: "path", path: string(p.path) } };
+			if (p.attachmentId !== undefined) return { operation, agentId, source: { kind: "attachment", id: string(p.attachmentId) } };
+			const s = keys(p.scopedArtifact, ["requestId", "artifactId"]);
+			return { operation, agentId, source: { kind: "artifact", requestId: string(s.requestId), id: string(s.artifactId) } };
+		}
+		case "files.list": {
+			const p = keys(value, ["operation", "requestId"]);
+			if (p.operation !== "list") return invalid();
+			return { operation, requestId: string(p.requestId) };
+		}
+		case "files.read": {
+			const p = keys(value, ["operation", "requestId", "artifactId", "view", "cursor", "limit"]);
+			if (p.operation !== "read" || (p.view !== undefined && p.view !== "text" && p.view !== "pages")) return invalid();
+			const limit = p.limit === undefined ? undefined : integer(p.limit);
+			if (limit === 0 || (p.view === undefined && (p.cursor !== undefined || limit !== undefined))) return invalid();
+			return { operation, requestId: string(p.requestId), artifactId: string(p.artifactId),
+				...(p.view === undefined ? {} : { view: p.view }), ...(p.cursor === undefined ? {} : { cursor: string(p.cursor) }),
+				...(limit === undefined ? {} : { limit }) };
+		}
+		default: return invalid();
+	}
+}
+const metadata = (a: AgentArtifact) => ({ artifactId: a.id, requestId: a.requestId, sha256: a.sha256, bytes: a.bytes,
+	name: a.originalName, mediaType: a.mediaType, storageClass: a.storageClass, state: a.state });
+/** 294's owner principal (ToolPermissions owner principals are always this ref); the review route compares against it. */
+const OWNER_PRINCIPAL = "owner";
+const unavailable = (capability: string) => Response.json({ error: "capability_unavailable", capability }, { status: 503 });
+
+/** HTTP boundary only. Hub owns execution; Store owns admission, lineage, grants and state transitions. */
+export class AgentCollaboration {
+	private readonly sessions: CollaborationSessions;
+	private readonly admission: CollaborationAdmission;
+	constructor(private readonly host: { readonly hub: Hub; readonly store: Store; readonly files: AgentFileStore;
+		readonly authority?: CollaborationAuthority;
+		readonly artifactReadAdmission?: (hold: ArtifactSecurityHold) => CollaborationGate;
+		/** The 293 native document reader for text/pages views. Absent or null: those views answer native_reader_unavailable. */
+		readonly documentReader?: NativeDocumentBuild | null;
+		/** Owner authentication at the caller boundary (294 C3 helper). Absent: owner actions answer 503, never succeed. */
+		readonly owner?: (req: Request, trusted: boolean) => { readonly ownerRef: string } | Response }, private readonly token: string) {
+		this.sessions = new CollaborationSessions(host.hub, host.store);
+		this.admission = new CollaborationAdmission(host.store, host.files, host.authority);
+		host.hub.attachCollaboration({ bind: (conv, input, dispatch) => this.sessions.bind(conv, input, dispatch),
+			retire: conv => this.sessions.retire(conv), gate: request => this.admission.gate(request),
+			permission: outcome => this.admission.permission(outcome),
+			artifactRead: hold => {
+				if (host.artifactReadAdmission) return host.artifactReadAdmission(hold);
+				if (hold.representation.view !== "raw" && !host.documentReader) throw new CollaborationStoreError("document_representations_unavailable", 503);
+				return this.admission.gate();
+			} });
+	}
+	/**
+	 * Owner routes under /api/agent-collaboration. Listing reads the same history the trusted web already shows; cancel
+	 * and file download are owner actions and need the injected owner principal.
+	 */
+	async handleOwner(req: Request, trusted: boolean): Promise<Response> {
+		if (!trusted) return Response.json({ error: "forbidden" }, { status: 403 });
+		const url = new URL(req.url), { store, files } = this.host;
+		try {
+			if (url.pathname === "/api/agent-collaboration/requests" && req.method === "GET") {
+				const conv = url.searchParams.get("conv");
+				if (!conv || !store.getConversation(conv)) return Response.json({ error: "conversation_not_found" }, { status: 404 });
+				const page = store.listAgentRequests(conv, url.searchParams.get("cursor") ?? undefined);
+				return Response.json({ requests: page.requests.map(request => this.participant(request.id, conv)), nextCursor: page.nextCursor });
+			}
+			const cancel = url.pathname.match(/^\/api\/agent-collaboration\/requests\/([^/]+)\/cancel$/);
+			const download = url.pathname.match(/^\/api\/agent-collaboration\/artifacts\/([^/]+)$/);
+			const review = url.pathname.match(/^\/api\/agent-collaboration\/holds\/([^/]+)$/);
+			if (!cancel && !download && !review) return Response.json({ error: "not_found" }, { status: 404 });
+			if (!this.host.owner) return Response.json({ error: "owner_auth_unavailable" }, { status: 503 });
+			const owner = this.host.owner(req, trusted);
+			if (owner instanceof Response) return owner;
+			if (cancel && req.method === "POST") {
+				const body: unknown = await req.json();
+				if (!record(body) || !Number.isSafeInteger(body.expectedRevision)) return invalid();
+				const receipt = store.cancelAgentRequestAsOwner({ requestId: decodeURIComponent(cancel[1]!), expectedRevision: Number(body.expectedRevision), reason: "owner_cancelled" });
+				if (receipt.state === "cancel_requested") void this.host.hub.interruptCancelledCollaboration().catch(error => console.error("collaboration cancel interrupt:", error));
+				this.host.hub.wakeCollaborationReplies();
+				return Response.json(receipt);
+			}
+			if (review && req.method === "POST") {
+				const body: unknown = await req.json();
+				if (!record(body) || (body.choice !== "allow" && body.choice !== "deny") || !Number.isSafeInteger(body.expectedRevision) || !text(body.submissionId)) return invalid();
+				return Response.json(this.reviewHold({ holdId: decodeURIComponent(review[1]!), choice: body.choice, expectedRevision: Number(body.expectedRevision),
+					submissionId: body.submissionId, ownerPrincipalRef: owner.ownerRef }));
+			}
+			if (download && (req.method === "GET" || req.method === "POST")) {
+				const artifact = store.agentArtifact(decodeURIComponent(download[1]!));
+				// A trashed artifact keeps its tombstone row; its bytes are gone for good, which is 410, not an unknown ID.
+				if (artifact?.state === "trashed") return Response.json({ error: "artifact_revoked" }, { status: 410 });
+				if (!artifact || artifact.state !== "committed") return Response.json({ error: "artifact_not_found" }, { status: 404 });
+				using core = new AgentContentFiles(files.root);
+				const bytes = core.read([".collaboration", "artifacts", artifact.sealedName]);
+				if (createHash("sha256").update(bytes).digest("hex") !== artifact.sha256) return Response.json({ error: "file_changed" }, { status: 409 });
+				return new Response(new Uint8Array(bytes), { headers: { "content-type": artifact.mediaType || "application/octet-stream",
+					"content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(artifact.originalName)}`, "x-zgw-artifact-sha256": artifact.sha256 } });
+			}
+			return Response.json({ error: "method_not_allowed" }, { status: 405 });
+		} catch (error) {
+			if (error instanceof CollaborationStoreError || error instanceof AgentContentError) return Response.json({ error: error.code }, { status: error.status });
+			if (error instanceof SyntaxError) return invalid();
+			throw error;
+		}
+	}
+	/** Housekeeping candidates and the operator-selected move to the Trash (the Store re-checks every reference). */
+	cleanupRows() {
+		return this.host.store.agentArtifactCleanupRows().map(row => ({ artifactId: row.artifactId, state: row.state, bytes: row.bytes,
+			target: join(this.host.files.root, ".collaboration", "artifacts", row.sealedName) }));
+	}
+	trashArtifact(artifactId: string): void {
+		using core = new AgentContentFiles(this.host.files.root);
+		new AgentArtifacts(core, this.host.store, this.admission.gate()).trash(artifactId);
+	}
+	async handle(req: Request, trusted: boolean): Promise<Response> {
+		const denied = maintenanceAuth(req, trusted, this.token);
+		if (denied) return denied;
+		return this.host.hub.admitWorkRequest(() => this.dispatch(req));
+	}
+	private async dispatch(req: Request): Promise<Response> {
+		try {
+			const url = new URL(req.url), download = url.pathname.match(/^\/internal\/agent-collaboration\/artifacts\/([^/]+)$/);
+			const upload = url.pathname === "/internal/agent-collaboration/files";
+			if (download ? req.method !== "GET" : req.method !== "POST") return invalid();
+			if (!download && !upload && url.pathname !== "/internal/agent-collaboration") return Response.json({ error: "not_found" }, { status: 404 });
+			if (!download && url.search) return invalid();
+			const chunks: Uint8Array[] = [];
+			let length = 0;
+			if (req.body) for await (const chunk of req.body) {
+				length += chunk.length;
+				if (length > (upload ? 11 * 1024 * 1024 : 512 * 1024)) throw new CollaborationStoreError("body_too_large", 413);
+				chunks.push(chunk);
+			}
+			const body = Buffer.concat(chunks);
+			let envelope: Record<string, unknown>, file: File | undefined;
+			if (download) {
+				if ([...url.searchParams.keys()].some(k => k !== "requestId") || url.searchParams.getAll("requestId").length !== 1) return invalid();
+				envelope = { operation: "files.read", payload: { operation: "read", requestId: url.searchParams.get("requestId"), artifactId: download[1] } };
+			} else if (upload) {
+				const form = await new Request(req.url, { method: "POST", headers: req.headers, body }).formData();
+				if ([...form.keys()].length !== 2 || !(form.get("file") instanceof File) || typeof form.get("metadata") !== "string") return invalid();
+				const part = form.get("file"), description = form.get("metadata");
+				if (!(part instanceof File) || typeof description !== "string") return invalid();
+				file = part;
+				envelope = keys(JSON.parse(description), ["operation", "payload", "sourceSessionPath", "toolCallId", "context"]);
+			} else envelope = keys(await new Response(body).json(), ["operation", "payload", "sourceSessionPath", "toolCallId", "context"]);
+			const payload = parse(envelope.operation, envelope.payload);
+			if ("text" in payload && Buffer.byteLength(payload.text) > 65536) throw new CollaborationStoreError("request_too_large", 413);
+			if (upload && payload.operation !== "files.stage") return invalid();
+			const proof: unknown = JSON.parse(req.headers.get("x-zgw-managed-proof") ?? "null");
+			const uploaded = file ? Buffer.from(await file.arrayBuffer()) : undefined;
+			const logicalPayload = { ...(payload.operation === "request" ? { ...payload, text: payload.text.trim(), files: [...payload.files].sort() } : payload),
+				...(uploaded ? { fileSha256: createHash("sha256").update(uploaded).digest("hex") } : {}) };
+			const call = await this.sessions.authenticate({ method: req.method, route: url.pathname + url.search, operation: payload.operation, body, proof, logicalPayload });
+			if (!download && (envelope.sourceSessionPath !== call.binding.sessionPath || envelope.toolCallId !== call.verified.toolCallId ||
+				!isDeepStrictEqual(envelope.context, { requestId: call.requestId, rootId: call.rootId, binding: call.binding }))) return invalid();
+			call.assertCurrent();
+			const { store, files, hub } = this.host;
+			if (call.binding.activationId !== null) {
+				await hub.recordCollaborationConsumption(call.binding.convId, call.binding.inputId);
+				call.assertCurrent();
+			}
+			const policy = this.admission.gate();
+			const gate: CollaborationGate = { ...policy, assertAccess: (tx, source, target) => {
+				call.assertCurrent();
+				policy.assertAccess(tx, source, target);
+				return undefined;
+			} };
+			switch (payload.operation) {
+				case "request": {
+					hub.checkCollaborationText(payload.text);
+					const cursors = new Map(store.listConversations().map(c => [c.id, store.recentEvents(c.id, 1).at(-1)?.seq ?? 0]));
+					const before = new Set(store.eventsAfter(call.binding.convId, 0).flatMap(event =>
+						event.type === "message.collaboration" && record(event.data) && text(event.data.requestId) ? [event.data.requestId] : []));
+					const receipt = store.acceptAgentRequest({ toolCallId: call.verified.toolCallId, targetAgentId: payload.agentId,
+						kind: payload.kind, text: payload.text, files: payload.files, ...(payload.retryOf ? { retryOf: payload.retryOf } : {}) }, call.binding, gate);
+					testCrashPoint("collaboration.admission.after-commit");
+					hub.collaborationQueued(receipt.requestId, cursors);
+					return Response.json(receipt, { status: before.has(receipt.requestId) ? 200 : 202 });
+				}
+				case "requests": {
+					if (payload.requestId) return Response.json(this.participant(payload.requestId, call.binding.convId));
+					const page = store.listAgentRequests(call.binding.convId);
+					return Response.json({ requests: page.requests.map(r => this.participant(r.id, call.binding.convId)), nextCursor: page.nextCursor });
+				}
+				case "cancel": {
+					const receipt = store.cancelAgentRequest(payload, call.binding);
+					if (receipt.state === "cancel_requested") void hub.interruptCancelledCollaboration().catch(error => console.error("collaboration cancel interrupt:", error));
+					hub.wakeCollaborationReplies();
+					return Response.json(receipt);
+				}
+				case "result": {
+					const request = store.getAgentRequest(payload.requestId);
+					if (!request) throw new CollaborationStoreError("request_not_found", 404);
+					if (request.targetConv !== call.binding.convId || call.binding.activationId === null) throw new CollaborationStoreError("result_forbidden", 403);
+					const submitted = { requestId: request.id, toolCallId: call.verified.toolCallId, outcome: payload.status, text: payload.text };
+					const prior = store.agentResultIntent(call.binding.activationId);
+					if (prior) {
+						// A wire retry of the same submission returns its receipt; it never seals the outputs again.
+						return Response.json(store.recordAgentResultIntent({ ...prior, ...submitted, expectedRevision: prior.expectedRevision }, call.binding), { status: 200 });
+					}
+					// The extension froze further writes at this result execute; it drains and seals the exact listed outputs.
+					const sealed = await hub.collaborationSnapshot(call.binding.convId, { requestId: request.id, requestRevision: request.revision,
+						operationKey: call.operationKey, bindingDigest: collaborationDigest(call.binding), paths: payload.outputs });
+					call.assertCurrent();
+					if (!sealed.ok) throw new CollaborationStoreError(sealed.error, sealed.error === "file_not_found" ? 404 : sealed.error === "file_too_large" ? 413 : 409);
+					const outputs = (() => {
+						using core = new AgentContentFiles(files.root);
+						return sealed.files.map(file => {
+							const bytes = core.read([".collaboration", "artifacts", file.sealedName]);
+							if (bytes.length !== file.bytes || createHash("sha256").update(bytes).digest("hex") !== file.sha256) throw new CollaborationStoreError("file_changed");
+							return { sha256: file.sha256, bytes: file.bytes, mediaType: file.mediaType, name: file.name, sealedName: file.sealedName };
+						});
+					})();
+					const artifacts = store.prepareAgentResult({ requestId: request.id, expectedRevision: request.revision, files: outputs }, call.binding);
+					const prepared = store.getAgentRequest(request.id);
+					if (!prepared) throw new CollaborationStoreError("request_not_found", 404);
+					const receipt = store.recordAgentResultIntent({ ...submitted, expectedRevision: prepared.revision, artifacts: artifacts.map(a => a.id) }, call.binding);
+					return Response.json({ ...receipt, files: artifacts.map(metadata) }, { status: 202 });
+				}
+				case "files.stage": {
+					switch (payload.source.kind) {
+						case "attachment": return unavailable("attachment_export_metadata");
+						case "artifact": return unavailable("collaboration_transfer_authority");
+						case "path": break;
+						default: return collaborationNever(payload.source);
+					}
+					if (!file || !uploaded) return invalid();
+					if (file.size > 10 * 1024 * 1024) throw new CollaborationStoreError("file_too_large", 413);
+					const bytes = uploaded;
+					call.assertCurrent();
+					const target = store.listConversations(false).find(c => c.agentId === payload.agentId);
+					if (!target) throw new CollaborationStoreError("agent_not_found", 404);
+					const stage = store.beginAgentStage({ operationKey: call.operationKey,
+						source: { kind: "agent_path", path: payload.source.path, sha256: createHash("sha256").update(bytes).digest("hex") },
+						target: { agentId: payload.agentId, convId: target.id, lifecycleEpoch: store.ensureAgentLifecycle(payload.agentId) },
+						ownerPrincipalRef: "", authority: null }, call.binding, gate);
+					using core = new AgentContentFiles(files.root);
+					const artifact = await new AgentArtifacts(core, store, gate).stage(stage.transferId, async () => ({ bytes, name: file.name, mediaType: file.type || "application/octet-stream" }));
+					call.assertCurrent();
+					return Response.json({ ...metadata(artifact), transferId: stage.transferId }, { status: stage.state === "staged" ? 200 : 202 });
+				}
+				case "files.list": {
+					const request = store.getAgentRequest(payload.requestId);
+					this.participant(payload.requestId, call.binding.convId);
+					return Response.json({ files: (request?.payload.files ?? []).flatMap(id => {
+						const a = store.agentArtifact(id), grant = store.agentArtifactGrant(id, call.binding.convId, payload.requestId);
+						return a && grant && !grant.revoked ? [metadata(a)] : [];
+					}) });
+				}
+				case "files.read": {
+					this.participant(payload.requestId, call.binding.convId);
+					const { operation: _operation, ...args } = payload;
+					using core = new AgentContentFiles(files.root);
+					call.assertCurrent();
+					const artifacts = new AgentArtifacts(core, store, gate);
+					const present = async (artifact: AgentArtifact, bytes: Buffer) => {
+						const presented = await presentArtifactRead({ artifact, bytes, args, reader: this.host.documentReader });
+						call.assertCurrent();
+						return { presented, bytes };
+					};
+					type Shown = { readonly presented: PresentedRead; readonly bytes: Buffer } | { readonly held: Record<string, unknown> };
+					const continuation = call.binding.readContinuationId;
+					const shown: Shown = continuation === undefined
+						? await artifacts.readReviewed<Shown>({ ...args, readOperationId: call.operationId }, call.binding, async (artifact, bytes, readId) => {
+							const value = await present(artifact, bytes);
+							const summary = this.review(value.presented);
+							if (summary === null) return { release: true, value };
+							return { release: false, value: { held: this.holdRead(artifact, readId, value.presented, args, call.binding, gate, summary) } };
+						})
+						: await artifacts.releaseHeld<Shown>(this.continuationHold(continuation, args), call.binding, async (artifact, bytes) => {
+							const value = await present(artifact, bytes);
+							return { sha256: value.presented.representation.sha256, value };
+						});
+					call.assertCurrent();
+					if ("held" in shown) return Response.json(shown.held, { status: 202 });
+					if (download) return new Response(new Uint8Array(shown.bytes), { headers: { "content-type": "application/octet-stream",
+						"x-zgw-artifact-id": payload.artifactId, "x-zgw-request-id": payload.requestId } });
+					return Response.json(shown.presented.body);
+				}
+				default: return collaborationNever(payload);
+			}
+		} catch (error) {
+			if (error instanceof ManagedCallError) return Response.json({ error: error.code }, { status: 403 });
+			if (error instanceof OmoCommandError) return Response.json({ error: "collaboration_native_unavailable" }, { status: 503 });
+			if (error instanceof CollaborationStoreError || error instanceof AgentContentError) return Response.json({ error: error.code }, { status: error.status });
+			if (error instanceof SyntaxError || error instanceof TypeError) return Response.json({ error: "invalid_payload" }, { status: 400 });
+			throw error;
+		}
+	}
+	/**
+	 * The gateway's message security check (MessageGuard through the Hub) over every text a read would release, plus the
+	 * pages no text layer covered: null when the read may go out as is, else what the owner's review card shows.
+	 */
+	private review(presented: PresentedRead): ArtifactReviewSummary | null {
+		const findings = this.host.hub.collaborationFindings(presented.texts).map(({ kind, count }) => ({ kind, count }));
+		if (findings.length === 0 && presented.unscannedPages.length === 0) return null;
+		return { findings, unscannedPages: [...presented.unscannedPages] };
+	}
+	/**
+	 * Flagged content stays unreleased. A peer activation reading a sealed result gets the owner review hold and its inbox
+	 * decision; any other flagged read (owner turn, request input) has no reviewable continuation and is refused.
+	 */
+	private holdRead(artifact: AgentArtifact, readId: string, presented: PresentedRead, args: ArtifactReadArguments, binding: import("./collaboration-types.ts").CollaborationBinding, gate: CollaborationGate, summary: ArtifactReviewSummary) {
+		const { store, hub } = this.host;
+		const activation = binding.activationId === null ? null : store.getAgentActivation(binding.activationId);
+		if (!activation || !artifact.resultId) throw new CollaborationStoreError("collaboration_security_review_required");
+		const hold = store.createArtifactSecurityHold({ readOperationId: readId, originInputSeq: activation.inputSeq, ownerPrincipalRef: OWNER_PRINCIPAL,
+			representation: { ...presented.representation, revision: 1, scanRevision: `message-guard:${store.securityAllowedValues().revision}` }, readArguments: args, summary }, binding, gate);
+		hub.refreshDecisions();
+		return { state: "held", holdId: hold.id, decisionId: hold.decisionId, revision: hold.revision, requestId: args.requestId, artifactId: args.artifactId,
+			view: args.view ?? "raw", contentReleased: false, unscannedPages: hold.summary?.unscannedPages ?? [] };
+	}
+	private continuationHold(continuationId: string, args: ArtifactReadArguments): ArtifactSecurityHold {
+		const hold = this.host.store.artifactHoldByContinuation(continuationId);
+		if (!hold || !isDeepStrictEqual(hold.readArguments, args)) throw new CollaborationStoreError("artifact_review_stale");
+		return hold;
+	}
+	private reviewHold(input: { readonly holdId: string; readonly choice: "allow" | "deny"; readonly expectedRevision: number; readonly submissionId: string; readonly ownerPrincipalRef: string }) {
+		const { store, hub } = this.host;
+		const hold = store.artifactSecurityHold(input.holdId);
+		if (!hold) throw new CollaborationStoreError("hold_not_found", 404);
+		const receipt = store.reviewArtifactHold({ ...input, scopeDigest: hold.scopeDigest }, store.artifactReaderBinding(hold.readOperationId), this.admission.gate());
+		if (receipt.reviewState === "allowed") hub.resumeArtifactReview(hold.id);
+		else hub.refreshDecisions();
+		return { ...receipt, resumeState: store.artifactSecurityHold(hold.id)?.continuation.state ?? null };
+	}
+	private participant(id: string, conv: string) {
+		const request = this.host.store.getAgentRequest(id);
+		if (!request) throw new CollaborationStoreError("request_not_found", 404);
+		if (request.requesterConv !== conv && request.targetConv !== conv) throw new CollaborationStoreError("request_forbidden", 403);
+		// F3 D5: the recipient agent names a sent card's receiver; the stored request message carries only its sender.
+		return { requestId: request.id, rootId: request.rootId, parentId: request.parentId, kind: request.kind, targetAgent: request.targetAgent,
+			state: request.state, revision: request.revision, resultId: request.resultId, text: request.payload.text, files: request.payload.files };
+	}
+}