Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Subagent handler tests with a mocked Anthropic Messages client.
*
* Strategy: every test scripts a sequence of Messages API responses, hands
* them to a FakeMessagesClient, and inspects (a) the SubagentResult the
* handler returns and (b) the persisted rows in subagent_messages +
* subagent_tool_executions. Replay tests simulate a crash by constructing
* a fresh handler bound to the same job row with partial state already
* written.
*
* PGLite in-memory so the schema, ON CONFLICT, and two-phase persistence
* all exercise real SQL.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../src/core/pglite-engine.ts';
import { MinionQueue } from '../src/core/minions/queue.ts';
import {
makeSubagentHandler,
RateLeaseUnavailableError,
stripProviderPrefix,
type MessagesClient,
} from '../src/core/minions/handlers/subagent.ts';
import type { ToolDef, MinionJobContext } from '../src/core/minions/types.ts';
import type Anthropic from '@anthropic-ai/sdk';
import { OperationError } from '../src/core/ops/contract.ts';
import { __setMaintenanceWriteWaitForTests } from '../src/core/persistence/maintenance-wait.ts';
let engine: PGLiteEngine;
let queue: MinionQueue;
beforeAll(async () => {
engine = new PGLiteEngine();
await engine.connect({ database_url: '' });
await engine.initSchema();
queue = new MinionQueue(engine);
}, 60_000);
afterAll(async () => {
await engine.disconnect();
});
beforeEach(async () => {
await engine.executeRaw('DELETE FROM subagent_tool_executions');
await engine.executeRaw('DELETE FROM subagent_messages');
await engine.executeRaw('DELETE FROM subagent_rate_leases');
await engine.executeRaw('DELETE FROM minion_jobs');
});
// ── FakeMessagesClient ──────────────────────────────────────
type FakeResponse = Partial<Anthropic.Message> & { content: Anthropic.Message['content'] };
class FakeMessagesClient implements MessagesClient {
public calls: Anthropic.MessageCreateParamsNonStreaming[] = [];
constructor(private responses: FakeResponse[]) {}
async create(
params: Anthropic.MessageCreateParamsNonStreaming,
): Promise<Anthropic.Message> {
this.calls.push(params);
if (this.responses.length === 0) throw new Error('FakeMessagesClient: out of scripted responses');
const r = this.responses.shift()!;
return {
id: `msg_${this.calls.length}`,
type: 'message',
role: 'assistant',
model: params.model,
stop_reason: 'end_turn',
stop_sequence: null,
usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 } as any,
...r,
} as Anthropic.Message;
}
}
// Build a synthetic MinionJobContext around a real minion_jobs row. The
// handler only reads data/id/signal/shutdownSignal/updateTokens — we stub
// the rest. `subagent` is a protected job name (Lane 4H) so tests submit
// under the trusted-submit flag.
async function makeCtx(input: unknown): Promise<MinionJobContext> {
const job = await queue.add(
'subagent',
input as Record<string, unknown>,
{},
{ allowProtectedSubmit: true },
);
const ac = new AbortController();
const shutdown = new AbortController();
return {
id: job.id,
name: job.name,
data: (input as Record<string, unknown>) ?? {},
attempts_made: 0,
idempotency_key: null,
signal: ac.signal,
deadlineAtMs: null,
shutdownSignal: shutdown.signal,
async updateProgress() {},
async updateTokens() {},
async log() {},
async isActive() { return true; },
async readInbox() { return []; },
};
}
// ── Tiny tool registry for tests ────────────────────────────
function makeEchoTool(name = 'echo', idempotent = true): ToolDef {
return {
name,
description: 'echo input',
input_schema: { type: 'object', properties: { value: { type: 'string' } }, required: [] },
idempotent,
async execute(input) { return { echoed: input }; },
};
}
function makeThrowingTool(name = 'broken'): ToolDef {
return {
name,
description: 'always throws',
input_schema: { type: 'object', properties: {}, required: [] },
idempotent: true,
async execute() { throw new Error('tool broken'); },
};
}
// ── Tests ───────────────────────────────────────────────────
describe('subagent handler happy path', () => {
test('an explicit empty binding exposes no tools to the agent loop', async () => {
const client = new FakeMessagesClient([{ content: [{ type: 'text', text: 'done' }] as any }]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [makeEchoTool('echo')] });
await handler(await makeCtx({ prompt: 'finish', allowed_tools: [] }));
expect(client.calls[0]!.tools ?? []).toEqual([]);
});
test('malformed bindings fail before a model request', async () => {
for (const allowed_tools of [null, 'echo', [42], ['']]) {
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [makeEchoTool('echo')] });
await expect(handler(await makeCtx({ prompt: 'finish', allowed_tools }))).rejects.toThrow(/allowed_tools/);
expect(client.calls).toHaveLength(0);
}
});
test('no-tool end_turn: returns text response + persists user + assistant rows', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'hello world' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
const result = await handler(ctx);
expect(result.result).toBe('hello world');
expect(result.turns_count).toBe(1);
expect(result.stop_reason).toBe('end_turn');
expect(result.tokens.in).toBe(10);
expect(result.tokens.out).toBe(5);
const msgs = await engine.executeRaw<{ count: string }>(
`SELECT count(*)::text AS count FROM subagent_messages WHERE job_id = $1`,
[ctx.id],
);
expect(parseInt(msgs[0]!.count, 10)).toBe(2); // user seed + assistant
});
test('single tool_use turn: tool executes, two-phase row goes complete', async () => {
const tool = makeEchoTool();
const client = new FakeMessagesClient([
{
content: [
{ type: 'tool_use', id: 'tu_1', name: 'echo', input: { value: 'v1' } } as any,
],
stop_reason: 'tool_use' as any,
},
{
content: [{ type: 'text', text: 'done' }] as any,
stop_reason: 'end_turn',
},
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [tool] });
const ctx = await makeCtx({ prompt: 'go' });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.result).toBe('done');
expect(client.calls.length).toBe(2);
// tool_executions row complete with echoed output
const rows = await engine.executeRaw<{ status: string; output: unknown }>(
`SELECT status, output FROM subagent_tool_executions WHERE job_id = $1`,
[ctx.id],
);
expect(rows.length).toBe(1);
expect(rows[0]!.status).toBe('complete');
const out = typeof rows[0]!.output === 'string' ? JSON.parse(rows[0]!.output as string) : rows[0]!.output;
expect(out).toEqual({ echoed: { value: 'v1' } });
});
test('tool throws: row goes failed, model sees error, loop continues', async () => {
const tool = makeThrowingTool();
const client = new FakeMessagesClient([
{
content: [{ type: 'tool_use', id: 'tu_1', name: 'broken', input: {} } as any],
stop_reason: 'tool_use' as any,
},
{
content: [{ type: 'text', text: 'recovered' }] as any,
stop_reason: 'end_turn',
},
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [tool] });
const ctx = await makeCtx({ prompt: 'try' });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.result).toBe('recovered');
const rows = await engine.executeRaw<{ status: string; error: string | null }>(
`SELECT status, error FROM subagent_tool_executions WHERE job_id = $1`,
[ctx.id],
);
expect(rows[0]!.status).toBe('failed');
expect(rows[0]!.error).toContain('tool broken');
});
test('unknown tool name fails execution but loop continues', async () => {
const client = new FakeMessagesClient([
{
content: [{ type: 'tool_use', id: 'tu_nope', name: 'no_such_tool', input: {} } as any],
stop_reason: 'tool_use' as any,
},
{ content: [{ type: 'text', text: 'ok' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'x' });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
const rows = await engine.executeRaw<{ status: string; error: string | null }>(
`SELECT status, error FROM subagent_tool_executions WHERE job_id = $1`,
[ctx.id],
);
expect(rows[0]!.status).toBe('failed');
expect(rows[0]!.error).toContain('not in the registry');
});
test('max_turns exceeded returns stop_reason=max_turns', async () => {
// Model keeps calling tool_use forever; we cap at 2 turns.
const echoing: FakeResponse[] = Array.from({ length: 5 }).map((_, i) => ({
content: [{ type: 'tool_use', id: `tu_${i}`, name: 'echo', input: {} } as any],
stop_reason: 'tool_use' as any,
}));
const client = new FakeMessagesClient(echoing);
const tool = makeEchoTool();
const handler = makeSubagentHandler({ engine, client, toolRegistry: [tool] });
const ctx = await makeCtx({ prompt: 'loop', max_turns: 2 });
const result = await handler(ctx);
expect(result.stop_reason).toBe('max_turns');
expect(result.turns_count).toBe(2);
});
});
describe('subagent handler replay (crash recovery)', () => {
test('resumes from persisted messages when prior rows exist', async () => {
// Seed an in-progress conversation by running the first client, then
// running a second handler on the SAME job with responses starting at
// turn 2. No duplicate user-seed row (ON CONFLICT DO NOTHING).
const tool = makeEchoTool();
const client1 = new FakeMessagesClient([
{
content: [{ type: 'tool_use', id: 'tu_1', name: 'echo', input: { v: 1 } } as any],
stop_reason: 'tool_use' as any,
},
]);
const handler1 = makeSubagentHandler({ engine, client: client1, toolRegistry: [tool] });
const ctx = await makeCtx({ prompt: 'start' });
// Run handler1 until it WOULD make a second LLM call — force that
// second call to error so we persist only the first assistant message.
try {
const client1b = new FakeMessagesClient([
{
content: [{ type: 'tool_use', id: 'tu_1', name: 'echo', input: { v: 1 } } as any],
stop_reason: 'tool_use' as any,
},
]);
const interrupted = makeSubagentHandler({ engine, client: client1b, toolRegistry: [tool] });
await interrupted(ctx);
} catch {
// Out-of-scripted-responses — simulates worker kill before turn 2.
}
// Confirm partial state: 1 user + 1 assistant + 1 synthesized user
// (tool_result) + 1 tool_exec complete.
const preRows = await engine.executeRaw<{ c: string }>(
`SELECT count(*)::text AS c FROM subagent_messages WHERE job_id = $1`,
[ctx.id],
);
const preCount = parseInt(preRows[0]!.c, 10);
expect(preCount).toBeGreaterThanOrEqual(1);
// Resume with a fresh handler + client that supplies ONE more response.
const client2 = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'resumed ok' }] as any, stop_reason: 'end_turn' },
]);
const handler2 = makeSubagentHandler({ engine, client: client2, toolRegistry: [tool] });
const result = await handler2(ctx);
expect(result.result).toBe('resumed ok');
expect(result.stop_reason).toBe('end_turn');
// Second client should see the prior conversation in the messages
// array — at minimum the user seed + prior assistant + tool_result.
expect(client2.calls[0]!.messages.length).toBeGreaterThan(1);
});
test('prior completed tool exec is replayed without re-invoking execute', async () => {
// Prior state: a completed tool row. We assert the tool's execute is
// NOT called on resume. Use a tool that throws if invoked — passing
// means we used the replay path.
const throwingTool = makeThrowingTool('pre_done');
const ctx = await makeCtx({ prompt: 'start' });
// Seed prior state manually: user, assistant with tool_use, tool_exec complete.
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', $2::jsonb)`,
[ctx.id, JSON.stringify([{ type: 'text', text: 'start' }])],
);
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks, model)
VALUES ($1, 1, 'assistant', $2::jsonb, 'claude-sonnet-4-6')`,
[
ctx.id,
JSON.stringify([
{ type: 'tool_use', id: 'tu_seeded', name: 'pre_done', input: {} },
]),
],
);
await engine.executeRaw(
`INSERT INTO subagent_tool_executions (job_id, message_idx, tool_use_id, tool_name, input, status, output)
VALUES ($1, 1, 'tu_seeded', 'pre_done', '{}'::jsonb, 'complete', $2::jsonb)`,
[ctx.id, JSON.stringify({ replayed: true })],
);
// Handler MUST NOT call the throwing execute and MUST end the loop on
// the next LLM response.
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'finished after replay' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [throwingTool] });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.result).toBe('finished after replay');
// Only one LLM call made on this resume (we had 2 persisted messages +
// the tool result synthesis happened when resuming, then model spoke).
expect(client.calls.length).toBe(1);
});
// v0.37.7.0 #1151 regression — terminal-on-resume.
// Pre-fix, this scenario dead-lettered the job: replay reconciler saw
// last=assistant with zero tool_uses, did nothing, main loop called
// messages.create against a conversation ending in assistant → Sonnet
// 4.6+ rejects assistant-prefill with HTTP 400 → 3 retries → dead.
// Post-fix, the reconciler short-circuits: reconstructs finalText from
// the persisted text blocks and returns stop_reason='end_turn' without
// any LLM call.
test('text-only assistant tail on resume returns terminal without LLM call (#1151)', async () => {
const ctx = await makeCtx({ prompt: 'start' });
// Seed prior state: user prompt, then a TERMINAL assistant turn
// (text-only, no tool_use blocks). This is the exact shape the
// #1151 reporter found in their dead jobs (job 190's last message
// was a synthesis summary listing 3 written slugs).
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', $2::jsonb)`,
[ctx.id, JSON.stringify([{ type: 'text', text: 'start' }])],
);
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks, model, tokens_in, tokens_out)
VALUES ($1, 1, 'assistant', $2::jsonb, 'claude-sonnet-4-6', 100, 50)`,
[
ctx.id,
JSON.stringify([
{ type: 'text', text: 'wrote 3 pages: wiki/notes/a, wiki/notes/b, wiki/notes/c' },
]),
],
);
// The FakeMessagesClient has ZERO scripted responses. If the handler
// tries to call messages.create, it throws. The fix guarantees we
// never reach that path.
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.result).toBe('wrote 3 pages: wiki/notes/a, wiki/notes/b, wiki/notes/c');
// Crucial assertion: no messages.create call was made on resume.
expect(client.calls.length).toBe(0);
// Token totals from the persisted assistant message rolled up.
expect(result.tokens.in).toBe(100);
expect(result.tokens.out).toBe(50);
});
// Companion: the existing tool-use replay path is unchanged.
test('text-only terminal short-circuit does NOT affect tool-use replay path', async () => {
// This is a smoke test that the new else-branch doesn't accidentally
// swallow the pending-tool-use case. If we have a persisted assistant
// with a tool_use block (no synthesized user turn yet), the existing
// tool-synthesis path must still fire.
const echoTool = makeEchoTool('echo_x');
const ctx = await makeCtx({ prompt: 'start' });
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', $2::jsonb)`,
[ctx.id, JSON.stringify([{ type: 'text', text: 'start' }])],
);
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks, model)
VALUES ($1, 1, 'assistant', $2::jsonb, 'claude-sonnet-4-6')`,
[
ctx.id,
JSON.stringify([
{ type: 'tool_use', id: 'tu_pending', name: 'echo_x', input: { v: 'r' } },
]),
],
);
// No prior tool_exec row — replay reconciler will dispatch.
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'done after tool' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [echoTool] });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.result).toBe('done after tool');
// The handler DID call messages.create (one call) after synthesizing
// the tool_result wrapper.
expect(client.calls.length).toBe(1);
});
test('pending non-idempotent tool exec rejects on resume', async () => {
const nonIdempotent = { ...makeEchoTool('do_once'), idempotent: false };
const ctx = await makeCtx({ prompt: 'start' });
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', $2::jsonb)`,
[ctx.id, JSON.stringify([{ type: 'text', text: 'start' }])],
);
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 1, 'assistant', $2::jsonb)`,
[
ctx.id,
JSON.stringify([{ type: 'tool_use', id: 'tu_x', name: 'do_once', input: {} }]),
],
);
await engine.executeRaw(
`INSERT INTO subagent_tool_executions (job_id, message_idx, tool_use_id, tool_name, input, status)
VALUES ($1, 1, 'tu_x', 'do_once', '{}'::jsonb, 'pending')`,
[ctx.id],
);
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [nonIdempotent] });
await expect(handler(ctx)).rejects.toThrow(/non-idempotent/);
});
});
describe('subagent handler lease behavior', () => {
test('acquires + releases a lease around the LLM call', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'ok' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({
engine, client, toolRegistry: [], maxConcurrent: 1, rateLeaseKey: 'k1',
});
const ctx = await makeCtx({ prompt: 'hi' });
await handler(ctx);
// No leases should remain after completion.
const rows = await engine.executeRaw<{ c: string }>(
`SELECT count(*)::text AS c FROM subagent_rate_leases`,
);
expect(parseInt(rows[0]!.c, 10)).toBe(0);
});
test('v0.41 Bug 3: stripProviderPrefix strips `anthropic:` qualified model', async () => {
expect(stripProviderPrefix('anthropic:claude-sonnet-4-6')).toBe('claude-sonnet-4-6');
});
test('v0.41 Bug 3: stripProviderPrefix is idempotent on bare names', async () => {
expect(stripProviderPrefix('claude-sonnet-4-6')).toBe('claude-sonnet-4-6');
});
test('v0.41 Bug 3: stripProviderPrefix handles edge inputs', async () => {
expect(stripProviderPrefix('')).toBe('');
// Leading colon = no valid provider name; pass through unchanged.
// The `idx > 0` guard (not `>= 0`) makes this intentional.
expect(stripProviderPrefix(':')).toBe(':');
expect(stripProviderPrefix('a:b:c')).toBe('b:c'); // only strips first prefix
});
test('v0.41 Bug 3: handler passes bare model id to Anthropic SDK when data.model is qualified', async () => {
const calls: Array<Anthropic.MessageCreateParamsNonStreaming> = [];
const client: MessagesClient = {
async create(params) {
calls.push(params);
return {
content: [{ type: 'text', text: 'ok' }],
stop_reason: 'end_turn',
usage: { input_tokens: 1, output_tokens: 1 },
role: 'assistant',
} as unknown as Anthropic.Message;
},
};
const handler = makeSubagentHandler({
engine, client, toolRegistry: [], maxConcurrent: 100, rateLeaseKey: 'k_prefix',
});
const ctx = await makeCtx({
prompt: 'hello',
model: 'anthropic:claude-sonnet-4-6', // qualified — the field-report bug case
});
await handler(ctx);
expect(calls.length).toBe(1);
// The SDK MUST receive the bare model id, not the prefixed one.
expect(calls[0]!.model).toBe('claude-sonnet-4-6');
});
test('throws RateLeaseUnavailableError when cap full', async () => {
// Preload the cap with a stale-looking-but-live lease owned by a
// different job.
const owner = await queue.add('holder', {});
await engine.executeRaw(
`INSERT INTO subagent_rate_leases (key, owner_job_id, expires_at)
VALUES ('k_cap', $1, now() + interval '1 minute')`,
[owner.id],
);
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({
engine, client, toolRegistry: [], maxConcurrent: 1, rateLeaseKey: 'k_cap',
});
const ctx = await makeCtx({ prompt: 'blocked' });
await expect(handler(ctx)).rejects.toBeInstanceOf(RateLeaseUnavailableError);
});
});
describe('subagent handler input validation', () => {
test('missing prompt throws', async () => {
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({});
await expect(handler(ctx)).rejects.toThrow(/prompt/);
});
test('allowed_tools unknown name rejected at dispatch', async () => {
const tool = makeEchoTool('real');
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [tool] });
const ctx = await makeCtx({ prompt: 'x', allowed_tools: ['real', 'ghost_tool'] });
await expect(handler(ctx)).rejects.toThrow(/unknown tool/);
});
});
describe('makeSubagentHandler default client construction', () => {
test('factory default wires sdk.messages through to the handler', async () => {
// Regression guard for the v0.16.0 shipped bug: makeSubagentHandler
// was casting `new Anthropic()` (top-level SDK class) to MessagesClient,
// but `.create()` lives at sdk.messages.create. Every subagent job in
// production died with "client.create is not a function" on first LLM
// call. This test exercises the default-client path (no `deps.client`
// injected) via the makeAnthropic dep-injection seam, so the exact
// default-branch construction is covered without a real API call.
const calls: Anthropic.MessageCreateParamsNonStreaming[] = [];
const fakeSdk = {
messages: {
async create(
params: Anthropic.MessageCreateParamsNonStreaming,
): Promise<Anthropic.Message> {
calls.push(params);
return {
id: 'msg_regression',
type: 'message',
role: 'assistant',
model: params.model,
stop_reason: 'end_turn',
stop_sequence: null,
content: [{ type: 'text', text: 'ok' }],
usage: {
input_tokens: 1,
output_tokens: 1,
cache_read_input_tokens: 0,
cache_creation_input_tokens: 0,
},
} as unknown as Anthropic.Message;
},
},
} as unknown as Anthropic;
// Crucial: do NOT pass `client`. Only `makeAnthropic`. This forces the
// factory to hit the default-client branch (`deps.client ?? makeAnthropic().messages`).
const handler = makeSubagentHandler({
engine,
makeAnthropic: () => fakeSdk,
toolRegistry: [],
});
const ctx = await makeCtx({ prompt: 'hello' });
const result = await handler(ctx);
expect(calls.length).toBe(1);
expect(result.stop_reason).toBe('end_turn');
expect(result.result).toBe('ok');
});
});
// ── #2778: per-turn output-token cap + max_tokens stop handling ─────
import { resolveMaxOutputTokens } from '../src/core/minions/handlers/subagent.ts';
describe('resolveMaxOutputTokens (#2778)', () => {
test('defaults to 8192 when nothing set', () => {
expect(resolveMaxOutputTokens(undefined, null)).toBe(8192);
expect(resolveMaxOutputTokens(undefined, undefined)).toBe(8192);
});
test('per-job value wins over config', () => {
expect(resolveMaxOutputTokens(2048, '5000')).toBe(2048);
});
test('config value used when per-job unset', () => {
expect(resolveMaxOutputTokens(undefined, '5000')).toBe(5000);
});
test('invalid values fall through to next tier', () => {
expect(resolveMaxOutputTokens(0, '5000')).toBe(5000);
expect(resolveMaxOutputTokens(-1, null)).toBe(8192);
expect(resolveMaxOutputTokens(Number.NaN, 'garbage')).toBe(8192);
expect(resolveMaxOutputTokens(undefined, '')).toBe(8192);
expect(resolveMaxOutputTokens(undefined, '0')).toBe(8192);
});
});
describe('subagent handler output-token cap (#2778)', () => {
test('default: SDK call carries max_tokens=8192 (was hardcoded 4096)', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'ok' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
await handler(ctx);
expect(client.calls[0]!.max_tokens).toBe(8192);
});
test('data.max_tokens flows to the SDK call', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'ok' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi', max_tokens: 2048 });
await handler(ctx);
expect(client.calls[0]!.max_tokens).toBe(2048);
});
test('agent.max_output_tokens config flows to the SDK call', async () => {
await engine.setConfig('agent.max_output_tokens', '5000');
try {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'ok' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
await handler(ctx);
expect(client.calls[0]!.max_tokens).toBe(5000);
} finally {
await engine.executeRaw(`DELETE FROM config WHERE key = 'agent.max_output_tokens'`);
}
});
test('final turn hitting the cap surfaces stop_reason=max_tokens, not a silent end_turn', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'truncated tex' }] as any, stop_reason: 'max_tokens' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
const result = await handler(ctx);
expect(result.stop_reason).toBe('max_tokens');
expect(result.result).toBe('truncated tex');
});
test('max_tokens stop with tool_use: truncation note injected so the model re-issues the dropped call', async () => {
const tool = makeEchoTool();
const client = new FakeMessagesClient([
{
// A complete tool_use survived, but the turn stopped on max_tokens —
// the API dropped whatever came after (e.g. a big put_page call).
content: [{ type: 'tool_use', id: 'tu_1', name: 'echo', input: { value: 'v1' } } as any],
stop_reason: 'max_tokens' as any,
},
{ content: [{ type: 'text', text: 'recovered' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [tool] });
const ctx = await makeCtx({ prompt: 'go' });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.result).toBe('recovered');
// The synthesized user turn (persisted + fed to the second call) must
// carry the truncation note alongside the tool_result. Assert on the
// persisted row — client.calls[].messages is the live array the loop
// keeps mutating, so positional checks there are unreliable.
const rows = await engine.executeRaw<{ content_blocks: unknown }>(
`SELECT content_blocks FROM subagent_messages
WHERE job_id = $1 AND role = 'user' AND message_idx > 0
ORDER BY message_idx ASC`,
[ctx.id],
);
expect(rows.length).toBe(1);
const blocks = (typeof rows[0]!.content_blocks === 'string'
? JSON.parse(rows[0]!.content_blocks as string)
: rows[0]!.content_blocks) as Array<{ type: string; text?: string }>;
expect(blocks.some(b => b.type === 'tool_result')).toBe(true);
const texts = blocks.filter(b => b.type === 'text').map(b => b.text ?? '');
expect(texts.some(t => t.includes('truncated') && t.includes('DROPPED'))).toBe(true);
});
});
describe('handler-entry capability gate on the config-resolved model', () => {
test('config-resolved models.subagent lacking tool calling is refused at dispatch', async () => {
// The queue submit gate only sees explicit data.model. A job that omits
// data.model resolves `models.subagent` inside the handler — pre-fix that
// path bypassed the capability check entirely and a tool-incapable model
// (declared supports_tools: false) ran the loop anyway. Fixture is the
// nvidia recipe: it still declares supports_tools: false (minimax flipped
// to true in #4782, so it no longer exercises the no_tools path).
await engine.setConfig('models.subagent', 'nvidia:nvidia/nemotron-3-super-120b-a12b');
try {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'should never run' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' }); // no data.model → queue gate passes
await expect(handler(ctx)).rejects.toThrow(/lacks native tool calling/);
expect(client.calls.length).toBe(0); // refused before any provider call
} finally {
await engine.unsetConfig('models.subagent');
}
});
test('already-terminal replay is NOT refused when config points at a tool-incapable model', async () => {
// #1151 precedent: a job whose last persisted message is a terminal
// assistant turn needs no provider call — the replay short-circuit
// returns the committed result. A capability refusal here (config
// repointed between submit and replay) would dead-letter completed work.
// Gateway loop ON: that's the only routing where the capability gate is
// the deciding check (the legacy path's Anthropic pin refuses
// non-Anthropic models regardless). The gateway path's terminal
// early-return runs before any provider client is constructed, so no
// API key is needed.
await engine.setConfig('models.subagent', 'nvidia:nvidia/nemotron-3-super-120b-a12b');
await engine.setConfig('agent.use_gateway_loop', 'true');
try {
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
// Persist a completed transcript: seed user + terminal assistant.
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', $2::text::jsonb), ($1, 1, 'assistant', $3::text::jsonb)`,
[
ctx.id,
JSON.stringify([{ type: 'text', text: 'hi' }]),
JSON.stringify([{ type: 'text', text: 'committed answer' }]),
],
);
const result = await handler(ctx);
expect(result.result).toBe('committed answer');
// Replay short-circuit: no new turns persisted beyond the 2 seeded rows
// (a provider call would have appended an assistant row — and would have
// failed anyway, since no gateway credentials are configured here).
const rows = await engine.executeRaw<{ count: string }>(
`SELECT count(*)::text AS count FROM subagent_messages WHERE job_id = $1`,
[ctx.id],
);
expect(parseInt(rows[0]!.count, 10)).toBe(2);
} finally {
await engine.unsetConfig('models.subagent');
await engine.unsetConfig('agent.use_gateway_loop');
}
});
test('non-terminal gateway replay (pending tool-call) IS still refused on a tool-incapable model', async () => {
// A gateway transcript persists pending dispatch as `tool-call` blocks.
// A replay that still needs the loop to resume on the provider must NOT
// slip past the capability gate via the terminal exception.
await engine.setConfig('models.subagent', 'nvidia:nvidia/nemotron-3-super-120b-a12b');
await engine.setConfig('agent.use_gateway_loop', 'true');
try {
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', $2::text::jsonb), ($1, 1, 'assistant', $3::text::jsonb)`,
[
ctx.id,
JSON.stringify([{ type: 'text', text: 'hi' }]),
JSON.stringify([{ type: 'tool-call', toolCallId: 'tc_1', toolName: 'echo', input: {} }]),
],
);
await expect(handler(ctx)).rejects.toThrow(/lacks native tool calling/);
} finally {
await engine.unsetConfig('models.subagent');
await engine.unsetConfig('agent.use_gateway_loop');
}
});
test('a BARE Anthropic id in models.subagent still runs (not refused as unknown provider)', async () => {
// A bare `claude-*` id (no `provider:` prefix) is a supported config value
// everywhere else: isAnthropicProvider() has an explicit bare-`claude-`
// branch and the legacy path strips the prefix before calling the Messages
// API. classifyCapabilities() resolves through the recipe registry, which
// requires an explicit provider, so classifying the raw value would report
// `unknown` and this gate would refuse a config that works.
await engine.setConfig('models.subagent', 'claude-sonnet-4-6');
try {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'ran on the bare id' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' }); // no data.model → config resolves
const result = await handler(ctx);
expect(result.result).toBe('ran on the bare id');
// The provider call carries the bare id (the legacy path strips any prefix).
expect(client.calls.length).toBe(1);
expect(client.calls[0]!.model).toBe('claude-sonnet-4-6');
} finally {
await engine.unsetConfig('models.subagent');
}
});
test('a bare NON-Anthropic id in models.subagent is still refused', async () => {
// The normalization above is deliberately narrow: only bare ids that
// isAnthropicProvider() recognizes get an `anthropic:` prefix for the
// verdict. A bare `gpt-5` is not a recipe-resolvable model, so the gate
// must keep reporting `unknown` rather than classifying it as Anthropic.
await engine.setConfig('models.subagent', 'gpt-5');
try {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'should never run' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
await expect(handler(ctx)).rejects.toThrow(/references an unknown provider/);
expect(client.calls.length).toBe(0);
} finally {
await engine.unsetConfig('models.subagent');
}
});
});
// ── #4217 structural write accounting ───────────────────────
describe('write accounting (#4217)', () => {
test('gateway text-only completion fails required writes and replay spends no more tokens (#5098)', async () => {
const { configureGateway, resetGateway, __setChatTransportForTests } = await import('../src/core/ai/gateway.ts');
configureGateway({ env: {} });
let calls = 0;
__setChatTransportForTests(async () => {
calls++;
return {
model: 'openai:gpt-5.2', providerId: 'openai', text: 'brain_put_page({"slug":"notes/example"})',
blocks: [{ type: 'text', text: 'brain_put_page({"slug":"notes/example"})' }], stopReason: 'end',
usage: { input_tokens: 10, output_tokens: 5, cache_read_tokens: 0, cache_creation_tokens: 0 },
};
});
await engine.setConfig('agent.use_gateway_loop', 'true');
try {
const handler = makeSubagentHandler({ engine, client: new FakeMessagesClient([]), toolRegistry: [makePutPageTool('ok')] });
const ctx = await makeCtx({ prompt: 'write a page', model: 'openai:gpt-5.2', require_writes: true });
await expect(handler(ctx)).rejects.toThrow('zero required put_page writes');
await expect(handler(ctx)).rejects.toThrow('zero required put_page writes');
expect(calls).toBe(1);
expect(await engine.executeRaw('SELECT id FROM subagent_tool_executions WHERE job_id = $1', [ctx.id])).toEqual([]);
const readOnly = await handler({ ...ctx, data: { ...ctx.data, require_writes: false } });
expect(readOnly.stop_reason).toBe('end_turn');
expect(readOnly.pages_written).toBe(0);
expect(calls).toBe(1);
} finally {
__setChatTransportForTests(null);
resetGateway();
await engine.unsetConfig('agent.use_gateway_loop');
}
});
function makePutPageTool(behavior: 'ok' | 'fail' | ((input: unknown) => 'ok' | 'fail')): ToolDef {
return {
name: 'brain_put_page',
description: 'write a page',
input_schema: { type: 'object', properties: { slug: { type: 'string' } }, required: [] },
idempotent: true,
async execute(input) {
const mode = typeof behavior === 'function' ? behavior(input) : behavior;
if (mode === 'fail') throw new Error('expected 1024 dimensions, not 1280');
return { slug: (input as { slug?: string }).slug ?? 'wiki/x', status: 'created' };
},
};
}
const putPageTurn = (slug: string, id: string) => ({
content: [{ type: 'tool_use', id, name: 'brain_put_page', input: { slug } }] as any,
stop_reason: 'tool_use' as const,
});
const endTurn = { content: [{ type: 'text', text: 'done' }] as any, stop_reason: 'end_turn' as const };
test('require_writes + ALL writes failed → UnrecoverableError with first error', async () => {
const client = new FakeMessagesClient([putPageTurn('wiki/a', 'tu_1'), endTurn]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [makePutPageTool('fail')] });
const ctx = await makeCtx({ prompt: 'write pages', require_writes: true });
await expect(handler(ctx)).rejects.toThrow(/all 1 put_page write\(s\) failed.*1024 dimensions/);
});
test('all writes failed WITHOUT require_writes → completed, truthful counts', async () => {
// CDX-12: open-ended agent runs keep the generic contract — a failed write
// plus a useful text answer is still a completion, but the counts tell the truth.
const client = new FakeMessagesClient([putPageTurn('wiki/a', 'tu_1'), endTurn]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [makePutPageTool('fail')] });
const ctx = await makeCtx({ prompt: 'write pages' });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.pages_attempted).toBe(1);
expect(result.pages_written).toBe(0);
expect(result.pages_failed).toBe(1);
});
test('partial failure with require_writes → completed with counts', async () => {
const client = new FakeMessagesClient([
{
content: [
{ type: 'tool_use', id: 'tu_ok', name: 'brain_put_page', input: { slug: 'wiki/ok' } },
{ type: 'tool_use', id: 'tu_bad', name: 'brain_put_page', input: { slug: 'FAIL' } },
] as any,
stop_reason: 'tool_use',
},
endTurn,
]);
const tool = makePutPageTool((input) => ((input as { slug?: string }).slug === 'FAIL' ? 'fail' : 'ok'));
const handler = makeSubagentHandler({ engine, client, toolRegistry: [tool] });
const ctx = await makeCtx({ prompt: 'write pages', require_writes: true });
const result = await handler(ctx);
expect(result.pages_attempted).toBe(2);
expect(result.pages_written).toBe(1);
expect(result.pages_failed).toBe(1);
});
test('zero attempts cannot satisfy require_writes even when the model claims a skip', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'nothing met the bar' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [makePutPageTool('ok')] });
const ctx = await makeCtx({ prompt: 'write pages', require_writes: true });
await expect(handler(ctx)).rejects.toThrow('zero required put_page writes');
await expect(handler(ctx)).rejects.toThrow('zero required put_page writes');
expect(client.calls).toHaveLength(1);
const result = await handler({ ...ctx, data: { ...ctx.data, require_writes: false } });
expect(result.result).toBe('nothing met the bar');
expect(result.pages_attempted).toBe(0);
expect(result.pages_written).toBe(0);
expect(result.pages_failed).toBe(0);
});
test('allow_clean_zero_writes: a clean finish after a completed read completes; without it the job dead-letters (#5540)', async () => {
const searchTurn = {
content: [{ type: 'tool_use', id: 'tu_s', name: 'brain_search', input: { value: 'themes' } }] as any,
stop_reason: 'tool_use' as const,
};
const strict = makeSubagentHandler({
engine, client: new FakeMessagesClient([searchTurn, endTurn]),
toolRegistry: [makeEchoTool('brain_search'), makePutPageTool('ok')],
});
const strictCtx = await makeCtx({ prompt: 'find patterns', require_writes: true });
await expect(strict(strictCtx)).rejects.toThrow('zero required put_page writes');
const handler = makeSubagentHandler({
engine, client: new FakeMessagesClient([searchTurn, endTurn]),
toolRegistry: [makeEchoTool('brain_search'), makePutPageTool('ok')],
});
const ctx = await makeCtx({ prompt: 'find patterns', require_writes: true, allow_clean_zero_writes: true });
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.pages_attempted).toBe(0);
expect(result.pages_written).toBe(0);
});
test('allow_clean_zero_writes does not excuse a run whose only tool failed (#5540)', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'tool_use', id: 'tu_b2', name: 'broken', input: {} }] as any, stop_reason: 'tool_use' },
endTurn,
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [makeThrowingTool('broken')] });
const ctx = await makeCtx({ prompt: 'find patterns', require_writes: true, allow_clean_zero_writes: true });
await expect(handler(ctx)).rejects.toThrow('zero required put_page writes');
});
test('non-put_page tool failures do not count toward write accounting', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'tool_use', id: 'tu_b', name: 'broken', input: {} }] as any, stop_reason: 'tool_use' },
endTurn,
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [makeThrowingTool('broken')] });
const ctx = await makeCtx({ prompt: 'do stuff', require_writes: true });
await expect(handler(ctx)).rejects.toThrow('zero required put_page writes');
const result = await handler({ ...ctx, data: { ...ctx.data, require_writes: false } });
expect(result.pages_attempted).toBe(0);
});
});
// ── #4087/CDX-6 model-aware output-cap default ──────────────
describe('resolveMaxOutputTokens model-aware default', () => {
const { resolveMaxOutputTokens } = require('../src/core/minions/handlers/subagent.ts');
test('thinking-by-default Claude 5 model gets 32000 when nothing is configured', () => {
expect(resolveMaxOutputTokens(undefined, null, 'openrouter:anthropic/claude-sonnet-5')).toBe(32000);
expect(resolveMaxOutputTokens(undefined, null, 'anthropic:claude-fable-5')).toBe(32000);
});
test('recipe-declared thinking models (DeepSeek v4) get 32000 too (#4172)', () => {
expect(resolveMaxOutputTokens(undefined, null, 'deepseek:deepseek-v4-flash')).toBe(32000);
});
test('non-thinking models keep 8192', () => {
expect(resolveMaxOutputTokens(undefined, null, 'anthropic:claude-sonnet-4-6')).toBe(8192);
expect(resolveMaxOutputTokens(undefined, null, 'anthropic:claude-3-5-sonnet-20241022')).toBe(8192);
expect(resolveMaxOutputTokens(undefined, null, undefined)).toBe(8192);
});
test('per-job and config overrides still win over the thinking default', () => {
expect(resolveMaxOutputTokens(12000, null, 'anthropic:claude-fable-5')).toBe(12000);
expect(resolveMaxOutputTokens(undefined, '9000', 'anthropic:claude-fable-5')).toBe(9000);
});
});
// ── #4216 oneshot mode dispatch ─────────────────────────────
describe('oneshot mode dispatch (#4216)', () => {
const PREFIXES = ['wiki/personal/reflections/*', 'wiki/originals/*'];
const SUFFIX = 'abc123';
const SLUG_A = `wiki/personal/reflections/2026-08-16-topic-${SUFFIX}`;
const SLUG_B = `wiki/originals/ideas/2026-08-16-idea-${SUFFIX}`;
const VALID = JSON.stringify({
pages: [
{ slug: SLUG_A, body: `A. [[${SLUG_B}]]` },
{ slug: SLUG_B, body: `B. [[${SLUG_A}]]` },
],
skipped: false,
});
const chatStub = (text: string) => (async () => ({
text,
blocks: [{ type: 'text' as const, text }],
stopReason: 'end' as const,
usage: { input_tokens: 10, output_tokens: 10, cache_read_tokens: 0, cache_creation_tokens: 0 },
model: 'anthropic:claude-sonnet-4-6',
providerId: 'anthropic',
})) as any;
test('valid oneshot output: single call, pages written, synth_mode_used=oneshot, accounting scoped', async () => {
const client = new FakeMessagesClient([]); // legacy loop must never run
const handler = makeSubagentHandler({ engine, client, _chat: chatStub(VALID) });
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot', require_writes: true,
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: SUFFIX,
});
const result = await handler(ctx);
expect(result.synth_mode_used).toBe('oneshot');
expect(result.turns_count).toBe(1);
expect(result.pages_written).toBe(2);
expect(result.pages_failed).toBe(0);
expect(client.calls.length).toBe(0);
expect(await engine.getPage(SLUG_A)).not.toBeNull();
});
test('explicit oneshot skip under require_writes completes instead of dead-lettering (#5590)', async () => {
const client = new FakeMessagesClient([]);
const skip = JSON.stringify({ pages: [], skipped: true, skip_reason: 'verbatim paste of an existing page' });
const handler = makeSubagentHandler({ engine, client, _chat: chatStub(skip) });
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot', require_writes: true,
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: SUFFIX,
});
const result = await handler(ctx);
expect(result.synth_mode_used).toBe('oneshot');
expect(result.oneshot_skipped).toBe(true);
expect(result.pages_attempted).toBe(0);
expect(result.pages_written).toBe(0);
expect(client.calls.length).toBe(0);
});
test('a oneshot skip replayed after its transcript persisted still completes without another model call (#5590)', async () => {
const client = new FakeMessagesClient([]);
const skip = JSON.stringify({ pages: [], skipped: true, skip_reason: 'already captured' });
const handler = makeSubagentHandler({ engine, client, _chat: chatStub(skip) });
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot', require_writes: true,
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: SUFFIX,
});
expect((await handler(ctx)).oneshot_skipped).toBe(true);
let chatCalls = 0;
const spy = (async (...args: any[]) => { chatCalls++; return chatStub(skip)(...args); }) as any;
const replay = await makeSubagentHandler({ engine, client, _chat: spy })({ ...ctx, attempts_made: 1 });
expect(replay.synth_mode_used).toBe('oneshot');
expect(replay.oneshot_skipped).toBe(true);
expect(replay.pages_attempted).toBe(0);
expect(chatCalls).toBe(0);
expect(client.calls.length).toBe(0);
});
test('an agentic-fallback transcript that merely looks like a skip still dead-letters on replay (#5590)', async () => {
const client = new FakeMessagesClient([]);
let chatCalls = 0;
const spy = (async (...args: any[]) => { chatCalls++; return chatStub('{}')(...args); }) as any;
const handler = makeSubagentHandler({ engine, client, _chat: spy });
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot', require_writes: true,
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: SUFFIX,
});
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', '[{"type":"text","text":"synthesize"}]'::jsonb),
($1, 1, 'assistant', $2::text::jsonb)`,
[ctx.id, JSON.stringify([{ type: 'text', text: JSON.stringify({ pages: [], skipped: true }) }])],
);
await expect(handler({ ...ctx, attempts_made: 1 })).rejects.toThrow('zero required put_page writes');
expect(chatCalls).toBe(0);
});
test('oneshot pages:[] without the skip flag still dead-letters when the fallback writes nothing (#5590)', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'nothing met the bar' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, _chat: chatStub(JSON.stringify({ pages: [], skipped: false })) });
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot', require_writes: true,
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: SUFFIX,
});
await expect(handler(ctx)).rejects.toThrow('zero required put_page writes');
});
test('invalid oneshot output falls back to the agentic loop IN THE SAME JOB', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'agentic loop answered' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, _chat: chatStub('not json at all') });
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot',
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: SUFFIX,
});
const result = await handler(ctx);
expect(result.result).toBe('agentic loop answered');
expect(result.synth_mode_used).toBe('agentic_fallback');
expect(result.fallback_reason).toBe('unparseable');
expect(client.calls.length).toBe(1); // the loop really ran
});
test('REGRESSION pin: payload without mode keeps the legacy result shape (no synth fields)', async () => {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'plain job' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, _chat: chatStub(VALID) });
const ctx = await makeCtx({ prompt: 'plain' });
const result = await handler(ctx);
expect(result.result).toBe('plain job');
expect('synth_mode_used' in result).toBe(false);
expect('fallback_reason' in result).toBe(false);
});
test('mode=agentic stamps synth_mode_used=agentic and never calls the oneshot chat', async () => {
let oneshotCalls = 0;
const spy = (async (...args: any[]) => { oneshotCalls++; return chatStub(VALID)(...args); }) as any;
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'agentic by request' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, _chat: spy });
const ctx = await makeCtx({ prompt: 'synthesize', mode: 'agentic' });
const result = await handler(ctx);
expect(result.synth_mode_used).toBe('agentic');
expect(oneshotCalls).toBe(0);
});
test.each([['echo'], []])('oneshot tool ceiling %j prevents programmatic write escalation', async (...allowedTools) => {
// A submitter that scoped its job to read-only tools must not gain
// brain_put_page by flipping mode: oneshot — the oneshot registry runs
// through the SAME filterAllowedTools as the loop registry.
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'read-only answer' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({
engine, client,
toolRegistry: [makeEchoTool(), makeEchoTool('brain_put_page')],
_chat: chatStub(VALID),
});
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot',
allowed_tools: allowedTools,
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: SUFFIX,
});
const result = await handler(ctx);
expect(result.synth_mode_used).toBe('agentic_fallback');
expect(result.fallback_reason).toBe('no_put_page_tool');
// No page write happened anywhere.
const rows = await engine.executeRaw<{ n: number }>(
`SELECT count(*)::int AS n FROM subagent_tool_executions WHERE job_id = $1 AND tool_name = 'brain_put_page'`,
[ctx.id],
);
expect(rows[0]!.n).toBe(0);
if (allowedTools.length === 0) expect(client.calls[0]!.tools ?? []).toEqual([]);
});
test('crash-replayed TRUNCATED terminal turn recovers max_tokens, not end_turn (F1)', async () => {
// A length-stopped zero-write run persisted its terminal turn, crashed
// before completeJob, and replays. Pre-fix the early-return hardcoded
// end_turn, laundering the truncation past the zero-attempt honesty
// gate — the job completed with zero pages and consumed the transcript.
const client = new FakeMessagesClient([]); // replay path must not call the model
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'synthesize', require_writes: true });
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks, tokens_out)
VALUES ($1, 0, 'user', '[{"type":"text","text":"synthesize"}]'::jsonb, NULL),
($1, 1, 'assistant', '[{"type":"text","text":"truncated partial outp"}]'::jsonb, 8192)`,
[ctx.id],
);
await expect(handler(ctx)).rejects.toThrow(/did not finish cleanly.*max_tokens/);
});
test('crash-replayed CLEAN terminal turn still returns end_turn', async () => {
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hello' });
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks, tokens_out)
VALUES ($1, 0, 'user', '[{"type":"text","text":"hello"}]'::jsonb, NULL),
($1, 1, 'assistant', '[{"type":"text","text":"a normal answer"}]'::jsonb, 42)`,
[ctx.id],
);
const result = await handler(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(result.result).toBe('a normal answer');
});
test('half-persisted transcript + oneshot ledger rows → recovery, NEVER an agentic re-call (RT-2)', async () => {
// Crash shape: all writes settled, then only the seed user message
// landed (the two transcript INSERTs are not atomic). Pre-fix, the
// messages>0 gate skipped oneshot entirely and the loop replay re-called
// a nondeterministic model with the pages already written.
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'should never run' }] as any, stop_reason: 'end_turn' },
]);
let oneshotChatCalls = 0;
const spy = (async (...args: any[]) => { oneshotChatCalls++; return chatStub(VALID)(...args); }) as any;
const handler = makeSubagentHandler({ engine, client, _chat: spy });
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot', require_writes: true,
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: SUFFIX,
});
// Seed: one message (no terminal assistant row) + a completed oneshot ledger row.
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', '[{"type":"text","text":"synthesize"}]'::jsonb)`,
[ctx.id],
);
await engine.executeRaw(
`INSERT INTO subagent_tool_executions (job_id, message_idx, tool_use_id, tool_name, input, status)
VALUES ($1, 1, 'oneshot-cafef00d-p0', 'brain_put_page', $2::text::jsonb, 'complete')`,
[ctx.id, JSON.stringify({ slug: SLUG_A, content: 'already written' })],
);
const result = await handler(ctx);
expect(result.synth_mode_used).toBe('oneshot');
expect((result as { recovered?: boolean }).recovered).toBe(true);
expect(oneshotChatCalls).toBe(0); // ledger-first: model never re-called
expect(client.calls.length).toBe(0); // agentic loop never ran
});
test('replayed completed oneshot job is NOT stamped agentic_fallback (honesty rule)', async () => {
// First invocation completes via oneshot (persists the 2-message terminal
// transcript). A second invocation of the SAME job (outcome write lost,
// stall requeue) replays from the transcript — no fallback happened, so
// stamping 'agentic_fallback' would poison the phase fallback histogram.
const replaySuffix = `${SUFFIX}-replay`;
const replayOutput = VALID.replaceAll(SUFFIX, replaySuffix);
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, _chat: chatStub(replayOutput) });
const ctx = await makeCtx({
prompt: 'synthesize', mode: 'oneshot', require_writes: true,
allowed_slug_prefixes: PREFIXES, oneshot_slug_suffix: replaySuffix,
});
const first = await handler(ctx);
expect(first.synth_mode_used).toBe('oneshot');
const initialWrites = await engine.executeRaw<{ request_id: string; status: string }>(
"SELECT input->>'request_id' AS request_id,status FROM subagent_tool_executions WHERE job_id=$1 ORDER BY tool_use_id", [ctx.id]);
expect(initialWrites).toHaveLength(2);
expect(initialWrites.every(row => typeof row.request_id === 'string' && row.status === 'complete')).toBe(true);
let chatCalls = 0;
const spy = (async (...args: any[]) => { chatCalls++; return chatStub(replayOutput)(...args); }) as any;
const handler2 = makeSubagentHandler({ engine, client, _chat: spy });
const replayCtx: typeof ctx = { ...ctx, attempts_made: 1 };
const replay = await handler2(replayCtx);
expect(replay.synth_mode_used).not.toBe('agentic_fallback');
expect('fallback_reason' in replay).toBe(false);
// The ledger-first recovery path may finalize from rows (oneshot) or the
// transcript replay may return unset — either is honest; a fabricated
// fallback is not. Either way the model is not re-called by the loop.
expect(chatCalls).toBe(0);
expect(await engine.executeRaw(
"SELECT input->>'request_id' AS request_id,status FROM subagent_tool_executions WHERE job_id=$1 ORDER BY tool_use_id", [ctx.id]))
.toEqual(initialWrites);
});
});
// ── #4217 accounting fail-open (transient read error never kills a finished job) ──
describe('finalizeWriteAccounting read-error posture (CX-A3)', () => {
const { finalizeWriteAccounting } = require('../src/core/minions/handlers/subagent-persistence.ts');
const explodingEngine = {
executeRaw: async () => { throw new Error('pool reaped mid-read'); },
} as unknown as import('../src/core/engine.ts').BrainEngine;
const result = { result: 'done', turns_count: 3, stop_reason: 'end_turn', tokens: { in: 1, out: 1, cache_read: 0, cache_create: 0 } };
test('open-ended jobs fail OPEN: result returned unchanged on a read error', async () => {
const out = await finalizeWriteAccounting(explodingEngine, 999, result, { requireWrites: false });
expect(out).toBe(result);
});
test('require_writes jobs fail CLOSED: the read error rethrows (retry re-reads on a healthy pool)', async () => {
// Fail-open here would complete an all-writes-failed job on the exact
// pool failure the accounting exists to survive.
await expect(finalizeWriteAccounting(explodingEngine, 999, result, { requireWrites: true }))
.rejects.toThrow('pool reaped mid-read');
});
test('zero attempts + dirty stop_reason + require_writes → UnrecoverableError (CX-A4)', async () => {
const okEngine = {
executeRaw: async () => [],
} as unknown as import('../src/core/engine.ts').BrainEngine;
const truncated = { ...result, stop_reason: 'max_tokens' };
await expect(finalizeWriteAccounting(okEngine, 999, truncated, { requireWrites: true }))
.rejects.toThrow(/did not finish cleanly.*max_tokens/);
await expect(finalizeWriteAccounting(okEngine, 999, result, { requireWrites: true }))
.rejects.toThrow('zero required put_page writes');
const out = await finalizeWriteAccounting(okEngine, 999, result, { requireWrites: false });
expect(out.pages_attempted).toBe(0);
});
});
describe('handler-entry capability gate on the resolved model', () => {
test('config-resolved models.subagent with supports_subagent_loop: false is refused at dispatch', async () => {
// The queue submit gate only sees explicit data.model. A job that omits
// data.model resolves `models.subagent` inside the handler — pre-fix that
// path bypassed the capability check entirely and a loop-incapable model
// (declared supports_subagent_loop: false) ran the loop anyway.
await engine.setConfig('models.subagent', 'moonshot:kimi-k2.5');
try {
const client = new FakeMessagesClient([
{ content: [{ type: 'text', text: 'should never run' }] as any, stop_reason: 'end_turn' },
]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' }); // no data.model → queue gate passes
await expect(handler(ctx)).rejects.toThrow(/supports_subagent_loop/);
expect(client.calls.length).toBe(0); // refused before any provider call
} finally {
await engine.unsetConfig('models.subagent');
}
});
test('already-terminal replay is NOT refused when config points at a loop-incapable model', async () => {
// #1151 precedent: a job whose last persisted message is a terminal
// assistant turn needs no provider call — the replay short-circuit
// returns the committed result. A capability refusal here (config
// repointed between submit and replay) would dead-letter completed work.
// Gateway loop ON: that's the only routing where the capability gate is
// the deciding check (the legacy path's Anthropic pin refuses
// non-Anthropic models regardless). The gateway path's terminal
// early-return runs before any provider client is constructed, so no
// API key is needed.
await engine.setConfig('models.subagent', 'moonshot:kimi-k2.5');
await engine.setConfig('agent.use_gateway_loop', 'true');
try {
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
// Persist a completed transcript: seed user + terminal assistant.
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', $2::text::jsonb), ($1, 1, 'assistant', $3::text::jsonb)`,
[
ctx.id,
JSON.stringify([{ type: 'text', text: 'hi' }]),
JSON.stringify([{ type: 'text', text: 'committed answer' }]),
],
);
const result = await handler(ctx);
expect(result.result).toBe('committed answer');
// Replay short-circuit: no new turns persisted beyond the 2 seeded rows
// (a provider call would have appended an assistant row — and would have
// failed anyway, since no gateway credentials are configured here).
const rows = await engine.executeRaw<{ count: string }>(
`SELECT count(*)::text AS count FROM subagent_messages WHERE job_id = $1`,
[ctx.id],
);
expect(parseInt(rows[0]!.count, 10)).toBe(2);
} finally {
await engine.unsetConfig('models.subagent');
await engine.unsetConfig('agent.use_gateway_loop');
}
});
test('non-terminal gateway replay (pending tool-call) IS still refused on a loop-incapable model', async () => {
// A gateway transcript persists pending dispatch as `tool-call` blocks.
// A replay that still needs the loop to resume on the provider must NOT
// slip past the capability gate via the terminal exception.
await engine.setConfig('models.subagent', 'moonshot:kimi-k2.5');
await engine.setConfig('agent.use_gateway_loop', 'true');
try {
const client = new FakeMessagesClient([]);
const handler = makeSubagentHandler({ engine, client, toolRegistry: [] });
const ctx = await makeCtx({ prompt: 'hi' });
await engine.executeRaw(
`INSERT INTO subagent_messages (job_id, message_idx, role, content_blocks)
VALUES ($1, 0, 'user', $2::text::jsonb), ($1, 1, 'assistant', $3::text::jsonb)`,
[
ctx.id,
JSON.stringify([{ type: 'text', text: 'hi' }]),
JSON.stringify([{ type: 'tool-call', toolCallId: 'tc_1', toolName: 'echo', input: {} }]),
],
);
await expect(handler(ctx)).rejects.toThrow(/supports_subagent_loop/);
} finally {
await engine.unsetConfig('models.subagent');
await engine.unsetConfig('agent.use_gateway_loop');
}
});
});
describe('legacy loop: an accepted tool write that is still pending (#5474)', () => {
// A deadline this far out leaves a replay window well past every case below.
const farDeadline = () => Date.now() + 10 * 60_000;
/** A put_page whose write is pending for `pendingFor` dispatches, then lands in `settles`. */
function stagedWrite(pendingFor: number, opts: { throwPending?: boolean; settles?: 'committed' | 'failed'; retryAfterMs?: number } = {}) {
const requestIds: unknown[] = [];
const tool: ToolDef = { ...makeEchoTool('brain_put_page'), async execute(input) {
const request_id = (input as Record<string, unknown>).request_id; requestIds.push(request_id);
if (requestIds.length > pendingFor) return { request_id, state: opts.settles ?? 'committed', retry_after_ms: null };
const receipt = { request_id, state: 'queued', retry_after_ms: opts.retryAfterMs ?? 10 };
if (!opts.throwPending) return receipt;
const pending = new OperationError('write_pending', 'The write is accepted and is still pending.', 'Read its receipt.');
pending.writeRequest = receipt as never; pending.writeError = 'write_pending';
throw pending;
} };
return { tool, requestIds };
}
const oneWriteThenDone = () => new FakeMessagesClient([
{ content: [{ type: 'tool_use', id: 'tu_w', name: 'brain_put_page', input: { slug: 'notes/staged-example', content: 'x' } } as any], stop_reason: 'tool_use' as any },
{ content: [{ type: 'text', text: 'done' }] as any, stop_reason: 'end_turn' },
]);
const rowStatuses = async (jobId: number) =>
(await engine.executeRaw<{ status: string }>('SELECT status FROM subagent_tool_executions WHERE job_id = $1', [jobId])).map(r => r.status);
for (const throwPending of [false, true]) {
test(`a ${throwPending ? 'thrown write_pending' : 'returned queued receipt'} is replayed under one request id until it commits`, async () => {
const { tool, requestIds } = stagedWrite(4, { throwPending });
const client = oneWriteThenDone();
const ctx = { ...(await makeCtx({ prompt: 'go' })), deadlineAtMs: farDeadline() };
const result = await makeSubagentHandler({ engine, client, toolRegistry: [tool] })(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(client.calls.length).toBe(2);
expect(requestIds).toHaveLength(5);
expect(new Set(requestIds).size).toBe(1);
expect(await rowStatuses(ctx.id)).toEqual(['complete']);
});
}
test('the replay window follows the job deadline, not the shorter maintenance wait', async () => {
const restore = __setMaintenanceWriteWaitForTests(0);
try {
const { tool, requestIds } = stagedWrite(3);
const ctx = { ...(await makeCtx({ prompt: 'go' })), deadlineAtMs: farDeadline() };
const result = await makeSubagentHandler({ engine, client: oneWriteThenDone(), toolRegistry: [tool] })(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(requestIds).toHaveLength(4);
} finally { restore(); }
});
test('a job without a deadline replays only for the maintenance wait, then stays pending', async () => {
const restore = __setMaintenanceWriteWaitForTests(120);
try {
const { tool, requestIds } = stagedWrite(Number.MAX_SAFE_INTEGER);
const client = oneWriteThenDone();
const ctx = await makeCtx({ prompt: 'go' });
const started = Date.now();
const failure = await makeSubagentHandler({ engine, client, toolRegistry: [tool] })(ctx).then(() => null, (e: unknown) => e);
expect(failure).toMatchObject({ code: 'write_pending', writeRequest: { request_id: requestIds[0] } });
expect(Date.now() - started).toBeGreaterThanOrEqual(100);
expect(Date.now() - started).toBeLessThan(3_000);
expect(requestIds.length).toBeGreaterThan(2);
expect(new Set(requestIds).size).toBe(1);
expect(client.calls.length).toBe(1);
expect(await rowStatuses(ctx.id)).toEqual(['pending']);
} finally { restore(); }
});
test('a job already inside its deadline reserve does not replay', async () => {
const { tool, requestIds } = stagedWrite(Number.MAX_SAFE_INTEGER);
const ctx = { ...(await makeCtx({ prompt: 'go' })), deadlineAtMs: Date.now() + 40_000 };
await expect(makeSubagentHandler({ engine, client: oneWriteThenDone(), toolRegistry: [tool] })(ctx)).rejects.toMatchObject({ code: 'write_pending' });
expect(requestIds).toHaveLength(1);
expect(await rowStatuses(ctx.id)).toEqual(['pending']);
});
test('cancelling the job ends a long pause with the pending receipt and dispatches nothing more', async () => {
const { tool, requestIds } = stagedWrite(Number.MAX_SAFE_INTEGER, { retryAfterMs: 20_000 });
const cancel = new AbortController();
const ctx = { ...(await makeCtx({ prompt: 'go' })), deadlineAtMs: farDeadline(), signal: cancel.signal };
const started = Date.now();
const settled = makeSubagentHandler({ engine, client: oneWriteThenDone(), toolRegistry: [tool] })(ctx).then(() => null, (e: unknown) => e);
setTimeout(() => cancel.abort(new Error('example cancel')), 80);
expect(await settled).toMatchObject({ code: 'write_pending', writeRequest: { request_id: requestIds[0], state: 'queued' } });
expect(Date.now() - started).toBeLessThan(5_000);
await new Promise(resolve => setTimeout(resolve, 150));
expect(requestIds).toHaveLength(1);
expect(await rowStatuses(ctx.id)).toEqual(['pending']);
});
test('a write that ended failed is reported to the model, not replayed', async () => {
const { tool, requestIds } = stagedWrite(0, { settles: 'failed' });
const client = oneWriteThenDone();
const ctx = { ...(await makeCtx({ prompt: 'go' })), deadlineAtMs: farDeadline() };
const result = await makeSubagentHandler({ engine, client, toolRegistry: [tool] })(ctx);
expect(result.stop_reason).toBe('end_turn');
expect(requestIds).toHaveLength(1);
expect(client.calls.length).toBe(2);
expect(await rowStatuses(ctx.id)).toEqual(['failed']);
});
test('a tool that is not a journal mutation passes a queued-looking result straight through', async () => {
let dispatches = 0;
const lookalike: ToolDef = { ...makeEchoTool('brain_search'), async execute() {
dispatches++; return { request_id: '00000000-0000-4000-8000-000000000000', state: 'queued', retry_after_ms: 10 };
} };
const client = new FakeMessagesClient([
{ content: [{ type: 'tool_use', id: 'tu_s', name: 'brain_search', input: { query: 'x' } } as any], stop_reason: 'tool_use' as any },
{ content: [{ type: 'text', text: 'done' }] as any, stop_reason: 'end_turn' },
]);
const ctx = { ...(await makeCtx({ prompt: 'go' })), deadlineAtMs: farDeadline() };
expect((await makeSubagentHandler({ engine, client, toolRegistry: [lookalike] })(ctx)).stop_reason).toBe('end_turn');
expect(dispatches).toBe(1);
});
});