@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/agent/tools/registry.js

@@ -2,8 +2,18 @@ import listProjects from "./handlers/list-projects.js";
 import listAgents from "./handlers/list-agents.js";
 import listVaultAgents from "./handlers/list-vault-agents.js";
 import importAgent from "./handlers/import-agent.js";
+import createAgent from "./handlers/create-agent.js";
+import setAgentPrompt from "./handlers/set-agent-prompt.js";
+import writeAgentMemory from "./handlers/write-agent-memory.js";
+import configureAgent from "./handlers/configure-agent.js";
+import removeAgent from "./handlers/remove-agent.js";
+import addMcp from "./handlers/add-mcp.js";
+import completeTask from "./handlers/complete-task.js";
+import commentTask from "./handlers/comment-task.js";
+import markCommitment from "./handlers/mark-commitment.js";
 import addProject from "./handlers/add-project.js";
 import listMcps from "./handlers/list-mcps.js";
+import listMcpTools from "./handlers/list-mcp-tools.js";
 import readAgentMemory from "./handlers/read-agent-memory.js";
 import remember from "./handlers/remember.js";
 import readSelfMemory from "./handlers/read-self-memory.js";
@@ -25,12 +35,17 @@ import setPermissionMode from "./handlers/set-permission-mode.js";
 import searchFiles from "./handlers/search-files.js";
 import listSkills from "./handlers/list-skills.js";
 import loadSkill from "./handlers/load-skill.js";
+import readSkill from "./handlers/read-skill.js";
+import attachMedia from "./handlers/attach-media.js";
+import viewMedia from "./handlers/view-media.js";
 import transcribeAudio from "./handlers/transcribe-audio.js";
 import askQuestions from "./handlers/ask-questions.js";
 import createTask from "./handlers/create-task.js";
 import recordCommitment from "./handlers/record-commitment.js";
 import listCommitments from "./handlers/list-commitments.js";
 import rememberRoutine from "./handlers/remember-routine.js";
+import listRoutines from "./handlers/list-routines.js";
+import runRoutine from "./handlers/run-routine.js";
 import listTasks from "./handlers/list-tasks.js";
 import discoverTools from "./handlers/discover-tools.js";
 import gitStatus from "./handlers/git-status.js";
@@ -43,6 +58,10 @@ import asanaCreateTask from "./handlers/asana-create-task.js";
 import asanaUpdateTask from "./handlers/asana-update-task.js";
 import githubListRepos from "./handlers/github-list-repos.js";
 import githubCreateIssue from "./handlers/github-create-issue.js";
+import calendarListEvents from "./handlers/calendar-list-events.js";
+import calendarFindSlot from "./handlers/calendar-find-slot.js";
+import calendarCreateEvent from "./handlers/calendar-create-event.js";
+import calendarUpdateEvent from "./handlers/calendar-update-event.js";
 import obsidianSearchNotes from "./handlers/obsidian-search-notes.js";
 import obsidianReadNote from "./handlers/obsidian-read-note.js";
 import obsidianWriteNote from "./handlers/obsidian-write-note.js";
@@ -57,8 +76,17 @@ const NATIVE_TOOLS = [
   listAgents,
   listVaultAgents,
   importAgent,
+  createAgent,
+  setAgentPrompt,
+  writeAgentMemory,
+  configureAgent,
+  removeAgent,
+  addMcp,
+  completeTask,
+  markCommitment,
   addProject,
   listMcps,
+  listMcpTools,
   readAgentMemory,
   remember,
   readSelfMemory,
@@ -80,13 +108,19 @@ const NATIVE_TOOLS = [
   searchFiles,
   listSkills,
   loadSkill,
+  readSkill,
+  attachMedia,
+  viewMedia,
   transcribeAudio,
   askQuestions,
   createTask,
+  commentTask,
   listTasks,
   recordCommitment,
   listCommitments,
   rememberRoutine,
+  listRoutines,
+  runRoutine,
   discoverTools,
   gitStatus,
   gitDiff,
@@ -105,6 +139,10 @@ const NATIVE_TOOLS = [
   obsidianReadNote,
   obsidianWriteNote,
   obsidianListNotes,
+  calendarListEvents,
+  calendarFindSlot,
+  calendarCreateEvent,
+  calendarUpdateEvent,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env
@@ -141,6 +179,10 @@ export const BASE_TOOL_NAMES = new Set([
   TOOLS.LIST_MCPS,
   TOOLS.LIST_SKILLS,
   TOOLS.LOAD_SKILL,
+  // A skill shown "loaded on demand" is useless without the tool that pages it,
+  // so read_skill is hot everywhere load_skill is (project agents on chat
+  // channels rely on it to reach a lazy skill's sections).
+  TOOLS.READ_SKILL,
   // Memory + identity.
   TOOLS.READ_AGENT_MEMORY,
   TOOLS.READ_SELF_MEMORY,
@@ -161,11 +203,28 @@ export const BASE_TOOL_NAMES = new Set([
   // Tasks (very common ask via chat).
   TOOLS.CREATE_TASK,
   TOOLS.LIST_TASKS,
+  // The write-back half. It was left out and the asymmetry bit: on Telegram the
+  // model could open a task and list it but not close one, so — seeing the name
+  // in the lazy-tools block and no schema — it invented the call. It passed
+  // `id`, which is what list_tasks hands back, against a schema that says
+  // `task`, and spent three iterations on "task required" before giving up with
+  // the task still open. A pair where one half is hot and the other is cold is
+  // a pair the model will guess its way across.
+  TOOLS.COMPLETE_TASK,
+  // Same argument as the pair above, one step further: an agent that just did
+  // the work is the one with something to say about it, and a note it has to
+  // discover first is a note it will not write. Cheap schema, and it keeps the
+  // task verbs a single hot group instead of three hot and one cold.
+  TOOLS.COMMENT_TASK,
   // Commitments. In the base set on purpose: a promise is caught in passing
   // ("le dije a Ana que el viernes"), and a tool the model has to discover
   // first is a tool it will not reach for mid-sentence.
   TOOLS.RECORD_COMMITMENT,
   TOOLS.LIST_COMMITMENTS,
+  // Same pairing, same reason: a promise you can record but never resolve rots
+  // in the watcher's signal list forever (secretary-watch has been reporting
+  // one dead commitment from July 2025 on every run since August).
+  TOOLS.MARK_COMMITMENT,
   // Files + basic shell — frequent enough on chat to keep hot.
   TOOLS.READ_FILE,
   TOOLS.WRITE_FILE,
@@ -204,9 +263,21 @@ const NATIVE_CATEGORY = {
   [TOOLS.LIST_AGENTS]:         "inventory",
   [TOOLS.LIST_VAULT_AGENTS]:   "inventory",
   [TOOLS.LIST_MCPS]:           "inventory",
+  [TOOLS.LIST_MCP_TOOLS]:      "mcp",
   [TOOLS.LIST_SKILLS]:         "inventory",
   [TOOLS.LOAD_SKILL]:          "skills",
+  [TOOLS.READ_SKILL]:          "skills",
+  [TOOLS.ATTACH_MEDIA]:        "skills",
+  [TOOLS.VIEW_MEDIA]:          "skills",
   [TOOLS.IMPORT_AGENT]:        "agents",
+  [TOOLS.CREATE_AGENT]:        "agents",
+  [TOOLS.SET_AGENT_PROMPT]:    "agents",
+  [TOOLS.WRITE_AGENT_MEMORY]:  "agents",
+  [TOOLS.CONFIGURE_AGENT]:     "agents",
+  [TOOLS.REMOVE_AGENT]:        "agents",
+  [TOOLS.ADD_MCP]:             "mcp",
+  [TOOLS.COMPLETE_TASK]:       "tasks",
+  [TOOLS.MARK_COMMITMENT]:     "tasks",
   [TOOLS.ADD_PROJECT]:         "projects",
   [TOOLS.CALL_AGENT]:          "agents",
   [TOOLS.RUN_SUBAGENT]:        "agents",
@@ -223,6 +294,9 @@ const NATIVE_CATEGORY = {
   [TOOLS.ASK_QUESTIONS]:       "conversation",
   [TOOLS.CREATE_TASK]:         "tasks",
   [TOOLS.LIST_TASKS]:          "tasks",
+  [TOOLS.COMMENT_TASK]:        "tasks",
+  [TOOLS.LIST_ROUTINES]:       "routines",
+  [TOOLS.RUN_ROUTINE]:         "routines",
   [TOOLS.TRANSCRIBE_AUDIO]:    "voice",
   [TOOLS.READ_FILE]:           "files",
   [TOOLS.WRITE_FILE]:          "files",
@@ -426,3 +500,8 @@ export function makeToolHandlers(ctx) {
 export function listBridgedToolNames() {
   return BRIDGED_TOOLS.map(t => t.name);
 }
+
+/** Every name the loop can actually call this process (native + bridged). */
+export function listCallableToolNames() {
+  return ALL_TOOLS.map((t) => t.name);
+}

package/src/core/agent/tools/tool-call-parser.js

@@ -64,13 +64,28 @@ export function extractPseudoToolCalls(text) {
   // run-agent loop then treats them identically.
   const llamaCalls = extractLlamaDottedFunctionCalls(text);
 
-  // `[tool call: NAME] {…json…}` — APX's own internal transcription of a tool
-  // call, which used to be written into Gemini history when a turn had no
-  // thought signature to replay. Models copied the format out of their own
-  // history and started writing calls instead of making them, and the line
-  // was delivered to the user verbatim. The history no longer contains it,
-  // but a model that already learned the shape (or any model that invents it)
-  // must have the call EXECUTED rather than printed.
+  // DeepSeek (and some OpenAI-compatible gateways) dump native tool markup
+  // as prose instead of filling `tool_calls`. The wire shape looks like:
+  //
+  //   <||DSML||tool_calls>
+  //   <||DSML||invoke name="read_file">
+  //   <||DSML||parameter name="path" string="true">notes.md</||DSML||parameter>
+  //   </||DSML||invoke>
+  //   </||DSML||tool_calls>
+  //
+  // Without this pass the loop treats the blob as the final answer, the
+  // files never get read, and the operator sees XML in the routine preview.
+  const dsmlCalls = extractDsmlToolCalls(text);
+
+  // `[tool call: NAME] {…json…}` and `[tool NAME] {…json…}` — APX's own
+  // internal transcriptions of a tool call. The first used to be written into
+  // Gemini history when a turn had no thought signature to replay; the second
+  // is how the message store rendered tool records between 2026-08-19 and
+  // 2026-08-26. Models copied the format out of their own history and started
+  // writing calls instead of making them, and the line was delivered to the
+  // user verbatim. Neither shape is in the history any more, but a model that
+  // already learned it (or any model that invents it) must have the call
+  // EXECUTED rather than printed.
   const bracketCalls = extractBracketToolCalls(text);
 
   // Second pass: balanced `{name, arguments}` JSON anywhere in the text.
@@ -99,6 +114,7 @@ export function extractPseudoToolCalls(text) {
       // captured — otherwise we'd double-fire the tool.
       const insideLlamaWrap =
         llamaCalls.some((lc) => lc._rawStart <= i && balanced.end <= lc._rawEnd) ||
+        dsmlCalls.some((dc) => dc._rawStart <= i && balanced.end <= dc._rawEnd) ||
         bracketCalls.some((bc) => bc._rawStart <= i && balanced.end <= bc._rawEnd);
       if (insideLlamaWrap) {
         i = balanced.end - 1;
@@ -117,17 +133,76 @@ export function extractPseudoToolCalls(text) {
   // Strip internal markers used to dedupe against JSON pass.
   return [
     ...llamaCalls.map(({ _rawStart, _rawEnd, ...rest }) => rest),
+    ...dsmlCalls.map(({ _rawStart, _rawEnd, ...rest }) => rest),
     ...bracketCalls.map(({ _rawStart, _rawEnd, ...rest }) => rest),
     ...jsonCalls,
   ];
 }
 
-// Parse `[tool call: NAME] {…}` — see the note in extractPseudoToolCalls.
-// `_raw` spans the bracket AND its argument object so the whole line is
-// removed from the visible text, not just the JSON half.
+// DeepSeek DSML markup. Tags use one or two pipes (`|DSML|` / `||DSML||`).
+// Each invoke becomes one pseudo-tool-call; parameter bodies stay strings
+// unless they parse as JSON (so `{"a":1}` still arrives as an object).
+export function extractDsmlToolCalls(text) {
+  if (!text || typeof text !== "string" || !/DSML/i.test(text)) return [];
+  const out = [];
+  const openRe = /<\|{1,2}DSML\|{1,2}invoke\s+name="([^"]+)"\s*>/gi;
+  let m;
+  while ((m = openRe.exec(text)) !== null) {
+    const name = m[1];
+    const start = m.index;
+    const afterOpen = start + m[0].length;
+    const closeRe = /<\/\|{1,2}DSML\|{1,2}invoke>/i;
+    const closeMatch = closeRe.exec(text.slice(afterOpen));
+    const innerEnd = closeMatch ? afterOpen + closeMatch.index : text.length;
+    const end = closeMatch ? innerEnd + closeMatch[0].length : innerEnd;
+    const inner = text.slice(afterOpen, innerEnd);
+    const args = {};
+    const paramRe =
+      /<\|{1,2}DSML\|{1,2}parameter\s+name="([^"]+)"[^>]*>([\s\S]*?)<\/\|{1,2}DSML\|{1,2}parameter>/gi;
+    let p;
+    while ((p = paramRe.exec(inner)) !== null) {
+      args[p[1]] = coerceDsmlValue(p[2].trim());
+    }
+    out.push({
+      id: nextId(),
+      type: "function",
+      function: { name, arguments: args },
+      _pseudo: true,
+      _raw: text.slice(start, end),
+      _rawStart: start,
+      _rawEnd: end,
+    });
+    openRe.lastIndex = end;
+  }
+  return out;
+}
+
+function coerceDsmlValue(raw) {
+  if (raw === "") return "";
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+  if ((raw.startsWith("{") && raw.endsWith("}")) || (raw.startsWith("[") && raw.endsWith("]"))) {
+    try { return JSON.parse(raw); } catch { /* keep the string */ }
+  }
+  return raw;
+}
+
+// Parse `[tool call: NAME] {…}` and the bare `[tool NAME] {…}` — see the note
+// in extractPseudoToolCalls. `_raw` spans the bracket, its argument object AND
+// any `→ …` result copied along with it, so the whole line is removed from the
+// visible text, not just the JSON half.
 function extractBracketToolCalls(text) {
   const out = [];
-  const re = /\[tool[ _]call:\s*([a-zA-Z_][a-zA-Z0-9_]*)\]\s*/g;
+  // Two shapes. `[tool call: NAME]` (also `[tool_call:`, `[tool:`) is the one
+  // models invent. The bare `[tool NAME]` is APX's own — the message store
+  // rendered history that way for a week, and gemini-3.7-flash copied it
+  // fourteen times in a day. It counts as a call only when an argument object
+  // follows: `[tool run_shell] no anduvo` is prose about a tool, not a call.
+  // `[tool result: NAME]` matches NEITHER, deliberately — it annotates a past
+  // record, and re-running someone's old shell command is not a recovery.
+  const re =
+    /\[tool(?:[ _]call)?:\s*([a-zA-Z_][a-zA-Z0-9_]*)\]\s*|\[tool[ _]+([a-zA-Z_][a-zA-Z0-9_]*)\]\s*(?=\{)/g;
   let m;
   while ((m = re.exec(text)) !== null) {
     const argsStart = m.index + m[0].length;
@@ -143,9 +218,14 @@ function extractBracketToolCalls(text) {
         end = balanced.end;
       }
     }
+    // A model copying a record copies the whole thing, result included:
+    // `[tool run_shell] {…} → <output>`. That tail is a stale result being
+    // passed off as a fresh one; the real one arrives when the call runs.
+    const tail = text.slice(end).match(/^[ \t]*(?:→|->|=>)[^\n]*/);
+    if (tail) end += tail[0].length;
     out.push({
       id: nextId(),
-      function: { name: m[1], arguments: args },
+      function: { name: m[1] || m[2], arguments: args },
       _pseudo: true,
       _raw: text.slice(m.index, end),
       _rawStart: m.index,
@@ -269,6 +349,32 @@ export function extractBareFunctionCalls(text, knownNames) {
   }
   return out;
 }
+// APX's own context annotation for a past tool result, in every spelling a
+// model reaches for when it copies the shape instead of calling the tool:
+// `[tool result: run_shell]`, `[result: shell]`, `[tool_result: shell]`. The
+// name is bounded so an ordinary bracketed sentence is not swallowed.
+const TOOL_LOG_NAME = String.raw`\[(?:tool[\s_-]*)?results?\s*[:\-]\s*[a-z0-9_.\- ]{1,40}\]`;
+/** The whole line, when the line IS the annotation. */
+const TOOL_LOG_LINE = new RegExp(String.raw`^[ \t]*${TOOL_LOG_NAME}[^\n]*$`, "gim");
+/** Just the prefix, so a human sentence around it survives. */
+const TOOL_LOG_PREFIX = new RegExp(String.raw`${TOOL_LOG_NAME}\s*`, "gi");
+
+/**
+ * Does this text CLAIM tool results that no tool produced?
+ *
+ * The loop calls this on a turn that emitted zero tool calls. Two or more
+ * annotation lines is not a model quoting its history in passing, it is a model
+ * writing the transcript it was supposed to generate — and the sentence after
+ * them ("Listo, ya te lo mandé") is a report on work that never happened. There
+ * is nothing to recover here: the lines carry no structured call, and guessing
+ * a shell command out of hallucinated prose and running it would be far worse
+ * than asking the model to do the work for real.
+ */
+export function looksLikeFabricatedToolLog(text) {
+  if (!text || typeof text !== "string") return false;
+  return (String(text).match(TOOL_LOG_PREFIX) || []).length >= 2;
+}
+
 export function cleanTextOfPseudoToolCalls(text, knownNames) {
   if (!text || typeof text !== "string") return text;
 
@@ -291,7 +397,22 @@ export function cleanTextOfPseudoToolCalls(text, knownNames) {
   for (const call of extractBareFunctionCalls(out, knownNames)) {
     if (call._raw) out = out.replace(call._raw, "");
   }
-  out = out.replace(/\[tool result:\s*[^\]]+\]\s*/gi, "");
+  // APX's own history annotation: `[tool result: <name>] (<call>) → <result>`.
+  // A line that IS the annotation goes whole — the prefix used to be stripped
+  // on its own, which left `(command=…) → ==> …` standing there as the answer.
+  // Mid-sentence the prefix alone still goes, so the human half survives.
+  //
+  // Matched loosely, because a model copying the shape out of its history does
+  // not copy it exactly. The turn that shipped on 2026-08-29 wrote `[result:
+  // shell]` — no "tool", and the tool's real name is `run_shell` — five times,
+  // each followed by a made-up command and a made-up output, and the strict
+  // pattern let every line through. `[tool_result: x]`, `[results: x]` and
+  // `[result - x]` are the same copy with a different slip.
+  out = out.replace(TOOL_LOG_LINE, "");
+  out = out.replace(TOOL_LOG_PREFIX, "");
+  // The same for the bare `[tool <name>]` form once its call has been lifted
+  // out above: what is left is bookkeeping, never something to say.
+  out = out.replace(/^[ \t]*\[tool[ _]+[a-z_][a-z0-9_]*\][^\n]*$/gim, "");
   // …and the history annotation the message store substitutes for a stale
   // answer (`sanitizeAssistantForContext`). It describes a turn; it is never
   // something to say to the user.
@@ -299,6 +420,8 @@ export function cleanTextOfPseudoToolCalls(text, knownNames) {
   // Some models emit a stray `</function>` after the args without the
   // opening tag — sweep those too.
   out = out.replace(/<\/?function(?:\.[a-zA-Z_][a-zA-Z0-9_]*)?>/gi, "");
+  // Leftover DSML wrappers after the invoke spans were removed.
+  out = out.replace(/<\/?\|{1,2}DSML\|{1,2}[^>]*>/gi, "");
 
   // Tidy up whitespace & blank lines
   out = out.replace(/\n{3,}/g, "\n\n").trim();

package/src/core/agent/vision-bridge.js

@@ -0,0 +1,69 @@
+// Vision bridge: turn attached photos into a short text description for models
+// that cannot see pixels (zen:big-pickle and most free Zen models, etc.).
+//
+// Gemini already renders `m.images` as inlineData. OpenAI/Anthropic wire them
+// as multimodal parts. Zen free models advertise chat but not vision — sending
+// raw image_url often 400s or is ignored, and the agent roleplays "I can't see
+// the photo". Bridging once with a vision model and folding the description
+// into the prompt is what makes Candela actually react to a gym selfie.
+import { callEngine } from "#core/engines/index.js";
+import { modelWiresVision } from "#core/agent/model-capabilities.js";
+
+const DEFAULT_VISION_MODEL = "gemini:gemini-2.0-flash";
+
+const BRIDGE_SYSTEM =
+  "You describe photos for another AI that cannot see them. Be concrete: who/what, " +
+  "clothing, pose, setting, expression. 3–6 sentences. No preamble, no 'the image shows'.";
+
+/** Backward-compatible name used by the turn builder. */
+export const providerWiresVision = modelWiresVision;
+
+export function visionBridgeModel(globalConfig) {
+  const configured = globalConfig?.super_agent?.vision_bridge_model;
+  if (typeof configured === "string" && configured.includes(":")) return configured;
+  // Prefer an explicit has_image routing target if the operator already named one.
+  const rules = globalConfig?.super_agent?.routing?.rules;
+  if (Array.isArray(rules)) {
+    for (const r of rules) {
+      if (r?.when?.has_image === true && typeof r.model === "string" && r.model.includes(":")) {
+        return r.model;
+      }
+    }
+  }
+  return DEFAULT_VISION_MODEL;
+}
+
+/**
+ * Describe turn images with a vision model. Returns null on failure (no key,
+ * model down) so the caller can keep going with the path marker alone.
+ */
+export async function describeTurnImages(images, globalConfig, { signal } = {}) {
+  const usable = (images || []).filter((im) => im && im.data && im.mime);
+  if (!usable.length) return null;
+  const modelId = visionBridgeModel(globalConfig);
+  try {
+    const result = await callEngine({
+      modelId,
+      system: BRIDGE_SYSTEM,
+      messages: [{
+        role: "user",
+        content: usable.length === 1 ? "Describe this photo." : `Describe these ${usable.length} photos.`,
+        images: usable.map((im) => ({ data: im.data, mime: im.mime })),
+      }],
+      config: globalConfig,
+      maxTokens: 500,
+      signal,
+    });
+    const text = (result.text || "").trim();
+    return text || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Fold a bridge description into the prompt the text model will read. */
+export function withImageDescription(prompt, description) {
+  if (!description) return prompt;
+  const block = `[Attached photo — you cannot see pixels; this is what it shows:\n${description}\n]`;
+  return prompt ? `${prompt}\n\n${block}` : block;
+}

package/src/core/apc/agent-identity.js

@@ -0,0 +1,74 @@
+// An agent's visual and organisational identity: its avatar blob and its
+// typology.
+//
+// WHY THESE LIVE IN CORE. Both used to be web-only knowledge — the blob keys in
+// `blobPresets.ts` and the five typologies hardcoded in `AgentDetailScreen.tsx`.
+// So an agent created from the web got a face and a type, and the same agent
+// created from the CLI, the MCP server or the super-agent got neither: it
+// rendered as a grey lettered disc and carried no typology at all. The surfaces
+// that create agents are not all in the browser, so the vocabulary can't be.
+
+// Blob keys come from ./blob-keys.js, which `scripts/export_web_assets.py`
+// generates alongside the renderer's blobPresets.ts — one generator, two
+// consumers. `tests/agent-blob-parity.test.js` fails if the two ever drift.
+export { BLOB_KEYS } from "./blob-keys.js";
+import { BLOB_KEYS } from "./blob-keys.js";
+
+/** Default super-agent avatar. Users may override it with super_agent.icon. */
+export const SUPER_AGENT_BLOB = "noche";
+
+export function isBlobKey(v) {
+  return typeof v === "string" && BLOB_KEYS.includes(v);
+}
+
+/** Resolve a safe super-agent avatar from global config. */
+export function resolveSuperAgentBlob(config) {
+  return isBlobKey(config?.super_agent?.icon) ? config.super_agent.icon : SUPER_AGENT_BLOB;
+}
+
+/**
+ * Choose an avatar for a new agent.
+ *
+ * Random, but not naively so: it draws from the blobs this project isn't
+ * already using, so a team of six has six distinguishable faces instead of the
+ * same one three times over — which is the whole point of having an avatar. Once
+ * every blob is taken it falls back to the full list, since a repeat beats no
+ * face at all.
+ *
+ * @param taken  blob keys already in use in this project
+ * @param rng    injectable [0,1) source, for deterministic tests
+ */
+export function pickBlob({ taken = [], rng = Math.random } = {}) {
+  const used = new Set([SUPER_AGENT_BLOB, ...taken.filter(isBlobKey)]);
+  const free = BLOB_KEYS.filter((k) => !used.has(k));
+  const pool = free.length > 0 ? free : BLOB_KEYS.filter((k) => k !== SUPER_AGENT_BLOB);
+  return pool[Math.floor(rng() * pool.length) % pool.length];
+}
+
+/**
+ * Agent typologies. The value is what lands in `Type:` frontmatter; the label
+ * and description are what the web shows in its picker.
+ *
+ * `orchestrator` also implies master: the web sets `is_master` when the type is
+ * orchestrator, and the daemon does the same on create, so the hierarchy view
+ * and the typology can't disagree.
+ */
+export const AGENT_TYPES = Object.freeze([
+  { value: "orchestrator", label: "Orchestrator", description: "Coordinates the team and delegates." },
+  { value: "specialist",   label: "Specialist",   description: "Domain expert; runs tasks." },
+  { value: "assistant",    label: "Assistant",    description: "Conversational helper." },
+  { value: "worker",       label: "Worker",       description: "Runs autonomous tasks." },
+  { value: "monitor",      label: "Monitor",      description: "Watches state and reports." },
+]);
+
+export const AGENT_TYPE_VALUES = Object.freeze(AGENT_TYPES.map((t) => t.value));
+
+export function isAgentType(v) {
+  return typeof v === "string" && AGENT_TYPE_VALUES.includes(v);
+}
+
+/** Lowercase and validate. Returns null for empty/unknown input. */
+export function normalizeAgentType(v) {
+  const s = String(v || "").trim().toLowerCase();
+  return isAgentType(s) ? s : null;
+}