Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

44.4 KB
Raw Blame
/**
 * The /bots chat command: onboarding wizard, fleet management, replay, export/import.
 * Moved out of Agent (P2.1 split); `agent` is the Agent instance.
 */
import type { Agent } from '../agent.js';
import type { ChannelMessage } from '../../types/channel.js';
import type { Channel } from '../../channels/base.js';
import { formatRelative, formatBytes } from './format.js';
import path from 'node:path';
import { homedir } from 'node:os';
import { mkdirSync } from 'node:fs';
import { refinePersona } from '../../bots/persona-template.js';
import { PERMISSION_TIERS, tierPermissionsFile, isPermissionTier, type PermissionTier } from '../../bots/permission-tiers.js';
import { buildBotBundle, writeBundle, readBundle, importBotBundle } from '../../bots/bundle.js';
import { applyBotFieldPatch } from '../../bots/edit.js';
import { openFolder, tildify } from '../../bots/open-folder.js';

export async function handleBotsCommand(agent: Agent, trimmed: string, msg: ChannelMessage, channel: any): Promise<void> {
  const bm = agent.botManager;
  // A /bots command typed from INSIDE a bot thread replies THERE (cli.ts
  // parks the thread id) — the roster/journal/inbox render in the bot's
  // transcript instead of bouncing the user back to the main chat.
  const pendingBot = (channel as any).consumePendingBotChatTarget?.() ?? null;
  const channelId = pendingBot ? `bot:${pendingBot}` : msg.channelId;
  if (!bm) {
    await channel.send('Bots are not available (BotManager not wired).', channelId);
    return;
  }
  const rawArgs = trimmed.slice('/bots'.length).trim();
  const parts = rawArgs.length > 0 ? rawArgs.split(/\s+/) : [];
  const action = (parts[0] ?? '').toLowerCase();

  // All bot-targeting actions accept id OR name — resolve to the id here.
  if (['open', 'send', 'journal', 'inbox', 'budget', 'edit', 'delete', 'enable', 'disable', 'stop', 'pause', 'start', 'run', 'persona', 'crew', 'add-crew', 'remove-crew', 'promote', 'demote', 'permissions'].includes(action) && parts[1]) {
    const resolved = bm.resolveBotId(parts[1]);
    if (resolved) parts[1] = resolved;
  }

  // Any explicit /bots command cancels pending onboarding capture — the
  // user has moved on; a later task in the bot chat must never be eaten
  // by the persona/budget state machine (review K1).
  if (agent.pendingPersonaFor && action !== '') {
    agent.pendingPersonaFor = null;
  }

  const stateIcons: Record<string, string> = { idle: '⚪', queued: '🔵', running: '🟢', paused: '🟡', disabled: '⛔' };
  const runIcons: Record<string, string> = { completed: '✅', failed: '❌', halted: '⛔', paused: '⏸', denied: '🚫' };

  if (action === '' || action === 'list') {
    const summaries = bm.getStatusSummaries();
    if (summaries.length === 0) {
      await channel.send('No bots configured. Use `/bots create <id> "Name" "Description"` to onboard one.', channelId);
      return;
    }
    // Fleet tree: 👑 leads first with crew nested beneath (multi-level,
    // recursive); parentless solos flat after.
    const fmt = (s: typeof summaries[number], indent: string) => {
      const icon = stateIcons[s.state] ?? '❓';
      const badge = s.fleetRole === 'lead' ? ' 👑' : '';
      // Crew runs are short and asynchronous — a snapshot rarely catches
      // them green. Make activity legible anyway: leads show how many crew
      // are working right now, every bot shows its last run outcome.
      const crewNote = s.fleetRole === 'lead' && s.crewWorking
        ? ` · 🟢 ${s.crewWorking} crew working`
        : '';
      const lastRun = s.lastRunAt ? ` · last run ${s.lastRunState ?? '?'} ${formatRelative(s.lastRunAt)}` : '';
      const activity = s.activity ? `\n${indent}   ↳ ${s.activity}` : '';
      const attention = s.needsYou ? ' · ⚠ needs you' : '';
      const cooling = s.routinePausedUntil !== undefined
        ? (Number.isFinite(s.routinePausedUntil) ? ` · ⏸ routine cooling down, resumes ${formatRelative(s.routinePausedUntil)}` : ' · ⏸ routine paused')
        : '';
      // Where the owner finds results — on the fleet's folder, not per crew.
      const folder = !s.parent ? `\n${indent}   📁 ${tildify(bm.store.deliverablesDir(s.id))}` : '';
      return `${indent}${icon} **${s.name}** (${s.id})${badge} — ${s.state}${crewNote}${attention}${cooling}${lastRun}${folder}${activity}`;
    };
    const lines: string[] = [`**Bots** (${summaries.length})`, ''];
    const rendered = new Set<string>();
    const renderCrew = (leadId: string, depth: number) => {
      const crew = summaries.filter(s => s.parent === leadId);
      for (const c of crew) {
        const indent = '  '.repeat(depth);
        lines.push(fmt(c, depth > 0 ? `${indent}└─` : '  '));
        rendered.add(c.id);
        renderCrew(c.id, depth + 1);
      }
      if (crew.length === 0 && depth === 1) {
        lines.push(`${'  '.repeat(depth)}└─ (empty crew — \`/bots add-crew\` or the lead can bot_spawn)`);
      }
    };
    for (const root of summaries.filter(s => !s.parent)) {
      lines.push(fmt(root, ''));
      rendered.add(root.id);
      if (root.fleetRole === 'lead') renderCrew(root.id, 1);
    }
    for (const s of summaries) {
      if (!rendered.has(s.id)) lines.push(fmt(s, '')); // detached crew (defensive)
    }
    const running = summaries.filter(s => s.state === 'running').length;
    lines.push('', `Running: ${running} | Queued: ${summaries.reduce((a, s) => a + (s.state === 'queued' ? 1 : 0), 0)}`);
    // Tappable controls where the surface has them (Telegram): one row per
    // lead/solo (crew follow their lead), plus a fleet row. Taps run the
    // same /bots commands.
    if (typeof channel.sendWithActions === 'function') {
      const roots = summaries.filter(s => !s.parent).slice(0, 8);
      const rows = roots.map(s => {
        const off = s.state === 'disabled' || s.state === 'paused';
        return [
          { label: `${off ? '▶ Start' : '⏹ Stop'} ${s.name}`.slice(0, 40), command: `/bots ${off ? 'start' : 'stop'} ${s.id}` },
          { label: '🏃 Run', command: `/bots run ${s.id}` },
          { label: '📋 Runs', command: `/bots journal ${s.id}` },
        ];
      });
      rows.push([
        { label: '💰 Cost', command: '/bots cost' },
        { label: '📁 Outputs', command: '/bots outputs' },
        { label: '🩺 Doctor', command: '/bots doctor' },
        { label: '🛑 Stop all', command: '/bots stop all' },
      ]);
      await channel.sendWithActions(lines.join('\n'), rows, channelId);
      return;
    }
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'help') {
    await sendBotsHelp(channel, channelId);
    return;
  }

  if (action === 'doctor') {
    const report = bm.doctor();
    const errors = report.findings.filter(f => f.severity === 'error').length;
    const lines = [report.findings.length === 0
      ? `✅ Fleet healthy — ${report.checked} bot(s) checked, nothing actionable.`
      : `🩺 **Fleet doctor** — ${errors} actionable, ${report.findings.length - errors} warning(s), ${report.checked} bot(s) checked`, ''];
    for (const f of report.findings.slice(0, 25)) lines.push(`${f.severity === 'error' ? '❌' : '⚠️'} **${f.botId}** ${f.check}: ${f.detail}`);
    if (report.findings.length > 25) lines.push(`…and ${report.findings.length - 25} more`);
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'fetch' || action === 'get') {
    // /bots fetch <id> [name|latest] — send a deliverable to THIS chat (a phone
    // cannot open a path on the owner's machine).
    const target = parts[1]?.toLowerCase();
    if (!target || !bm.store.exists(target)) {
      await channel.send('Usage: `/bots fetch <id> [name|latest]` — sends a delivered file to this chat.', channelId);
      return;
    }
    const items = bm.listDeliverables(target);
    const wanted = parts.slice(2).join(' ').trim();
    const item = !wanted || wanted === 'latest' ? items[0] : items.find(d => d.name === wanted || d.name.endsWith(wanted) || path.basename(d.path) === wanted);
    if (!item) {
      await channel.send(items.length === 0 ? `**${target}** has delivered nothing yet.` : `No deliverable "${wanted}" — \`/bots outputs ${target}\` lists them.`, channelId);
      return;
    }
    if (typeof channel.sendFile !== 'function' || channel.type === 'cli') {
      await channel.send(`📁 ${tildify(item.path)}`, channelId);
      return;
    }
    await channel.sendFile(item.path, channelId);
    return;
  }

  if (action === 'open') {
    const target = parts[1]?.toLowerCase();
    const manifest = target ? bm.store.get(target) : null;
    if (!target || !manifest) {
      await channel.send(`No bot "${target ?? ''}". See \`/bots\` for the roster.`, channelId);
      return;
    }
    if (typeof (channel as any).enterBotChat === 'function') {
      // Hydrate a cold thread from the durable journal (last 10 runs,
      // compact) — the bot may have worked unattended for hours.
      const history = bm.getJournal(target, 10).map(r => ({
        content: `${r.state === 'completed' ? '✅' : r.state === 'failed' ? '❌' : '⛔'} (${r.trigger}, ${formatRelative(r.startedAt)}${r.durationMs ? `, ${(r.durationMs / 1000).toFixed(0)}s` : ''}) ${r.summary?.slice(0, 300) ?? r.runId}`,
        timestamp: r.startedAt,
      })).reverse();
      (channel as any).enterBotChat(target, manifest.name, history);
      return;
    }
    await channel.send(`Opening a bot chat is only supported in the TUI — use \`/bots send ${target} <message>\` here.`, channelId);
    return;
  }

  if (action === 'create' || action === 'onboard') {
    // /bots create <id> "Name" "Description" ["persona text"]
    const id = (parts[1] ?? '').toLowerCase();
    if (!id) {
      await channel.send('Usage: `/bots create <id> "Name" "Description" "persona (optional)"` — the bot starts with a fail-closed default profile you can refine via its profile files.', channelId);
      return;
    }
    const rest = parts.slice(2).join(' ');
    const quoted = [...rest.matchAll(/"([^"]*)"/g)].map(m => m[1]);
    const name = quoted[0] ?? id.toUpperCase();
    const description = quoted[1];
    const personaText = quoted[2];
    try {
      const manifest = bm.store.create({ id, name, description });
      agent.pendingPersonaNewlyCreated = true;
      if (personaText) {
        bm.store.writePersona(id, personaText + '\n');
        bm.invalidateRuntime(id);
        await channel.send(`🤖 Bot **${manifest.name}** (\`${id}\`) onboarded with your persona — enabled, fail-closed defaults.\n📁 Its results will appear in \`${tildify(bm.store.deliverablesDir(id))}\` (\`/bots folder ${id}\` opens it).\nStart using it: \`/bot ${id} <task>\`, \`/bots open ${id}\`, or just \`@${id} <task>\`.`, channelId);
        await agent.offerFleetStep(bm, id, manifest.name, msg, channel);
        return;
      }
      // No persona given — open its chat and prompt for one now (TUI only).
      if (typeof (channel as any).enterBotChat === 'function') {
        (channel as any).enterBotChat(id, manifest.name);
        agent.pendingPersonaFor = id;
        await channel.send(
          `🤖 **${manifest.name}** onboarded (fail-closed defaults). 📁 Results: \`${tildify(bm.store.deliverablesDir(id))}\`\n\nNow give it its character — your next message here becomes its **persona** (who it is, how it works, how it reports). Send \`/skip\` to keep the starter template, or \`/persona\` later to change it.`,
          `bot:${id}`,
        );
      } else {
        // No bot thread here (Telegram, web, Discord): the next message in
        // this chat is the persona; the tier, fleet and budget steps follow
        // as tappable choices — the same onboarding as the TUI.
        agent.pendingPersonaFor = id;
        agent.pendingPersonaChannelId = channelId;
        await channel.send(
          `🤖 **${manifest.name}** (\`${id}\`) created — enabled, fail-closed defaults. 📁 Results: \`${tildify(bm.store.deliverablesDir(id))}\`\n\n` +
          `Now give it its character — your **next message here** becomes its persona (who it is, how it works, how it reports). I will offer to structure it into a template. Send \`/skip\` to keep the starter persona.`,
          channelId,
        );
      }
    } catch (err: any) {
      await channel.send(`Could not create bot "${id}": ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'persona') {
    const target = parts[1]?.toLowerCase();
    const personaText = parts.slice(2).join(' ');
    if (!target) {
      await channel.send('Usage: `/bots persona <id> <full persona text in one message>` — or open the bot chat (`/bots open <id>`) and type `/persona`.', channelId);
      return;
    }
    const resolved = bm.resolveBotId(target) ?? target;
    if (!bm.store.exists(resolved)) {
      await channel.send(`No bot "${target}". See \`/bots\` for the roster.`, channelId);
      return;
    }
    if (!personaText) {
      // Bare `/persona` (typed inside the bot chat): arm the capture —
      // the next message in that thread becomes the persona. This is the
      // promised flow ("edit it anytime with /persona here"); it must not
      // degrade to the /bots roster.
      agent.pendingBudgetFor = null;
      agent.pendingPersonaFor = resolved;
      const name = bm.store.get(resolved)?.name ?? resolved;
      await channel.send(`✍️ Persona capture armed for **${name}** — your next message in this chat becomes its persona. \`/skip\` keeps the current one.`, `bot:${resolved}`);
      return;
    }
    await agent.finalizePersona(bm, resolved, personaText, msg);
    return;
  }

  if (action === 'send') {
    const target = parts[1]?.toLowerCase();
    const message = parts.slice(2).join(' ');
    if (!target || !message) {
      await channel.send('Usage: `/bots send <id> <message>`', channelId);
      return;
    }
    const result = bm.enqueue(target, { trigger: 'chat', prompt: message, source: { channelType: msg.channelType, channelId } });
    if (!result.accepted) {
      await channel.send(`Could not message **${target}**: [reason: ${result.reasonCode}]`, channelId);
      return;
    }
    await channel.send(`🤖 Queued for **${target}** (job ${result.jobId}) — runs outside the main conversation.`, channelId);
    return;
  }

  if (action === 'enable' || action === 'disable') {
    const target = parts[1]?.toLowerCase();
    if (!target) {
      await channel.send(`Usage: \`/bots ${action} <id>\``, channelId);
      return;
    }
    try {
      bm.setEnabled(target, action === 'enable');
      await channel.send(`${action === 'enable' ? '✅ Enabled' : '⏸ Disabled'} bot **${target}**.`, channelId);
    } catch (err: any) {
      await channel.send(`Failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'budget') {
    const target = parts[1]?.toLowerCase();
    const value = (parts[2] ?? '').toLowerCase();
    if (!target || !value) {
      const suggested = agent.config.bots?.suggestedDailyTokenBudget ?? 5_000_000;
      await channel.send(`Usage: \`/bots budget <id> <tokens|suggest|none>\` — every bot has a daily cap (default ${suggested.toLocaleString()}/day); suggest = that default, none = unlimited.`, channelId);
      return;
    }
    try {
      bm.store.update(target, m => {
        // 0 = explicitly unlimited; absent = the fleet default applies (ADR-020).
        if (value === 'none') { m.autonomy = { ...m.autonomy, dailyTokenBudget: 0 }; }
        else if (value === 'suggest') { if (m.autonomy) delete m.autonomy.dailyTokenBudget; }
        else {
          const n = parseInt(value, 10);
          if (!Number.isFinite(n) || n <= 0) throw new Error('budget must be a positive integer, "suggest", or "none"');
          m.autonomy = { ...m.autonomy, dailyTokenBudget: n };
        }
      });
      bm.invalidateRuntime(target);
      const m = bm.store.get(target);
      const cap = m ? bm.dailyCapFor(m) : 0;
      const applied = cap > 0 ? `${cap.toLocaleString()}/day${m?.autonomy?.dailyTokenBudget === undefined ? ' (fleet default)' : ''}` : 'none (unlimited)';
      await channel.send(`💰 Budget for **${target}**: ${applied}. Hit the cap → the bot pauses until the next day, never killed.`, channelId);
    } catch (err: any) {
      await channel.send(`Failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'edit') {
    const target = parts[1]?.toLowerCase();
    const path = parts[2];
    const value = parts.slice(3).join(' ');
    if (!target || !path || !value) {
      await channel.send('Usage: `/bots edit <id> <field> <value>`\nEditable fields: name, description, model.provider, model.model, memory.scope, memory.allowCrossBotRecall, comms.canMessage, tools.allow, tools.deny, autonomy.maxConcurrent, autonomy.maxSteps, autonomy.dailyTokenBudget', channelId);
      return;
    }
    try {
      const manifest = bm.store.get(target);
      if (!manifest) throw new Error(`Bot "${target}" does not exist`);
      const result = applyBotFieldPatch(manifest, path, value);
      if (!result.ok) {
        await channel.send(`⚠ ${result.error}`, channelId);
        return;
      }
      bm.store.save(manifest);
      bm.invalidateRuntime(target);
      await channel.send(`✏️ **${target}**.${path} = ${result.display}`, channelId);
    } catch (err: any) {
      await channel.send(`Failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'delete') {
    const target = parts[1]?.toLowerCase();
    const confirmed = parts[2]?.toLowerCase() === 'confirm';
    if (!target || !bm.store.exists(target)) {
      await channel.send('Usage: `/bots delete <id> confirm` — removes the profile dir, halts any running turn, and dead-letters pending jobs. This cannot be undone.', channelId);
      return;
    }
    if (!confirmed && typeof (channel as any).askToContinue === 'function') {
      const crewCount = bm.store.crewOf(target).length;
      const proceed = await (channel as any).askToContinue(`Delete bot **${target}** and its profile (persona, memory links, journal)? This cannot be undone.${crewCount > 0 ? ` Its ${crewCount} crew member(s) will be deleted with it (fleet cascade).` : ''}`);
      if (!proceed) {
        await channel.send('Deletion cancelled.', channelId);
        return;
      }
    } else if (!confirmed) {
      await channel.send(`Type \`/bots delete ${target} confirm\` to permanently delete.`, channelId);
      return;
    }
    try {
      await bm.halt(target);
      bm.store.delete(target);
      bm.invalidateRuntime(target);
      await channel.send(`🗑 Bot **${target}** deleted (running turn halted; its profile directory is gone).`, channelId);
    } catch (err: any) {
      await channel.send(`Failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'export') {
    // /bots export <id> [path] — a shareable bundle: manifests + personas +
    // permissions + skills (single JSON; a lead's bundle carries its whole
    // crew tree). Sandbox, journal, and .env never travel.
    const target = parts[1]?.toLowerCase();
    if (!target || !bm.store.exists(target)) {
      await channel.send('Usage: `/bots export <id> [outPath]` — writes a shareable JSON bundle (fleet leads include their crew).', channelId);
      return;
    }
    try {
      const bundle = buildBotBundle(bm.store, target);
      const outPath = parts.slice(2).join(' ') || undefined;
      const path = writeBundle(bundle, outPath?.trim() || undefined);
      const crewNote = bundle.kind === 'fleet' ? ` (fleet — ${bundle.bots.length} bots incl. crew)` : '';
      await channel.send(`📦 Exported **${target}**${crewNote} → \`${path}\`\nIncluded: manifests, personas, permissions, skills. Never included: sandbox, journals, .env (local state + secrets).`, channelId);
    } catch (err: any) {
      await channel.send(`Export failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'import') {
    // /bots import <path> — recreate bots from a bundle. Imported bots
    // start DISABLED (fail-closed); enable each one consciously.
    const rawPath = parts.slice(1).join(' ').trim();
    if (!rawPath) {
      await channel.send('Usage: `/bots import <bundlePath>` — recreates bots from a `.bot.json` bundle. Imported bots start disabled; enable with `/bots enable <id>`.', channelId);
      return;
    }
    try {
      const bundle = readBundle(rawPath.startsWith('~') ? rawPath.replace(/^~/, homedir()) : rawPath);
      const report = importBotBundle(bm.store, bundle, { overwrite: parts.includes('--overwrite') });
      const lines: string[] = [];
      if (report.created.length > 0) lines.push(`✅ Created: ${report.created.map(id => `\`${id}\``).join(', ')} (disabled — enable with \`/bots enable <id>\`)`);
      for (const s of report.skipped) lines.push(`⏭ \`${s.id}\`: ${s.reason}`);
      if (lines.length === 0) lines.push('Nothing to import.');
      await channel.send(`📥 Import from \`${rawPath}\`:\n${lines.join('\n')}`, channelId);
    } catch (err: any) {
      await channel.send(`Import failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'stop' || action === 'pause') {
    const target = parts[1]?.toLowerCase();
    if (!target) {
      await channel.send('Usage: `/bots stop <id>` or `/bots stop all` (kill switch — every bot halts, queued work is held)', channelId);
      return;
    }
    if (target === 'all') {
      const r = await bm.stopAll();
      await channel.send(`🛑 Kill switch: ${r.stopped} bot(s) stopped, ${r.halted} running turn(s) halted, ${r.heldJobs} queued job(s) held. Nothing runs until \`/bots start all\` (or per bot).`, channelId);
      return;
    }
    const result = await bm.stop(target);
    const crewNote = result.crewStopped > 0 ? `\n🛑 Fleet cascade: ${result.crewStopped} crew bot(s) stopped with it.` : '';
    const heldNote = result.heldJobs > 0 ? `\n↩ ${result.heldJobs} queued job(s) held fleet-wide — resume with \`/bots start ${target}\`.` : '';
    await channel.send(result.halted
      ? `⛔ Halt signal sent to **${target}** — it will stop after the current tool step.${crewNote}${heldNote}`
      : `⛔ **${target}** stopped — nothing was running.${crewNote}${heldNote}`, channelId);
  }

  if (action === 'start' && parts[1]?.toLowerCase() === 'all') {
    const r = bm.startAll();
    await channel.send(`▶ Started ${r.started} fleet(s)/solo bot(s); ${r.resumed} held job(s) resumed; paused routines cleared.`, channelId);
    return;
  }

  if (action === 'start') {
    const target = parts[1]?.toLowerCase();
    if (!target) {
      await channel.send('Usage: `/bots start <id>`', channelId);
      return;
    }
    try {
      const { resumed } = bm.start(target);
      await channel.send(resumed > 0
        ? `▶️ **${target}** started — ${resumed} held job(s) back in the queue.`
        : `▶️ **${target}** started — nothing was held; it is idle and ready for tasks.`, channelId);
    } catch (err: any) {
      await channel.send(`Failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'run') {
    const target = parts[1]?.toLowerCase();
    const routine = parts.slice(2).join(' ') || undefined;
    if (!target) {
      await channel.send('Usage: `/bots run <id> [routineName]` — no routine = a bare wake turn.', channelId);
      return;
    }
    const result = bm.runNow(target, routine);
    if (!result.accepted) {
      if (result.reasonCode === 'routine_unknown') {
        const names = (bm.store.get(target)?.schedules ?? []).map(r => r.name);
        await channel.send(`No routine "${routine}" on **${target}**.${names.length ? ` Configured: ${names.join(', ')}` : ' This bot has no routines — add them with `/bots edit <id>` or /bots open.'}`, channelId);
        return;
      }
      await channel.send(`Could not run **${target}**: [reason: ${result.reasonCode}]`, channelId);
      return;
    }
    await channel.send(routine
      ? `🏃 Routine **${routine}** fired on **${target}** (job ${result.jobId}) — runs outside the main conversation.`
      : `🏃 Wake sent to **${target}** (job ${result.jobId}) — it gets a turn to check its mailbox and pending work.`, channelId);
    return;
  }

  if (action === 'journal') {
    const target = parts[1]?.toLowerCase();
    if (!target) {
      await channel.send('Usage: `/bots journal <id>`', channelId);
      return;
    }
    const records = bm.getJournal(target, 10);
    if (records.length === 0) {
      await channel.send(`No runs recorded yet for **${target}**.`, channelId);
      return;
    }
    const lines = [`**${target} — recent runs**`, ''];
    for (const r of [...records].reverse()) {
      const icon = r.state === 'completed' ? '✅' : r.state === 'failed' ? '❌' : r.state === 'paused' ? '⏸' : '⛔';
      const reason = r.reasonCode ? ` · [reason: ${r.reasonCode}]` : '';
      const outcome = r.outcome ? ` · ${r.outcome === 'none' ? '⚠ no outcome' : r.outcome}` : '';
      const runFor = r.turnStartedAt ? ((Date.now() - r.turnStartedAt < r.durationMs ? r.durationMs : (r.startedAt + r.durationMs - r.turnStartedAt)) / 1000).toFixed(0) + 's run' : (r.durationMs / 1000).toFixed(1) + 's';
      lines.push(`${icon} ${r.runId} · ${r.trigger} · ${r.state} · ${runFor} · ${(r.tokensIn + r.tokensOut).toLocaleString()} tok${r.steps !== undefined ? ` · ${r.steps} steps` : ''}${outcome}${reason}`);
      for (const d of r.deliverables ?? []) lines.push(`   📁 ${tildify(d)}`);
      if (r.summary) lines.push(`   ${r.summary.slice(0, 100)}`);
    }
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'inbox') {
    const target = parts[1]?.toLowerCase();
    if (!target) {
      await channel.send('Usage: `/bots inbox <id>`', channelId);
      return;
    }
    const mail = bm.peekMailbox(target);
    if (mail.length === 0) {
      await channel.send(`**${target}** mailbox is empty.`, channelId);
      return;
    }
    const lines = [`**${target} — inbox** (${mail.length})`, ''];
    for (const m of mail) {
      lines.push(`🤖 from **${m.from}**: ${m.content.slice(0, 120)}`);
    }
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'dlq') {
    // /bots dlq clear [id] — drop dead-lettered jobs (the journal keeps the runs).
    if (parts[1]?.toLowerCase() === 'clear') {
      const target = parts[2]?.toLowerCase();
      if (target && !bm.store.exists(target)) {
        await channel.send(`No bot "${target}".`, channelId);
        return;
      }
      const n = bm.clearDlq(target);
      await channel.send(n > 0 ? `🧹 Cleared ${n} dead-lettered job(s)${target ? ` for **${target}**` : ''}. The runs stay in \`/bots journal\`.` : 'Dead-letter queue was already empty.', channelId);
      return;
    }
    const target = parts[1]?.toLowerCase();
    const entries = target ? bm.getDlq(target) : bm.getDlq();
    if (entries.length === 0) {
      await channel.send('Dead-letter queue is empty — nothing failed permanently.', channelId);
      return;
    }
    const lines = ['**Dead-letter queue** (replay: `/bots replay <botId> <jobId>` · clear: `/bots dlq clear [id]`)', ''];
    for (const e of entries.slice(0, 10)) {
      lines.push(`🚫 **${e.botId}** ${e.id} · ${e.trigger} · attempts ${e.attempts} · [reason: ${e.reasonCode ?? 'unknown'}] · ${e.prompt.slice(0, 60)}`);
    }
    if (entries.length > 10) lines.push(`…and ${entries.length - 10} more`);
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'replay') {
    const target = parts[1]?.toLowerCase();
    const jobId = parts[2];
    if (!target || !jobId) {
      await channel.send('Usage: `/bots replay <botId> <jobId>`', channelId);
      return;
    }
    const result = bm.replayDlq(target, jobId);
    if (!result.accepted) {
      await channel.send(`Replay failed: [reason: ${result.reasonCode}] — is that job id in the DLQ?`, channelId);
      return;
    }
    await channel.send(`↻ Job ${jobId} re-enqueued for **${target}** (new job ${result.jobId}).`, channelId);
    return;
  }

  if (action === 'permissions') {
    // /bots permissions <id> [tier] — show or set the capability tier.
    const target = parts[1]?.toLowerCase();
    const tierArg = (parts[2] ?? '').toLowerCase();
    if (!target || !bm.store.exists(target)) {
      await channel.send('Usage: `/bots permissions <id> [readonly|builder|operator|full]` — omit the tier to see the current one.', channelId);
      return;
    }
    if (!tierArg) {
      const perms = bm.store.readPermissions(target);
      const deny = new Set(perms.tools?.deny ?? bm.store.get(target)?.tools?.deny ?? []);
      const matched = Object.entries(PERMISSION_TIERS).find(([, t]) => t.deny.length === deny.size && t.deny.every(d => deny.has(d)))?.[0];
      const current = matched ?? 'custom';
      const effective = deny.has('run_command') ? 'no shell' : 'shell within its path scopes';
      const scopeCount = perms.paths?.length ?? 0;
      await channel.send(`🔐 **${target}**: ${current} (deny: ${[...deny].join(', ') || 'none'}, path scopes: ${scopeCount}) — ${effective}. Source: its permissions.yaml. Set with \`/bots permissions ${target} <readonly|builder|operator|full>\`.`, channelId);
      return;
    }
    if (!isPermissionTier(tierArg)) {
      await channel.send('Unknown tier — use `readonly`, `builder`, `operator`, or `full`.', channelId);
      return;
    }
    bm.store.writePermissions(target, tierPermissionsFile(tierArg));
    bm.store.update(target, m => { delete (m as any).tools; });
    bm.invalidateRuntime(target);
    await channel.send(`🔐 Permissions for **${target}**: **${PERMISSION_TIERS[tierArg].label}** — ${PERMISSION_TIERS[tierArg].description}\n(Written to its permissions.yaml — the single source of truth.)`, channelId);
    return;
  }

  if (action === 'promote' || action === 'demote') {
    // /bots promote <id> — solo/crew → fleet lead (demote: lead → solo).
    const target = parts[1]?.toLowerCase();
    if (!target || !bm.store.exists(target)) {
      await channel.send(`Usage: \`/bots ${action} <id>\``, channelId);
      return;
    }
    try {
      bm.store.update(target, m => {
        if (action === 'promote') {
          m.fleetRole = 'lead';
        } else {
          m.fleetRole = undefined;
          if (bm.store.crewOf(target).length > 0) throw new Error(`**${target}** still has crew — remove-crew first`);
        }
      });
      bm.invalidateRuntime(target);
      await channel.send(action === 'promote'
        ? `👑 **${target}** is now a fleet lead. It will self-organize: give it a setup task and it will build its own crew with bot_spawn (persona-derived), or add crew with \`/bots add-crew ${target} …\`.`
        : `⬇ **${target}** demoted to a solo bot.`, channelId);
    } catch (err: any) {
      await channel.send(`Failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'crew') {
    // /bots crew <leadId> — the fleet tree + per-crew recent runs.
    const leadId = parts[1]?.toLowerCase();
    if (!leadId || !bm.store.exists(leadId)) {
      await channel.send('Usage: `/bots crew <leadId>`', channelId);
      return;
    }
    const lead = bm.store.get(leadId);
    if (lead?.fleetRole !== 'lead') {
      await channel.send(`**${lead?.name ?? leadId}** is not a fleet lead.`, channelId);
      return;
    }
    const crew = bm.store.crewOf(leadId);
    const lines = [`👑 **${lead.name}** fleet (${crew.length}/${bm.maxCrew()})`, ''];
    if (crew.length === 0) {
      lines.push('(empty — `/bots add-crew` or tell the lead to bot_spawn)');
    }
    const stateIcons2: Record<string, string> = { idle: '⚪', queued: '🔵', running: '🟢', paused: '🟡', disabled: '⛔' };
    for (const c of crew) {
      const summary = bm.getStatusSummaries().find(s => s.id === c.id);
      const runs = bm.getJournal(c.id, 3);
      const lastRun = runs.length > 0 ? `last: ${runs[runs.length - 1].state}` : 'no runs yet';
      lines.push(`${stateIcons2[summary?.state ?? 'idle']} **${c.name}** (${c.id})${c.description ? ` — ${c.description}` : ''} · ${lastRun}`);
      for (const r of runs.slice(-2).reverse()) {
        lines.push(`   ↳ ${r.state === 'completed' ? '✅' : r.state === 'failed' ? '❌' : '⛔'} ${r.summary?.slice(0, 90) ?? r.runId}`);
      }
    }
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'add-crew') {
    // /bots add-crew <leadId> <id> "Name" "Description" ["persona"]
    const leadId = parts[1]?.toLowerCase();
    const rest = parts.slice(2).join(' ');
    const quoted = [...rest.matchAll(/"([^"]*)"/g)].map(m => m[1]);
    const id = quoted[0] ?? parts[2];
    if (!leadId || !id || !quoted[0]) {
      await channel.send('Usage: `/bots add-crew <leadId> <id> "Name" "Description" "persona (optional)"`', channelId);
      return;
    }
    if (!bm.store.exists(leadId) || bm.store.get(leadId)?.fleetRole !== 'lead') {
      await channel.send(`**${leadId}** is not a fleet lead.`, channelId);
      return;
    }
    try {
      let persona: string | undefined;
      if (quoted[2]) {
        (channel as any).sendHeartbeat?.('⏳ Building the crew persona (up to ~60s)…');
        const refined = await refinePersona(quoted[2], quoted[0], agent.providers.getDefault());
        (channel as any).clearHeartbeat?.();
        persona = refined ?? quoted[2];
      }
      const result = bm.addCrew(leadId, { id, name: quoted[0], description: quoted[1], persona });
      if (!result.ok) {
        await channel.send(`⚠ ${result.error}`, channelId);
        return;
      }
      await channel.send(`👑 Crew member **${quoted[0]}** (\`${result.manifest.id}\`) added to **${leadId}** — fail-closed defaults, comms linked to the lead${persona ? ', persona refined' : ''}.`, channelId);
    } catch (err: any) {
      await channel.send(`Failed: ${err?.message}`, channelId);
    }
    return;
  }

  if (action === 'remove-crew') {
    const leadId = parts[1]?.toLowerCase();
    const crewId = parts[2]?.toLowerCase();
    if (!leadId || !crewId) {
      await channel.send('Usage: `/bots remove-crew <leadId> <crewId>`', channelId);
      return;
    }
    const crew = bm.store.get(crewId);
    if (!crew || crew.parent !== leadId) {
      await channel.send(`**${crewId}** is not crew of **${leadId}**. See \`/bots crew ${leadId}\`.`, channelId);
      return;
    }
    if (typeof (channel as any).askToContinue === 'function') {
      const proceed = await (channel as any).askToContinue(`Retire crew member **${crew.name}** (${crewId})? Profile, sandbox, and queue are removed permanently.`);
      if (!proceed) {
        await channel.send('Retirement cancelled.', channelId);
        return;
      }
    }
    const result = await bm.removeCrew(leadId, crewId);
    await channel.send(result.ok ? `👑 Crew member **${crewId}** retired from **${leadId}**.` : `⚠ ${result.error}`, channelId);
    return;
  }

  if (action === 'outputs' || action === 'deliverables') {
    // /bots outputs [id] — what the bots delivered, and where it is on disk.
    const target = parts[1]?.toLowerCase();
    if (target && !bm.store.exists(target)) {
      await channel.send(`No bot "${target}". See \`/bots\` for the roster.`, channelId);
      return;
    }
    const items = bm.listDeliverables(target).slice(0, 30);
    const root = target ? bm.store.deliverablesDir(target) : bm.store.deliverablesRoot();
    if (items.length === 0) {
      await channel.send(`Nothing delivered yet. Results will appear in \`${tildify(root)}\` — a bot delivers with bot_deliver when a result is finished.`, channelId);
      return;
    }
    const lines = [`**Deliverables** — ${tildify(root)}`, ''];
    for (const d of items) {
      lines.push(`${d.final ? '📄' : '📝'} ${formatRelative(d.mtimeMs)} · **${d.botId}** · ${d.name} (${formatBytes(d.bytes)})`);
    }
    lines.push('', '📄 final · 📝 work in progress (under work/) · `/bots folder <id>` opens the folder · `/bots fetch <id> [name]` sends a file here');
    if (typeof channel.sendWithActions === 'function' && channel.type !== 'cli') {
      const rows = items.slice(0, 6).map(d => [{ label: `📎 ${path.basename(d.path).slice(0, 36)}`, command: `/bots fetch ${d.botId} ${d.name}` }]);
      await channel.sendWithActions(lines.join('\n'), rows, channelId);
      return;
    }
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'cost' || action === 'usage') {
    // /bots cost [days] — where the tokens go, per bot and per fleet.
    const days = Math.max(1, Math.min(90, parseInt(parts[1] ?? '7', 10) || 7));
    const report = bm.costReport(days);
    if (report.bots.length === 0) {
      await channel.send('No bots configured.', channelId);
      return;
    }
    const k = (n: number) => n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M` : n >= 1000 ? `${Math.round(n / 1000)}k` : String(n);
    const lines = [`**Bot token spend** — today and the last ${days} days`, ''];
    if (report.fleetCap > 0) lines.push(`Fleet today: ${k(report.fleetToday)} / ${k(report.fleetCap)}${report.fleetPaused ? ' · ⛔ paused (cap reached)' : ''}`, '');
    for (const fleet of report.fleets) {
      const lead = report.bots.find(b => b.id === fleet.id)!;
      const members = report.bots.filter(b => b.parent === fleet.id);
      const row = (b: typeof lead, indent: string) => {
        const capNote = b.cap > 0 ? ` / ${k(b.cap)}${b.paused ? ' ⛔' : ''}` : ' (no cap)';
        const w = b.window;
        const empty = w.noOutcome > 0 ? ` · ⚠ ${w.noOutcome} empty` : '';
        return `${indent}**${b.name}** — today ${k(b.today.tokensIn + b.today.tokensOut)}${capNote} · ${days}d ${k(w.tokensIn + w.tokensOut)} in ${w.runs} runs (${w.failed} failed, ${w.deliverables} delivered${empty})`;
      };
      lines.push(row(lead, members.length ? '👑 ' : ''));
      for (const m of members) lines.push(row(m, '  └─ '));
      if (members.length) lines.push(`  fleet total: ${days}d ${k(fleet.window.tokensIn + fleet.window.tokensOut)} · ${fleet.window.deliverables} delivered`);
    }
    const total = report.bots.reduce((a, b) => a + b.window.tokensIn + b.window.tokensOut, 0);
    lines.push('', `All bots, ${days}d: ${k(total)} tokens. \`/bots budget <id>\` sets a cap; \`/bots show <id>\` opens a run.`);
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'show' || action === 'transcript') {
    // /bots show <id> [runId] — what a run actually did.
    const target = parts[1]?.toLowerCase();
    if (!target || !bm.store.exists(target)) {
      await channel.send('Usage: `/bots show <id> [runId]` — the tool trace and reply of a run (newest when no id).', channelId);
      return;
    }
    const t = bm.readTranscript(target, parts[2]);
    if (!t) {
      await channel.send(`No transcript${parts[2] ? ` for run ${parts[2]}` : ''} — transcripts exist for runs made after the governance update.`, channelId);
      return;
    }
    const r = t.record;
    const lines = [`**${target} · run ${r.runId}** — ${r.trigger} · ${r.state}${r.outcome ? ` · ${r.outcome}` : ''} · ${(r.tokensIn + r.tokensOut).toLocaleString()} tok · ${r.steps ?? '?'} steps${r.reasonCode ? ` · [${r.reasonCode}]` : ''}`, ''];
    if (t.prompt) lines.push(`**Task:** ${t.prompt.replace(/\s+/g, ' ').slice(0, 240)}`, '');
    if (t.trace.length > 0) {
      lines.push(`**Tools (${t.trace.length}):**`);
      for (const step of t.trace.slice(0, 25)) lines.push(`${step.ok ? '✓' : '✗'} ${step.name}${step.arg ? ` ${step.arg.slice(0, 70)}` : ''}`);
      if (t.trace.length > 25) lines.push(`…and ${t.trace.length - 25} more`);
      lines.push('');
    }
    for (const d of r.deliverables ?? []) lines.push(`📁 ${tildify(d)}`);
    if (r.claimedWithoutAction) lines.push('⚠ The reply claimed delivery or execution the trace does not show.');
    lines.push('', `**Reply:** ${t.output.slice(0, 1200)}${t.output.length > 1200 ? '…' : ''}`);
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'tasks') {
    // /bots tasks <leadId> — what a lead has delegated and what came back.
    const target = parts[1]?.toLowerCase();
    if (!target || !bm.store.exists(target)) {
      await channel.send('Usage: `/bots tasks <leadId>` — open and recent delegated tasks of a fleet lead.', channelId);
      return;
    }
    const tasks = bm.tasksFor(target);
    if (tasks.length === 0) {
      await channel.send(`**${target}** has not delegated any tasks yet.`, channelId);
      return;
    }
    const icons: Record<string, string> = { queued: '🔵', running: '🟢', done: '✅', failed: '❌', halted: '⏹', cancelled: '🚫' };
    const lines = [`**${target} — delegated tasks** (newest first)`, ''];
    for (const t of tasks) {
      const r = t.result;
      lines.push(`${icons[t.status] ?? '•'} ${t.id} → **${t.assignee}**${t.stage ? ` (${t.stage})` : ''} · ${t.status}${r?.outcome ? ` · ${r.outcome}` : ''} · ${formatRelative(t.completedAt ?? t.startedAt ?? t.createdAt)}`);
      lines.push(`   ${t.goal.slice(0, 100)}`);
      for (const d of r?.deliverables ?? []) lines.push(`   📁 ${tildify(d)}`);
    }
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  if (action === 'folder') {
    // /bots folder <id> — open the deliverables folder in Finder / Explorer / the file manager.
    const target = parts[1]?.toLowerCase();
    if (!target || !bm.store.exists(target)) {
      await channel.send('Usage: `/bots folder <id>` — opens the bot\'s deliverables folder.', channelId);
      return;
    }
    const dir = bm.store.deliverablesDir(target);
    mkdirSync(dir, { recursive: true });
    const opened = await openFolder(dir);
    await channel.send(opened ? `📁 Opened \`${tildify(dir)}\`` : `📁 ${tildify(dir)}\n(could not open a file manager here — copy the path)`, channelId);
    return;
  }

  if (action === 'storage') {
    const usage = bm.getStorage();
    if (usage.length === 0) {
      await channel.send('No bot storage in use.', channelId);
      return;
    }
    const lines = ['**Bot storage**', ''];
    let total = 0;
    for (const u of usage) {
      total += u.bytes;
      lines.push(`**${u.id}**: ${formatBytes(u.bytes)} (journal ${formatBytes(u.journalBytes)})`);
    }
    lines.push('', `Total: ${formatBytes(total)} — caps are enforced at write time (transcripts keep last 50 runs; journals rotate at 5 MB).`);
    await channel.send(lines.join('\n'), channelId);
    return;
  }

  await sendBotsHelp(channel, channelId);
}

async function sendBotsHelp(channel: Pick<Channel, 'send'>, channelId: string): Promise<void> {
  await channel.send(
    '**Bots commands**\n' +
    '`/bots` — roster with live states\n' +
    '`/bots open <id>` — open a bot chat (transcript swaps to the bot thread)\n' +
    '`/bots create <id> "Name" "Description"` — onboard a bot\n' +
    '`/bot <id> <message>` — message a bot from any channel\n' +
    '`/bots persona <id> <text>` — set/replace its character (with template conversion)\n' +
    '`/bots budget <id> <tokens|suggest|none>` — daily token budget (default 5M/day; none = unlimited)\n' +
    '`/bots outputs [id]` — what the bots delivered, and where\n' +
    '`/bots tasks <leadId>` — a lead\'s delegated tasks and their results\n' +
    '`/bots folder <id>` — open a bot\'s deliverables folder\n' +
    '`/bots edit <id> <field> <value>` — edit any config field anytime\n' +
    '`/bots journal <id>` — recent runs\n' +
    '`/bots inbox <id>` — pending bot-to-bot mail\n' +
    '`/bots dlq [clear [id]]` — dead-lettered jobs; clear drops them\n' +
    '`/bots cost [days]` — token spend per bot and fleet, against caps\n' +
    '`/bots show <id> [runId]` — what a run actually did (tools, deliverables, reply)\n' +
    '`/bots stop all` / `/bots start all` — fleet kill switch\n' +
    '`/bots doctor` — fleet health check\n' +
    '`/bots fetch <id> [name|latest]` — send a delivered file to this chat\n' +
    '`/bots help` — this list\n' +
    '`/bots replay <botId> <jobId>` — re-run a dead-lettered job\n' +
    '`/bots storage` — disk usage\n' +
    '`/bots enable|disable|stop|start <id>` — control (stop holds queued jobs; start resumes them)\n' +
    '`/bots run <id> [routineName]` — fire a routine now, or a bare wake turn\n' +
    '`/bots crew <leadId>` — fleet tree with per-crew runs\n' +
    '`/bots promote <id>` / demote — make a bot a fleet lead (it then self-organizes) / back to solo\n' +
    '`/bots permissions <id> [tier]` — capability tier: readonly | builder | operator | full\n' +
    '`/bots add-crew <leadId> <id> "Name" "Desc" ["persona"]` — add a sub-bot to a fleet\n' +
    '`/bots remove-crew <leadId> <crewId>` — retire a crew member\n' +
    '`/bots delete <id> confirm` — permanently delete',
    channelId,
  );
}

/** ~ for the home dir — paths shown to people, not to tools. */

/** Open a folder in the platform file manager; false when there is none (headless/SSH). */