Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.
import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
import { tmpdir, platform } from 'node:os';
import { join } from 'node:path';
import { afterEach, describe, expect, it } from 'vitest';
import type { ChannelMessage } from '../types/channel.js';
import { getWorkKey, WorkLedger } from './work-ledger.js';
const dirs: string[] = [];
afterEach(() => {
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
function setup(options: { maxTerminalEntries?: number; now?: () => number } = {}) {
const dir = mkdtempSync(join(tmpdir(), 'mercury-work-ledger-'));
dirs.push(dir);
const filePath = join(dir, 'work-ledger.json');
return { dir, filePath, ledger: new WorkLedger({ filePath, ...options }) };
}
function message(id: string, metadata?: Record<string, unknown>): ChannelMessage {
return {
id,
channelId: 'chat-1',
channelType: 'signal',
senderId: 'user-1',
content: `work ${id}`,
timestamp: 100,
metadata,
};
}
describe('WorkLedger', () => {
it('uses stable identifier precedence and rejects duplicate acceptance', () => {
const { ledger } = setup();
const msg = message('transport-id', { requestId: 'request-id', canonicalMessageId: 'canonical-id' });
expect(getWorkKey(msg)).toBe('request:request-id');
expect(ledger.accept(msg).accepted).toBe(true);
expect(ledger.accept({ ...msg, content: 'duplicate payload' }).accepted).toBe(false);
expect(ledger.get('request:request-id')?.message.content).toBe('work transport-id');
});
it('atomically persists owner-only state and recovers interrupted jobs', () => {
const { filePath, ledger } = setup();
const queued = ledger.accept(message('queued')).entry;
const running = ledger.accept(message('running')).entry;
ledger.markRunning(running.key);
const recovered = new WorkLedger({ filePath }).recoverInterrupted();
expect(recovered.map((entry) => entry.key)).toEqual([queued.key, running.key]);
expect(recovered[0].message.metadata?.workRecovered).toBe(true);
expect(recovered[0].message.metadata?.workWasInterrupted).toBe(false);
expect(recovered[1].message.metadata?.workWasInterrupted).toBe(true);
expect(recovered[1].attempts).toBe(1);
if (platform() !== 'win32') {
expect(statSync(filePath).mode & 0o777).toBe(0o600);
}
expect(JSON.parse(readFileSync(filePath, 'utf8')).version).toBe(1);
});
it('keeps completed responses in the outbox until delivery succeeds', () => {
const { filePath, ledger } = setup();
const entry = ledger.accept(message('outbox')).entry;
ledger.markRunning(entry.key);
ledger.markCompleted(entry.key, 'durable result');
ledger.markDeliveryError(entry.key, new Error('offline'));
const restarted = new WorkLedger({ filePath });
expect(restarted.getUndeliveredResponses()).toMatchObject([
{ key: entry.key, finalResponse: 'durable result', delivered: false, deliveryError: 'offline' },
]);
restarted.markDelivered(entry.key);
expect(new WorkLedger({ filePath }).getUndeliveredResponses()).toEqual([]);
});
it('keeps explicit failure responses retryable until delivered', () => {
const { ledger } = setup();
const entry = ledger.accept(message('failed-outbox')).entry;
ledger.markRunning(entry.key);
ledger.markFailed(entry.key, 'provider unavailable', 'Mercury could not finish after retrying providers.');
expect(ledger.getUndeliveredResponses()).toMatchObject([
{ key: entry.key, status: 'failed', finalResponse: 'Mercury could not finish after retrying providers.', delivered: false },
]);
});
it('persists delayed retries as queued work', () => {
const { filePath, ledger } = setup();
const entry = ledger.accept(message('retry')).entry;
ledger.markRunning(entry.key);
ledger.markRetry(entry.key, 'network unavailable', 50_000);
const restored = new WorkLedger({ filePath }).get(entry.key);
expect(restored).toMatchObject({ status: 'queued', attempts: 1, error: 'network unavailable', nextAttemptAt: 50_000 });
});
it('checkpoints continuation context instead of discarding completed tool progress', () => {
const { filePath, ledger } = setup();
const entry = ledger.accept(message('continuation')).entry;
ledger.markRunning(entry.key);
ledger.markRetry(entry.key, 'Generation was interrupted after one or more tools completed', 10_000, {
continuation: true,
workCwd: '/tmp/project',
activity: 'Writing composition',
summary: 'Screenshot and voiceover completed',
});
const restored = new WorkLedger({ filePath }).get(entry.key);
expect(restored).toMatchObject({
status: 'queued',
message: { metadata: {
workContinuation: true,
continuationAttempt: 1,
workCwd: '/tmp/project',
continuationActivity: 'Writing composition',
continuationSummary: 'Screenshot and voiceover completed',
} },
});
expect(restored).not.toHaveProperty('finalResponse');
});
it('automatically revives legacy ambiguous failures after an upgrade', () => {
const { filePath, ledger } = setup();
const entry = ledger.accept(message('legacy-interruption')).entry;
ledger.markRunning(entry.key);
ledger.markFailed(entry.key, 'Work stopped in an interrupted/ambiguous state; side effects may be partial');
ledger.markDelivered(entry.key);
const recovered = new WorkLedger({ filePath }).recoverInterrupted();
expect(recovered).toHaveLength(1);
expect(recovered[0]).toMatchObject({
status: 'queued',
delivered: false,
finalResponse: undefined,
message: { metadata: { workContinuation: true, continuationAttempt: 1 } },
});
});
it('quarantines invalid state and starts a valid empty ledger', () => {
const { dir, filePath } = setup();
writeFileSync(filePath, '{not-json', { mode: 0o600 });
const ledger = new WorkLedger({ filePath, now: () => 1234 });
expect(ledger.getUndeliveredResponses()).toEqual([]);
expect(readdirSync(dir)).toContain('work-ledger.json.corrupt-1234');
expect(JSON.parse(readFileSync(filePath, 'utf8'))).toEqual({ version: 1, entries: [] });
});
it('bounds terminal history without pruning active work', () => {
let now = 1_000;
const { ledger } = setup({ maxTerminalEntries: 1, now: () => now++ });
const active = ledger.accept(message('active')).entry;
const first = ledger.accept(message('first')).entry;
ledger.markFailed(first.key, 'first failed');
const second = ledger.accept(message('second')).entry;
ledger.markCompleted(second.key, 'second complete');
ledger.markDelivered(second.key);
expect(ledger.get(active.key)?.status).toBe('queued');
expect(ledger.get(second.key)?.status).toBe('completed');
expect(ledger.get(first.key)).toBeUndefined();
});
it('cancelActive marks queued and running work cancelled so restart never resumes it', () => {
const { filePath, ledger } = setup();
const queued = ledger.accept(message('queued')).entry;
const running = ledger.accept(message('running')).entry;
ledger.markRunning(running.key);
const done = ledger.accept(message('done')).entry;
ledger.markCompleted(done.key, 'already done');
ledger.markDelivered(done.key);
const cancelledCount = ledger.cancelActive('Test deliberate stop');
expect(cancelledCount).toBe(2);
expect(ledger.get(queued.key)?.status).toBe('cancelled');
expect(ledger.get(running.key)?.status).toBe('cancelled');
expect(ledger.get(done.key)?.status).toBe('completed');
// A restart must NOT resurrect cancelled entries.
const recovered = new WorkLedger({ filePath }).recoverInterrupted();
expect(recovered).toHaveLength(0);
expect(new WorkLedger({ filePath }).get(queued.key)?.status).toBe('cancelled');
});
it('cancelled entries carry a resume hint via the undelivered outbox', () => {
const { filePath, ledger } = setup();
const entry = ledger.accept(message('killed')).entry;
ledger.markRunning(entry.key);
ledger.cancelActive('Test stop');
const outbox = new WorkLedger({ filePath }).getUndeliveredResponses();
expect(outbox).toHaveLength(1);
expect(outbox[0].status).toBe('cancelled');
expect(outbox[0].finalResponse).toContain('cancelled');
});
it('cancelled is terminal: markRunning, markCompleted and markFailed cannot resurrect it', () => {
const { ledger } = setup();
const entry = ledger.accept(message('terminal')).entry;
ledger.markCancelled(entry.key);
ledger.markRunning(entry.key);
expect(ledger.get(entry.key)?.status).toBe('cancelled');
ledger.markCompleted(entry.key, 'late response');
expect(ledger.get(entry.key)?.status).toBe('cancelled');
ledger.markFailed(entry.key, new Error('late failure'));
expect(ledger.get(entry.key)?.status).toBe('cancelled');
});
});
describe('scheduled work recovery', () => {
it.each(['queued', 'running', 'paused', 'failed'] as const)('never replays %s scheduled work after restart', (state) => {
const { ledger, filePath } = setup();
const entry = ledger.accept(message('schedule', { scheduledTaskId: 'task-1', scheduledRunId: 'run-1' })).entry;
if (state === 'running') ledger.markRunning(entry.key);
if (state === 'paused') ledger.markPaused(entry.key, 'Side effects may be partial');
if (state === 'failed') ledger.markFailed(entry.key, 'interrupted/ambiguous');
const restarted = new WorkLedger({ filePath });
expect(restarted.recoverInterrupted()).toEqual([]);
expect(restarted.get(entry.key)).toMatchObject({ status: 'failed', error: expect.stringContaining('explicitly reschedule') });
expect(new WorkLedger({ filePath }).recoverInterrupted()).toEqual([]);
});
});