Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { z } from 'zod';
import type { ChannelMessage } from '../types/channel.js';
import { getMercuryHome } from '../utils/config.js';
import { logger } from '../utils/logger.js';
const channelMessageSchema = z.object({
id: z.string(),
channelId: z.string(),
channelType: z.enum(['cli', 'telegram', 'web', 'internal', 'signal', 'discord', 'slack', 'whatsapp', 'desktop']),
senderId: z.string(),
senderName: z.string().optional(),
content: z.string(),
timestamp: z.number().finite(),
sessionId: z.string().optional(),
metadata: z.record(z.unknown()).optional(),
});
const workEntrySchema = z.object({
key: z.string(),
message: channelMessageSchema,
status: z.enum(['queued', 'running', 'paused', 'completed', 'failed', 'cancelled']),
attempts: z.number().int().nonnegative(),
acceptedAt: z.number().finite(),
updatedAt: z.number().finite(),
startedAt: z.number().finite().optional(),
completedAt: z.number().finite().optional(),
finalResponse: z.string().optional(),
error: z.string().optional(),
delivered: z.boolean(),
deliveryError: z.string().optional(),
nextAttemptAt: z.number().finite().optional(),
});
const ledgerSchema = z.object({
version: z.literal(1),
entries: z.array(workEntrySchema),
});
export type WorkStatus = 'queued' | 'running' | 'paused' | 'completed' | 'failed' | 'cancelled';
export type WorkEntry = z.infer<typeof workEntrySchema>;
export interface WorkLedgerOptions {
filePath?: string;
maxTerminalEntries?: number;
terminalMaxAgeMs?: number;
now?: () => number;
}
export interface WorkContinuationContext {
workCwd?: string;
activity?: string;
summary?: string;
continuation?: boolean;
}
const DEFAULT_MAX_TERMINAL_ENTRIES = 500;
const DEFAULT_TERMINAL_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
export function getWorkKey(message: ChannelMessage): string {
const requestId = message.metadata?.requestId;
if (typeof requestId === 'string' && requestId.trim()) return `request:${requestId}`;
const canonicalMessageId = message.metadata?.canonicalMessageId;
if (typeof canonicalMessageId === 'string' && canonicalMessageId.trim()) return `canonical:${canonicalMessageId}`;
return `channel:${message.channelType}:${message.id}`;
}
export class WorkLedger {
private entries = new Map<string, WorkEntry>();
private readonly filePath: string;
private readonly maxTerminalEntries: number;
private readonly terminalMaxAgeMs: number;
private readonly now: () => number;
constructor(options: WorkLedgerOptions = {}) {
this.filePath = options.filePath ?? join(getMercuryHome(), 'work-ledger.json');
this.maxTerminalEntries = options.maxTerminalEntries ?? DEFAULT_MAX_TERMINAL_ENTRIES;
this.terminalMaxAgeMs = options.terminalMaxAgeMs ?? DEFAULT_TERMINAL_MAX_AGE_MS;
this.now = options.now ?? Date.now;
this.load();
}
accept(message: ChannelMessage): { accepted: boolean; entry: WorkEntry } {
const key = getWorkKey(message);
const existing = this.entries.get(key);
if (existing) return { accepted: false, entry: structuredClone(existing) };
const now = this.now();
const entry: WorkEntry = {
key,
message: channelMessageSchema.parse(JSON.parse(JSON.stringify(message))),
status: 'queued',
attempts: 0,
acceptedAt: now,
updatedAt: now,
delivered: false,
};
this.entries.set(key, entry);
this.persist();
return { accepted: true, entry: structuredClone(entry) };
}
get(key: string): WorkEntry | undefined {
const entry = this.entries.get(key);
return entry ? structuredClone(entry) : undefined;
}
markRunning(key: string): WorkEntry {
return this.update(key, (entry) => {
if (entry.status === 'cancelled') return;
entry.status = 'running';
entry.attempts += 1;
entry.startedAt = this.now();
entry.error = undefined;
entry.nextAttemptAt = undefined;
});
}
markCompleted(key: string, finalResponse: string): WorkEntry {
return this.update(key, (entry) => {
// A user-cancelled entry is terminal — do not resurrect it.
if (entry.status === 'cancelled') return;
entry.status = 'completed';
entry.completedAt = this.now();
entry.finalResponse = finalResponse;
entry.error = undefined;
entry.delivered = false;
entry.deliveryError = undefined;
});
}
markFailed(key: string, error: unknown, finalResponse?: string): WorkEntry {
return this.update(key, (entry) => {
if (entry.status === 'cancelled') return;
entry.status = 'failed';
entry.completedAt = this.now();
entry.error = error instanceof Error ? error.message : String(error);
entry.finalResponse = finalResponse ?? `I couldn't finish this request: ${entry.error}`;
entry.delivered = false;
});
}
/**
* Pause an in-flight task honestly: the work is NOT done (step budget
* exhausted, stall, interruption), so it must never read as completed.
* Paused entries carry a resume hint and are recovered on restart like
* interrupted work — a "continue" message (or a restart) resumes them.
*/
markPaused(key: string, reason: string): WorkEntry {
return this.update(key, (entry) => {
if (entry.status === 'cancelled') return;
entry.status = 'paused';
entry.completedAt = this.now();
entry.error = reason;
entry.finalResponse = reason;
entry.delivered = false;
});
}
/**
* Mark a single entry as cancelled by the user (terminal state).
* Cancelled entries are NEVER auto-resumed by recoverInterrupted().
*/
markCancelled(key: string, reason = 'Cancelled by the user'): WorkEntry {
return this.update(key, (entry) => {
entry.status = 'cancelled';
entry.completedAt = this.now();
entry.error = undefined;
entry.nextAttemptAt = undefined;
entry.finalResponse = `This task was cancelled by the user before it completed. Nothing was lost — send "continue" if you want Mercury to resume it.`;
entry.delivered = false;
void reason;
});
}
/**
* Deliberate-shutdown sweep: every queued or running entry is marked
* cancelled so a restart does NOT silently resume work the user chose
* to stop. Called from /exit, SIGTERM/SIGINT shutdown, and the TUI
* Ctrl+C exit path. Real crashes never reach this — their running
* entries survive and recoverInterrupted() resumes them.
*/
cancelActive(reason = 'Mercury was stopped by the user'): number {
let count = 0;
for (const entry of this.entries.values()) {
if (entry.status !== 'queued' && entry.status !== 'running') continue;
this.markCancelled(entry.key, reason);
count += 1;
}
if (count > 0) {
logger.info({ count }, 'Deliberate shutdown: active work marked cancelled (no auto-resume)');
}
return count;
}
markRetry(key: string, error: unknown, nextAttemptAt: number, context: WorkContinuationContext = {}): WorkEntry {
return this.update(key, (entry) => {
// A user-cancelled entry is terminal: a retry scheduled by a turn the
// owner stopped must never bring it back (ADR-038).
if (entry.status === 'cancelled') return;
entry.status = 'queued';
entry.error = error instanceof Error ? error.message : String(error);
entry.nextAttemptAt = nextAttemptAt;
entry.delivered = false;
entry.completedAt = undefined;
entry.finalResponse = undefined;
entry.deliveryError = undefined;
const previousContinuationAttempt = typeof entry.message.metadata?.continuationAttempt === 'number'
? entry.message.metadata.continuationAttempt
: 0;
entry.message.metadata = {
...entry.message.metadata,
workRecovered: true,
workWasInterrupted: true,
...(context.continuation ? { workContinuation: true, continuationAttempt: previousContinuationAttempt + 1 } : {}),
...(context.workCwd ? { workCwd: context.workCwd } : {}),
...(context.activity ? { continuationActivity: context.activity.slice(0, 300) } : {}),
...(context.summary ? { continuationSummary: context.summary.slice(0, 1000) } : {}),
continuationReason: entry.error.slice(0, 1000),
};
});
}
markDelivered(key: string): WorkEntry {
return this.update(key, (entry) => {
entry.delivered = true;
entry.deliveryError = undefined;
});
}
markDeliveryError(key: string, error: unknown): WorkEntry {
return this.update(key, (entry) => {
entry.delivered = false;
entry.deliveryError = error instanceof Error ? error.message : String(error);
});
}
recoverInterrupted(): WorkEntry[] {
const recovered: WorkEntry[] = [];
for (const entry of this.entries.values()) {
const recoverableFailure = entry.status === 'failed' && /interrupted\/ambiguous|side effects may be partial|after one or more tools completed|partial output/i.test(entry.error || '');
const isPaused = entry.status === 'paused';
if (entry.status !== 'queued' && entry.status !== 'running' && !recoverableFailure && !isPaused) continue;
if (typeof entry.message.metadata?.scheduledTaskId === 'string') {
// The scheduler owns recovery. Never replay a turn whose external effects
// may have happened before the process stopped, even if it was queued.
this.markFailed(entry.key, 'Scheduled run interrupted; inspect its effects and explicitly reschedule it.');
continue;
}
const interrupted = entry.status === 'running' || isPaused;
entry.status = 'queued';
entry.updatedAt = this.now();
entry.completedAt = undefined;
entry.finalResponse = undefined;
entry.delivered = false;
entry.message.metadata = {
...entry.message.metadata,
workRecovered: true,
workWasInterrupted: interrupted || recoverableFailure,
...(recoverableFailure || isPaused ? {
workContinuation: true,
continuationAttempt: (typeof entry.message.metadata?.continuationAttempt === 'number' ? entry.message.metadata.continuationAttempt : 0) + 1,
continuationReason: entry.error?.slice(0, 1000),
} : {}),
};
recovered.push(structuredClone(entry));
}
if (recovered.length > 0) this.persist();
return recovered;
}
/** Cancelled and paused entries carry a resume hint instead of a real response. */
getUndeliveredResponses(): WorkEntry[] {
return [...this.entries.values()]
.filter((entry) => ((entry.status === 'completed' || entry.status === 'failed') && !entry.delivered && typeof entry.finalResponse === 'string')
|| ((entry.status === 'cancelled' || entry.status === 'paused') && !entry.delivered))
.sort((a, b) => a.acceptedAt - b.acceptedAt)
.map((entry) => structuredClone(entry));
}
private update(key: string, mutate: (entry: WorkEntry) => void): WorkEntry {
const entry = this.entries.get(key);
if (!entry) throw new Error(`Unknown work ledger entry: ${key}`);
mutate(entry);
entry.updatedAt = this.now();
this.persist();
return structuredClone(entry);
}
private load(): void {
if (!existsSync(this.filePath)) return;
try {
const parsed = ledgerSchema.parse(JSON.parse(readFileSync(this.filePath, 'utf8')));
this.entries = new Map(parsed.entries.map((entry) => [entry.key, entry]));
} catch (error) {
const recoveryPath = `${this.filePath}.corrupt-${this.now()}`;
try {
renameSync(this.filePath, recoveryPath);
} catch (renameError) {
logger.warn({ renameError, filePath: this.filePath }, 'Unable to quarantine invalid work ledger');
}
this.entries.clear();
logger.error({ error, recoveryPath }, 'Invalid work ledger quarantined; starting with an empty ledger');
this.persist();
}
}
private persist(): void {
this.prune();
const dir = dirname(this.filePath);
mkdirSync(dir, { recursive: true, mode: 0o700 });
const tempPath = `${this.filePath}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
const payload = JSON.stringify({ version: 1, entries: [...this.entries.values()] }, null, 2) + '\n';
let fd: number | undefined;
try {
fd = openSync(tempPath, 'wx', 0o600);
const buffer = Buffer.from(payload);
let offset = 0;
while (offset < buffer.length) {
const written = writeSync(fd, buffer, offset, buffer.length - offset);
offset += written;
}
fsyncSync(fd);
closeSync(fd);
fd = undefined;
renameSync(tempPath, this.filePath);
chmodSync(this.filePath, 0o600);
let dirFd: number | undefined;
try {
dirFd = openSync(dir, 'r');
fsyncSync(dirFd);
} catch {
// Directory fsync is not supported on every platform/filesystem.
} finally {
if (dirFd !== undefined) closeSync(dirFd);
}
} finally {
if (fd !== undefined) closeSync(fd);
if (existsSync(tempPath)) {
try { unlinkSync(tempPath); } catch { /* best effort */ }
}
}
}
private prune(): void {
const terminal = [...this.entries.values()]
.filter((entry) => entry.status === 'failed' || entry.status === 'cancelled' || (entry.status === 'completed' && entry.delivered))
.sort((a, b) => b.updatedAt - a.updatedAt);
const cutoff = this.now() - this.terminalMaxAgeMs;
for (let index = 0; index < terminal.length; index++) {
const entry = terminal[index];
if (index >= this.maxTerminalEntries || entry.updatedAt < cutoff) this.entries.delete(entry.key);
}
}
}