Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
import { refinePersona } from './persona-template.js';
import { createHash, randomUUID } from 'node:crypto';
import { homedir } from 'node:os';
import { basename, extname, isAbsolute, relative, resolve, join } from 'node:path';
import { writeFileSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, rmSync } from 'node:fs';
import type { Tool } from 'ai';
import type { ChannelAttachment } from '../types/channel.js';
import type { MercuryConfig } from '../utils/config.js';
import type { ProviderRegistry } from '../providers/registry.js';
import type { TokenBudget } from '../utils/tokens.js';
import type { CapabilityRegistry } from '../capabilities/registry.js';
import type { UserMemoryStore } from '../memory/user-memory.js';
import { UserMemoryStore as UserMemoryStoreImpl } from '../memory/user-memory.js';
import { BotInbox } from './inbox.js';
import { BotApprovals, durableGrant } from './approvals.js';
import { detectTier } from './permission-tiers.js';
import { BotStore, deliverableFileName, BOT_JOURNAL_FILENAME, BOT_PERMISSIONS_FILENAME, isValidCronExpression, MAX_FLEET_DEPTH, BOT_SHARED_SANDBOX_DIRNAME } from './store.js';
import { BotJournal, type BotTranscript, type BotUsage } from './journal.js';
import { BotQueue, idempotencyKeyFor, LEASE_SECONDS, type DurableBotJob } from './queue.js';
import { sweepSharedSandbox } from './retention.js';
import { planBotShape, proposeCrew, type BotShapePlan } from './fleet-onboarding.js';
import { createBotCapabilityRegistry, filterBotTools } from './registry-factory.js';
import { createBotSendTool } from './tools/bot-send.js';
import { BotTaskStore, renderTaskPrompt, renderBatchDigest, isTerminalTask, type BotTask, type BotTaskResult } from './tasks.js';
import { createFleetDelegateTool, createFleetTasksTool, createFleetPipelineTool } from './tools/fleet-tasks.js';
import { createBotStateTool } from './tools/bot-state.js';
import { extractBotMemories } from './memory-extract.js';
import { runBotDoctor, type DoctorReport } from './doctor.js';
import { createBotDeliverTool } from './tools/bot-deliver.js';
import { createBotScheduleTool, type BotScheduler } from './tools/bot-schedule.js';
import { createFleetStatusTool } from './tools/fleet-status.js';
import { createBotSpawnTool } from './tools/bot-spawn.js';
import { runBotTurn, isTransientFailure, isTurnLimitFailure, taintOf, type BotExpectedOutcome, type BotTurnMail, type BotActivityEvent, type BotTaint } from './bot-turn.js';
import { guardTools } from '../security/tool-guard.js';
import { parsePersonaAccess, stripPersonaAccessSection } from './persona-access.js';
import { mergePathScopes } from './registry-factory.js';
import { synthesizeSkill, MIN_TOOLS_FOR_SYNTHESIS } from './skill-synthesis.js';
import { SkillLoader } from '../skills/loader.js';
import { logger } from '../utils/logger.js';
import { resolveToolPath, type CwdSource } from '../capabilities/filesystem/resolve-path.js';
import type {
BotLiveState,
BotManifest,
BotRunRecord,
BotStatusSummary,
BotTrigger,
} from './types.js';
export interface BotJob {
id: string;
botId: string;
trigger: BotTrigger;
prompt: string;
/** Mailbox attribution — set for bot-to-bot deliveries. */
fromBot?: string;
/** Originating surface for completion delivery. */
source?: { channelType: string; channelId: string };
/** Photos/PDFs to hand the turn; `web/api/uploads.ts` already wrote them to disk. */
attachments?: ChannelAttachment[];
createdAt: number;
attempts: number;
/** Scheduler task id for cron runs (routine gating + no-outcome streaks). */
routineId?: string;
}
/**
* Fleet delegation rule: a mailbox job WITH a prompt (fromBot set) is a TASK
* dispatched by another bot — its result is returned to the sender's mailbox
* on completion. Plain mail wakes (prompt '') never reply — no ping-pong.
* Derived from the job itself, so it survives restarts with zero schema.
*/
function replyTargetFor(job: BotJob): string | undefined {
return job.trigger === 'mailbox' && job.fromBot && job.prompt ? job.fromBot : undefined;
}
export interface BotCostRow {
id: string;
name: string;
parent?: string;
today: BotUsage;
window: BotUsage;
/** Daily cap in effect (0 = unlimited). */
cap: number;
paused: boolean;
}
export interface BotCostReport {
days: number;
bots: BotCostRow[];
fleets: Array<{ id: string; name: string; members: number; today: BotUsage; window: BotUsage }>;
fleetToday: number;
fleetCap: number;
fleetPaused: boolean;
}
export interface BotSendResult {
accepted: boolean;
jobId?: string;
reasonCode?: 'target_disabled' | 'target_unknown' | 'queue_full' | 'not_linked';
}
export interface BotManagerDeps {
config: MercuryConfig;
providers: ProviderRegistry;
tokenBudget: TokenBudget;
store?: BotStore;
/** Durable job store; defaults to the SQLite→JSON backend at the bots root. */
queue?: BotQueue;
/** Per-bot memory factory (P0-5 wires the default: UserMemoryStore with bot:<id> key). */
userMemoryFactory?: (botId: string, manifest: BotManifest) => UserMemoryStore | null;
/** Global (native) skills root; default resolves to <botsRoot>/../skills (~/.mercury/skills). */
skillsRoot?: string;
/** Deliver turn output to the invoking surface (chat/telegram/api). */
notify?: (channelType: string, channelId: string, message: string) => Promise<void>;
}
/** How many recent events the live feed keeps in memory (the whole fleet). */
const LIVE_EVENTS = 2000;
const MAX_TRANSIENT_ATTEMPTS = 3;
/** Consecutive no-outcome runs after which a work routine is paused (ADR-020). */
export const NO_OUTCOME_PAUSE_AFTER = 3;
/** No routine runs more often than this, whatever its cron says (Bots 2.0). */
export const ROUTINE_MIN_GAP_MINUTES = 15;
/** A routine that fails this many runs in a row is switched off until the owner starts it again. */
export const ROUTINE_FAIL_OFF_AFTER = 5;
/** Hand-offs nest at most this deep: owner → lead → crew → crew's crew. */
export const MAX_HANDOFF_DEPTH = 3;
/** One run hands off at most this many tasks, across all its delegate calls. */
export const MAX_HANDOFFS_PER_RUN = 12;
/** First no-outcome cooldown; doubles per repeat up to NO_OUTCOME_PAUSE_MAX_MS. A pause always ends by itself. */
export const NO_OUTCOME_PAUSE_MS = 6 * 60 * 60 * 1000;
export const NO_OUTCOME_PAUSE_MAX_MS = 24 * 60 * 60 * 1000;
/** A delegated batch wakes its requester with partial results after this long (ADR-021). */
export const DEFAULT_TASK_DEADLINE_MINUTES = 120;
const MAILBOX_CAPACITY = 100;
/** Bot-thread result display cap — matches CLIChannel.MAX_MESSAGE_CHARS (64KB). */
const BOT_RESULT_DISPLAY_CAP = 64 * 1024;
/** Bare wake turn (`/bots run <id>` with no routine): the bot gets a real
* turn with no task attached — it checks its mailbox and standing work. */
const WAKE_PROMPT = '[wake] You were triggered manually with no specific task attached. Check your mailbox and any pending work; act on whatever your persona or standing routines call for, otherwise reply with a one-line status.';
/** Structural subset of the main Scheduler the bot runtime needs. */
type BotSchedulerLike = {
addDelayedTask(m: { id: string; description: string; prompt: string; delaySeconds?: number; executeAt?: string; botId?: string; createdAt: string }): void;
addPersistedTask(m: { id: string; cron: string; description: string; prompt: string; botId?: string; createdAt: string }): void;
persistSchedules(): void;
getManifests(): Array<{ id: string; botId?: string }>;
removeTask(id: string): void;
};
/**
* Owns the bot fleet: per-bot job queues, isolated turn runtimes, mailboxes,
* run journals, and live statuses. Bots never touch Agent.processQueue —
* they run as independent coroutines in this manager (BOTS-ARCHITECTURE.md §2.2).
*/
export class BotManager {
readonly store: BotStore;
readonly queue: BotQueue;
/** Durable fleet tasks (ADR-021). */
readonly tasks: BotTaskStore;
private readonly config: MercuryConfig;
private readonly providers: ProviderRegistry;
private readonly tokenBudget: TokenBudget;
private readonly userMemoryFactory?: BotManagerDeps['userMemoryFactory'];
private readonly skillsRoot?: BotManagerDeps['skillsRoot'];
private notify?: BotManagerDeps['notify'];
private alert?: (message: string) => Promise<void>;
private sendFile?: (channelType: string, channelId: string, filePath: string) => Promise<void>;
/** Deliver turn output to the invoking surface (wired by the Agent). */
setNotify(cb: NonNullable<BotManagerDeps['notify']>): void {
this.notify = cb;
}
/** Push needs-you events (permanent failure, budget pause) to the owner. */
setAlert(cb: (message: string) => Promise<void>): void {
this.alert = cb;
}
/** Deliver a file to a remote chat (Telegram/Discord/Slack) — a path on the owner's disk is useless on a phone. */
setSendFile(cb: (channelType: string, channelId: string, filePath: string) => Promise<void>): void {
this.sendFile = cb;
}
/** Fleet health, same checks as `mercury bots doctor`. */
doctor(): DoctorReport {
return runBotDoctor({
store: this.store,
queue: this.queue,
journalFor: (id) => this.journalFor(id),
scheduledRoutineIds: this.scheduler?.getManifests().map(m => m.id),
});
}
/** Wire the main Scheduler so bots can self-schedule (bot_schedule tool). */
setScheduler(scheduler: BotSchedulerLike): void {
this.scheduler = scheduler;
// Runtime-created toolsets gain the tool on next invalidation; simplest
// is to refresh all bot runtimes so every bot sees the new tool.
for (const botId of [...this.registries.keys()]) this.invalidateRuntime(botId);
}
private async alertOwner(botId: string, message: string): Promise<void> {
// Needs-you events (permanent failure, budget pause) live in the BOT'S
// OWN thread — the main chat is never informed (§3.1). Remote owner
// surfaces (signal/telegram/…) still get the heads-up via the alert
// channel; the CLI is excluded there (agent wiring) because it would
// print into whatever main session is open.
if (this.notify) {
await this.notify('cli', `bot:${botId}`, message).catch((e) =>
logger.warn({ e, botId }, 'Bot alert to bot thread failed'));
}
if (this.alert) {
await this.alert(message).catch((e) => logger.warn({ e, botId }, 'Bot alert send failed'));
}
}
private queues: Map<string, BotJob[]> = new Map();
private scheduler?: BotSchedulerLike;
private mailboxes: Map<string, BotTurnMail[]> = new Map();
private running: Map<string, Set<string>> = new Map(); // botId → running job ids
private aborts: Map<string, AbortController> = new Map(); // job key → controller
private registries: Map<string, { registry: CapabilityRegistry; tools: Record<string, Tool>; skillsPrompt: string; manifest: BotManifest; permsMtimeMs: number }> = new Map();
private activity: Map<string, string> = new Map(); // botId → current activity
private lastRun: Map<string, { at: number; state: BotRunRecord['state'] }> = new Map();
private needsYou: Set<string> = new Set();
private journals: Map<string, BotJournal> = new Map();
private userMemories: Map<string, UserMemoryStore | null> = new Map();
private disabled = new Set<string>();
/** Bots stopped by the user (/bots stop) — their held jobs must not sneak
* back in via the passive due-sweep; only /bots start (or a restart) resumes. */
private held = new Set<string>();
/** Per-bot daily token usage: botId → { day (UTC yyyy-mm-dd), tokens }. */
private dailyTokens: Map<string, { day: string; tokens: number }> = new Map();
private pausedForBudget = new Set<string>();
/** botId → UTC day the 80% budget warning was sent. */
private budgetWarned: Map<string, string> = new Map();
/** Fleet-wide daily usage and pause (ADR-020). */
private fleetDailyTokens: { day: string; tokens: number } = { day: '', tokens: 0 };
private fleetPausedDay: string | null = null;
/** routine key → when its last run ended (min-interval gate). */
private routineLastEnd: Map<string, number> = new Map();
/** botId → UTC day a turn-limit notice was sent (once a day, not per run). */
private turnLimitAlerted: Map<string, string> = new Map();
/** Periodic due-sweep interval — cleared by dispose() (tests, shutdown). */
private dueTimer?: ReturnType<typeof setInterval>;
/** What the bots did for the owner, kept until read (Bots 2.0). */
readonly inbox: BotInbox;
/** Bots asking the owner mid-run, waiting for an answer (Bots 2.0). */
readonly approvals = new BotApprovals();
/** job id → how many hand-offs deep it is (owner-started work is 0). */
private jobDepth = new Map<string, number>();
/** running job id → tasks it has handed off so far. */
private jobFanout = new Map<string, number>();
constructor(deps: BotManagerDeps) {
this.config = deps.config;
this.providers = deps.providers;
this.tokenBudget = deps.tokenBudget;
this.userMemoryFactory = deps.userMemoryFactory ?? ((botId, manifest) => {
// Default: per-bot namespace in the shared second-brain DB.
// scope 'none' = stateless bot. SQLite-less devices degrade to a
// stateless bot until the sql.js/JSONL fallback lands (P1, §2.11).
const scope = manifest.memory?.scope ?? 'own';
if (scope === 'none') return null;
try {
return new UserMemoryStoreImpl(this.config, `bot:${botId}`);
} catch (err: any) {
logger.warn({ botId, err: err?.message }, 'Bot memory store unavailable (no native SQLite) — running stateless');
return null;
}
});
this.notify = deps.notify;
this.store = deps.store ?? new BotStore(undefined, this.config.bots?.deliverablesDir);
this.skillsRoot = deps.skillsRoot;
this.queue = deps.queue ?? new BotQueue(this.store.botsRoot, this.config.bots?.retention?.dlqCap);
this.tasks = new BotTaskStore(this.store.botsRoot);
this.inbox = new BotInbox(this.store.botsRoot);
this.queue.onInterruptedSchedule = (job) => {
if (!this.store.exists(job.botId)) return;
const routines = this.store.readRoutineState(job.botId);
routines.paused['*'] = { since: new Date().toISOString(), reason: 'A scheduled run was interrupted. Inspect its effects before /bots start or manual DLQ replay.' };
this.store.writeRoutineState(job.botId, routines);
this.needsYou.add(job.botId);
this.inbox.add({ botId: job.botId, botName: this.store.get(job.botId)?.name ?? job.botId, runId: job.id, files: [], kind: 'needs-you', title: 'Scheduled run interrupted', summary: routines.paused['*'].reason, reasonCode: 'scheduled_interrupted' });
};
// A stop survives a restart (it used to be in memory only, so a restart
// quietly undid /bots stop).
for (const id of this.store.readHeld()) if (this.store.exists(id)) this.held.add(id);
// Today's spend survives a restart too: rebuilt from the journals, so a
// restart can't reset a bot's (or the fleet's) daily budget.
const dayStart = Date.parse(`${new Date().toISOString().slice(0, 10)}T00:00:00Z`);
const today = new Date().toISOString().slice(0, 10);
for (const m of this.store.list()) {
try {
const u = this.journalFor(m.id).usage(m.id, dayStart);
const tokens = u.tokensIn + u.tokensOut;
if (tokens > 0) {
this.dailyTokens.set(m.id, { day: today, tokens });
this.fleetDailyTokens = { day: today, tokens: (this.fleetDailyTokens.day === today ? this.fleetDailyTokens.tokens : 0) + tokens };
const cap = this.dailyCapFor(m);
if (cap > 0 && tokens >= cap) this.pausedForBudget.add(m.id);
}
} catch { /* a journal we can't read starts the day at zero */ }
}
// Resume work a crashed predecessor left behind: pending jobs (and
// expired-lease claimed jobs) re-enter the in-memory queues. Durable
// enqueue happens before any ack, so nothing was lost (§2.6).
for (const job of this.queue.resumeJobs()) {
if (this.store.exists(job.botId)) {
const q = this.queues.get(job.botId) ?? [];
this.queues.set(job.botId, q);
q.push({
id: job.id, botId: job.botId, trigger: job.trigger, prompt: job.prompt,
fromBot: job.fromBot, source: job.source, createdAt: job.createdAt, attempts: job.attempts,
});
this.pump(job.botId);
} else {
this.queue.settle(job.id, 'dead', 'bot_removed');
}
}
// Durable mailboxes survive restarts: rehydrate into the in-memory boxes.
// The needs-you badge too: it lives on the newest journal row (set when a
// run is DLQ'd or crashes, cleared by the next run's row), so the
// in-memory set is only a cache of that — a restart must not clear an
// escalation the owner has not seen.
for (const m of this.store.list()) {
const drained = this.queue.drainMail(m.id);
if (drained.length > 0) this.mailboxes.set(m.id, drained);
if (this.journalFor(m.id).read(m.id, 1)[0]?.needsYou || this.store.readRoutineState(m.id).paused['*']) this.needsYou.add(m.id);
}
// A profile relocation (re-parent or fleet-layout migration) invalidates
// the cached journal handle (it is bound to the old dir) and the bot's
// compiled toolset.
this.store.onRelocate = (botId) => {
this.journals.delete(botId);
this.invalidateRuntime(botId);
};
// Periodic due-sweep: retry-backoff jobs re-enter the in-memory queues
// when their run_after elapses (also covers crash-restart backoffs).
this.dueTimer = setInterval(() => { this.resumeDueJobs(); this.sweepTaskDeadlines(); }, 30_000);
this.dueTimer.unref?.();
// Retention janitor: on boot + once a day, cool down aged files in the
// fleet-shared folder into the archive and expire the archive (disabled
// entirely with `sandboxJanitor.enabled: false`).
if (this.config.bots?.retention?.sandboxJanitor?.enabled !== false) {
const janitorTimer = setInterval(() => this.sweepRetention(), 24 * 60 * 60 * 1000);
janitorTimer.unref?.();
setTimeout(() => this.sweepRetention(), 15_000);
}
// Real-time activity consumer registration happens via onBotActivity();
// executeTurn feeds every registered listener AND the live `activity`
// map (rendered by the /bots roster and fleet_status).
}
/**
* Real-time bot activity bus. Every bot turn emits granular events
* (turn-start, step, tool start/finish, turn-end); listeners render them —
* the CLI bot-thread live region, the web feed, future dashboards. The
* manager itself also mirrors the latest label into the `activity` map so
* the roster goes live with no extra UI.
*/
private activityListeners = new Set<(ev: BotActivityEvent) => void>();
onBotActivity(listener: (ev: BotActivityEvent) => void): () => void {
this.activityListeners.add(listener);
return () => this.activityListeners.delete(listener);
}
/**
* ADR-044 across the fleet: what the sender had read when it handed work on
* (a delegated job), and what each finished run had read (its result, and
* any digest built from it, carries that on). In memory; a restart forgets.
*/
private jobTaint = new Map<string, BotTaint>();
private runTaint = new Map<string, BotTaint>();
/** What each running job was asked, by whom, for the live feed (set when the turn starts). */
private jobContext = new Map<string, { trigger: string; prompt: string; fromBot?: string }>();
/**
* The live feed's short memory: recent events across the fleet, so a
* screen opened mid-run shows what already happened. In memory only and
* capped (LIVE_EVENTS); a 'thinking' preview replaces the previous one of
* the same run instead of piling up.
*/
private liveLog: BotActivityEvent[] = [];
/** The owner sent a bot a message: it shows in the live feed at once, before the run starts. */
noteOwnerMessage(botId: string, jobId: string, prompt: string): void {
// Already started (an idle bot picks the job up at once): the run's own start says it all.
if (this.liveLog.some((e) => e.jobId === jobId && e.kind !== 'queued')) return;
const busy = (this.running.get(botId)?.size ?? 0) > 0;
this.emitBotActivity({ botId, jobId, kind: 'queued', label: busy ? 'Queued: runs when the current run finishes' : 'Starting', stepIndex: 0, elapsedMs: 0, trigger: 'api', prompt: prompt.slice(0, 600) });
}
/** Recent live events, oldest first: for some bots (a fleet) or all, newer than `since`. */
recentActivity(opts: { bots?: string[]; since?: number; limit?: number } = {}): BotActivityEvent[] {
const want = opts.bots?.length ? new Set(opts.bots) : null;
const since = opts.since ?? 0;
const out = this.liveLog.filter((e) => (!want || want.has(e.botId)) && (e.at ?? 0) > since);
return out.slice(-Math.max(1, Math.min(opts.limit ?? 400, LIVE_EVENTS)));
}
private emitBotActivity(ev: BotActivityEvent): void {
const ctx = ev.jobId ? this.jobContext.get(ev.jobId) : undefined;
ev = {
...ev,
at: ev.at ?? Date.now(),
botName: ev.botName ?? this.store.get(ev.botId)?.name ?? ev.botId,
...(ev.kind === 'turn-start' && ctx ? { trigger: ctx.trigger, prompt: ctx.prompt.slice(0, 600), ...(ctx.fromBot ? { fromBot: ctx.fromBot } : {}) } : {}),
};
if (ev.kind === 'turn-end' && ev.jobId) this.jobContext.delete(ev.jobId);
if (ev.kind === 'thinking') {
for (let i = this.liveLog.length - 1; i >= 0; i--) {
if (this.liveLog[i].kind === 'thinking' && this.liveLog[i].jobId === ev.jobId) { this.liveLog.splice(i, 1); break; }
}
}
this.liveLog.push(ev);
if (this.liveLog.length > LIVE_EVENTS) this.liveLog.splice(0, this.liveLog.length - LIVE_EVENTS);
// Live roster label: keep the static job description until the first
// step arrives, then follow the actual work. 'thinking' events are a
// stream preview for threads, not a roster label — the label must stay
// semantic (step/tool names), not the last 80 chars of reasoning.
if (ev.kind !== 'turn-end' && ev.kind !== 'thinking' && ev.kind !== 'queued') this.activity.set(ev.botId, ev.label);
for (const listener of this.activityListeners) {
try { listener(ev); } catch (err: any) {
logger.warn({ botId: ev.botId, err: err?.message }, 'Bot activity listener failed');
}
}
}
/**
* Pull due (backoff-elapsed) jobs from the durable queue into memory and
* run them. This is the ONLY re-entry path for a retried/paused job: the
* precise backoff timers call it too, instead of pushing a captured copy
* of the job themselves. A timer that pushed its own copy raced the 30s
* sweep — the sweep moved the job from the queue into `running`, the
* timer saw an empty queue and pushed it again, and the job ran twice
* (the second settle a silent no-op). Reading durable state here makes
* re-entry idempotent: a running job is `claimed` (not due), a finished
* one is gone, a queued one is skipped by id.
*/
private resumeDueJobs(): void {
const due = this.queue.dueJobs();
for (const job of due) {
if (this.disabled.has(job.botId) || this.held.has(job.botId)) continue;
this.reenterJob(job);
}
// Liveness: a bot paused for its daily budget with work already queued
// has nothing new arriving to pump it — the sweep does, so the pause
// ends at the day rollover rather than at the next trigger.
for (const [botId, queue] of this.queues) {
if (queue.length > 0 && !this.held.has(botId)) this.pump(botId);
}
}
/** Re-enter a durable job into its bot's in-memory lane unless that id is
* already queued OR running — a job id is never in both, and never twice. */
private reenterJob(job: DurableBotJob): boolean {
const q = this.queues.get(job.botId) ?? [];
if (q.some(j => j.id === job.id) || this.running.get(job.botId)?.has(job.id)) return false;
q.push({
id: job.id, botId: job.botId, trigger: job.trigger, prompt: job.prompt,
fromBot: job.fromBot, source: job.source, createdAt: job.createdAt, attempts: job.attempts,
});
this.queues.set(job.botId, q);
this.pump(job.botId);
return true;
}
/**
* Fleet-wide concurrency cap: config override or a fixed default of 8.
* NOT cpu-derived: a bot turn is a network-bound LLM call plus small tool
* subprocesses — a cpus()-1 cap serialized whole fleets on small VMs
* (4 vCPU → 3 concurrent turns) while doing nothing to protect a 16-core
* box any more than a 1-core one. Providers' own rate limits and the
* transient-retry machinery handle 429 pressure.
*/
private fleetCap(): number {
const configured = this.config.bots?.maxConcurrent ?? 0;
if (configured > 0) return configured;
return 8;
}
private journalFor(botId: string): BotJournal {
let j = this.journals.get(botId);
if (!j) {
const manifest = this.store.get(botId);
const retention = { ...(this.config.bots?.retention ?? {}), ...(manifest?.retention ?? {}) };
j = new BotJournal(this.store.botDir(botId), retention.journalRotateBytes, retention.journalKeepRotations, retention.transcriptRuns ?? 50);
this.journals.set(botId, j);
}
return j;
}
private getOrCreateJournal(botId: string): BotJournal {
return this.journalFor(botId);
}
enqueue(botId: string, job: { trigger: BotTrigger; prompt: string; fromBot?: string; source?: { channelType: string; channelId: string }; attempts?: number; routineId?: string; attachments?: ChannelAttachment[]; manualReplay?: boolean; taint?: BotTaint }): { jobId: string; accepted: boolean; reasonCode?: string; duplicated?: boolean } {
const manifest = this.store.get(botId);
if (!manifest) return { jobId: '', accepted: false, reasonCode: 'target_unknown' };
if (!manifest.enabled || this.disabled.has(botId)) return { jobId: '', accepted: false, reasonCode: 'target_disabled' };
const queue = this.queues.get(botId) ?? [];
this.queues.set(botId, queue);
// Routine gate (ADR-020): a cron tick is an opportunity, not an order.
// It is skipped — never stacked — when the bot is still busy, when the
// routine ran too recently, or when the routine was paused for
// producing nothing. The next tick tries again.
if (job.trigger === 'cron' && !job.manualReplay) {
// A stopped bot's routines don't queue up behind the stop.
if (this.held.has(botId)) return { jobId: '', accepted: false, reasonCode: 'stopped' };
const key = job.routineId ?? `bot:${botId}:cron`;
const routineState = this.store.readRoutineState(botId);
const pausedEntry = routineState.paused[key] ?? routineState.paused['*'];
if (pausedEntry) {
const until = pausedEntry.until ? Date.parse(pausedEntry.until) : Number.POSITIVE_INFINITY;
if (Date.now() < until) return { jobId: '', accepted: false, reasonCode: 'routine_paused' };
// Cooldown over: the routine is live again with a clean streak (liveness contract).
delete routineState.paused[key];
delete routineState.noOutcomeStreak[key];
this.store.writeRoutineState(botId, routineState);
logger.info({ botId, routineKey: key }, 'Bot routine cooldown over — resuming');
}
if (queue.length > 0 || (this.running.get(botId)?.size ?? 0) > 0) return { jobId: '', accepted: false, reasonCode: 'busy' };
const persisted = routineState.lastEnd?.[key] ? Date.parse(routineState.lastEnd[key]) : undefined;
const lastEnd = this.routineLastEnd.get(key) ?? (Number.isFinite(persisted) ? persisted : undefined);
const minGapMs = this.routineConfig(manifest, key).minIntervalMinutes * 60_000;
if (lastEnd !== undefined && Date.now() - lastEnd < minGapMs) return { jobId: '', accepted: false, reasonCode: 'too_soon' };
}
if (queue.length >= MAILBOX_CAPACITY) {
return { jobId: '', accepted: false, reasonCode: 'queue_full' };
}
// Durable-before-ack: the job is persisted (idempotency-deduped) before
// the caller hears "accepted" — a crash between ack and run loses nothing.
const durable = this.queue.enqueue({
id: randomUUID().slice(0, 8),
botId,
trigger: job.trigger,
prompt: job.prompt,
fromBot: job.fromBot,
source: job.source,
attachments: job.attachments,
attempts: job.attempts ?? 0,
createdAt: Date.now(),
idempotencyKey: idempotencyKeyFor(botId, job.trigger, job.prompt, job.fromBot, job.attachments),
});
if (durable.duplicated) {
return { jobId: durable.job.id, accepted: true, duplicated: true };
}
const id = durable.job.id;
queue.push({ id, botId, trigger: job.trigger, prompt: job.prompt, fromBot: job.fromBot, source: job.source, createdAt: durable.job.createdAt, attempts: durable.job.attempts, routineId: job.routineId });
// Before the pump: an idle bot starts the job right away.
if (job.taint) this.jobTaint.set(id, job.taint);
this.pump(botId);
return { jobId: id, accepted: true };
}
/** The fleet's floor between two runs of one routine (`bots.routineMinGapMinutes`, default 15). */
private routineMinGap(): number {
const v = this.config.bots?.routineMinGapMinutes;
return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : ROUTINE_MIN_GAP_MINUTES;
}
/** A routine's declared contract (bot.yaml schedules) or the defaults. */
private routineConfig(manifest: BotManifest, routineKey: string): { expects: BotExpectedOutcome; minIntervalMinutes: number } {
const declared = (manifest.schedules ?? []).find(r => `bot:${manifest.id}:${r.name}` === routineKey);
// Every routine waits at least ROUTINE_MIN_GAP_MINUTES between runs, the
// owner's own too: a 5-minute cron on a lead spent hundreds of millions of
// tokens writing records about records. Routines a bot created for itself
// wait 30 minutes unless the owner says otherwise.
return {
expects: declared?.expects ?? 'work',
minIntervalMinutes: Math.max(this.routineMinGap(), declared?.minIntervalMinutes ?? (declared ? this.routineMinGap() : 30)),
};
}
/**
* The outcome contract of a job: unattended wakes must produce work; a
* delegated task or a conversation is answered by its reply; a bare
* mailbox wake may find nothing.
*/
private expectationFor(manifest: BotManifest, job: BotJob): BotExpectedOutcome {
if (job.trigger === 'cron') return this.routineConfig(manifest, job.routineId ?? `bot:${manifest.id}:cron`).expects;
if (job.trigger === 'mailbox') return job.prompt ? 'message' : 'check';
if (job.trigger === 'api' || job.trigger === 'cloud') return 'work';
return 'message';
}
/**
* Fleet task dispatch: a delegated TASK from one bot to another (lead →
* crew, crew → lead). Durable job with the task as the prompt — on
* completion the result is returned to the sender's mailbox
* (replyTargetFor), closing the delegation loop.
*/
dispatchTask(targetBotId: string, fromBot: string, task: string): BotSendResult {
// One typed task in a batch of one (ADR-021): same wake-once contract
// and digest as fleet_delegate.
const r = this.delegate(fromBot, { tasks: [{ bot: targetBotId, goal: task }] });
if (!r.ok) return { accepted: false, reasonCode: 'not_linked' };
const t = this.tasks.get(r.tasks[0].id);
if (!t || t.status === 'failed') return { accepted: false, reasonCode: (t?.result?.reasonCode as BotSendResult['reasonCode']) ?? 'target_disabled' };
return { accepted: true, jobId: t.jobId };
}
// ---- fleet tasks (ADR-021) ------------------------------------------------
/**
* Fan-out: typed tasks for several crew at once, grouped in a batch. The
* requester is woken ONCE with a digest when the batch settles or its
* deadline passes — never once per task.
*/
delegate(requester: string, spec: { tasks: Array<{ bot: string; goal: string; acceptance?: string }>; label?: string; deadlineMinutes?: number; wakeWhen?: 'all' | 'each' }): { ok: true; batchId: string; tasks: Array<{ id: string; assignee: string; duplicated: boolean }> } | { ok: false; error: string } {
const lead = this.store.get(requester);
if (!lead) return { ok: false, error: `No bot "${requester}"` };
const roster = this.effectiveRoster(requester, lead);
for (const t of spec.tasks) {
if (t.bot === requester) return { ok: false, error: 'You cannot delegate to yourself' };
if (!roster.includes(t.bot)) return { ok: false, error: `"${t.bot}" is not in your crew (${roster.join(', ') || 'no crew yet — bot_spawn one'})` };
}
const handoff = this.handoffCheck(requester, spec.tasks.length);
if (!handoff.ok) return handoff;
const deadlineAt = Date.now() + (spec.deadlineMinutes ?? DEFAULT_TASK_DEADLINE_MINUTES) * 60_000;
const batch = this.tasks.createBatch({ requester, label: spec.label, wakeWhen: spec.wakeWhen ?? 'all', deadlineAt });
const out: Array<{ id: string; assignee: string; duplicated: boolean }> = [];
for (const t of spec.tasks) {
const r = this.startTask({ batchId: batch.id, requester, assignee: t.bot, goal: t.goal, acceptance: t.acceptance }, undefined, handoff.depth);
out.push({ id: r.task.id, assignee: t.bot, duplicated: r.duplicated });
}
logger.info({ requester, batchId: batch.id, tasks: out.length }, 'Fleet batch dispatched');
return { ok: true, batchId: batch.id, tasks: out };
}
/**
* A bot wants something outside its grants. The question goes to the
* owner's inbox (and their phone, if an alert channel is set up) and the run
* waits for the answer; no answer in `bots.approvalWaitMinutes` (default 10)
* is a no. "Always" goes into this bot's own permissions file, never the
* global one.
*/
private async askOwner(botId: string, prompt: string): Promise<string> {
const manifest = this.store.get(botId);
const runId = [...(this.running.get(botId) ?? [])][0];
if (!manifest || !runId) return 'no';
const minutes = Math.max(1, Math.min(60, this.config.bots?.approvalWaitMinutes ?? 10));
const { approval, answer } = this.approvals.ask({ botId, botName: manifest.name, runId, prompt }, minutes * 60_000);
const what = prompt.split('\n')[0];
this.emitBotActivity({ botId, jobId: runId, kind: 'step', label: 'Waiting for your approval', stepIndex: 0, elapsedMs: 0 });
const entry = this.inbox.add({
botId, botName: manifest.name, runId, kind: 'needs-you', approvalId: approval.id, files: [],
title: `${manifest.name} asks: ${what.slice(0, 120)}`,
summary: `${prompt}\n\nThe run is waiting for your answer. Without one in ${minutes} minute${minutes === 1 ? '' : 's'}, it's refused.`,
});
if (this.alert) {
void this.alert(`🔐 **${manifest.name}** asks: ${what}. Answer in Mercury Desktop (Bots → Inbox) within ${minutes} min, or it's refused.`).catch(() => {});
}
const result = await answer;
this.inbox.markRead([entry.id]);
if (result === 'always') this.persistGrant(botId, prompt);
logger.info({ botId, runId, answer: result, what: what.slice(0, 80) }, 'Bot approval answered');
return result;
}
/** "Always": make the owner's yes part of this bot's permissions.yaml. */
private persistGrant(botId: string, prompt: string): void {
const grant = durableGrant(prompt);
if (!grant) return;
const perms = this.store.readPermissions(botId);
if ('command' in grant) {
perms.autoApproveCommands = [...new Set([...(perms.autoApproveCommands ?? []), grant.command])];
} else {
perms.paths = mergePathScopes(perms.paths, [{ scope: grant.path, read: true, write: grant.write }]);
}
this.store.writePermissions(botId, perms);
logger.info({ botId, grant }, 'Owner granted a bot permission permanently');
}
/**
* May `requester` hand off `count` more tasks now? Work nests at most
* MAX_HANDOFF_DEPTH deep (a lead's crew can't keep delegating downwards
* forever), and one run hands off at most MAX_HANDOFFS_PER_RUN tasks. The
* refusal says what to do instead, so the model stops trying.
*/
private handoffCheck(requester: string, count: number): { ok: true; depth: number } | { ok: false; error: string } {
const running = [...(this.running.get(requester) ?? [])];
const depth = Math.max(0, ...running.map((j) => this.jobDepth.get(j) ?? 0)) + 1;
if (depth > MAX_HANDOFF_DEPTH) {
return { ok: false, error: `Hand-off limit: this work is already ${depth - 1} hand-offs deep (max ${MAX_HANDOFF_DEPTH}). Do it yourself, or report back to whoever asked you with what you have.` };
}
const job = running[0];
const used = job ? this.jobFanout.get(job) ?? 0 : 0;
if (used + count > MAX_HANDOFFS_PER_RUN) {
return { ok: false, error: `Hand-off limit: one run can hand off at most ${MAX_HANDOFFS_PER_RUN} tasks (${used} so far). Wait for those results, or combine tasks.` };
}
if (job) this.jobFanout.set(job, used + count);
return { ok: true, depth };
}
private startTask(input: Omit<BotTask, 'id' | 'status' | 'createdAt' | 'jobId'>, previous?: BotTaskResult, depth?: number): { task: BotTask; duplicated: boolean } {
const created = this.tasks.createTask(input);
if (created.duplicated) return created;
const requesterName = this.store.get(input.requester)?.name ?? input.requester;
// Pipeline stages chain on the lead's behalf: one level below it.
const level = depth ?? Math.max(0, ...[...(this.running.get(input.requester) ?? [])].map((j) => this.jobDepth.get(j) ?? 0)) + 1;
// The requester's untrusted reads travel with the task (called inside its turn).
const handedOn = taintOf();
const job = this.enqueue(input.assignee, { trigger: 'mailbox', prompt: renderTaskPrompt(created.task, requesterName, previous), fromBot: input.requester, ...(handedOn ? { taint: handedOn } : {}) });
if (job.accepted && job.jobId) this.jobDepth.set(job.jobId, level);
if (!job.accepted) {
this.tasks.update(created.task.id, { status: 'failed', completedAt: Date.now(), result: { outcome: 'none', summary: `could not dispatch: ${job.reasonCode}`, deliverables: [], reasonCode: job.reasonCode } });
this.onTaskSettled(created.task.id);
} else {
// enqueue pumps synchronously: the turn may already be running by the
// time the job id is known, so record that state here.
const alreadyRunning = this.running.get(input.assignee)?.has(job.jobId) ?? false;
this.tasks.update(created.task.id, { jobId: job.jobId, ...(alreadyRunning ? { status: 'running', startedAt: Date.now() } : {}) });
}
return created;
}
/** A lead's pipeline (bot.yaml) on one input: stages chain themselves. */
runPipeline(leadId: string, input: string, label?: string): { ok: true; runId: string; total: number; firstStage: string; duplicated: boolean } | { ok: false; error: string } {
const lead = this.store.get(leadId);
const stages = lead?.pipeline?.stages ?? [];
if (!lead || stages.length === 0) return { ok: false, error: 'No pipeline declared in bot.yaml (pipeline.stages)' };
const roster = this.effectiveRoster(leadId, lead);
const missing = stages.map(st => st.bot).filter(b => !roster.includes(b));
if (missing.length > 0) return { ok: false, error: `Pipeline stage bot(s) not in your crew: ${missing.join(', ')}` };
const runId = randomUUID().slice(0, 8);
const batch = this.tasks.createBatch({ requester: leadId, label: label ?? `${lead.pipeline?.name ?? 'pipeline'}: ${input.slice(0, 40)}`, wakeWhen: 'all', deadlineAt: Date.now() + stages.length * DEFAULT_TASK_DEADLINE_MINUTES * 60_000 });
const r = this.startStage(leadId, batch.id, runId, input, 0);
return { ok: true, runId, total: stages.length, firstStage: stages[0].name, duplicated: r.duplicated };
}
private startStage(leadId: string, batchId: string, runId: string, input: string, index: number, previous?: BotTaskResult): { task: BotTask; duplicated: boolean } {
const stages = this.store.get(leadId)?.pipeline?.stages ?? [];
const stage = stages[index];
const handoff = previous ? (previous.deliverables.join(', ') || previous.summary.slice(0, 500)) : '(none)';
const goal = stage.goal.replace(/\{\{\s*input\s*\}\}/g, input).replace(/\{\{\s*previous\s*\}\}/g, handoff);
return this.startTask({
batchId, requester: leadId, assignee: stage.bot, goal, acceptance: stage.acceptance, stage: stage.name,
pipeline: { runId, index, total: stages.length, input, final: Boolean(stage.final) },
}, previous);
}
private onTaskSettled(taskId: string): void {
const task = this.tasks.get(taskId);
if (!task) return;
if (task.pipeline) {
this.advancePipeline(task);
return;
}
this.notifyBatch(task.batchId, 'settled', task.id);
}
private advancePipeline(task: BotTask): void {
const stages = this.store.get(task.requester)?.pipeline?.stages ?? [];
const p = task.pipeline!;
const isLast = p.index + 1 >= stages.length;
if (task.status === 'done' && !isLast) {
this.startStage(task.requester, task.batchId, p.runId, p.input, p.index + 1, task.result);
return;
}
// Last stage done, or a stage failed: promote finals, then wake the lead once.
if (task.status === 'done' && p.final && task.result) {
task.result.deliverables = task.result.deliverables.map(d => this.promoteDeliverable(task.requester, d));
this.tasks.update(task.id, { result: task.result });
}
this.notifyBatch(task.batchId, 'settled', task.id);
}
/** A crew's finished deliverable becomes the fleet's final: moved from work/<crew>/ to the top of the lead's folder. */
private promoteDeliverable(leadId: string, path: string): string {
const leadDir = this.store.deliverablesDir(leadId);
const rel = relative(join(leadDir, 'work'), path);
if (rel.startsWith('..') || isAbsolute(rel) || !existsSync(path)) return path;
let dest = join(leadDir, basename(path));
for (let i = 2; existsSync(dest); i++) dest = join(leadDir, `${basename(path, extname(path))} (${i})${extname(path)}`);
try {
renameSync(path, dest);
this.store.writeDeliverablesIndex(leadDir);
logger.info({ leadId, dest }, 'Pipeline final promoted to the fleet folder');
return dest;
} catch {
return path;
}
}
/**
* Wake the requester with a digest: on settle, when every task in an
* 'all' batch is terminal (a late result after a deadline wake reports
* just itself); on deadline, once, with what is done and what is still
* running. 'each' batches wake per task.
*/
private notifyBatch(batchId: string, reason: 'settled' | 'deadline', settledTaskId?: string): void {
const batch = this.tasks.batch(batchId);
if (!batch) return;
const tasks = this.tasks.tasksInBatch(batchId);
const open = tasks.filter(t => !isTerminalTask(t.status));
const name = (id: string) => this.store.get(id)?.name ?? id;
let digest: string | null = null;
if (reason === 'deadline') {
if (open.length === 0 || batch.notifiedAt) return;
digest = renderBatchDigest(batch, tasks, name);
this.tasks.markBatchNotified(batchId);
} else if (batch.wakeWhen === 'each') {
const one = tasks.find(t => t.id === settledTaskId);
if (one) digest = renderBatchDigest(batch, [one], name);
} else if (open.length === 0) {
digest = batch.notifiedAt
? `Late result for batch "${batch.label ?? batchId}":\n` + renderBatchDigest(batch, tasks.filter(t => t.id === settledTaskId), name)
: renderBatchDigest(batch, tasks, name);
this.tasks.markBatchNotified(batchId);
} else if (batch.notifiedAt) {
// Deadline already woke the requester; each straggler reports itself once.
const one = tasks.find(t => t.id === settledTaskId);
if (one) digest = `Late result for batch "${batch.label ?? batchId}":\n` + renderBatchDigest(batch, [one], name);
}
if (!digest) return;
const taints = tasks.map((t) => (t.jobId ? this.runTaint.get(t.jobId) : undefined)).filter((t): t is BotTaint => !!t);
const digestTaint = taints.length ? { sources: [...new Set(taints.flatMap((t) => t.sources))].slice(0, 6), suspicious: taints.some((t) => t.suspicious) } : undefined;
const sent = this.sendToBot(batch.requester, 'fleet', digest, digestTaint ?? null);
if (!sent.accepted) logger.warn({ requester: batch.requester, batchId, reason: sent.reasonCode }, 'Fleet digest not delivered');
}
private sweepTaskDeadlines(): void {
for (const batch of this.tasks.overdueBatches()) this.notifyBatch(batch.id, 'deadline');
}
/** Open and recent tasks a lead asked for, newest first. */
tasksFor(requester: string): BotTask[] {
return this.tasks.recent(requester, 20);
}
async cancelTask(requester: string, taskId: string): Promise<{ ok: true } | { ok: false; error: string }> {
const task = this.tasks.get(taskId);
if (!task || task.requester !== requester) return { ok: false, error: `No task ${taskId} of yours` };
if (isTerminalTask(task.status)) return { ok: false, error: `Task ${taskId} is already ${task.status}` };
if (task.jobId) {
const q = this.queues.get(task.assignee) ?? [];
this.queues.set(task.assignee, q.filter(j => j.id !== task.jobId));
if (this.running.get(task.assignee)?.has(task.jobId)) await this.halt(task.assignee, task.jobId);
else this.queue.settle(task.jobId, 'done');
}
this.tasks.update(taskId, { status: 'cancelled', completedAt: Date.now() });
return { ok: true };
}
/** Fire-and-forget mailbox delivery from another bot. */
sendToBot(targetBotId: string, fromBot: string, content: string, taint?: BotTaint | null): BotSendResult {
// Sent from inside a turn (bot_send, the owner's dispatch): that turn's reads travel with the mail.
// null: the caller knows it's clean (a result sent after its run ended).
const carried = taint === undefined ? taintOf() : taint ?? undefined;
const manifest = this.store.get(targetBotId);
if (!manifest) return { accepted: false, reasonCode: 'target_unknown' };
if (!manifest.enabled || this.disabled.has(targetBotId)) return { accepted: false, reasonCode: 'target_disabled' };
const box = this.mailboxes.get(targetBotId) ?? [];
if (box.length >= MAILBOX_CAPACITY) {
return { accepted: false, reasonCode: 'queue_full' };
}
// Durable-before-ack for handoffs too: a bot_send that returns "queued"
// must survive a crash before the target's next turn drains it.
this.queue.enqueueMail({ botId: targetBotId, from: fromBot, content, createdAt: Date.now() });
box.push({ from: fromBot, content, ...(carried ? { taint: carried } : {}) });
this.mailboxes.set(targetBotId, box);
// If the bot is idle (no running turn, empty job queue), wake it with a
// mailbox-driven turn so mail is consumed promptly.
const queue = this.queues.get(targetBotId) ?? [];
const isRunning = (this.running.get(targetBotId)?.size ?? 0) > 0;
let jobId: string | undefined;
if (queue.length === 0 && !isRunning) {
jobId = randomUUID().slice(0, 8);
queue.push({ id: jobId, botId: targetBotId, trigger: 'mailbox', prompt: '', createdAt: Date.now(), attempts: 0 });
this.queues.set(targetBotId, queue);
this.pump(targetBotId);
}
return { accepted: true, jobId };
}
/** Poll-and-drain a bot's mailbox (turns); durable rows removed too. */
drainMailbox(botId: string): BotTurnMail[] {
const box = this.mailboxes.get(botId) ?? [];
this.mailboxes.set(botId, []);
this.queue.drainMail(botId);
return box;
}
peekMailbox(botId: string): BotTurnMail[] {
return [...(this.mailboxes.get(botId) ?? [])];
}
/** Kick the queue: start turns while slots (per-bot and fleet-wide) exist. */
private pump(botId: string): void {
const manifest = this.store.get(botId);
if (!manifest?.enabled || this.disabled.has(botId)) return;
// Stopped by the owner: work waits (durably) until they start it again.
if (this.held.has(botId)) return;
const today = new Date().toISOString().slice(0, 10);
const used = this.dailyTokens.get(botId);
if (used && used.day !== today) {
this.dailyTokens.delete(botId);
this.pausedForBudget.delete(botId);
}
if (this.pausedForBudget.has(botId)) {
this.activity.set(botId, 'Paused — daily token budget reached');
return;
}
if (this.fleetPausedDay === today) {
this.activity.set(botId, 'Paused — fleet daily token budget reached');
return;
}
const queue = this.queues.get(botId) ?? [];
const running = this.running.get(botId) ?? new Set();
this.running.set(botId, running);
const perBotCap = manifest.autonomy?.maxConcurrent ?? 1;
while (queue.length > 0 && running.size < perBotCap && this.fleetRunningCount() < this.fleetCap()) {
const job = queue.shift()!;
void this.executeTurn(job);
}
}
/** Hard daily budget stop: pause (resume next UTC day), never die. */
private recordBotTokens(botId: string, manifest: BotManifest, tokens: number): void {
const today = new Date().toISOString().slice(0, 10);
const entry = this.dailyTokens.get(botId);
const next = entry && entry.day === today ? entry.tokens + tokens : tokens;
this.dailyTokens.set(botId, { day: today, tokens: next });
const cap = this.dailyCapFor(manifest);
if (cap > 0 && next >= cap) {
this.pausedForBudget.add(botId);
logger.warn({ botId, used: next, cap }, 'Bot daily token budget reached — pausing until next day');
void this.alertOwner(botId, `🟡 **${manifest.name}** paused — daily token budget reached (${next.toLocaleString()} ≥ ${cap.toLocaleString()}). Resumes tomorrow; \`/bots budget ${botId} <tokens>\` to change it.`);
} else if (cap > 0 && next >= cap * 0.8 && this.budgetWarned.get(botId) !== today) {
this.budgetWarned.set(botId, today);
void this.alertOwner(botId, `🟠 **${manifest.name}** has used ${Math.round(100 * next / cap)}% of today's token budget (${next.toLocaleString()} / ${cap.toLocaleString()}).`);
}
// Fleet-wide cap: one runaway bot must not spend the whole day's budget.
if (this.fleetDailyTokens.day !== today) this.fleetDailyTokens = { day: today, tokens: 0 };
this.fleetDailyTokens.tokens += tokens;
const fleetCap = this.config.bots?.fleetDailyTokenBudget ?? 0;
if (fleetCap > 0 && this.fleetDailyTokens.tokens >= fleetCap && this.fleetPausedDay !== today) {
this.fleetPausedDay = today;
logger.warn({ used: this.fleetDailyTokens.tokens, cap: fleetCap }, 'Fleet daily token budget reached — all bots paused until next day');
void this.alertOwner(botId, `🔴 All bots paused — the fleet's daily token budget is used up (${this.fleetDailyTokens.tokens.toLocaleString()} ≥ ${fleetCap.toLocaleString()}). Resumes tomorrow; \`bots.fleetDailyTokenBudget\` in mercury.yaml changes the cap.`);
}
}
/** Effective daily cap: the bot's own, else the fleet default; 0 = unlimited. */
dailyCapFor(manifest: BotManifest): number {
const own = manifest.autonomy?.dailyTokenBudget;
if (own !== undefined) return own;
return this.config.bots?.suggestedDailyTokenBudget ?? 5_000_000;
}
/** Today's spend for /bots and the API. */
dailyUsage(botId: string): { tokens: number; cap: number } {
const today = new Date().toISOString().slice(0, 10);
const entry = this.dailyTokens.get(botId);
const manifest = this.store.get(botId);
return { tokens: entry && entry.day === today ? entry.tokens : 0, cap: manifest ? this.dailyCapFor(manifest) : 0 };
}
private fleetRunningCount(): number {
let total = 0;
for (const s of this.running.values()) total += s.size;
return total;
}
private async executeTurn(job: BotJob): Promise<void> {
const { botId } = job;
const running = this.running.get(botId) ?? new Set();
this.running.set(botId, running);
running.add(job.id);
const controller = new AbortController();
this.aborts.set(`${botId}:${job.id}`, controller);
this.activity.set(botId, describeJob(job));
const manifest = this.store.get(botId);
if (!manifest) {
running.delete(job.id);
return;
}
// Lease heartbeat: a turn can outlive LEASE_SECONDS by minutes (long
// provider calls). Without a heartbeat the 30s due-sweep requeues the
// STILL-RUNNING job, a duplicate turn starts, and whichever settles
// first makes the other's settle a silent no-op — the job vanishes
// from the DLQ and /bots replay reports not_found. A live turn must
// never expire its lease.
let heartbeat: ReturnType<typeof setInterval> | undefined;
try {
this.queue.claim(job.id, LEASE_SECONDS);
heartbeat = setInterval(() => {
try { this.queue.heartbeatLease(job.id, LEASE_SECONDS); } catch { /* best effort */ }
}, (LEASE_SECONDS / 3) * 1000);
heartbeat.unref?.();
const taskForJob = this.tasks.byJob(job.id);
if (taskForJob) this.tasks.update(taskForJob.id, { status: 'running', startedAt: Date.now() });
const turn = this.buildTurn(botId, manifest, job, controller.signal);
this.jobContext.set(job.id, { trigger: job.trigger, prompt: job.prompt ?? '', ...(job.fromBot ? { fromBot: job.fromBot } : {}) });
const handed = this.jobTaint.get(job.id);
const output = await runBotTurn({
...turn.input,
jobId: job.id,
...(job.fromBot ? { fromBot: job.fromBot } : {}),
...(handed ? { taint: handed } : {}),
onActivity: (ev) => this.emitBotActivity(ev),
});
turn.cleanup();
this.jobTaint.delete(job.id);
if (output.taint) {
this.runTaint.set(job.id, output.taint);
if (this.runTaint.size > 500) this.runTaint.delete(this.runTaint.keys().next().value as string);
}
// Decided up front so the journal row can carry the needs-you flag:
// a failure that will retry is not an escalation; one headed for the
// DLQ is (the flag is durable via the row — the constructor rehydrates
// it from the newest journal row on restart).
// A rejected key is permanent for THAT provider, not for the bot:
// remember it, and if another usable provider exists the next attempt
// runs there (resolveProvider skips rejected providers).
let authSwitch = false;
const usedProvider = turn.input.provider?.name;
if (output.status === 'failed' && output.reasonCode === 'provider_auth' && usedProvider) {
this.providers.markAuthFailure?.(usedProvider);
authSwitch = resolveProvider(this.providers, manifest, this.config).name !== usedProvider;
}
const willRetry = job.trigger !== 'cron' && output.status === 'failed' && !!output.reasonCode
&& (isTransientFailure(output.reasonCode) || authSwitch) && job.attempts + 1 < MAX_TRANSIENT_ATTEMPTS;
const turnLimited = output.status === 'failed' && isTurnLimitFailure(output.reasonCode);
const routineKey = job.trigger === 'cron' ? (job.routineId ?? `bot:${botId}:cron`) : undefined;
const record: BotRunRecord = {
runId: job.id,
botId,
trigger: job.trigger,
state: output.status === 'completed' ? 'completed' : output.status,
startedAt: job.createdAt,
durationMs: Date.now() - job.createdAt,
tokensIn: output.tokensIn,
tokensOut: output.tokensOut,
summary: output.output.slice(0, 300),
...(output.report ? { report: output.report.kind, ...(output.report.complete ? { complete: true } : {}) } : {}),
error: output.error,
reasonCode: output.reasonCode,
// A turn cut off by policy is not an escalation (ADR-020).
...(output.status === 'failed' && !willRetry && !turnLimited ? { needsYou: true } : {}),
turnStartedAt: output.startedAt,
steps: output.steps,
toolCalls: output.toolCalls,
peakInputTokens: output.peakInputTokens,
outcome: output.outcome,
...(output.deliverables.length > 0 ? { deliverables: output.deliverables } : {}),
...(output.claimedWithoutAction ? { claimedWithoutAction: true } : {}),
...(routineKey ? { routineId: routineKey } : {}),
};
const journal = this.journalFor(botId);
journal.append(record);
journal.writeTranscript(record, { prompt: job.prompt, output: output.output, trace: output.trace });
this.lastRun.set(botId, { at: Date.now(), state: record.state });
this.needsYou.delete(botId);
this.recordBotTokens(botId, manifest, output.tokensIn + output.tokensOut);
// Did this run fail for good (not a retry, not a policy cut-off)? Either the
// turn died, or the bot itself reported that it couldn't do the job.
const failedForGood = (output.status === 'failed' && !willRetry && !turnLimited) || output.outcome === 'failed';
let routineFailStreak = 0;
if (routineKey) {
this.routineLastEnd.set(routineKey, Date.now());
const state = this.store.readRoutineState(botId);
state.lastEnd = { ...(state.lastEnd ?? {}), [routineKey]: new Date().toISOString() };
if (failedForGood) {
routineFailStreak = (state.failStreak?.[routineKey] ?? 0) + 1;
state.failStreak = { ...(state.failStreak ?? {}), [routineKey]: routineFailStreak };
if (routineFailStreak >= ROUTINE_FAIL_OFF_AFTER) {
// Switched off, not cooled down: it would keep burning tokens on the same failure.
state.paused[routineKey] = { since: new Date().toISOString(), reason: `${routineFailStreak} runs in a row failed` };
delete state.failStreak![routineKey];
logger.warn({ botId, routineKey, streak: routineFailStreak }, 'Bot routine switched off — failing every run');
void this.alertOwner(botId, `⏹ **${manifest.name}**'s routine \`${routineKey.split(':').pop()}\` is switched off: its last ${routineFailStreak} runs failed${output.reasonCode ? ` (${output.reasonCode})` : ''}. Fix the cause, then Start the bot (\`/bots start ${botId}\`) to turn it back on.`);
}
} else if (output.status === 'completed' && state.failStreak?.[routineKey]) {
delete state.failStreak[routineKey];
}
if (output.status !== 'completed') {
state.paused[routineKey] = { since: new Date().toISOString(), reason: 'Scheduled run did not finish. Inspect its effects before /bots start or manual DLQ replay.' };
}
this.store.writeRoutineState(botId, state);
}
// No-outcome streak (ADR-020): a work routine that produces nothing
// three runs in a row is paused — the owner is told once, and
// /bots start resumes it. This is what stops a bot that has
// talked itself into a loop of records about records.
if (routineKey && this.expectationFor(manifest, job) === 'work' && output.status === 'completed') {
const state = this.store.readRoutineState(botId);
if (output.outcome === 'none') {
const streak = (state.noOutcomeStreak[routineKey] ?? 0) + 1;
state.noOutcomeStreak[routineKey] = streak;
if (streak >= NO_OUTCOME_PAUSE_AFTER) {
// Cooldown, not a stop: the routine resumes by itself (6h, doubling
// to 24h while it keeps producing nothing). The bot stays online
// for chat, mail and tasks throughout.
const pauses = (state.pauseCount?.[routineKey] ?? 0) + 1;
const cooldownMs = Math.min(NO_OUTCOME_PAUSE_MAX_MS, NO_OUTCOME_PAUSE_MS * 2 ** (pauses - 1));
const until = new Date(Date.now() + cooldownMs);
state.paused[routineKey] = { since: new Date().toISOString(), until: until.toISOString(), reason: `${streak} consecutive runs produced no deliverable or action` };
state.pauseCount = { ...(state.pauseCount ?? {}), [routineKey]: pauses };
delete state.noOutcomeStreak[routineKey];
logger.warn({ botId, routineKey, streak, resumesAt: until.toISOString() }, 'Bot routine cooling down — no outcome in consecutive runs');
void this.alertOwner(botId, `⏸ **${manifest.name}**'s routine \`${routineKey.split(':').pop()}\` is cooling down for ${Math.round(cooldownMs / 3600000)}h: ${streak} runs in a row produced no deliverable or action (only notes). It resumes automatically at ${until.toISOString().slice(11, 16)} UTC; \`/bots start ${botId}\` resumes it now. The bot still answers chat, mail and tasks meanwhile. Check its persona for instructions that reward activity over results.`);
}
} else {
delete state.noOutcomeStreak[routineKey];
if (state.pauseCount?.[routineKey]) delete state.pauseCount[routineKey];
}
this.store.writeRoutineState(botId, state);
}
if (turnLimited) {
const today = new Date().toISOString().slice(0, 10);
if (this.turnLimitAlerted.get(botId) !== today) {
this.turnLimitAlerted.set(botId, today);
void this.alertOwner(botId, `🟠 **${manifest.name}** hit the per-turn limit (${output.reasonCode === 'turn_time' ? 'time' : 'tokens'}) and was stopped. One task is too big for one run — split it, or raise \`autonomy.maxTokensPerTurn\` / \`maxTurnMinutes\` in bot.yaml.`);
}
}
// Auto-skill synthesis (P2-3): a completed multi-step run is a
// procedure worth keeping. Fire-and-forget, gated by config.
if (
output.status === 'completed'
&& output.toolsUsed.length >= MIN_TOOLS_FOR_SYNTHESIS
&& (this.config.bots as any)?.autoSkill?.enabled
) {
void synthesizeSkill({
botId,
botName: manifest.name,
prompt: job.prompt,
output: output.output,
toolsUsed: output.toolsUsed,
provider: resolveProvider(this.providers, manifest, this.config),
// The synthesized skill lands in the BOT'S OWN library (draft:true),
// not the global root — it is that bot's learned procedure, usable
// by it on the next run (runtime invalidated on success).
skillsRoot: this.store.skillsDir(botId),
}).then((synth) => { if (synth) this.invalidateRuntime(botId); })
.catch((err) => logger.warn({ err, botId }, 'Skill synthesis failed'));
}
// Transient provider failures retry with backoff, bounded; permanent
// failures go to the capped DLQ and stop (never silently re-queued — §2.6).
// Retries requeue the SAME job in place (durable): no settle-then-
// reenqueue window where a crash would lose the work.
// Re-entry rides the due-sweep (resumeDueJobs) — the timer only makes
// it precise; it never pushes a copy of the job itself (duplicate-run
// race with the periodic sweep).
if (willRetry) {
const delay = Math.min(15000, 1000 * 2 ** job.attempts);
this.queue.retry(job.id, job.attempts + 1, Date.now() + delay);
logger.info({ botId, jobId: job.id, reasonCode: output.reasonCode, retryIn: delay }, 'Bot turn failed transiently — retrying in place');
// A little past due: a timer can fire a millisecond early, and the job
// would then wait for the next 30 s sweep.
setTimeout(() => this.resumeDueJobs(), delay + 50).unref?.();
} else if (turnLimited) {
this.queue.settle(job.id, 'done');
this.store.clearCheckpoint(botId, job.id);
this.jobDepth.delete(job.id);
} else if (output.status === 'failed') {
this.queue.settle(job.id, 'dead', output.reasonCode);
// A replay from the dead-letter queue starts fresh: the failure may be in the conversation itself.
this.store.clearCheckpoint(botId, job.id);
this.jobDepth.delete(job.id);
this.needsYou.add(botId);
logger.warn({ botId, jobId: job.id, reasonCode: output.reasonCode }, 'Bot turn failed permanently — moved to DLQ (replayable via /bots dlq)');
// A routine failing again and again tells the owner once, on the first
// failure; the streak switches it off after ROUTINE_FAIL_OFF_AFTER.
if (routineFailStreak <= 1) {
await this.alertOwner(botId, `❌ **${manifest.name}** failed permanently [reason: ${output.reasonCode}] — replay with \`/bots replay ${botId} ${job.id}\``);
}
} else if (output.status === 'paused' && job.trigger === 'cron') {
this.queue.settle(job.id, 'dead', 'scheduled_interrupted');
this.needsYou.add(botId);
this.inbox.add({ botId, botName: manifest.name, runId: job.id, files: output.deliverables, kind: 'needs-you', title: 'Scheduled run paused', summary: 'Inspect the existing effects before /bots start or manually replaying this run from the DLQ.', reasonCode: 'scheduled_interrupted' });
} else if (output.status === 'paused') {
// Step-budget pause: work continues next turn — same job requeues in
// place (durable), no attempts bump.
this.queue.retry(job.id, job.attempts, Date.now() + 2000);
setTimeout(() => this.resumeDueJobs(), 2000).unref?.();
} else {
this.queue.settle(job.id, 'done');
this.store.clearCheckpoint(botId, job.id);
this.jobDepth.delete(job.id);
}
// Deliver the outcome — the bot thread is the ONLY local surface
// (BOTS-ARCHITECTURE §3.1): the FULL result lands in the BOT'S OWN
// thread and the CLI session that asked is NOT notified at all — a
// pointer into the main chat would leak into whatever session is open
// days later (a routine or retry finishing inside a brand-new session
// printed bot traffic into the user's regular chat/code). Remote
// channels (Telegram/web) stay the exception: their user cannot open
// bot threads, so the full result is delivered in that chat. Halts
// report too (a stopped run must announce it stopped, §2.6).
//
// Mailbox turns deliver too UNLESS the result is addressed to another
// bot (a delegated task — replyTargetFor routes it to the sender's
// mailbox below, and the user must not see the internal crew→lead mail
// twice). A lead's wake after crew results IS a mailbox trigger
// (sendToBot), and its synthesis is the user-facing outcome of the
// whole delegation — skipping every mailbox turn left it journaled
// but never shown.
// Quiet runs (bot_no_update) are recorded, never announced: "nothing new"
// every 15 minutes is exactly the noise the owner stops reading.
if (this.notify && !replyTargetFor(job) && output.outcome !== 'quiet') {
const botThread = `bot:${botId}`;
const icon = output.status === 'completed' ? '🤖' : output.status === 'failed' ? '❌' : output.status === 'halted' ? '⏹' : '⏸';
// Full result, matched to the channel's per-message cap (64KB) — the
// bot thread is the primary delivery surface, so results must arrive
// complete (tables, code, lists), not sliced at a pointer-era 800.
const body = output.output.length > BOT_RESULT_DISPLAY_CAP
? output.output.slice(0, BOT_RESULT_DISPLAY_CAP) + `\n\n[…output truncated at ${Math.round(BOT_RESULT_DISPLAY_CAP / 1024)}KB — full text in the run transcripts]`
: output.output;
const delivered = output.deliverables.length > 0
? output.deliverables.map(p => `📁 Delivered → ${p}`).join('\n') + '\n\n'
: '';
const noOutcome = output.status === 'completed' && output.outcome === 'none' && this.expectationFor(manifest, job) === 'work'
? '⚠ No deliverable or action this run — only notes.' + (output.claimedWithoutAction ? ' The reply claims otherwise; the tool trace shows nothing was delivered.' : '') + '\n\n'
: '';
const fullText = output.status === 'halted'
? `⏹ Run ${job.id} was stopped by you — no further output. It is recorded in \`/bots journal ${botId}\`.`
: `${icon} (${job.trigger}): ${delivered}${noOutcome}${body}`;
// 1. Full result → the bot's own thread, always.
await this.notify('cli', botThread, fullText).catch((e) =>
logger.warn({ e, botId }, 'Bot result deliver to bot thread failed'));
// 2. Remote requesting surface only — no CLI pointer, no main-chat
// traffic, ever.
const sourceChannelType = job.source?.channelType ?? 'cli';
const sourceChannelId = job.source?.channelId;
if (sourceChannelId && sourceChannelId !== botThread && sourceChannelType !== 'cli') {
await this.notify(sourceChannelType, sourceChannelId, fullText).catch((e) =>
logger.warn({ e, botId }, 'Bot remote-channel result notify failed'));
// The files themselves, not just their paths (ADR-023).
if (this.sendFile) {
for (const file of output.deliverables) {
await this.sendFile(sourceChannelType, sourceChannelId, file).catch((e) =>
logger.warn({ e, botId, file }, 'Bot deliverable send to remote channel failed'));
}
}
}
}
// The owner's inbox (Bots 2.0): results, reported failures and runs that
// need them — durable, so they're there when the owner comes back. Not
// here: quiet runs, retries, halts, and results addressed to another bot.
if (!replyTargetFor(job) && output.status !== 'halted') {
const firstLine = (s: string) => s.split('\n').map((l) => l.trim()).find(Boolean) ?? '';
const base = { botId, botName: manifest.name, runId: job.id, files: output.deliverables };
if (output.outcome === 'failed') {
this.inbox.add({ ...base, kind: 'failed', title: `${manifest.name} couldn't do it: ${firstLine(output.report?.summary ?? output.output).slice(0, 100)}`, summary: output.report?.summary ?? output.output });
} else if (failedForGood) {
this.inbox.add({ ...base, kind: 'needs-you', title: `${manifest.name} failed (${output.reasonCode ?? 'error'})`, summary: output.error ?? output.output, reasonCode: output.reasonCode });
} else if (turnLimited) {
this.inbox.add({ ...base, kind: 'needs-you', title: `${manifest.name} hit its per-run limit`, summary: `The run was stopped at its ${output.reasonCode === 'turn_time' ? 'time' : 'token'} limit before it finished. Split the task, or raise the limit in the bot's settings.`, reasonCode: output.reasonCode });
} else if (output.status === 'completed' && ['deliverable', 'action', 'message', 'delegated'].includes(output.outcome)) {
const summary = output.report?.summary ?? output.output;
const files = output.deliverables.length;
this.inbox.add({
...base,
kind: 'result',
title: `${manifest.name}: ${firstLine(summary).slice(0, 110) || (files ? `delivered ${files} file${files === 1 ? '' : 's'}` : 'finished')}`,
summary,
...(output.report?.complete ? { complete: true } : {}),
});
}
}
// Fleet delegation loop: a task dispatched by another bot reports its
// result back to the sender's mailbox (attributed, plain mail — never a
// task, so results can't ping-pong). Paused runs requeue and report
// later; the failure/retry machinery above owns transient states.
// Memory (ADR-021): a productive run teaches the bot something.
const memoryStore = this.userMemoryFor(botId, manifest);
// A quiet run ("nothing new") has nothing to teach: no extra model call for it.
if (output.status === 'completed' && output.outcome !== 'quiet' && memoryStore && manifest.memory?.learn !== false) {
void extractBotMemories({
botId, botName: manifest.name, prompt: job.prompt, output: output.output, outcome: output.outcome,
deliverables: output.deliverables, provider: resolveProvider(this.providers, manifest, this.config), tokenBudget: this.tokenBudget, memory: memoryStore,
}).then((n) => { if (n > 0) logger.info({ botId, remembered: n }, 'Bot memories extracted'); });
}
// Typed task (ADR-021): record the result on the task and let the
// batch decide whether the requester is woken now.
const settledTask = output.status !== 'paused' ? this.tasks.byJob(job.id) : null;
if (settledTask) {
this.tasks.update(settledTask.id, {
status: output.status === 'completed' ? 'done' : output.status === 'failed' ? 'failed' : 'halted',
completedAt: Date.now(),
result: { outcome: output.outcome, summary: output.output.slice(0, 4000), deliverables: output.deliverables, reasonCode: output.reasonCode },
});
this.onTaskSettled(settledTask.id);
}
const replyTarget = settledTask ? undefined : replyTargetFor(job);
if (replyTarget && (output.status === 'completed' || output.status === 'failed' || output.status === 'halted')) {
const icon = output.status === 'completed' ? '✅' : output.status === 'failed' ? '❌' : '⏹';
const reply = output.status === 'completed'
? `✅ Task complete (job ${job.id}):\n${output.output.slice(0, 4000)}`
: output.status === 'failed'
? `❌ Task FAILED (job ${job.id})${output.reasonCode ? ` [reason: ${output.reasonCode}]` : ''}: ${(output.error ?? output.output).slice(0, 1000)}`
: `⏹ Task halted (job ${job.id}) — it was stopped; see /bots journal ${botId}.`;
const sent = this.sendToBot(replyTarget, botId, reply, output.taint ?? null);
if (!sent.accepted) {
logger.warn({ botId, replyTarget, reason: sent.reasonCode }, 'Fleet result reply not delivered');
}
}
} catch (err: any) {
logger.error({ botId, jobId: job.id, err: err?.message }, 'Bot turn crashed');
if (job.trigger === 'cron') {
const state = this.store.readRoutineState(botId);
state.paused[job.routineId ?? `bot:${botId}:cron`] = { since: new Date().toISOString(), reason: 'Scheduled run crashed. Inspect its effects before /bots start or manual DLQ replay.' };
this.store.writeRoutineState(botId, state);
}
this.queue.settle(job.id, 'dead', 'unknown_error');
this.needsYou.add(botId);
void this.alertOwner(botId, `💥 **${botId}** run ${job.id} crashed: ${String(err?.message ?? err).slice(0, 150)} — see journal; replay from DLQ.`);
this.journalFor(botId).append({
runId: job.id,
botId,
trigger: job.trigger,
state: 'failed',
startedAt: job.createdAt,
durationMs: Date.now() - job.createdAt,
tokensIn: 0,
tokensOut: 0,
error: err?.message,
reasonCode: 'unknown_error',
needsYou: true,
});
this.needsYou.add(botId);
} finally {
if (heartbeat) clearInterval(heartbeat);
running.delete(job.id);
this.jobFanout.delete(job.id);
this.approvals.cancelRun(job.id);
this.aborts.delete(`${botId}:${job.id}`);
if (running.size === 0) this.activity.delete(botId);
// Mail-arrival race: a reply (e.g. a crew's task result) delivered
// while this turn ran can land AFTER the turn's last mailbox poll —
// sendToBot saw the bot running and scheduled no wake. Without this,
// the mail sits unconsumed and the bot idles forever. If mail is
// pending and nothing is queued or running, schedule a wake turn.
const manifestNow = this.store.get(botId);
if (
(this.running.get(botId)?.size ?? 0) === 0
&& (this.queues.get(botId)?.length ?? 0) === 0
&& this.peekMailbox(botId).length > 0
&& manifestNow?.enabled && !this.disabled.has(botId)
) {
const q = this.queues.get(botId) ?? [];
q.push({ id: randomUUID().slice(0, 8), botId, trigger: 'mailbox', prompt: '', createdAt: Date.now(), attempts: 0 });
this.queues.set(botId, q);
logger.info({ botId, pending: this.peekMailbox(botId).length }, 'Mail arrived mid-turn — scheduling a wake so it is consumed');
}
this.pump(botId);
}
}
private userMemoryFor(botId: string, manifest: BotManifest): UserMemoryStore | null {
if (this.userMemories.has(botId)) return this.userMemories.get(botId) ?? null;
const factory = this.userMemoryFactory;
if (!factory) return null;
let store: UserMemoryStore | null = null;
try {
store = factory(botId, manifest);
} catch (err: any) {
// Memory is an enhancement, never a hard dependency — a store that
// fails to build (e.g. no native SQLite) degrades to a stateless bot.
logger.warn({ botId, err: err?.message }, 'Bot memory store build failed — running stateless');
}
this.userMemories.set(botId, store);
return store;
}
private buildTurn(botId: string, manifest: BotManifest, job: BotJob, signal: AbortSignal): { input: Parameters<typeof runBotTurn>[0]; cleanup: () => void } {
const { registry, tools, skillsPrompt } = this.getOrCreateRuntime(botId, manifest);
const userMemory = this.userMemoryFor(botId, manifest);
const mail: BotTurnMail[] = [];
// Deliveries from other bots arrive via the mailbox; drain at turn start.
const pending = this.drainMailbox(botId);
mail.push(...pending);
return {
input: {
manifest,
trigger: job.trigger,
prompt: job.prompt,
attachments: job.attachments,
persona: this.store.readPersona(botId),
mail,
pollMail: () => this.drainMailbox(botId),
sandbox: { workspace: this.store.sandboxDir(botId), shared: this.store.sharedSandboxDir() },
deliverablesDir: this.store.deliverablesDir(botId),
expects: this.expectationFor(manifest, job),
recentRuns: this.recentRunsDigest(botId),
stateNote: this.store.readState(botId),
skillsPrompt,
fleet: this.fleetContext(botId, manifest),
capabilities: registry,
tools,
userMemory,
provider: resolveProvider(this.providers, manifest, this.config),
tokenBudget: this.tokenBudget,
abortSignal: signal,
// Pick up an interrupted run of this job where it stopped; checkpoint every step.
resume: this.store.readCheckpoint(botId, job.id) as Parameters<typeof runBotTurn>[0]['resume'],
onCheckpoint: (messages) => this.store.writeCheckpoint(botId, job.id, messages),
},
cleanup: () => { /* per-bot registries are persistent, nothing to restore */ },
};
}
/** Last few runs, one line each — continuity the bot used to write to disk itself. */
private recentRunsDigest(botId: string): string {
const rows = this.journalFor(botId).read(botId, 5);
if (rows.length === 0) return '';
return [...rows].reverse().map(r => {
const when = new Date(r.turnStartedAt ?? r.startedAt).toISOString().slice(0, 16).replace('T', ' ');
const what = r.deliverables?.length ? `delivered ${r.deliverables.map(d => basename(d)).join(', ')}` : (r.summary ?? '').replace(/\s+/g, ' ').slice(0, 120);
return `- ${when} · ${r.trigger} · ${r.state}${r.outcome ? ` · ${r.outcome}` : ''} — ${what}`;
}).join('\n');
}
/** Fleet context for the turn prompt (undefined for solo bots). */
private fleetContext(botId: string, manifest: BotManifest) {
if (manifest.fleetRole === 'lead') {
return {
role: 'lead' as const,
leadName: manifest.parent ? this.store.get(manifest.parent)?.name : undefined,
crew: this.store.crewOf(botId).map(c => ({
id: c.id,
name: c.name,
description: c.description,
state: this.getStatusSummaries().find(s => s.id === c.id)?.state ?? 'idle',
})),
maxCrew: this.maxCrew(),
};
}
if (manifest.parent) {
return {
role: 'crew' as const,
leadName: this.store.get(manifest.parent)?.name,
crew: [],
maxCrew: 0,
};
}
return undefined;
}
private getOrCreateRuntime(botId: string, manifest: BotManifest): { registry: CapabilityRegistry; tools: Record<string, Tool>; skillsPrompt: string } {
// Staleness check: the toolset bakes in the manifest (tools.deny/allow,
// fleetRole) and permissions.yaml (path scopes). Hand-edits to those files
// must apply on the next turn — the manifest cache makes identity a
// reliable change signal (same object unless the file changed on disk).
const permsFile = join(this.store.botDir(botId), BOT_PERMISSIONS_FILENAME);
let permsMtimeMs = 0;
try { permsMtimeMs = statSync(permsFile).mtimeMs; } catch { /* no file yet */ }
const cached = this.registries.get(botId);
if (cached && cached.manifest === manifest && cached.permsMtimeMs === permsMtimeMs) {
return cached as { registry: CapabilityRegistry; tools: Record<string, Tool>; skillsPrompt: string };
}
// Skill access: global (native) library + the bot's own skills dir
// (auto-synthesized + hand-authored; own-dir names win on collision).
// Default root = <botsRoot>/../skills — ~/.mercury/skills in production,
// tmp-local in tests.
let skillLoader: SkillLoader | undefined;
let skillsPrompt = '';
try {
skillLoader = new SkillLoader(this.skillsRoot ?? resolve(this.store.botsRoot, '..', 'skills'), {
extraDirs: [this.store.skillsDir(botId)],
seedDefaults: false,
});
skillLoader.discover();
skillsPrompt = skillLoader.getSkillSummariesText();
} catch (err: any) {
logger.warn({ botId, err: err?.message }, 'Bot skill loader unavailable — continuing without skills');
}
const registry = createBotCapabilityRegistry({
botId,
manifest,
botDir: this.store.botDir(botId),
// Single source of truth; also materializes fleet inheritance (a crew
// without its own file gets its lead's copied in verbatim).
permissions: this.store.ensurePermissions(botId),
skillLoader,
// Built-in work areas: private sandbox + fleet-shared folder (rw+x,
// implicit — no permission ask).
sandbox: { workspace: this.store.sandboxDir(botId), shared: this.store.sharedSandboxDir() },
userMemory: this.userMemoryFor(botId, manifest),
config: this.config,
// Outside its grants the bot asks the owner (and waits a while) instead of failing outright.
ask: (prompt) => this.askOwner(botId, prompt),
});
// Filter FIRST (strips interactive/global-mutation tools and applies the
// permissions.yaml tool gate), THEN add the bot-specific tools —
// otherwise the filter would strip them again.
const filtered = filterBotTools({ ...registry.getTools() }, manifest, this.store.ensurePermissions(botId));
const effectiveRoster = this.effectiveRoster(botId, manifest);
if (effectiveRoster.length > 0) {
filtered.bot_send = createBotSendTool(this, botId, effectiveRoster) as Tool;
}
// bot_deliver: implicit lifecycle op — every bot can move a finished
// artifact out of its writable roots into the owner-curated outputs zone
// (exempt from the retention janitor).
filtered.bot_deliver = createBotDeliverTool(this, botId) as Tool;
// Fleet tools for leads: monitor the crew, spawn/retire within caps.
filtered.bot_state = createBotStateTool(this.store, botId) as Tool;
if (manifest.fleetRole === 'lead') {
filtered.fleet_status = createFleetStatusTool(this, botId);
filtered.fleet_delegate = createFleetDelegateTool(this, botId) as Tool;
filtered.fleet_tasks = createFleetTasksTool(this, botId) as Tool;
const stages = manifest.pipeline?.stages ?? [];
if (stages.length > 0) filtered.fleet_pipeline = createFleetPipelineTool(this, botId, stages.map(st => st.name)) as Tool;
if (this.config.bots?.fleets?.allowLeadSpawn !== false) {
const fleet = createBotSpawnTool(this, botId);
filtered.bot_spawn = fleet.spawn;
filtered.bot_retire = fleet.retire;
}
}
// bot_schedule: bots can schedule their own future runs (durable,
// capped) when the main scheduler is wired.
if (this.scheduler) {
filtered.bot_schedule = createBotScheduleTool(this.scheduler, botId);
}
// The bot's own tools (added after the registry's guard) get the same ADR-044 gate:
// a schedule, a new bot or a message to the fleet after reading something
// untrusted needs the owner (asked from the app; no answer is a no).
const own = ['bot_send', 'bot_deliver', 'bot_state', 'fleet_delegate', 'fleet_tasks', 'fleet_pipeline', 'bot_spawn', 'bot_retire', 'bot_schedule'];
const guarded = guardTools(Object.fromEntries(own.filter((n) => filtered[n]).map((n) => [n, filtered[n]])), { permissions: registry.permissions });
Object.assign(filtered, guarded);
this.registries.set(botId, { registry, tools: filtered, skillsPrompt, manifest, permsMtimeMs });
return { registry, tools: filtered, skillsPrompt };
}
/**
* Comms roster = explicit canMessage ∪ fleet relations (lead ↔ own crew).
* Derived per registry build; excludes the bot itself.
*/
private effectiveRoster(botId: string, manifest: BotManifest): string[] {
const roster = new Set(manifest.comms?.canMessage ?? []);
if (manifest.fleetRole === 'lead') {
for (const crew of this.store.crewOf(botId)) roster.add(crew.id);
}
// A mid-level lead (crew of a parent AND lead of its own crew) talks both ways.
if (manifest.parent) {
roster.add(manifest.parent);
}
roster.delete(botId);
return [...roster];
}
// ---- fleet management (shared by onboarding, lead tools, API) -----------
/** Max crew per lead — CrewAI guidance: 3-6 for delegation accuracy. */
/** The persona builder (no save): rough instructions → the structured persona format. Null when unavailable. */
async buildPersona(text: string, name: string): Promise<string | null> {
return refinePersona(text, name || 'Bot', this.providers.getDefault());
}
/** "Let Mercury decide": solo or fleet for what the owner described, with a proposed crew. Nothing is created. */
async planShape(input: { name: string; description: string; persona: string; fleet?: boolean }): Promise<BotShapePlan> {
return planBotShape(input, this.providers.getDefault(), this.maxCrew());
}
maxCrew(): number {
return this.config.bots?.fleets?.maxCrew ?? 6;
}
/** The bot's provider (public for fleet tools — persona building on spawn). */
resolveProviderFor(botId: string): ReturnType<typeof resolveProvider> {
const manifest = this.store.get(botId);
return resolveProvider(this.providers, manifest ?? { id: botId, name: botId, enabled: true } as BotManifest, this.config);
}
/**
* Add a crew member to a lead: validates the relationship, enforces the
* crew cap, creates with fail-closed defaults + comms back to the lead.
* Persona refinement (builder) is the caller's concern (async provider
* call); addCrew writes the persona text it is given.
*/
/** Promote a bot to fleet lead (the cockpit's "lead a fleet" paths). Idempotent. */
promoteLead(botId: string): { ok: boolean } {
const manifest = this.store.get(botId);
if (!manifest) return { ok: false };
if (manifest.fleetRole !== 'lead') {
this.store.update(botId, m => { m.fleetRole = 'lead'; });
this.invalidateRuntime(botId);
logger.info({ botId }, 'Bot promoted to fleet lead');
}
return { ok: true };
}
/**
* Fleet auto-build (the TUI onboarding's "auto" path, shared with the web
* cockpit): one LLM call proposes 3-5 matched specialists, each created
* through the standard addCrew path. DETACHED — the caller hears 202
* immediately; per-member progress rides `hooks`, and failures degrade to
* "lead with an empty crew" guidance, never an error state.
*/
autoCrew(botId: string, hooks: { onMember?: (name: string, id: string) => void; onError?: (msg: string) => void; onDone?: (created: number) => void } = {}): void {
void (async () => {
try {
const manifest = this.store.get(botId);
if (!manifest) return;
if (manifest.fleetRole !== 'lead') this.promoteLead(botId);
const persona = this.store.readPersona(botId);
const leadDescription = manifest.description ?? '';
const proposals = await proposeCrew(manifest.name, leadDescription, persona, resolveProvider(this.providers, manifest, this.config), this.maxCrew());
if (proposals.length === 0) {
hooks.onError?.("Crew proposal unavailable (provider) — the lead has an empty crew. Add specialists yourself, or give the lead a task and tell it to hire its own crew (bot_spawn).");
return;
}
let created = 0;
for (const p of proposals) {
const result = this.addCrew(botId, p);
if (result.ok) {
// A duplicate (already on the crew) is success without growth —
// replayed builds converge instead of inflating the roster.
if (!result.duplicate) {
created++;
hooks.onMember?.(p.name, result.manifest.id);
}
} else {
hooks.onError?.(`Crew member ${p.name} (${p.id}): ${result.error}`);
}
}
hooks.onDone?.(created);
} catch (err: any) {
hooks.onError?.(`Fleet auto-build failed: ${err?.message ?? err} — the lead has an empty crew; add specialists yourself later.`);
}
})();
}
addCrew(leadId: string, spec: { id: string; name: string; description?: string; persona?: string }): { ok: true; manifest: BotManifest; duplicate?: boolean } | { ok: false; error: string } {
const lead = this.store.get(leadId);
if (!lead) return { ok: false, error: `No bot "${leadId}"` };
if (lead.fleetRole !== 'lead') {
return { ok: false, error: `**${lead.name}** is not a fleet lead — promote it with \`/bots promote ${leadId}\` first` };
}
// Multi-level guard: no cycles, bounded depth (MAX_FLEET_DEPTH levels — e.g.
// CEO → Engineering Lead → Backend, the deepest level list() and crewOf() walk).
// `level` is the level the NEW bot would take: one below the lead it joins.
let ancestor: string | undefined = leadId;
let level = 1;
const seen = new Set<string>();
while (ancestor) {
if (seen.has(ancestor)) return { ok: false, error: 'Fleet cycle detected in parent chain' };
seen.add(ancestor);
if (ancestor === spec.id.toLowerCase()) {
return { ok: false, error: `Cannot add **${spec.id}** — it would become its own ancestor` };
}
// Refuse the level the reader cannot reach: a bot created below this lead
// would exist on disk and answer by id while staying out of the roster.
if (level >= MAX_FLEET_DEPTH) {
return { ok: false, error: `Fleet nesting is capped at ${MAX_FLEET_DEPTH} levels` };
}
ancestor = this.store.get(ancestor)?.parent;
level += 1;
}
// Replay-safety BEFORE the crew cap: a re-run "build the crew" turn
// (durable job replayed after an interrupted session) re-derives its
// specs through the LLM and can land on a DIFFERENT id for a specialist
// the fleet already has — the id guard alone let the roster grow a
// duplicate crew per replay. A spec matching an id or the normalized
// NAME of a member already under THIS lead is already-staffed: success
// without creation. Only foreign ids / names from another lead are an
// error. Duplicates skip the cap check — a full fleet stays full.
const id = spec.id.toLowerCase();
let existing: BotManifest | null = this.store.exists(id) ? this.store.get(id) : null;
if (!existing) {
const nameKey = (spec.name ?? '').trim().toLowerCase();
if (nameKey) {
existing = this.store.crewOf(leadId).find(m => m.name.trim().toLowerCase() === nameKey) ?? null;
}
}
if (existing) {
if (existing.fleetRole === 'crew' && existing.parent === leadId) {
return { ok: true, manifest: existing, duplicate: true };
}
return { ok: false, error: `Bot "${id}" already exists` };
}
const crew = this.store.crewOf(leadId);
const cap = this.maxCrew();
if (crew.length >= cap) {
return { ok: false, error: `Fleet is at the crew cap (${crew.length}/${cap}) — retire a member first or raise BOTS_FLEET_MAX_CREW` };
}
const manifest = this.store.create({
id,
name: spec.name,
description: spec.description,
persona: spec.persona,
manifest: { fleetRole: 'crew', parent: leadId, comms: { canMessage: [leadId] } },
});
// Inheritance at birth: the crew starts on its lead's permissions,
// copied verbatim (its own file from now on — edits diverge it).
this.store.ensurePermissions(manifest.id);
this.invalidateRuntime(leadId); // lead's roster + fleet prompt change
logger.info({ leadId, crewId: spec.id }, 'Crew member added to fleet');
return { ok: true, manifest };
}
/**
* Background persona refinement — bot_spawn used to await refinePersona
* (up to two serial LLM calls) inside the lead's TOOL EXECUTION, stalling
* the lead's turn once per spawned crew member. The member starts on the
* lead-written persona immediately and the refined file overwrites it
* whenever it lands; every later turn picks it up (buildTurn re-reads the
* persona file, so no runtime invalidation is required). Failure keeps the
* raw persona — refinePersona's own contract.
*/
schedulePersonaRefinement(botId: string, name: string, rawPersona: string): void {
const manifest = this.store.get(botId);
if (!manifest) return;
const provider = resolveProvider(this.providers, manifest, this.config);
void refinePersona(rawPersona, name, provider)
.then((refined) => {
if (!refined) return;
try {
this.store.writePersona(botId, refined);
logger.info({ botId }, 'Background persona refinement landed');
} catch (err: any) {
logger.warn({ botId, err: err?.message }, 'Background persona write failed');
}
})
.catch((err) => logger.warn({ botId, err: err?.message }, 'Background persona refinement failed'));
}
/** Remove a crew member (lead's own child only) and record it on the lead. */
async removeCrew(leadId: string, crewId: string): Promise<{ ok: true } | { ok: false; error: string }> {
const crew = this.store.get(crewId);
if (!crew) return { ok: false, error: `No bot "${crewId}"` };
if (crew.parent !== leadId) return { ok: false, error: `**${crewId}** is not crew of **${leadId}**` };
await this.delete(crewId);
this.invalidateRuntime(leadId);
this.journalFor(leadId).append({
runId: randomUUID().slice(0, 8),
botId: leadId,
trigger: 'chat',
state: 'completed',
startedAt: Date.now(),
durationMs: 0,
tokensIn: 0,
tokensOut: 0,
summary: `Retired crew member "${crew.name}" (${crewId})`,
});
logger.info({ leadId, crewId }, 'Crew member retired');
return { ok: true };
}
invalidateRuntime(botId: string): void {
this.registries.delete(botId);
}
/**
* Full lifecycle delete: halt, purge durable queue state (jobs/mail/DLQ),
* remove scheduler routines (zombie cron would fire forever), drop the
* profile dir, and clear every in-memory cache — so a re-created bot with
* the same id starts clean (no stale mail or resurrected routines).
*/
async delete(botId: string): Promise<void> {
await this.halt(botId);
// Fleet cascade: deleting a lead deletes its crew — recursively (a crew
// member may itself be a mid-level lead). Each member gets the FULL
// lifecycle delete (halt, purge queue/mail/DLQ, remove routines) because
// those live outside the profile dir and would otherwise outlive the bot.
// The filesystem half is free: crew profiles nest inside the lead's dir,
// so the lead's store.delete() removes the whole tree — which is also why
// this cascades BEFORE the lead's own profile is wiped below.
if (this.store.isLead(botId)) {
for (const crew of this.store.crewOf(botId)) {
logger.info({ leadId: botId, crewId: crew.id }, 'Fleet lead deleted — cascading to crew member');
await this.delete(crew.id);
}
}
// Scheduler routines (bot:<id>:*) — both bot.yaml routines and
// bot_schedule self-created ones; they must never fire again.
if (this.scheduler) {
for (const m of this.scheduler.getManifests()) {
if (m.botId === botId) this.scheduler.removeTask(m.id);
}
this.scheduler.persistSchedules();
}
this.queue.purgeBot(botId);
this.tasks.purgeBot(botId);
this.store.delete(botId);
this.registries.delete(botId);
this.journals.delete(botId);
this.userMemories.delete(botId);
this.queues.delete(botId);
this.mailboxes.delete(botId);
this.dailyTokens.delete(botId);
this.activity.delete(botId);
this.lastRun.delete(botId);
this.needsYou.delete(botId);
this.pausedForBudget.delete(botId);
if (this.held.delete(botId)) this.store.writeHeld(this.held);
logger.info({ botId }, 'Bot deleted: queue/mail/DLQ purged, routines removed');
}
/**
* One-shot fleet layout migration (startup, before routines register):
* the physical layout must mirror the manifest hierarchy — crew profiles
* nested under their lead's dir — so the delete cascade can never leave a
* crew behind. Two rules, both idempotent:
* 1. A crew bot whose lead no longer exists is cascade-deleted (it
* outlived its lead only because a pre-cascade delete created it).
* 2. An existing crew profile still flat at the root moves under its
* lead's directory (onRelocate refreshes journals/runtime caches).
*/
async migrateFleetLayout(): Promise<void> {
for (const m of this.store.list()) {
if (!m.parent) continue;
if (this.store.exists(m.parent)) {
this.store.relocateToParent(m);
} else {
logger.warn({ botId: m.id, parent: m.parent }, 'Crew bot outlived its lead — cascading the deletion');
await this.delete(m.id);
}
}
}
/**
* Permission consolidation to a SINGLE source of truth (startup): every
* bot ends with exactly one permissions.yaml and a persona that carries
* character only.
* 1. Inheritance backfill: a crew without its own file gets its lead's
* copied verbatim; a solo without one gets the fail-closed default.
* 2. Legacy bot.yaml tools block → permissions.yaml (the manifest copy
* stays as a readable fallback but no longer decides anything).
* 3. Persona `## Access` grants → merged into permissions.yaml paths,
* then stripped from the persona file (permissions never live there).
*/
async migratePermissions(): Promise<void> {
for (const m of this.store.list()) {
try {
const perms = this.store.ensurePermissions(m.id);
// 2. Legacy tool gate out of bot.yaml.
const legacyTools = m.tools;
if (legacyTools && ((legacyTools.allow?.length ?? 0) > 0 || (legacyTools.deny?.length ?? 0) > 0) && !perms.tools) {
this.store.writePermissions(m.id, { ...this.store.readPermissions(m.id), tools: legacyTools });
logger.info({ botId: m.id }, 'Migrated bot.yaml tools gate into permissions.yaml (single source of truth)');
}
// 3. Persona Access grants out of the persona.
const persona = this.store.readPersona(m.id);
const grants = parsePersonaAccess(persona);
if (grants.length > 0) {
const current = this.store.readPermissions(m.id);
this.store.writePermissions(m.id, { ...current, paths: mergePathScopes(current.paths, grants) });
this.store.writePersona(m.id, stripPersonaAccessSection(persona));
logger.info({ botId: m.id, grants: grants.length }, 'Migrated persona Access grants into permissions.yaml; persona is character-only now');
}
} catch (err: any) {
logger.warn({ botId: m.id, err: err?.message }, 'Permission migration failed for bot — leaving as-is');
}
}
}
/**
* Register every enabled bot's cron routines with the main Scheduler
* (manifest id `bot:<botId>:<name>`). Bot runs fire on the cron lane and
* route to the bot lane, never through Agent.processQueue. Idempotent:
* the Scheduler replaces existing tasks by id.
*/
registerRoutines(scheduler: { addPersistedTask(m: any): void }): void {
let count = 0;
for (const manifest of this.store.list()) {
if (!manifest.enabled) continue;
for (const routine of manifest.schedules ?? []) {
if (!isValidCronExpression(routine.cron)) {
logger.warn({ botId: manifest.id, cron: routine.cron }, 'Invalid cron expression — routine skipped');
continue;
}
scheduler.addPersistedTask({
id: `bot:${manifest.id}:${routine.name}`,
cron: routine.cron,
description: routine.name,
prompt: routine.prompt,
botId: manifest.id,
createdAt: new Date().toISOString(),
});
count++;
}
}
if (count > 0) {
logger.info({ routines: count }, 'Bot routines registered');
}
}
/**
* Re-register one bot's owner-declared routines after its schedules changed
* (the app's editor): routines no longer declared are removed, the rest
* replaced. Routines the bot created for itself are left alone.
*/
syncRoutines(botId: string, previousNames: string[]): void {
const scheduler = this.scheduler;
const manifest = this.store.get(botId);
if (!scheduler || !manifest) return;
const now = new Set((manifest.schedules ?? []).map((r) => r.name));
for (const name of previousNames) if (!now.has(name)) scheduler.removeTask(`bot:${botId}:${name}`);
for (const routine of manifest.schedules ?? []) {
scheduler.removeTask(`bot:${botId}:${routine.name}`);
if (!manifest.enabled || !isValidCronExpression(routine.cron)) continue;
scheduler.addPersistedTask({
id: `bot:${botId}:${routine.name}`, cron: routine.cron, description: routine.name, prompt: routine.prompt, botId, createdAt: new Date().toISOString(),
});
}
scheduler.persistSchedules();
}
// ---- control plane -------------------------------------------------------
async halt(botId: string, jobId?: string): Promise<boolean> {
const running = this.running.get(botId);
const hadRunning = !!running && running.size > 0;
for (const id of running ?? []) {
if (jobId && id !== jobId) continue;
this.approvals.cancelRun(id);
this.aborts.get(`${botId}:${id}`)?.abort();
}
// Queued-but-not-started jobs leave the in-memory lane; their durable rows
// stay pending, so /bots start (or a restart) can resume them — stop never
// silently destroys queued work (§2.7 control plane).
this.queues.set(botId, jobId ? (this.queues.get(botId) ?? []).filter(j => j.id !== jobId) : []);
return hadRunning;
}
async haltAll(): Promise<void> {
for (const [botId] of this.running) {
await this.halt(botId);
}
}
/**
* User-facing stop: abort the running turn(s) AND hold queued work. Held
* jobs stay durable-pending (survive a restart); the passive due-sweep
* skips held bots, so nothing resumes until /bots start. Explicit new
* triggers (send/mail/cron) still work — the bot is stopped, not disabled.
* FLEET: stopping a lead stops its crew too — recursively (a crew member
* may be a mid-level lead). Every stopped member's jobs are held the same
* durable way; /bots start on the lead resumes the whole subtree.
*/
async stop(botId: string): Promise<{ halted: boolean; heldJobs: number; crewStopped: number }> {
let heldJobs = (this.queues.get(botId) ?? []).length;
let halted = await this.halt(botId);
this.held.add(botId);
this.store.writeHeld(this.held);
let crewStopped = 0;
if (this.store.isLead(botId)) {
for (const crew of this.store.crewOf(botId)) {
const r = await this.stop(crew.id);
halted = halted || r.halted;
heldJobs += r.heldJobs;
crewStopped += 1 + r.crewStopped;
}
}
if (heldJobs > 0) {
logger.info({ botId, heldJobs, crewStopped }, 'Bot stopped — queued jobs held (resumable via /bots start)');
}
return { halted, heldJobs, crewStopped };
}
/**
* User-facing resume (the counterpart of stop): clear the stop-hold,
* re-enter held/pending durable jobs, and kick the queue. A disabled bot
* is enabled first — "start" is unambiguous. Safe on an already-running bot.
* FLEET: starting a lead resumes its crew subtree too (recursively) —
* except crew the user individually disabled, which stay off.
*/
start(botId: string): { resumed: number } {
const manifest = this.store.get(botId);
if (!manifest) throw new Error(`Bot "${botId}" does not exist`);
this.held.delete(botId);
this.store.writeHeld(this.held);
// An explicit start is the owner saying "try again": paused routines
// resume with a clean streak (and a routine switched off for failing gets another chance).
const routines = this.store.readRoutineState(botId);
if (Object.keys(routines.paused).length > 0 || Object.keys(routines.noOutcomeStreak).length > 0 || Object.keys(routines.failStreak ?? {}).length > 0) {
this.store.writeRoutineState(botId, { paused: {}, noOutcomeStreak: {}, pauseCount: {}, lastEnd: routines.lastEnd ?? {}, failStreak: {} });
}
let resumed = this.rehydratePending(botId);
if (!manifest.enabled || this.disabled.has(botId)) {
this.setEnabled(botId, true); // persists enabled + pumps
} else {
this.pump(botId);
}
if (this.store.isLead(botId)) {
for (const crew of this.store.crewOf(botId)) {
const m = this.store.get(crew.id);
if (!m?.enabled || this.disabled.has(crew.id)) continue; // explicitly disabled crew stay off
this.held.delete(crew.id);
this.store.writeHeld(this.held);
resumed += this.rehydratePending(crew.id);
this.pump(crew.id);
resumed += this.start(crew.id).resumed;
}
}
return { resumed };
}
/** Pull durable pending jobs for a bot back into the in-memory queue. */
private rehydratePending(botId: string): number {
const pending = this.queue.pendingJobs(botId);
if (pending.length === 0) return 0;
const q = this.queues.get(botId) ?? [];
const running = this.running.get(botId) ?? new Set();
let added = 0;
for (const job of pending) {
if (q.some(j => j.id === job.id) || running.has(job.id)) continue;
q.push({
id: job.id, botId, trigger: job.trigger, prompt: job.prompt,
fromBot: job.fromBot, source: job.source, createdAt: job.createdAt, attempts: job.attempts,
});
added++;
}
if (added > 0) {
this.queues.set(botId, q);
logger.info({ botId, resumed: added }, 'Re-entered pending bot jobs (explicit resume)');
}
return added;
}
/** Fire a bot's configured routine immediately, or send a bare wake turn. */
/** How many bot turns are running right now (the updater waits for them). */
runningJobs(): number {
let n = 0;
for (const set of this.running.values()) n += set.size;
return n;
}
runNow(botId: string, routineName?: string): { accepted: boolean; jobId?: string; reasonCode?: string } {
const manifest = this.store.get(botId);
if (!manifest) return { accepted: false, reasonCode: 'target_unknown' };
if (routineName) {
const routine = (manifest.schedules ?? []).find(r => r.name.toLowerCase() === routineName.toLowerCase());
if (!routine) return { accepted: false, reasonCode: 'routine_unknown' };
return this.enqueue(botId, { trigger: 'cron', prompt: routine.prompt });
}
return this.enqueue(botId, { trigger: 'chat', prompt: WAKE_PROMPT });
}
setEnabled(botId: string, enabled: boolean): void {
if (enabled) {
this.disabled.delete(botId);
this.store.setEnabled(botId, true);
this.pump(botId);
} else {
this.disabled.add(botId);
void this.halt(botId);
this.store.setEnabled(botId, false);
}
this.invalidateRuntime(botId);
}
// ---- observation ---------------------------------------------------------
getStatusSummaries(): BotStatusSummary[] {
const unread = this.inbox.unreadByBot();
return this.store.list().map((m) => {
const running = this.running.get(m.id);
const queue = this.queues.get(m.id) ?? [];
const last = this.lastRun.get(m.id);
let state: BotLiveState = 'idle';
if (!m.enabled || this.disabled.has(m.id)) state = 'disabled';
else if (this.pausedForBudget.has(m.id)) state = 'paused';
else if ((running?.size ?? 0) > 0) state = 'running';
else if (queue.length > 0) state = 'queued';
return {
id: m.id,
name: m.name,
enabled: m.enabled,
state,
activity: this.activity.get(m.id),
lastRunAt: last?.at,
lastRunState: last?.state,
needsYou: this.needsYou.has(m.id),
hasAvatar: this.store.hasAvatar(m.id),
unread: unread.get(m.id) ?? 0,
tier: detectTier(this.store.readPermissions(m.id)),
...(this.held.has(m.id) ? { stopped: true } : {}),
...(m.description ? { description: m.description } : {}),
fleetRole: m.fleetRole,
parent: m.parent,
crewWorking: m.fleetRole === 'lead'
? this.store.crewOf(m.id).filter(c => (this.running.get(c.id)?.size ?? 0) > 0).length
: undefined,
routinePausedUntil: this.routinePausedUntil(m.id),
};
});
}
/** Earliest automatic resume among a bot's cooling-down routines. */
private routinePausedUntil(botId: string): number | undefined {
const paused = Object.values(this.store.readRoutineState(botId).paused);
if (paused.length === 0) return undefined;
const times = paused.map(p => (p.until ? Date.parse(p.until) : Number.POSITIVE_INFINITY));
return Math.min(...times);
}
getJournal(botId: string, limit = 20): BotRunRecord[] {
return this.journalFor(botId).read(botId, limit);
}
/** Drop dead-lettered jobs (one bot or all); the journal still has the runs. */
clearDlq(botId?: string): number {
const n = this.queue.clearDlq(botId);
if (botId) { if (!this.getDlq(botId).length) this.needsYou.delete(botId); }
else this.needsYou.clear();
return n;
}
/**
* Where the tokens go (ADR-022): per bot — today's spend against its cap
* and the totals over a window — rolled up per fleet.
*/
costReport(days = 7): BotCostReport {
const now = Date.now();
const dayStart = Date.parse(new Date(now).toISOString().slice(0, 10) + 'T00:00:00Z');
const since = now - days * 24 * 60 * 60 * 1000;
const bots: BotCostRow[] = [];
for (const m of this.store.list()) {
const journal = this.journalFor(m.id);
const today = journal.usage(m.id, dayStart);
const window = journal.usage(m.id, since);
bots.push({ id: m.id, name: m.name, parent: m.parent, today, window, cap: this.dailyCapFor(m), paused: this.pausedForBudget.has(m.id) });
}
const fleets = bots.filter(b => !b.parent).map(lead => {
const members = bots.filter(b => b.parent === lead.id || b.id === lead.id);
const sum = (pick: (b: BotCostRow) => BotUsage) => members.reduce((acc, b) => { const u = pick(b); acc.runs += u.runs; acc.tokensIn += u.tokensIn; acc.tokensOut += u.tokensOut; acc.deliverables += u.deliverables; acc.noOutcome += u.noOutcome; acc.completed += u.completed; acc.failed += u.failed; return acc; }, { runs: 0, completed: 0, failed: 0, noOutcome: 0, deliverables: 0, tokensIn: 0, tokensOut: 0 });
return { id: lead.id, name: lead.name, members: members.length, today: sum(b => b.today), window: sum(b => b.window) };
});
const fleetCap = this.config.bots?.fleetDailyTokenBudget ?? 0;
const fleetToday = this.fleetDailyTokens.day === new Date(now).toISOString().slice(0, 10) ? this.fleetDailyTokens.tokens : 0;
return { days, bots, fleets, fleetToday, fleetCap, fleetPaused: this.fleetPausedDay === new Date(now).toISOString().slice(0, 10) };
}
/** Fleet kill switch: stop every lead and solo (crew cascade), hold their jobs. */
async stopAll(): Promise<{ stopped: number; halted: number; heldJobs: number }> {
let stopped = 0, halted = 0, heldJobs = 0;
for (const m of this.store.list()) {
if (m.parent) continue;
const r = await this.stop(m.id);
stopped += 1 + r.crewStopped;
if (r.halted) halted++;
heldJobs += r.heldJobs;
}
logger.warn({ stopped, halted, heldJobs }, 'All bots stopped (kill switch)');
return { stopped, halted, heldJobs };
}
startAll(): { started: number; resumed: number } {
let started = 0, resumed = 0;
for (const m of this.store.list()) {
if (m.parent || !m.enabled) continue;
resumed += this.start(m.id).resumed;
started++;
}
return { started, resumed };
}
listTranscripts(botId: string): Array<{ runId: string; mtimeMs: number }> {
return this.journalFor(botId).listTranscripts(botId).map(t => ({ runId: t.runId, mtimeMs: t.mtimeMs }));
}
readTranscript(botId: string, runId?: string): BotTranscript | null {
return this.journalFor(botId).readTranscript(botId, runId);
}
getDlq(botId?: string): DurableBotJob[] {
return this.queue.listDlq(botId);
}
/** Re-run a dead-lettered job: remove it from the DLQ and re-enqueue fresh. */
replayDlq(botId: string, jobId: string): { accepted: boolean; jobId?: string; reasonCode?: string } {
// Look up WITHOUT removing first: a bot-id mismatch must not destroy the
// DLQ entry (the old remove-then-check permanently deleted real work and
// then reported not_found).
const entry = this.queue.peekDlq(jobId);
if (!entry || entry.botId !== botId) return { accepted: false, reasonCode: 'not_found' };
const result = this.enqueue(botId, {
trigger: entry.trigger,
// The owner explicitly chose this job. Bypass routine timing/pause gates
// for this admission only; future ticks stay paused and a new crash still
// has cron recovery semantics.
manualReplay: true,
attachments: entry.attachments,
prompt: entry.prompt,
fromBot: entry.fromBot,
source: entry.source,
attempts: 0,
});
if (result.accepted) this.queue.removeFromDlq(jobId);
return result;
}
getStorage(): Array<{ id: string; bytes: number; journalBytes: number }> {
return this.store.usage();
}
getQueuedCount(botId: string): number {
return (this.queues.get(botId) ?? []).length;
}
/** Resolve a bot by id or case-insensitive name (for @mention routing). */
resolveBotId(nameOrId: string): string | null {
const needle = nameOrId.toLowerCase();
for (const m of this.store.list()) {
if (m.id === needle || m.name.toLowerCase() === needle) return m.id;
}
return null;
}
/**
* Compact bots section for the MAIN agent's system prompt: without it the
* conversational agent is blind to the bot fleet — it cannot answer "what
* do my bots do" or hand a task to the right specialist. Kept to a few
* lines per bot so the token cost stays trivial.
*/
getSystemPromptSection(): string {
const summaries = this.store.list();
if (summaries.length === 0) {
// Empty fleet: no prompt section at all — zero-bots users must see
// zero prompt/token drift (review A1).
return '';
}
const lines: string[] = [
'\n\nMercury Bots — the user maintains these persistent specialist agents (each has its own persona, model, memory, and permissions; they run OUTSIDE this conversation):',
];
for (const m of summaries) {
const state = this.running.get(m.id)?.size ? 'running' : ((this.queues.get(m.id)?.length ?? 0) > 0 ? 'queued' : (m.enabled ? 'idle' : 'disabled'));
const desc = m.description ? ` — ${m.description}` : '';
const fleetTag = m.fleetRole === 'lead' ? ' [fleet lead 👑]' : m.fleetRole === 'crew' ? ` [crew of ${m.parent}]` : '';
lines.push(`- **${m.name}** (\`${m.id}\`)${desc}${fleetTag} [${state}]`);
}
lines.push(`Bot control (never route bot work through this main conversation):
- \`/bot <id> <message>\` or \`@<id> <message>\` — dispatch a task to a bot; the result lands ONLY in the bot's own thread (\`/bots open <id>\`), never in this chat.
- \`/bots open <id>\` — open the bot's own chat; \`/bots\` — roster with live states.
- \`/bots create <id> "Name" "Description"\` — onboard; \`/bots persona <id> <text>\` — set its character.
- \`/bots export <id> [path]\` — shareable bundle (manifests + personas + permissions + skills; a lead's bundle carries its whole crew); \`/bots import <path>\` — recreate bots from a bundle (imported bots start disabled). Sandbox, journals, and .env never travel.
- \`/bots journal <id>\` — recent runs; \`/bots dlq\` — failed jobs (replayable); \`/bots stop|start|enable|disable <id>\`; \`/bots run <id> [routine]\` — fire a routine now (or a bare wake).
- Bots share data through the fleet-shared folder (\`${this.store.sharedSandboxDir()}\`); each also has a private sandbox next to its persona. Their outputs land in their own threads.
- The dispatch_bot tool lets you hand a task to a bot mid-conversation and continue talking; the result is delivered when the bot finishes.`);
return lines.join('\n');
}
/**
* Release timers and native queue handles. Idempotent — safe to call twice.
* Teardown MUST run this before deleting the bots root: on Windows an open
* SQLite handle keeps queue.db locked and its directory impossible to
* remove (EBUSY). Wired into the process shutdown and every test teardown.
*/
dispose(): void {
if (this.dueTimer) {
clearInterval(this.dueTimer);
this.dueTimer = undefined;
}
this.queue.close();
}
/**
* bot_deliver (ADR-020): move a finished artifact out of the bot's
* writable areas (its private sandbox or the fleet-shared folder) into
* the OWNER-VISIBLE deliverables folder (default ~/Documents/Mercury/
* <Bot name>/). Finals land on top of the folder; everything else goes
* under work/ (a crew bot's deliveries always do — the lead delivers the
* final). Files are named "YYYY-MM-DD <title>.<ext>" and the folder keeps
* a README index. Only files from the bot's OWN writable roots travel
* (containment is enforced); the source is removed on success (a move).
*/
deliver(
botId: string,
filePath: string,
opts: string | { saveAs?: string; title?: string; final?: boolean } = {},
): { accepted: boolean; path?: string; final?: boolean; reasonCode?: string } {
const options = typeof opts === 'string' ? { saveAs: opts } : opts;
const manifest = this.store.get(botId);
if (!manifest) return { accepted: false, reasonCode: 'target_unknown' };
// Relative paths are relative to the bot's sandbox (with "_shared/…"
// meaning the fleet folder), never to wherever the daemon was started.
const sandbox = this.store.sandboxDir(botId);
const getCwd: CwdSource = Object.assign(() => sandbox, {
roots: () => [['sandbox', sandbox], [BOT_SHARED_SANDBOX_DIRNAME, this.store.sharedSandboxDir()]] as const,
});
const candidate = resolveToolPath(filePath.replace(/^~(?=$|\/|\\)/, homedir()), getCwd);
const allowedBases = [this.store.sharedSandboxDir(), this.store.sandboxDir(botId)];
const inside = allowedBases.some((base) => {
const rel = relative(resolve(base), candidate);
return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
});
if (!inside || !existsSync(candidate) || !statSync(candidate).isFile()) {
return { accepted: false, reasonCode: 'outside_sandbox' };
}
const isCrew = Boolean(manifest.parent);
const final = Boolean(options.final) && !isCrew;
// Pin before the folder is created: from here on the folder name belongs to the files, not to
// whatever the bot is called today.
const botFolder = this.store.pinDeliverablesFolder(botId);
const destDir = isCrew ? botFolder : final ? botFolder : join(botFolder, 'work');
mkdirSync(destDir, { recursive: true });
// The same content delivered again (a retry, a re-run) is the file already
// there, not "Report (2).md" next to it.
const same = sameContentIn(destDir, candidate);
if (same) {
try { unlinkSync(candidate); } catch { /* the source copy is the bot's; leave it */ }
logger.info({ botId, dest: same }, 'Bot re-delivered an artifact already in the folder');
return { accepted: true, path: same, final };
}
const sourceName = options.saveAs || basename(candidate);
// A file without an extension opens as nothing on the owner's computer: text becomes .md.
const ext = extname(sourceName) || extname(candidate) || (looksLikeText(candidate) ? '.md' : '');
const stem = options.title?.trim() || basename(sourceName, ext);
const fileName = deliverableFileName(stem, ext);
const finalExt = extname(fileName);
const requested = basename(fileName, finalExt);
let dest = join(destDir, fileName);
for (let i = 2; existsSync(dest); i++) {
dest = join(destDir, `${requested} (${i})${finalExt}`);
}
try {
renameSync(candidate, dest);
} catch {
try {
copyFileSync(candidate, dest);
unlinkSync(candidate);
} catch {
return { accepted: false, reasonCode: 'move_failed' };
}
}
// The index lives on the fleet folder (finals on top); crew work is
// reachable from it under work/.
this.store.writeDeliverablesIndex(isCrew ? this.store.deliverablesDir(manifest.parent!) : botFolder);
logger.info({ botId, dest, final }, 'Bot delivered an artifact');
this.emitBotActivity({
botId,
jobId: '',
kind: 'tool',
label: `Delivered ${basename(dest)}`,
detail: dest,
stepIndex: 0,
elapsedMs: 0,
status: 'done',
});
return { accepted: true, path: dest, final };
}
/**
* One-time move of the hidden legacy outputs zone
* (~/.mercury/bots/outputs/<botId>/) into the visible deliverables folder.
* Idempotent: whatever is still there moves; a README pointer is left
* behind so an owner with a bookmark finds the new place.
*/
migrateDeliverables(): { moved: number } {
// Existing bots: pin the folder they already use, so the first rename after this upgrade does
// not move their deliverables. Runs before the legacy scan, which may return early.
for (const manifest of this.store.list()) {
if (manifest.parent) continue;
this.store.pinDeliverablesFolder(manifest.id);
}
const legacy = this.store.outputsDir();
if (!existsSync(legacy)) return { moved: 0 };
let moved = 0;
for (const entry of readdirSync(legacy, { withFileTypes: true })) {
if (!entry.isDirectory() || !this.store.exists(entry.name)) continue;
const from = join(legacy, entry.name);
const manifest = this.store.get(entry.name)!;
const to = manifest.parent ? this.store.deliverablesDir(entry.name) : join(this.store.deliverablesDir(entry.name), 'work');
for (const file of readdirSync(from, { withFileTypes: true })) {
if (!file.isFile()) continue;
try {
mkdirSync(to, { recursive: true });
let dest = join(to, file.name);
for (let i = 2; existsSync(dest); i++) dest = join(to, `${basename(file.name, extname(file.name))} (${i})${extname(file.name)}`);
renameSync(join(from, file.name), dest);
moved++;
} catch (err) {
logger.warn({ botId: entry.name, file: file.name, err: (err as Error)?.message }, 'Legacy deliverable could not be moved');
}
}
try { if (readdirSync(from).length === 0) rmSync(from, { recursive: true }); } catch { /* keep */ }
this.store.writeDeliverablesIndex(manifest.parent ? this.store.deliverablesDir(manifest.parent) : this.store.deliverablesDir(entry.name));
}
if (moved > 0) {
try {
writeFileSync(join(legacy, 'README.md'), `Deliverables moved to ${this.store.deliverablesRoot()} (Mercury 1.3.1, ADR-020).\nThis folder is no longer used.\n`, 'utf-8');
} catch { /* best effort */ }
logger.info({ moved, to: this.store.deliverablesRoot() }, 'Legacy bot outputs moved to the deliverables folder');
}
return { moved };
}
/** Finals (top of a bot's folder) and work (under work/), newest first. */
listDeliverables(botId?: string): Array<{ botId: string; name: string; bytes: number; mtimeMs: number; path: string; final: boolean }> {
const bots = botId ? [botId] : this.store.list().map(m => m.id);
const out: Array<{ botId: string; name: string; bytes: number; mtimeMs: number; path: string; final: boolean }> = [];
const scan = (bot: string, dir: string, prefix: string, final: boolean): void => {
if (!existsSync(dir)) return;
for (const e of readdirSync(dir, { withFileTypes: true })) {
if (!e.isFile() || e.name === 'README.md' || e.name.startsWith('.')) continue;
try {
const stat = statSync(join(dir, e.name));
out.push({ botId: bot, name: prefix + e.name, bytes: stat.size, mtimeMs: stat.mtimeMs, path: join(dir, e.name), final });
} catch { /* raced a concurrent delete — skip */ }
}
};
for (const bot of bots) {
const manifest = this.store.get(bot);
if (!manifest) continue;
const dir = this.store.deliverablesDir(bot);
if (manifest.parent) {
scan(bot, dir, '', false);
} else {
scan(bot, dir, '', true);
scan(bot, join(dir, 'work'), 'work/', false);
}
}
return out.sort((a, b) => b.mtimeMs - a.mtimeMs);
}
/** Contained path resolution for deliverable access; null when it escapes. Public for the web API's byte-exact download route. */
deliverableFile(botId: string, name: string): string | null {
if (!this.store.exists(botId)) return null;
const dir = this.store.deliverablesDir(botId);
const candidate = resolve(dir, name);
const rel = relative(dir, candidate);
if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return null;
return candidate;
}
readDeliverable(botId: string, name: string, maxBytes = 64 * 1024): { found: boolean; preview?: string; truncated?: boolean } {
const file = this.deliverableFile(botId, name);
if (!file || !existsSync(file)) return { found: false };
const buf = readFileSync(file);
return {
found: true,
preview: buf.subarray(0, maxBytes).toString('utf-8'),
truncated: buf.length > maxBytes,
};
}
deleteDeliverable(botId: string, name: string): { ok: boolean } {
const file = this.deliverableFile(botId, name);
if (!file || !existsSync(file)) return { ok: false };
unlinkSync(file);
return { ok: true };
}
/**
* Retention janitor sweep: files in the fleet-shared folder cool down into
* `_shared/.archive/<yyyy-mm>/` past the hot window, and the archive
* expires after the archive window — the working surface stays small while
* an incorrectly aged-out file stays recoverable for a month.
*/
sweepRetention(): void {
const sandbox = this.config.bots?.retention?.sandboxJanitor;
if (sandbox?.enabled === false) return;
const result = sweepSharedSandbox(this.store.botsRoot, {
hotDays: sandbox?.hotDays ?? 7,
archiveDays: sandbox?.archiveDays ?? 30,
});
const touched = result.moved.length + result.deleted.length;
if (touched > 0 || result.errors.length > 0) {
logger.info(
{ moved: result.moved.length, deleted: result.deleted.length, kept: result.kept, errors: result.errors },
'Sandbox retention sweep',
);
}
}
}
function resolveProvider(providers: ProviderRegistry, manifest: BotManifest, config?: MercuryConfig) {
const requested = manifest.model?.provider;
const getUsable = typeof providers.getUsable === 'function' ? providers.getUsable.bind(providers) : (name?: string) => (name ? providers.get(name) : undefined);
const provider = getUsable(requested);
if (provider) return provider;
if (requested) {
logger.warn({ botId: manifest.id, requested }, 'Bot provider not registered or not usable (no key / key rejected) — falling back to default');
}
// Crew lane (ADR-021): stage work on a cheaper provider when the fleet
// config names one and the crew bot has no choice of its own.
const crewProvider = manifest.parent ? config?.bots?.fleets?.crewProvider : undefined;
const crewLane = getUsable(crewProvider);
if (crewLane) return crewLane;
return providers.getDefault();
}
function describeJob(job: BotJob): string {
switch (job.trigger) {
case 'chat': return job.prompt ? `Responding: ${job.prompt.slice(0, 60)}` : 'Responding';
case 'mailbox': return job.fromBot ? `Handling message from ${job.fromBot}` : 'Handling mailbox';
case 'cron': return `Scheduled routine: ${job.prompt.slice(0, 60)}`;
default: return `Handling ${job.trigger} request`;
}
}
// Re-exported for the /bots storage view.
export { BOT_JOURNAL_FILENAME };
/** A file in `dir` with exactly the bytes of `file`, if any (size first, then content). */
function sameContentIn(dir: string, file: string): string | undefined {
try {
const size = statSync(file).size;
const want = createHash('sha256').update(readFileSync(file)).digest('hex');
for (const name of readdirSync(dir)) {
const p = join(dir, name);
const st = statSync(p);
if (!st.isFile() || st.size !== size || name === 'README.md') continue;
if (createHash('sha256').update(readFileSync(p)).digest('hex') === want) return p;
}
} catch { /* no folder yet, or unreadable: deliver normally */ }
return undefined;
}
/** No NUL bytes in the first 4 KB: text. */
function looksLikeText(file: string): boolean {
try {
const buf = readFileSync(file).subarray(0, 4096);
return !buf.includes(0);
} catch {
return false;
}
}