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.

38.7 KB
Raw Blame
import { requireOwner } from '../owner-gate.js';
import { trackStream } from '../../security/live-streams.js';
import { principalKey, principalOf } from '../middleware.js';
import { Hono } from 'hono';
import { openFolder, tildify } from '../../bots/open-folder.js';
import type { Context } from 'hono';
import { readFileSync, existsSync, mkdirSync, rmSync } from 'node:fs';
import type { BotManager } from '../../bots/bot-manager.js';
import type { BotManifest } from '../../bots/types.js';
import { PERMISSION_TIERS, tierPermissionsFile, isPermissionTier, type PermissionTier } from '../../bots/permission-tiers.js';
import { buildBotBundle, importBotBundle } from '../../bots/bundle.js';
import { isValidCronExpression } from '../../bots/store.js';
import { decodeAvatarInput, detectImage } from '../../bots/avatar.js';
import { storeInlineAttachments } from './uploads.js';

const app = new Hono();

let botManager: BotManager | undefined;
let webhookSecret: string | undefined;

export function setBotManager(bm: BotManager | undefined): void {
  botManager = bm;
}

/** Shared secret for bot webhook ingress; unset = auth via the web session only. */
export function setBotsWebhookSecret(secret: string | undefined): void {
  webhookSecret = secret;
}

// Fleet roster with live states
app.get('/api/bots', (c: any) => {
  if (!botManager) {
    return c.json({ bots: [], available: false });
  }
  return c.json({ bots: botManager.getStatusSummaries(), queue: botManager.queue.counts(), available: true, unread: botManager.inbox.unread() });
});

// The owner's inbox (Bots 2.0): results, reported failures and runs that need
// the owner, newest first. `?unread=1` for unread only, `?bot=<id>` for one bot.
// The live feed's recent history (the stream sends what happens next).
app.get('/api/bots/activity', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const bots = String(c.req.query('bots') ?? '').split(',').map((s: string) => s.trim()).filter(Boolean);
  const since = Number(c.req.query('since') ?? 0) || 0;
  const limit = Number(c.req.query('limit') ?? 400) || 400;
  return c.json({ events: botManager.recentActivity({ bots, since, limit }), now: Date.now() });
});

app.get('/api/bots/inbox', (c: Context) => {
  if (!botManager) return c.json({ entries: [], unread: 0, available: false });
  const limit = Math.max(1, Math.min(500, Number(c.req.query('limit')) || 100));
  const botId = c.req.query('bot') || undefined;
  const entries = botManager.inbox.list({ limit, botId, unreadOnly: c.req.query('unread') === '1' });
  return c.json({ entries, unread: botManager.inbox.unread(botId), available: true });
});

// The persona builder, for the app's editors: rough instructions in, the
// structured persona out. Nothing is saved; the owner reviews it first.
app.post('/api/bots/persona-builder', async (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const body = (await c.req.json().catch(() => ({}))) as { text?: unknown; name?: unknown };
  const text = typeof body.text === 'string' ? body.text.trim() : '';
  if (text.length < 10) return c.json({ error: 'Write a few words about what the bot should do first.' }, 400);
  const persona = await botManager.buildPersona(text, typeof body.name === 'string' ? body.name.slice(0, 60) : 'Bot');
  if (!persona) return c.json({ error: 'The persona builder isn\'t available right now (no model answered). Your text is unchanged.' }, 503);
  return c.json({ persona });
});

// "Let Mercury decide": one bot or a fleet for this job, and the proposed crew. Nothing is created.
app.post('/api/bots/plan', async (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const body = (await c.req.json().catch(() => ({}))) as { name?: unknown; description?: unknown; persona?: unknown; fleet?: unknown };
  const str = (v: unknown, n: number) => (typeof v === 'string' ? v.slice(0, n) : '');
  // fleet: true = the owner chose a fleet; only the crew is being designed.
  const plan = await botManager.planShape({ name: str(body.name, 60) || 'Bot', description: str(body.description, 300), persona: str(body.persona, 8000), fleet: body.fleet === true });
  return c.json({ plan, maxCrew: botManager.maxCrew() });
});

// Bots asking the owner mid-run: what's waiting, and the answer.
app.get('/api/bots/approvals', (c: Context) => {
  if (!botManager) return c.json({ approvals: [], available: false });
  return c.json({ approvals: botManager.approvals.list(c.req.query('bot') || undefined), available: true });
});

app.post('/api/bots/approvals/:id', async (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const body = (await c.req.json().catch(() => ({}))) as { answer?: unknown };
  if (body.answer !== 'yes' && body.answer !== 'always' && body.answer !== 'no') return c.json({ error: 'answer must be yes, always or no' }, 400);
  if (!botManager.approvals.answer(c.req.param('id') ?? '', body.answer)) {
    return c.json({ error: 'That question is no longer waiting (answered, timed out, or the run ended).' }, 409);
  }
  return c.json({ ok: true });
});

// Mark read: { ids: [...] } for some entries, {} for everything.
app.post('/api/bots/inbox/read', async (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const body = (await c.req.json().catch(() => ({}))) as { ids?: unknown };
  const ids = Array.isArray(body.ids) ? body.ids.filter((x): x is string => typeof x === 'string').slice(0, 1000) : undefined;
  botManager.inbox.markRead(ids);
  return c.json({ ok: true, unread: botManager.inbox.unread() });
});

// Onboard a bot
/** Tiers that run commands or reach the whole home folder: from another device, the owner decides. */
const POWERFUL_TIERS = new Set(['operator', 'full']);
function gateTier(c: any, tier: string | undefined, botId: string): Response | null {
  if (!tier || !POWERFUL_TIERS.has(tier)) return null;
  return requireOwner(c, { id: `bots.tier:${botId}:${tier}`, title: `Give the bot “${botId}” ${tier === 'full' ? 'full access to this computer' : 'permission to run commands'}` });
}

app.post('/api/bots', async (c: any) => {
  if (!botManager) {
    return c.json({ error: 'Bots not available' }, 400);
  }
  const body = await c.req.json().catch(() => null) as
    { id?: string; name?: string; description?: string; persona?: string; tier?: string; manifest?: Partial<BotManifest> } | null;
  if (!body?.id || !body?.name) {
    return c.json({ error: 'id and name are required' }, 400);
  }
  if (body.tier !== undefined && !isPermissionTier(body.tier)) {
    return c.json({ error: `Unknown permission tier: ${body.tier}` }, 400);
  }
  const tierWait = gateTier(c, body.tier, String(body.id));
  if (tierWait) return tierWait;
  try {
    const manifest = botManager.store.create({
      id: body.id,
      name: body.name,
      description: body.description,
      persona: body.persona,
      manifest: body.manifest,
    });
    // Tiers execute (§2.5): the chosen tier writes the full permissions.yaml
    // — tool gate AND path scopes. A tier choice that only flipped the tool
    // gate left bots unable to act.
    if (body.tier) {
      botManager.store.writePermissions(manifest.id, tierPermissionsFile(body.tier as PermissionTier));
    }
    botManager.invalidateRuntime(manifest.id);
    return c.json({ bot: manifest }, 201);
  } catch (err: any) {
    return c.json({ error: err?.message ?? 'Failed to create bot' }, 400);
  }
});

// ── Real-time fleet feed (SSE) ──────────────────────────────────────────────
// Mirrors the Kanban events route: one connection per browser tab, roster
// snapshot on connect, live bot_activity + bot_deliverable events from the
// in-process activity bus, keepalive, cleanup on abort. The web dashboard
// rides the same bus as the CLI's bot-thread live region.

/** Open fleet-feed clients — roster mutations (add crew, promote, delete) push fresh snapshots. */
const rosterSseClients = new Set<{ send: (event: string, data: unknown) => void }>();

/**
 * Subscribes a client to the fleet feed, and returns its unsubscribe.
 *
 * Exported so a test can stand where a browser tab stands: the point of the broadcast below is that
 * *someone else's* screen updates, which no assertion on the PATCH response can show.
 */
export function registerRosterClient(client: { send: (event: string, data: unknown) => void }): () => void {
  rosterSseClients.add(client);
  return () => { rosterSseClients.delete(client); };
}

function broadcastRoster(): void {
  if (!botManager) return;
  for (const client of rosterSseClients) {
    client.send('bot_roster', { bots: botManager.getStatusSummaries(), queue: botManager.queue.counts() });
  }
}

app.get('/api/bots/events', (c: any) => {
  const bm = botManager;
  if (!bm) return c.json({ error: 'Bots not available' }, 400);
  const stream = new ReadableStream({
    start(controller) {
      const encoder = new TextEncoder();
      const controllerRef = controller;
      const client = { send: (event: string, data: unknown) => {
        try {
          controllerRef.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
        } catch {
          // client disconnected — abort handler cleans up
        }
      } };

      // Snapshot on connect so the UI paints immediately (no first-event wait).
      client.send('bot_roster', { bots: bm.getStatusSummaries(), queue: bm.queue.counts() });
      rosterSseClients.add(client);

      const unsubscribe = bm.onBotActivity((ev) => client.send('bot_activity', ev));
      // A new inbox entry: the desktop turns it into a notification.
      const unsubscribeInbox = bm.inbox.onEntry((entry) => client.send('bot_inbox', entry));
      // A bot asked, or its question was answered / timed out: the app shows or clears the buttons.
      const unsubscribeApprovals = bm.approvals.onChange((e) => client.send('bot_approval', e));

      const keepalive = setInterval(() => {
        try { controller.enqueue(encoder.encode(': keepalive\n\n')); } catch { clearInterval(keepalive); }
      }, 15000);

      const cleanup = () => {
        clearInterval(keepalive);
        unsubscribe();
        unsubscribeInbox();
        unsubscribeApprovals();
        rosterSseClients.delete(client);
        untrack();
      };
      const untrack = trackStream(principalKey(principalOf(c)), () => { cleanup(); try { controller.close(); } catch { /* closed */ } });
      c.req.raw.signal?.addEventListener('abort', cleanup);
    },
    cancel() {},
  });
  return new Response(stream, {
    headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive' },
  });
});

// ── Deliverables (owner-curated outputs zone — bot_deliver) ────────────────
// Where results land — the fleet root and one bot's folder (ADR-020). The
// dashboard shows the path and, since it runs on the owner's machine, can
// open the folder in the file manager.
app.get('/api/bots/folder', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const dir = botManager.store.deliverablesRoot();
  return c.json({ path: dir, display: tildify(dir), exists: existsSync(dir) });
});

app.get('/api/bots/:id/folder', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = String(c.req.param('id') ?? '');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const dir = botManager.store.deliverablesDir(id);
  return c.json({ path: dir, display: tildify(dir), exists: existsSync(dir) });
});

app.post('/api/bots/folder/open', async (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const dir = botManager.store.deliverablesRoot();
  mkdirSync(dir, { recursive: true });
  return c.json({ ok: await openFolder(dir), path: dir });
});

app.post('/api/bots/:id/folder/open', async (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = String(c.req.param('id') ?? '');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const dir = botManager.store.deliverablesDir(id);
  mkdirSync(dir, { recursive: true });
  return c.json({ ok: await openFolder(dir), path: dir });
});

// Fleet-wide inbox, newest first.
app.get('/api/bots/outputs', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  return c.json({ outputs: botManager.listDeliverables() });
});

// ── Tier catalog for the onboarding wizard ──────────────────────────────────
app.get('/api/bots/tiers', (c: any) => {
  const tiers = Object.entries(PERMISSION_TIERS).map(([id, t]) => ({
    id, label: t.label, description: t.description, deny: t.deny,
  }));
  return c.json({ tiers });
});

// Import a shared bundle (bots start disabled — review before enabling).
app.post('/api/bots/import', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const bundle = await c.req.json().catch(() => null) as any;
  if (!bundle) return c.json({ error: 'Invalid JSON body' }, 400);
  // A bundle brings its own permissions and schedules.
  const importWait = requireOwner(c, { id: 'bots.import', title: 'Import bots (with their own permissions and schedules)' });
  if (importWait) return importWait;
  try {
    const report = importBotBundle(botManager.store, bundle, c.req.query('overwrite') === '1' ? { overwrite: true } : {});
    for (const created of report.created) botManager.invalidateRuntime(created);
    return c.json({ report });
  } catch (err: any) {
    return c.json({ error: err?.message ?? 'Invalid bundle' }, 400);
  }
});

// Single bot detail (manifest + live state + journal tail)
app.get('/api/bots/:id', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  let manifest;
  try {
    manifest = botManager.store.get(id);
  } catch {
    return c.json({ error: 'Bot not found' }, 404);
  }
  if (!manifest) return c.json({ error: 'Bot not found' }, 404);
  const summary = botManager.getStatusSummaries().find(s => s.id === id) ?? null;
  return c.json({
    bot: manifest,
    state: summary,
    journal: botManager.getJournal(id, 10),
    inbox: botManager.peekMailbox(id),
  });
});

// Patch config (enable/disable, model, tools, memory, comms, schedules)
app.patch('/api/bots/:id', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  const patch = await c.req.json().catch(() => null) as Partial<BotManifest> | null;
  if (!patch) return c.json({ error: 'Invalid JSON body' }, 400);
  if (patch.schedules !== undefined) {
    const problem = scheduleProblem(patch.schedules);
    if (problem) return c.json({ error: problem }, 400);
  }
  const previousRoutines = (botManager.store.get(id)?.schedules ?? []).map((r) => r.name);
  try {
    const updated = botManager.store.update(id, m => {
      // The id is the identity and stays immutable: directories, crew links, journals, threads and
      // avatars are all keyed by it. The name is a label the owner reads, so it is mutable — a bot
      // created with a placeholder name was stuck with it forever, and editing bot.yaml behind the
      // API's back (the only way until now) needs a daemon restart.
      if (patch.name !== undefined) {
        const name = typeof patch.name === 'string' ? patch.name.replace(/\s+/g, ' ').trim() : '';
        if (!name) throw new Error('Bot name must not be empty');
        m.name = name.slice(0, 60);
      }
      if (patch.enabled !== undefined) m.enabled = patch.enabled;
      if (patch.description !== undefined) m.description = patch.description;
      // null clears the choice: back to Mercury's default model.
      if (patch.model !== undefined) { if (patch.model) m.model = patch.model; else delete m.model; }
      if (patch.tools !== undefined) m.tools = patch.tools;
      if (patch.memory !== undefined) m.memory = patch.memory;
      if (patch.comms !== undefined) m.comms = patch.comms;
      if (patch.schedules !== undefined) m.schedules = patch.schedules;
      if (patch.autonomy !== undefined) m.autonomy = patch.autonomy;
      if (patch.retention !== undefined) m.retention = patch.retention;
    });
    botManager.invalidateRuntime(id);
    // Edited routines take effect now, not at the next restart.
    if (patch.schedules !== undefined || patch.enabled !== undefined) botManager.syncRoutines(id, previousRoutines);
    // A config edit is roster news: the name, the description, the model, the enabled flag and the
    // autonomy limits all travel in the summaries. Without this, an open drawer kept the old name
    // until some unrelated roster change happened — the edit looked like it had not been applied.
    broadcastRoster();
    return c.json({ bot: updated });
  } catch (err: any) {
    return c.json({ error: err?.message ?? 'Failed to update bot' }, 400);
  }
});

// Message a bot (durable enqueue; returns the job id immediately)
app.post('/api/bots/:id/message', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  const body = await c.req.json().catch(() => null) as
    { message?: string; from?: string; attachments?: unknown } | null;

  // Bytes on the wire, written before the job exists: the queue stores paths, and a
  // bot turn reads them exactly like a channel attachment.
  const upload = storeInlineAttachments(body?.attachments);
  if (!upload.ok) return c.json({ error: upload.error }, 400);

  const message = body?.message?.trim() ?? '';
  if (!message && upload.attachments.length === 0) {
    for (const a of upload.attachments) rmSync(a.path, { force: true });
    return c.json({ error: 'message is required' }, 400);
  }

  const result = botManager.enqueue(id, {
    trigger: 'api',
    prompt: message,
    fromBot: body?.from,
    attachments: upload.attachments.length > 0 ? upload.attachments : undefined,
  });
  if (!result.accepted) {
    // The turn will never run: its files must not stay in uploads.
    for (const a of upload.attachments) rmSync(a.path, { force: true });
    return c.json({ accepted: false, reasonCode: result.reasonCode }, 409);
  }
  if (!result.duplicated) botManager.noteOwnerMessage(id, result.jobId, message || '(attachments)');
  if (result.duplicated) {
    // A retry of a job already queued: that job holds its own copies of the files.
    for (const a of upload.attachments) rmSync(a.path, { force: true });
  }
  return c.json({
    accepted: true,
    jobId: result.jobId,
    status: 'accepted',
    ...(upload.attachments.length > 0 ? { attachments: upload.attachments.map(a => ({ name: a.name, kind: a.kind })) } : {}),
  }, 202);
});

// Inbox (pending bot-to-bot mail)
app.get('/api/bots/:id/inbox', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  return c.json({ inbox: botManager.peekMailbox(c.req.param('id')) });
});

// Run journal
app.get('/api/bots/:id/journal', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const limit = parseInt(c.req.query('limit') ?? '20', 10);
  return c.json({ journal: botManager.getJournal(c.req.param('id'), limit) });
});

// Dead-letter queue + replay
app.get('/api/bots/:id/dlq', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  return c.json({ dlq: botManager.getDlq(c.req.param('id')) });
});

app.post('/api/bots/:id/replay/:jobId', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const result = botManager.replayDlq(c.req.param('id'), c.req.param('jobId'));
  if (!result.accepted) return c.json(result, 404);
  return c.json({ ...result, status: 'accepted' });
});

// Enable/disable/stop/start controls
app.post('/api/bots/:id/enable', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  try {
    botManager.setEnabled(c.req.param('id'), true);
    return c.json({ ok: true });
  } catch (err: any) {
    return c.json({ error: err?.message }, 400);
  }
});

app.post('/api/bots/:id/disable', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  try {
    botManager.setEnabled(c.req.param('id'), false);
    return c.json({ ok: true });
  } catch (err: any) {
    return c.json({ error: err?.message }, 400);
  }
});

app.post('/api/bots/:id/stop', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const result = await botManager.stop(c.req.param('id'));
  return c.json({ ok: true, halted: result.halted, heldJobs: result.heldJobs, message: haltedMessage(result) });
});

app.post('/api/bots/:id/start', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  try {
    const result = botManager.start(c.req.param('id'));
    return c.json({ ok: true, resumed: result.resumed, message: result.resumed > 0 ? `Resumed ${result.resumed} held job(s)` : 'Nothing held — bot is ready' });
  } catch (err: any) {
    return c.json({ error: err?.message }, 404);
  }
});

// Fleet semantics — the CLI parity paths (§2.5 / agent.ts offerFleetStep):
// promote → lead; auto-build the matched crew detached with live roster
// broadcasts (30-90s of LLM proposal — the dashboard shows crew cards the
// moment each is created).
app.post('/api/bots/:id/promote', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const result = botManager.promoteLead(id);
  if (!result.ok) return c.json({ error: 'Bot not found' }, 404);
  broadcastRoster();
  return c.json({ ok: true, message: 'Bot is now a fleet lead — it can add/retire crew itself (bot_spawn), or you add specialists from its Ops panel.' });
});

app.post('/api/bots/:id/autocrew', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const bm = botManager;
  bm.autoCrew(id, {
    onMember: (_name, _memberId) => broadcastRoster(),
    onError: (msg) => {
      for (const client of rosterSseClients) client.send('bot_notice', { message: msg });
      broadcastRoster();
    },
    onDone: () => {
      for (const client of rosterSseClients) client.send('bot_notice', { message: `Fleet ready — ${bm.getStatusSummaries().filter((s) => s.parent === id).length} crew member(s) created. Dispatch tasks to any crew bot.` });
      broadcastRoster();
    },
  });
  return c.json({ accepted: true, status: 'building' }, 202);
});

// Fire a routine now (body { routine }) or send a bare wake turn
app.post('/api/bots/:id/run', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const body = await c.req.json().catch(() => null) as { routine?: string } | null;
  const result = botManager.runNow(c.req.param('id'), body?.routine);
  if (!result.accepted) return c.json(result, result.reasonCode === 'routine_unknown' ? 404 : 409);
  return c.json({ ...result, status: 'accepted' }, 202);
});

// Fleet views: crew roster of a lead + add-crew
app.get('/api/bots/:id/crew', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.isLead(id)) return c.json({ error: 'Not a fleet lead' }, 400);
  return c.json({
    lead: botManager.store.get(id),
    crew: botManager.store.crewOf(id),
    maxCrew: botManager.maxCrew(),
  });
});

app.post('/api/bots/:id/crew', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  const body = await c.req.json().catch(() => null) as { id?: string; name?: string; description?: string; persona?: string; tier?: string } | null;
  if (!body?.id || !body?.name) return c.json({ error: 'id and name are required' }, 400);
  if (body.tier !== undefined && !isPermissionTier(body.tier)) {
    return c.json({ error: `Unknown permission tier: ${body.tier}` }, 400);
  }
  const tierWait = gateTier(c, body.tier, String(body.id));
  if (tierWait) return tierWait;
  const result = botManager.addCrew(id, { id: body.id, name: body.name, description: body.description, persona: body.persona });
  if (!result.ok) return c.json({ error: result.error }, 400);
  // A tier choice overrides the crew's verbatim lead inheritance (§2.5:
  // inherit-unless-edited — an explicit tier IS an edit).
  if (body.tier) {
    botManager.store.writePermissions(result.manifest.id, tierPermissionsFile(body.tier as PermissionTier));
  }
  return c.json({ bot: result.manifest }, 201);
});

// Persona (character file) — read + write
app.get('/api/bots/:id/persona', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  return c.json({ persona: botManager.store.readPersona(id) });
});

app.put('/api/bots/:id/persona', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const body = await c.req.json().catch(() => null) as { persona?: string } | null;
  if (typeof body?.persona !== 'string' || !body.persona.trim()) {
    return c.json({ error: 'persona (non-empty string) is required' }, 400);
  }
  try {
    botManager.store.writePersona(c.req.param('id'), body.persona);
    botManager.invalidateRuntime(c.req.param('id'));
    return c.json({ ok: true });
  } catch (err: any) {
    return c.json({ error: err?.message ?? 'Bot not found' }, 404);
  }
});

// Avatar (a bot's face) — bytes in, bytes out. Stored as one extension-less
// file in the bot's profile dir, so the format is always the real one and
// deleting the bot deletes its face. Clients that get no avatar draw a
// monogram from the id; `hasAvatar` in the roster tells them which without a
// probe per bot.
app.get('/api/bots/:id/avatar', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const bytes = botManager.store.readAvatar(id);
  if (!bytes) return c.json({ error: 'Bot has no avatar' }, 404);

  const mime = detectImage(bytes);
  if (!mime) {
    // On disk but unreadable as an image: say so rather than serve a broken face.
    return c.json({ error: 'Stored avatar is not a readable image' }, 500);
  }
  const etag = `W/"${bytes.length}-${Math.round(botManager.store.avatarMtimeMs(id))}"`;
  if (c.req.header('If-None-Match') === etag) return c.body(null, 304);
  return c.body(new Uint8Array(bytes), 200, {
    'Content-Type': mime,
    'Content-Length': String(bytes.length),
    'Cache-Control': 'private, max-age=0, must-revalidate',
    // The bytes were sniffed as an image; the browser must not re-sniff them as HTML.
    'X-Content-Type-Options': 'nosniff',
    ETag: etag,
  });
});

app.put('/api/bots/:id/avatar', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const body = await c.req.json().catch(() => null);
  const avatar = decodeAvatarInput(body);
  if (!avatar.ok) return c.json({ error: avatar.error }, 400);
  try {
    botManager.store.writeAvatar(id, avatar.bytes);
    // The roster carries `hasAvatar`, so every open dashboard learns the face
    // changed without another request.
    broadcastRoster();
    return c.json({ ok: true, mime: avatar.mime, bytes: avatar.bytes.length });
  } catch (err: any) {
    return c.json({ error: err?.message ?? 'Could not store the avatar' }, 400);
  }
});

app.delete('/api/bots/:id/avatar', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const removed = botManager.store.removeAvatar(id);
  if (removed) broadcastRoster();
  return c.json({ ok: true, removed });
});

// Permissions.yaml — the single source of truth (tool gate, path scopes,
// shell lists). PUT with a tier applies the tier wholesale; PUT with a
// full document is the "custom" path. Fleet inheritance: a crew bot shows
// its inherited file; writing creates its own explicit copy.
app.get('/api/bots/:id/permissions', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  return c.json({ permissions: botManager.store.readPermissions(id) });
});

app.put('/api/bots/:id/permissions', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const body = await c.req.json().catch(() => null) as { tier?: string; permissions?: any } | null;
  const permWait = body?.permissions !== undefined
    ? requireOwner(c, { id: `bots.permissions:${c.req.param('id')}`, title: `Rewrite the permissions of the bot “${c.req.param('id')}”` })
    : gateTier(c, body?.tier, c.req.param('id'));
  if (permWait) return permWait;
  if (!body) return c.json({ error: 'Invalid JSON body' }, 400);
  try {
    if (body.tier !== undefined) {
      if (!isPermissionTier(body.tier)) return c.json({ error: `Unknown permission tier: ${body.tier}` }, 400);
      botManager.store.writePermissions(id, tierPermissionsFile(body.tier as PermissionTier));
    } else if (body.permissions !== undefined) {
      botManager.store.writePermissions(id, body.permissions);
    } else {
      return c.json({ error: 'Supply tier or permissions' }, 400);
    }
    botManager.invalidateRuntime(id);
    return c.json({ permissions: botManager.store.readPermissions(id) });
  } catch (err: any) {
    return c.json({ error: err?.message ?? 'Invalid permissions document' }, 400);
  }
});

// Shareable bundle (identity + persona + permissions + skills; a lead's
// bundle carries its whole crew). Delivered as an attachment download.
app.get('/api/bots/:id/bundle', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  try {
    const bundle = buildBotBundle(botManager.store, id, { withSkills: true });
    const json = JSON.stringify(bundle, null, 2);
    return new Response(json, {
      headers: {
        'Content-Type': 'application/json',
        'Content-Disposition': `attachment; filename="${id}-bundle.json"`,
      },
    });
  } catch (err: any) {
    return c.json({ error: err?.message ?? 'Failed to build bundle' }, 400);
  }
});

// Token spend per bot and fleet (ADR-022)
app.get('/api/bots-cost', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const days = Math.max(1, Math.min(90, parseInt(c.req.query('days') ?? '7', 10) || 7));
  return c.json(botManager.costReport(days));
});

// Fleet kill switch
app.post('/api/bots-stop-all', async (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  return c.json(await botManager.stopAll());
});
app.post('/api/bots-start-all', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  return c.json(botManager.startAll());
});

// Drop dead-lettered jobs (all, or ?bot=<id>)
app.delete('/api/bots-dlq', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const bot = c.req.query('bot') || undefined;
  if (bot && !botManager.store.exists(bot)) return c.json({ error: 'Bot not found' }, 404);
  return c.json({ cleared: botManager.clearDlq(bot) });
});

// A lead's delegated tasks
app.get('/api/bots/:id/tasks', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  if (!botManager.store.exists(String(c.req.param('id') ?? ''))) return c.json({ error: 'Bot not found' }, 404);
  return c.json({ tasks: botManager.tasksFor(String(c.req.param('id') ?? '')) });
});

// Run transcripts: list, and one run (newest when runId is "latest")
app.get('/api/bots/:id/runs', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  if (!botManager.store.exists(String(c.req.param('id') ?? ''))) return c.json({ error: 'Bot not found' }, 404);
  return c.json({ runs: botManager.listTranscripts(String(c.req.param('id') ?? '')) });
});
app.get('/api/bots/:id/runs/:runId', (c: Context) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = String(c.req.param('id') ?? '');
  if (!botManager.store.exists(id)) return c.json({ error: 'Bot not found' }, 404);
  const runId = String(c.req.param('runId') ?? '');
  const t = botManager.readTranscript(id, runId === 'latest' ? undefined : runId);
  if (!t) return c.json({ error: 'Transcript not found' }, 404);
  return c.json(t);
});

// This bot's deliverables
app.get('/api/bots/:id/outputs', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  if (!botManager.store.exists(c.req.param('id'))) return c.json({ error: 'Bot not found' }, 404);
  return c.json({ outputs: botManager.listDeliverables(c.req.param('id')) });
});

// Text preview of a deliverable (≤64KB)
app.get('/api/bots/:id/outputs/:name/preview', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const result = botManager.readDeliverable(c.req.param('id'), c.req.param('name'));
  if (!result.found) return c.json({ error: 'Deliverable not found' }, 404);
  return c.json({ preview: result.preview ?? '', truncated: !!result.truncated });
});

// Byte-exact download of a deliverable (content-type guessed from ext).
app.get('/api/bots/:id/outputs/:name/download', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  const name = c.req.param('name');
  const file = botManager.deliverableFile(id, name);
  if (!file) return c.json({ error: 'Deliverable not found' }, 404);
  try {
    const buf = readFileSync(file);
    const ext = (name.split('.').pop() ?? '').toLowerCase();
    const mime = MIME_BY_EXT[ext] ?? 'application/octet-stream';
    return new Response(new Uint8Array(buf), {
      headers: {
        'Content-Type': mime,
        'Content-Disposition': `attachment; filename="${name}"`,
      },
    });
  } catch {
    return c.json({ error: 'Deliverable not found' }, 404);
  }
});

// Owner curation: remove a deliverable
app.delete('/api/bots/:id/outputs/:name', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const result = botManager.deleteDeliverable(c.req.param('id'), c.req.param('name'));
  if (!result.ok) return c.json({ error: 'Deliverable not found' }, 404);
  return c.json({ ok: true });
});

function haltedMessage(result: { halted: boolean; heldJobs: number }): string {
  const base = result.halted ? 'Halt signal sent' : 'Nothing running';
  return result.heldJobs > 0 ? `${base}; ${result.heldJobs} queued job(s) held` : base;
}

// Storage view
app.get('/api/bots-storage', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  return c.json({ usage: botManager.getStorage(), queue: botManager.queue.counts() });
});

// Delete a bot entirely (profile dir removed)
app.delete('/api/bots/:id', (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  try {
    void botManager.halt(id);
    botManager.store.delete(id);
    botManager.invalidateRuntime(id);
    return c.json({ ok: true });
  } catch (err: any) {
    return c.json({ error: err?.message }, 400);
  }
});

// Generic webhook ingress: validate → dedupe → durable enqueue, ack fast
// (BOTS-ARCHITECTURE §2.3). Callers: external systems pushing events into a
// bot (e.g. an RSS monitor or CI pipeline waking the researcher bot).
app.post('/api/bots/:id/hooks/:hook', async (c: any) => {
  if (!botManager) return c.json({ error: 'Bots not available' }, 400);
  const id = c.req.param('id');
  // Auth: shared secret header when configured (webhook callers have no
  // browser session); otherwise the normal authGuard already applied.
  if (webhookSecret) {
    const provided = c.req.header('x-mercury-hook-secret');
    if (provided !== webhookSecret) {
      return c.json({ error: 'Invalid hook secret' }, 401);
    }
  }
  let text: string;
  if (contentTypeIsJson(c.req.header('content-type'))) {
    const body = await c.req.json().catch(() => null);
    if (!body) return c.json({ error: 'Invalid JSON body' }, 400);
    text = typeof body.text === 'string' ? body.text : JSON.stringify(body);
  } else {
    text = await c.req.text();
  }
  if (!text.trim()) return c.json({ error: 'Empty payload' }, 400);
  // Idempotency: an explicit event id joins the prompt, so the queue's
  // idempotency key dedupes redeliveries of the same event.
  const eventId = c.req.header('x-event-id');
  const prompt = eventId ? `[hook:${c.req.param('hook')}:${eventId}] ${text}` : `[hook:${c.req.param('hook')}] ${text}`;
  const result = botManager.enqueue(id, { trigger: 'api', prompt });
  if (!result.accepted) {
    return c.json({ accepted: false, reasonCode: result.reasonCode }, 409);
  }
  return c.json({ accepted: true, jobId: result.jobId, status: 'accepted' }, 202);
});

function contentTypeIsJson(value: string | undefined): boolean {
  return (value ?? '').split(';')[0].trim().toLowerCase() === 'application/json';
}

const MIME_BY_EXT: Record<string, string> = {
  txt: 'text/plain', md: 'text/markdown', json: 'application/json', yaml: 'application/yaml', yml: 'application/yaml',
  csv: 'text/csv', pdf: 'application/pdf', html: 'text/html', svg: 'image/svg+xml',
  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp',
  zip: 'application/zip', tar: 'application/x-tar', gz: 'application/gzip',
};

export default app;

/** What's wrong with an edited schedule list, or null. Each routine: a name, a valid cron, a prompt. */
function scheduleProblem(schedules: unknown): string | null {
  if (!Array.isArray(schedules)) return 'schedules must be a list';
  const names = new Set<string>();
  for (const r of schedules as Array<Record<string, unknown>>) {
    const name = typeof r?.name === 'string' ? r.name.trim() : '';
    if (!/^[a-z0-9][a-z0-9-]{0,40}$/i.test(name)) return `Routine name "${name}" must be letters, numbers and dashes`;
    if (names.has(name)) return `Two routines are called "${name}"`;
    names.add(name);
    if (typeof r.cron !== 'string' || !isValidCronExpression(r.cron)) return `"${name}": "${String(r.cron)}" isn't a valid schedule`;
    if (typeof r.prompt !== 'string' || !r.prompt.trim()) return `"${name}" needs instructions`;
  }
  return null;
}