mixdog 0.9.3 → 0.9.4

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

@@ -20,12 +20,9 @@ export const MEASURED_TOOL_USAGE = Object.freeze({
   agent: 330,
   shell: 81,
   cwd: 2,
-  diagnostics: 2,
   recall: 2,
   search: 2,
   web_fetch: 2,
-  provider_status: 2,
-  channel_status: 2,
 });
 const MEASURED_TOOL_ORDER = Object.freeze(Object.keys(MEASURED_TOOL_USAGE));
 export const DEFERRED_DEFAULT_FULL_TOOLS = Object.freeze([
@@ -81,9 +78,6 @@ const READONLY_TOOL_NAMES = new Set([
   'web_fetch',
   'recall',
   'memory',
-  'provider_status',
-  'channel_status',
-  'schedule_status',
   'fetch',
   'Skill',
 ]);
@@ -92,13 +86,8 @@ const DEFERRED_SELECT_ALIASES = {
   search: ['search', 'web_fetch'],
   web: ['web_fetch', 'search'],
   memory: ['memory', 'recall'],
-  channels: ['reply', 'fetch', 'react', 'edit_message', 'download_attachment', 'schedule_status', 'trigger_schedule', 'schedule_control', 'reload_config'],
-  discord: ['reply', 'fetch', 'react', 'edit_message', 'download_attachment'],
-  providers: ['provider_status'],
-  provider: ['provider_status'],
-  status: ['provider_status', 'channel_status', 'schedule_status'],
-  schedule: ['schedule_status', 'trigger_schedule', 'schedule_control'],
-  channel: ['channel_status'],
+  channels: ['reply', 'fetch'],
+  discord: ['reply', 'fetch'],
   explore: ['explore'],
   discovery: ['explore'],
   agent: ['agent'],
@@ -111,10 +100,6 @@ const TOOL_SEARCH_SAFE_AUTO_ALIASES = new Set([
   'web',
   'search',
   'agent',
-  'provider',
-  'providers',
-  'channel',
-  'schedule',
   'memory',
 ]);
 const TOOL_SEARCH_AMBIGUOUS_AUTO_QUERIES = new Set([
@@ -152,12 +137,9 @@ const TOOL_SEARCH_STOP_WORDS = new Set([
 ]);
 const TOOL_SEARCH_ROW_ALIASES = Object.freeze({
   agent: ['delegate', 'subagent', 'worker', 'parallel agent', 'background agent', 'reviewer', 'explorer'],
-  channel_status: ['channel status', 'discord status', 'channel config'],
   cwd: ['cwd', 'working directory', 'current directory', 'project root', 'folder'],
   memory: ['save memory', 'store memory', 'delete memory', 'forget memory', 'memory status'],
-  provider_status: ['provider status', 'auth status', 'model status', 'oauth status', 'provider config'],
   recall: ['recall', 'previous work', 'past work', 'prior context', 'history', 'resume context'],
-  schedule_status: ['schedule status', 'cron status'],
   search: ['web search', 'internet search', 'current info', 'latest info', 'online search', 'docs search'],
   shell: ['run command', 'execute command', 'terminal', 'powershell', 'bash', 'run tests', 'test command', 'build command', 'npm', 'node', 'git'],
   task: ['background task', 'async task', 'wait task', 'cancel task', 'task status'],
@@ -690,15 +672,33 @@ export function renderToolSearch(args = {}, session, mode = 'full') {
     ? autoToolSelectionNames(query, initialRows)
     : [];
   const selectedNames = forcedSelectedNames.length ? forcedSelectedNames : autoSelectedNames;
-  const toolSelection = selectedNames.length ? selectDeferredTools(session, selectedNames, mode) : null;
-  const selectionMode = forcedSelectedNames.length ? 'select' : (autoSelectedNames.length ? 'auto' : null);
-  const nextActiveNames = new Set((session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean));
-  const rows = [
-    ...catalog.map((tool) => toolRow(tool, nextActiveNames)),
-  ].filter((row) => row.name);
-  const matches = query
+  let toolSelection = selectedNames.length ? selectDeferredTools(session, selectedNames, mode) : null;
+  let selectionMode = forcedSelectedNames.length ? 'select' : (autoSelectedNames.length ? 'auto' : null);
+  let nextActiveNames = new Set((session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean));
+  let rows = catalog.map((tool) => toolRow(tool, nextActiveNames)).filter((row) => row.name);
+  let matches = query
     ? rankedToolSearchRows(rows, query)
     : rows;
+  // Query hits must become loadable without a second explicit select turn:
+  // if the query produced ranked matches but the forced/auto path above
+  // loaded nothing (no exact-name/alias/category hit), fall back to
+  // auto-loading the ranked match names themselves (deferred/non-active
+  // only, capped at `limit`). Ambiguous queries stay excluded so a guess
+  // never silently loads a wrong category.
+  const STRONG_MATCH_REASONS = new Set(['exact-name', 'exact-alias', 'alias-phrase', 'phrase', 'all-tokens']);
+  const isStrongMatch = (row) => row.score >= 24 || (row.reasons || []).some((reason) => STRONG_MATCH_REASONS.has(reason));
+  const queryLoadedNothing = !toolSelection
+    || (!toolSelection.added.length && !toolSelection.already.length);
+  if (query && !TOOL_SEARCH_AMBIGUOUS_AUTO_QUERIES.has(query) && matches.length && queryLoadedNothing) {
+    const fallbackNames = matches.filter((row) => !row.active && isStrongMatch(row)).map((row) => row.name).slice(0, limit);
+    if (fallbackNames.length) {
+      toolSelection = selectDeferredTools(session, fallbackNames, mode);
+      selectionMode = 'query';
+      nextActiveNames = new Set((session?.tools || []).map((tool) => clean(tool?.name)).filter(Boolean));
+      rows = catalog.map((tool) => toolRow(tool, nextActiveNames)).filter((row) => row.name);
+      matches = query ? rankedToolSearchRows(rows, query) : rows;
+    }
+  }
   const selected = toolSelection
     ? {
         mode: selectionMode,
@@ -706,7 +706,7 @@ export function renderToolSearch(args = {}, session, mode = 'full') {
       }
     : null;
   const nativeToolSearch = toolSelection?.native
-    ? toolSearchNativePayload(catalog, toolSelection.added, session?.provider)
+    ? toolSearchNativePayload(catalog, [...new Set([...toolSelection.added, ...(toolSelection.already || [])])], session?.provider)
     : null;
   return JSON.stringify({
     selected,
@@ -715,6 +715,6 @@ export function renderToolSearch(args = {}, session, mode = 'full') {
     matches: matches.slice(0, limit),
     activeTools: sortedNamesByMeasuredUsage(nextActiveNames),
     discoveredTools: sortedNamesByMeasuredUsage(session?.deferredDiscoveredTools || []),
-    note: 'query ranks matches and auto-loads high-confidence deferred tools; select exact tool names, or query select:a,b, to force load.',
+    note: 'query ranks matches and auto-loads high-confidence deferred tools, including ranked search hits (deferred, non-active) up to limit; already-loaded/discovered tools are re-surfaced on re-selection; select exact tool names, or query select:a,b, to force load.',
   }, null, 2);
 }

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

@@ -0,0 +1,84 @@
+// Standalone session tool definitions (wrapper tools surfaced by the runtime).
+// Pure, self-contained schemas + the agent-hidden default helper. Extracted
+// from mixdog-session-runtime.mjs; no runtime closure dependencies.
+
+export const TOOL_SEARCH_TOOL = {
+  name: 'tool_search',
+  title: 'Tool Search',
+  annotations: {
+    title: 'Tool Search',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    agentHidden: true,
+  },
+  description: 'Search deferred tools; confident queries load matches.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search text; confident hits load. select:a,b forces exact names.' },
+      select: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }], description: 'Force exact tool names.' },
+      limit: { type: 'number', description: 'Max matches.' },
+    },
+    additionalProperties: false,
+  },
+};
+
+export const CWD_TOOL = {
+  name: 'cwd',
+  title: 'Work Project',
+  annotations: {
+    title: 'Work Project',
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+    agentHidden: true,
+  },
+  description: 'Show or set the session work project for tool execution.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: { type: 'string', enum: ['get', 'set'], description: 'Default get.' },
+      path: { type: 'string', description: 'Project directory for set.' },
+    },
+    additionalProperties: false,
+  },
+};
+
+export const SKILL_TOOL = {
+  name: 'Skill',
+  title: 'Skill',
+  annotations: {
+    title: 'Skill',
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    agentHidden: false,
+  },
+  description: 'Load a named SKILL.md into context.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: 'Skill name.' },
+    },
+    required: ['name'],
+    additionalProperties: false,
+  },
+};
+
+export const LEAD_DISALLOWED_TOOLS = Object.freeze([]);
+export const AGENT_HIDDEN_WRAPPER_TOOLS = new Set([]);
+
+export function applyStandaloneToolDefaults(tool) {
+  if (!tool || !AGENT_HIDDEN_WRAPPER_TOOLS.has(tool.name)) return tool;
+  return {
+    ...tool,
+    annotations: {
+      ...(tool.annotations || {}),
+      agentHidden: true,
+    },
+  };
+}

package/src/session-runtime/warmup-schedulers.mjs

@@ -0,0 +1,201 @@
+// Background warmup/refresh schedulers, extracted from
+// mixdog-session-runtime.mjs. Dependency-injected factory: the timer handles
+// live in a caller-owned `timers` object (so the facade's clearTimeout teardown
+// still sees them) and all route/config/state reads go through supplied
+// accessors. Returns the schedule* functions plus a clearAll() teardown helper.
+import { performance } from 'node:perf_hooks';
+import { clean } from './session-text.mjs';
+
+export function createWarmupSchedulers({
+  timers,
+  bootProfile,
+  getRoute,
+  getConfig,
+  isCloseRequested,
+  getActiveTurnCount,
+  getSessionCreatePromise,
+  getProviderModelsCache,
+  getProviderModelsPromise,
+  reloadFullConfig,
+  ensureConfigForRouteProvider,
+  ensureProvidersReady,
+  ensureProviderEnabled,
+  refreshStatuslineUsageSnapshot,
+  warmProviderModelCache,
+  cachedProviderSetup,
+  warmCatalogsInBackground,
+  isFirstTurnCompleted,
+  envFlag,
+  delays,
+  flags,
+}) {
+  const {
+    providerWarmupDelayMs,
+    providerSetupWarmupDelayMs,
+    providerModelWarmupDelayMs,
+    modelCatalogWarmupDelayMs,
+    statuslineUsageWarmupDelayMs,
+    statuslineUsageRefreshDelayMs,
+    backgroundBusyRetryMs,
+  } = delays;
+  const {
+    providerWarmupEnabled,
+    modelPrefetchEnabled,
+    modelCatalogWarmupEnabled,
+  } = flags;
+
+  function scheduleProviderWarmup(delayMs = providerWarmupDelayMs) {
+    if (!providerWarmupEnabled) {
+      bootProfile('providers:warm-skipped');
+      return;
+    }
+    if (timers.providerWarmupTimer || isCloseRequested()) return;
+    timers.providerWarmupTimer = setTimeout(() => {
+      timers.providerWarmupTimer = null;
+      if (isCloseRequested()) return;
+      if (!isFirstTurnCompleted() && !envFlag('MIXDOG_PROVIDER_WARMUP_BEFORE_FIRST_TURN')) {
+        bootProfile('providers:warm-deferred', { reason: 'first-turn-pending' });
+        return;
+      }
+      if (getActiveTurnCount() > 0 || getSessionCreatePromise()) {
+        bootProfile('providers:warm-deferred', { reason: getActiveTurnCount() > 0 ? 'turn-active' : 'session-create' });
+        scheduleProviderWarmup(backgroundBusyRetryMs);
+        return;
+      }
+      const providersStartedAt = performance.now();
+      try {
+        reloadFullConfig();
+      } catch (error) {
+        bootProfile('config:full-failed', { error: error?.message || String(error) });
+      }
+      void ensureProvidersReady(getConfig().providers || {})
+        .then(() => {
+          bootProfile('providers:init:ready', { ms: (performance.now() - providersStartedAt).toFixed(1) });
+          if (isCloseRequested()) return null;
+          return true;
+        })
+        .catch((error) => bootProfile('providers:warm-failed', { error: error?.message || String(error) }));
+    }, delayMs);
+    timers.providerWarmupTimer.unref?.();
+  }
+
+  function scheduleProviderSetupWarmup(delayMs = providerSetupWarmupDelayMs) {
+    if (timers.providerSetupWarmupTimer || isCloseRequested()) return;
+    timers.providerSetupWarmupTimer = setTimeout(() => {
+      timers.providerSetupWarmupTimer = null;
+      if (isCloseRequested()) return;
+      void cachedProviderSetup()
+        .then(() => bootProfile('provider-setup:warm-ready'))
+        .catch((error) => bootProfile('provider-setup:warm-failed', { error: error?.message || String(error) }));
+    }, delayMs);
+    timers.providerSetupWarmupTimer.unref?.();
+  }
+
+  function scheduleProviderModelWarmup(delayMs = providerModelWarmupDelayMs) {
+    if (!modelPrefetchEnabled) return;
+    if (timers.providerModelWarmupTimer || isCloseRequested()) return;
+    timers.providerModelWarmupTimer = setTimeout(() => {
+      timers.providerModelWarmupTimer = null;
+      if (isCloseRequested() || Array.isArray(getProviderModelsCache().models) || getProviderModelsPromise()) return;
+      if (getActiveTurnCount() > 0 || getSessionCreatePromise()) {
+        bootProfile('provider-models:warm-deferred', { reason: getActiveTurnCount() > 0 ? 'turn-active' : 'session-create' });
+        scheduleProviderModelWarmup(backgroundBusyRetryMs);
+        return;
+      }
+      warmProviderModelCache();
+    }, delayMs);
+    timers.providerModelWarmupTimer.unref?.();
+  }
+
+  function scheduleModelCatalogWarmup(delayMs = modelCatalogWarmupDelayMs) {
+    if (!modelCatalogWarmupEnabled) {
+      bootProfile('model-catalog:warm-skipped', { reason: 'disabled' });
+      return;
+    }
+    if (timers.modelCatalogWarmupTimer || isCloseRequested()) return;
+    timers.modelCatalogWarmupTimer = setTimeout(() => {
+      timers.modelCatalogWarmupTimer = null;
+      if (isCloseRequested()) return;
+      if (getActiveTurnCount() > 0 || getSessionCreatePromise()) {
+        bootProfile('model-catalog:warm-deferred', { reason: getActiveTurnCount() > 0 ? 'turn-active' : 'session-create' });
+        scheduleModelCatalogWarmup(backgroundBusyRetryMs);
+        return;
+      }
+      void warmCatalogsInBackground()
+        .then(() => bootProfile('model-catalog:warm-ready'))
+        .catch((error) => bootProfile('model-catalog:warm-failed', { error: error?.message || String(error) }));
+    }, delayMs);
+    timers.modelCatalogWarmupTimer.unref?.();
+  }
+
+  function scheduleStatuslineUsageWarmup(delayMs = statuslineUsageWarmupDelayMs) {
+    const route = getRoute();
+    const providerId = clean(route?.provider);
+    if (!providerId || !providerId.includes('oauth')) {
+      bootProfile('statusline-usage:warm-skipped', { provider: providerId || null });
+      return;
+    }
+    if (timers.statuslineUsageWarmupTimer || isCloseRequested()) return;
+    timers.statuslineUsageWarmupTimer = setTimeout(async () => {
+      timers.statuslineUsageWarmupTimer = null;
+      if (isCloseRequested()) return;
+      if (getActiveTurnCount() > 0 || getSessionCreatePromise()) {
+        bootProfile('statusline-usage:warm-deferred', { reason: getActiveTurnCount() > 0 ? 'turn-active' : 'session-create' });
+        scheduleStatuslineUsageWarmup(backgroundBusyRetryMs);
+        return;
+      }
+      try {
+        ensureConfigForRouteProvider();
+        await ensureProvidersReady(ensureProviderEnabled(getConfig(), getRoute().provider));
+        if (isCloseRequested()) return;
+        refreshStatuslineUsageSnapshot(getRoute());
+        bootProfile('statusline-usage:warm-ready', { provider: clean(getRoute()?.provider) });
+      } catch (error) {
+        bootProfile('statusline-usage:warm-failed', { error: error?.message || String(error) });
+      } finally {
+        scheduleStatuslineUsageRefresh();
+      }
+    }, delayMs);
+    timers.statuslineUsageWarmupTimer.unref?.();
+  }
+
+  // Idle keep-alive loop: periodically re-fetch the OAuth usage snapshot so its
+  // cachedAt stays "live-fresh" and the statusline usage segment does not vanish
+  // after LIVE_USAGE_SNAPSHOT_MAX_AGE_MS while the session is idle. Turn-driven
+  // refreshes (recordStandaloneStatusTelemetry) already cover active sessions.
+  function scheduleStatuslineUsageRefresh(delayMs = statuslineUsageRefreshDelayMs) {
+    const route = getRoute();
+    const providerId = clean(route?.provider);
+    if (!providerId || !providerId.includes('oauth')) return;
+    if (timers.statuslineUsageRefreshTimer || isCloseRequested()) return;
+    timers.statuslineUsageRefreshTimer = setTimeout(async () => {
+      timers.statuslineUsageRefreshTimer = null;
+      if (isCloseRequested()) return;
+      if (getActiveTurnCount() > 0 || getSessionCreatePromise()) {
+        // Active turns refresh usage on their own; just re-arm the idle loop.
+        scheduleStatuslineUsageRefresh();
+        return;
+      }
+      try {
+        ensureConfigForRouteProvider();
+        await ensureProvidersReady(ensureProviderEnabled(getConfig(), getRoute().provider));
+        if (isCloseRequested()) return;
+        refreshStatuslineUsageSnapshot(getRoute());
+      } catch {
+        // Usage display must never affect the session runtime.
+      } finally {
+        scheduleStatuslineUsageRefresh();
+      }
+    }, delayMs);
+    timers.statuslineUsageRefreshTimer.unref?.();
+  }
+
+  return {
+    scheduleProviderWarmup,
+    scheduleProviderSetupWarmup,
+    scheduleProviderModelWarmup,
+    scheduleModelCatalogWarmup,
+    scheduleStatuslineUsageWarmup,
+    scheduleStatuslineUsageRefresh,
+  };
+}

package/src/standalone/agent-tool/helpers.mjs

@@ -0,0 +1,237 @@
+// Pure, dependency-light helpers extracted from the agent-tool facade. No
+// module-level mutable state lives here (the frontmatter perm cache and all
+// timers stay in the facade / their owner modules). Behavior-preserving:
+// function bodies are identical to the originals.
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import {
+  normalizeAgentPermissionOrNone,
+  parseMarkdownFrontmatter,
+} from '../../runtime/shared/markdown-frontmatter.mjs';
+import { clearGatewaySessionRoute, writeGatewaySessionRoute } from '../../vendor/statusline/src/gateway/session-routes.mjs';
+import { PRESET_ALIASES } from './tool-def.mjs';
+
+export function envTimeoutMs(name, fallback) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === '') return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+
+export function clean(value) {
+  return String(value ?? '').trim();
+}
+
+export function agentTagOf(session) {
+  return clean(session?.agentTag);
+}
+
+export function normalizeAgentName(value) {
+  const id = clean(value).toLowerCase().replace(/[\s_]+/g, '-');
+  if (id === 'explorer') return 'explore';
+  if (id === 'maint' || id === 'maintenance' || id === 'memory') return 'maintainer';
+  if (id === 'heavy' || id === 'heavyworker') return 'heavy-worker';
+  if (id === 'review') return 'reviewer';
+  if (id === 'debug') return 'debugger';
+  return id;
+}
+
+export function positiveInt(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+export function terminalPidForContext(context = {}) {
+  return positiveInt(context?.clientHostPid);
+}
+
+export function agentScope(args = {}, context = {}) {
+  const scope = clean(args.scope || args.terminal || args.term).toLowerCase();
+  if (args.allTerminals === true || scope === 'all' || scope === 'global') return {};
+  return context || {};
+}
+
+export function sessionMatchesContext(session, context = {}) {
+  const wantedPid = terminalPidForContext(context);
+  if (!wantedPid) return true;
+  const sessionPid = positiveInt(session?.clientHostPid);
+  return !!sessionPid && sessionPid === wantedPid;
+}
+
+export function rowMatchesContext(row, context = {}) {
+  const wantedPid = terminalPidForContext(context);
+  if (!wantedPid) return true;
+  const rowPid = positiveInt(row?.clientHostPid);
+  return !!rowPid && rowPid === wantedPid;
+}
+
+export function nonNegativeInt(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+
+export function presetKey(preset) {
+  return clean(preset?.id || preset?.name);
+}
+
+export function bridgeRouteForStatusline(preset = {}) {
+  const provider = clean(preset.provider);
+  const model = clean(preset.model);
+  if (!provider || !model) return null;
+  const out = {
+    mode: 'fixed',
+    defaultProvider: provider,
+    defaultModel: model,
+  };
+  const id = clean(preset.id);
+  const name = clean(preset.name);
+  const modelDisplay = clean(preset.modelDisplay || preset.display || preset.displayName);
+  const effort = clean(preset.effort);
+  if (id) out.presetId = id;
+  if (name) out.presetName = name;
+  if (modelDisplay) out.modelDisplay = modelDisplay;
+  if (effort) {
+    out.effort = effort;
+    out.displayEffort = effort;
+  }
+  if (preset.fast === true || preset.fast === false) out.fast = preset.fast;
+  return out;
+}
+
+export function writeAgentStatuslineRoute(sessionId, preset) {
+  const route = bridgeRouteForStatusline(preset);
+  if (!sessionId || !route) return false;
+  try { return writeGatewaySessionRoute(sessionId, route); } catch { return false; }
+}
+
+export function clearAgentStatuslineRoute(sessionId) {
+  if (!sessionId) return false;
+  try { return clearGatewaySessionRoute(sessionId); } catch { return false; }
+}
+
+export function findPreset(config, key) {
+  const wanted = clean(key).toLowerCase();
+  if (!wanted) return null;
+  const presets = Array.isArray(config?.presets) ? config.presets : [];
+  return presets.find((p) => {
+    return clean(p?.id).toLowerCase() === wanted || clean(p?.name).toLowerCase() === wanted;
+  }) || null;
+}
+
+export function synthesizePreset(config, key) {
+  const alias = PRESET_ALIASES.get(clean(key).toLowerCase());
+  if (!alias) return null;
+  const base = findPreset(config, alias.base);
+  if (!base) return null;
+  return {
+    ...base,
+    id: alias.id,
+    name: alias.name,
+    effort: alias.effort,
+  };
+}
+
+export function normalizeAgentRoute(routeLike, fallbackProvider = '') {
+  const provider = clean(routeLike?.provider) || clean(fallbackProvider);
+  const model = clean(routeLike?.model);
+  if (!provider || !model) return null;
+  return {
+    provider,
+    model,
+    effort: clean(routeLike?.effort) || undefined,
+    fast: routeLike?.fast === true,
+  };
+}
+
+export function agentPresetName(agent) {
+  return `AGENT ${String(agent || '').toUpperCase()}`;
+}
+
+export async function resolvePrompt(args, cwd) {
+  const prompt = clean(args.prompt || args.message);
+  const file = clean(args.file);
+  if (prompt && file) throw new Error('agent: provide only one of prompt/message or file');
+  if (prompt) return prompt;
+  if (file) {
+    const target = isAbsolute(file) ? file : resolve(cwd || process.cwd(), file);
+    return readFileSync(target, 'utf8');
+  }
+  throw new Error('agent: prompt/message/file is required');
+}
+
+export function withCwdHeader(prompt, cwd) {
+  if (!cwd) return prompt;
+  if (String(prompt).startsWith('[effective-cwd]')) return prompt;
+  return `[effective-cwd] ${cwd}\n\n${prompt}`;
+}
+
+export function compactIso(value) {
+  const text = clean(value);
+  if (!text) return '';
+  return text.replace('T', ' ').replace(/\.\d+Z$/, 'Z');
+}
+
+export function formatElapsedMs(ms) {
+  const n = Number(ms);
+  if (!Number.isFinite(n) || n < 0) return '';
+  const totalSec = Math.floor(n / 1000);
+  if (totalSec < 60) return `${totalSec}s`;
+  const min = Math.floor(totalSec / 60);
+  const sec = totalSec % 60;
+  if (min < 60) return sec ? `${min}m${sec}s` : `${min}m`;
+  const hr = Math.floor(min / 60);
+  const remMin = min % 60;
+  return remMin ? `${hr}h${remMin}m` : `${hr}h`;
+}
+
+export function elapsedFromStamps(startedAt, finishedAt, status) {
+  const start = Date.parse(clean(startedAt));
+  if (!Number.isFinite(start)) return null;
+  const finish = Date.parse(clean(finishedAt));
+  const end = Number.isFinite(finish) ? finish : Date.now();
+  const label = formatElapsedMs(end - start);
+  if (!label) return null;
+  return Number.isFinite(finish) ? label : `${label} (running)`;
+}
+
+export function stripFinalAnswerWrapper(value) {
+  const text = String(value ?? '').trim();
+  const match = /^<final-answer\b[^>]*>([\s\S]*?)<\/final-answer>\s*$/i.exec(text);
+  return match ? match[1].trim() : text;
+}
+
+// Process-wide TTL cache for agent AGENT.md frontmatter permission. The file
+// rarely changes, but this otherwise pays several existsSync()+readFileSync()
+// calls on EVERY spawn — multiplied across a parallel fanout that is pure
+// redundant synchronous I/O on the event loop, which blocks every other
+// concurrent spawn. Short TTL keeps edits picked up quickly while collapsing
+// burst reads. Cache + TTL are owned here alongside the sole reader.
+const _frontmatterPermCache = new Map(); // key -> { value, atMs }
+const FRONTMATTER_PERM_CACHE_TTL_MS = envTimeoutMs('MIXDOG_AGENT_FRONTMATTER_TTL_MS', 5_000);
+
+export function readAgentFrontmatterPermission(agent, dataDir, standaloneSourceRoot) {
+  const cleanAgent = clean(agent);
+  if (!cleanAgent) return null;
+  const cacheKey = `${dataDir || ''}\u0000${cleanAgent}`;
+  const cached = _frontmatterPermCache.get(cacheKey);
+  if (cached && Date.now() - cached.atMs < FRONTMATTER_PERM_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  const candidates = [];
+  if (dataDir) {
+    candidates.push(join(dataDir, 'agents', cleanAgent, 'AGENT.md'));
+    candidates.push(join(dataDir, 'agents', `${cleanAgent}.md`));
+  }
+  candidates.push(join(standaloneSourceRoot, 'agents', cleanAgent, 'AGENT.md'));
+  candidates.push(join(standaloneSourceRoot, 'agents', `${cleanAgent}.md`));
+  let resolved = null;
+  for (const file of candidates) {
+    if (!existsSync(file)) continue;
+    const fm = parseMarkdownFrontmatter(readFileSync(file, 'utf8'));
+    const permission = normalizeAgentPermissionOrNone(fm.permission);
+    if (permission) { resolved = permission; break; }
+  }
+  _frontmatterPermCache.set(cacheKey, { value: resolved, atMs: Date.now() });
+  return resolved;
+}