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

package/src/agent/definition.ts

@@ -1,6 +1,8 @@
 import { YAML } from "bun";
 import { createHash } from "node:crypto";
+import { join } from "node:path";
 import { AGENT_FIELDS, type AgentField } from "./fields.ts";
+import type { ToolKey } from "./tool-permission-types.ts";
 
 export const AGENT_MAX_BYTES = 32768;
 export const AGENT_SCHEMA = 1;
@@ -84,6 +86,17 @@ export function validateAgentFields(fields: DefinitionFields, kind: DefinitionKi
 	if (typeof maxBytes === "number" && (maxBytes < 0 || maxBytes > 32768)) throw new AgentDefinitionError("memory.maxBytes", "expected 0..32768");
 	const schema = fields.schema;
 	if (schema !== undefined && schema !== AGENT_SCHEMA) throw new AgentDefinitionError("schema", "unsupported version");
+	const targets = at(fields, "collaboration.targets");
+	if (Array.isArray(targets) && (targets.some(id => typeof id !== "string" || !/^[a-f0-9]{8}$/.test(id)) || new Set(targets).size !== targets.length))
+		throw new AgentDefinitionError("collaboration.targets", "expected distinct stable agent IDs");
+}
+
+/** Save/admission callers supply their current catalogue; names never substitute for stable IDs. */
+export function validateCollaborationTargets(input: { readonly agentId: string | null; readonly fields: DefinitionFields; readonly knownIds: ReadonlySet<string> }): void {
+	const targets = at(input.fields, "collaboration.targets");
+	if (!Array.isArray(targets)) return;
+	if (targets.some(id => id === input.agentId || !input.knownIds.has(id)))
+		throw new AgentDefinitionError("collaboration.targets", "self or unknown agent");
 }
 
 /** Read-time migration seam. A missing schema is the original v1 format; never mutates the caller's object. */
@@ -91,7 +104,8 @@ export function migrateAgentFields(fields: DefinitionFields): DefinitionFields {
 	return { ...fields };
 }
 
-export function parseAgentDefinition(source: string, kind: DefinitionKind = "agent"): AgentDefinition {
+/** The frontmatter as YAML reads it and the body, before any field check (the size, the --- block and an object are checked). */
+export function readAgentFrontmatter(source: string): { readonly fields: Record<string, unknown>; readonly body: string } {
 	if (Buffer.byteLength(source, "utf8") > AGENT_MAX_BYTES) throw new AgentDefinitionError("file", "maximum 32768 bytes");
 	const match = /^---\r?\n([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m.exec(source);
 	if (!match || match.index !== 0) throw new AgentDefinitionError("frontmatter", "expected --- YAML frontmatter");
@@ -103,8 +117,13 @@ export function parseAgentDefinition(source: string, kind: DefinitionKind = "age
 	}
 	if (parsed === null) parsed = {};
 	if (!object(parsed)) throw new AgentDefinitionError("frontmatter", "expected an object");
-	validateAgentFields(parsed, kind);
-	return { fields: migrateAgentFields(parsed), body: source.slice(match[0].length), kind, source };
+	return { fields: parsed, body: source.slice(match[0].length) };
+}
+
+export function parseAgentDefinition(source: string, kind: DefinitionKind = "agent"): AgentDefinition {
+	const { fields, body } = readAgentFrontmatter(source);
+	validateAgentFields(fields, kind);
+	return { fields: migrateAgentFields(fields), body, kind, source };
 }
 
 export function serializeAgentDefinition(definition: AgentDefinition): string {
@@ -149,6 +168,49 @@ function set(fields: Record<string, unknown>, keys: readonly string[], value: un
 	if (last !== undefined) Object.defineProperty(target, last, { value, enumerable: true, writable: true, configurable: true });
 }
 
+export interface LegacyScopeGrant {
+	readonly toolKey: ToolKey;
+	readonly operations: readonly string[];
+	readonly resources: readonly string[];
+}
+
+/** One existing (pre-294) scope the owner confirms or declines on its own. `source` says where it came from. */
+export interface LegacyScopeItem {
+	readonly id: "knowledge_read" | "knowledge_write" | "history_search" | "web";
+	readonly source: "implicit" | "defaults" | "agent";
+	readonly grants: readonly LegacyScopeGrant[];
+}
+
+/**
+ * Legacy grants name the tool, not a registration: the gateway has no engine tool schema to digest. A digest that never
+ * matches a real registration makes the catalog hold such a grant as tool_changed, so its first use asks the owner again
+ * for the exact registration instead of silently binding one.
+ */
+export const LEGACY_REGISTRATION = "legacy:unbound";
+
+const legacyKey = (sourceKind: ToolKey["sourceKind"], ownerId: string, originalName: string): ToolKey =>
+	({ sourceKind, ownerId, originalName, registrationDigest: LEGACY_REGISTRATION });
+
+/**
+ * The scopes an existing agent has today (plan C9), as a list for the migration card. The implicit knowledge read (whole
+ * knowledge/, source/ stays read-only), write (outputs/, notes/, MEMORY.md) and own history search are always listed.
+ * Web is listed only for an explicit boolean `tools.web: true` from defaults.md or agent.md, with that source. Unknown
+ * YAML keys, other values and the package default never add a scope, and skills never widen tools.
+ */
+export function legacyToolScopes(merged: { readonly fields: DefinitionFields; readonly origins: Readonly<Record<string, string>> }, knowledgeRoot: string): LegacyScopeItem[] {
+	const writable = [join(knowledgeRoot, "MEMORY.md"), join(knowledgeRoot, "notes"), join(knowledgeRoot, "outputs")].map((path) => `path:${path}`);
+	const items: LegacyScopeItem[] = [
+		{ id: "knowledge_read", source: "implicit", grants: [{ toolKey: legacyKey("builtin", "engine", "read"), operations: ["read", "list"], resources: [`path:${knowledgeRoot}`] }] },
+		{ id: "knowledge_write", source: "implicit", grants: ["write", "edit"].map((name) => ({ toolKey: legacyKey("builtin", "engine", name), operations: ["write"], resources: writable })) },
+		{ id: "history_search", source: "implicit", grants: [{ toolKey: legacyKey("gateway", "gateway", "zgw_agent_history_search"), operations: ["search"], resources: [] }] },
+	];
+	const origin = merged.origins["tools.web"];
+	if (at(merged.fields, "tools.web") === true && (origin === "defaults" || origin === "agent")) {
+		items.push({ id: "web", source: origin, grants: [{ toolKey: legacyKey("builtin", "engine", "web_search"), operations: ["search"], resources: ["provider:engine/web_search"] }] });
+	}
+	return items;
+}
+
 export function mergeAgentDefinition(agent: AgentDefinition, defaults?: AgentDefinition): MergedAgentDefinition {
 	validateAgentFields(agent.fields);
 	if (defaults) validateAgentFields(defaults.fields, "defaults");

package/src/agent/fields.ts

@@ -7,11 +7,13 @@ export interface AgentField {
 	readonly applies: "gateway" | "extension";
 	readonly widget: "text" | "textarea" | "number" | "toggle" | "model" | "select" | "skills" | "group";
 	readonly forbidden: boolean;
+	/** Not drawn by the editor: the gateway writes the value itself (the schema version). */
+	readonly hidden?: boolean;
 }
 
 /** The registry owns defaults, validation types and editor metadata. Undefined means no package override. */
 export const AGENT_FIELDS: readonly AgentField[] = [
-	{ name: "schema", type: "integer", default: 1, required: false, merge: "replace", applies: "gateway", widget: "number", forbidden: false },
+	{ name: "schema", type: "integer", default: 1, required: false, merge: "replace", applies: "gateway", widget: "number", forbidden: false, hidden: true },
 	{ name: "name", type: "string", default: undefined, required: true, merge: "replace", applies: "gateway", widget: "text", forbidden: false },
 	{ name: "description", type: "string", default: undefined, required: true, merge: "replace", applies: "gateway", widget: "textarea", forbidden: false },
 	{ name: "icon", type: "string", default: undefined, required: false, merge: "replace", applies: "gateway", widget: "text", forbidden: false },
@@ -20,6 +22,8 @@ export const AGENT_FIELDS: readonly AgentField[] = [
 	{ name: "model.modelId", type: "string", default: undefined, required: false, merge: "replace", applies: "extension", widget: "text", forbidden: false },
 	{ name: "thinking", type: "string", default: undefined, required: false, merge: "replace", applies: "extension", widget: "select", forbidden: false },
 	{ name: "skills", type: "strings", default: [], required: false, merge: "replace", applies: "extension", widget: "skills", forbidden: false },
+	{ name: "collaboration", type: "object", default: {}, required: false, merge: "keys", applies: "gateway", widget: "group", forbidden: false, hidden: true },
+	{ name: "collaboration.targets", type: "strings", default: [], required: false, merge: "replace", applies: "gateway", widget: "skills", forbidden: false, hidden: true },
 	{ name: "tools", type: "object", default: {}, required: false, merge: "keys", applies: "extension", widget: "group", forbidden: false },
 	{ name: "tools.web", type: "boolean", default: false, required: false, merge: "replace", applies: "extension", widget: "toggle", forbidden: false },
 	{ name: "tools.bash", type: "boolean", default: undefined, required: false, merge: "replace", applies: "extension", widget: "toggle", forbidden: true },
@@ -35,8 +39,10 @@ export const AGENT_FIELDS: readonly AgentField[] = [
 /**
  * The registry rows as the agent API sends them with every definition answer (`registry` in GET /api/agents/:id and
  * /api/agents/defaults). The web editor draws its widgets from these rows, so a new registry row needs no web change.
- * Forbidden rows are sent marked, so the editor can refuse them before the gateway does.
+ * Forbidden rows are sent marked, so the editor can refuse them before the gateway does; hidden rows carry
+ * `hidden: true`, so the editor does not draw them (other rows omit the key).
  */
 export function registryMetadata(rows: readonly AgentField[] = AGENT_FIELDS): AgentField[] {
-	return rows.map(({ name, type, default: value, required, merge, applies, widget, forbidden }) => ({ name, type, default: value, required, merge, applies, widget, forbidden }));
+	return rows.map(({ name, type, default: value, required, merge, applies, widget, forbidden, hidden }) =>
+		({ name, type, default: value, required, merge, applies, widget, forbidden, ...(hidden === true ? { hidden: true } : {}) }));
 }

package/src/agent/file-core.ts

@@ -0,0 +1,325 @@
+import { dlopen, read as nativeRead } from "bun:ffi";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, ftruncateSync, readSync, writeFileSync, type BigIntStats } from "node:fs";
+import { MEDIA_MAX_BYTES } from "../media.ts";
+
+export class AgentContentError extends Error {
+	constructor(readonly code: string, readonly status = 400, readonly errno?: number) { super(errno === undefined ? code : `${code} (errno ${errno})`); }
+}
+
+// Keep descriptor-relative access on macOS and the existing Linux/glibc test entry.
+const native = (() => {
+	const common = {
+		openat: { args: ["i32", "buffer", "i32", "i32"], returns: "i32" },
+		mkdirat: { args: ["i32", "buffer", "i32"], returns: "i32" },
+	} as const;
+	const rename = { args: ["i32", "buffer", "i32", "buffer", "u32"], returns: "i32" } as const;
+	const error = { args: [], returns: "ptr" } as const;
+	switch (process.platform) {
+		case "darwin": {
+			const symbols = dlopen("/usr/lib/libSystem.B.dylib", { ...common, renameatx_np: rename, __error: error }).symbols;
+			// Darwin sys/fcntl.h and sys/stdio.h: AT_FDCWD and RENAME_EXCL.
+			return { ...symbols, renameExclusive: symbols.renameatx_np, errorLocation: symbols.__error, cwd: -2, exclusive: 0x00000004 };
+		}
+		case "linux": {
+			const symbols = dlopen("libc.so.6", { ...common, renameat2: rename, __errno_location: error }).symbols;
+			// Linux uapi/linux/{fcntl,fs}.h: AT_FDCWD and RENAME_NOREPLACE.
+			return { ...symbols, renameExclusive: symbols.renameat2, errorLocation: symbols.__errno_location, cwd: -100, exclusive: 1 };
+		}
+		default: throw new AgentContentError("unsupported_filesystem_platform", 503);
+	}
+})();
+const DIRECTORY = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+
+function errno(): number {
+	const pointer = native.errorLocation();
+	if (pointer === null) throw new AgentContentError("filesystem_errno_unavailable", 503);
+	return nativeRead.i32(pointer);
+}
+
+function openRoot(root: string): number {
+	if (!root.startsWith("/") || root.includes("\0")) throw new AgentContentError("invalid_path");
+	let fd = native.openat(native.cwd, Buffer.from("/\0"), DIRECTORY, 0);
+	if (fd < 0) throw new AgentContentError("unsafe_root", 400, errno());
+	try {
+		for (const part of root.split("/").filter(Boolean)) {
+			const next = native.openat(fd, component(part), DIRECTORY, 0);
+			if (next < 0) throw new AgentContentError("unsafe_root", 400, errno());
+			closeSync(fd);
+			fd = next;
+		}
+		return fd;
+	} catch (error) { closeSync(fd); throw error; }
+}
+
+function component(value: string): Buffer {
+	if (!value || value === "." || value === ".." || /[/\\\0]/.test(value)) throw new AgentContentError("invalid_path");
+	return Buffer.from(`${value}\0`);
+}
+
+export function sourceName(value: string): string {
+	if (!value || value.startsWith(".") || /[/\\\0]/.test(value)) throw new AgentContentError("invalid_filename");
+	let name = "";
+	for (const character of value.replace(/[^\p{L}\p{N}._-]/gu, "_")) {
+		if (Buffer.byteLength(name + character) > 180) break;
+		name += character;
+	}
+	return name;
+}
+
+export function numberedName(name: string, ordinal: number): string {
+	if (ordinal === 1) return name;
+	const dot = name.lastIndexOf(".");
+	return dot > 0 ? `${name.slice(0, dot)} (${ordinal})${name.slice(dot)}` : `${name} (${ordinal})`;
+}
+
+function identity(a: BigIntStats, b: BigIntStats): boolean {
+	return a.dev === b.dev && a.ino === b.ino;
+}
+
+/** Creation identity survives rename/restore but not replacement at the same display path. */
+export function contentIdentity(stat: BigIntStats): string {
+	return `${stat.dev}:${stat.ino}:${stat.birthtimeNs}`;
+}
+
+export interface ContentVersion {
+	readonly dev: bigint;
+	readonly ino: bigint;
+	readonly size: bigint;
+	readonly mtimeNs: bigint;
+	readonly ctimeNs: bigint;
+	/** Opaque root/ancestor identity captured by readWithIdentity; keep it with the version. */
+	readonly ancestry: string;
+}
+
+function fileStamp(a: Omit<ContentVersion, "ancestry">, b: BigIntStats): boolean {
+	return a.dev === b.dev && a.ino === b.ino && a.size === b.size && a.mtimeNs === b.mtimeNs && a.ctimeNs === b.ctimeNs && b.nlink === 1n;
+}
+
+export interface ContentPublication {
+	readonly directory: readonly string[];
+	readonly name: string;
+	readonly bytes: Uint8Array;
+	readonly immutable: boolean;
+	/** Immutable artifact identifiers never take a numbered replacement. */
+	readonly exact?: boolean;
+}
+
+/** All names are relative to a gateway-owned root; no caller-selected host path reader. */
+// allow: SIZE_OK - one descriptor lifecycle; this task permits only this product file, not a separate filesystem layer.
+export class AgentContentFiles implements Disposable {
+	private readonly fd: number;
+	private readonly rootIdentity: BigIntStats;
+
+	constructor(private readonly root: string) {
+		this.fd = openRoot(root);
+		try { this.rootIdentity = fstatSync(this.fd, { bigint: true }); }
+		catch (error) { closeSync(this.fd); throw error; }
+	}
+
+	[Symbol.dispose](): void { closeSync(this.fd); }
+
+	private open(parent: number, name: string, flags: number): number {
+		const fd = native.openat(parent, component(name), flags | constants.O_NOFOLLOW, 0o600);
+		if (fd < 0) throw new AgentContentError("unsafe_path", 400, errno());
+		return fd;
+	}
+
+	private directory<T>(parts: readonly string[], create: boolean | (() => void), action: (fd: number, check: () => void, ancestry: string) => T): T {
+		const chain: { readonly parent: number; readonly name: string; readonly fd: number; readonly stat: BigIntStats }[] = [];
+		let parent = this.fd;
+		const check = () => {
+			const root = openRoot(this.root);
+			try {
+				if (!identity(this.rootIdentity, fstatSync(root, { bigint: true }))) throw new AgentContentError("file_changed", 409);
+			} finally { closeSync(root); }
+			for (const entry of chain) {
+				const current = this.open(entry.parent, entry.name, DIRECTORY);
+				try {
+					if (!identity(entry.stat, fstatSync(current, { bigint: true }))) throw new AgentContentError("file_changed", 409);
+				} finally { closeSync(current); }
+			}
+		};
+		try {
+			for (const part of parts) {
+				let fd: number;
+				if (typeof create === "function") {
+					try { fd = this.open(parent, part, DIRECTORY); }
+					catch (error) {
+						if (!(error instanceof AgentContentError) || error.errno !== 2) throw error;
+						check();
+						create();
+						check();
+						if (native.mkdirat(parent, component(part), 0o700) < 0) throw new AgentContentError("directory_create_failed", 503, errno());
+						fd = this.open(parent, part, DIRECTORY);
+					}
+				} else {
+					if (create && native.mkdirat(parent, component(part), 0o700) < 0 && errno() !== 17) throw new AgentContentError("directory_create_failed", 503);
+					fd = this.open(parent, part, DIRECTORY);
+				}
+				try { chain.push({ parent, name: part, fd, stat: fstatSync(fd, { bigint: true }) }); }
+				catch (error) { closeSync(fd); throw error; }
+				parent = fd;
+			}
+			check();
+			const ancestry = JSON.stringify([String(this.rootIdentity.dev), String(this.rootIdentity.ino),
+				...chain.map(entry => [entry.name, String(entry.stat.dev), String(entry.stat.ino)])]);
+			const result = action(parent, check, ancestry);
+			check();
+			return result;
+		} finally {
+			for (const entry of chain.reverse()) closeSync(entry.fd);
+		}
+	}
+
+	read(parts: readonly string[]): Buffer {
+		return this.readWithIdentity(parts).bytes;
+	}
+
+	readWithIdentity(parts: readonly string[]): { readonly bytes: Buffer; readonly identity: ContentVersion } {
+		const name = parts.at(-1);
+		if (name === undefined) throw new AgentContentError("invalid_path");
+		return this.directory(parts.slice(0, -1), false, (parent, _check, ancestry) => {
+			// NONBLOCK ensures a substituted FIFO cannot hang before fstat rejects it.
+			const fd = this.open(parent, name, constants.O_RDONLY | constants.O_NONBLOCK);
+			try {
+				const before = fstatSync(fd, { bigint: true });
+				if (!before.isFile() || before.nlink !== 1n) throw new AgentContentError("not_single_regular_file");
+				if (before.size > BigInt(MEDIA_MAX_BYTES)) throw new AgentContentError("too_large", 413);
+				const bytes = Buffer.alloc(Number(before.size) + 1);
+				let length = 0;
+				while (length < bytes.length) {
+					const count = readSync(fd, bytes, length, bytes.length - length, length);
+					if (count === 0) break;
+					length += count;
+				}
+				if (length !== Number(before.size) || !fileStamp(before, fstatSync(fd, { bigint: true }))) throw new AgentContentError("file_changed", 409);
+				const current = this.open(parent, name, constants.O_RDONLY | constants.O_NONBLOCK);
+				try {
+					if (!fileStamp(before, fstatSync(current, { bigint: true }))) throw new AgentContentError("file_changed", 409);
+				} finally { closeSync(current); }
+				return { bytes: bytes.subarray(0, length), identity: Object.freeze({
+					dev: before.dev, ino: before.ino, size: before.size, mtimeNs: before.mtimeNs, ctimeNs: before.ctimeNs, ancestry,
+				}) };
+			} finally { closeSync(fd); }
+		});
+	}
+
+	/** Synchronous admission precedes the first mutation, including mkdir. No awaits or second SDK queue. */
+	write(input: {
+		readonly segments: readonly string[];
+		readonly bytes: Uint8Array;
+		readonly expectedIdentity?: ContentVersion;
+		readonly beforeMutation: () => void;
+	}): void {
+		const parts = [...input.segments];
+		const name = parts.at(-1);
+		if (name === undefined) throw new AgentContentError("invalid_path");
+		for (const part of parts) component(part);
+		if (input.bytes.byteLength > MEDIA_MAX_BYTES) throw new AgentContentError("too_large", 413);
+		const bytes = Buffer.from(input.bytes);
+		const expected = input.expectedIdentity;
+		let admitted = false;
+		let callbackFailure: unknown;
+		const admit = () => {
+			if (admitted) return;
+			try { input.beforeMutation(); }
+			catch (error) { callbackFailure = error; throw error; }
+			admitted = true;
+		};
+		try {
+			this.directory(parts.slice(0, -1), expected ? false : admit, (parent, check, ancestry) => {
+				let fd: number;
+				let created = false;
+				try { fd = this.open(parent, name, constants.O_RDWR | constants.O_NONBLOCK); }
+				catch (error) {
+					if (!(error instanceof AgentContentError) || error.errno !== 2 || expected) throw error;
+					check();
+					admit();
+					check();
+					fd = this.open(parent, name, constants.O_RDWR | constants.O_NONBLOCK | constants.O_CREAT | constants.O_EXCL);
+					created = true;
+				}
+				try {
+					// Match publish: set the mode on the newly owned fd before reopening it.
+					if (created) fchmodSync(fd, 0o600);
+					const before = fstatSync(fd, { bigint: true });
+					if (expected && (expected.ancestry !== ancestry || !fileStamp(expected, before))) throw new AgentContentError("file_changed", 409);
+					if (!before.isFile() || before.nlink !== 1n) throw new AgentContentError("not_single_regular_file");
+					if (before.size > BigInt(MEDIA_MAX_BYTES)) throw new AgentContentError("too_large", 413);
+					const verify = (stamp: Omit<ContentVersion, "ancestry">) => {
+						check();
+						const current = this.open(parent, name, constants.O_RDONLY | constants.O_NONBLOCK);
+						try {
+							if (!fileStamp(stamp, fstatSync(fd, { bigint: true })) || !fileStamp(stamp, fstatSync(current, { bigint: true }))) throw new AgentContentError("file_changed", 409);
+						} finally { closeSync(current); }
+					};
+					verify(before);
+					admit();
+					verify(before);
+					// Never O_TRUNC on open: the same validated fd is mutated only after admission.
+					if (!created) ftruncateSync(fd, 0);
+					writeFileSync(fd, bytes);
+					fsyncSync(fd);
+					const written = fstatSync(fd, { bigint: true });
+					if (written.size !== BigInt(bytes.length)) throw new AgentContentError("file_changed", 409);
+					verify(written);
+				} finally { closeSync(fd); }
+			});
+		} catch (error) {
+			if (expected && error !== callbackFailure && error instanceof AgentContentError &&
+				["unsafe_path", "unsafe_root", "not_single_regular_file", "too_large"].includes(error.code)) throw new AgentContentError("file_changed", 409);
+			throw error;
+		}
+	}
+
+	publish(input: ContentPublication): { readonly name: string; readonly sha256: string; readonly bytes: number; readonly fileIdentity: string } {
+		if (input.bytes.byteLength > MEDIA_MAX_BYTES) throw new AgentContentError("too_large", 413);
+		const bytes = Buffer.from(input.bytes);
+		const name = sourceName(input.name);
+		return this.directory(input.directory, true, parent => {
+			const pending = `.pending-${randomUUID()}`;
+			const fd = this.open(parent, pending, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+			let written: BigIntStats;
+			try {
+				fchmodSync(fd, 0o600);
+				writeFileSync(fd, bytes);
+				fchmodSync(fd, input.immutable ? 0o400 : 0o600);
+				fsyncSync(fd);
+				written = fstatSync(fd, { bigint: true });
+				if (!written.isFile() || written.nlink !== 1n || written.size !== BigInt(bytes.length)) throw new AgentContentError("file_changed", 409);
+			} finally { closeSync(fd); }
+			// A failed write remains an unreferenced pending file, never an accepted manifest.
+			for (let ordinal = 1; ordinal <= (input.exact ? 1 : 1000); ordinal++) {
+				const candidate = numberedName(name, ordinal);
+				if (native.renameExclusive(parent, component(pending), parent, component(candidate), native.exclusive) === 0) {
+					const published = this.open(parent, candidate, constants.O_RDONLY | constants.O_NONBLOCK);
+					try {
+						const current = fstatSync(published, { bigint: true });
+						if (!identity(written, current) || current.nlink !== 1n || current.size !== written.size || current.mtimeNs !== written.mtimeNs) throw new AgentContentError("file_changed", 409);
+					} finally { closeSync(published); }
+					fsyncSync(parent);
+					return { name: candidate, sha256: createHash("sha256").update(bytes).digest("hex"), bytes: bytes.length, fileIdentity: contentIdentity(written) };
+				}
+				const code = errno();
+				if (code !== 17) throw new AgentContentError("publish_failed", 503, code);
+				// Preserve the upload contract: an occupied symlink is an error, not a suffix candidate.
+				const occupied = this.open(parent, candidate, constants.O_RDONLY | constants.O_NONBLOCK);
+				closeSync(occupied);
+			}
+			throw new AgentContentError("file_exists", 409);
+		});
+	}
+
+	/** Called only after the Store's protected explicit deletion has recorded its tombstone. */
+	trash(name: string): void {
+		this.directory([".collaboration", "artifacts"], false, source =>
+			this.directory([".collaboration", "trash"], true, target => {
+				if (native.renameExclusive(source, component(name), target, component(name), native.exclusive) < 0) {
+					throw new AgentContentError("trash_failed", 503, errno());
+				}
+				fsyncSync(source);
+				fsyncSync(target);
+			}));
+	}
+}

package/src/agent/files.ts

@@ -3,17 +3,42 @@ import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSy
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { runtimePaths, type Env } from "../runtime/paths.ts";
 import { say, type Text } from "../server-text.ts";
-import { parseAgentDefinition, AgentDefinitionError, serializeAgentDefinition, type AgentDefinition } from "./definition.ts";
+import { AGENT_SCHEMA, parseAgentDefinition, AgentDefinitionError, mergeAgentDefinition, validateCollaborationTargets, migrateAgentFields, readAgentFrontmatter, serializeAgentDefinition, validateAgentFields, type AgentDefinition } from "./definition.ts";
+import { AGENT_FIELDS } from "./fields.ts";
 import { migrateLegacyAgentFiles } from "./legacy-files.ts";
 
 export function agentTrashEntry(id: string, timestamp: string): string {
 	return `${id}-${timestamp}`;
 }
 
-/** Trash names retain the UTC ISO timestamp used by the file store, including colons. */
+/** A UTC ISO time as toISOString writes it; null for any other text, so Date.parse never rolls Feb 30 or hour 25 over. */
+export function utcIsoTime(text: string): number | null {
+	const at = Date.parse(text);
+	return Number.isFinite(at) && new Date(at).toISOString() === text ? at : null;
+}
+
+/** Trash names retain the UTC ISO timestamp used by the file store, including colons; NaN for an impossible time. */
 export function agentTrashTimestamp(entry: string): number | null {
 	const timestamp = /-(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)$/.exec(entry)?.[1];
-	return timestamp === undefined ? null : Date.parse(timestamp);
+	return timestamp === undefined ? null : utcIsoTime(timestamp) ?? Number.NaN;
+}
+
+/**
+ * A deleted knowledge file is kept as agents/.file-trash/<id>/<UTC ISO time>-<path>, with only "%", "/" and the control
+ * characters U+0000-U+001F and U+007F of the path escaped as %XX (uppercase hex), so any name the agent wrote comes back.
+ * The path stays readable and short: base64 would push a 180-byte upload name past the 255-byte limit.
+ */
+export function agentFileTrashName(path: string, timestamp: string): string {
+	return `${timestamp}-${path.replace(/[%/\u0000-\u001f\u007f]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`)}`;
+}
+
+/** The deletion time and the original path of a file archive entry; null for any name the store did not write. */
+export function parseAgentFileTrashName(entry: string): { readonly deletedAt: number; readonly path: string } | null {
+	const match = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)-((?:[^%/\u0000-\u001f\u007f]|%(?:25|2F|[01][0-9A-F]|7F))+)$/su.exec(entry);
+	if (!match?.[1] || !match[2]) return null;
+	const deletedAt = utcIsoTime(match[1]);
+	if (deletedAt === null) return null;
+	return { deletedAt, path: match[2].replace(/%([0-9A-F]{2})/g, (_, hex: string) => String.fromCharCode(Number.parseInt(hex, 16))) };
 }
 
 /** A broken entry must not prevent the other agents from being listed. */
@@ -24,6 +49,24 @@ export function unreadableAgent(error: unknown): boolean {
 }
 
 const COPY_SUFFIX: Text = { en: " copy", ko: " 사본" };
+/** What parseNew reads for a required text the new agent does not have yet; it never leaves the preview. */
+const NEW_AGENT_PLACEHOLDER = "new agent";
+
+/**
+ * A definition without a schema is the v1 format; write the number, so the editor never has to show it. The line goes
+ * first and the rest stays byte for byte; a frontmatter that cannot take a leading line (a flow map) is re-serialized.
+ */
+function withSchema(source: string): string {
+	const definition = parseAgentDefinition(source);
+	if (definition.fields.schema !== undefined) return source;
+	const block = source.replace(/^---(\r?\n)/, `---$1schema: ${AGENT_SCHEMA}$1`);
+	try {
+		if (parseAgentDefinition(block).fields.schema === AGENT_SCHEMA) return block;
+	} catch (error) {
+		if (!(error instanceof AgentDefinitionError)) throw error;
+	}
+	return serializeAgentDefinition({ ...definition, fields: { schema: AGENT_SCHEMA, ...definition.fields } });
+}
 
 export class AgentFileError extends Error {
 	constructor(readonly code: "path" | "exists" | "id", message: string) {
@@ -77,12 +120,14 @@ export class AgentFileStore {
 		return new Date(this.lastTime).toISOString();
 	}
 
-	create(source: string): string {
-		parseAgentDefinition(source);
+	create(input: string): string {
+		const source = withSchema(input);
 		const id = randomUUID().slice(0, 8);
+		validateCollaborationTargets({ agentId: id, fields: mergeAgentDefinition(parseAgentDefinition(source), this.readDefaults()).fields, knownIds: new Set(this.list().map(agent => agent.id)) });
 		const folder = this.folder(id);
 		mkdirSync(folder);
 		mkdirSync(join(folder, "knowledge/source"), { recursive: true });
+		mkdirSync(join(folder, "knowledge/outputs"), { recursive: true });
 		mkdirSync(join(folder, "knowledge/notes/daily"), { recursive: true });
 		writeFileSync(join(folder, "knowledge/MEMORY.md"), "", { flag: "wx" });
 		writeFileSync(join(folder, "agent.md"), source, { flag: "wx" });
@@ -123,8 +168,28 @@ export class AgentFileStore {
 	}
 
 	save(id: string, source: string): void {
-		parseAgentDefinition(source);
-		this.saveFile(join(this.folder(id), "agent.md"), source);
+		validateCollaborationTargets({ agentId: id, fields: mergeAgentDefinition(this.parse(source), this.readDefaults()).fields, knownIds: new Set(this.list().map(agent => agent.id)) });
+		this.saveFile(join(this.folder(id), "agent.md"), withSchema(source));
+	}
+
+	/** `source` as a save of it reads back (schema 1 filled in, parsed and validated); nothing is written. */
+	parse(source: string): AgentDefinition {
+		return parseAgentDefinition(withSchema(source));
+	}
+
+	/**
+	 * A new agent's text before its required texts are written (agent-ux int): a missing or blank name or description reads as a
+	 * placeholder, so the permission fields, which do not depend on them, can be evaluated as a save would read them. `filled`
+	 * names the fields that hold the placeholder; nothing is written.
+	 */
+	parseNew(source: string): { readonly definition: AgentDefinition; readonly filled: readonly string[] } {
+		const { fields, body } = readAgentFrontmatter(source);
+		const filled = AGENT_FIELDS.filter((field) => field.required && field.type === "string" && !field.name.includes("."))
+			.map((field) => field.name).filter((name) => fields[name] === undefined || (typeof fields[name] === "string" && !fields[name].trim()));
+		if (filled.length === 0) return { definition: this.parse(source), filled };
+		const complete = { schema: AGENT_SCHEMA, ...fields, ...Object.fromEntries(filled.map((name) => [name, NEW_AGENT_PLACEHOLDER])) };
+		validateAgentFields(complete);
+		return { definition: { fields: migrateAgentFields(complete), body, kind: "agent", source }, filled };
 	}
 
 	readDefaults(): AgentDefinition | undefined {
@@ -133,7 +198,10 @@ export class AgentFileStore {
 	}
 
 	saveDefaults(source: string): void {
-		parseAgentDefinition(source, "defaults");
+		const defaults = parseAgentDefinition(source, "defaults");
+		const agents = this.list(), knownIds = new Set(agents.map(agent => agent.id));
+		validateCollaborationTargets({ agentId: null, fields: defaults.fields, knownIds });
+		for (const agent of agents) validateCollaborationTargets({ agentId: agent.id, fields: mergeAgentDefinition(agent.definition, defaults).fields, knownIds });
 		this.saveFile(join(this.root, "defaults.md"), source);
 	}
 
@@ -189,4 +257,15 @@ export class AgentFileStore {
 		renameSync(this.checked(join(".trash", entry)), target);
 		return id;
 	}
+
+	/** Restores an archive entry under a fresh id, for an entry whose own id is taken; never touches the live folder. */
+	restoreAs(entry: string): string {
+		if (!/^[a-f0-9]{8}-\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(entry)) throw new AgentFileError("id", "Invalid trash entry");
+		const source = this.checked(join(".trash", entry));
+		if (!lstatSync(source).isDirectory()) throw new AgentFileError("path", "Trash entry is not a folder");
+		let id = randomUUID().slice(0, 8);
+		while (existsSync(this.folder(id))) id = randomUUID().slice(0, 8);
+		renameSync(source, this.folder(id));
+		return id;
+	}
 }

package/src/agent/list.ts

@@ -1,9 +1,9 @@
 import type { AgentDefinition } from "./definition.ts";
 
-export interface AgentListEntry { readonly name: string; readonly description: string; readonly link: string }
+export interface AgentListEntry { readonly id: string; readonly name: string; readonly description: string; readonly convId: string; readonly link: string }
 
 /**
- * The read-only list main sees: name, one-line purpose and the gateway-relative web link of the conversation.
+ * The read-only list main sees: stable agent and conversation ids, name, one-line purpose and gateway-relative link.
  * `visible` holds only non-hidden conversations, so a trashed agent (hidden conversation) never appears.
  * Definition body and knowledge are never part of the result.
  */
@@ -15,7 +15,7 @@ export function agentList(
 	for (const { id, definition } of agents) {
 		const conv = visible.find((row) => row.agentId === id);
 		if (!conv) continue;
-		entries.push({ name: String(definition.fields.name), description: String(definition.fields.description), link: `/#conv=${encodeURIComponent(conv.id)}` });
+		entries.push({ id, name: String(definition.fields.name), description: String(definition.fields.description), convId: conv.id, link: `/#conv=${encodeURIComponent(conv.id)}` });
 	}
 	return entries;
 }