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

package/src/agent/api.ts

@@ -1,11 +1,13 @@
-import { existsSync, lstatSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { YAML } from "bun";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { Hub } from "../hub.ts";
 import { MEDIA_MAX_BYTES } from "../media.ts";
 import type { Store } from "../store.ts";
 import { mergeAgentDefinition, parseAgentDefinition, AgentDefinitionError, serializeAgentDefinition, type AgentDefinition } from "./definition.ts";
 import { registryMetadata } from "./fields.ts";
-import { AgentFileError, AgentFileStore, unreadableAgent } from "./files.ts";
+import { agentFileTrashName, AgentFileError, AgentFileStore, parseAgentFileTrashName, unreadableAgent } from "./files.ts";
+import { AgentContentError, AgentContentFiles, contentIdentity, numberedName, sourceName } from "./file-core.ts";
 
 class AgentApiError extends Error {
 	constructor(readonly status: number, readonly code: string) {
@@ -17,15 +19,76 @@ function object(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/** A draft keeps the editor text of a new agent; 64 KB is twice the definition cap, room for a text being edited. */
+export const DRAFT_MAX_BYTES = 65536;
+
+/** Draft ids are made by the web (12 lowercase letters or digits); nothing else reaches the file system. */
+function draftId(value: string): string {
+	if (!/^[a-z0-9]{12}$/.test(value)) throw new AgentApiError(400, "invalid_draft_id");
+	return value;
+}
+
+interface DraftBody { readonly source: string; readonly kind: "new"; readonly files: readonly { readonly name: string; readonly size: number }[] }
+
+/** The source is kept unvalidated (it is still being typed); only the shape is checked. */
+function draftBody(value: unknown): DraftBody {
+	if (!object(value) || typeof value.source !== "string" || value.kind !== "new" || !Array.isArray(value.files)) throw new AgentApiError(400, "invalid_draft");
+	const files = value.files.map((file: unknown) => {
+		if (!object(file) || typeof file.name !== "string" || typeof file.size !== "number" || !Number.isSafeInteger(file.size) || file.size < 0) throw new AgentApiError(400, "invalid_draft");
+		return { name: file.name, size: file.size };
+	});
+	if (Buffer.byteLength(value.source) > DRAFT_MAX_BYTES) throw new AgentApiError(413, "too_large");
+	return { source: value.source, kind: "new", files };
+}
+
+/** The name a half-typed draft shows in the list, or null while its frontmatter does not parse yet. */
+function draftName(source: string): string | null {
+	const frontmatter = /^---\r?\n([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m.exec(source)?.[1];
+	if (frontmatter === undefined) return null;
+	let parsed: unknown;
+	try {
+		parsed = YAML.parse(frontmatter);
+	} catch {
+		return null;
+	}
+	return object(parsed) && typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : null;
+}
+
+type KnowledgeArea = "source" | "outputs" | "notes" | "memory" | "other";
+
+/** The area of a path relative to knowledge/: uploads, results, notes, MEMORY.md, or anything else. */
+function knowledgeArea(parts: readonly string[]): KnowledgeArea {
+	if (parts.length === 1 && parts[0] === "MEMORY.md") return "memory";
+	const top = parts[0];
+	return top === "source" || top === "outputs" || top === "notes" ? top : "other";
+}
+
+/** RFC 5987 value: encodeURIComponent leaves ' ( ) * as they are, which the header grammar does not allow. */
+function attachment(name: string): string {
+	return `attachment; filename*=UTF-8''${encodeURIComponent(name).replace(/['()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)}`;
+}
+
 async function source(req: Request): Promise<string> {
 	const value: unknown = await req.json();
 	if (!object(value) || typeof value.source !== "string") throw new AgentApiError(400, "source_required");
 	return value.source;
 }
 
+/**
+ * The text the editor holds, for POST /api/agents/preview: a text up to the draft size; a save's own limit is reported in the
+ * answer. `kind: "new"` marks the create screen's text, which may not have its name and description yet (agent-ux int).
+ */
+function previewSource(value: unknown): { readonly source: string; readonly kind: "agent" | "new" } {
+	if (!object(value) || typeof value.source !== "string") throw new AgentApiError(400, "source_required");
+	if (value.kind !== undefined && value.kind !== "agent" && value.kind !== "new") throw new AgentApiError(400, "invalid_kind");
+	if (Buffer.byteLength(value.source) > DRAFT_MAX_BYTES) throw new AgentApiError(413, "too_large");
+	return { source: value.source, kind: value.kind === "new" ? "new" : "agent" };
+}
+
 /** Only metadata leaves list endpoints; definition text is returned by the detail endpoint. */
 export class AgentApi {
 	private readonly deleting = new Set<string>();
+	private lastTime = 0;
 
 	constructor(private readonly files: AgentFileStore, private readonly store: Store, private readonly hub: Hub) {}
 
@@ -41,21 +104,62 @@ export class AgentApi {
 		const applied = this.store.eventsAfter(conv.id, this.store.lastSeq(conv.id, "session.rotated"))
 			.filter((event) => event.type === "agent.applied").at(-1)?.data;
 		const appliedSha = object(applied) && typeof applied.sha === "string" ? applied.sha : null;
+		const opened = this.hub.hasSession(conv.id) || applied !== undefined;
+		const stale = opened && appliedSha !== merged.sha;
 		return {
 			id, name: definition.fields.name, description: definition.fields.description, icon: definition.fields.icon ?? null,
-			convId: conv.id, definitionSha: merged.sha, stale: appliedSha !== null && appliedSha !== merged.sha,
+			convId: conv.id, definitionSha: merged.sha, appliedSha, stale,
+			...(opened && appliedSha === null ? { staleReason: "unknown" } : {}),
 		};
 	}
 
-	/** The definition text, the merged result and the field registry the editor draws its widgets from. */
+	/**
+	 * The definition text, the merged result, the shared layer as this gateway parsed it (`defaultsFields`: what the merge applied
+	 * under the agent's own values, which the editor reads instead of parsing defaults.md itself) and the field registry.
+	 */
 	private detail(id: string) {
 		const definition = this.files.read(id);
+		const defaults = this.files.readDefaults();
 		return { ...this.summary(id, definition), source: serializeAgentDefinition(definition),
-			...mergeAgentDefinition(definition, this.files.readDefaults()), registry: registryMetadata() };
+			...mergeAgentDefinition(definition, defaults), defaultsFields: defaults?.fields ?? {}, registry: registryMetadata(), lastDaily: this.lastDaily(id) };
+	}
+
+	/** The date of the newest notes/daily/YYYY-MM-DD.md, or null; a linked folder or note does not count. */
+	private lastDaily(id: string): string | null {
+		let folder: string;
+		try {
+			folder = this.path([id, "knowledge", "notes", "daily"]);
+		} catch (error) {
+			if (error instanceof AgentApiError) return null;
+			throw error;
+		}
+		if (!existsSync(folder)) return null;
+		const dates = readdirSync(folder).filter((name) => /^\d{4}-\d{2}-\d{2}\.md$/.test(name) && lstatSync(join(folder, name)).isFile()).sort();
+		return dates.at(-1)?.slice(0, 10) ?? null;
+	}
+
+	/**
+	 * The editor's current text evaluated exactly as a save reads it back (agent-ux todo 12): schema 1 filled in, parsed and
+	 * validated by this gateway's parser, merged with the current defaults.md; nothing is written. Text a save would refuse
+	 * answers `valid: false` with the save's field-level code, so the editor shows no guess for it. A new agent's text without
+	 * its name or description yet is evaluated with a placeholder for them (agent-ux int); the answer leaves those fields out.
+	 */
+	private preview({ source, kind }: { readonly source: string; readonly kind: "agent" | "new" }) {
+		try {
+			const { definition, filled } = kind === "new" ? this.files.parseNew(source) : { definition: this.files.parse(source), filled: [] };
+			const merged = mergeAgentDefinition(definition, this.files.readDefaults());
+			const own = (entries: object) => Object.fromEntries(Object.entries(entries).filter(([name]) => !filled.includes(name)));
+			return { valid: true, fields: own(merged.fields), origins: own(merged.origins) };
+		} catch (error) {
+			if (error instanceof AgentDefinitionError) return { valid: false, error: "invalid_agent_definition", field: error.field };
+			throw error;
+		}
 	}
 
+	/** defaults.md as text (what the defaults editor edits) and as this gateway parsed it (`fields`: the layer the create screen reads under a new agent's values). */
 	private defaults() {
-		return { source: this.files.readDefaults()?.source ?? "---\n{}\n---\n", registry: registryMetadata() };
+		const defaults = this.files.readDefaults();
+		return { source: defaults?.source ?? "---\n{}\n---\n", fields: defaults?.fields ?? {}, registry: registryMetadata() };
 	}
 
 	private list() {
@@ -79,13 +183,180 @@ export class AgentApi {
 		return path;
 	}
 
+	private timestamp(): string {
+		this.lastTime = Math.max(Date.now(), this.lastTime + 1);
+		return new Date(this.lastTime).toISOString();
+	}
+
+	/** A request path relative to knowledge/: every part checked by path() (no links, no ".."), with its area. */
+	private knowledge(id: string, value: unknown): { readonly parts: string[]; readonly file: string; readonly area: KnowledgeArea } {
+		if (typeof value !== "string") throw new AgentApiError(400, "invalid_path");
+		const parts = value.split("/");
+		return { parts, file: this.path([id, "knowledge", ...parts]), area: knowledgeArea(parts) };
+	}
+
+	/** The size of a regular file; a missing one is 404 file_not_found, anything else 400 `notFile`. */
+	private regularFile(file: string, notFile: string): number {
+		try {
+			const stat = lstatSync(file);
+			if (!stat.isFile()) throw new AgentApiError(400, notFile);
+			return stat.size;
+		} catch (error) {
+			if (error instanceof Error && "code" in error && error.code === "ENOENT") throw new AgentApiError(404, "file_not_found");
+			throw error;
+		}
+	}
+
+	/** The first of `name`, `name (2)` ... that nothing (no file, folder or link) takes in the folder `parts`. */
+	private freePath(parts: readonly string[], name: string): { readonly name: string; readonly file: string } {
+		for (let n = 1; n <= 1000; n++) {
+			const candidate = numberedName(name, n);
+			const file = this.path([...parts, candidate]);
+			if (!existsSync(file)) return { name: candidate, file };
+		}
+		throw new AgentApiError(409, "file_exists");
+	}
+
+	/**
+	 * Knowledge file actions. Delete moves a regular file of source/ or outputs/ to agents/.file-trash/<id>/ (outside
+	 * .trash/, whose folders the archived-agent cleanup takes whole); housekeeping offers it to the operator after 30 days.
+	 */
+	private async fileAction(req: Request, id: string, action: string, entryPart: string | undefined): Promise<Response> {
+		if (action === "download" && req.method === "GET") {
+			const query = new URL(req.url).searchParams, artifactId = query.get("artifactId");
+			if (artifactId !== null) {
+				if (!artifactId || query.has("path") || !query.get("requestId")) throw new AgentApiError(400, "invalid_artifact_selector");
+				const requestId = query.get("requestId") ?? "";
+				const conv = this.conversation(id), request = this.store.getAgentRequest(requestId);
+				const artifact = this.store.agentArtifact(artifactId);
+				if (!request || !artifact || artifact.requestId !== requestId) throw new AgentApiError(404, "artifact_not_found");
+				if (request.requesterConv !== conv.id && request.targetConv !== conv.id) throw new AgentApiError(403, "request_forbidden");
+				const grant = this.store.agentArtifactGrant(artifactId, conv.id, requestId);
+				if (!grant) throw new AgentApiError(403, "artifact_forbidden");
+				if (grant.revoked || artifact.state === "trashed") throw new AgentApiError(410, "artifact_revoked");
+				// T3's readGranted requires a live native binding. An owner download must not fabricate one.
+				return Response.json({ error: "capability_unavailable", capability: "owner_artifact_release" }, { status: 503 });
+			}
+			const target = this.knowledge(id, new URL(req.url).searchParams.get("path"));
+			if (target.area === "other") throw new AgentApiError(400, "file_not_readable");
+			this.regularFile(target.file, "not_a_file");
+			return new Response(readFileSync(target.file), {
+				headers: { "Content-Type": "application/octet-stream", "Content-Disposition": attachment(target.parts.at(-1) ?? "file") },
+			});
+		}
+		if (action === "trash" && req.method === "GET") {
+			const folder = this.path([".file-trash", id]);
+			if (!existsSync(folder)) return Response.json([]);
+			const rows = readdirSync(folder).flatMap((entry) => {
+				const parsed = parseAgentFileTrashName(entry);
+				const stat = lstatSync(join(folder, entry));
+				return parsed === null || !stat.isFile() ? [] : [{ entry, path: parsed.path, size: stat.size, deletedAt: new Date(parsed.deletedAt).toISOString() }];
+			});
+			return Response.json(rows.sort((a, b) => b.deletedAt.localeCompare(a.deletedAt) || b.entry.localeCompare(a.entry)));
+		}
+		if (req.method !== "POST") throw new AgentApiError(405, "method_not_allowed");
+		if (action === "delete") {
+			const body: unknown = await req.json();
+			const target = this.knowledge(id, object(body) ? body.path : undefined);
+			if ((target.area !== "source" && target.area !== "outputs") || target.parts.at(-1)?.endsWith(".lock")) throw new AgentApiError(400, "file_not_deletable");
+			this.regularFile(target.file, "file_not_deletable");
+			const folder = this.path([".file-trash", id]);
+			let entry = agentFileTrashName(target.parts.join("/"), this.timestamp());
+			if (Buffer.byteLength(entry) > 255) throw new AgentApiError(400, "path_too_long");
+			this.conversation(id);
+			if (this.deleting.has(id)) throw new AgentApiError(409, "agent_busy");
+			mkdirSync(folder, { recursive: true });
+			while (existsSync(this.path([".file-trash", id, entry]))) entry = agentFileTrashName(target.parts.join("/"), this.timestamp());
+			renameSync(target.file, this.path([".file-trash", id, entry]));
+			this.hub.agentUpdated(this.summary(id, this.files.read(id)));
+			return Response.json({ entry });
+		}
+		if (action.startsWith("trash/") && entryPart !== undefined) {
+			const entry = decodeURIComponent(entryPart);
+			const parsed = parseAgentFileTrashName(entry);
+			if (parsed === null) throw new AgentApiError(400, "invalid_trash_entry");
+			const archived = this.path([".file-trash", id, entry]);
+			const target = this.knowledge(id, parsed.path);
+			if (target.area !== "source" && target.area !== "outputs") throw new AgentApiError(400, "invalid_trash_entry");
+			this.regularFile(archived, "invalid_trash_entry");
+			this.conversation(id);
+			if (this.deleting.has(id)) throw new AgentApiError(409, "agent_busy");
+			const parent = target.parts.slice(0, -1);
+			mkdirSync(this.path([id, "knowledge", ...parent]), { recursive: true });
+			const free = this.freePath([id, "knowledge", ...parent], target.parts.at(-1) ?? "");
+			renameSync(archived, free.file);
+			this.hub.agentUpdated(this.summary(id, this.files.read(id)));
+			return Response.json({ path: [...parent, free.name].join("/") });
+		}
+		throw new AgentApiError(405, "method_not_allowed");
+	}
+
+	/** Moves a draft to agents/.drafts-trash/ (outside .trash/); housekeeping offers it to the operator after 30 days. */
+	private archiveDraft(id: string): boolean {
+		const file = this.path([".drafts", `${id}.json`]);
+		if (!existsSync(file)) return false;
+		mkdirSync(this.path([".drafts-trash"]), { recursive: true });
+		let entry = `${this.timestamp()}-${id}.json`;
+		while (existsSync(this.path([".drafts-trash", entry]))) entry = `${this.timestamp()}-${id}.json`;
+		renameSync(file, this.path([".drafts-trash", entry]));
+		return true;
+	}
+
+	/** An id whose draft was archived (created into an agent or discarded) is closed: a late save must not bring it back. */
+	private draftClosed(id: string): boolean {
+		const trash = this.path([".drafts-trash"]);
+		return existsSync(trash) && readdirSync(trash).some((name) => name.endsWith(`-${id}.json`));
+	}
+
+	private drafts() {
+		const folder = this.path([".drafts"]);
+		if (!existsSync(folder)) return [];
+		const rows = readdirSync(folder).filter((name) => /^[a-z0-9]{12}\.json$/.test(name)).flatMap((name) => {
+			try {
+				const draft: unknown = JSON.parse(readFileSync(this.path([".drafts", name]), "utf8"));
+				if (!object(draft) || typeof draft.updatedAt !== "string") return [];
+				return [{ id: name.slice(0, 12), name: typeof draft.name === "string" ? draft.name : null, updatedAt: draft.updatedAt }];
+			} catch (error) {
+				if (error instanceof SyntaxError || (error instanceof AgentApiError && error.code === "symlink_not_allowed")) return [];
+				throw error;
+			}
+		});
+		return rows.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id));
+	}
+
+	private async draft(req: Request, id: string): Promise<Response> {
+		const file = this.path([".drafts", `${id}.json`]);
+		if (req.method === "GET") {
+			if (!existsSync(file)) throw new AgentApiError(404, "draft_not_found");
+			return new Response(readFileSync(file), { headers: { "Content-Type": "application/json" } });
+		}
+		if (req.method === "DELETE") {
+			if (!this.archiveDraft(id)) throw new AgentApiError(404, "draft_not_found");
+			return Response.json({ ok: true });
+		}
+		if (req.method !== "PUT") throw new AgentApiError(405, "method_not_allowed");
+		if (Number(req.headers.get("content-length")) > DRAFT_MAX_BYTES * 4 + 65536) throw new AgentApiError(413, "too_large");
+		const body = draftBody(await req.json());
+		// Checked right before the write (no await between): a create or discard that archived the draft meanwhile wins.
+		if (!existsSync(file) && this.draftClosed(id)) throw new AgentApiError(409, "draft_closed");
+		const draft = { id, name: draftName(body.source), ...body, updatedAt: this.timestamp() };
+		mkdirSync(this.path([".drafts"]), { recursive: true });
+		writeFileSync(file, JSON.stringify(draft));
+		return Response.json(draft);
+	}
+
 	private tree(id: string) {
-		const entries: { path: string; type: "file" | "directory"; size: number }[] = [];
+		const copies = new Set(this.store.eventsAfter(this.conversation(id).id, 0).flatMap(event =>
+			event.type === "agent.collaboration.materialized" && object(event.data) && typeof event.data.fileIdentity === "string" ? [event.data.fileIdentity] : []));
+		const entries: { path: string; type: "file" | "directory"; size: number; area: KnowledgeArea; modifiedAt: string | null; origin?: "user-upload" | "collaboration-copy" }[] = [];
 		const walk = (parts: readonly string[]) => {
 			for (const name of readdirSync(this.path([id, "knowledge", ...parts]))) {
-				const stat = lstatSync(this.path([id, "knowledge", ...parts, name]));
+				const stat = lstatSync(this.path([id, "knowledge", ...parts, name]), { bigint: true });
 				if (!stat.isFile() && !stat.isDirectory()) throw new AgentApiError(400, "unsupported_file");
-				entries.push({ path: [...parts, name].join("/"), type: stat.isDirectory() ? "directory" : "file", size: stat.isFile() ? stat.size : 0 });
+				// The modified time rides along for the editor's outputs list (agent-ux todo 17); a folder has none.
+				const path = [...parts, name].join("/");
+				entries.push({ path, type: stat.isDirectory() ? "directory" : "file", size: stat.isFile() ? Number(stat.size) : 0, area: knowledgeArea([...parts, name]), modifiedAt: stat.isFile() ? stat.mtime.toISOString() : null,
+					...(stat.isFile() && knowledgeArea([...parts, name]) === "source" ? { origin: copies.has(contentIdentity(stat)) ? "collaboration-copy" as const : "user-upload" as const } : {}) });
 				if (stat.isDirectory()) walk([...parts, name]);
 			}
 		};
@@ -93,6 +364,25 @@ export class AgentApi {
 		return entries;
 	}
 
+	/**
+	 * Restores an archive entry beside a live agent of the same id. The entry's own conversation comes back only while it is
+	 * still hidden (its agent is gone); a conversation that a live agent shows stays with it, and a new one is opened.
+	 */
+	private restoreAs(entry: string, oldId: string): Response {
+		const visible = this.store.listConversations(false);
+		const hidden = this.store.listConversations(true).find((row) => row.agentId === oldId && !visible.some((shown) => shown.id === row.id));
+		const id = this.files.restoreAs(entry);
+		// A new id is a new agent (C9): managed with zero grants; the archived agent's grants stay with its old id.
+		this.store.toolPermissions.startManaged(id);
+		if (hidden) {
+			this.store.setConversationAgent(hidden.id, id);
+			this.store.setConversationHidden(hidden.id, false);
+		} else {
+			this.hub.createConversation(String(this.files.read(id).fields.name), id);
+		}
+		return this.changed(id);
+	}
+
 	private changed(id: string) {
 		const detail = this.detail(id);
 		this.hub.agentUpdated(this.summary(id, this.files.read(id)));
@@ -106,11 +396,29 @@ export class AgentApi {
 			if (path === "/api/agents") {
 				if (req.method === "GET") return Response.json(this.list());
 				if (req.method !== "POST") throw new AgentApiError(405, "method_not_allowed");
-				const id = this.files.create(await source(req));
+				const body: unknown = await req.json();
+				if (!object(body) || typeof body.source !== "string") throw new AgentApiError(400, "source_required");
+				if (body.draftId !== undefined && typeof body.draftId !== "string") throw new AgentApiError(400, "invalid_draft_id");
+				const fromDraft = body.draftId === undefined ? null : draftId(body.draftId);
+				const id = this.files.create(body.source);
+				// New agents start managed with zero grants; tools.web in the file or in defaults.md grants nothing (C9).
+				this.store.toolPermissions.startManaged(id);
 				const definition = this.files.read(id);
 				this.hub.createConversation(String(definition.fields.name), id);
+				if (fromDraft !== null) this.archiveDraft(fromDraft);
 				return new Response((await this.changed(id)).body, { status: 201, headers: { "Content-Type": "application/json" } });
 			}
+			if (path === "/api/agents/preview") {
+				if (req.method !== "POST") throw new AgentApiError(405, "method_not_allowed");
+				if (Number(req.headers.get("content-length")) > DRAFT_MAX_BYTES * 4 + 65536) throw new AgentApiError(413, "too_large");
+				return Response.json(this.preview(previewSource(await req.json())));
+			}
+			if (path === "/api/agents/drafts") {
+				if (req.method !== "GET") throw new AgentApiError(405, "method_not_allowed");
+				return Response.json(this.drafts());
+			}
+			const draft = /^\/api\/agents\/drafts\/([^/]+)$/.exec(path);
+			if (draft?.[1]) return await this.draft(req, draftId(decodeURIComponent(draft[1])));
 			if (path === "/api/agents/defaults") {
 				if (req.method === "GET") return Response.json(this.defaults());
 				if (req.method !== "PUT") throw new AgentApiError(405, "method_not_allowed");
@@ -137,11 +445,28 @@ export class AgentApi {
 				const entry = decodeURIComponent(restore[1]);
 				const id = /^([a-f0-9]{8})-/.exec(entry)?.[1];
 				if (!id) throw new AgentApiError(400, "invalid_trash_entry");
+				const text = await req.text();
+				const body: unknown = text.trim() ? JSON.parse(text) : {};
+				if (!object(body) || (body.newId !== undefined && typeof body.newId !== "boolean")) throw new AgentApiError(400, "invalid_request");
+				if (body.newId === true) return this.restoreAs(entry, id);
 				const conv = this.conversation(id, false);
-				this.files.restore(entry);
+				try {
+					this.files.restore(entry);
+				} catch (error) {
+					if (error instanceof AgentFileError && error.code === "exists") return Response.json({ error: "exists", id }, { status: 409 });
+					throw error;
+				}
+				// A restored agent is a new lifecycle: earlier requests, grants and cancellations never revive.
+				this.store.advanceAgentLifecycle(id, this.store.ensureAgentLifecycle(id));
 				this.store.setConversationHidden(conv.id, false);
 				return this.changed(id);
 			}
+			const fileRoute = /^\/api\/agents\/([a-f0-9]{8})\/files\/(delete|trash|download|trash\/([^/]+)\/restore)$/.exec(path);
+			if (fileRoute?.[1] && fileRoute[2]) {
+				this.conversation(fileRoute[1]);
+				if (this.deleting.has(fileRoute[1])) throw new AgentApiError(409, "agent_busy");
+				return await this.fileAction(req, fileRoute[1], fileRoute[2], fileRoute[3]);
+			}
 			const match = /^\/api\/agents\/([a-f0-9]{8})(?:\/(clone|delete|files|source))?$/.exec(path);
 			const id = match?.[1];
 			if (!id) throw new AgentApiError(404, "not_found");
@@ -159,6 +484,8 @@ export class AgentApi {
 			if (action === "files" && req.method === "GET") return Response.json(this.tree(id));
 			if (action === "clone" && req.method === "POST") {
 				const cloned = this.files.clone(id);
+				// A clone never copies the source agent's grants or legacy scope (C9, Q09).
+				this.store.toolPermissions.startManaged(cloned);
 				this.hub.createConversation(String(this.files.read(cloned).fields.name), cloned);
 				return this.changed(cloned);
 			}
@@ -167,6 +494,8 @@ export class AgentApi {
 				this.conversation(id);
 				if (!object(body) || body.name !== this.files.read(id).fields.name) throw new AgentApiError(400, "name_mismatch");
 				if (this.deleting.has(id)) throw new AgentApiError(409, "agent_busy");
+				// Open collaboration obligations keep the agent and its files; cancel or let them finish, then retry.
+				if (this.store.agentCollaborationBusy(this.conversation(id).id)) throw new AgentApiError(409, "agent_collaboration_busy");
 				this.deleting.add(id);
 				try {
 					const conv = this.conversation(id);
@@ -184,22 +513,18 @@ export class AgentApi {
 				const file = form.get("file");
 				if (!(file instanceof File) || file.size === 0) throw new AgentApiError(400, "missing_file");
 				if (file.size > MEDIA_MAX_BYTES) throw new AgentApiError(413, "too_large");
-				// Reject traversal rather than silently turning it into a different name.
-				if (!file.name || file.name.startsWith(".") || /[/\\\0]/.test(file.name)) throw new AgentApiError(400, "invalid_filename");
-				let name = "";
-				for (const character of file.name.replace(/[^\p{L}\p{N}._-]/gu, "_")) {
-					if (Buffer.byteLength(name + character) > 180) break;
-					name += character;
-				}
+				const name = sourceName(file.name);
 				const bytes = new Uint8Array(await file.arrayBuffer());
 				this.conversation(id);
 				if (this.deleting.has(id)) throw new AgentApiError(409, "agent_busy");
-				writeFileSync(this.path([id, "knowledge", "source", name]), bytes, { flag: "wx" });
+				using content = new AgentContentFiles(this.files.root);
+				const free = content.publish({ directory: [id, "knowledge", "source"], name, bytes, immutable: false });
 				this.hub.agentUpdated(this.summary(id, this.files.read(id)));
-				return Response.json({ name, size: bytes.length }, { status: 201 });
+				return Response.json({ name: free.name, size: bytes.length }, { status: 201 });
 			}
 			throw new AgentApiError(405, "method_not_allowed");
 		} catch (error) {
+			if (error instanceof AgentContentError) return Response.json({ error: error.code }, { status: error.status });
 			if (error instanceof AgentApiError) return Response.json({ error: error.code }, { status: error.status });
 			if (error instanceof AgentDefinitionError) return Response.json({ error: "invalid_agent_definition", field: error.field }, { status: 400 });
 			if (error instanceof AgentFileError) return Response.json({ error: error.code }, { status: error.code === "exists" ? 409 : 400 });