Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
29.7 KB
Raw Blame
/**
 * E2E: runSubagentViaGateway integration path (v0.38 Slice 1 + S1.5).
 *
 * Exercises the FULL gateway-native subagent handler path end-to-end:
 *   - Handler entry → reads `agent.use_gateway_loop` config → routes to gateway path
 *   - runSubagentViaGateway builds ChatToolDef[] + ToolHandler Map from ToolDef
 *   - Calls gateway.toolLoop() with persistence callbacks
 *   - Callbacks write subagent_messages (v2 ChatBlock shape) +
 *     subagent_tool_executions (with ordinal + gbrain_tool_use_id) under
 *     the write-ordering invariant
 *   - Returns SubagentResult mapped from gateway loop result
 *
 * Hermetic: PGLite in-memory engine, gateway transport stubbed via
 * `__setChatTransportForTests`. No ANTHROPIC_API_KEY, no real Anthropic
 * SDK instantiation (we stub `makeAnthropic` so the legacy-path fallback
 * doesn't trip on missing env).
 *
 * Plan reference: ~/.claude/plans/system-instruction-you-are-working-shimmying-breeze.md
 * (Slice 1 verification step 6 + cross-provider crash-replay regression — the
 * load-bearing test the CEO/codex review called out before v0.38 ships).
 */

import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import { PGLiteEngine } from '../../src/core/pglite-engine.ts';
import { resetPgliteState } from '../helpers/reset-pglite.ts';
import { makeSubagentHandler } from '../../src/core/minions/handlers/subagent.ts';
import { UnrecoverableError } from '../../src/core/minions/types.ts';
import type { MinionJobContext, ToolDef, ToolCtx } from '../../src/core/minions/types.ts';
import {
  __setChatTransportForTests,
  __setGenerateTextTransportForTests,
  configureGateway,
  resetGateway,
  type ChatBlock,
  type ChatResult,
} from '../../src/core/ai/gateway.ts';

// ── Helpers ─────────────────────────────────────────────────

let engine: PGLiteEngine;

beforeAll(async () => {
  engine = new PGLiteEngine();
  await engine.connect({});
  await engine.initSchema();
});

afterAll(async () => {
  await engine.disconnect();
});

beforeEach(async () => {
  await resetPgliteState(engine);
  await engine.setConfig('version', '85');
  await engine.setConfig('agent.use_gateway_loop', 'true');

  configureGateway({
    chat_model: 'anthropic:claude-sonnet-4-6',
    embedding_model: 'openai:text-embedding-3-large',
    embedding_dimensions: 1536,
    expansion_model: 'anthropic:claude-haiku-4-5',
    env: { ANTHROPIC_API_KEY: 'stub', OPENAI_API_KEY: 'stub' },
  });
});

function clearGateway(): void {
  __setChatTransportForTests(null);
  resetGateway();
}

interface FakeJobOpts {
  prompt: string;
  model?: string;
  allowed_tools?: string[];
  mode?: string;
}

async function makeFakeJob(opts: FakeJobOpts): Promise<{ jobId: number; ctx: MinionJobContext; tokenSink: any[] }> {
  // Insert a minion_jobs row so foreign keys validate (subagent_tool_executions.job_id FK).
  const rows = await engine.executeRaw<{ id: number }>(
    `INSERT INTO minion_jobs (submission_authority, name, status, data, queue, priority, created_at)
     VALUES ('{"version":1,"kind":"application"}'::jsonb, 'subagent', 'active', $1::jsonb, 'default', 0, now())
     RETURNING id`,
    [JSON.stringify({ prompt: opts.prompt, model: opts.model, allowed_tools: opts.allowed_tools, mode: opts.mode })],
  );
  const jobId = rows[0].id;

  const tokenSink: Array<{ input?: number; output?: number; cache_read?: number }> = [];

  const abortCtrl = new AbortController();
  const shutdownCtrl = new AbortController();
  const ctx: MinionJobContext = {
    id: jobId,
    name: 'subagent',
    data: { prompt: opts.prompt, model: opts.model, allowed_tools: opts.allowed_tools, mode: opts.mode },
    attempts_made: 0,
    idempotency_key: null,
    signal: abortCtrl.signal,
    deadlineAtMs: null,
    shutdownSignal: shutdownCtrl.signal,
    updateProgress: async () => {},
    updateTokens: async (t) => { tokenSink.push(t); },
    log: async () => {},
    isActive: async () => true,
    readInbox: async () => [],
  };
  return { jobId, ctx, tokenSink };
}

/**
 * Stub ToolDef registry — avoids pulling in buildBrainTools (which needs
 * config + engine + brain setup). Tools are simple in-test functions.
 */
function makeStubTools(executions: Array<{ name: string; input: unknown; ts: number }>): ToolDef[] {
  return [
    {
      name: 'search',
      description: 'stub search',
      input_schema: { type: 'object' },
      idempotent: true,
      async execute(input: unknown, _ctx: ToolCtx) {
        executions.push({ name: 'search', input, ts: Date.now() });
        return { results: [{ slug: 'wiki/foo' }] };
      },
    },
    {
      name: 'put_page',
      description: 'stub put_page (non-idempotent)',
      input_schema: { type: 'object' },
      idempotent: false,
      async execute(input: unknown, _ctx: ToolCtx) {
        executions.push({ name: 'put_page', input, ts: Date.now() });
        return { saved: true };
      },
    },
    {
      name: 'always_fail',
      description: 'stub that always throws',
      input_schema: { type: 'object' },
      idempotent: true,
      async execute(_input: unknown, _ctx: ToolCtx) {
        throw new Error('intentional tool failure');
      },
    },
  ];
}

/**
 * `brain_put_page` stub — the oneshot dispatch path (`data.mode ===
 * 'oneshot'`) requires this exact tool name to be present in the registry
 * (`args.putPageTool = registry.find(t => t.name === 'brain_put_page')`) or
 * it never calls chat() at all (falls back with `no_put_page_tool` before
 * reaching the model). Only present for oneshot-path tests; never invoked
 * by the error-path test below (the chat() call itself throws first).
 */
function makeOneshotStubTools(): ToolDef[] {
  return [
    {
      name: 'brain_put_page',
      description: 'stub brain_put_page',
      input_schema: { type: 'object' },
      idempotent: false,
      async execute() {
        throw new Error('brain_put_page stub should not execute in this test');
      },
    },
  ];
}

/**
 * Build the handler with a stubbed Anthropic constructor so the legacy
 * code path's `new Anthropic()` at construction never fires (we route
 * through the gateway path; the legacy client is unused).
 */
function buildHandler(toolRegistry: ToolDef[]) {
  return makeSubagentHandler({
    engine,
    config: {} as any,
    toolRegistry,
    makeAnthropic: () => ({ messages: { create: async () => { throw new Error('legacy path should not be invoked'); } } }) as any,
  });
}

// ── Tests ───────────────────────────────────────────────────

describe('runSubagentViaGateway (v0.38 Slice 1 — full handler path through gateway.toolLoop)', () => {
  afterAll(() => clearGateway());

  it('happy path 1-turn: gateway returns text, handler returns SubagentResult', async () => {
    __setChatTransportForTests(async () => ({
      text: 'all done',
      blocks: [{ type: 'text', text: 'all done' }] as ChatBlock[],
      stopReason: 'end',
      usage: { input_tokens: 12, output_tokens: 3, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'anthropic:claude-sonnet-4-6',
      providerId: 'anthropic',
    } satisfies ChatResult));

    const executions: Array<{ name: string; input: unknown; ts: number }> = [];
    const tools = makeStubTools(executions);
    const handler = buildHandler(tools);
    const { jobId, ctx } = await makeFakeJob({ prompt: 'hello', model: 'anthropic:claude-sonnet-4-6' });

    const result = await handler(ctx);

    expect(result.result).toBe('all done');
    expect(result.stop_reason).toBe('end_turn');
    expect(result.tokens.in).toBeGreaterThanOrEqual(12);
    expect(result.tokens.out).toBeGreaterThanOrEqual(3);
    expect(executions.length).toBe(0); // no tools called

    // Verify persistence: 1 seed user message + 1 assistant message.
    const messages = await engine.executeRaw<Record<string, unknown>>(
      `SELECT message_idx, role FROM subagent_messages WHERE job_id = $1 ORDER BY message_idx`,
      [jobId],
    );
    expect(messages.length).toBe(2);
    expect(messages[0].role).toBe('user');
    expect(messages[0].message_idx).toBe(0);
    expect(messages[1].role).toBe('assistant');
    expect(messages[1].message_idx).toBe(1);
  });

  it('openrouter:anthropic/… auto-routes through the gateway when the flag is off', async () => {
    await engine.unsetConfig('agent.use_gateway_loop');
    __setChatTransportForTests(async () => ({
      text: 'or-anthropic done',
      blocks: [{ type: 'text', text: 'or-anthropic done' }] as ChatBlock[],
      stopReason: 'end',
      usage: { input_tokens: 8, output_tokens: 2, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'openrouter:anthropic/claude-haiku-4.5',
      providerId: 'openrouter',
    } satisfies ChatResult));

    const handler = buildHandler(makeStubTools([]));
    const { ctx } = await makeFakeJob({
      prompt: 'hello',
      model: 'openrouter:anthropic/claude-haiku-4.5',
    });
    const result = await handler(ctx);
    expect(result.result).toBe('or-anthropic done');
    expect(result.stop_reason).toBe('end_turn');
  });

  it('openrouter:deepseek/… auto-routes through the gateway when the flag is off (#4757)', async () => {
    // The DeepSeek family shares the anthropic-via-OR contract: the recipe
    // predicate admits it (classifyCapabilities passes) and the handler's
    // isOpenRouterSubagentFamily auto-enables the gateway loop — without
    // that, the legacy Anthropic-direct pin throws "non-Anthropic but
    // agent.use_gateway_loop is not enabled" for a model the recipe accepts.
    await engine.unsetConfig('agent.use_gateway_loop');
    __setChatTransportForTests(async () => ({
      text: 'or-deepseek done',
      blocks: [{ type: 'text', text: 'or-deepseek done' }] as ChatBlock[],
      stopReason: 'end',
      usage: { input_tokens: 8, output_tokens: 2, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'openrouter:deepseek/deepseek-v4-flash',
      providerId: 'openrouter',
    } satisfies ChatResult));

    const handler = buildHandler(makeStubTools([]));
    const { ctx } = await makeFakeJob({
      prompt: 'hello',
      model: 'openrouter:deepseek/deepseek-v4-flash',
    });
    const result = await handler(ctx);
    expect(result.result).toBe('or-deepseek done');
    expect(result.stop_reason).toBe('end_turn');
  });

  it('openrouter:openai/… stays REFUSED when the flag is off — the auto-route is a family allowlist, not "anything on OpenRouter"', async () => {
    // Only families with a live abort/retry replay pin (anthropic/, deepseek/)
    // auto-enable the gateway loop. Everything else proxied through OpenRouter
    // is refused before the transport is reached. Two gates share the
    // allowlist (openrouter-families.ts): the recipe capability gate
    // (`supports_subagent_loop: false`) fires first; had a family been added
    // to the recipe predicate but not the handler's auto-route, the legacy
    // `use_gateway_loop is not enabled` refusal would surface instead. Either
    // way: rejected, zero transport calls.
    await engine.unsetConfig('agent.use_gateway_loop');
    let transportCalls = 0;
    __setChatTransportForTests(async () => {
      transportCalls++;
      return {
        text: 'must not run',
        blocks: [{ type: 'text', text: 'must not run' }] as ChatBlock[],
        stopReason: 'end',
        usage: { input_tokens: 1, output_tokens: 1, cache_read_tokens: 0, cache_creation_tokens: 0 },
        model: 'openrouter:openai/gpt-5.2',
        providerId: 'openrouter',
      } satisfies ChatResult;
    });

    const handler = buildHandler(makeStubTools([]));
    const { ctx } = await makeFakeJob({ prompt: 'hello', model: 'openrouter:openai/gpt-5.2' });
    await expect(handler(ctx)).rejects.toThrow(/supports_subagent_loop: false|use_gateway_loop is not enabled/);
    expect(transportCalls).toBe(0);
  });

  it('happy path 2-turn with tool: dispatches, persists v2 stable ID, returns final text', async () => {
    let turn = 0;
    __setChatTransportForTests(async () => {
      turn++;
      if (turn === 1) {
        return {
          text: '',
          blocks: [
            { type: 'tool-call', toolCallId: 'provider-tc-1', toolName: 'search', input: { q: 'acme' } },
          ] as ChatBlock[],
          stopReason: 'tool_calls',
          usage: { input_tokens: 20, output_tokens: 8, cache_read_tokens: 0, cache_creation_tokens: 0 },
          model: 'anthropic:claude-sonnet-4-6',
          providerId: 'anthropic',
        } satisfies ChatResult;
      }
      return {
        text: 'found acme corp',
        blocks: [{ type: 'text', text: 'found acme corp' }] as ChatBlock[],
        stopReason: 'end',
        usage: { input_tokens: 25, output_tokens: 4, cache_read_tokens: 0, cache_creation_tokens: 0 },
        model: 'anthropic:claude-sonnet-4-6',
        providerId: 'anthropic',
      } satisfies ChatResult;
    });

    const executions: Array<{ name: string; input: unknown; ts: number }> = [];
    const tools = makeStubTools(executions);
    const handler = buildHandler(tools);
    const { jobId, ctx } = await makeFakeJob({
      prompt: 'find acme',
      model: 'anthropic:claude-sonnet-4-6',
      allowed_tools: ['search'],
    });

    const result = await handler(ctx);

    expect(result.result).toBe('found acme corp');
    expect(result.stop_reason).toBe('end_turn');
    expect(executions.length).toBe(1);
    expect(executions[0].name).toBe('search');
    expect(executions[0].input).toEqual({ q: 'acme' });

    // Verify v2 stable-ID persistence: ordinal + gbrain_tool_use_id populated.
    const toolRows = await engine.executeRaw<Record<string, unknown>>(
      `SELECT message_idx, tool_use_id, tool_name, status, ordinal,
              gbrain_tool_use_id::text AS gbrain_tool_use_id, schema_version
         FROM subagent_tool_executions
        WHERE job_id = $1`,
      [jobId],
    );
    expect(toolRows.length).toBe(1);
    expect(toolRows[0].tool_name).toBe('search');
    expect(toolRows[0].status).toBe('complete');
    expect(toolRows[0].ordinal).toBe(0);
    expect(toolRows[0].schema_version).toBe(2); // v0.38 write
    expect(String(toolRows[0].gbrain_tool_use_id)).toMatch(/^[0-9a-f-]{36}$/); // UUID v7
    expect(toolRows[0].tool_use_id).toBe('provider-tc-1'); // raw provider id preserved (#4155)

    // Token accumulation across both turns.
    expect(result.tokens.in).toBe(45); // 20 + 25
    expect(result.tokens.out).toBe(12); // 8 + 4
  });

  it('#4155 regression: two different tool calls sharing the SAME provider id persist as two rows with the raw id intact', async () => {
    // Real-world shape: claude-cli replays a fresh subprocess per turn from
    // an id-stripped transcript, so the model invents the SAME short id
    // ("toolu_01") for the first tool call of every turn. Pre-fix, the second
    // turn's INSERT collided on the former job-wide `uniq_subagent_tools_use_id
    // UNIQUE (job_id, tool_use_id)` constraint (a DIFFERENT constraint than
    // this INSERT's own conflict target `(job_id, message_idx, ordinal)`) and
    // threw, dead-lettering the job after 3 attempts. Migration v131 dropped
    // that constraint; the raw provider id is stored as-is and row identity
    // is (job_id, message_idx, ordinal).
    let turn = 0;
    __setChatTransportForTests(async () => {
      turn++;
      if (turn === 1) {
        return {
          text: '',
          blocks: [{ type: 'tool-call', toolCallId: 'toolu_01', toolName: 'search', input: { q: 'first' } }] as ChatBlock[],
          stopReason: 'tool_calls',
          usage: { input_tokens: 10, output_tokens: 5, cache_read_tokens: 0, cache_creation_tokens: 0 },
          model: 'anthropic:claude-sonnet-4-6',
          providerId: 'anthropic',
        } satisfies ChatResult;
      }
      if (turn === 2) {
        return {
          text: '',
          blocks: [{ type: 'tool-call', toolCallId: 'toolu_01', toolName: 'put_page', input: { slug: 'x' } }] as ChatBlock[],
          stopReason: 'tool_calls',
          usage: { input_tokens: 10, output_tokens: 5, cache_read_tokens: 0, cache_creation_tokens: 0 },
          model: 'anthropic:claude-sonnet-4-6',
          providerId: 'anthropic',
        } satisfies ChatResult;
      }
      return {
        text: 'both done',
        blocks: [{ type: 'text', text: 'both done' }] as ChatBlock[],
        stopReason: 'end',
        usage: { input_tokens: 5, output_tokens: 3, cache_read_tokens: 0, cache_creation_tokens: 0 },
        model: 'anthropic:claude-sonnet-4-6',
        providerId: 'anthropic',
      } satisfies ChatResult;
    });

    const executions: Array<{ name: string; input: unknown; ts: number }> = [];
    const tools = makeStubTools(executions);
    const handler = buildHandler(tools);
    const { jobId, ctx } = await makeFakeJob({
      prompt: 'do two things',
      model: 'anthropic:claude-sonnet-4-6',
      allowed_tools: ['search', 'put_page'],
    });

    const result = await handler(ctx);

    expect(result.result).toBe('both done');
    expect(result.stop_reason).toBe('end_turn');
    expect(executions.map(e => e.name)).toEqual(['search', 'put_page']);

    const toolRows = await engine.executeRaw<Record<string, unknown>>(
      `SELECT message_idx, tool_use_id, tool_name, status
         FROM subagent_tool_executions
        WHERE job_id = $1
        ORDER BY message_idx`,
      [jobId],
    );
    // Both rows persisted — the collision never threw.
    expect(toolRows.length).toBe(2);
    expect(toolRows[0].tool_name).toBe('search');
    expect(toolRows[1].tool_name).toBe('put_page');
    expect(toolRows[0].status).toBe('complete');
    expect(toolRows[1].status).toBe('complete');
    // The RAW provider id is stored on both rows — readers disambiguate by
    // message_idx, which must differ across the two turns.
    expect(toolRows[0].tool_use_id).toBe('toolu_01');
    expect(toolRows[1].tool_use_id).toBe('toolu_01');
    expect(toolRows[0].message_idx).not.toBe(toolRows[1].message_idx);
  });

  it('tool error path: handler persists status=failed, loop continues with error feedback', async () => {
    let turn = 0;
    __setChatTransportForTests(async () => {
      turn++;
      if (turn === 1) {
        return {
          text: '',
          blocks: [
            { type: 'tool-call', toolCallId: 'tc-fail', toolName: 'always_fail', input: {} },
          ] as ChatBlock[],
          stopReason: 'tool_calls',
          usage: { input_tokens: 5, output_tokens: 2, cache_read_tokens: 0, cache_creation_tokens: 0 },
          model: 'anthropic:claude-sonnet-4-6',
          providerId: 'anthropic',
        } satisfies ChatResult;
      }
      return {
        text: 'sorry that failed',
        blocks: [{ type: 'text', text: 'sorry that failed' }] as ChatBlock[],
        stopReason: 'end',
        usage: { input_tokens: 8, output_tokens: 3, cache_read_tokens: 0, cache_creation_tokens: 0 },
        model: 'anthropic:claude-sonnet-4-6',
        providerId: 'anthropic',
      } satisfies ChatResult;
    });

    const executions: Array<{ name: string; input: unknown; ts: number }> = [];
    const tools = makeStubTools(executions);
    const handler = buildHandler(tools);
    const { jobId, ctx } = await makeFakeJob({ prompt: 'try', model: 'anthropic:claude-sonnet-4-6' });

    const result = await handler(ctx);

    expect(result.result).toBe('sorry that failed');
    const toolRows = await engine.executeRaw<Record<string, unknown>>(
      `SELECT status, error FROM subagent_tool_executions WHERE job_id = $1`,
      [jobId],
    );
    expect(toolRows[0].status).toBe('failed');
    expect(String(toolRows[0].error)).toContain('intentional tool failure');
  });

  it('terminal classification: a "prompt is too long" error is converted to UnrecoverableError (gap parity with the legacy path)', async () => {
    // The legacy raw-Anthropic-SDK path (subagent.ts's non-gateway branch)
    // converts this exact condition to UnrecoverableError so the worker
    // routes straight to `dead`, bypassing max_stalled retries. Pins that
    // the gateway-native path does the same.
    //
    // Deliberately exercises the REAL production error boundary rather than
    // __setChatTransportForTests (which bypasses gateway.chat()'s own
    // try/catch): __setGenerateTextTransportForTests stubs the transport ONE
    // layer deeper, so the thrown error passes through chat()'s real catch
    // and gets normalizeAIError()-wrapped exactly like a live provider call.
    // The thrown shape puts the phrase ONLY on the SDK's actual inner
    // `.error.message` field (not the outer `.message`, which normalizeAIError
    // copies onto the wrapped error) — the shape isPromptTooLongError's
    // cause-chain walk exists to still catch post-wrap.
    __setChatTransportForTests(null);
    __setGenerateTextTransportForTests(async () => {
      throw {
        status: 400,
        message: 'BadRequestError',
        error: {
          type: 'invalid_request_error',
          message: 'prompt is too long: 1707509 tokens > 1000000 maximum',
        },
      };
    });

    try {
      const tools = makeStubTools([]);
      const handler = buildHandler(tools);
      const { ctx } = await makeFakeJob({ prompt: 'huge input', model: 'anthropic:claude-sonnet-4-6' });

      let caught: unknown;
      try {
        await handler(ctx);
      } catch (e) {
        caught = e;
      }
      expect(caught).toBeInstanceOf(UnrecoverableError);
      const message = String((caught as Error).message);
      expect(message).toContain('prompt_too_long');
      // The actually-useful detail (the inner .error.message, not the outer
      // normalizeAIError()-wrapped "BadRequestError" text) must survive into
      // the dead-lettered job's error — this is what an operator reads to
      // diagnose a `dead` job, not just a generic label.
      expect(message).toContain('1707509 tokens > 1000000 maximum');
      expect(message).not.toContain('BadRequestError');
    } finally {
      __setGenerateTextTransportForTests(null);
    }
  });

  it('terminal classification: the oneshot dispatch path (data.mode=oneshot) also converts "prompt is too long" to UnrecoverableError (sibling gap to the gateway-loop fix above, #4674)', async () => {
    // Same production error boundary as the gateway-loop test above: the
    // oneshot dispatch runner (subagent-oneshot.ts) calls the SAME
    // gateway.chat() entrypoint, so a prompt-too-long error arrives
    // normalizeAIError()-wrapped here too. Before this fix, the oneshot
    // catch rethrew every non-abort error verbatim — no isPromptTooLongError
    // check — so this exact condition retried up to max_stalled on the
    // oneshot path even though the gateway-loop and legacy paths already
    // fast-failed on it.
    __setChatTransportForTests(null);
    __setGenerateTextTransportForTests(async () => {
      throw {
        status: 400,
        message: 'BadRequestError',
        error: {
          type: 'invalid_request_error',
          message: 'prompt is too long: 1707509 tokens > 1000000 maximum',
        },
      };
    });

    try {
      const tools = makeOneshotStubTools();
      const handler = buildHandler(tools);
      const { ctx } = await makeFakeJob({
        prompt: 'huge input',
        model: 'anthropic:claude-sonnet-4-6',
        mode: 'oneshot',
      });

      let caught: unknown;
      try {
        await handler(ctx);
      } catch (e) {
        caught = e;
      }
      expect(caught).toBeInstanceOf(UnrecoverableError);
      const message = String((caught as Error).message);
      expect(message).toContain('prompt_too_long');
      expect(message).toContain('1707509 tokens > 1000000 maximum');
      expect(message).not.toContain('BadRequestError');
    } finally {
      __setGenerateTextTransportForTests(null);
    }
  });

  it('max_turns: loop terminates when budget exhausted', async () => {
    // Always return tool_calls — never end. Should hit max_turns cap (default 20 in subagent.ts).
    __setChatTransportForTests(async () => ({
      text: '',
      blocks: [
        { type: 'tool-call', toolCallId: `tc-${Math.random()}`, toolName: 'search', input: {} },
      ] as ChatBlock[],
      stopReason: 'tool_calls',
      usage: { input_tokens: 1, output_tokens: 1, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'anthropic:claude-sonnet-4-6',
      providerId: 'anthropic',
    } satisfies ChatResult));

    const executions: Array<{ name: string; input: unknown; ts: number }> = [];
    const tools = makeStubTools(executions);
    const handler = buildHandler(tools);
    const { ctx } = await makeFakeJob({
      prompt: 'loop forever',
      model: 'anthropic:claude-sonnet-4-6',
    });
    // Override max_turns via data so the test runs in <1s.
    ctx.data.max_turns = 3;

    const result = await handler(ctx);

    expect(result.stop_reason).toBe('max_turns');
    // 3 tool dispatches over 3 turns (max_turns cap).
    expect(executions.length).toBe(3);
  });

  it('refusal stop reason: handler maps refusal → SubagentStopReason refusal', async () => {
    __setChatTransportForTests(async () => ({
      text: 'I cannot help with that',
      blocks: [{ type: 'text', text: 'I cannot help with that' }] as ChatBlock[],
      stopReason: 'refusal',
      usage: { input_tokens: 5, output_tokens: 7, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'anthropic:claude-sonnet-4-6',
      providerId: 'anthropic',
    } satisfies ChatResult));

    const tools = makeStubTools([]);
    const handler = buildHandler(tools);
    const { ctx } = await makeFakeJob({ prompt: 'bad request', model: 'anthropic:claude-sonnet-4-6' });

    const result = await handler(ctx);
    expect(result.stop_reason).toBe('refusal');
    expect(result.result).toBe('I cannot help with that');
  });

  it("length stop reason: output-cap truncation maps to max_tokens, not end_turn (#4088)", async () => {
    // Pre-fix, the gateway loop folded 'length' into 'end' and the handler's
    // else-arm reported 'end_turn' — a capped, truncated run looked like a
    // clean-but-empty completion (undoing #2778's honesty fix on this path).
    __setChatTransportForTests(async () => ({
      text: 'partial truncated outp',
      blocks: [{ type: 'text', text: 'partial truncated outp' }] as ChatBlock[],
      stopReason: 'length',
      usage: { input_tokens: 22000, output_tokens: 8192, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'anthropic:claude-sonnet-4-6',
      providerId: 'anthropic',
    } satisfies ChatResult));

    const tools = makeStubTools([]);
    const handler = buildHandler(tools);
    const { ctx } = await makeFakeJob({ prompt: 'huge prompt', model: 'anthropic:claude-sonnet-4-6' });

    const result = await handler(ctx);
    expect(result.stop_reason).toBe('max_tokens');
    expect(result.result).toBe('partial truncated outp');
  });

  it('non-Anthropic model routes through gateway path (the load-bearing v0.38 unlock)', async () => {
    // This is the headline scenario: openai:gpt-5.2 (no caching) works.
    // Pre-v0.38, this would have refused at queue.ts. With the gateway path
    // flag on, the loop runs end-to-end.
    __setChatTransportForTests(async () => ({
      text: 'gpt-5 says hi',
      blocks: [{ type: 'text', text: 'gpt-5 says hi' }] as ChatBlock[],
      stopReason: 'end',
      usage: { input_tokens: 4, output_tokens: 4, cache_read_tokens: 0, cache_creation_tokens: 0 },
      model: 'openai:gpt-5.2',
      providerId: 'openai',
    } satisfies ChatResult));

    const tools = makeStubTools([]);
    const handler = buildHandler(tools);
    const { ctx } = await makeFakeJob({ prompt: 'hi', model: 'openai:gpt-5.2' });

    const result = await handler(ctx);
    expect(result.result).toBe('gpt-5 says hi');
    expect(result.stop_reason).toBe('end_turn');
  });

  it('write-ordering invariant: assistant message persisted BEFORE tool pending row', async () => {
    // The D11 + codex P1 write-ordering invariant: persistence callbacks
    // fire in order so a SIGKILL between any two steps leaves the DB in a
    // reconcilable state. This test asserts the message_idx of the assistant
    // is strictly less than any subagent_tool_executions row that references it.
    let turn = 0;
    __setChatTransportForTests(async () => {
      turn++;
      if (turn === 1) {
        return {
          text: '',
          blocks: [
            { type: 'tool-call', toolCallId: 'order-tc', toolName: 'search', input: {} },
          ] as ChatBlock[],
          stopReason: 'tool_calls',
          usage: { input_tokens: 1, output_tokens: 1, cache_read_tokens: 0, cache_creation_tokens: 0 },
          model: 'anthropic:claude-sonnet-4-6',
          providerId: 'anthropic',
        } satisfies ChatResult;
      }
      return {
        text: 'done',
        blocks: [{ type: 'text', text: 'done' }] as ChatBlock[],
        stopReason: 'end',
        usage: { input_tokens: 1, output_tokens: 1, cache_read_tokens: 0, cache_creation_tokens: 0 },
        model: 'anthropic:claude-sonnet-4-6',
        providerId: 'anthropic',
      } satisfies ChatResult;
    });

    const tools = makeStubTools([]);
    const handler = buildHandler(tools);
    const { jobId, ctx } = await makeFakeJob({ prompt: 'go', model: 'anthropic:claude-sonnet-4-6' });

    await handler(ctx);

    // Find the assistant turn that contains the tool call.
    const msgs = await engine.executeRaw<Record<string, unknown>>(
      `SELECT message_idx, role FROM subagent_messages WHERE job_id = $1 ORDER BY message_idx`,
      [jobId],
    );
    const assistantIdx = (msgs.find(m => m.role === 'assistant') as any).message_idx;

    const toolRow = await engine.executeRaw<Record<string, unknown>>(
      `SELECT message_idx FROM subagent_tool_executions WHERE job_id = $1`,
      [jobId],
    );
    expect(toolRow[0].message_idx).toBe(assistantIdx);
    // Both rows present means the order completed correctly (assistant first,
    // tool exec keyed to it, follow-up user with results, second assistant).
    expect(msgs.length).toBeGreaterThanOrEqual(3);
  });
});