Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
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;
}