mixdog 1.2.6 → 1.3.1

package/src/runtime/shared/agent-avatar.mjs

@@ -0,0 +1,320 @@
+// The Mixdog mascot: a blocky pixel creature on a 16x12 grid, painted from the
+// string layers in agent-avatar-sprites.mjs (design/mockups/mixy-art). Every
+// look is the same body block; the species (ears, marks, tail, legs), an
+// accessory, the expression and the colour vary. An agent's `agent.json`
+// stores its pick as `avatar: { kind: 'mascot', species, accessory,
+// expression, color }` (an older `variant` reads as its mapped look), or its
+// own images per motion state as `avatar: { kind: 'custom', states: { idle,
+// typing?, message? } }`. An agent without one gets a stable look from its id.
+import { MIXY_AGENT_ID } from '../agent/orchestrator/session/agent-home.mjs';
+import { MASCOT_SPRITES } from './agent-avatar-sprites.mjs';
+
+/** The palette an avatar colour is chosen from. */
+export const AGENT_AVATAR_COLORS = Object.freeze([
+  '#e6e6e6',
+  '#9a9a9a',
+  '#f06a5f',
+  '#f59a42',
+  '#f2c94c',
+  '#5cc98a',
+  '#3fc1c9',
+  '#5b9bff',
+  '#9b7bff',
+  '#ef6fb0',
+]);
+
+/** Every species a user can pick: the six dogs. Mixy's own (`mixy`) is not one of them. */
+export const MASCOT_SPECIES = Object.freeze(['labrador', 'shepherd', 'terrier', 'corgi', 'husky', 'shiba']);
+export const MASCOT_ACCESSORIES = Object.freeze(['none', 'collar', 'glasses', 'beanie', 'scarf', 'bow']);
+/** Picks that were removed, read as their nearest remaining option. */
+const RETIRED_SPECIES = { dalmatian: 'labrador', cat: 'labrador', bird: 'labrador', robot: 'labrador' };
+const RETIRED_ACCESSORIES = { headset: 'glasses' };
+export const MASCOT_EXPRESSIONS = Object.freeze(['calm', 'happy', 'wink', 'sleepy']);
+
+/** Mixy, the primary assistant: its own silver pup with one ear up and a
+ *  slate collar with the gold star medal. Never offered in the picker. */
+export const MIXY_AVATAR = Object.freeze({
+  kind: 'mascot',
+  species: 'mixy',
+  accessory: 'none',
+  expression: 'calm',
+  color: '#e6e6e6',
+});
+
+/** The fixed inks a sprite letter names; B, D, L and E depend on the look. */
+export const MASCOT_INKS = Object.freeze({
+  K: '#141414',
+  G: '#f2c94c',
+  R: '#e5534b',
+  O: '#f59a42',
+  W: '#f4f4f4',
+  C: '#3fc1c9',
+  M: '#8a8a90',
+  S: '#2a2b30',
+  P: '#ef8fb4',
+  N: '#f06a5f',
+  n: '#c4544c',
+  r: '#b94039',
+  F: '#ef6fb0',
+  f: '#b8497f',
+});
+
+/** `hex` with every channel scaled by `k`. */
+export function shadeHex(hex, k) {
+  const n = Number.parseInt(hex.slice(1), 16);
+  const channel = (shift) =>
+    Math.round(((n >> shift) & 255) * k)
+      .toString(16)
+      .padStart(2, '0');
+  return `#${channel(16)}${channel(8)}${channel(0)}`;
+}
+
+/** `hex` mixed `k` of the way to white. */
+function liftHex(hex, k) {
+  const n = Number.parseInt(hex.slice(1), 16);
+  const channel = (shift) => {
+    const value = (n >> shift) & 255;
+    return Math.round(value + (255 - value) * k)
+      .toString(16)
+      .padStart(2, '0');
+  };
+  return `#${channel(16)}${channel(8)}${channel(0)}`;
+}
+
+// The 12 looks before species existed, `<ears>-<expression>-<plain|collar>`:
+// each reads as the species with those ears, the collar as an accessory.
+const LEGACY_EARS = { floppy: 'labrador', perky: 'shepherd', folded: 'terrier' };
+const LEGACY_VARIANTS = Object.keys(LEGACY_EARS).flatMap((ears) =>
+  ['calm', 'happy'].flatMap((expression) => ['plain', 'collar'].map((extra) => `${ears}-${expression}-${extra}`))
+);
+
+/** An older `variant` as its species, accessory and expression; null if unknown. */
+export function mascotFromVariant(variant) {
+  if (!LEGACY_VARIANTS.includes(variant)) return null;
+  const [ears, expression, extra] = variant.split('-');
+  return { species: LEGACY_EARS[ears], accessory: extra === 'collar' ? 'collar' : 'none', expression };
+}
+
+/** `species-accessory-expression`: a look's key (data attributes, tests). */
+export const mascotLook = (avatar) => `${avatar.species}-${avatar.accessory}-${avatar.expression}`;
+
+function layerCells(rows, color, eye) {
+  if (!rows) return [];
+  const ink = (key) => {
+    if (key === 'B') return color;
+    if (key === 'D') return shadeHex(color, 0.7);
+    if (key === 'L') return liftHex(color, 0.35);
+    return MASCOT_INKS[key === 'E' ? eye : key];
+  };
+  const cells = [];
+  rows.forEach((row, y) => {
+    for (let x = 0; x < row.length; x += 1) if (row[x] !== '.') cells.push({ x, y, fill: ink(row[x]) });
+  });
+  return cells;
+}
+
+/** A look's cells by part, in paint order — the groups the renderer draws
+ *  (tail, legs, then the bobbing body with its ears, marks, eyes and
+ *  accessory). `blink` is the closed eyes an idle blink shows. Null for an
+ *  unknown species. */
+export function mascotParts(avatar) {
+  const species = MASCOT_SPRITES.species[avatar.species];
+  if (!species) return null;
+  const paint = (rows) => layerCells(rows, avatar.color, species.eye);
+  return {
+    tail: paint(species.tail && MASCOT_SPRITES.tails[species.tail]),
+    legs: paint(MASCOT_SPRITES.legs[species.legs]),
+    body: paint(MASCOT_SPRITES.body),
+    ear: paint(species.ears),
+    marks: paint(species.marks),
+    eyes: paint(MASCOT_SPRITES.eyes[avatar.expression]),
+    blink: paint(MASCOT_SPRITES.eyes.sleepy),
+    accessory: paint(MASCOT_SPRITES.accessories[avatar.accessory]),
+  };
+}
+
+/** The look as one still frame: each cell's final fill. [] when unknown. */
+export function mascotCells(avatar) {
+  const parts = mascotParts(avatar);
+  if (!parts) return [];
+  const cells = new Map();
+  for (const part of ['tail', 'legs', 'body', 'ear', 'marks', 'eyes', 'accessory']) {
+    for (const cell of parts[part]) cells.set(`${cell.y},${cell.x}`, cell);
+  }
+  return [...cells.values()];
+}
+
+/** Cells as one SVG path per fill, each row's run one rectangle. */
+export function cellPaths(cells) {
+  const byFill = new Map();
+  for (const { x, y, fill } of cells) {
+    const rows = byFill.get(fill) ?? new Map();
+    byFill.set(fill, rows);
+    rows.set(y, [...(rows.get(y) ?? []), x]);
+  }
+  return [...byFill].map(([fill, rows]) => {
+    let d = '';
+    for (const [y, xs] of [...rows].sort(([a], [b]) => a - b)) {
+      const sorted = [...new Set(xs)].sort((a, b) => a - b);
+      for (let i = 0; i < sorted.length; ) {
+        let j = i;
+        while (j + 1 < sorted.length && sorted[j + 1] === sorted[j] + 1) j += 1;
+        const run = j - i + 1;
+        d += `M${sorted[i]} ${y}h${run}v1h-${run}z`;
+        i = j + 1;
+      }
+    }
+    return { fill, d };
+  });
+}
+
+/** The motion states an avatar shows today, `idle` first (a custom avatar's
+ *  one required image, and every missing state's fallback). */
+export const AGENT_AVATAR_STATES = Object.freeze(['idle', 'typing', 'message']);
+
+/** The single image avatar before per-state images: a PNG beside AGENT.md
+ *  under a content-hash name. Still read, as a custom avatar's idle image. */
+export const AGENT_AVATAR_IMAGE_FILE = /^avatar-[0-9a-f]{12}\.png$/;
+/** One state's image in `agents/<id>/avatar/`, under a content-hash name (a
+ *  new upload is a new name, so caches by name never go stale). An animated
+ *  one keeps its still first frame beside it (avatarPosterFile). */
+export const AGENT_AVATAR_STATE_FILE = /^(idle|typing|message)-[0-9a-f]{12}\.(png|gif|webp)$/;
+export const AGENT_AVATAR_DIR = 'avatar';
+/** The largest image upload accepted, and the largest side of an animation. */
+export const AGENT_AVATAR_IMAGE_MAX_BYTES = 1024 * 1024;
+export const AGENT_AVATAR_IMAGE_MAX_SIDE = 512;
+
+/** A state image's path under the agent's folder ('/'-separated). */
+export const agentAvatarStatePath = (file) =>
+  AGENT_AVATAR_IMAGE_FILE.test(file) ? file : `${AGENT_AVATAR_DIR}/${file}`;
+/** The still first frame stored beside an animated state image. */
+export const avatarPosterFile = (file) => file.replace(/\.(png|gif|webp)$/, '.poster.png');
+/** The image a custom avatar shows in `state`: its own, else idle's. */
+export const customAvatarStateFile = (avatar, state) => avatar.states[state] ?? avatar.states.idle;
+
+const u16le = (bytes, at) => bytes[at] | (bytes[at + 1] << 8);
+const u24le = (bytes, at) => bytes[at] | (bytes[at + 1] << 8) | (bytes[at + 2] << 16);
+const u32be = (bytes, at) => ((bytes[at] << 24) | (bytes[at + 1] << 16) | (bytes[at + 2] << 8) | bytes[at + 3]) >>> 0;
+const ascii = (bytes, at, length) => String.fromCharCode(...bytes.subarray(at, at + length));
+
+/** An upload's format and size, read from its header bytes: a PNG (an APNG
+ *  counts as animated), a GIF (always treated as animated) or a WebP; null
+ *  for anything else — SVG and every other markup included. */
+export function avatarImageInfo(bytes) {
+  if (!(bytes instanceof Uint8Array) || bytes.length < 30) return null;
+  if (u32be(bytes, 0) === 0x89504e47 && u32be(bytes, 4) === 0x0d0a1a0a && ascii(bytes, 12, 4) === 'IHDR') {
+    let animated = false;
+    for (let at = 8; at + 8 <= bytes.length; at += 12 + u32be(bytes, at)) {
+      const type = ascii(bytes, at + 4, 4);
+      if (type === 'acTL') animated = true;
+      if (type === 'IDAT' || type === 'IEND') break;
+    }
+    return { format: 'png', width: u32be(bytes, 16), height: u32be(bytes, 20), animated };
+  }
+  if (ascii(bytes, 0, 6) === 'GIF87a' || ascii(bytes, 0, 6) === 'GIF89a') {
+    return { format: 'gif', width: u16le(bytes, 6), height: u16le(bytes, 8), animated: true };
+  }
+  if (ascii(bytes, 0, 4) === 'RIFF' && ascii(bytes, 8, 4) === 'WEBP') {
+    const chunk = ascii(bytes, 12, 4);
+    if (chunk === 'VP8X') {
+      const animated = (bytes[20] & 0x02) !== 0;
+      return { format: 'webp', width: u24le(bytes, 24) + 1, height: u24le(bytes, 27) + 1, animated };
+    }
+    if (chunk === 'VP8 ') {
+      return { format: 'webp', width: u16le(bytes, 26) & 0x3fff, height: u16le(bytes, 28) & 0x3fff, animated: false };
+    }
+    if (chunk === 'VP8L') {
+      const bits = (bytes[21] | (bytes[22] << 8) | (bytes[23] << 16) | (bytes[24] << 24)) >>> 0;
+      return { format: 'webp', width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1, animated: false };
+    }
+  }
+  return null;
+}
+
+/** Why bytes cannot be a state image ('' when they can): not a PNG, GIF or
+ *  WebP, over 1 MB, not square, or over 512px. */
+export function agentAvatarImageProblem(bytes) {
+  const info = avatarImageInfo(bytes);
+  if (!info) return 'must be a PNG, GIF or WebP image';
+  if (bytes.length > AGENT_AVATAR_IMAGE_MAX_BYTES) return 'is larger than 1 MB';
+  if (!info.width || info.width !== info.height) return 'must be square';
+  if (info.width > AGENT_AVATAR_IMAGE_MAX_SIDE) return 'must be 512px or smaller';
+  return '';
+}
+
+function normalizeCustom(states) {
+  if (!states || typeof states !== 'object') return null;
+  const kept = {};
+  for (const state of AGENT_AVATAR_STATES) {
+    const file = states[state];
+    if (file == null) continue;
+    const own = typeof file === 'string' && AGENT_AVATAR_STATE_FILE.test(file) && file.startsWith(`${state}-`);
+    const legacy = state === 'idle' && typeof file === 'string' && AGENT_AVATAR_IMAGE_FILE.test(file);
+    if (!own && !legacy) return null;
+    kept[state] = file;
+  }
+  return kept.idle ? { kind: 'custom', states: kept } : null;
+}
+
+const pick = (value, list, fallback) => (value == null ? fallback : list.includes(value) ? value : null);
+
+/** A stored avatar as the app understands it, or null when it is not one. An
+ *  older single image reads as a custom avatar with only its idle image; an
+ *  older mascot `variant` as its mapped species, accessory and expression. */
+export function normalizeAgentAvatar(value) {
+  if (!value || typeof value !== 'object') return null;
+  if (value.kind === 'image') {
+    return typeof value.file === 'string' && AGENT_AVATAR_IMAGE_FILE.test(value.file)
+      ? { kind: 'custom', states: { idle: value.file } }
+      : null;
+  }
+  if (value.kind === 'custom') return normalizeCustom(value.states);
+  if (value.kind !== 'mascot') return null;
+  const color = typeof value.color === 'string' ? value.color.toLowerCase() : '';
+  if (!AGENT_AVATAR_COLORS.includes(color)) return null;
+  const look =
+    value.species == null && typeof value.variant === 'string'
+      ? mascotFromVariant(value.variant)
+      : {
+          species: pick(
+            RETIRED_SPECIES[value.species] ?? value.species,
+            [...MASCOT_SPECIES, MIXY_AVATAR.species],
+            null
+          ),
+          accessory: pick(RETIRED_ACCESSORIES[value.accessory] ?? value.accessory, MASCOT_ACCESSORIES, 'none'),
+          expression: pick(value.expression, MASCOT_EXPRESSIONS, 'calm'),
+        };
+  if (!look?.species || !look.accessory || !look.expression) return null;
+  return { kind: 'mascot', ...look, color };
+}
+
+// FNV-1a: a small stable string hash, the same on every platform.
+function hashId(id) {
+  let hash = 0x811c9dc5;
+  for (const char of String(id)) {
+    hash ^= char.codePointAt(0);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash;
+}
+
+/** The look of an agent that never picked one: fixed by its id — the
+ *  species, accessory and colour it had before species existed (its old
+ *  variant, mapped), with the neutral face every default wears. */
+export function defaultAgentAvatar(id) {
+  const hash = hashId(id);
+  return {
+    kind: 'mascot',
+    ...mascotFromVariant(LEGACY_VARIANTS[hash % LEGACY_VARIANTS.length]),
+    expression: 'calm',
+    color: AGENT_AVATAR_COLORS[Math.floor(hash / LEGACY_VARIANTS.length) % AGENT_AVATAR_COLORS.length],
+  };
+}
+
+/** What an agent shows: its own images, else Mixy's fixed look (for Mixy),
+ *  its own mascot pick, or its id default. */
+export function agentAvatar(id, stored) {
+  const own = normalizeAgentAvatar(stored);
+  if (id === MIXY_AGENT_ID) return own ?? { ...MIXY_AVATAR };
+  return own ?? defaultAgentAvatar(id);
+}

package/src/runtime/shared/agent-kind.mjs

@@ -0,0 +1,152 @@
+// An agent definition's kind (isContactAgentId reads it), decided read-only —
+// the one rule for the runtime and the desktop (which reads `kind` from the
+// runtime's catalog rows). Nothing is ever stamped on disk.
+//
+// An explicit frontmatter `kind` wins (`bot` from the bot dialog and Mixy's
+// setup tool, `agent` from the Workflows page and other chats). v1.3.0 wrote
+// no marker for bots, and v1.2.6 agents have none either, so an unmarked
+// user-made agent is a bot only on evidence that only a v1.3.0 bot creation
+// produced:
+//   T1  its home thread holds the creation greeting (agentGreetingKickoff,
+//       sent only to bots a dialog or the host greeted on creation; agents
+//       older than 1.3 were recorded without one);
+//   T2  its agent.json has an `avatar` (the bot dialog always sent one) AND
+//       its AGENT.md body is the bot dialog's default (agentBodyFromBrief).
+// Anything else is a workflow agent, as in v1.2.6.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { agentHomeSessionId } from '../agent/orchestrator/session/agent-home.mjs';
+import { readMarkdownDocument } from './markdown-frontmatter.mjs';
+import { BOT_AGENT_KIND } from './agent-route-config.mjs';
+import { botStoreActive, isStoreBot } from './agent-store.mjs';
+
+const RUNTIME_MARKER = '[mixdog-runtime]';
+/** The creation greeting's opening (shared/agent-greeting.ts, v1.3.0 on). */
+const CREATION_GREETING = /(^|\n)\[mixdog-runtime\] The user just created you as /;
+/** The closing lines of the bot dialog's default AGENT.md (agentBodyFromBrief). */
+const DIALOG_BODY_TAIL = [
+  /^- Help the user( with this role)? in a natural, friendly conversation, in the language they write in\.$/,
+  /^- Ask a short question when a request is unclear, and say plainly when something is outside what you do\.$/,
+  /^- Keep replies as short or as detailed as the moment needs\.$/,
+];
+
+function messageText(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((part) => (typeof part === 'string' ? part : typeof part?.text === 'string' ? part.text : ''))
+    .join('\n');
+}
+
+const NO_HOME = Object.freeze({ exists: false, greeted: false, chatted: false });
+// Per session file, keyed by its size and mtime: a home thread is read once
+// until it changes.
+const homeEvidenceCache = new Map();
+
+/** What `agentId`'s home thread (sessions/sess_home_<id>.json) holds:
+ *  whether it exists, whether it has the creation greeting, and whether the
+ *  user and the agent talked (any user message that is not a runtime turn,
+ *  or any assistant message). A missing or unreadable file holds nothing. */
+export function homeThreadEvidence(dataDir, agentId) {
+  const sessionId = agentHomeSessionId(agentId);
+  if (!dataDir || !sessionId) return NO_HOME;
+  const file = join(dataDir, 'sessions', `${sessionId}.json`);
+  let stat;
+  try {
+    stat = statSync(file);
+  } catch {
+    return NO_HOME;
+  }
+  const cached = homeEvidenceCache.get(file);
+  if (cached && cached.size === stat.size && cached.mtimeMs === stat.mtimeMs) return cached.value;
+  let messages = [];
+  try {
+    const doc = JSON.parse(readFileSync(file, 'utf8'));
+    if (Array.isArray(doc?.messages)) messages = doc.messages;
+  } catch {
+    // unreadable: it proves nothing
+  }
+  let greeted = false;
+  let chatted = false;
+  for (const message of messages) {
+    if (message?.role === 'assistant') chatted = true;
+    if (message?.role !== 'user') continue;
+    const text = messageText(message.content);
+    if (CREATION_GREETING.test(text)) greeted = true;
+    else if (text.trim() && !text.trimStart().startsWith(RUNTIME_MARKER)) chatted = true;
+  }
+  const value = Object.freeze({ exists: true, greeted, chatted });
+  homeEvidenceCache.set(file, { size: stat.size, mtimeMs: stat.mtimeMs, value });
+  return value;
+}
+
+function isDialogDefaultBody(body) {
+  const lines = String(body || '')
+    .trim()
+    .split(/\r?\n/);
+  const tail = lines.slice(-DIALOG_BODY_TAIL.length);
+  return tail.length === DIALOG_BODY_TAIL.length && DIALOG_BODY_TAIL.every((line, index) => line.test(tail[index]));
+}
+
+/** The definition's kind: the explicit frontmatter kind (lower-cased); else,
+ *  for an unmarked user-made agent (`dataDir`/`id` given, not a shipped role),
+ *  `bot` on T1 or T2 evidence; else null (a workflow agent). `manifest` and
+ *  `body` are the user copy's agent.json and AGENT.md body. */
+export function agentDefinitionKind(definition) {
+  const { dataDir, id } = definition;
+  // Once bots have their own store the folder decides: bots/ holds bots,
+  // agents/ workflow agents (an explicit marker still read as written).
+  if (dataDir && id && isStoreBot(dataDir, id)) return BOT_AGENT_KIND;
+  if (dataDir && botStoreActive(dataDir)) return explicitKind(definition.frontmatterKind);
+  return evidenceKind(definition);
+}
+
+const explicitKind = (frontmatterKind) =>
+  (typeof frontmatterKind === 'string' ? frontmatterKind.trim().toLowerCase() : '') || null;
+
+/** The pre-store rule alone (the split's decision input): the explicit kind,
+ *  else `bot` on T1/T2 evidence for an unmarked user-made agent, else null. */
+export function evidenceKind({ frontmatterKind, dataDir, shippedRoot, id, manifest, body }) {
+  const explicit = explicitKind(frontmatterKind);
+  if (explicit) return explicit;
+  if (!dataDir || !id || id === 'lead') return null;
+  if (shippedRoot && existsSync(join(shippedRoot, 'agents', id, 'AGENT.md'))) return null;
+  if (manifest?.avatar && isDialogDefaultBody(body)) return BOT_AGENT_KIND;
+  return homeThreadEvidence(dataDir, id).greeted ? BOT_AGENT_KIND : null;
+}
+
+/** agentDefinitionKind from the user copy on disk, for readers that have no
+ *  loaded definition at hand: a store bot (bots/<id>/) is a bot; any other id
+ *  is read from agents/<id>/, else from the shipped role. */
+export function readAgentDefinitionKind({ dataDir, shippedRoot, id }) {
+  if (isStoreBot(dataDir, id)) return BOT_AGENT_KIND;
+  const dir = join(dataDir, 'agents', id);
+  let doc;
+  try {
+    doc = readMarkdownDocument(readFileSync(join(dir, 'AGENT.md'), 'utf8'));
+  } catch {
+    // No user copy: the shipped role's own frontmatter decides.
+    try {
+      return agentDefinitionKind({
+        frontmatterKind: readMarkdownDocument(readFileSync(join(shippedRoot, 'agents', id, 'AGENT.md'), 'utf8'))
+          .frontmatter.kind,
+      });
+    } catch {
+      return null;
+    }
+  }
+  let manifest = {};
+  try {
+    manifest = JSON.parse(readFileSync(join(dir, 'agent.json'), 'utf8')) || {};
+  } catch {
+    manifest = {};
+  }
+  return agentDefinitionKind({
+    frontmatterKind: doc.frontmatter.kind,
+    dataDir,
+    shippedRoot,
+    id,
+    manifest,
+    body: doc.body,
+  });
+}

package/src/runtime/shared/agent-route-config.d.mts

@@ -0,0 +1,4 @@
+// Types for the desktop's one import of agent-route-config.mjs.
+export const WORKFLOW_AGENT_KIND: 'agent';
+export const BOT_AGENT_KIND: 'bot';
+export function isContactAgentId(value: unknown, kind?: unknown): boolean;

package/src/runtime/shared/agent-route-config.mjs

@@ -16,6 +16,26 @@ export const DEFAULT_DISABLED_AGENT_IDS = Object.freeze([
 // runs only once the user turns it on and picks its model.
 export const DEFAULT_DISABLED_AGENT_ROSTER = Object.freeze([...DEFAULT_DISABLED_AGENT_IDS, 'maintainer']);
 
+/** The AGENT.md frontmatter `kind` the Workflows page writes when it creates
+ *  an agent: a workflow delegation role, never a contact (봇). */
+export const WORKFLOW_AGENT_KIND = 'agent';
+
+/** The AGENT.md frontmatter `kind` every bot creation path writes: the bot
+ *  dialog, and the setup tool when Mixy (agent mode) creates an agent. */
+export const BOT_AGENT_KIND = 'bot';
+
+/** A contact agent (a 봇): one explicitly marked `kind: bot` at creation —
+ *  never Mixy ('lead') nor a shipped role (the starter sub-agents Worker,
+ *  Reviewer, … and the Maintainer). `kind` is the definition's frontmatter
+ *  `kind`; an unmarked custom agent (every agent made before bots existed)
+ *  stays a workflow agent. The one rule for the runtime (delegation, agent
+ *  catalogs) and the desktop (contacts, agent lists). */
+export function isContactAgentId(value, kind) {
+  const id = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  const bot = typeof kind === 'string' && kind.trim().toLowerCase() === BOT_AGENT_KIND;
+  return Boolean(id) && id !== 'lead' && !DEFAULT_DISABLED_AGENT_ROSTER.includes(id) && bot;
+}
+
 function record(value) {
   return isPlainObject(value) ? value : {};
 }
@@ -112,9 +132,19 @@ export function withAgentDisabled(config, agentId, disabled) {
 // left under retired slots (agents.maintenance, workflowRoutes.*,
 // maintenance.memory, generated workflow-* presets) are scrubbed by
 // canonicalizeAgentRouteStorage, never folded in.
+// A bot's route lives with the bot (agent-store.mjs registers the reader in
+// the runtime): the resolver answers a route, null (a bot without one), or
+// undefined (no bot — the config decides).
+let botRouteResolver = null;
+export function setBotRouteResolver(resolver) {
+  botRouteResolver = typeof resolver === 'function' ? resolver : null;
+}
+
 export function configuredAgentRouteCandidates(config, agentId) {
   const id = String(agentId || '').trim();
   if (!id) return [];
+  const bot = botRouteResolver?.(id);
+  if (bot !== undefined) return bot ? [bot] : [];
   const route = record(config?.agents)[id];
   return route ? [route] : [];
 }

package/src/runtime/shared/agent-store.mjs

@@ -0,0 +1,132 @@
+// Where a user-made definition lives once bots have their own store (1.3.1):
+// bots under <dataDir>/bots/<id>/ (with their own model route in agent.json),
+// workflow agents under <dataDir>/agents/<id>/. The store is active once the
+// one-time split finished (bots/migration.json, bot-split-migration.mjs);
+// before that — or if it never could run — every reader sees agents/ as
+// before. The ids the split copied are bots for good: their agents/ originals
+// stay on disk for rollback but no catalog reads them again.
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { setBotRouteResolver } from './agent-route-config.mjs';
+
+export const BOTS_DIR = 'bots';
+export const BOT_MIGRATION_MANIFEST = 'migration.json';
+export const BOT_MIGRATION_VERSION = 1;
+/** Mixy's bot id once it has its own folder. */
+export const MIXY_BOT_ID = 'mixy';
+
+function readJson(file) {
+  try {
+    const value = JSON.parse(readFileSync(file, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+// Small stat-keyed caches: the store is read on route and catalog paths.
+const fileCache = new Map();
+function cachedJson(file) {
+  let stat;
+  try {
+    stat = statSync(file);
+  } catch {
+    fileCache.delete(file);
+    return null;
+  }
+  const hit = fileCache.get(file);
+  if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return hit.value;
+  const value = readJson(file);
+  fileCache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, value });
+  return value;
+}
+
+/** The finished split's record, or null before it ran. */
+export function readBotMigration(dataDir) {
+  if (!dataDir) return null;
+  const manifest = cachedJson(join(dataDir, BOTS_DIR, BOT_MIGRATION_MANIFEST));
+  return manifest?.version === BOT_MIGRATION_VERSION ? manifest : null;
+}
+
+/** Whether `dataDir` has its bot store (the split finished). */
+export function botStoreActive(dataDir) {
+  return readBotMigration(dataDir) !== null;
+}
+
+/** The agents/ ids the split copied to bots/: the agent catalog skips them. */
+export function migratedBotIds(dataDir) {
+  return new Set(readBotMigration(dataDir)?.bots || []);
+}
+
+export const botDir = (dataDir, id) => join(dataDir, BOTS_DIR, id);
+
+/** Whether `id` is a store bot: the store is active and the bot has its
+ *  folder, or the split copied it (an id it moved is never an agent again).
+ *  Mixy's own folder is no ordinary bot. */
+export function isStoreBot(dataDir, id) {
+  if (!dataDir || !id || id === MIXY_BOT_ID || id.startsWith('.')) return false;
+  const manifest = readBotMigration(dataDir);
+  if (!manifest) return false;
+  return existsSync(botDir(dataDir, id)) || (manifest.bots || []).includes(id);
+}
+
+/** The folder of a user-made definition: bots/<id> for a store bot, else agents/<id>. */
+export function userDefinitionDir(dataDir, id) {
+  return isStoreBot(dataDir, id) ? botDir(dataDir, id) : join(dataDir, 'agents', id);
+}
+
+const isCompleteRoute = (route) =>
+  Boolean(
+    route && typeof route === 'object' && String(route.provider || '').trim() && String(route.model || '').trim()
+  );
+
+/** A store bot's own route (agent.json `route`): the route, null when it has
+ *  none, undefined when `id` is no store bot. */
+export function readBotRoute(dataDir, id) {
+  if (!isStoreBot(dataDir, id)) return undefined;
+  const route = cachedJson(join(botDir(dataDir, id), 'agent.json'))?.route;
+  return isCompleteRoute(route) ? route : null;
+}
+
+/** Stores (or with null removes) a store bot's route in its agent.json; every
+ *  other key is kept. */
+export function writeBotRoute(dataDir, id, route) {
+  const dir = botDir(dataDir, id);
+  const file = join(dir, 'agent.json');
+  const manifest = readJson(file) || {};
+  if (route) manifest.route = route;
+  else delete manifest.route;
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+  fileCache.delete(file);
+}
+
+// --- Mixy: its own bot (bots/mixy), apart from the Lead ---
+// Mixy's identity (name, face, persona, 일하는 방식, connectors, `created`)
+// lives in bots/mixy once the store is active, in agents/lead before. Its
+// model route is always its own (bots/mixy/agent.json `route`), never the
+// Lead's: changing one never changes the other. Its home thread keeps the id
+// sess_home_lead, and its runtime role id stays `lead`.
+
+/** The folder Mixy's identity is read from and written to. */
+export function mixyIdentityDir(dataDir) {
+  return botStoreActive(dataDir) ? botDir(dataDir, MIXY_BOT_ID) : join(dataDir, 'agents', 'lead');
+}
+
+/** Mixy's own route, or null when it has none (its thread keeps its own). */
+export function readMixyRoute(dataDir) {
+  if (!dataDir) return null;
+  const route = cachedJson(join(botDir(dataDir, MIXY_BOT_ID), 'agent.json'))?.route;
+  return isCompleteRoute(route) ? route : null;
+}
+
+/** Stores (or with null removes) Mixy's own route; nothing of the Lead's. */
+export function writeMixyRoute(dataDir, route) {
+  writeBotRoute(dataDir, MIXY_BOT_ID, route);
+}
+
+/** Every config route read (configuredAgentRouteCandidates) asks the bot
+ *  store first: a bot's route lives with the bot, never in the config. */
+export function registerBotRouteStore(getDataDir) {
+  setBotRouteResolver((id) => readBotRoute(getDataDir(), id));
+}