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

package/web/agents.js

@@ -13,19 +13,21 @@ registerStrings(strings);
 export const AGENTS_PATH = "/api/agents";
 export const DEFAULTS_PATH = "/api/agents/defaults";
 export const TRASH_PATH = "/api/agents/trash";
+export const DRAFTS_PATH = "/api/agents/drafts";
+/** The quiet period after the last change before the create screen saves its draft (agent-ux todo 11). */
+export const DRAFT_DELAY_MS = 1500;
+/** How long a draft reopen waits for that draft's saves still on the wire before it opens from the newest local state (todo 18 fix 4). */
+export const DRAFT_REOPEN_WAIT_MS = 10_000;
 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") });
@@ -34,23 +36,31 @@ function originLabels() {
 // 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 four headings a role instruction should cover (agent-ux todo 9), in the UI language: the scope, the tasks (with
+ * the outputs/ folder), what not to do, and the form of address (which overrides the profile nickname rule when set).
+ * app.js draws them as the guide above the body; the body's placeholder is an example with the same headings.
+ */
+export function roleGuideItems() {
+	return ["scope", "tasks", "limits", "address"].map((key) => ({ key, label: t(`agents.roleGuide.${key}`), text: t(`agents.roleGuide.${key}.text`) }));
+}
+
 /**
  * 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.
+ * as the label, so a new registry row needs no web change. `hidden: true` keeps a row out of the editor while its value
+ * stays in the saved source: the schema version is hidden here as well as by the gateway's flag, so an older gateway's
+ * registry without the flag hides it too (agent-ux todo 8).
  */
 export const FIELD_PRESENTATION = Object.freeze({
-	schema: { label: "agents.field.schema.label", help: "agents.field.schema.help" },
+	schema: { label: "agents.field.schema.label", help: "agents.field.schema.help", hidden: true },
 	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" },
@@ -58,8 +68,11 @@ export const FIELD_PRESENTATION = Object.freeze({
 	"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" },
+	// The gateway marks the collaboration rows hidden for older webs; this web draws them (292 C-10) as a directional check list.
+	collaboration: { label: "agents.field.collaboration.label", hidden: false },
+	"collaboration.targets": { label: "agents.field.collaboration.targets.label", help: "agents.field.collaboration.targets.help", hidden: false, widget: "targets" },
 	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" },
+	"tools.bash": { label: "agents.field.tools.bash.label", help: "agents.field.tools.forbidden.help" }, "tools.eval": { label: "agents.field.tools.eval.label", help: "agents.field.tools.forbidden.help" },
 	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" },
@@ -489,8 +502,33 @@ export function splitSource(source) {
  * `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 { split, own, rawByKey, unparsed, unknownRaw } = parseEntries(detail?.source ?? "", registry);
+	// defaults.md as the gateway parsed it (todo 12 fix 2): `fields` of the defaults answer, `defaultsFields` of a detail. It is the shared
+	// layer under an agent's own values; the defaults editor edits that layer itself, so it has none above its own values. The text is
+	// never parsed here: this reader covers the block style the editor writes, the gateway's parser also flow style and anchors.
+	const defaults = kind !== "defaults" && isObject(detail?.defaultsFields) ? structuredClone(detail.defaultsFields) : {};
+	// The layers under this definition's own values, and for an existing agent what the gateway merged for it (its own values included).
+	const inherited = inheritedFields(registry, defaults);
+	const merged = kind === "agent" && isObject(detail?.fields) ? detail.fields : {};
+	return {
+		kind, registry, id: kind === "agent" ? detail?.id ?? null : null, name: kind === "agent" ? detail?.name ?? null : null,
+		defaults,
+		// Only a new agent has a draft (todo 11): the id the web made, or the id of the draft being reopened.
+		draftId: kind === "new" && typeof detail?.draftId === "string" ? detail.draftId : null,
+		// What the gateway holds now (todo 13): the merged sha the save answer is compared with, and the text an untouched editor composes.
+		definitionSha: kind === "agent" && typeof detail?.definitionSha === "string" ? detail.definitionSha : null,
+		serverSource: kind !== "new" && typeof detail?.source === "string" ? detail.source : 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.body, bodyTouched: false,
+		inherited, merged, origins: kind === "agent" && isObject(detail?.origins) ? detail.origins : {}, dirty: false,
+	};
+}
+
+/** A definition text split by its known top-level entries: `own` holds what the reader could parse, `unparsed` the keys it could not, `unknownRaw` the rest. */
+function parseEntries(source, registry) {
+	const split = splitSource(source);
 	const known = topLevelKeys(registry);
 	const own = {};
 	const rawByKey = {};
@@ -508,14 +546,7 @@ export function editorState(detail, kind = "agent") {
 			}
 		} 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,
-	};
+	return { split, own, rawByKey, unparsed, unknownRaw };
 }
 
 /** The registry's package defaults as nested fields (the values every agent has before defaults.md and agent.md). */
@@ -525,11 +556,19 @@ export function packageDefaults(registry) {
 	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. */
+/**
+ * The rows the editor draws, in the gateway's registry order: a `group` row before its children and a `field` row per
+ * leaf. A hidden row is left out (its value stays in the source). A forbidden row is a read-only `forbidden` row: the
+ * editor shows it switched off with the reason in `help` and never writes a value for it.
+ */
 export function editorRows(state) {
 	const rows = [];
 	for (const field of state.registry) {
-		if (field.forbidden) continue;
+		if (field.hidden === true) continue;
+		if (field.forbidden) {
+			rows.push({ kind: "forbidden", name: field.name, label: field.label, help: field.help });
+			continue;
+		}
 		if (state.kind === "defaults" && field.required) continue;
 		const top = field.name.split(".")[0];
 		if (field.widget === "group" || field.widget === "model") {
@@ -538,11 +577,16 @@ export function editorRows(state) {
 		}
 		const ownValue = fieldAt(state.own, field.name);
 		const own = ownValue !== undefined;
-		const inheritedValue = state.kind === "agent" ? fieldAt(state.inherited, field.name) : field.default;
+		// An untouched field of an existing agent shows what the gateway merged for it and the origin it named (exact even for
+		// text the reader cannot parse). A touched field, and every field while creating, shows the layers under the own values
+		// (package defaults, then defaults.md), so a cleared override falls back to the shared or package value (gate review B3).
+		const fromServer = state.kind === "agent" && !own && !state.touched.has(top);
+		const inheritedValue = state.kind === "defaults" ? field.default : fieldAt(fromServer ? state.merged : state.inherited, field.name);
 		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 if (fromServer) origin = state.origins[field.name] ?? (value === undefined ? "none" : "package");
+		else if (fieldAt(state.defaults, field.name) !== undefined) origin = "defaults";
 		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,
@@ -555,6 +599,88 @@ export function editorRows(state) {
 	return rows;
 }
 
+export const PREVIEW_PATH = "/api/agents/preview";
+/** The box asks the gateway this long after the last change: shorter than the draft's quiet period, so the box follows typing. */
+export const PREVIEW_DELAY_MS = 300;
+
+/**
+ * The can/cannot box's request (agent-ux todo 12): the editor's composed text, raw YAML included, for the gateway to
+ * evaluate exactly as a save would read it (its own parser and merge with the current defaults.md); nothing is written.
+ * The browser computes no permission itself: its reader covers only the block style the editor writes. The create screen
+ * sends `kind: "new"`, so the box shows what the new agent could do before it has a name and description (agent-ux int).
+ */
+export function previewRequest(state) {
+	const body = state.kind === "new" ? { source: composeSource(state), kind: "new" } : { source: composeSource(state) };
+	return { method: "POST", path: PREVIEW_PATH, headers: { "content-type": "application/json" }, body: JSON.stringify(body) };
+}
+
+/**
+ * The box's state after the gateway answered: a valid answer brings the merged fields a save of that text would apply;
+ * text the gateway refuses gives `unavailable` (the box shows a line, never a guess); a failed request or an unreadable
+ * answer gives `failed` - the current text was not evaluated, so no older answer is shown as if it were (todo 12 fix 4).
+ */
+export function previewState(answer) {
+	if (isObject(answer) && answer.valid === true && isObject(answer.fields)) return { status: "ready", fields: answer.fields };
+	if (isObject(answer) && answer.valid === false) return { status: "unavailable", fields: null };
+	return { status: "failed", fields: null };
+}
+
+/** What a definition inherits before its own values: the registry's package defaults with defaults.md over them (what the rows show). */
+function inheritedFields(registry, defaults) {
+	const fields = packageDefaults(registry);
+	applyLayer(fields, defaults, registry);
+	return fields;
+}
+
+/** One definition layer over `fields`, as the gateway applies it: a registry row with merge "keys" merges an object per key; anything else replaces the value. */
+function applyLayer(fields, input, registry, prefix = []) {
+	for (const [key, value] of Object.entries(input)) {
+		const path = [...prefix, key];
+		const field = registry.find((row) => row.name === path.join("."));
+		if (field?.merge === "keys") {
+			if (isObject(value)) {
+				applyLayer(fields, value, registry, path);
+				continue;
+			}
+		}
+		setPath(fields, path, structuredClone(value));
+	}
+}
+
+/**
+ * What the agent can and cannot do with the merged fields the gateway answered (agent-ux todo 12), as the extension
+ * enforces it: the file tools confined to knowledge/ with writes only under outputs/, notes/ and MEMORY.md
+ * (host/omo-bridge/agent-control.ts BASE_TOOLS and the write scope), its own history search, confirmation questions, web
+ * research only with tools.web, the checked skills, and the end-of-reply notification with notify. Each item carries a
+ * tooltip with the detail.
+ */
+export function capabilities(merged) {
+	const item = (key, text, tip) => ({ key, text, tip });
+	const web = fieldAt(merged, "tools.web") === true;
+	const notify = fieldAt(merged, "notify") === true;
+	const skills = fieldAt(merged, "skills");
+	const names = Array.isArray(skills) ? skills.filter((name) => typeof name === "string" && name.trim()).map((name) => name.trim()) : [];
+	const can = [
+		item("read", t("agents.cap.read"), t("agents.cap.read.tip")),
+		item("write", t("agents.cap.write"), t("agents.cap.write.tip")),
+		item("history", t("agents.cap.history"), t("agents.cap.history.tip")),
+		item("ask", t("agents.cap.ask"), t("agents.cap.ask.tip")),
+	];
+	const cannot = [
+		item("shell", t("agents.cap.shell"), t("agents.cap.shell.tip")),
+		item("source", t("agents.cap.source"), t("agents.cap.source.tip")),
+		item("outside", t("agents.cap.outside"), t("agents.cap.outside.tip")),
+		item("works", t("agents.cap.works"), t("agents.cap.works.tip")),
+		item("others", t("agents.cap.others"), t("agents.cap.others.tip")),
+	];
+	if (web) can.push(item("web", t("agents.cap.web"), t("agents.cap.web.on.tip")));
+	else cannot.push(item("web", t("agents.cap.web"), t("agents.cap.web.off.tip")));
+	if (names.length > 0) can.push(item("skills", t("agents.cap.skills", { count: names.length, names: names.join(", ") }), t("agents.cap.skills.tip")));
+	else cannot.push(item("skills", t("agents.cap.skills.none"), t("agents.cap.skills.tip")));
+	if (notify) can.push(item("notify", t("agents.cap.notify"), t("agents.cap.notify.tip")));
+	return { can, cannot };
+}
+
 /** 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) };
@@ -566,9 +692,10 @@ export function widgetValue(field, input) {
 		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 === "skills" || field.widget === "targets") {
+		// The check list (todo 10, 292 targets) gives the checked names as an array; a text value is still read as a comma or line list.
+		const names = Array.isArray(input) ? input.map((item) => String(item)) : text.split(/[\n,]+/);
+		return { value: [...new Set(names.map((item) => item.trim()).filter(Boolean))] };
 	}
 	if (field.widget === "select") {
 		if (text === "") return { value: undefined };
@@ -578,6 +705,28 @@ export function widgetValue(field, input) {
 	return { value: text.trim() === "" ? undefined : text };
 }
 
+/**
+ * The allowed-skills check list (agent-ux todo 10). `commands` is GET /api/commands?conv=main: its `source: "skill"` rows
+ * (the `skill:` prefix removed, duplicates dropped, sorted) are the installed skills, checked when the saved value names
+ * them (in either form, as the gateway's allowedAgentCommands matches). A saved name that is not installed stays first,
+ * checked and `installed: false`, so saving keeps it and the user can still uncheck it. A `commands` that is not a list
+ * (the gateway answered 503 or the request failed) gives `loaded: false` and only the saved names, `installed: null`.
+ */
+export function skillOptions(commands, saved) {
+	const bare = (name) => String(name).replace(/^skill:/, "").trim();
+	const savedNames = [...new Set((Array.isArray(saved) ? saved : []).filter((name) => typeof name === "string").map(bare).filter(Boolean))];
+	if (!Array.isArray(commands)) return { loaded: false, options: savedNames.map((name) => ({ name, checked: true, installed: null, description: "" })) };
+	const installed = new Map();
+	for (const command of commands) {
+		if (!isObject(command) || command.source !== "skill" || typeof command.name !== "string") continue;
+		const name = bare(command.name);
+		if (name && !installed.has(name)) installed.set(name, typeof command.description === "string" ? command.description : "");
+	}
+	const missing = savedNames.filter((name) => !installed.has(name)).map((name) => ({ name, checked: true, installed: false, description: "" }));
+	const listed = [...installed].sort(([a], [b]) => a.localeCompare(b)).map(([name, description]) => ({ name, checked: savedNames.includes(name), installed: true, description }));
+	return { loaded: true, options: [...missing, ...listed] };
+}
+
 /** 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);
@@ -646,13 +795,189 @@ export function validateEditor(state) {
 	return errors;
 }
 
-/** The request that saves the editor: POST for a new agent, PUT for an existing one or the defaults. */
+/**
+ * The request that saves the editor: POST for a new agent (with its draft id, so the gateway archives the draft), 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 };
+	if (state.kind === "defaults") return { method: "PUT", path: DEFAULTS_PATH, headers, body: JSON.stringify({ source: composeSource(state) }) };
+	if (state.kind === "new" || !state.id) {
+		const body = JSON.stringify(typeof state.draftId === "string" && state.draftId ? { source: composeSource(state), draftId: state.draftId } : { source: composeSource(state) });
+		return { method: "POST", path: AGENTS_PATH, headers, body };
+	}
+	return { method: "PUT", path: `${AGENTS_PATH}/${encodeURIComponent(state.id)}`, headers, body: JSON.stringify({ source: composeSource(state) }) };
+}
+
+const DRAFT_ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+
+/** A draft id the web makes (agent-ux todo 11): 12 lowercase letters or digits; the random source is injectable for tests. */
+export function newDraftId(random = cryptoRandom) {
+	let id = "";
+	for (let i = 0; i < 12; i += 1) id += DRAFT_ID_ALPHABET[Math.min(DRAFT_ID_ALPHABET.length - 1, Math.floor(random() * DRAFT_ID_ALPHABET.length))];
+	return id;
+}
+
+function cryptoRandom() {
+	return crypto.getRandomValues(new Uint32Array(1))[0] / 2 ** 32;
+}
+
+/**
+ * The create screen's draft autosave (agent-ux todo 11, 18): durable, one lane per draft id. `touch(state)` keeps the
+ * latest state of the lane of `state.draftId` and (re)starts that lane's quiet period through the injected scheduler; when
+ * it ends the state is due. A due state is never dropped: it goes out at once, or behind the lane's request on the wire,
+ * in order, whatever is touched afterwards for any draft (one request per draft on the wire, so an older answer never
+ * lands after a newer one; a lane's own newer state waits for its own quiet period). `flush()` makes every waiting
+ * state due at once (the dialog closes); `settle(draftId)` does that for one draft and resolves once its wire is clear,
+ * returning false when the last save returned false or rejected; `latest(draftId)` is the newest state this page holds for a draft; `pending` says whether any
+ * state still waits; `idle` resolves once every wire is clear.
+ */
+export function createDraftSaver(save, { delayMs = DRAFT_DELAY_MS, setTimer = (fn, ms) => setTimeout(fn, ms), clearTimer = (handle) => clearTimeout(handle) } = {}) {
+	const lanes = new Map();
+	const laneOf = (id) => {
+		let lane = lanes.get(id);
+		if (!lane) {
+			lane = { latest: null, handle: null, due: [], inflight: null, last: null, saved: true };
+			lanes.set(id, lane);
+		}
+		return lane;
+	};
+	// A lane stays in the map once made (a handful of small objects per session): a clean lane and a fresh one behave the same.
+	const send = (lane, state) => {
+		const result = save(state);
+		if (typeof result?.then !== "function") {
+			lane.saved = result !== false;
+			if (lane.due.length > 0) send(lane, lane.due.shift());
+			return;
+		}
+		lane.inflight = Promise.resolve(result).then((saved) => { lane.saved = saved !== false; }, () => { lane.saved = false; }).then(() => {
+			lane.inflight = null;
+			if (lane.due.length > 0) send(lane, lane.due.shift());
+		});
+	};
+	const fire = (lane) => {
+		lane.handle = null;
+		if (lane.latest === null) return;
+		const state = lane.latest;
+		lane.latest = null;
+		if (lane.inflight !== null) lane.due.push(state);
+		else send(lane, state);
+	};
+	return {
+		touch(state) {
+			const lane = laneOf(state.draftId);
+			lane.latest = state;
+			lane.last = state;
+			if (lane.handle !== null) clearTimer(lane.handle);
+			lane.handle = setTimer(() => fire(lane), delayMs);
+		},
+		flush() {
+			let any = false;
+			for (const lane of [...lanes.values()]) {
+				if (lane.handle === null) continue;
+				clearTimer(lane.handle);
+				any = true;
+				fire(lane);
+			}
+			return any;
+		},
+		async settle(draftId) {
+			const lane = lanes.get(draftId);
+			if (!lane) return true;
+			if (lane.handle !== null) {
+				clearTimer(lane.handle);
+				fire(lane);
+			}
+			while (lane.inflight !== null) await lane.inflight;
+			return lane.saved;
+		},
+		/** The newest state this page holds for a draft (waiting, due or sent), or null: what a reopen falls back to when the wire does not answer. */
+		latest(draftId) { return lanes.get(draftId)?.last ?? null; },
+		get pending() { return [...lanes.values()].some((lane) => lane.handle !== null || lane.due.length > 0); },
+		get idle() { return Promise.all([...lanes.values()].map((lane) => lane.inflight ?? Promise.resolve())).then(() => undefined); },
+	};
+}
+
+/**
+ * The can/cannot box's preview requests (agent-ux todo 12, 18): disposable, owned by one editor at a time. `touch(state)`
+ * restarts the quiet period for the current owner and `flush()` asks at once; one request on the wire, the latest state
+ * after it. `request(state, token)` gets the owner token of the moment it goes out; `discard()` (the editor closes,
+ * changes or is replaced) drops what waits - a state flushed behind the wire included - and moves the token on, so the
+ * caller ignores the answer of an earlier owner (`owns(token)` is false) and nothing of a gone editor is ever drawn.
+ */
+export function createPreviewRequester(request, { delayMs = DRAFT_DELAY_MS, setTimer = (fn, ms) => setTimeout(fn, ms), clearTimer = (handle) => clearTimeout(handle) } = {}) {
+	let owner = 1;
+	let handle = null;
+	let latest = null;
+	let queued = false;
+	let inflight = null;
+	const send = (state) => {
+		const result = request(state, owner);
+		if (typeof result?.then !== "function") return;
+		inflight = Promise.resolve(result).then(() => undefined, () => undefined).then(() => {
+			inflight = null;
+			if (!queued) return;
+			queued = false;
+			const next = latest;
+			latest = null;
+			send(next);
+		});
+	};
+	const fire = () => {
+		handle = null;
+		if (latest === null) return;
+		if (inflight !== null) {
+			queued = true;
+			return;
+		}
+		const state = latest;
+		latest = null;
+		send(state);
+	};
+	return {
+		touch(state) {
+			latest = state;
+			queued = false;
+			if (handle !== null) clearTimer(handle);
+			handle = setTimer(fire, delayMs);
+		},
+		flush() {
+			if (handle === null) return false;
+			clearTimer(handle);
+			fire();
+			return true;
+		},
+		discard() {
+			if (handle !== null) clearTimer(handle);
+			handle = null;
+			latest = null;
+			queued = false;
+			owner += 1;
+		},
+		owns(token) { return token === owner; },
+		get token() { return owner; },
+		get pending() { return handle !== null || queued; },
+		get idle() { return inflight ?? Promise.resolve(); },
+	};
+}
+
+/** The autosave request: the composed source as typed (the gateway does not validate it) with the picked files' names and sizes. */
+export function draftRequest(state, files = []) {
+	return { method: "PUT", path: `${DRAFTS_PATH}/${encodeURIComponent(state.draftId)}`, headers: { "content-type": "application/json" }, body: JSON.stringify({ source: composeSource(state), kind: "new", files }) };
+}
+
+/** GET /api/agents/drafts rows as the gateway sends them (newest first); a half-typed draft without a name has null. */
+export function draftRows(list) {
+	if (!Array.isArray(list)) return [];
+	return list.filter((row) => isObject(row) && typeof row.id === "string").map((row) => ({ id: row.id, name: typeof row.name === "string" && row.name ? row.name : null, updatedAt: typeof row.updatedAt === "string" ? row.updatedAt : "" }));
+}
+
+export function draftLoadRequest(id) {
+	return { method: "GET", path: `${DRAFTS_PATH}/${encodeURIComponent(id)}` };
+}
+
+export function discardDraftRequest(id) {
+	return { method: "DELETE", path: `${DRAFTS_PATH}/${encodeURIComponent(id)}` };
 }
 
 /** The delete button works only when the typed name is exactly the agent's current name (the gateway checks the same). */
@@ -668,8 +993,106 @@ 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` };
+/** The restore call of an archive entry; `newId: true` asks the gateway for a fresh id when the entry's own id is live again (plan todo 22). */
+export function restoreRequest(entry, { newId = false } = {}) {
+	const path = `${TRASH_PATH}/${encodeURIComponent(entry)}/restore`;
+	return newId ? { method: "POST", path, headers: { "content-type": "application/json" }, body: JSON.stringify({ newId: true }) } : { method: "POST", path };
+}
+
+/**
+ * What the archive row shows for a restore answer: the restored agent's detail, the same-id conflict (409 `exists`, the
+ * row offers a restore under a new id) or the refusal line.
+ */
+export function restoreOutcome(status, body) {
+	if (status >= 200 && status < 300) return isObject(body) ? { kind: "restored", detail: body } : { kind: "error", message: errorLine(null, status) };
+	if (status === 409 && isObject(body) && body.error === "exists") return { kind: "conflict", id: typeof body.id === "string" ? body.id : "" };
+	return { kind: "error", message: errorLine(body, status) };
+}
+
+/** The gateway's upload limit (src/media.ts MEDIA_MAX_BYTES); the web refuses a larger file before any request (agent-ux todo 14). */
+export const UPLOAD_MAX_BYTES = 10 * 1024 * 1024;
+
+let uploadKeys = 0;
+
+/**
+ * The upload queue of the files the user picked or dropped (agent-ux todo 14): one row per file with its progress and
+ * state. A file the gateway would refuse (over the limit, empty, or without a name) fails here at once and is never sent.
+ */
+export function uploadRows(files) {
+	if (!files || typeof files.length !== "number") return [];
+	return Array.from(files, (file) => {
+		const name = typeof file?.name === "string" ? file.name : "";
+		const size = typeof file?.size === "number" && Number.isFinite(file.size) ? file.size : 0;
+		const error = size > UPLOAD_MAX_BYTES ? "too_large" : size <= 0 ? "missing_file" : !name || name.startsWith(".") || /[/\\\0]/.test(name) ? "invalid_filename" : null;
+		uploadKeys += 1;
+		return { key: `u${uploadKeys}`, file, name, size, status: error ? "failed" : "waiting", progress: 0, error, errorLine: error ? uploadErrorLine(error) : null, savedName: null };
+	});
+}
+
+/** The sentence for a refused upload: the gateway's code, or the web's own size check with the limit. */
+export function uploadErrorLine(code) {
+	if (code === "too_large") return t("agents.upload.tooLarge", { max: formatBytes(UPLOAD_MAX_BYTES) });
+	const key = `agents.error.${code}`;
+	const line = t(key);
+	return line === key ? t("agents.error.rejected") : line;
+}
+
+/**
+ * The create screen's queue (agent-ux todo 18): the same rows, but `queued` instead of `waiting`, so nextUpload never sends
+ * them - the definition does not exist yet. uploadsAfterCreate turns them into waiting rows once the gateway answered with an id.
+ */
+export function queuedUploadRows(files) {
+	return uploadRows(files).map((row) => (row.status === "waiting" ? { ...row, status: "queued" } : row));
+}
+
+/** What the draft keeps of the queue: names and sizes of the files that would be uploaded, never the files (todo 11, 18). */
+export function draftFileList(rows) {
+	return rows.filter((row) => row.status === "queued").map((row) => ({ name: row.name, size: row.size }));
+}
+
+/** After the create request: the new agent's id and the queue as waiting rows, or null when the answer carries no id or nothing is queued. */
+export function uploadsAfterCreate(body, rows) {
+	const id = isObject(body) && typeof body.id === "string" && body.id ? body.id : null;
+	if (id === null || !Array.isArray(rows) || !rows.some((row) => row.status === "queued")) return null;
+	return { id, rows: rows.map((row) => (row.status === "queued" ? { ...row, status: "waiting" } : row)) };
+}
+
+/** The first row still waiting (uploads go one by one, in order); null when nothing waits. */
+export function nextUpload(rows) {
+	return rows.find((row) => row.status === "waiting") ?? null;
+}
+
+/** The rows with one row changed: a new state, its progress (0..1) and, when done, the name the gateway saved it under. */
+export function advanceUpload(rows, key, patch) {
+	return rows.map((row) => {
+		if (row.key !== key) return row;
+		const status = patch.status ?? row.status;
+		const progress = status === "done" ? 1 : status === "failed" || status === "waiting" ? 0 : typeof patch.progress === "number" ? Math.min(1, Math.max(0, patch.progress)) : row.progress;
+		const error = status === "failed" ? patch.error ?? row.error ?? "rejected" : null;
+		return { ...row, status, progress, error, errorLine: status === "failed" ? patch.errorLine ?? uploadErrorLine(error) : null, savedName: status === "done" ? patch.savedName ?? row.name : row.savedName };
+	});
+}
+
+/** A failed upload back in the queue; a file the web itself refused (too large, empty, bad name) stays failed, since sending it would fail the same way. */
+export function retryUpload(rows, key) {
+	return rows.map((row) => (row.key === key && row.status === "failed" && !(row.error === "too_large" && row.size > UPLOAD_MAX_BYTES) && row.error !== "missing_file" && row.error !== "invalid_filename"
+		? { ...row, status: "waiting", progress: 0, error: null, errorLine: null } : row));
+}
+
+export function uploadSummary(rows) {
+	const count = (status) => rows.filter((row) => row.status === status).length;
+	const uploading = count("uploading");
+	const waiting = count("waiting");
+	return { total: rows.length, done: count("done"), failed: count("failed"), waiting, uploading, active: uploading > 0 || waiting > 0 };
+}
+
+/** The state text of one row: 대기, 만들기 뒤 올립니다, 올리는 중 N%, 완료, or 실패 with its reason. */
+export function uploadStateLine(row) {
+	if (row.status === "queued") return t("agents.upload.state.queued");
+	if (row.status === "uploading") return t("agents.upload.state.uploading", { percent: Math.round(row.progress * 100) });
+	if (row.status === "done") return t("agents.upload.state.done");
+	if (row.status === "failed") return t("agents.upload.state.failed", { reason: row.errorLine ?? uploadErrorLine(row.error) });
+	return t("agents.upload.state.waiting");
 }
 
 export function filesPath(id) {
@@ -680,8 +1103,130 @@ export function sourceUploadPath(id) {
 	return `${AGENTS_PATH}/${encodeURIComponent(id)}/source`;
 }
 
+/** The editor composes exactly the gateway's text (nothing was changed), so there is nothing to save (todo 13, bug 285). */
+export function unchangedSource(state) {
+	return typeof state.serverSource === "string" && composeSource(state) === state.serverSource;
+}
+
+/**
+ * An `agent.updated` for the agent the open editor shows, whose saved definition changed elsewhere (another tab revoked a
+ * collaboration target, say): "reload" for an untouched editor, so it never shows or saves back what was revoked; "changed" for
+ * an editor with unsaved edits, which keeps them and must say that saving writes its copy over the change; else null.
+ */
+export function editorUpdateAction(editor, data) {
+	if (!isObject(editor) || editor.kind !== "agent" || !isObject(data) || data.id !== editor.id || data.hidden === true) return null;
+	if (typeof data.definitionSha !== "string" || data.definitionSha === editor.definitionSha) return null;
+	return editor.dirty === true ? "changed" : "reload";
+}
+
+/** What a save did: the merged sha the gateway answered against the sha before, and whether an open session now lags. */
+export function saveOutcome(state, body) {
+	const sha = typeof body?.definitionSha === "string" ? body.definitionSha : null;
+	return { changed: sha === null || sha !== state.definitionSha, stale: body?.stale === true };
+}
+
+/**
+ * agent-ux todo 21: what "지금 적용" applies after a save - the agent, its conversation and the saved sha - only when the save
+ * changed the definition and the agent's open session now lags; else null (no button).
+ */
+export function applyNowTarget(outcome, body) {
+	if (!outcome.changed || !outcome.stale) return null;
+	if (typeof body?.id !== "string" || typeof body.convId !== "string" || typeof body.definitionSha !== "string") return null;
+	return { agentId: body.id, convId: body.convId, sha: body.definitionSha };
+}
+
+/** The button stays only while that agent is still stale (an agent.applied with the saved sha ends it). */
+export function applyNowShown(target, agents) {
+	return target !== null && agents.some((p) => p.id === target.agentId && p.stale === true);
+}
+
+/** The header new-session request: an agent conversation whose definition changed opens its next session at once (todo 21). */
+export function rotateRequest(convId, view) {
+	if (view.agent && view.stale) return { type: "conversation.rotate", conv: convId, open: true };
+	return { type: "conversation.rotate", conv: convId };
+}
+
+/** How long "지금 적용" waits for the rotation and the new session's agent.applied before it says it could not confirm. */
+export const APPLY_WAIT_MS = 30_000;
+
+/**
+ * Follows one "지금 적용" request through its conversation's events: null while it waits, else the outcome. Success is
+ * only the agent.applied after session.rotated whose sha is the saved one; another sha (or null, a mixed session) is a
+ * mismatch. The gateway's agent_open_failed and turn_running refusals end the wait; other events are ignored.
+ */
+export function applyWatch(target) {
+	let rotated = false;
+	return (event) => {
+		if (event?.conv !== target.convId) return null;
+		if (event.type === "session.rotated") rotated = true;
+		if (event.type === "agent.applied" && rotated) return event.data?.sha === target.sha ? "applied" : "mismatch";
+		if (event.type === "error" && event.data?.message === "agent_open_failed") return "open_failed";
+		if (event.type === "error" && event.data?.code === "turn_running") return "turn_running";
+		return null;
+	};
+}
+
+/**
+ * T21W-B1: the events after which the page reads the gateway's agent list again - an agent conversation's rotation, any
+ * agent.applied and a failed open - so the header and its open:true decision follow the gateway, not a retired session.
+ */
+export function reconcileAgents(event, agents) {
+	if (event?.type === "agent.applied") return true;
+	if (event?.type === "session.rotated") return agents.some((p) => p.convId === event.conv);
+	return event?.type === "error" && event.data?.message === "agent_open_failed";
+}
+
+/**
+ * T21W-B2: the one ordering rule of the agent list. Every write (a list answer, agent.updated, a save answer,
+ * agent.applied) moves the list's stamp on; a list answer may land only when the stamp is still the one its request
+ * was sent at, so it never overwrites a newer write.
+ */
+export function freshListAnswer(sentStamp, stampNow) {
+	return sentStamp === stampNow;
+}
+
+const APPLY_LINES = Object.freeze({
+	applied: "agents.apply.done",
+	mismatch: "agents.apply.mismatch",
+	open_failed: "agents.apply.openFailed",
+	turn_running: "agents.apply.turnRunning",
+	unconfirmed: "agents.apply.unconfirmed",
+});
+
+/** The editor status line for an outcome of applyWatch (or "unconfirmed" when nothing answered in time). */
+export function applyLine(result) {
+	return t(Object.hasOwn(APPLY_LINES, result) ? APPLY_LINES[result] : APPLY_LINES.unconfirmed);
+}
+
+const SAVE_ERROR_LINES = Object.freeze({
+	agent_busy: "agents.error.save.agent_busy",
+	exists: "agents.error.save.exists",
+	file_exists: "agents.error.save.file_exists",
+	too_large: "agents.error.save.too_large",
+	invalid_filename: "agents.error.save.invalid_filename",
+	file_not_deletable: "agents.error.save.file_not_deletable",
+});
+
+/**
+ * The sentence for a failed save (todo 13): the gateway's code (app.js agentApi puts `code`, `field`, `status` and
+ * `network` on the thrown error) becomes what happened and what to do; an invalid definition names the field by its
+ * editor label; a request that never reached the gateway says the text is kept. Other errors keep their message.
+ */
+export function saveErrorLine(error, fields = []) {
+	if (error?.network === true) return t("agents.error.save.network");
+	const code = typeof error?.code === "string" ? error.code : null;
+	if (code === "invalid_agent_definition") {
+		const field = typeof error.field === "string" && error.field ? error.field : null;
+		if (field === null) return t("agents.error.invalid_agent_definition");
+		return t("agents.error.save.invalid_field", { label: fields.find((row) => row.name === field)?.label ?? field });
+	}
+	if (code !== null && Object.hasOwn(SAVE_ERROR_LINES, code)) return t(SAVE_ERROR_LINES[code]);
+	return typeof error?.message === "string" ? error.message : String(error);
+}
+
 const ERROR_LINES = Object.freeze({
 	name_mismatch: "agents.error.name_mismatch",
+	draft_closed: "agents.error.draft_closed",
 	agent_busy: "agents.error.agent_busy",
 	agent_not_found: "agents.error.agent_not_found",
 	invalid_agent_definition: "agents.error.invalid_agent_definition",
@@ -692,6 +1237,9 @@ const ERROR_LINES = Object.freeze({
 	file_exists: "agents.error.file_exists",
 	exists: "agents.error.exists",
 	invalid_trash_entry: "agents.error.invalid_trash_entry",
+	file_not_deletable: "agents.error.file_not_deletable",
+	file_not_found: "agents.error.file_not_found",
+	invalid_path: "agents.error.invalid_path",
 	forbidden: "agents.error.forbidden",
 	method_not_allowed: "agents.error.method_not_allowed",
 });
@@ -727,11 +1275,18 @@ export function applyAgentUpdate(agents, conversations, data, now = Date.now())
 	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. */
+/**
+ * `agent.applied` of a conversation: the new session carries `sha`; the notice stays only while the definition differs.
+ * A known sha also ends an `unknown` applied state the list was loaded with (bug 283).
+ */
 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));
+	return agents.map((p) => {
+		if (p.convId !== convId) return p;
+		const { staleReason: _reason, ...known } = p;
+		return { ...known, stale: p.definitionSha !== sha };
+	});
 }
 
 /**
@@ -778,18 +1333,45 @@ export function sidebarItems(conversations, agents, view) {
 	return items;
 }
 
-/** The chat header for the open conversation: the agent name and its stale badge, or nothing for main. */
+/**
+ * The chat header for the open conversation: the agent name and its definition state, or nothing for main. `staleReason`
+ * is "unknown" while the gateway could not learn which definition the open session applied (todo 3), else null.
+ */
 export function headerView(conv, agents) {
-	if (!conv?.agentId) return { agent: false, icon: "", name: "", stale: false, agentId: null };
+	if (!conv?.agentId) return { agent: false, icon: "", name: "", stale: false, staleReason: null, agentId: null };
 	const agent = agents.find((p) => p.id === conv.agentId) ?? null;
 	const name = agent?.name ?? conv.title;
+	const stale = agent?.stale === true;
 	return {
 		agent: true, agentId: conv.agentId, name,
 		icon: typeof agent?.icon === "string" && agent.icon.trim() ? agent.icon.trim() : agentInitial(name),
-		stale: agent?.stale === true,
+		stale, staleReason: stale && agent.staleReason === "unknown" ? "unknown" : null,
+	};
+}
+
+/**
+ * Bug 283: the header only says the definition state; the new-session button carries the action. For [view] this is the
+ * status line to show (a key of web/i18n/main.js, drawn in the UI language by app.js), whether the button is highlighted,
+ * and the keys of its label and of the question it asks before `conversation.rotate`.
+ */
+export function staleNotice(view) {
+	if (!view.stale) return { shown: false, textKey: null, attention: false, labelKey: "head.newSession", confirmKey: "head.newSession.confirm" };
+	return {
+		shown: true, textKey: view.staleReason === "unknown" ? "agent.stale.unknown" : "agent.stale.changed",
+		attention: true, labelKey: "head.newSession.apply", confirmKey: "head.newSession.confirm.apply",
 	};
 }
 
+/**
+ * Who speaks in [conv] (bug 284): an agent conversation's bubbles, reference labels and sidebar profile carry the agent's
+ * name and text icon (its emoji, else the name's first letter); main keeps [main]'s name and icon picture.
+ */
+export function speakerView(conv, agents, main) {
+	const view = headerView(conv, agents);
+	if (!view.agent) return { agent: false, agentId: null, name: main.name, icon: null, iconUrl: main.iconUrl ?? null };
+	return { agent: true, agentId: view.agentId, name: view.name, icon: view.icon, iconUrl: null };
+}
+
 /** 보관함 rows: the entry name carries the agent id and the UTC time it was deleted. */
 export function trashRows(entries) {
 	if (!Array.isArray(entries)) return [];
@@ -800,14 +1382,291 @@ export function trashRows(entries) {
 	});
 }
 
-/** Knowledge file rows, folders first within each folder, with a size label; `source/` files are the ones the web uploads. */
+const KNOWLEDGE_AREAS = Object.freeze(["source", "outputs", "notes", "memory", "other"]);
+
+/** The area of a knowledge path: the gateway's `area` field, or read from the path for an older gateway's answer. */
+function knowledgeArea(path, area) {
+	if (KNOWLEDGE_AREAS.includes(area)) return area;
+	if (path === "MEMORY.md") return "memory";
+	const top = path.split("/")[0];
+	return top === "source" || top === "outputs" || top === "notes" ? top : "other";
+}
+
+/** Knowledge file rows, folders first within each folder, with a size label and their area; `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/"),
+		source: e.path === "source" || e.path.startsWith("source/"), area: knowledgeArea(e.path, e.area),
+		modifiedAt: typeof e.modifiedAt === "string" ? e.modifiedAt : null,
+		origin: e.origin === "collaboration-copy" || e.origin === "user-upload" ? e.origin : null,
 	}));
 	return rows.sort((a, b) => a.path.localeCompare(b.path, "ko"));
 }
+
+/** A source/ or outputs/ file can be downloaded (agent-ux todo 17); the gateway serves the todo 2 download route for them. */
+export function downloadable(row) {
+	return row.type === "file" && (row.area === "source" || row.area === "outputs");
+}
+
+export function downloadPath(id, path) {
+	return `${filesPath(id)}/download?path=${encodeURIComponent(path)}`;
+}
+
+/** A file's modified time in the UI locale, or nothing when the gateway sent none. */
+export function modifiedLabel(modifiedAt, locale) {
+	const ms = typeof modifiedAt === "string" ? Date.parse(modifiedAt) : Number.NaN;
+	return Number.isNaN(ms) ? "" : new Date(ms).toLocaleString(locale, { dateStyle: "short", timeStyle: "short" });
+}
+
+/** Whether an ended turn belongs to the agent whose editor is open, so its files (the outputs the answer wrote) are read again. */
+export function turnEndRefreshes(editor, conv) {
+	return editor?.kind === "agent" && typeof editor.convId === "string" && editor.convId === conv;
+}
+
+/**
+ * The rows by screen block (agent-ux todo 15): 올린 자료 (source/), 결과물 (outputs/) and 기록 (MEMORY.md, then notes/). The top
+ * folders are the headings, so they are not rows, and depth counts under them; paths outside the three areas are left out.
+ */
+export function fileAreas(rows) {
+	const under = (area) => rows.filter((row) => row.area === area && row.path !== area).map((row) => ({ ...row, depth: row.depth - 1 }));
+	return { source: under("source"), outputs: under("outputs"), notes: [...rows.filter((row) => row.area === "memory"), ...under("notes")] };
+}
+
+/** The status line after uploads (bug 285): one file or a count, that the agent uses them at once, and every name the gateway changed. */
+export function uploadedLine(saved) {
+	if (saved.length === 0) return "";
+	const line = saved.length === 1 ? t("agents.uploaded.one", { name: saved[0].name }) : t("agents.uploaded.many", { count: saved.length });
+	const renamed = saved.filter((file) => file.savedName !== file.name).map((file) => t("agents.uploaded.renamed", { saved: file.savedName }));
+	return [line, ...renamed].join(" ");
+}
+
+/** Only a regular file under source/ or outputs/ can be deleted (what the gateway accepts, agent-ux todo 16); MEMORY.md, notes/, folders and lock files never. */
+export function deletableFile(row) {
+	return row.type === "file" && (row.area === "source" || row.area === "outputs") && row.path !== row.area && !row.name.endsWith(".lock");
+}
+
+export function fileDeleteRequest(id, path) {
+	return { method: "POST", path: `${filesPath(id)}/delete`, headers: { "content-type": "application/json" }, body: JSON.stringify({ path }) };
+}
+
+export function fileTrashPath(id) {
+	return `${filesPath(id)}/trash`;
+}
+
+export function fileRestoreRequest(id, entry) {
+	return { method: "POST", path: `${fileTrashPath(id)}/${encodeURIComponent(entry)}/restore` };
+}
+
+/** The deleted files of an agent as the gateway lists them (newest first): the archive entry, the original path, its size and when it was deleted. */
+export function fileTrashRows(entries) {
+	if (!Array.isArray(entries)) return [];
+	return entries.filter((e) => isObject(e) && typeof e.entry === "string" && typeof e.path === "string").map((e) => ({
+		entry: e.entry, path: e.path, name: e.path.slice(e.path.lastIndexOf("/") + 1), area: knowledgeArea(e.path, undefined),
+		size: typeof e.size === "number" ? e.size : 0, label: formatBytes(typeof e.size === "number" ? e.size : null), deletedAt: typeof e.deletedAt === "string" ? e.deletedAt : null,
+	}));
+}
+
+export function fileTrashLabel(count) {
+	return t("agents.files.trash", { count });
+}
+
+/** The 기록 block's last daily note line: the date of the newest notes/daily file the gateway found, or that there is none yet. */
+export function lastDailyLine(lastDaily) {
+	return typeof lastDaily === "string" && lastDaily ? t("agents.lastDaily", { date: lastDaily }) : t("agents.lastDaily.none");
+}
+
+// The 도구 권한 section of an agent's editor (plan 294 item 9, C8/C10): the grants the gateway lists
+// (GET /api/agents/:id/tool-permissions), their state, the revoke / revoke-all / edit requests and the scope draft an
+// edit works on. The tool, operation and target words come from web/decisions.js through the `describe` parameter;
+// this module imports no other web module, so the agent-web mutation tree stays self-contained.
+const TOOL_STATES = ["allowed", "applying", "revoked", "suspended", "blocked"];
+const TOOL_PERMISSION_ERROR_KEYS = {
+	grant_conflict: "grant", policy_conflict: "policy", cursor_stale: "policy", cursor_invalid: "policy", grant_not_found: "gone", not_found: "unsupported",
+	page_nonce_invalid: "expired", agent_tool_client_required: "expired", forbidden: "forbidden", forbidden_origin: "forbidden", forbidden_host: "forbidden",
+	custom_header_required: "forbidden", agent_access_blocked: "blocked", operation_conflict: "operation", tool_request_invalid: "invalid", method_not_allowed: "invalid",
+};
+const STALE_POLICY_CODES = new Set(["policy_conflict", "cursor_stale", "cursor_invalid"]);
+const EXPIRED_CLIENT_CODES = new Set(["page_nonce_invalid", "agent_tool_client_required"]);
+const UNEDITABLE_SCOPE_KEYS = new Set(["kind", "selection", "targetHandle", "targetId", "targetLabel", "targetTitle", "account", "host"]);
+const IDENTITY_DESCRIBE = {
+	toolName: (toolKey) => (isObject(toolKey) && typeof toolKey.originalName === "string" ? toolKey.originalName : ""),
+	operationLabel: (_toolKey, operation) => (typeof operation === "string" ? operation : ""),
+	scopeText: () => "",
+};
+
+export function toolPermissionsPath(agentId) {
+	return `/api/agents/${encodeURIComponent(agentId)}/tool-permissions`;
+}
+
+export function toolPermissionsRequest(agentId, cursor = null) {
+	const path = toolPermissionsPath(agentId);
+	return { method: "GET", path: cursor ? `${path}?cursor=${encodeURIComponent(cursor)}` : path };
+}
+
+/** The design states (C8): a revoked grant stays revoked; blocked access hides every other state; applying means the sessions have not acknowledged the policy yet. */
+export function grantState(grant, policy) {
+	const state = isObject(grant) ? grant.state : null;
+	if (state === "revoked") return "revoked";
+	if (isObject(policy) && policy.accessState === "blocked") return "blocked";
+	if (state === "suspended") return "suspended";
+	if (isObject(policy) && typeof policy.appliedRevision === "number" && typeof policy.policyRevision === "number" && policy.appliedRevision < policy.policyRevision) return "applying";
+	return "allowed";
+}
+
+export function grantStateLabel(state) {
+	return t(`agents.tool.state.${TOOL_STATES.includes(state) ? state : "blocked"}`);
+}
+
+export function accessSummary(policy) {
+	if (!isObject(policy) || typeof policy.policyRevision !== "number") return "";
+	return t(policy.accessState === "blocked" ? "agents.tool.access.blocked" : "agents.tool.access.open", { revision: policy.policyRevision });
+}
+
+const stringList = (value) => (Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : null);
+
+export function toolGrantRows(page, describe = IDENTITY_DESCRIBE) {
+	if (!isObject(page) || !Array.isArray(page.items)) return [];
+	const policy = isObject(page.policy) ? page.policy : null;
+	const rows = [];
+	for (const grant of page.items) {
+		if (!isObject(grant) || typeof grant.id !== "string") continue;
+		const operations = stringList(grant.operations) ?? [];
+		const state = grantState(grant, policy);
+		rows.push({
+			id: grant.id,
+			tool: describe.toolName(grant.toolKey) || IDENTITY_DESCRIBE.toolName(grant.toolKey),
+			operation: operations.map((operation) => describe.operationLabel(grant.toolKey, operation) || operation).join(", "),
+			target: describe.scopeText(grant.scope),
+			state,
+			stateLabel: grantStateLabel(state),
+			revision: typeof grant.revision === "number" ? grant.revision : 0,
+			operations,
+			origin: typeof grant.originDecisionId === "string" ? grant.originDecisionId : "",
+		});
+	}
+	return rows;
+}
+
+export function revokeRequest(agentId, grant, operationId) {
+	return { method: "POST", path: `${toolPermissionsPath(agentId)}/${encodeURIComponent(grant.id)}/revoke`, body: { operationId, expectedRevision: grant.revision } };
+}
+
+export function revokeAllRequest(agentId, policy, operationId) {
+	return { method: "POST", path: `${toolPermissionsPath(agentId)}/revoke-all`, body: { operationId, expectedPolicyRevision: policy.policyRevision } };
+}
+
+function cloneScope(scope) {
+	const copy = {};
+	if (!isObject(scope)) return copy;
+	for (const [key, value] of Object.entries(scope)) copy[key] = Array.isArray(value) ? [...value] : value;
+	return copy;
+}
+
+/** POST .../tool-permissions/:grantId/edit (C3): the whole draft against the grant revision the editor started from. */
+export function editRequest(agentId, grant, draft, operationId) {
+	return {
+		method: "POST", path: `${toolPermissionsPath(agentId)}/${encodeURIComponent(grant.id)}/edit`,
+		body: { operationId, expectedRevision: grant.revision, operations: [...draft.operations], scope: cloneScope(draft.scope) },
+	};
+}
+
+/** A copy of the grant's operations and scope to edit, with the text of every editable list value; opaque handles stay as they are. */
+export function scopeDraft(grant) {
+	const scope = cloneScope(isObject(grant) ? grant.scope : null);
+	const text = {};
+	for (const [key, value] of Object.entries(scope)) {
+		if (UNEDITABLE_SCOPE_KEYS.has(key) || !stringList(value)) continue;
+		text[key] = value.join(", ");
+	}
+	return { operations: [...(stringList(isObject(grant) ? grant.operations : null) ?? [])], scope, text };
+}
+
+export function parseScopeText(text) {
+	if (typeof text !== "string") return [];
+	return [...new Set(text.split(/[\n,]/).map((entry) => entry.trim()).filter(Boolean))];
+}
+
+/**
+ * Narrowing (fewer operations, fewer list values, a new restriction key) applies at once; anything added, a dropped
+ * restriction key or a changed single value is a widening the inbox has to confirm (C8).
+ */
+export function classifyEdit(grant, draft) {
+	const before = scopeDraft(grant);
+	const operations = stringList(draft?.operations) ?? [];
+	const scope = isObject(draft?.scope) ? draft.scope : {};
+	const added = { operations: operations.filter((operation) => !before.operations.includes(operation)), scope: {} };
+	const removed = { operations: before.operations.filter((operation) => !operations.includes(operation)), scope: {} };
+	let widened = added.operations.length > 0;
+	for (const key of new Set([...Object.keys(before.scope), ...Object.keys(scope)])) {
+		if (!(key in scope)) {
+			widened = true;
+			continue;
+		}
+		if (!(key in before.scope)) continue;
+		const was = stringList(before.scope[key]);
+		const now = stringList(scope[key]);
+		if (was && now) {
+			const plus = now.filter((entry) => !was.includes(entry));
+			const minus = was.filter((entry) => !now.includes(entry));
+			if (plus.length > 0) {
+				added.scope[key] = plus;
+				widened = true;
+			}
+			if (minus.length > 0) removed.scope[key] = minus;
+			continue;
+		}
+		if (JSON.stringify(before.scope[key]) !== JSON.stringify(scope[key])) widened = true;
+	}
+	const narrowed = removed.operations.length > 0 || Object.keys(removed.scope).length > 0 || Object.keys(scope).some((key) => !(key in before.scope));
+	return { kind: widened ? "widen" : narrowed ? "narrow" : "same", added, removed };
+}
+
+export function editLine(kind) {
+	return t(`agents.tool.edit.${kind === "widen" || kind === "narrow" ? kind : "same"}`);
+}
+
+/** The list after a revoke answer: the grant is revoked at the answered (or next) revision and the policy revision moves on. */
+export function applyRevoke(page, grantId, result) {
+	const answer = isObject(result) ? result : {};
+	const items = page.items.map((grant) => {
+		if (grant.id !== grantId) return grant;
+		const revoked = isObject(answer.grant) && answer.grant.id === grantId ? answer.grant : { revision: grant.revision + 1 };
+		return { ...grant, ...revoked, state: "revoked" };
+	});
+	const policyRevision = typeof answer.policyRevision === "number" ? answer.policyRevision : page.policy.policyRevision;
+	return { ...page, items, policy: { ...page.policy, policyRevision } };
+}
+
+export function revokeLine(result) {
+	const running = isObject(result) && Array.isArray(result.running) ? result.running : [];
+	return t(running.length > 0 ? "agents.tool.revokedRunning" : "agents.tool.revoked");
+}
+
+export function interpretPermissionResponse(status, body) {
+	const error = isObject(body) && typeof body.error === "string" ? body.error : null;
+	if (status === 200) return { kind: "ok", body };
+	if (status === 202) return { kind: "confirm", decisionId: isObject(body) && typeof body.decisionId === "string" ? body.decisionId : null, body };
+	if (status === 409) return { kind: STALE_POLICY_CODES.has(error) ? "stale" : "conflict", error };
+	if (status === 404) return { kind: error === null || error === "not_found" ? "unsupported" : "gone", error };
+	if (status === 403 && EXPIRED_CLIENT_CODES.has(error)) return { kind: "expired", error };
+	if (status === 400 || status === 401 || status === 403 || status === 410) return { kind: "refused", error };
+	return { kind: "unavailable", error, status };
+}
+
+/** C10 agent.tool_permissions.updated: the open editor reloads when its agent's policy moved past the loaded page. */
+export function policyEventStale(page, event) {
+	if (!isObject(page) || !isObject(page.policy) || !isObject(event) || event.agentId !== page.policy.agentId || typeof event.policyRevision !== "number") return false;
+	const policy = page.policy;
+	return event.policyRevision !== policy.policyRevision ||
+		(typeof event.authorityEpoch === "number" && event.authorityEpoch !== policy.authorityEpoch) ||
+		(typeof event.accessState === "string" && event.accessState !== policy.accessState);
+}
+
+export function toolPermissionErrorLine(error, status = 0) {
+	if (error === null && status === 0) return t("agents.tool.error.network");
+	const key = typeof error === "string" ? TOOL_PERMISSION_ERROR_KEYS[error] : undefined;
+	return t(`agents.tool.error.${key ?? "generic"}`);
+}