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

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

@@ -0,0 +1,282 @@
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { AgentContentError, AgentContentFiles, type ContentVersion } from "../../src/agent/file-core.ts";
+import { collaborationDigest } from "../../src/agent/collaboration-types.ts";
+import { sniffImage } from "../../src/media.ts";
+import { CollaborationExtensionError, record, type CollaborationApi, type CollaborationControl, type CollaborationTool, type SealedOutput, type SnapshotCall, type SnapshotError, type SnapshotResult } from "./agent-collaboration.ts";
+
+type FileOperations = {
+	readonly access: (path: string) => Promise<void>; readonly readFile: (path: string) => Promise<Buffer>;
+	readonly writeFile: (path: string, content: string) => Promise<void>; readonly mkdir: (path: string) => Promise<void>;
+	readonly detectImageMimeType: (path: string) => Promise<string | undefined>;
+};
+export type FilePolicy = (request: { readonly operation: string; readonly canonicalPath: string }) => Promise<{ allow: true } | { allow: false; reason: string }>;
+type FileOptions = { readonly operations?: FileOperations; readonly filesystemPolicy?: FilePolicy };
+type ReadOptions = {
+	readonly operations?: Pick<FileOperations, "access" | "readFile"> & {
+		readonly detectImageMimeType?: (path: string) => Promise<string | null | undefined>;
+	};
+	readonly filesystemPolicy?: FilePolicy;
+};
+export interface NativeFileSdk {
+	createReadToolDefinition(cwd: string, options?: ReadOptions): CollaborationTool;
+	createWriteToolDefinition(cwd: string, options?: FileOptions): CollaborationTool;
+	createEditToolDefinition(cwd: string, options?: FileOptions): CollaborationTool;
+	createReadOnlyTools(cwd: string, options?: { readonly read?: ReadOptions }): readonly CollaborationTool[];
+	withFileMutationQueue<T>(path: string, action: () => Promise<T>): Promise<T>;
+}
+
+type SnapshotRuntime = {
+	readonly root: string;
+	readonly control: CollaborationControl;
+	/** Pass the public queue from the same SDK instance as the registered native definitions. */
+	readonly queue: <T>(path: string, action: () => Promise<T>) => Promise<T>;
+	readonly assertKnowledgeLock: () => void;
+};
+const fail = (code: SnapshotError): never => { throw new CollaborationExtensionError(code); };
+const digest = (bytes: Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
+const segment = (value: string): boolean => value.length > 0 && value !== "." && value !== ".." && !/[/\\\0]/.test(value);
+function parseCall(value: unknown): SnapshotCall {
+	if (!record(value) || Object.keys(value).some(key => !["requestId", "requestRevision", "operationKey", "bindingDigest", "paths"].includes(key)) ||
+		typeof value.requestId !== "string" || !segment(value.requestId) || typeof value.operationKey !== "string" || !value.operationKey ||
+		typeof value.bindingDigest !== "string" || !/^[a-f0-9]{64}$/.test(value.bindingDigest) ||
+		typeof value.requestRevision !== "number" || !Number.isSafeInteger(value.requestRevision) || value.requestRevision < 0 ||
+		!Array.isArray(value.paths) || value.paths.length > 10 ||
+		!value.paths.every((path): path is string => typeof path === "string" && path.startsWith("outputs/") && path.split("/").every(segment))) return fail("invalid_snapshot");
+	const paths = [...value.paths];
+	if (new Set(paths.map(path => path.normalize("NFC").toLowerCase())).size !== paths.length) return fail("invalid_snapshot");
+	return { requestId: value.requestId, requestRevision: value.requestRevision, operationKey: value.operationKey, bindingDigest: value.bindingDigest, paths };
+}
+function sealed(value: unknown): value is SealedOutput {
+	return record(value) && typeof value.path === "string" && typeof value.sealedName === "string" &&
+		/^[a-f0-9-]{36}$/.test(value.sealedName) && typeof value.sha256 === "string" && /^[a-f0-9]{64}$/.test(value.sha256) &&
+		typeof value.bytes === "number" && Number.isSafeInteger(value.bytes) && value.bytes >= 0 && value.bytes <= 10 * 1024 * 1024 &&
+		typeof value.mediaType === "string" && typeof value.name === "string";
+}
+function errorCode(error: unknown): SnapshotError {
+	if (error instanceof SyntaxError) return "snapshot_unknown";
+	if (error instanceof CollaborationExtensionError) {
+		switch (error.code) {
+			case "invalid_snapshot": case "snapshot_conflict": case "binding_conflict": case "request_blocked":
+			case "read_only_continuation": case "agent_knowledge_locked": case "snapshot_not_quiescent":
+			case "file_not_found": case "file_changed": case "file_not_regular": case "file_linked":
+			case "path_forbidden": case "file_too_large": case "snapshot_io_failed": case "snapshot_unknown": return error.code;
+			case "binding_missing": return "binding_conflict";
+			default: throw error;
+		}
+	}
+	if (error instanceof AgentContentError) {
+		switch (error.code) {
+			case "file_changed": return "file_changed";
+			case "not_single_regular_file": return "file_not_regular";
+			case "too_large": return "file_too_large";
+			case "invalid_path": case "invalid_filename": case "unsafe_root": return "path_forbidden";
+			case "unsafe_path": return error.errno === 2 ? "file_not_found" : "path_forbidden";
+			case "file_exists": return "snapshot_conflict";
+			default: return "snapshot_io_failed";
+		}
+	}
+	throw error;
+}
+
+// allow: SIZE_OK - T5 path-stage reuses this T4-owned SDK queue and policy closure; unrelated snapshot/writer extraction is forbidden.
+/** Actual T3 bytes and immutable receipts. SDK writer installation remains the caller's separate obligation. */
+export class CollaborationSnapshots {
+	private readonly running = new Map<string, { readonly payload: string; readonly promise: Promise<SnapshotResult> }>();
+	private readonly operations = new Set<Promise<unknown>>();
+	constructor(private readonly runtime: SnapshotRuntime) {
+		runtime.control.installSnapshots(data => this.snapshot(data), () => this.operations.size);
+	}
+	/** Count the actual operation promise, never a tool_call/tool_result interval or an early abort rejection. */
+	async track<T>(operation: (assertWritable: () => void) => Promise<T>): Promise<T> {
+		const captured = this.runtime.control.capture();
+		captured.assertWritable();
+		const running = operation(captured.assertWritable);
+		this.operations.add(running);
+		try { return await running; } finally { this.operations.delete(running); }
+	}
+	/** The logical outputs area never falls back to agent-wide public outputs. */
+	outputRoot(): string | undefined {
+		const captured = this.runtime.control.capture();
+		if (!captured.requestId || !captured.binding.agentId || captured.binding.readContinuationId) return undefined;
+		if (![captured.requestId, captured.binding.agentId].every(segment)) return fail("path_forbidden");
+		return join(this.runtime.root, ".collaboration", "work", captured.binding.agentId, String(captured.binding.lifecycleEpoch), captured.requestId);
+	}
+	install(api: CollaborationApi, input: { readonly sdk: NativeFileSdk; readonly cwd: string; readonly policy?: FilePolicy }): void {
+		const { sdk, cwd, policy } = input;
+		this.runtime.control.installStage(async (path, ctx, signal) => {
+			const captured = this.runtime.control.captureNative(ctx);
+			captured.assertWritable();
+			if (path.includes("\0") || path.split(/[\\/]/).some(part => part === ".." || part === ".collaboration" || part === ".file-trash" || part === ".trash")) return fail("path_forbidden");
+			const logical = relative(cwd, resolve(cwd, path)), parts = logical.split("/");
+			if (captured.binding.agentId !== null && (!parts.every(segment) || !["source", "outputs"].includes(parts[0] ?? ""))) return fail("path_forbidden");
+			const privateRoot = captured.binding.activationId !== null && parts[0] === "outputs" ? this.outputRoot() : undefined;
+			if (captured.binding.activationId !== null && parts[0] === "outputs" && !privateRoot) return fail("path_forbidden");
+			const nativeCwd = privateRoot ?? cwd, target = resolve(nativeCwd, captured.binding.agentId === null ? path : logical);
+			const fence = () => {
+				captured.assertWritable();
+				if (signal?.aborted) return fail("binding_conflict");
+				if (captured.binding.agentId !== null) this.runtime.assertKnowledgeLock();
+			};
+			// The same native reader/policy admits the path. Capture its actual bytes, not its truncated display.
+			return this.track(async () => {
+				const supplied = await sdk.withFileMutationQueue(target, async () => {
+					fence();
+					using core = new AgentContentFiles(dirname(target));
+					let bytes: Buffer | undefined;
+					const load = (actual: string): Buffer => {
+						fence(); if (actual !== target) return fail("path_forbidden");
+						bytes ??= core.read([target.slice(dirname(target).length + 1)]);
+						return bytes;
+					};
+					const reader = sdk.createReadOnlyTools(nativeCwd, { read: {
+						...(policy ? { filesystemPolicy: async (request: Parameters<FilePolicy>[0]) => {
+							fence();
+							if (request.canonicalPath !== target) return { allow: false as const, reason: "path_forbidden" };
+							return policy({ ...request, canonicalPath: privateRoot ? resolve(cwd, logical) : request.canonicalPath });
+						} } : {}),
+						operations: { access: async actual => { load(actual); }, readFile: async actual => load(actual),
+							detectImageMimeType: async actual => sniffImage(load(actual))?.type },
+					} }).find(tool => tool.name === "read");
+					if (!reader) throw new CollaborationExtensionError("native_read_definition_missing");
+					await reader.execute("collaboration-stage", { path: target }, undefined, undefined, ctx);
+					fence();
+					if (!bytes) return fail("file_not_found");
+					return bytes;
+				});
+				fence();
+				return { bytes: supplied, path: captured.binding.agentId === null ? path : logical,
+					name: target.slice(dirname(target).length + 1), mediaType: sniffImage(supplied)?.type ?? "application/octet-stream" };
+			});
+		});
+		const read = (root: string, options?: ReadOptions): CollaborationTool => {
+			// The public composed factory preserves the SDK's selectedReadFolder default as well as its native reader.
+			const tool = sdk.createReadOnlyTools(root, { read: options }).find(tool => tool.name === "read");
+			if (!tool) throw new CollaborationExtensionError("native_read_definition_missing");
+			return { ...sdk.createReadToolDefinition(root, options), execute: tool.execute };
+		};
+		const factories = { read, write: sdk.createWriteToolDefinition, edit: sdk.createEditToolDefinition };
+		for (const kind of ["read", "write", "edit"] as const) {
+			const factory = factories[kind], ordinary = factory(cwd, policy ? { filesystemPolicy: policy } : undefined);
+			api.registerTool({ ...ordinary, serverPinned: true, execute: async (id, params, signal, update, ctx) => {
+				if (!this.runtime.control.isPeer()) return ordinary.execute(id, params, signal, update, ctx);
+				const captured = this.runtime.control.captureNative(ctx);
+				captured.assertWritable();
+				if (!record(ctx) || !captured.binding.agentId || !captured.requestId) return fail("read_only_continuation");
+				if (typeof params.path !== "string" || params.path.includes("\0") || params.path.split(/[\\/]/).some(part => part === "..")) return fail("path_forbidden");
+				const logical = relative(cwd, resolve(cwd, params.path));
+				const segments = logical.split("/");
+				if (isAbsolute(logical) || !segments.every(segment)) return fail("path_forbidden");
+				const output = segments[0] === "outputs";
+				if (!output && (kind !== "read" || !["source", "notes", "MEMORY.md"].includes(segments[0] ?? ""))) return fail("path_forbidden");
+				const privateRoot = this.outputRoot();
+				if (!privateRoot) return fail("read_only_continuation");
+				const nativeCwd = output ? privateRoot : cwd, target = join(nativeCwd, logical);
+				const parts = relative(this.runtime.root, target).split("/");
+				if (!parts.every(segment)) return fail("path_forbidden");
+				const fence = () => {
+					captured.assertWritable();
+					if (signal?.aborted) return fail("binding_conflict");
+					this.runtime.assertKnowledgeLock();
+				};
+				return this.track(async () => {
+					using core = new AgentContentFiles(this.runtime.root);
+					let loaded: { readonly bytes: Buffer; readonly identity: ContentVersion } | undefined;
+					const exact = (path: string) => { fence(); if (path !== target) fail("path_forbidden"); };
+					const operations: FileOperations = {
+						access: async path => { exact(path); loaded = core.readWithIdentity(parts); },
+						readFile: async path => { exact(path); loaded ??= core.readWithIdentity(parts); return loaded.bytes; },
+						detectImageMimeType: async path => { exact(path); loaded ??= core.readWithIdentity(parts); return sniffImage(loaded.bytes)?.type; },
+						// Native mkdir admission is checked here; the descriptor core creates missing directories with its write fence.
+						mkdir: async path => { fence(); if (path !== dirname(target)) fail("path_forbidden"); },
+						writeFile: async (path, content) => {
+							exact(path);
+							core.write({ segments: parts, bytes: Buffer.from(content),
+								...(loaded ? { expectedIdentity: loaded.identity } : {}), beforeMutation: fence });
+						},
+					};
+					const tool = factory(nativeCwd, { operations });
+					// Preserve all native getters, updates and render/result behavior; only this invocation's cwd changes.
+					const nativeCtx = new Proxy(ctx, { get: (object, key, receiver) => key === "cwd" ? nativeCwd : Reflect.get(object, key, receiver) });
+					// A native read can reject early on abort while its image/helper still runs. Drain the real promise instead.
+					const result = await tool.execute(id, { ...params, path: logical }, kind === "read" ? undefined : signal, update, nativeCtx);
+					fence();
+					return result;
+				});
+			} });
+		}
+	}
+	async snapshot(data: unknown): Promise<SnapshotResult> {
+		try {
+			const call = parseCall(data);
+			const captured = this.runtime.control.snapshotCapture(call);
+			const key = collaborationDigest([call.bindingDigest, call.operationKey]), payload = collaborationDigest(call);
+			const existing = this.running.get(key);
+			if (existing) return existing.payload === payload ? existing.promise : { ok: false, error: "snapshot_conflict" };
+			const promise = this.capture({ call, key, payload, assertCurrent: captured.assertCurrent, agentId: captured.binding.agentId,
+				lifecycleEpoch: captured.binding.lifecycleEpoch }).catch((error: unknown): SnapshotResult => ({ ok: false, error: errorCode(error) }));
+			this.running.set(key, { payload, promise });
+			try { return await promise; } finally { this.running.delete(key); }
+		} catch (error) { return { ok: false, error: errorCode(error) }; }
+	}
+	private async capture(input: { readonly call: SnapshotCall; readonly key: string; readonly payload: string; readonly assertCurrent: () => void;
+		readonly agentId: string | null; readonly lifecycleEpoch: number }): Promise<SnapshotResult> {
+		// Freeze belongs to the exact registered result execute. Drain happens before taking any file queue.
+		await Promise.allSettled([...this.operations]);
+		input.assertCurrent();
+		this.runtime.assertKnowledgeLock();
+		if (input.agentId === null || !segment(input.agentId)) return fail("binding_conflict");
+		using core = new AgentContentFiles(this.runtime.root);
+		const receipt = [".collaboration", "snapshots", input.key];
+		try {
+			core.publish({ directory: receipt, name: "claim.json", bytes: Buffer.from(JSON.stringify({ payload: input.payload })),
+				immutable: true, exact: true });
+		} catch (error) {
+			if (!(error instanceof AgentContentError) || error.code !== "file_exists") throw error;
+			const claim: unknown = JSON.parse(core.read([...receipt, "claim.json"]).toString());
+			if (!record(claim) || claim.payload !== input.payload) return fail("snapshot_conflict");
+			let completed: unknown;
+			try { completed = JSON.parse(core.read([...receipt, "complete.json"]).toString()); }
+			catch (readError) {
+				if (readError instanceof AgentContentError && readError.errno === 2) return fail("snapshot_unknown");
+				throw readError;
+			}
+			if (!record(completed) || completed.ok !== true || completed.snapshotKey !== input.key ||
+				completed.requestId !== input.call.requestId || completed.bindingDigest !== input.call.bindingDigest ||
+				!Array.isArray(completed.files) || !completed.files.every(sealed) ||
+				completed.files.length !== input.call.paths.length ||
+				completed.files.some((file, index) => file.path !== input.call.paths[index])) return fail("snapshot_unknown");
+			for (const file of completed.files) {
+				const bytes = core.read([".collaboration", "artifacts", file.sealedName]);
+				if (bytes.length !== file.bytes || digest(bytes) !== file.sha256) return fail("file_changed");
+			}
+			input.assertCurrent(); this.runtime.assertKnowledgeLock();
+			return { ok: true, snapshotKey: input.key, requestId: input.call.requestId,
+				bindingDigest: input.call.bindingDigest, files: completed.files };
+		}
+		const work = [".collaboration", "work", input.agentId, String(input.lifecycleEpoch), input.call.requestId];
+		const outputs: SealedOutput[] = [];
+		for (const path of input.call.paths) {
+			input.assertCurrent(); this.runtime.assertKnowledgeLock();
+			const parts = [...work, ...path.split("/")];
+			const bytes = await this.runtime.queue(join(this.runtime.root, ...parts), async () => {
+				input.assertCurrent(); this.runtime.assertKnowledgeLock();
+				const bytes = core.read(parts);
+				input.assertCurrent(); this.runtime.assertKnowledgeLock();
+				return bytes;
+			});
+			// Queue is released before sealing/fsync/receipt IO. No HTTP, model or owner wait holds it.
+			input.assertCurrent(); this.runtime.assertKnowledgeLock();
+			const output = core.publish({ directory: [".collaboration", "artifacts"], name: randomUUID(), bytes, immutable: true, exact: true });
+			const checked = core.read([".collaboration", "artifacts", output.name]);
+			if (checked.length !== output.bytes || digest(checked) !== output.sha256) return fail("file_changed");
+			outputs.push({ path, sealedName: output.name, sha256: output.sha256, bytes: output.bytes,
+				mediaType: sniffImage(bytes)?.type ?? "application/octet-stream", name: path.split("/").at(-1) ?? path });
+		}
+		input.assertCurrent(); this.runtime.assertKnowledgeLock();
+		const result: SnapshotResult = { ok: true, snapshotKey: input.key, requestId: input.call.requestId,
+			bindingDigest: input.call.bindingDigest, files: outputs };
+		core.publish({ directory: receipt, name: "complete.json", bytes: Buffer.from(JSON.stringify(result)), immutable: true, exact: true });
+		return result;
+	}
+}