@monster-orange/den 0.4.11 → 0.4.13

package/src/ui/cli/agents-command.ts

@@ -410,13 +410,23 @@ async function listPersonas(
     return 0;
   }
   for (const l of columns([
-    ["PERSONA", "STANDING", "RUNTIME", "MODEL", "ROLE"],
+    [
+      "PERSONA",
+      "SOURCE",
+      "STANDING",
+      "RUNTIME",
+      "MODEL",
+      "ROLE",
+      "DESCRIPTION",
+    ],
     ...all.map((x) => [
       x.id,
+      x.origin,
       x.standing ? "yes" : "-",
       x.runtime ?? DEFAULT_RUNTIME_ID,
       x.model ?? "-",
-      x.role,
+      x.role ?? "-",
+      x.description,
     ]),
   ]))
     d.out(l);

package/src/ui/cli/env-probe.ts

@@ -112,7 +112,10 @@ function probeInput(d: ProbeDeps, dir: string): LaunchInput {
   return {
     persona: {
       id: PROBE_ID,
-      role: "",
+      description: "",
+      category: "engineering",
+      allowedCommands: [],
+      origin: "builtin",
       prompt: "",
       standing: false,
       tools: [],

package/src/ui/mcp/tools.ts

@@ -740,7 +740,7 @@ const agentResumeTool: DenTool = {
   name: "agent_resume",
   title: "Resume an agent",
   description:
-    "Resume a stopped or interrupted agent in the same conversation, persona, workspace and folder. Never starts a new conversation: an agent whose runtime can't resume is refused. Never the caller itself.",
+    "Resume a stopped or interrupted agent in the same conversation, persona, workspace and folder. Never starts a new conversation: an agent whose runtime can't resume is refused. Never the caller itself. Answers with agent: its id, persona, runtime, workspace, cwd, session (the session handle, <dist>-<ws>:<id>), sessionId, displayName (a person's name for it) and sessionTitle (the name its session shows: Den's rename or the runtime's, the later), when set.",
   action: true,
   shape: {
     agent: z.string().describe("The agent's id"),

package/src/ui/server/agent-paths.ts

@@ -0,0 +1,52 @@
+/**
+ * Which file paths an agent printed are links (AG-4b): GET
+ * /api/workspaces/<ws>/agents/<id>/paths?p=<path>&p=<path>… answers
+ * { paths: { <path as given>: <absolute path> | null } }.
+ *
+ * A path is resolved against the agent's cwd (an absolute one stays), and
+ * is a link only when it exists and its real path (symlinks followed) is
+ * inside the agent's workspace: the workspace's directory, or the agent's
+ * own cwd (a worktree of it). Anything else is null, so a path outside
+ * the workspace is never a link and the page never learns whether it
+ * exists. Only stat is used: nothing is read, nothing is opened.
+ */
+import * as fs from "fs";
+import * as path from "path";
+
+/** The most paths one ask takes (a screen's worth). */
+export const MAX_PATHS = 64;
+/** The longest path taken. */
+const MAX_PATH_LEN = 1024;
+
+function realOrNull(p: string): string | null {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+const inside = (p: string, root: string) =>
+  p === root || p.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
+
+/** Each path's absolute path when it is a link, else null. */
+export function agentPathLinks(
+  given: readonly string[],
+  cwd: string,
+  roots: readonly string[],
+): Record<string, string | null> {
+  const real = roots
+    .map((r) => realOrNull(r))
+    .filter((r): r is string => r !== null);
+  const base = realOrNull(cwd) ?? path.resolve(cwd);
+  const out: Record<string, string | null> = {};
+  for (const p of given) {
+    if (Object.hasOwn(out, p)) continue;
+    out[p] = null;
+    if (!p || p.length > MAX_PATH_LEN || p.includes("\0")) continue;
+    const abs = path.resolve(base, p);
+    const r = realOrNull(abs);
+    if (r && real.some((root) => inside(r, root))) out[p] = r;
+  }
+  return out;
+}

package/src/ui/server/agent-routes.ts

@@ -12,8 +12,26 @@
  *                                                 runs its version command and
  *                                                 refuses a path that isn't
  *                                                 that runtime (AG-0.5)
+ *   GET  /api/personas/<id>                       one persona with its
+ *                                                 instructions (Details)
+ *   POST /api/personas                            New persona (AG-10.7): a
+ *                                                 local one; a person only
+ *   POST /api/personas/<id>                       Edit: a local one only
+ *                                                 (409 read_only otherwise)
+ *   DELETE /api/personas/<id>                     Delete: a local one only
  *   GET  /api/workspaces/<ws>/agents              the workspace's agents
- *   POST /api/workspaces/<ws>/agents              start { persona, runtime?, model?, id? }
+ *   POST /api/workspaces/<ws>/agents              start { persona, runtime?,
+ *                                                 model?, version?,
+ *                                                 permission?, allow?,
+ *                                                 instruction?, id? }
+ *                                                 (AG-10.1): each checked
+ *                                                 against the catalog; the
+ *                                                 instruction is typed into
+ *                                                 the session once it is
+ *                                                 ready, never an argument
+ *   POST /api/workspaces/<ws>/sessions            a plain session: the login
+ *                                                 shell in the workspace's
+ *                                                 folder (AG-10.1)
  *   POST /api/workspaces/<ws>/agents/<id>/stop
  *   POST /api/workspaces/<ws>/agents/<id>/resume  the same conversation (AG-14)
  *   POST /api/workspaces/<ws>/agents/<id>/fresh   a new conversation, same
@@ -23,6 +41,14 @@
  *                                                 first prompt is its
  *                                                 handoff.md; a resume of
  *                                                 one is refused (409 rotated)
+ *   POST /api/workspaces/<ws>/agents/<id>/name    { name: string | null }: the
+ *                                                 name its tab and the lists
+ *                                                 show (AG-4b); the id never
+ *                                                 changes; null or "" clears
+ *   GET  /api/workspaces/<ws>/agents/<id>/paths?p=…  which printed paths are
+ *                                                 links (AG-4b): inside its
+ *                                                 workspace and there (stat
+ *                                                 only; agent-paths.ts)
  *   POST /api/workspaces/<ws>/agents/<id>/remove  forget a stopped one (Undo:
  *                                                 /api/agents/restore)
  *   POST /api/agents/clear-stopped                { workspaces: [...] }: forget
@@ -67,13 +93,22 @@ import { HostError } from "../../shared/sessions/client.js";
 import {
   AgentError,
   agentRecord,
+  checkInstruction,
+  createPersona,
+  deletePersona,
   listAgents,
   listPersonas,
+  personaDetail,
+  registries,
+  sendFirstInstruction,
+  startPlainSession,
+  updatePersona,
   listRuntimes,
   markInterrupted,
   NOT_IN_WORKSPACE,
   pruneStopped,
   removeAgent,
+  renameAgent,
   removeStopped,
   restoreAgents,
   resumeInterrupted,
@@ -88,7 +123,9 @@ import {
   type AgentsResolved,
   type Started,
 } from "../cli/agent-ops.js";
+import { agentSessionName } from "../../shared/agents/session-name.js";
 import { recordAction } from "./audit.js";
+import { agentPathLinks, MAX_PATHS } from "./agent-paths.js";
 import {
   agentPrincipalOf,
   auditActorOf,
@@ -101,14 +138,18 @@ import type { Actor } from "../../shared/agent-actor.js";
 export interface AgentRouteDeps {
   /** The operations' deps (tests: an in-process host, a temp state dir). */
   agents?: AgentsDeps;
+  /** When a first instruction counts its session ready (tests: shorter). */
+  instruction?: { quietMs?: number; maxMs?: number };
 }
 
 const AGENTS_PATH =
-  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove))?$/;
+  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume|fresh|relaunch|remove|name|paths))?$/;
 
 const RUNTIME_PATH = /^\/api\/agents\/runtimes\/([^/]+)\/path$/;
-/** A start's body is a few short names. */
-const MAX_BODY = 4096;
+const PERSONA_PATH = /^\/api\/personas\/([^/]+)$/;
+const PLAIN_PATH = /^\/api\/workspaces\/([^/]+)\/sessions$/;
+/** A start's body: a few names, commands and a first instruction. */
+const MAX_BODY = 32 * 1024;
 /** A list of names (a page's workspaces, an Undo's agents). */
 const MANY_BODY = 64 * 1024;
 const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
@@ -163,10 +204,20 @@ function sendError(res: http.ServerResponse, e: unknown, ws?: string): void {
   throw e;
 }
 
+function sessionTitleOf(
+  rec: Started["rec"],
+  d: AgentsResolved,
+): { sessionTitle?: string } {
+  const n = agentSessionName(rec, d.stateDir());
+  return n ? { sessionTitle: n } : {};
+}
+
 /** A started or resumed agent's answer: its record, or its early exit. */
 function sendStarted(
   res: http.ServerResponse,
   s: Started & { fresh?: boolean },
+  d: AgentsResolved,
+  extra: Record<string, unknown> = {},
 ): void {
   if (s.early) {
     const code =
@@ -197,17 +248,47 @@ function sendStarted(
       // The host's id: the Agents tab opens its pane by it (?open=<id>).
       sessionId: s.info.ref.id,
       startedAt: s.rec.startedAt,
+      ...(s.rec.model ? { model: s.rec.model } : {}),
+      ...(s.rec.version ? { version: s.rec.version } : {}),
+      ...(s.rec.permission ? { permission: s.rec.permission } : {}),
+      ...(s.rec.overrides?.length ? { overrides: s.rec.overrides } : {}),
+      ...(s.rec.displayName ? { displayName: s.rec.displayName } : {}),
+      // AG-4b: the name its session shows (Den's rename or the runtime's),
+      // as the lists show it (MCP agent_resume answers with this). Its
+      // handle is `session`.
+      ...sessionTitleOf(s.rec, d),
     },
     // A resume with nothing to continue yet started fresh (same id).
     ...(s.fresh ? { fresh: true } : {}),
     ...(s.warnings.length ? { warnings: s.warnings } : {}),
+    ...extra,
   });
 }
 
-/** What a POST's body names: a few optional strings. */
-async function startBody(
-  req: http.IncomingMessage,
-): Promise<Record<string, string | undefined>> {
+/** What a start's body names: optional strings, a command list, an instruction. */
+interface StartBody {
+  persona?: string;
+  runtime?: string;
+  model?: string;
+  id?: string;
+  version?: string;
+  permission?: string;
+  allow?: unknown;
+  instruction?: unknown;
+}
+
+const START_KEYS = [
+  "persona",
+  "runtime",
+  "model",
+  "id",
+  "version",
+  "permission",
+  "allow",
+  "instruction",
+];
+
+async function startBody(req: http.IncomingMessage): Promise<StartBody> {
   const raw = await readBody(req).catch(() => "");
   if (raw.length > MAX_BODY)
     throw new AgentError("request too large", { status: 413, usage: true });
@@ -219,15 +300,38 @@ async function startBody(
   }
   if (!v || typeof v !== "object" || Array.isArray(v))
     throw new AgentError("the body must be a JSON object", { usage: true });
-  const out: Record<string, string | undefined> = {};
-  for (const k of ["persona", "runtime", "model", "id"]) {
-    const x = (v as Record<string, unknown>)[k];
+  const o = v as Record<string, unknown>;
+  for (const k of Object.keys(o))
+    if (!START_KEYS.includes(k))
+      throw new AgentError(
+        `${k}: unknown field (a start takes ${START_KEYS.join(", ")})`,
+        { usage: true },
+      );
+  const out: Record<string, unknown> = {};
+  for (const k of [
+    "persona",
+    "runtime",
+    "model",
+    "id",
+    "version",
+    "permission",
+  ]) {
+    const x = o[k];
     if (x === undefined || x === null || x === "") continue;
     if (typeof x !== "string")
       throw new AgentError(`${k} must be a string`, { usage: true });
+    if (x.length > 128 || /[^\x21-\x7e]/.test(x))
+      throw new AgentError(
+        `${k} must be a short name (no spaces or control characters)`,
+        {
+          usage: true,
+        },
+      );
     out[k] = x;
   }
-  return out;
+  if (o.allow !== undefined && o.allow !== null) out.allow = o.allow;
+  if (o.instruction !== undefined) out.instruction = o.instruction;
+  return out as StartBody;
 }
 
 /**
@@ -243,6 +347,8 @@ export async function handleAgentRoutes(
 ): Promise<boolean> {
   const m = AGENTS_PATH.exec(pathname);
   const rp = RUNTIME_PATH.exec(pathname);
+  const pp = PERSONA_PATH.exec(pathname);
+  const plain = PLAIN_PATH.exec(pathname);
   // AG-14's routes over many agents at once.
   const many =
     pathname === "/api/agents/clear-stopped" ||
@@ -253,22 +359,34 @@ export async function handleAgentRoutes(
     pathname !== "/api/agents/runtimes" &&
     !m &&
     !rp &&
+    !pp &&
+    !plain &&
     !many
   )
     return false;
   const method = req.method ?? "GET";
   const d = webDeps(deps.agents);
 
+  if (pp) return personaRoute(req, res, safeDecode(pp[1]), d);
+  if (plain) return plainSession(req, res, safeDecode(plain[1]), d);
+  if (pathname === "/api/personas" && method === "POST")
+    return personaRoute(req, res, null, d);
+
   if (rp) return runtimePath(req, res, safeDecode(rp[1]), d);
   if (many) return manyAgents(req, res, pathname, d);
   if (!m) {
     if (method !== "GET" && method !== "HEAD")
-      return methodNotAllowed(res, "GET");
+      return methodNotAllowed(
+        res,
+        pathname === "/api/personas" ? "GET, POST" : "GET",
+      );
     try {
       const ws = queryWorkspace(req, d);
       const runtimes = await listRuntimes(d, ws);
       sendJson(res, {
-        ...(pathname === "/api/personas" ? { personas: listPersonas(d) } : {}),
+        ...(pathname === "/api/personas"
+          ? { personas: listPersonas(d), ...registries(d) }
+          : {}),
         runtimes,
         ...(ws ? { workspace: ws } : {}),
         // AG-0.2: the file a person edits to set a runtime's path.
@@ -294,6 +412,8 @@ export async function handleAgentRoutes(
     | "fresh"
     | "relaunch"
     | "remove"
+    | "name"
+    | "paths"
     | undefined;
 
   if (!action && method === "GET") {
@@ -313,6 +433,38 @@ export async function handleAgentRoutes(
     }
     return true;
   }
+  // AG-4b: which paths an agent printed are links (read-only: stat only).
+  if (action === "paths") {
+    if (method !== "GET" && method !== "HEAD")
+      return methodNotAllowed(res, "GET");
+    try {
+      const rec = agentRecord(d, id!, ws);
+      const given = new URL(
+        req.url ?? "/",
+        "http://localhost",
+      ).searchParams.getAll("p");
+      if (given.length > MAX_PATHS)
+        throw new AgentError(`at most ${MAX_PATHS} paths at once`, {
+          usage: true,
+        });
+      let wsDir: string | null = null;
+      try {
+        wsDir = d.workspaceDir(ws);
+      } catch {
+        wsDir = null;
+      }
+      sendJson(res, {
+        paths: agentPathLinks(
+          given,
+          rec.cwd,
+          [wsDir, rec.cwd].filter((x): x is string => !!x),
+        ),
+      });
+    } catch (e) {
+      sendError(res, e, ws);
+    }
+    return true;
+  }
   if (method !== "POST")
     return methodNotAllowed(res, action ? "POST" : "GET, POST");
 
@@ -345,16 +497,54 @@ export async function handleAgentRoutes(
       if (!body.persona)
         throw new AgentError("persona is required", { usage: true });
       what = `start ${body.id ?? body.persona} in ${ws}`;
+      const instruction = checkInstruction(body.instruction);
       const s = await startAgent(d, {
         workspace: ws,
         persona: body.persona,
         runtime: body.runtime,
         model: body.model,
         id: body.id,
+        ...(body.version !== undefined ? { version: body.version } : {}),
+        ...(body.permission !== undefined
+          ? { permission: body.permission }
+          : {}),
+        ...(body.allow !== undefined ? { allow: body.allow } : {}),
+        strict: true,
       });
-      what = `start ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
+      const ov = s.rec.overrides?.length
+        ? `; overrides ${s.rec.overrides.join(", ")}`
+        : "";
+      what = `start ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}${ov}) in ${ws}`;
       audit(what, s.early ? "exited at once" : undefined);
-      sendStarted(res, s);
+      sendStarted(res, s, d, instruction ? { instruction: "pending" } : {});
+      // AG-10.1: its first message, once it is ready: typed into its
+      // session (the host's write path), never an argument. Its text is
+      // never logged; its length is.
+      if (instruction && !s.early) {
+        const id = s.rec.id;
+        void sendFirstInstruction(
+          d,
+          s.info.ref.id,
+          s.rec.runtime,
+          instruction,
+          deps.instruction ?? {},
+        ).then((sent) =>
+          recordAction(
+            actor,
+            {
+              verb: "agents",
+              detail: `first instruction to ${id} in ${ws} (${instruction.length} characters)`,
+              ...(sent
+                ? {}
+                : {
+                    outcome: "refused" as const,
+                    reason: "its session ended or no host",
+                  }),
+            },
+            principalOf(req),
+          ),
+        );
+      }
     } else if (verb === "stop") {
       // The answer comes once the session has ended (200, stopped: true),
       // or, still running after the wait, 202 with stillStopping: true.
@@ -375,12 +565,25 @@ export async function handleAgentRoutes(
       const s = await startFresh(d, id!, ws);
       what = `start ${s.rec.id} fresh (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
       audit(what, s.early ? "exited at once" : undefined);
-      sendStarted(res, s);
+      sendStarted(res, s, d);
     } else if (verb === "relaunch") {
       const s = await relaunchAgent(d, id!, ws);
       what = `relaunch ${s.rec.id} from its handoff (${s.why}) in ${ws}`;
       audit(what, s.early ? "exited at once" : undefined);
-      sendStarted(res, s);
+      sendStarted(res, s, d);
+    } else if (verb === "name") {
+      const body = await jsonBody(req);
+      if (!("name" in body))
+        throw new AgentError("name is required (null clears it)", {
+          usage: true,
+        });
+      const rec = renameAgent(d, id!, ws, body.name);
+      audit(what);
+      sendJson(res, {
+        ok: true,
+        agent: rec.id,
+        ...(rec.displayName ? { displayName: rec.displayName } : {}),
+      });
     } else if (verb === "remove") {
       const removed = await removeAgent(d, id!, ws);
       audit(what);
@@ -388,7 +591,7 @@ export async function handleAgentRoutes(
     } else {
       const s = await resumeAgent(d, id!, ws);
       audit(what);
-      sendStarted(res, s);
+      sendStarted(res, s, d);
     }
   } catch (e) {
     audit(what, e instanceof Error ? e.message : String(e));
@@ -515,6 +718,113 @@ function queryWorkspace(
   return ws;
 }
 
+/**
+ * The persona routes (AG-10.6, 10.7): GET one (anyone who may read);
+ * POST (new: `id` null; edit: a local one), DELETE (a local one): a
+ * person only. An agent's token can't make or change a persona (its
+ * permissions are the person's to set). Every change is audited, refused
+ * or done; never the instructions themselves.
+ */
+async function personaRoute(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  id: string | null,
+  d: AgentsResolved,
+): Promise<true> {
+  const method = req.method ?? "GET";
+  if (id !== null && (method === "GET" || method === "HEAD")) {
+    try {
+      sendJson(res, { persona: personaDetail(d, id) });
+    } catch (e) {
+      sendError(res, e);
+    }
+    return true;
+  }
+  if (method !== "POST" && !(method === "DELETE" && id !== null))
+    return methodNotAllowed(
+      res,
+      id === null ? "GET, POST" : "GET, POST, DELETE",
+    );
+  const actor = auditActorOf(req);
+  const verb = id === null ? "create" : method === "DELETE" ? "delete" : "edit";
+  let what = `persona ${verb}${id ? ` ${id}` : ""}`;
+  const audit = (reason?: string) =>
+    recordAction(
+      actor,
+      {
+        verb: "agents",
+        detail: what,
+        ...(reason ? { outcome: "refused" as const, reason } : {}),
+      },
+      principalOf(req),
+    );
+  try {
+    if (actor && !actor.unverified)
+      throw new AgentError(
+        "an agent can't create, change or delete personas: a person sets what agents may do",
+        { status: 403 },
+      );
+    if (verb === "delete") {
+      deletePersona(d, id!);
+      audit();
+      sendJson(res, { ok: true, deleted: id });
+      return true;
+    }
+    const body = await jsonBody(req);
+    const p =
+      verb === "create" ? createPersona(d, body) : updatePersona(d, id!, body);
+    what = `persona ${verb} ${p.id}`;
+    audit();
+    sendJson(res, { ok: true, persona: p });
+  } catch (e) {
+    audit(e instanceof Error ? e.message : String(e));
+    sendError(res, e);
+  }
+  return true;
+}
+
+/**
+ * POST /api/workspaces/<ws>/sessions (AG-10.1 Plain session): a person's
+ * login shell in the workspace's folder. A person only; audited.
+ */
+async function plainSession(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  ws: string,
+  d: AgentsResolved,
+): Promise<true> {
+  if (req.method !== "POST") return methodNotAllowed(res, "POST");
+  const actor = auditActorOf(req);
+  let what = `plain session in ${ws}`;
+  const audit = (reason?: string) =>
+    recordAction(
+      actor,
+      {
+        verb: "sessions",
+        detail: what,
+        ...(reason ? { outcome: "refused" as const, reason } : {}),
+      },
+      principalOf(req),
+    );
+  try {
+    if (actor && !actor.unverified)
+      throw new AgentError("an agent can't start a session from the page", {
+        status: 403,
+      });
+    const { info } = await startPlainSession(d, ws);
+    what = `plain session ${info.name} in ${ws}`;
+    audit();
+    sendJson(res, {
+      ok: true,
+      session: { id: info.ref.id, name: info.name, workspace: ws },
+    });
+  } catch (e) {
+    audit(e instanceof Error ? e.message : String(e));
+    sendError(res, e, ws);
+  }
+  return true;
+}
+
 /**
  * POST /api/agents/runtimes/<id>/path: a person only, never an agent (it
  * runs the path given). Audited, refused or done; never the path's output.

package/src/ui/server/agents-layout-pref.ts

@@ -0,0 +1,43 @@
+/**
+ * The Agents tab's layout (AG-4b), a person's view preference: Focus (one
+ * pane, the default), Tabs or Tile. Stored in the user config as
+ * `agents.layout` and served by /api/settings as `agents_layout`, like the
+ * other view prefs (graph-prefs.ts, shell-prefs.ts). It changes no session
+ * and no agent: only how the page lays out their terminals.
+ */
+import type { UserConfig } from "../../shared/den-config.js";
+
+export const AGENTS_LAYOUTS = ["focus", "tabs", "tile"] as const;
+export type AgentsLayout = (typeof AGENTS_LAYOUTS)[number];
+export const AGENTS_LAYOUT_DEFAULT: AgentsLayout = "focus";
+
+const isLayout = (v: unknown): v is AgentsLayout =>
+  typeof v === "string" && (AGENTS_LAYOUTS as readonly string[]).includes(v);
+
+/** The stored layout, or the default when unset or hand-broken. */
+export function agentsLayout(user: UserConfig): AgentsLayout {
+  const v = (user.agents as { layout?: unknown } | undefined)?.layout;
+  return isLayout(v) ? v : AGENTS_LAYOUT_DEFAULT;
+}
+
+/**
+ * Apply a POSTed `agents_layout` to `user` (in place): a layout sets
+ * agents.layout, null clears it (and an agents block left empty goes).
+ * Anything else: the error to answer with.
+ */
+export function patchAgentsLayout(
+  user: UserConfig,
+  v: unknown,
+): { ok: true } | { ok: false; error: string } {
+  if (v !== null && !isLayout(v))
+    return {
+      ok: false,
+      error: `agents_layout must be one of ${AGENTS_LAYOUTS.map((l) => `"${l}"`).join(", ")}, or null`,
+    };
+  const agents = { ...(user.agents ?? {}) } as Record<string, unknown>;
+  if (v === null) delete agents.layout;
+  else agents.layout = v;
+  if (Object.keys(agents).length) user.agents = agents as UserConfig["agents"];
+  else delete user.agents;
+  return { ok: true };
+}