mixdog 0.9.67 → 0.9.69

package/src/session-runtime/runtime-tunables.mjs

@@ -0,0 +1,57 @@
+// Env-tunable boot timings and feature gates for the session runtime, lifted
+// out of runtime-core so the facade reads as wiring instead of a wall of
+// knobs. Values are read ONCE per runtime construction: a mid-session env
+// change must not retune a schedule that is already armed.
+import { envDelayMs, envFlag, envPresent } from './env.mjs';
+
+export function readRuntimeTunables() {
+  const codeGraphPrewarmEnabled = !envFlag('MIXDOG_DISABLE_CODE_GRAPH_PREWARM');
+  return {
+    sessionPrewarmDelayMs: envDelayMs('MIXDOG_SESSION_PREWARM_DELAY_MS', 50, { min: 0, max: 10_000 }),
+    providerSetupWarmupDelayMs: envDelayMs('MIXDOG_PROVIDER_SETUP_WARMUP_DELAY_MS', 300, { min: 0, max: 60_000 }),
+    modelCatalogWarmupDelayMs: envDelayMs('MIXDOG_MODEL_CATALOG_WARMUP_DELAY_MS', 200, { min: 0, max: 60_000 }),
+    providerWarmupDelayMs: envDelayMs('MIXDOG_PROVIDER_WARMUP_DELAY_MS', 1_500, { min: 0, max: 60_000 }),
+    // Background model-catalog prefetch delay. Kept short so the first `/model`
+    // open finds a warm cache instead of paying a cold full network load. The
+    // work is async + unref'd, so short-lived detached runtimes still exit
+    // cleanly without waiting on it. Operators can raise it via env if a
+    // detached runtime must avoid the /models round-trip entirely.
+    providerModelWarmupDelayMs: envDelayMs('MIXDOG_PROVIDER_MODEL_WARMUP_DELAY_MS', 2_000, { min: 0, max: 120_000 }),
+    codeGraphPrewarmDelayMs: envDelayMs('MIXDOG_CODE_GRAPH_PREWARM_DELAY_MS', 250, { min: 0, max: 60_000 }),
+    statuslineUsageWarmupDelayMs: envDelayMs('MIXDOG_STATUSLINE_USAGE_WARMUP_DELAY_MS', 800, { min: 0, max: 60_000 }),
+    // Idle keep-alive: re-fetch usage before the statusline's 10-min staleness
+    // cut (LIVE_USAGE_SNAPSHOT_MAX_AGE_MS) so the usage segment does not
+    // disappear while the session sits idle with no turns to trigger a refresh.
+    statuslineUsageRefreshDelayMs: envDelayMs('MIXDOG_STATUSLINE_USAGE_REFRESH_MS', 240_000, { min: 30_000, max: 540_000 }),
+    channelStartDelayMs: envDelayMs('MIXDOG_CHANNEL_START_DELAY_MS', 10_000, { min: 0, max: 120_000 }),
+    backgroundBusyRetryMs: envDelayMs('MIXDOG_BACKGROUND_BUSY_RETRY_MS', 1_000, { min: 50, max: 10_000 }),
+    // Boot-time remote start is deferred past the first frame; see the caller.
+    remoteAutoStartDelayMs: envDelayMs('MIXDOG_REMOTE_AUTOSTART_DELAY_MS', 1_500, { min: 0, max: 60_000 }),
+    sessionPrewarmEnabled: !envFlag('MIXDOG_DISABLE_SESSION_PREWARM')
+      && (envFlag('MIXDOG_ENABLE_SESSION_PREWARM') || envPresent('MIXDOG_SESSION_PREWARM_DELAY_MS')),
+    providerWarmupEnabled: !envFlag('MIXDOG_DISABLE_PROVIDER_WARMUP')
+      && (
+        envFlag('MIXDOG_ENABLE_PROVIDER_WARMUP')
+        || envFlag('MIXDOG_PROVIDER_WARMUP_BEFORE_FIRST_TURN')
+        || envPresent('MIXDOG_PROVIDER_WARMUP_DELAY_MS')
+        || envPresent('MIXDOG_PROVIDER_MODEL_WARMUP_DELAY_MS')
+      ),
+    // Boot-time model-catalog prefetch is intentionally decoupled from the
+    // heavier providerWarmupEnabled gate (which stays opt-in for provider
+    // *init* side effects). Fetching the model list in the background after a
+    // short delay is cheap, fire-and-forget and unref'd, so it is ON by
+    // default — otherwise the FIRST `/model` open always paid a cold full
+    // network load. Operators can still disable it explicitly.
+    modelPrefetchEnabled: !envFlag('MIXDOG_DISABLE_PROVIDER_WARMUP')
+      && !envFlag('MIXDOG_DISABLE_MODEL_PREFETCH'),
+    codeGraphPrewarmEnabled,
+    modelCatalogWarmupEnabled: !envFlag('MIXDOG_DISABLE_MODEL_CATALOG_WARMUP'),
+    // Lazy code-graph prewarm (default ON): do NOT prewarm at startup / on cwd
+    // change — that fired ~250ms after the first frame and, in a large tree,
+    // burned a worker (and felt like a freeze) before the user did anything.
+    // Instead prewarm ONCE on the first real turn, when a code lookup is
+    // actually imminent. MIXDOG_CODE_GRAPH_PREWARM_EAGER=1 restores the old
+    // eager behavior.
+    codeGraphPrewarmLazy: codeGraphPrewarmEnabled && !envFlag('MIXDOG_CODE_GRAPH_PREWARM_EAGER'),
+  };
+}

package/src/session-runtime/self-update.mjs

@@ -0,0 +1,129 @@
+// Self-update controller: registry version check + background staging of the
+// next version. Extracted from runtime-core so the runtime facade owns wiring
+// only. State is per-runtime and in-memory; the 24h TTL lives in the shared
+// update-checker cache.
+import {
+  checkLatestVersion,
+  isDevInstall,
+} from '../runtime/shared/update-checker.mjs';
+import {
+  spawnStagedInstall,
+  runStagedInstall,
+  isStagedComplete,
+} from '../runtime/shared/staged-update.mjs';
+
+const STAGE_POLL_MS = 3_000;
+const STAGE_POLL_MAX_MS = 10 * 60 * 1000;
+
+export function createSelfUpdateController({ getConfig, getDataDir, emitNotification }) {
+  let checkState = {
+    currentVersion: null,
+    latestVersion: null,
+    updateAvailable: false,
+    lastCheckedAt: 0,
+  };
+  // phase: 'idle' | 'checking' | 'installing' | 'installed' | 'failed'
+  let processState = { phase: 'idle', version: null, error: null };
+
+  function autoUpdateEnabled() {
+    return getConfig()?.update?.auto !== false;
+  }
+
+  async function checkForUpdate({ force = false } = {}) {
+    if (processState.phase !== 'installing') processState.phase = 'checking';
+    try {
+      const result = await checkLatestVersion({ force, dataDir: getDataDir() });
+      checkState = {
+        currentVersion: result.currentVersion,
+        latestVersion: result.latestVersion,
+        updateAvailable: result.updateAvailable,
+        lastCheckedAt: result.lastCheckedAt,
+      };
+    } catch {
+      // checkLatestVersion() is already silent-safe; this catch is belt-and-
+      // braces so a boot-time call can never crash the runtime.
+    } finally {
+      if (processState.phase === 'checking') processState.phase = 'idle';
+    }
+    return checkState;
+  }
+
+  async function runUpdateNow() {
+    if (processState.phase === 'installing') {
+      return { ...processState, alreadyInstalling: true, error: 'update already in progress' };
+    }
+    if (isDevInstall()) {
+      processState = { phase: 'failed', version: null, error: 'dev install — update skipped' };
+      return processState;
+    }
+    const ver = checkState.latestVersion;
+    if (!ver || !checkState.updateAvailable) {
+      processState = { phase: 'idle', version: null, error: null };
+      return { ...processState, error: 'no update available' };
+    }
+    // "Update now" stages the new version (verified, self-contained) rather than
+    // installing over the live global dir; the swap applies on the next launch.
+    // phase 'installed' here means "staged & ready — restart to apply".
+    processState = { phase: 'installing', version: ver, error: null };
+    try {
+      const result = await runStagedInstall(ver);
+      processState = result?.ok
+        ? { phase: 'installed', version: result.version || ver, error: null }
+        : { phase: 'failed', version: null, error: result?.error || 'update failed' };
+    } catch (err) {
+      processState = { phase: 'failed', version: null, error: err?.message || String(err) };
+    }
+    return processState;
+  }
+
+  // Non-blocking boot hook: the caller defers it past the synchronous runtime
+  // construction, so a slow/hanging registry request can never delay boot. The
+  // check ALWAYS runs (it populates the maintenance picker), but an available
+  // update only kicks off a hidden BACKGROUND staging install; the swap into
+  // the global dir happens on the next clean launch (cli.mjs pre-import), so
+  // npm never overwrites files this live process holds. force:true — the 24h
+  // disk cache went stale-visible (it kept reporting an older "latest" than the
+  // installed version); checkLatestVersion still falls back to it offline.
+  // isDevInstall(): a git checkout must never self-update.
+  function startBootCheck() {
+    const timer = setTimeout(() => {
+      void (async () => {
+        await checkForUpdate({ force: true });
+        if (!(autoUpdateEnabled() && !isDevInstall() && checkState.updateAvailable)) return;
+        const ver = checkState.latestVersion;
+        if (!ver) return;
+        // The notice fires ONLY once staging completed (a ready-to-apply package
+        // sits on disk) — never upfront — so no "update available" nag runs
+        // while the background stage does.
+        const announceReady = () => {
+          emitNotification('update ready', { kind: 'update-notice', version: ver, tone: 'info' });
+        };
+        if (isStagedComplete(ver)) { announceReady(); return; }
+        try { spawnStagedInstall(ver); } catch { /* best-effort background stage */ }
+        // Poll for completion, then announce once. Unref'd so it never holds the
+        // process open; gives up silently after the cap (next launch retries).
+        const startedAt = Date.now();
+        const poll = setInterval(() => {
+          if (isStagedComplete(ver)) {
+            clearInterval(poll);
+            announceReady();
+          } else if (Date.now() - startedAt > STAGE_POLL_MAX_MS) {
+            clearInterval(poll);
+          }
+        }, STAGE_POLL_MS);
+        poll.unref?.();
+      })().catch(() => {});
+    }, 0);
+    timer.unref?.();
+    return timer;
+  }
+
+  return {
+    autoUpdateEnabled,
+    checkForUpdate,
+    runUpdateNow,
+    getCheckState: () => checkState,
+    getProcessState: () => processState,
+    startBootCheck,
+  };
+}

package/src/session-runtime/skills-api.mjs

@@ -0,0 +1,77 @@
+// Skill surface (status listing, resource load, tool envelope, project skill
+// creation). Extracted from runtime-core so the facade only wires the mutable
+// cwd and the context module into it.
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { clean } from './session-text.mjs';
+
+const SKILL_TEMPLATE = (name, description) => [
+  '---',
+  `name: ${name}`,
+  `description: ${description}`,
+  '---',
+  '',
+  '# Instructions',
+  '',
+  'Describe when and how to use this skill.',
+  '',
+].join('\n');
+
+export function createSkillsApi({ contextMod, getCwd }) {
+  function skillsStatus() {
+    const cwd = getCwd();
+    const skills = typeof contextMod.collectSkillsCached === 'function'
+      ? contextMod.collectSkillsCached(cwd)
+      : [];
+    const norm = (value) => String(value || '').replace(/\\/g, '/').toLowerCase();
+    const cwdNorm = norm(cwd);
+    // A skill under <cwd>/.mixdog/skills is project-scoped; everything else
+    // comes from the user/global tree.
+    const sourceForSkill = (filePath) => (
+      cwdNorm && norm(filePath).startsWith(`${cwdNorm}/.mixdog/skills/`) ? 'project' : 'skill'
+    );
+    return {
+      cwd,
+      count: skills.length,
+      skills: skills.map((skill) => ({
+        name: skill.name,
+        description: skill.description || '',
+        filePath: skill.filePath || null,
+        source: sourceForSkill(skill.filePath),
+      })),
+    };
+  }
+
+  function skillContent(name) {
+    const res = typeof contextMod.loadSkillResource === 'function'
+      ? contextMod.loadSkillResource(name, getCwd())
+      : null;
+    if (!res) throw new Error(`skill not found: ${name}`);
+    return { name, content: res.content, dir: res.dir };
+  }
+
+  function skillToolContent(name) {
+    if (typeof contextMod.isSkillDisabled === 'function' && contextMod.isSkillDisabled(name)) {
+      const label = String(name || '').trim() || 'skill';
+      return `Error: skill "${label}" is disabled`;
+    }
+    const skill = skillContent(name);
+    // The general tool envelope keeps the main/Lead session identical to agent
+    // loops: the model-visible tool_result is the short stub and the SKILL.md
+    // body is delivered ONCE as a separate injected user message.
+    return contextMod.buildSkillToolEnvelope(skill.name, skill.content, skill.dir);
+  }
+
+  function addProjectSkill(input = {}) {
+    const name = clean(input.name).replace(/[^a-zA-Z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!name) throw new Error('skill name is required');
+    const dir = join(getCwd(), '.mixdog', 'skills', name);
+    const filePath = join(dir, 'SKILL.md');
+    if (existsSync(filePath)) throw new Error(`skill already exists: ${name}`);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, SKILL_TEMPLATE(name, clean(input.description) || 'Project skill.'), 'utf8');
+    return { name, filePath };
+  }
+
+  return { skillsStatus, skillContent, skillToolContent, addProjectSkill };
+}

package/src/session-runtime/tool-surface.mjs

@@ -0,0 +1,83 @@
+// Lead tool surface: which tools the model sees before a session exists, and
+// how that pre-session selection is replayed once one does. Extracted from
+// runtime-core, which keeps the mutable session/route/mode it injects here.
+import {
+  applyDeferredToolSurface,
+  filterDisallowedTools,
+  selectDeferredTools,
+} from './tool-catalog.mjs';
+import { LEAD_DISALLOWED_TOOLS } from './tool-defs.mjs';
+import { deferredSurfaceModeForLead, toolSpecForMode } from './effort.mjs';
+
+export function createToolSurface({
+  mgr,
+  mode,
+  standaloneTools,
+  agentToolNames,
+  getSession,
+  getRoute,
+  getConfig,
+  cfgMod,
+  loadWorkflowPack,
+  activeWorkflowId,
+  dataDir,
+}) {
+  let preSessionSurface = null;
+
+  // A workflow that delegates to NOBODY must not advertise the agent tool: a
+  // schema-visible tool policy always rejects is a guaranteed error turn.
+  function workflowAllowsAgents() {
+    try {
+      const pack = loadWorkflowPack(cfgMod.getPluginData?.() || dataDir, activeWorkflowId(getConfig()));
+      if (!pack || pack.agentsConfigured !== true) return true;
+      return Array.isArray(pack.agents) && pack.agents.length > 0;
+    } catch {
+      return true;
+    }
+  }
+
+  function modelStandaloneTools() {
+    return workflowAllowsAgents()
+      ? standaloneTools
+      : standaloneTools.filter((tool) => !agentToolNames.has(String(tool?.name || '')));
+  }
+
+  function buildPreSessionSurface() {
+    const previewTools = typeof mgr.previewSessionTools === 'function'
+      ? mgr.previewSessionTools(toolSpecForMode(mode), [])
+      : [];
+    const tools = filterDisallowedTools(previewTools, LEAD_DISALLOWED_TOOLS);
+    const surface = { tools: Array.isArray(tools) ? tools.slice() : [] };
+    applyDeferredToolSurface(surface, deferredSurfaceModeForLead(mode), modelStandaloneTools(), {
+      provider: getRoute().provider,
+    });
+    return surface;
+  }
+
+  return {
+    modelStandaloneTools,
+    invalidatePreSessionToolSurface() {
+      preSessionSurface = null;
+    },
+    /** The live session once it exists; the preview surface until then. */
+    activeToolSurface() {
+      const session = getSession();
+      if (session) return session;
+      preSessionSurface ??= buildPreSessionSurface();
+      return preSessionSurface;
+    },
+    /** Replay deferred tools the model loaded before the session existed. */
+    applyPreSessionToolSelection() {
+      const session = getSession();
+      if (!session || !preSessionSurface) return;
+      const selected = Array.isArray(preSessionSurface.deferredSelectedTools)
+        ? preSessionSurface.deferredSelectedTools
+        : [];
+      const discovered = Array.isArray(preSessionSurface.deferredDiscoveredTools)
+        ? preSessionSurface.deferredDiscoveredTools
+        : [];
+      const replay = [...new Set([...selected, ...discovered])];
+      if (replay.length) selectDeferredTools(session, replay, deferredSurfaceModeForLead(mode));
+    },
+  };
+}

package/src/session-runtime/workflow-agents-api.mjs

@@ -1,5 +1,9 @@
+import { join } from 'node:path';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { clean, hasOwn, sessionHasConversationMessages, tombstoneOnClose } from './session-text.mjs';
 import { isKnownProvider } from '../standalone/provider-admin.mjs';
+import { serializeFrontmatterDoc } from '../runtime/shared/markdown-frontmatter.mjs';
+import { isHiddenAgent } from '../runtime/agent/orchestrator/internal-agents.mjs';
 import {
   normalizeWorkflowRoute,
   upsertWorkflowPreset,
@@ -9,8 +13,12 @@ import {
   agentPresetSlot,
   normalizeAgentId,
   normalizeWorkflowId,
+  workflowIdFromName,
+  availableWorkflowId,
+  availableAgentId,
   DEFAULT_WORKFLOW_ID,
   normalizeSearchRouteConfig,
+  clearAgentDefinitionCache,
 } from './workflow.mjs';
 import { ONBOARDING_VERSION } from './quick-search-models.mjs';
 import { findOutputStyle } from './output-styles.mjs';
@@ -27,7 +35,7 @@ export function createWorkflowAgentsApi(deps) {
     cfgMod, reg, mgr, STANDALONE_DATA_DIR,
     resolveRoute, lookupModelMeta, adoptConfig, saveConfigAndAdopt, displayConfig, ensureProvidersReady,
     agentRouteFromConfig, loadAgentDefinition, activeWorkflowId, listWorkflowPacks,
-    loadWorkflowPack, workflowSummary,
+    loadWorkflowPack, workflowSummary, listCustomAgentIds,
     getOutputStyleStatusCached, seedOutputStyleStatusCache, scheduleOutputStyleSave,
     recreateCurrentSessionIfReady, notifyFnForSession, invalidateContextStatusCache,
   } = deps;
@@ -124,12 +132,28 @@ export function createWorkflowAgentsApi(deps) {
     listAgents() {
       const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
       const config = getConfig();
-      return FIXED_AGENT_SLOTS.map((agent) => ({
+      const fixed = FIXED_AGENT_SLOTS.map((agent) => ({
         ...agent,
         locked: true,
+        userOverride: existsSync(join(dataDir, 'agents', agent.id, 'AGENT.md')),
         route: agentRouteFromConfig(config, agent.id, dataDir),
         definition: loadAgentDefinition(dataDir, agent.id),
       }));
+      // Custom agents (user-authored roles): discovered from agents/<id>/
+      // AGENT.md directories beyond the fixed slots.
+      const custom = (listCustomAgentIds?.(dataDir) || []).map((id) => {
+        const definition = loadAgentDefinition(dataDir, id);
+        return {
+          id,
+          label: definition?.name || id,
+          description: definition?.description || '',
+          custom: true,
+          userOverride: existsSync(join(dataDir, 'agents', id, 'AGENT.md')),
+          route: agentRouteFromConfig(config, id, dataDir),
+          definition,
+        };
+      });
+      return [...fixed, ...custom];
     },
     listWorkflows() {
       const currentConfig = displayConfig();
@@ -200,9 +224,188 @@ export function createWorkflowAgentsApi(deps) {
       saveConfigAndAdopt(nextConfig);
       return workflowSummary(pack);
     },
+    // Workflow editor surface (desktop Workflows page): full pack read/write.
+    // User packs live at <dataDir>/workflows/<id>/WORKFLOW.md; saving a
+    // built-in id writes a user override, deleting the override reverts it.
+    getWorkflowPack(workflowId) {
+      const id = normalizeWorkflowId(workflowId, '');
+      if (!id) throw new Error(`unknown workflow "${workflowId}"`);
+      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
+      const pack = loadWorkflowPack(dataDir, id);
+      if (!pack || pack.id !== id) throw new Error(`workflow "${workflowId}" not found`);
+      return {
+        id: pack.id,
+        name: pack.name,
+        description: pack.description,
+        source: pack.source,
+        agentsConfigured: pack.agentsConfigured === true,
+        agents: pack.agents,
+        body: pack.body,
+        userOverride: existsSync(join(dataDir, 'workflows', id, 'WORKFLOW.md')),
+      };
+    },
+    async saveWorkflowPack(payload = {}) {
+      const id = normalizeWorkflowId(payload.id, '');
+      if (!id) throw new Error('workflow id must contain letters/numbers (dashes and dots allowed)');
+      const body = String(payload.body || '').trim();
+      if (!body) throw new Error('WORKFLOW.md body must not be empty');
+      // Frontmatter values are single-line by format; collapse any newlines.
+      const oneLine = (value) => clean(value).replace(/\s+/g, ' ');
+      const name = oneLine(payload.name) || id;
+      const description = oneLine(payload.description);
+      // agents: null/absent keeps the pack on "all agents" (no frontmatter key).
+      const agents = Array.isArray(payload.agents)
+        ? [...new Set(payload.agents
+            .map((agent) => normalizeAgentId(agent) || normalizeWorkflowId(agent))
+            .filter(Boolean))]
+        : null;
+      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
+      const dir = join(dataDir, 'workflows', id);
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, 'WORKFLOW.md'), serializeFrontmatterDoc({
+        id,
+        name,
+        ...(description ? { description } : {}),
+        ...(agents ? { agents: agents.join(', ') } : {}),
+      }, body));
+      return this.getWorkflowPack(id);
+    },
+    async createWorkflow(payload = {}) {
+      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
+      const name = clean(payload.name).replace(/\s+/g, ' ');
+      if (!name) throw new Error('workflow name must not be empty');
+      const requestedId = normalizeWorkflowId(payload.id, '');
+      if (requestedId) {
+        const existing = loadWorkflowPack(dataDir, requestedId);
+        if (existing && existing.id === requestedId) throw new Error(`workflow "${requestedId}" already exists`);
+        return this.saveWorkflowPack({ ...payload, id: requestedId, name });
+      }
+      const id = availableWorkflowId(workflowIdFromName(name), (candidate) => {
+        const existing = loadWorkflowPack(dataDir, candidate);
+        return Boolean(existing && existing.id === candidate);
+      });
+      return this.saveWorkflowPack({ ...payload, id, name });
+    },
+    async deleteWorkflow(workflowId) {
+      const id = normalizeWorkflowId(workflowId, '');
+      if (!id) throw new Error(`unknown workflow "${workflowId}"`);
+      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
+      const pack = loadWorkflowPack(dataDir, id);
+      if (!pack || pack.id !== id) throw new Error(`workflow "${id}" not found`);
+      const dir = join(dataDir, 'workflows', id);
+      if (!existsSync(join(dir, 'WORKFLOW.md'))) {
+        throw new Error(`workflow "${id}" is built-in and cannot be deleted`);
+      }
+      rmSync(dir, { recursive: true, force: true });
+      const remaining = loadWorkflowPack(dataDir, id);
+      const revertedToBuiltIn = Boolean(remaining && remaining.id === id);
+      // A fully-removed pack must not stay active; fall back to Default.
+      if (!revertedToBuiltIn && activeWorkflowId(getConfig()) === id) {
+        const nextConfig = { ...getConfig() };
+        nextConfig.workflow = { ...(nextConfig.workflow || {}), active: DEFAULT_WORKFLOW_ID };
+        saveConfigAndAdopt(nextConfig);
+      }
+      return { id, deleted: true, revertedToBuiltIn };
+    },
+    // Agent editor surface (desktop Workflows page): the fixed roles stay
+    // built-in; custom agents are user-authored under <dataDir>/agents/<id>/.
+    getAgentDefinition(agentId) {
+      const id = normalizeAgentId(agentId) || normalizeWorkflowId(agentId);
+      if (!id) throw new Error(`unknown agent "${agentId}"`);
+      // Internal hidden roles (scheduler-task, webhook-handler, …) are
+      // Mixdog-managed and never editable through the agent surface.
+      if (isHiddenAgent(id)) throw new Error(`agent "${id}" is internal and cannot be edited`);
+      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
+      const definition = loadAgentDefinition(dataDir, id);
+      if (!definition) throw new Error(`agent "${agentId}" not found`);
+      return {
+        id,
+        name: definition.name,
+        description: definition.description,
+        body: definition.body,
+        custom: !FIXED_AGENT_SLOTS.some((agent) => agent.id === id),
+        userOverride: existsSync(join(dataDir, 'agents', id, 'AGENT.md')),
+        route: agentRouteFromConfig(getConfig(), id, dataDir),
+      };
+    },
+    async saveAgentDefinition(payload = {}) {
+      const body = String(payload.body || '').trim();
+      if (!body) throw new Error('AGENT.md body must not be empty');
+      const oneLine = (value) => clean(value).replace(/\s+/g, ' ');
+      const requestedId = clean(payload.id);
+      let id = normalizeAgentId(requestedId) || normalizeWorkflowId(requestedId);
+      if (hasOwn(payload, 'id') && !id) {
+        throw new Error('agent id must contain letters/numbers (dashes and dots allowed)');
+      }
+      if (id && isHiddenAgent(id)) throw new Error(`agent "${id}" is internal and cannot be edited`);
+      const name = oneLine(payload.name);
+      if (!name && !id) throw new Error('agent name must not be empty');
+      const description = oneLine(payload.description);
+      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
+      if (!id) {
+        id = availableAgentId(name, (candidate) => Boolean(loadAgentDefinition(dataDir, candidate)));
+      }
+      const dir = join(dataDir, 'agents', id);
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, 'AGENT.md'), serializeFrontmatterDoc({
+        name: name || id,
+        ...(description ? { description } : {}),
+      }, body));
+      // loadAgentDefinition prefers the manifest for name/description.
+      writeFileSync(join(dir, 'agent.json'), `${JSON.stringify({
+        name: name || id,
+        ...(description ? { description } : {}),
+      }, null, 2)}\n`);
+      clearAgentDefinitionCache(id);
+      if (payload.route) {
+        await this.setAgentRoute(id, payload.route);
+      } else if (!FIXED_AGENT_SLOTS.some((agent) => agent.id === id)
+        && !agentRouteFromConfig(getConfig(), id, dataDir)) {
+        // Custom roles have no built-in preset fallback, so a model-less save
+        // would spawn as `agent "<id>" has no model assignment`. Seed the
+        // current default route; an unconfigured install just stays routeless.
+        try { await this.setAgentRoute(id, {}); } catch { /* no default route yet */ }
+      }
+      return this.getAgentDefinition(id);
+    },
+    async deleteAgentDefinition(agentId) {
+      const id = normalizeAgentId(agentId) || normalizeWorkflowId(agentId);
+      if (!id) throw new Error(`unknown agent "${agentId}"`);
+      if (isHiddenAgent(id)) throw new Error(`agent "${id}" is internal and cannot be deleted`);
+      const builtIn = FIXED_AGENT_SLOTS.some((agent) => agent.id === id);
+      const dataDir = cfgMod.getPluginData?.() || STANDALONE_DATA_DIR;
+      const dir = join(dataDir, 'agents', id);
+      // Built-in roles are never removed: dropping their user override reverts
+      // the role to the shipped AGENT.md, mirroring workflow-pack deletes.
+      if (!existsSync(join(dir, 'AGENT.md'))) {
+        throw new Error(builtIn
+          ? `agent "${id}" has no user override to reset`
+          : `agent "${id}" not found`);
+      }
+      rmSync(dir, { recursive: true, force: true });
+      clearAgentDefinitionCache(id);
+      const revertedToBuiltIn = Boolean(loadAgentDefinition(dataDir, id));
+      // A fully-removed custom agent must not leave a dangling route/preset.
+      if (!revertedToBuiltIn) {
+        const nextConfig = { ...getConfig() };
+        if (nextConfig.agents && id in nextConfig.agents) {
+          const agents = { ...nextConfig.agents };
+          delete agents[id];
+          nextConfig.agents = agents;
+        }
+        const presetId = workflowPresetId(agentPresetSlot(id));
+        nextConfig.presets = (Array.isArray(nextConfig.presets) ? nextConfig.presets : [])
+          .filter((preset) => clean(preset?.id) !== presetId);
+        saveConfigAndAdopt(nextConfig);
+      }
+      return { id, deleted: true, revertedToBuiltIn };
+    },
     async setAgentRoute(agentId, next) {
-      const id = normalizeAgentId(agentId);
+      // Custom agents keep their workflow-style id; routes persist in
+      // config.agents[<id>] exactly like the fixed roles.
+      const id = normalizeAgentId(agentId) || normalizeWorkflowId(agentId);
       if (!id) throw new Error(`unknown agent "${agentId}"`);
+      if (isHiddenAgent(id)) throw new Error(`agent "${id}" is internal and has no configurable route`);
       let selectedRoute = resolveRoute(getConfig(), { ...(next || {}) });
       await ensureProvidersReady(ensureProviderEnabled(getConfig(), selectedRoute.provider));
       const modelMeta = await lookupModelMeta(selectedRoute.provider, selectedRoute.model);