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

package/web/agents.js

@@ -0,0 +1,813 @@
+// Agent screens (agent-sessions plan todo 10, design D5). Only decisions live here, with no DOM, so
+// test/unit/agent-web.test.ts can exercise them: the sidebar group and header view models, the definition editor
+// state (registry widgets, origin labels, raw YAML for unknown keys, the instruction body), the `agent.md` source the
+// editor saves, the delete confirmation, 보관함 rows and the knowledge file list. app.js draws the screens from these.
+// The gateway validates every save (src/agent/definition.ts); this module composes the source and checks what the
+// editor can tell before the request.
+import { formatBytes } from "./gc.js";
+import strings from "./i18n/agents.js";
+import { onLanguageChange, registerStrings, t } from "./i18n.js";
+
+registerStrings(strings);
+
+export const AGENTS_PATH = "/api/agents";
+export const DEFAULTS_PATH = "/api/agents/defaults";
+export const TRASH_PATH = "/api/agents/trash";
+export const AGENT_MAX_BYTES = 32768;
+export const DESCRIPTION_MAX = 120;
+export const MEMORY_MAX_BYTES = 32768;
+export const THINKING_LEVELS = Object.freeze(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
+export let ORIGIN_LABELS = originLabels();
+export const DEFAULT_ICON = "◎";
+export let STALE_LABEL = t("agents.stale.label");
+export let STALE_TITLE = t("agents.stale.title");
+export let DELETE_HINT = t("agents.delete.hint");
+export let EMPTY_AGENTS_LINE = t("agents.empty.list");
+export let EMPTY_TRASH_LINE = t("agents.empty.trash");
+export let EMPTY_FILES_LINE = t("agents.empty.files");
+export let NEW_AGENT_BODY = t("agents.new.body");
+
+function originLabels() {
+	return Object.freeze({ package: t("agents.origin.package"), defaults: t("agents.origin.defaults"), agent: t("agents.origin.agent"), none: t("agents.origin.none") });
+}
+
+// The exported texts follow the UI language (app.js reads them at render time).
+onLanguageChange(() => {
+	ORIGIN_LABELS = originLabels();
+	STALE_LABEL = t("agents.stale.label");
+	STALE_TITLE = t("agents.stale.title");
+	DELETE_HINT = t("agents.delete.hint");
+	EMPTY_AGENTS_LINE = t("agents.empty.list");
+	EMPTY_TRASH_LINE = t("agents.empty.trash");
+	EMPTY_FILES_LINE = t("agents.empty.files");
+	NEW_AGENT_BODY = t("agents.new.body");
+});
+
+/**
+ * The editor's labels and hints by registry field name. The field list itself (names, types, widgets, defaults, forbidden
+ * rows) is the gateway's registry (src/agent/fields.ts), sent as `registry` in every GET /api/agents/:id and
+ * /api/agents/defaults answer; editorFields() joins the two. A gateway row without an entry here renders with its name
+ * as the label, so a new registry row needs no web change.
+ */
+export const FIELD_PRESENTATION = Object.freeze({
+	schema: { label: "agents.field.schema.label", help: "agents.field.schema.help" },
+	name: { label: "agents.field.name.label", help: "agents.field.name.help" },
+	description: { label: "agents.field.description.label", help: "agents.field.description.help" },
+	icon: { label: "agents.field.icon.label", help: "agents.field.icon.help" },
+	model: { label: "agents.field.model.label", help: "agents.field.model.help" },
+	"model.provider": { label: "agents.field.model.provider.label" }, "model.modelId": { label: "agents.field.model.modelId.label" },
+	thinking: { label: "agents.field.thinking.label", options: THINKING_LEVELS },
+	skills: { label: "agents.field.skills.label", help: "agents.field.skills.help" },
+	tools: { label: "agents.field.tools.label" }, "tools.web": { label: "agents.field.tools.web.label" },
+	"tools.bash": { label: "agents.field.tools.bash.label" }, "tools.eval": { label: "agents.field.tools.eval.label" },
+	notify: { label: "agents.field.notify.label" }, rules: { label: "agents.field.rules.label" },
+	"rules.gateway": { label: "agents.field.rules.gateway.label" }, "rules.install": { label: "agents.field.rules.install.label" },
+	memory: { label: "agents.field.memory.label" },
+	"memory.maxBytes": { label: "agents.field.memory.maxBytes.label", help: "agents.field.memory.maxBytes.help", min: 0, max: MEMORY_MAX_BYTES },
+});
+
+/** The gateway's registry rows with the editor's labels, in registry order; a row the web has no entry for is labelled by its name. */
+export function editorFields(registry) {
+	return (Array.isArray(registry) ? registry : []).map((field) => {
+		const presentation = FIELD_PRESENTATION[field.name] ?? {};
+		return { ...field, ...presentation, label: t(presentation.label ?? field.name), help: t(presentation.help ?? "") };
+	});
+}
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)^---[ \t]*(?:\r?\n|$)/m;
+
+function isObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export function fieldAt(fields, name) {
+	let value = fields;
+	for (const key of name.split(".")) {
+		if (!isObject(value) || !Object.hasOwn(value, key)) return undefined;
+		value = value[key];
+	}
+	return value;
+}
+
+function setPath(target, keys, value) {
+	const [head, ...rest] = keys;
+	if (rest.length === 0) {
+		if (value === undefined) delete target[head];
+		else target[head] = value;
+		return;
+	}
+	if (value === undefined) {
+		if (!isObject(target[head])) return;
+		setPath(target[head], rest, value);
+		if (Object.keys(target[head]).length === 0) delete target[head];
+		return;
+	}
+	if (!isObject(target[head])) target[head] = {};
+	setPath(target[head], rest, value);
+}
+
+/** Top-level registry keys, in registry order (a group's children share their group's key). */
+export function topLevelKeys(registry) {
+	const keys = [];
+	for (const field of registry) {
+		const top = field.name.split(".")[0];
+		if (!keys.includes(top)) keys.push(top);
+	}
+	return keys;
+}
+
+// ---- YAML subset: what agent.md frontmatter uses (block maps and sequences, flow maps and sequences, plain, quoted
+// and block scalars, comments). Anything else throws, and the editor then keeps that entry's text as it is.
+
+const QUOTE_OPENER = /^(?:|.*[\s:,\[{-])$/;
+const FLOW_START = /^[\[{]/;
+
+function stripComment(line) {
+	let quote = null;
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (quote) {
+			if (ch === "\\" && quote === '"') i++;
+			else if (ch === "'" && quote === "'" && line[i + 1] === "'") i++;
+			else if (ch === quote) quote = null;
+			continue;
+		}
+		if ((ch === '"' || ch === "'") && QUOTE_OPENER.test(line.slice(0, i))) quote = ch;
+		else if (ch === "#" && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i).trimEnd();
+	}
+	return line.trimEnd();
+}
+
+function indentOf(line) {
+	return line.length - line.trimStart().length;
+}
+
+function closingQuote(text, start, quote) {
+	for (let i = start + 1; i < text.length; i++) {
+		if (quote === '"' && text[i] === "\\") {
+			i++;
+			continue;
+		}
+		if (text[i] === quote) {
+			if (quote === "'" && text[i + 1] === "'") {
+				i++;
+				continue;
+			}
+			return i;
+		}
+	}
+	throw new Error("unterminated quote");
+}
+
+function parseQuoted(text) {
+	if (text[0] === '"') return JSON.parse(text);
+	return text.slice(1, -1).replace(/''/g, "'");
+}
+
+function parseFlow(text) {
+	let i = 0;
+	const ws = () => {
+		while (i < text.length && /\s/.test(text[i])) i++;
+	};
+	const scalarToken = (key) => {
+		ws();
+		const ch = text[i];
+		if (ch === '"' || ch === "'") {
+			const end = closingQuote(text, i, ch);
+			const value = parseQuoted(text.slice(i, end + 1));
+			i = end + 1;
+			return value;
+		}
+		const start = i;
+		while (i < text.length) {
+			const c = text[i];
+			if (c === "," || c === "]" || c === "}") break;
+			if (c === ":" && (i + 1 >= text.length || /[\s,\]}]/.test(text[i + 1]))) break;
+			i++;
+		}
+		const raw = text.slice(start, i).trim();
+		if (key) return raw;
+		return parsePlain(raw);
+	};
+	const value = () => {
+		ws();
+		const ch = text[i];
+		if (ch === "[") {
+			i++;
+			const out = [];
+			ws();
+			if (text[i] === "]") {
+				i++;
+				return out;
+			}
+			for (;;) {
+				out.push(value());
+				ws();
+				if (text[i] === ",") {
+					i++;
+					ws();
+					if (text[i] === "]") {
+						i++;
+						return out;
+					}
+					continue;
+				}
+				if (text[i] === "]") {
+					i++;
+					return out;
+				}
+				throw new Error("flow sequence");
+			}
+		}
+		if (ch === "{") {
+			i++;
+			const out = {};
+			ws();
+			if (text[i] === "}") {
+				i++;
+				return out;
+			}
+			for (;;) {
+				const key = String(scalarToken(true));
+				ws();
+				if (text[i] !== ":") throw new Error("flow map key");
+				i++;
+				out[key] = value();
+				ws();
+				if (text[i] === ",") {
+					i++;
+					ws();
+					if (text[i] === "}") {
+						i++;
+						return out;
+					}
+					continue;
+				}
+				if (text[i] === "}") {
+					i++;
+					return out;
+				}
+				throw new Error("flow map");
+			}
+		}
+		return scalarToken(false);
+	};
+	const result = value();
+	ws();
+	if (i !== text.length) throw new Error("trailing text");
+	return result;
+}
+
+function parsePlain(raw) {
+	const t = raw.trim();
+	if (t === "" || t === "~" || /^null$/i.test(t)) return null;
+	if (/^true$/i.test(t)) return true;
+	if (/^false$/i.test(t)) return false;
+	if (/^[-+]?(?:\.[0-9]+|[0-9]+(?:\.[0-9]*)?)(?:[eE][-+]?[0-9]+)?$/.test(t)) return Number(t);
+	if (t[0] === '"' || t[0] === "'") {
+		if (closingQuote(t, 0, t[0]) !== t.length - 1) throw new Error("text after quote");
+		return parseQuoted(t);
+	}
+	if (FLOW_START.test(t)) return parseFlow(t);
+	if (/^[&*!|>@`%]/.test(t)) throw new Error("unsupported scalar");
+	return t;
+}
+
+function flowBalanced(text) {
+	let depth = 0;
+	let quote = null;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (quote) {
+			if (ch === "\\" && quote === '"') i++;
+			else if (ch === "'" && quote === "'" && text[i + 1] === "'") i++;
+			else if (ch === quote) quote = null;
+			continue;
+		}
+		if (ch === '"' || ch === "'") quote = ch;
+		else if (ch === "[" || ch === "{") depth++;
+		else if (ch === "]" || ch === "}") depth--;
+	}
+	return depth <= 0 && quote === null;
+}
+
+function parseBlockScalar(lines, i, indent, header) {
+	const style = header[0];
+	const chomp = header.includes("-") ? "strip" : header.includes("+") ? "keep" : "clip";
+	const collected = [];
+	let inner = null;
+	while (i < lines.length) {
+		const line = lines[i];
+		if (line.trim() === "") {
+			collected.push("");
+			i++;
+			continue;
+		}
+		if (indentOf(line) <= indent) break;
+		inner ??= indentOf(line);
+		if (indentOf(line) < inner) throw new Error("block scalar indentation");
+		collected.push(line.slice(inner));
+		i++;
+	}
+	while (collected.length && collected.at(-1) === "") collected.pop();
+	let text;
+	if (style === "|") text = collected.join("\n");
+	else {
+		text = "";
+		for (const [index, piece] of collected.entries()) {
+			if (piece === "") text += "\n";
+			else text += (index > 0 && collected[index - 1] !== "" ? " " : "") + piece;
+		}
+	}
+	if (chomp !== "strip" && collected.length) text += "\n";
+	return [text, i];
+}
+
+function parseMap(lines, i, indent) {
+	const out = {};
+	while (i < lines.length) {
+		if (lines[i].trim() === "") {
+			i++;
+			continue;
+		}
+		const ind = indentOf(lines[i]);
+		if (ind < indent) break;
+		if (ind > indent) throw new Error("mapping indentation");
+		const line = lines[i].trim();
+		if (line === "-" || line.startsWith("- ")) throw new Error("sequence in mapping");
+		const match = /^("(?:[^"\\]|\\.)*"|'(?:[^']|'')*'|[^\s"'#][^:]*?)\s*:(?:\s+(.*))?$/.exec(line);
+		if (!match) throw new Error("expected key");
+		const key = match[1][0] === '"' || match[1][0] === "'" ? parseQuoted(match[1]) : match[1];
+		let rest = match[2] ?? "";
+		i++;
+		if (rest.trim() === "") {
+			const [value, next] = parseNode(lines, i, indent + 1);
+			out[key] = value;
+			i = next;
+		} else if (/^[|>]/.test(rest.trim())) {
+			const [value, next] = parseBlockScalar(lines, i, indent, rest.trim());
+			out[key] = value;
+			i = next;
+		} else {
+			while (!flowBalanced(rest) && i < lines.length && (lines[i].trim() === "" || indentOf(lines[i]) > indent)) rest += ` ${lines[i++].trim()}`;
+			out[key] = parsePlain(rest);
+		}
+	}
+	return [out, i];
+}
+
+function parseSeq(lines, i, indent) {
+	const out = [];
+	while (i < lines.length) {
+		if (lines[i].trim() === "") {
+			i++;
+			continue;
+		}
+		const ind = indentOf(lines[i]);
+		if (ind < indent) break;
+		if (ind > indent) throw new Error("sequence indentation");
+		const line = lines[i].trim();
+		if (!(line === "-" || line.startsWith("- "))) throw new Error("expected sequence item");
+		const rest = line === "-" ? "" : line.slice(2);
+		if (rest.trim() === "") {
+			const [value, next] = parseNode(lines, i + 1, indent + 1);
+			out.push(value);
+			i = next;
+		} else if (/^[^\s"'#\[{][^:]*?\s*:(?:\s|$)/.test(rest) || rest === "-" || rest.startsWith("- ")) {
+			// "- key: value" and "- - item": the item is a collection whose first entry sits on the dash line.
+			lines[i] = " ".repeat(indent + 2) + rest;
+			const [value, next] = parseNode(lines, i, indent + 2);
+			out.push(value);
+			i = next;
+		} else {
+			out.push(parsePlain(rest));
+			i++;
+		}
+	}
+	return [out, i];
+}
+
+function parseNode(lines, i, minIndent) {
+	while (i < lines.length && lines[i].trim() === "") i++;
+	if (i >= lines.length) return [null, i];
+	const indent = indentOf(lines[i]);
+	if (indent < minIndent) return [null, i];
+	const first = lines[i].trim();
+	if (first === "-" || first.startsWith("- ")) return parseSeq(lines, i, indent);
+	if (/^[\[{"']/.test(first)) {
+		let text = first;
+		let next = i + 1;
+		while (next < lines.length && (lines[next].trim() === "" || indentOf(lines[next]) >= minIndent)) text += ` ${lines[next++].trim()}`;
+		return [parsePlain(text), next];
+	}
+	return parseMap(lines, i, indent);
+}
+
+/** Parses the YAML subset agent.md frontmatter uses; throws for anything outside it. */
+export function parseYaml(text) {
+	const lines = text.replace(/\r\n/g, "\n").split("\n").map(stripComment);
+	let i = 0;
+	while (i < lines.length && lines[i].trim() === "") i++;
+	if (i >= lines.length) return null;
+	if (indentOf(lines[i]) !== 0) throw new Error("root indentation");
+	const rootIsScalar = /^[\[{"']/.test(lines[i]) || (!/:(\s|$)/.test(lines[i]) && lines[i] !== "-" && !lines[i].startsWith("- "));
+	const [value, next] = rootIsScalar ? [parsePlain(lines.slice(i).join(" ")), lines.length] : parseNode(lines, i, 0);
+	for (let j = next; j < lines.length; j++) if (lines[j].trim() !== "") throw new Error("trailing text");
+	return value;
+}
+
+const PLAIN_UNSAFE = /^[-?:,\[\]{}#&*!|>'"%@`\s]|[\[\]{},]|:\s|\s#|:$|[\u0000-\u001f\u007f]|\s$/;
+const PLAIN_RESERVED = /^(?:true|false|null|~|yes|no|on|off|y|n|\.inf|-\.inf|\.nan)$/i;
+const PLAIN_NUMERIC = /^[-+]?(?:0x[0-9a-f]+|0o[0-7]+|(?:0|[1-9][0-9_]*)(?:\.[0-9_]*)?(?:[eE][-+]?[0-9]+)?|\.[0-9]+(?:[eE][-+]?[0-9]+)?)$/i;
+
+export function emitScalar(value) {
+	if (value === null || value === undefined) return "null";
+	if (typeof value === "boolean") return String(value);
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : "null";
+	const text = String(value);
+	if (text === "" || PLAIN_UNSAFE.test(text) || PLAIN_RESERVED.test(text) || PLAIN_NUMERIC.test(text)) return JSON.stringify(text);
+	return text;
+}
+
+function isScalar(value) {
+	return !Array.isArray(value) && !isObject(value);
+}
+
+function emitMapEntries(value, indent) {
+	const pad = " ".repeat(indent);
+	return Object.keys(value).map((key) => `${pad}${emitScalar(key)}:${emitValue(value[key], indent + 2)}`).join("");
+}
+
+function emitSeqItems(value, indent) {
+	const pad = " ".repeat(indent);
+	return value.map((item) => {
+		if (isScalar(item) || item.length === 0 || (Array.isArray(item) && item.every(isScalar))) return `${pad}-${emitValue(item, indent + 2)}`;
+		if (Array.isArray(item)) return `${pad}-\n${emitSeqItems(item, indent + 2)}`;
+		if (Object.keys(item).length === 0) return `${pad}- {}\n`;
+		return `${pad}- ${emitMapEntries(item, indent + 2).slice(indent + 2)}`;
+	}).join("");
+}
+
+function emitValue(value, indent) {
+	if (Array.isArray(value)) {
+		if (value.length === 0) return " []\n";
+		if (value.every(isScalar)) return ` [${value.map((item) => emitScalar(item)).join(", ")}]\n`;
+		return `\n${emitSeqItems(value, indent)}`;
+	}
+	if (isObject(value)) return Object.keys(value).length === 0 ? " {}\n" : `\n${emitMapEntries(value, indent)}`;
+	return ` ${emitScalar(value)}\n`;
+}
+
+/** One top-level frontmatter entry (block style for objects, flow style for lists), ending with a newline. */
+export function emitEntry(key, value) {
+	return `${emitScalar(key)}:${emitValue(value, 2)}`;
+}
+
+/**
+ * Splits agent.md into the comment lines before the first key, the top-level frontmatter entries (each `key` with its
+ * exact text, `null` when the line is not `key:`) and the instruction body. `ok` is false without a frontmatter block.
+ */
+export function splitSource(source) {
+	const match = FRONTMATTER.exec(source);
+	if (!match || match.index !== 0) return { ok: false, preamble: "", entries: [], body: source };
+	const lines = match[1].split("\n");
+	if (lines.at(-1) === "") lines.pop();
+	const entries = [];
+	let preamble = "";
+	for (const line of lines) {
+		if (/^[^\s#]/.test(line)) {
+			const key = /^("(?:[^"\\]|\\.)*"|'(?:[^']|'')*'|[^\s"'#:\[\]{},&*!|>%@`?-][^:]*?)\s*:(?:\s|$)/.exec(line);
+			entries.push({ key: key ? (key[1][0] === '"' || key[1][0] === "'" ? parseQuoted(key[1]) : key[1]) : null, raw: `${line}\n` });
+		} else if (entries.length === 0) preamble += `${line}\n`;
+		else entries.at(-1).raw += `${line}\n`;
+	}
+	return { ok: true, preamble, entries, body: source.slice(match[0].length) };
+}
+
+/**
+ * The editor's state for one definition: `kind` is "new", "agent" or "defaults"; `detail` is the gateway's answer, whose
+ * `registry` decides which frontmatter keys are fields and which stay raw YAML.
+ */
+export function editorState(detail, kind = "agent") {
+	const split = splitSource(detail?.source ?? "");
+	const registry = editorFields(detail?.registry);
+	const known = topLevelKeys(registry);
+	const own = {};
+	const rawByKey = {};
+	const unparsed = new Set();
+	let unknownRaw = "";
+	for (const entry of split.entries) {
+		if (entry.key !== null && known.includes(entry.key)) {
+			rawByKey[entry.key] = entry.raw;
+			try {
+				const parsed = parseYaml(entry.raw);
+				if (!isObject(parsed) || !Object.hasOwn(parsed, entry.key)) throw new Error("entry");
+				own[entry.key] = parsed[entry.key];
+			} catch {
+				unparsed.add(entry.key);
+			}
+		} else unknownRaw += entry.raw;
+	}
+	const inherited = kind === "agent" && isObject(detail?.fields) ? detail.fields : packageDefaults(registry);
+	return {
+		kind, registry, id: kind === "agent" ? detail?.id ?? null : null, name: kind === "agent" ? detail?.name ?? null : null,
+		convId: kind === "agent" ? detail?.convId ?? null : null, stale: kind === "agent" && detail?.stale === true,
+		own, rawByKey, touched: new Set(), unparsed, unknownRaw, unknownTouched: false, preamble: split.preamble,
+		body: split.ok ? split.body : kind === "new" ? NEW_AGENT_BODY : split.body, bodyTouched: false,
+		inherited, origins: kind === "agent" && isObject(detail?.origins) ? detail.origins : {}, dirty: false,
+	};
+}
+
+/** The registry's package defaults as nested fields (the values every agent has before defaults.md and agent.md). */
+export function packageDefaults(registry) {
+	const fields = {};
+	for (const field of registry) if (field.default !== undefined) setPath(fields, field.name.split("."), structuredClone(field.default));
+	return fields;
+}
+
+/** The rows the editor draws, in the gateway's registry order: a `group` row before its children and a `field` row per leaf. */
+export function editorRows(state) {
+	const rows = [];
+	for (const field of state.registry) {
+		if (field.forbidden) continue;
+		if (state.kind === "defaults" && field.required) continue;
+		const top = field.name.split(".")[0];
+		if (field.widget === "group" || field.widget === "model") {
+			rows.push({ kind: "group", name: field.name, label: field.label, help: field.help });
+			continue;
+		}
+		const ownValue = fieldAt(state.own, field.name);
+		const own = ownValue !== undefined;
+		const inheritedValue = state.kind === "agent" ? fieldAt(state.inherited, field.name) : field.default;
+		const value = own ? ownValue : inheritedValue;
+		let origin;
+		if (own) origin = state.kind === "defaults" ? "defaults" : "agent";
+		else if (state.kind === "agent") origin = state.origins[field.name] ?? (value === undefined ? "none" : "package");
+		else origin = field.default === undefined ? "none" : "package";
+		rows.push({
+			kind: "field", name: field.name, label: field.label, help: field.help, widget: field.widget, type: field.type, required: field.required,
+			value: value === undefined ? null : value, own, origin, originLabel: ORIGIN_LABELS[origin],
+			clearable: own && !field.required,
+			unparsed: state.unparsed.has(top) && !state.touched.has(top),
+			...(field.options ? { options: field.options } : {}), ...(field.min !== undefined ? { min: field.min } : {}), ...(field.max !== undefined ? { max: field.max } : {}),
+		});
+	}
+	return rows;
+}
+
+/** The value a widget's input means for its field; `undefined` clears an optional override; `{ error }` refuses it. */
+export function widgetValue(field, input) {
+	if (field.widget === "toggle") return { value: Boolean(input) };
+	const text = typeof input === "string" ? input : input === null || input === undefined ? "" : String(input);
+	if (field.widget === "number") {
+		if (text.trim() === "") return field.required ? { error: t("agents.error.required", { label: field.label }) } : { value: undefined };
+		const number = Number(text.trim());
+		if (!Number.isSafeInteger(number)) return { error: t("agents.error.integer", { label: field.label }) };
+		if (field.min !== undefined && number < field.min || field.max !== undefined && number > field.max) return { error: t("agents.error.range", { label: field.label, min: field.min ?? "", max: field.max ?? "" }) };
+		return { value: number };
+	}
+	if (field.widget === "skills") {
+		const items = [...new Set(text.split(/[\n,]+/).map((item) => item.trim()).filter(Boolean))];
+		return { value: items };
+	}
+	if (field.widget === "select") {
+		if (text === "") return { value: undefined };
+		if (field.options && !field.options.includes(text)) return { error: t("agents.error.option", { label: field.label, options: field.options.join(", ") }) };
+	}
+	if (field.required) return { value: text };
+	return { value: text.trim() === "" ? undefined : text };
+}
+
+/** A new state with the field set (`undefined` removes the override and empties parents); never changes `state`. */
+export function setField(state, name, value) {
+	const own = structuredClone(state.own);
+	setPath(own, name.split("."), value === undefined ? undefined : structuredClone(value));
+	const touched = new Set(state.touched);
+	touched.add(name.split(".")[0]);
+	return { ...state, own, touched, dirty: true };
+}
+
+export function clearField(state, name) {
+	return setField(state, name, undefined);
+}
+
+export function setBody(state, body) {
+	return { ...state, body, bodyTouched: true, dirty: true };
+}
+
+export function setUnknownRaw(state, unknownRaw) {
+	return { ...state, unknownRaw, unknownTouched: true, dirty: true };
+}
+
+/** The agent.md text the editor saves: untouched entries keep their exact text, touched ones are emitted anew. */
+export function composeSource(state) {
+	let header = state.preamble ?? "";
+	for (const key of topLevelKeys(state.registry)) {
+		if (!state.touched.has(key) && state.rawByKey[key] !== undefined) {
+			header += state.rawByKey[key];
+			continue;
+		}
+		const value = state.own[key];
+		if (value !== undefined) header += emitEntry(key, value);
+	}
+	const extra = state.unknownRaw.replace(/\s+$/, "");
+	if (extra) header += `${extra}\n`;
+	return `---\n${header}---\n${state.body}`;
+}
+
+function characters(text) {
+	return [...text].length;
+}
+
+/** What the editor can tell before the gateway validates: required fields, lengths, ranges, the model pair, the size. */
+export function validateEditor(state) {
+	const errors = [];
+	const own = state.own;
+	if (state.kind !== "defaults") {
+		if (typeof own.name !== "string" || !own.name.trim()) errors.push({ name: "name", message: t("agents.validation.name.required") });
+		if (typeof own.description !== "string" || !own.description.trim()) errors.push({ name: "description", message: t("agents.validation.description.required") });
+	} else {
+		if (own.name !== undefined) errors.push({ name: "name", message: t("agents.validation.defaults.name") });
+		if (own.description !== undefined) errors.push({ name: "description", message: t("agents.validation.defaults.description") });
+	}
+	if (typeof own.description === "string" && characters(own.description) > DESCRIPTION_MAX) errors.push({ name: "description", message: t("agents.validation.description.length", { max: DESCRIPTION_MAX, count: characters(own.description) }) });
+	const maxBytes = fieldAt(own, "memory.maxBytes");
+	if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > MEMORY_MAX_BYTES)) errors.push({ name: "memory.maxBytes", message: t("agents.validation.memory.range", { max: MEMORY_MAX_BYTES }) });
+	if (own.schema !== undefined && own.schema !== 1) errors.push({ name: "schema", message: t("agents.validation.schema") });
+	if (own.thinking !== undefined && !THINKING_LEVELS.includes(own.thinking)) errors.push({ name: "thinking", message: t("agents.validation.thinking", { levels: THINKING_LEVELS.join(", ") }) });
+	if (own.model !== undefined) {
+		const provider = fieldAt(own, "model.provider");
+		const modelId = fieldAt(own, "model.modelId");
+		if (typeof provider !== "string" || !provider.trim() || typeof modelId !== "string" || !modelId.trim()) errors.push({ name: "model", message: t("agents.validation.model.pair") });
+	}
+	for (const { name, forbidden } of state.registry) if (forbidden && fieldAt(own, name) !== undefined) errors.push({ name, message: t("agents.validation.forbidden", { name }) });
+	const bytes = new TextEncoder().encode(composeSource(state)).length;
+	if (bytes > AGENT_MAX_BYTES) errors.push({ name: "file", message: t("agents.validation.size", { max: AGENT_MAX_BYTES, size: bytes }) });
+	return errors;
+}
+
+/** The request that saves the editor: POST for a new agent, PUT for an existing one or the defaults. */
+export function saveRequest(state) {
+	const body = JSON.stringify({ source: composeSource(state) });
+	const headers = { "content-type": "application/json" };
+	if (state.kind === "defaults") return { method: "PUT", path: DEFAULTS_PATH, headers, body };
+	if (state.kind === "new" || !state.id) return { method: "POST", path: AGENTS_PATH, headers, body };
+	return { method: "PUT", path: `${AGENTS_PATH}/${encodeURIComponent(state.id)}`, headers, body };
+}
+
+/** The delete button works only when the typed name is exactly the agent's current name (the gateway checks the same). */
+export function deleteEnabled(typed, name) {
+	return typeof name === "string" && name !== "" && typed === name;
+}
+
+export function deleteRequest(id, name) {
+	return { method: "POST", path: `${AGENTS_PATH}/${encodeURIComponent(id)}/delete`, headers: { "content-type": "application/json" }, body: JSON.stringify({ name }) };
+}
+
+export function cloneRequest(id) {
+	return { method: "POST", path: `${AGENTS_PATH}/${encodeURIComponent(id)}/clone` };
+}
+
+export function restoreRequest(entry) {
+	return { method: "POST", path: `${TRASH_PATH}/${encodeURIComponent(entry)}/restore` };
+}
+
+export function filesPath(id) {
+	return `${AGENTS_PATH}/${encodeURIComponent(id)}/files`;
+}
+
+export function sourceUploadPath(id) {
+	return `${AGENTS_PATH}/${encodeURIComponent(id)}/source`;
+}
+
+const ERROR_LINES = Object.freeze({
+	name_mismatch: "agents.error.name_mismatch",
+	agent_busy: "agents.error.agent_busy",
+	agent_not_found: "agents.error.agent_not_found",
+	invalid_agent_definition: "agents.error.invalid_agent_definition",
+	invalid_request: "agents.error.invalid_request",
+	too_large: "agents.error.too_large",
+	missing_file: "agents.error.missing_file",
+	invalid_filename: "agents.error.invalid_filename",
+	file_exists: "agents.error.file_exists",
+	exists: "agents.error.exists",
+	invalid_trash_entry: "agents.error.invalid_trash_entry",
+	forbidden: "agents.error.forbidden",
+	method_not_allowed: "agents.error.method_not_allowed",
+});
+
+/** The Korean line for a gateway refusal (`{ error, field? }` with its HTTP status). */
+export function errorLine(body, status) {
+	const code = typeof body?.error === "string" ? body.error : null;
+	const base = code && ERROR_LINES[code] ? t(ERROR_LINES[code]) : `${t("agents.error.rejected")} (${code ?? `HTTP ${status}`})`;
+	return typeof body?.field === "string" && body.field ? `${base}: ${body.field}` : base;
+}
+
+/** `agent.updated` from the gateway: a summary upserts the agent (and brings its conversation back after a restore); `hidden` removes both. */
+export function applyAgentUpdate(agents, conversations, data, now = Date.now()) {
+	if (!isObject(data) || typeof data.id !== "string") return { agents, conversations, removedConv: null, restoredConv: null };
+	if (data.hidden === true) {
+		const convId = typeof data.convId === "string" ? data.convId : agents.find((p) => p.id === data.id)?.convId ?? null;
+		return {
+			agents: agents.filter((p) => p.id !== data.id),
+			conversations: conversations.filter((c) => c.id !== convId && c.agentId !== data.id),
+			removedConv: convId, restoredConv: null,
+		};
+	}
+	const summary = { ...data };
+	const next = agents.some((p) => p.id === data.id) ? agents.map((p) => (p.id === data.id ? { ...p, ...summary } : p)) : [...agents, summary];
+	let restoredConv = null;
+	let convs = conversations;
+	if (typeof data.convId === "string") {
+		if (!conversations.some((c) => c.id === data.convId)) {
+			convs = [...conversations, { id: data.convId, title: String(data.name ?? data.id), threadId: null, createdAt: new Date(now).toISOString(), agentId: data.id }];
+			restoredConv = data.convId;
+		} else if (typeof data.name === "string") convs = conversations.map((c) => (c.id === data.convId && c.title !== data.name ? { ...c, title: data.name } : c));
+	}
+	return { agents: next, conversations: convs, removedConv: null, restoredConv };
+}
+
+/** `agent.applied` of a conversation: the new session carries `sha`; the badge stays only while the definition differs. */
+export function applyAgentApplied(agents, convId, data) {
+	const sha = typeof data?.sha === "string" ? data.sha : null;
+	if (!sha) return agents;
+	return agents.map((p) => (p.convId === convId ? { ...p, stale: p.definitionSha !== sha } : p));
+}
+
+/**
+ * Improvement 262: the sidebar shows the one main conversation and one conversation per agent. Other conversations
+ * without an agent (made by the old "+" button) stay hidden; the gateway keeps them.
+ */
+export function mainConversations(conversations) {
+	return conversations.filter((c) => c.id === "main" && !c.agentId);
+}
+
+/** Each agent's one conversation: the first in conversation order when a store still holds more than one. */
+function agentConversations(conversations) {
+	const seen = new Set();
+	return conversations.filter((c) => {
+		if (!c.agentId || seen.has(c.agentId)) return false;
+		seen.add(c.agentId);
+		return true;
+	});
+}
+
+/** The conversation to open for `id`: itself when the sidebar lists it (main or an agent's conversation), else main. */
+export function shownConversation(conversations, id) {
+	return agentConversations(conversations).some((c) => c.id === id) ? id : "main";
+}
+
+export function agentInitial(name) {
+	const text = String(name ?? "").trim();
+	return text ? [...text][0] : DEFAULT_ICON;
+}
+
+/** The sidebar group's rows, in conversation order: icon (or the name's first letter), name, running dot, stale and pending. */
+export function sidebarItems(conversations, agents, view) {
+	const items = [];
+	for (const conv of agentConversations(conversations)) {
+		const agent = agents.find((p) => p.id === conv.agentId) ?? null;
+		const name = agent?.name ?? conv.title;
+		items.push({
+			convId: conv.id, agentId: conv.agentId, name, description: agent?.description ?? "",
+			icon: typeof agent?.icon === "string" && agent.icon.trim() ? agent.icon.trim() : agentInitial(name),
+			active: conv.id === view.current, running: view.running.has(conv.id) || view.busy(conv.id) === true,
+			pending: (view.pending.get(conv.id) ?? 0) > 0, stale: agent?.stale === true,
+		});
+	}
+	return items;
+}
+
+/** The chat header for the open conversation: the agent name and its stale badge, or nothing for main. */
+export function headerView(conv, agents) {
+	if (!conv?.agentId) return { agent: false, icon: "", name: "", stale: false, agentId: null };
+	const agent = agents.find((p) => p.id === conv.agentId) ?? null;
+	const name = agent?.name ?? conv.title;
+	return {
+		agent: true, agentId: conv.agentId, name,
+		icon: typeof agent?.icon === "string" && agent.icon.trim() ? agent.icon.trim() : agentInitial(name),
+		stale: agent?.stale === true,
+	};
+}
+
+/** 보관함 rows: the entry name carries the agent id and the UTC time it was deleted. */
+export function trashRows(entries) {
+	if (!Array.isArray(entries)) return [];
+	return entries.map((entry) => {
+		const match = /^([a-f0-9]{8})-(.+)$/.exec(String(entry.entry ?? ""));
+		const deletedAt = match && !Number.isNaN(Date.parse(match[2])) ? new Date(match[2]).toISOString() : null;
+		return { entry: String(entry.entry ?? ""), id: match?.[1] ?? null, name: String(entry.name ?? ""), description: String(entry.description ?? ""), icon: typeof entry.icon === "string" && entry.icon ? entry.icon : agentInitial(entry.name), deletedAt };
+	});
+}
+
+/** Knowledge file rows, folders first within each folder, with a size label; `source/` files are the ones the web uploads. */
+export function fileRows(entries) {
+	if (!Array.isArray(entries)) return [];
+	const rows = entries.filter((e) => typeof e?.path === "string").map((e) => ({
+		path: e.path, type: e.type === "directory" ? "directory" : "file", size: typeof e.size === "number" ? e.size : 0,
+		depth: e.path.split("/").length - 1, name: e.path.slice(e.path.lastIndexOf("/") + 1),
+		label: e.type === "directory" ? t("agents.file.folder") : formatBytes(typeof e.size === "number" ? e.size : null),
+		source: e.path === "source" || e.path.startsWith("source/"),
+	}));
+	return rows.sort((a, b) => a.path.localeCompare(b.path, "ko"));
+}