Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
/**
* The API contract between a Mercury runtime and every client that is not
* shipped inside the same binary: Mercury Desktop, the phone apps, scripts.
*
* Two numbers exist and they move independently:
*
* - the PACKAGE version (`package.json`, `/api/health.version`) — what to
* print in an About box and what `mercury upgrade` compares;
* - the API VERSION (`API_VERSION`, `/api/health.apiVersion`) — a single
* integer bumped ONLY on a change a client cannot tolerate: a removed or
* renamed route, a changed response shape, a changed auth scheme.
*
* Additive changes never bump the integer. They add a FEATURE flag instead,
* and clients gate UI on the flag. A client declares the range of API
* versions it understands; outside that range it tells the user to update
* one side or the other. `docs/api-contract.md` records which runtime
* release introduced each version.
*/
export const API_VERSION = 1;
/**
* Capabilities a client may rely on. Order is irrelevant; names are stable
* once published (remove = bump API_VERSION).
*/
export const API_FEATURES: readonly string[] = Object.freeze([
'auth.devices', // device tokens: POST /api/auth/token, GET/DELETE /api/auth/devices
'chat.sse', // GET /api/chat/events (Server-Sent Events)
'chat.attachments', // multipart uploads on POST /api/chat/send
'bots', // /api/bots/*
'plugins', // /api/plugins/*
'mcp', // /api/mcp/*
'boards', // /api/boards/*
'brain', // /api/brain/*
'code.session', // POST /api/chat/send { programming, cwd } — per-session coding
'chat.uploads', // attachments on messages + GET /api/chat/uploads/:month/:file
'voice', // /api/voice, /api/voice/events, /api/voice/control (Optimus)
'devices', // /api/devices: desktop plugins' permissions, microphone choice and test
'usage.history', // GET /api/usage/history?days= — tokens per local day
'brain.people', // PATCH/merge persons, person checks, GET /api/brain/graph/v2
'chat.stop', // POST /api/chat/stop — interrupt the running turn (same as /stop)
'providers.manage', // GET /api/providers/settings, POST /api/providers/:id/check (live, unsaved), PUT /api/providers/roles; saves apply live; health.setupRequired
'voice.check',
'artifacts', // GET /api/artifacts (paged), /:id, /:id/file (Range), POST /:id/export, DELETE /:id; SSE 'artifacts'; message.artifacts
'chat.activity', // GET /api/chat/activity (SSE: started, needs_you, resolved, done, stopped, failed per session), GET /api/chat/pending?sessionId
'chat.plan', // SSE 'plan' { steps, updatedAt } + GET /api/chat/plan?sessionId= (the plan checklist)
'channels', // GET /api/channels, POST :type/check, PUT :type, POST :type/access, POST/GET signal/link
'transcribe', // GET/POST /api/transcribe — dictation: raw audio in, text out
'speak', // GET/POST /api/speak — read aloud: text in, MP3 out
'budget', // GET/PUT /api/budget — daily cap, Token Saver, bot caps; saves apply live
'threads.save', // POST /api/chat/threads/:id/save { saved } — thread.savedAt
'cloud.signin', // GET /api/cloud/status, POST/GET/DELETE /api/cloud/signin (browser pairing from any client) // POST /api/voice/check { vendor, key?, endpoint? }
'brain.map', // GET /api/brain/map[?archive=1] — themes, sub-themes, notes, related links
'artifacts.convert', // GET /api/artifacts/:id/file?as=pdf|docx, POST /api/artifacts/:id/export { dest, as } — Markdown/text as PDF or Word
'artifacts.folder', // GET /api/artifacts/folder (the output folder, loose files), POST /api/artifacts/folder/tidy
'suggestions', // GET /api/suggestions?n= (greeting, subtitle, items {id,title,prompt,why,kind}), POST /api/suggestions/:id/used
'artifacts.cleanup', // GET /api/artifacts/usage, POST /api/artifacts/delete { ids | kind, olderThanDays, threadId | all }; DELETE removes Mercury-owned originals too
'chat.favicon', // GET /api/chat/favicon?domain= — a site's icon (204 when it has none), fetched and cached by the runtime
'security.remote', // device pairing needs the owner (202 + POST /api/auth/token/pending), sensitive remote actions 428 + X-Mercury-Approval, /api/security/* (this computer), SSE 'owner_approval' (local activity), expired devices 401 { expired }
'updates', // GET /api/updates[?seen=1], POST /api/updates/check, POST /api/updates/server { version?, now? } (202; remote → 428 owner), POST /api/updates/server/cancel — see UPDATES.md
'chat.running', // GET /api/chat/running (running + waiting chats, limit), PUT /api/chat/concurrency { maxTurns } — ADR-037; SSE 'queue_dropped' (ADR-038)
'budget.split', // GET /api/budget daily.split + daily.cachedWeight, PUT { cachedWeight }; /api/usage split + counted breakdowns — #296
'chat.usage', // message.usage on assistant replies; text_done { usage } — what each reply cost
'chat.effort', // POST /api/chat/effort, GET /api/chat/models?sessionId= current.effort — per-chat effort (#188)
'media.image', // GET /api/media/models, PUT /api/media/default; POST /api/chat/send { media: { kind: "image", aspect? } } (ADR-042)
'media.jobs', // GET /api/media/models video, music; PUT /api/media/default { kind: video|music }; SSE 'media_ready' { text, artifacts }; send { media: { kind: video|music } } (ADR-042 phase 3)
'media.speech', // GET /api/media/models speech { options, current, choice, voice, replies }, PUT /api/media/speech (ADR-042 phase 2)
'chat.trace', // live step ids/durations, progress/phase events, message.trace on replies (ADR-041); GET /api/chat/threads/:id/live (a running reply so far)
'chat.research', // SSE 'research' / 'research_plan' / 'research_plan_resolved' / 'notice'; GET /api/chat/threads/:id/research, POST …/research/finish, …/research/off, POST /api/chat/research/plan/:id; message.research; step_done { failed, reason }
]);
export interface ApiContractInfo {
apiVersion: number;
features: readonly string[];
}
export function apiContract(): ApiContractInfo {
return { apiVersion: API_VERSION, features: API_FEATURES };
}