Merge remote-tracking branch 'origin/main'

apps/server/src/services/__tests__/budget.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { resolveToolBudget } from '../inference/budget.js';
+import type { Agent } from '../../types/api.js';
+
+const BASE_AGENT: Agent = {
+  id: 'test-agent',
+  name: 'Test',
+  description: 'test',
+  system_prompt: '',
+  temperature: 0.7,
+  top_p: null,
+  top_k: null,
+  min_p: null,
+  presence_penalty: null,
+  top_n_sigma: null,
+  dry_multiplier: null,
+  dry_base: null,
+  dry_allowed_length: null,
+  dry_penalty_last_n: null,
+  tools: ['view_file'],
+  model: null,
+  source: 'global',
+  max_tool_calls: null,
+  steps: null,
+  llama_extra_args: null,
+};
+
+describe('resolveToolBudget', () => {
+  it('returns 100 when agent is null (no-agent raw chat)', () => {
+    expect(resolveToolBudget(null)).toBe(100);
+  });
+
+  it('returns 100 when agent has no max_tool_calls override', () => {
+    expect(resolveToolBudget(BASE_AGENT)).toBe(100);
+  });
+
+  it('returns max_tool_calls when agent overrides the default', () => {
+    const agent: Agent = { ...BASE_AGENT, max_tool_calls: 25 };
+    expect(resolveToolBudget(agent)).toBe(25);
+  });
+
+  it('returns 0 when max_tool_calls is explicitly 0 (text-only mode)', () => {
+    const agent: Agent = { ...BASE_AGENT, max_tool_calls: 0 };
+    expect(resolveToolBudget(agent)).toBe(0);
+  });
+});

apps/server/src/services/__tests__/inference-helpers.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it, vi, afterEach } from 'vitest';
+import { samplerOptsFromAgent } from '../inference/stream-phase.js';
+import { createContentFlusher } from '../inference/content-flusher.js';
+import type { Sql } from '../../db.js';
+import type { Agent } from '../../types/api.js';
+
+const BASE_AGENT: Agent = {
+  id: 'test-agent',
+  name: 'Test',
+  description: 'test',
+  system_prompt: '',
+  temperature: 0.7,
+  top_p: null,
+  top_k: null,
+  min_p: null,
+  presence_penalty: null,
+  top_n_sigma: null,
+  dry_multiplier: null,
+  dry_base: null,
+  dry_allowed_length: null,
+  dry_penalty_last_n: null,
+  tools: ['view_file'],
+  model: null,
+  source: 'global',
+  max_tool_calls: null,
+  steps: null,
+  llama_extra_args: null,
+};
+
+describe('samplerOptsFromAgent', () => {
+  it('maps every nullable sampler field to undefined when agent is null', () => {
+    expect(samplerOptsFromAgent(null)).toEqual({
+      temperature: undefined,
+      top_p: undefined,
+      top_k: undefined,
+      min_p: undefined,
+      presence_penalty: undefined,
+      top_n_sigma: undefined,
+      dry_multiplier: undefined,
+      dry_base: undefined,
+      dry_allowed_length: undefined,
+      dry_penalty_last_n: undefined,
+    });
+  });
+
+  it('strips null sampler fields to undefined but keeps numeric values', () => {
+    const agent: Agent = {
+      ...BASE_AGENT,
+      temperature: 0.5,
+      top_p: 0.9,
+      top_k: null,
+      min_p: 0.05,
+      presence_penalty: null,
+      top_n_sigma: 1,
+      dry_multiplier: null,
+      dry_base: 1.75,
+      dry_allowed_length: null,
+      dry_penalty_last_n: 256,
+    };
+    expect(samplerOptsFromAgent(agent)).toEqual({
+      temperature: 0.5,
+      top_p: 0.9,
+      top_k: undefined,
+      min_p: 0.05,
+      presence_penalty: undefined,
+      top_n_sigma: 1,
+      dry_multiplier: undefined,
+      dry_base: 1.75,
+      dry_allowed_length: undefined,
+      dry_penalty_last_n: 256,
+    });
+  });
+
+  it('never includes a tools field (callers add it)', () => {
+    expect('tools' in samplerOptsFromAgent(BASE_AGENT)).toBe(false);
+  });
+});
+
+describe('createContentFlusher', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // A tagged-template stub matching postgres' sql`...` shape. Records the
+  // interpolated content snapshot (values[0]) of each UPDATE.
+  function makeSqlSpy() {
+    const writes: string[] = [];
+    const sql = ((_strings: TemplateStringsArray, ...values: unknown[]) => {
+      writes.push(values[0] as string);
+      return Promise.resolve([]);
+    }) as unknown as Sql;
+    return { sql, writes };
+  }
+
+  it('debounces: many scheduleFlush calls in one window produce one write', async () => {
+    vi.useFakeTimers();
+    const { sql, writes } = makeSqlSpy();
+    let content = '';
+    const flusher = createContentFlusher(sql, 'msg-1', () => content, 500);
+
+    content = 'a';
+    flusher.scheduleFlush();
+    content = 'ab';
+    flusher.scheduleFlush();
+    content = 'abc';
+    flusher.scheduleFlush();
+
+    expect(writes).toHaveLength(0); // nothing before the interval elapses
+    vi.advanceTimersByTime(500);
+    await flusher.drain();
+
+    expect(writes).toHaveLength(1);
+    // snapshot is read at fire time → latest content, not the value at schedule time
+    expect(writes[0]).toBe('abc');
+  });
+
+  it('arms a fresh timer after a flush fires', async () => {
+    vi.useFakeTimers();
+    const { sql, writes } = makeSqlSpy();
+    let content = 'one';
+    const flusher = createContentFlusher(sql, 'msg-1', () => content, 500);
+
+    flusher.scheduleFlush();
+    vi.advanceTimersByTime(500);
+    await Promise.resolve();
+
+    content = 'two';
+    flusher.scheduleFlush();
+    vi.advanceTimersByTime(500);
+    await flusher.drain();
+
+    expect(writes).toEqual(['one', 'two']);
+  });
+
+  it('drain cancels a pending timer without performing a final flush', async () => {
+    vi.useFakeTimers();
+    const { sql, writes } = makeSqlSpy();
+    let content = 'pending';
+    const flusher = createContentFlusher(sql, 'msg-1', () => content, 500);
+
+    flusher.scheduleFlush();
+    // Drain before the timer fires — the pending flush is cancelled, not forced.
+    await flusher.drain();
+    vi.advanceTimersByTime(500);
+    await Promise.resolve();
+
+    expect(writes).toHaveLength(0);
+  });
+});

apps/server/src/services/__tests__/model-context.test.ts

@@ -9,12 +9,9 @@ import {
 
 const TEST_URL = 'http://llama-swap.test:8401';
 
-function mockOkProps(n_ctx: number, total_slots = 1) {
+function mockOkProps(n_ctx: number) {
   return new Response(
-    JSON.stringify({
-      default_generation_settings: { n_ctx },
-      total_slots,
-    }),
+    JSON.stringify({ default_generation_settings: { n_ctx } }),
     { status: 200, headers: { 'Content-Type': 'application/json' } },
   );
 }
@@ -33,12 +30,10 @@ afterEach(() => {
 
 describe('getModelContext — positive cache', () => {
   it('returns the parsed body on a 200 with valid shape', async () => {
-    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockOkProps(262_144, 1));
+    const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(mockOkProps(262_144));
     const result = await getModelContext('qwen3.6');
     expect(result).not.toBeNull();
     expect(result!.n_ctx).toBe(262_144);
-    expect(result!.total_slots).toBe(1);
-    expect(typeof result!.fetched_at).toBe('number');
     // Verify the URL was constructed correctly — encodes the model name in
     // case it contains characters that would break the path.
     expect(fetchSpy).toHaveBeenCalledExactlyOnceWith(
@@ -57,19 +52,6 @@ describe('getModelContext — positive cache', () => {
     expect(fetchSpy).toHaveBeenCalledTimes(1);
   });
 
-  it('defaults total_slots to 1 when the server omits it', async () => {
-    // Mirror the docstring claim — total_slots is informational and we don't
-    // reject the response just because it's missing.
-    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
-      new Response(JSON.stringify({ default_generation_settings: { n_ctx: 8192 } }), {
-        status: 200,
-      }),
-    );
-    const result = await getModelContext('partial-model');
-    expect(result).not.toBeNull();
-    expect(result!.n_ctx).toBe(8192);
-    expect(result!.total_slots).toBe(1);
-  });
 });
 
 // ---- negative cache (single-shot) ------------------------------------------

apps/server/src/services/__tests__/sentinels.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { SENTINEL_KINDS, isAnySentinel, isCapHitSentinel, isDoomLoopSentinel, isMistakeRecoverySentinel } from '../inference/sentinels.js';
+import type { Message } from '../../types/api.js';
+
+function makeSentinel(kind: string): Message {
+  return {
+    id: 'msg-1',
+    session_id: 's',
+    chat_id: 'c',
+    role: 'system',
+    content: '',
+    kind: 'message',
+    tool_calls: null,
+    tool_results: null,
+    status: 'complete',
+    last_seq: 0,
+    tokens_used: null,
+    ctx_used: null,
+    ctx_max: null,
+    started_at: null,
+    finished_at: null,
+    created_at: new Date().toISOString(),
+    metadata: { kind } as unknown as import('../../types/api.js').MessageMetadata,
+    summary: false,
+    tail_start_id: null,
+    compacted_at: null,
+  };
+}
+
+describe('SENTINEL_KINDS — single source of truth', () => {
+  it('contains the three known sentinel kinds', () => {
+    expect(SENTINEL_KINDS.has('cap_hit')).toBe(true);
+    expect(SENTINEL_KINDS.has('doom_loop')).toBe(true);
+    expect(SENTINEL_KINDS.has('mistake_recovery')).toBe(true);
+  });
+
+  it('does not contain arbitrary strings', () => {
+    expect(SENTINEL_KINDS.has('user')).toBe(false);
+    expect(SENTINEL_KINDS.has('assistant')).toBe(false);
+    expect(SENTINEL_KINDS.has('')).toBe(false);
+  });
+});
+
+describe('isAnySentinel', () => {
+  it('returns true for cap_hit', () => {
+    expect(isAnySentinel(makeSentinel('cap_hit'))).toBe(true);
+  });
+
+  it('returns true for doom_loop', () => {
+    expect(isAnySentinel(makeSentinel('doom_loop'))).toBe(true);
+  });
+
+  it('returns true for mistake_recovery', () => {
+    expect(isAnySentinel(makeSentinel('mistake_recovery'))).toBe(true);
+  });
+
+  it('returns false for non-system role', () => {
+    const m = { ...makeSentinel('cap_hit'), role: 'user' as const };
+    expect(isAnySentinel(m)).toBe(false);
+  });
+
+  it('returns false for null metadata', () => {
+    const m = { ...makeSentinel('cap_hit'), metadata: null };
+    expect(isAnySentinel(m)).toBe(false);
+  });
+
+  it('returns false for unknown kind', () => {
+    expect(isAnySentinel(makeSentinel('unknown_kind'))).toBe(false);
+  });
+});
+
+describe('individual sentinel predicates still work', () => {
+  it('isCapHitSentinel matches cap_hit only', () => {
+    expect(isCapHitSentinel(makeSentinel('cap_hit'))).toBe(true);
+    expect(isCapHitSentinel(makeSentinel('doom_loop'))).toBe(false);
+  });
+
+  it('isDoomLoopSentinel matches doom_loop only', () => {
+    expect(isDoomLoopSentinel(makeSentinel('doom_loop'))).toBe(true);
+    expect(isDoomLoopSentinel(makeSentinel('cap_hit'))).toBe(false);
+  });
+
+  it('isMistakeRecoverySentinel matches mistake_recovery only', () => {
+    expect(isMistakeRecoverySentinel(makeSentinel('mistake_recovery'))).toBe(true);
+    expect(isMistakeRecoverySentinel(makeSentinel('cap_hit'))).toBe(false);
+  });
+});

apps/server/src/services/__tests__/step-decision.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import { resolveTurnConfig, MAX_STEPS } from '../inference/turn-config.js';
+import { decideStep, decidePostToolAction } from '../inference/step-decision.js';
+import { DOOM_LOOP_THRESHOLD } from '../inference/sentinels.js';
+import type { MistakeState } from '../inference/mistake-tracker.js';
+import type { Agent, ToolCall } from '../../types/api.js';
+
+const BASE_AGENT: Agent = {
+  id: 'test-agent',
+  name: 'Test',
+  description: 'test',
+  system_prompt: '',
+  temperature: 0.7,
+  top_p: null,
+  top_k: null,
+  min_p: null,
+  presence_penalty: null,
+  top_n_sigma: null,
+  dry_multiplier: null,
+  dry_base: null,
+  dry_allowed_length: null,
+  dry_penalty_last_n: null,
+  tools: ['view_file'],
+  model: null,
+  source: 'global',
+  max_tool_calls: null,
+  steps: null,
+  llama_extra_args: null,
+};
+
+function call(name: string, args: Record<string, unknown> = {}): ToolCall {
+  return { id: `tc-${name}-${JSON.stringify(args)}`, name, args };
+}
+
+describe('resolveTurnConfig', () => {
+  it('no agent → budget 100, cap MAX_STEPS, not text-only', () => {
+    expect(resolveTurnConfig(null)).toEqual({
+      effectiveCap: MAX_STEPS,
+      budget: 100,
+      isTextOnly: false,
+    });
+  });
+
+  it('steps: 0 → effectiveCap 0 and isTextOnly true', () => {
+    expect(resolveTurnConfig({ ...BASE_AGENT, steps: 0 })).toEqual({
+      effectiveCap: 0,
+      budget: 100,
+      isTextOnly: true,
+    });
+  });
+
+  it('steps below MAX_STEPS → effectiveCap is the agent value', () => {
+    expect(resolveTurnConfig({ ...BASE_AGENT, steps: 5 }).effectiveCap).toBe(5);
+  });
+
+  it('steps above MAX_STEPS → effectiveCap clamps to MAX_STEPS', () => {
+    expect(resolveTurnConfig({ ...BASE_AGENT, steps: 9999 }).effectiveCap).toBe(MAX_STEPS);
+  });
+
+  it('max_tool_calls overrides the budget', () => {
+    expect(resolveTurnConfig({ ...BASE_AGENT, max_tool_calls: 12 }).budget).toBe(12);
+  });
+});
+
+describe('decideStep (top-of-loop gate)', () => {
+  it('returns stream when no doom loop and under budget', () => {
+    expect(decideStep({ recentToolCalls: [], toolsUsed: 0, budget: 30 })).toEqual({ kind: 'stream' });
+  });
+
+  it('returns budget when toolsUsed has reached the budget', () => {
+    expect(decideStep({ recentToolCalls: [], toolsUsed: 30, budget: 30 })).toEqual({ kind: 'budget' });
+  });
+
+  it('returns doom (with the looping call) on identical-repeat tail', () => {
+    const recent = Array.from({ length: DOOM_LOOP_THRESHOLD }, () => call('view_file', { path: '/a' }));
+    const d = decideStep({ recentToolCalls: recent, toolsUsed: 1, budget: 30 });
+    expect(d.kind).toBe('doom');
+    if (d.kind === 'doom') {
+      expect(d.loop.name).toBe('view_file');
+      expect(d.loop.args).toEqual({ path: '/a' });
+    }
+  });
+
+  it('doom takes precedence over budget when both would trip', () => {
+    const recent = Array.from({ length: DOOM_LOOP_THRESHOLD }, () => call('grep', { q: 'x' }));
+    expect(decideStep({ recentToolCalls: recent, toolsUsed: 30, budget: 30 }).kind).toBe('doom');
+  });
+});
+
+describe('decidePostToolAction (post-tool decision)', () => {
+  const clean: MistakeState = { run: [], nudges: 0 };
+
+  it('non-continue actions stop the loop without consulting the tracker', () => {
+    expect(decidePostToolAction('paused', { run: ['exec_error', 'exec_error', 'exec_error'], nudges: 0 })).toBe('stop');
+    expect(decidePostToolAction('synthesis_done', clean)).toBe('stop');
+  });
+
+  it('continue with a clean tracker → continue', () => {
+    expect(decidePostToolAction('continue', clean)).toBe('continue');
+  });
+
+  it('continue with a threshold streak and no prior nudge → nudge', () => {
+    const tracker: MistakeState = { run: ['zod_reject', 'tool_not_found', 'exec_error'], nudges: 0 };
+    expect(decidePostToolAction('continue', tracker)).toBe('nudge');
+  });
+
+  it('continue with a threshold streak after a nudge already fired → escalate', () => {
+    const tracker: MistakeState = { run: ['zod_reject', 'tool_not_found', 'exec_error'], nudges: 1 };
+    expect(decidePostToolAction('continue', tracker)).toBe('escalate');
+  });
+});

apps/server/src/services/__tests__/tools-registry.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import {
+  ALL_TOOLS,
+  TOOLS_BY_NAME,
+  appendMcpTools,
+  toolJsonSchemas,
+  type ToolDef,
+} from '../tools.js';
+
+// Parity test for the register-through MCP-discovery contract (Phase 6 split).
+// `ALL_TOOLS` / `TOOLS_BY_NAME` are `let`-bound in tools/registry.ts and
+// reassigned by appendMcpTools() at startup; this barrel re-exports them.
+// apps/coder relies on this exact behavior: it imports `appendMcpTools` + the
+// live `ALL_TOOLS` binding from @boocode/server/tools, calls appendMcpTools()
+// once, then reads ALL_TOOLS. ESM live bindings must carry the mutation
+// through the barrel re-export — if the split ever snapshots the array instead
+// of re-exporting the live binding, these assertions fail. Each test file gets
+// an isolated module instance (vitest default), so mutating the registry here
+// does not leak into tools.test.ts.
+function makeFakeMcpTool(name: string): ToolDef<unknown> {
+  return {
+    name,
+    description: `fake mcp tool ${name}`,
+    inputSchema: z.object({}) as z.ZodType<unknown>,
+    jsonSchema: {
+      type: 'function',
+      function: {
+        name,
+        description: `fake mcp tool ${name}`,
+        parameters: { type: 'object', properties: {}, additionalProperties: false },
+      },
+    },
+    async execute() {
+      return { ok: true };
+    },
+  };
+}
+
+describe('appendMcpTools register-through contract', () => {
+  it('is a no-op for an empty array', () => {
+    const before = ALL_TOOLS.length;
+    appendMcpTools([]);
+    expect(ALL_TOOLS.length).toBe(before);
+  });
+
+  it('mutates the live ALL_TOOLS / TOOLS_BY_NAME bindings observable through the barrel', () => {
+    const before = ALL_TOOLS.length;
+    // Names chosen so insertion lands away from the array ends, proving the
+    // re-sort runs (a naive concat would leave them at the tail).
+    const a = makeFakeMcpTool('mcp__alpha__probe');
+    const z2 = makeFakeMcpTool('mcp__zeta__probe');
+    appendMcpTools([z2, a]);
+
+    expect(ALL_TOOLS.length).toBe(before + 2);
+    expect(TOOLS_BY_NAME['mcp__alpha__probe']).toBe(a);
+    expect(TOOLS_BY_NAME['mcp__zeta__probe']).toBe(z2);
+
+    // Still alpha-sorted after the append (prompt-cache stability invariant).
+    const names = ALL_TOOLS.map((t) => t.name);
+    expect(names).toEqual([...names].sort((x, y) => x.localeCompare(y)));
+
+    // toolJsonSchemas() reads through the same live binding.
+    const schemaNames = toolJsonSchemas().map((s) => s.function.name);
+    expect(schemaNames).toContain('mcp__alpha__probe');
+    expect(schemaNames).toContain('mcp__zeta__probe');
+  });
+});

apps/server/src/services/agents.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import type { Agent, AgentsResponse, AgentParseError } from '../types/api.js';
 import { ALL_TOOLS, resolveToolTier } from './tools.js';
 import { validateExtraArgs } from './inference/llama-args-validator.js';
+import { stripQuotes } from '../utils/string-utils.js';
 
 // v1.8.1: global agents live at /data/AGENTS.md inside the container
 // (./data:/data:ro mount on the host). Per-project AGENTS.md at the project
@@ -107,17 +108,50 @@ interface ParsedFrontmatter {
   llama_extra_args?: string[];
 }
 
-function stripQuotes(s: string): string {
-  if (
-    s.length >= 2 &&
-    (s[0] === '"' || s[0] === "'") &&
-    s[0] === s[s.length - 1]
-  ) {
-    return s.slice(1, -1);
-  }
-  return s;
+// P5: table-driven validation for the "soft-range" numeric frontmatter fields.
+// Each was a near-identical Number() + finite/integer + range-warn + push-error
+// block. "Soft-range" = the value is STORED whenever the type checks out; an
+// out-of-range value only emits a console.warn (it is NOT skipped). A type
+// mismatch hard-fails the block. The range descriptor in the warn message is
+// `min-max` when both bounds exist, else `(≥min)` — matching the original
+// hand-written strings byte-for-byte.
+//
+// max_tool_calls and steps are deliberately NOT in this table: they are
+// "hard-range" (store ONLY if in range; an in-type-but-out-of-range value is
+// warned AND skipped) with bespoke messages, so they stay explicit below.
+type NumericFieldKey =
+  | 'temperature'
+  | 'top_p'
+  | 'top_k'
+  | 'min_p'
+  | 'presence_penalty'
+  | 'top_n_sigma'
+  | 'dry_multiplier'
+  | 'dry_base'
+  | 'dry_allowed_length'
+  | 'dry_penalty_last_n';
+
+interface NumericFieldSpec {
+  key: NumericFieldKey;
+  isInt: boolean;
+  min?: number;
+  max?: number;
 }
 
+const NUMERIC_FIELDS: readonly NumericFieldSpec[] = [
+  { key: 'temperature', isInt: false },
+  { key: 'top_p', isInt: false, min: 0, max: 1 },
+  { key: 'top_k', isInt: true, min: 0, max: 200 },
+  { key: 'min_p', isInt: false, min: 0, max: 1 },
+  { key: 'presence_penalty', isInt: false, min: -2, max: 2 },
+  // v2.6 sampling-streamjson-tokens (#11): llama.cpp sampler extensions.
+  { key: 'top_n_sigma', isInt: false, min: 0 },
+  { key: 'dry_multiplier', isInt: false, min: 0 },
+  { key: 'dry_base', isInt: false, min: 0 },
+  { key: 'dry_allowed_length', isInt: true, min: 0 },
+  { key: 'dry_penalty_last_n', isInt: true, min: -1 },
+];
+
 function parseFrontmatter(yaml: string): { data: ParsedFrontmatter; errors: string[] } {
   const data: ParsedFrontmatter = {};
   const errors: string[] = [];
@@ -140,108 +174,33 @@ function parseFrontmatter(yaml: string): { data: ParsedFrontmatter; errors: stri
     const key = line.slice(0, colonIdx).trim();
     const valueRaw = line.slice(colonIdx + 1).trim();
 
-    if (key === 'temperature') {
+    const numericSpec = NUMERIC_FIELDS.find((f) => f.key === key);
+    if (numericSpec) {
       const n = Number(valueRaw);
-      if (Number.isFinite(n)) data.temperature = n;
-      else errors.push(`temperature must be a number (got "${valueRaw}")`);
-    } else if (key === 'top_p') {
-      const n = Number(valueRaw);
-      if (Number.isFinite(n)) {
-        data.top_p = n;
-        if (n < 0 || n > 1) {
-          console.warn(`agents: top_p ${n} out of range 0-1, ignoring (falling back to default)`);
+      const typeOk = numericSpec.isInt ? Number.isInteger(n) : Number.isFinite(n);
+      if (typeOk) {
+        // Soft-range: store regardless of range; out-of-range only warns.
+        data[numericSpec.key] = n;
+        const below = numericSpec.min !== undefined && n < numericSpec.min;
+        const above = numericSpec.max !== undefined && n > numericSpec.max;
+        if (below || above) {
+          const range =
+            numericSpec.max !== undefined
+              ? `${numericSpec.min}-${numericSpec.max}`
+              : `(≥${numericSpec.min})`;
+          console.warn(
+            `agents: ${numericSpec.key} ${n} out of range ${range}, ignoring (falling back to default)`,
+          );
         }
       } else {
-        errors.push(`top_p must be a number (got "${valueRaw}")`);
+        errors.push(
+          `${numericSpec.key} must be ${numericSpec.isInt ? 'an integer' : 'a number'} (got "${valueRaw}")`,
+        );
       }
-    } else if (key === 'top_k') {
-      const n = Number(valueRaw);
-      if (Number.isInteger(n)) {
-        data.top_k = n;
-        if (n < 0 || n > 200) {
-          console.warn(`agents: top_k ${n} out of range 0-200, ignoring (falling back to default)`);
-        }
-      } else {
-        errors.push(`top_k must be an integer (got "${valueRaw}")`);
-      }
-    } else if (key === 'min_p') {
-      const n = Number(valueRaw);
-      if (Number.isFinite(n)) {
-        data.min_p = n;
-        if (n < 0 || n > 1) {
-          console.warn(`agents: min_p ${n} out of range 0-1, ignoring (falling back to default)`);
-        }
-      } else {
-        errors.push(`min_p must be a number (got "${valueRaw}")`);
-      }
-    } else if (key === 'presence_penalty') {
-      const n = Number(valueRaw);
-      if (Number.isFinite(n)) {
-        data.presence_penalty = n;
-        if (n < -2 || n > 2) {
-          console.warn(`agents: presence_penalty ${n} out of range -2-2, ignoring (falling back to default)`);
-        }
-      } else {
-        errors.push(`presence_penalty must be a number (got "${valueRaw}")`);
-      }
-    } else if (key === 'top_n_sigma') {
-      // v2.6 #11: llama.cpp top-n-sigma sampler. Float ≥ 0 (typical 0-3).
-      // Mirrors top_p/min_p: store then warn on out-of-range (non-numeric
-      // hard-fails the block).
-      const n = Number(valueRaw);
-      if (Number.isFinite(n)) {
-        data.top_n_sigma = n;
-        if (n < 0) {
-          console.warn(`agents: top_n_sigma ${n} out of range (≥0), ignoring (falling back to default)`);
-        }
-      } else {
-        errors.push(`top_n_sigma must be a number (got "${valueRaw}")`);
-      }
-    } else if (key === 'dry_multiplier') {
-      // v2.6 #11: DRY repetition-penalty multiplier. Float ≥ 0 (0 disables DRY).
-      const n = Number(valueRaw);
-      if (Number.isFinite(n)) {
-        data.dry_multiplier = n;
-        if (n < 0) {
-          console.warn(`agents: dry_multiplier ${n} out of range (≥0), ignoring (falling back to default)`);
-        }
-      } else {
-        errors.push(`dry_multiplier must be a number (got "${valueRaw}")`);
-      }
-    } else if (key === 'dry_base') {
-      // v2.6 #11: DRY penalty growth base. Float ≥ 0.
-      const n = Number(valueRaw);
-      if (Number.isFinite(n)) {
-        data.dry_base = n;
-        if (n < 0) {
-          console.warn(`agents: dry_base ${n} out of range (≥0), ignoring (falling back to default)`);
-        }
-      } else {
-        errors.push(`dry_base must be a number (got "${valueRaw}")`);
-      }
-    } else if (key === 'dry_allowed_length') {
-      // v2.6 #11: DRY max sequence length not penalized. Integer ≥ 0.
-      const n = Number(valueRaw);
-      if (Number.isInteger(n)) {
-        data.dry_allowed_length = n;
-        if (n < 0) {
-          console.warn(`agents: dry_allowed_length ${n} out of range (≥0), ignoring (falling back to default)`);
-        }
-      } else {
-        errors.push(`dry_allowed_length must be an integer (got "${valueRaw}")`);
-      }
-    } else if (key === 'dry_penalty_last_n') {
-      // v2.6 #11: DRY lookback window. Integer ≥ -1 (-1 = whole context, 0 = off).
-      const n = Number(valueRaw);
-      if (Number.isInteger(n)) {
-        data.dry_penalty_last_n = n;
-        if (n < -1) {
-          console.warn(`agents: dry_penalty_last_n ${n} out of range (≥-1), ignoring (falling back to default)`);
-        }
-      } else {
-        errors.push(`dry_penalty_last_n must be an integer (got "${valueRaw}")`);
-      }
-    } else if (key === 'tools') {
+      continue;
+    }
+
+    if (key === 'tools') {
       if (valueRaw === '') {
         data.tools = [];
         arrayKey = 'tools';
@@ -478,14 +437,6 @@ interface CacheEntry {
 // corresponding mtime so the next read sees a miss without a watcher.
 const cache = new Map<string, CacheEntry>();
 
-export function invalidateAgentsCache(projectPath?: string): void {
-  if (projectPath === undefined) {
-    cache.clear();
-  } else {
-    cache.delete(projectPath);
-  }
-}
-
 // v1.13.8: cache-read accessor for the system-prompt prefix-fingerprint log.
 // Returns the AGENTS.md mtimes that getAgentsForProject() observed on its
 // last cache fill for this projectPath. Both fields are null when the cache

apps/server/src/services/auto_name.ts

@@ -19,8 +19,6 @@ function cleanTitle(raw: string): string {
   return name;
 }
 
-// TODO: wire suggestTags after task model validation
-
 export async function maybeAutoNameChat(
   ctx: InferenceContext,
   chatId: string,

apps/server/src/services/codecontext_client.ts

@@ -113,7 +113,7 @@ export async function callCodecontext(
   fetcher: typeof fetch = fetch,
 ): Promise<CodecontextResponse> {
   // Step 1: realpath the project root, then realpath the requested target_dir
-  // (defaulting to projectPath when the caller didn't pass one — the 8 wrappers
+  // (defaulting to projectPath when the caller didn't pass one — the 12 wrappers
   // never pass target_dir; tests can override). A non-existent target_dir
   // throws before we hit the network so the model gets a sharp error.
   const resolvedProject = await realpath(req.projectPath);

apps/server/src/services/compaction.ts

@@ -22,6 +22,8 @@ import type { Config } from '../config.js';
 import type { Broker } from './broker.js';
 import { SUMMARY_TEMPLATE } from './compaction-prompt.js';
 import * as modelContextLookup from './model-context.js';
+import { SENTINEL_KINDS } from './inference/sentinels.js';
+import type { OpenAiMessage } from './inference/payload.js';
 
 // v1.13.9: ratio-only overflow trigger. Fires compaction at 85% of ctx_max
 // (opencode session/overflow.ts pattern). Replaces the v1.11.0-era
@@ -256,24 +258,9 @@ export function buildPrompt(
 // would silently drop pre-legacy-compact history before the LLM sees it.
 // Compaction wants to send the entire head, full stop.) ===
 
-// v1.13.6: exported for unit-test access (reasoning render coverage).
-export interface OpenAiMessage {
-  role: 'system' | 'user' | 'assistant' | 'tool';
-  content: string | null;
-  tool_calls?: Array<{
-    id: string;
-    type: 'function';
-    function: { name: string; arguments: string };
-  }>;
-  tool_call_id?: string;
-}
-
-// #12: mirror inference/sentinels.ts:isAnySentinel over the CompactionMessage
-// shape (which carries metadata as { kind?: string } | null, not the full
-// Message type isAnySentinel expects). All UI-only sentinels are stripped from
-// the head payload — they never go to the summarizer LLM. Keep the kind list in
-// sync with isAnySentinel in sentinels.ts.
-const SENTINEL_KINDS = new Set(['cap_hit', 'doom_loop', 'mistake_recovery']);
+// #12: SENTINEL_KINDS imported from inference/sentinels.ts (single source).
+// OpenAiMessage imported from inference/payload.ts (structurally compatible —
+// compaction's head payload doesn't need the optional reasoning? field).
 function isAnySentinel(m: CompactionMessage): boolean {
   return (
     m.role === 'system' &&

apps/server/src/services/file_ops.ts

@@ -200,7 +200,7 @@ export async function grep(
 export async function findFiles(
   projectRoot: string,
   pattern?: string,
-  opts?: { type?: 'file' | 'dir'; max_results?: number; path?: string; extra_roots?: readonly string[] }
+  opts?: { max_results?: number; path?: string; extra_roots?: readonly string[] }
 ): Promise<FindFilesResult> {
   const limit = Math.min(
     Math.max(opts?.max_results ?? DEFAULT_FIND_RESULTS, 1),

apps/server/src/services/git_meta.ts

@@ -83,10 +83,3 @@ export async function getGitMeta(rootPath: string): Promise<GitMeta | null> {
   return value;
 }
 
-export function invalidateGitMetaCache(rootPath?: string): void {
-  if (rootPath) {
-    cache.delete(rootPath);
-  } else {
-    cache.clear();
-  }
-}

apps/server/src/services/inference/budget.ts

@@ -1,32 +1,10 @@
 import type { Agent } from '../../types/api.js';
-import { READ_ONLY_TOOL_NAMES } from '../tools.js';
-
-// v1.8.2: tool-call budget defaults. Resolved per-turn by resolveToolBudget.
-//   - Agent with explicit max_tool_calls: that value.
-//   - Agent with read-only-only tools:    BUDGET_READ_ONLY (50).
-//   - Agent with any non-read-only tool:  BUDGET_NON_READ_ONLY (10).
-//   - No agent (raw chat):                BUDGET_NO_AGENT (50).
-// v1.13.7: bumped BUDGET_NO_AGENT 15→30 to match BUDGET_READ_ONLY. Every tool
-// in ALL_TOOLS today is read-only (see services/tools.ts comment at
-// READ_ONLY_TOOL_NAMES); the cautious 15-cap was a forward-looking guard for
-// write tools that haven't landed yet. No-agent mode gets the same toolset as
-// an all-read-only agent at runtime, so they should share the same budget.
-// v1.13.12: bumped read-only caps 30→50. Real recon sessions were hitting 30
-// with ~3 turns wasted on codecontext parse failures (empty node_modules
-// files); legitimate need was ~27, and Architect-class system overviews want
-// deeper recon than a 30-cap permits. Headroom of 20 absorbs failure-retry
-// turns + deeper exploration without changing the safety floor materially —
-// the doom-loop guard (3 identical calls → abort) catches the actual failure
-// mode this cap was guarding against.
-export const BUDGET_READ_ONLY = 100;
-export const BUDGET_NON_READ_ONLY = 100;
-export const BUDGET_NO_AGENT = 100;
-
-const READ_ONLY_SET: ReadonlySet<string> = new Set(READ_ONLY_TOOL_NAMES);
 
+// Tool-call budget. All three historical tiers (read-only, non-read-only,
+// no-agent) converged to 100 as of v1.13.12, collapsing the tier logic.
+// The only remaining override is per-agent max_tool_calls from AGENTS.md
+// frontmatter. Flat default of 100; doom-loop guard in sentinels.ts catches
+// pathological cases well before the cap is reached.
 export function resolveToolBudget(agent: Agent | null): number {
-  if (agent?.max_tool_calls != null) return agent.max_tool_calls;
-  if (!agent) return BUDGET_NO_AGENT;
-  const allReadOnly = agent.tools.every((t) => READ_ONLY_SET.has(t));
-  return allReadOnly ? BUDGET_READ_ONLY : BUDGET_NON_READ_ONLY;
+  return agent?.max_tool_calls ?? 100;
 }

apps/server/src/services/inference/content-flusher.ts

@@ -0,0 +1,64 @@
+// P5: the debounced DB content-flush timer, extracted from the verbatim copy
+// that lived in executeStreamPhase + the three sentinel summaries (4 sites).
+// Each site streamed deltas into a local `accumulated`/`state.accumulated`
+// string and threw an UPDATE at the row at most once per DB_FLUSH_INTERVAL_MS
+// to bound write rate under heavy streaming.
+//
+// The accumulated string stays owned by the caller (stream-phase keeps it on
+// the shared StreamPhaseState; the summaries keep a local) — the flusher reads
+// it through a `getContent` thunk at fire time, snapshotting the latest value
+// exactly as the inline `const snapshot = accumulated` did. No final flush is
+// performed on drain (matches the originals): every caller writes the full
+// content itself in its terminal UPDATE, so drain only cancels the pending
+// timer and awaits whatever write is already chained.
+
+import type { Sql } from '../../db.js';
+import { DB_FLUSH_INTERVAL_MS } from './types.js';
+
+export interface ContentFlusher {
+  // Arm a debounced flush. No-op if one is already pending (the in-flight timer
+  // will pick up the latest content via getContent when it fires).
+  scheduleFlush: () => void;
+  // Cancel any pending timer and await the in-flight write chain. Does NOT
+  // perform a final flush — the caller's terminal UPDATE owns the final write.
+  drain: () => Promise<void>;
+}
+
+export function createContentFlusher(
+  sql: Sql,
+  messageId: string,
+  getContent: () => string,
+  intervalMs: number = DB_FLUSH_INTERVAL_MS,
+): ContentFlusher {
+  let pendingFlushTimer: NodeJS.Timeout | null = null;
+  let flushPromise: Promise<unknown> = Promise.resolve();
+
+  const flushNow = () => {
+    if (pendingFlushTimer) {
+      clearTimeout(pendingFlushTimer);
+      pendingFlushTimer = null;
+    }
+    const snapshot = getContent();
+    flushPromise = flushPromise.then(() =>
+      sql`UPDATE messages SET content = ${snapshot} WHERE id = ${messageId}`
+    );
+  };
+
+  const scheduleFlush = () => {
+    if (pendingFlushTimer) return;
+    pendingFlushTimer = setTimeout(() => {
+      pendingFlushTimer = null;
+      flushNow();
+    }, intervalMs);
+  };
+
+  const drain = async () => {
+    if (pendingFlushTimer) {
+      clearTimeout(pendingFlushTimer);
+      pendingFlushTimer = null;
+    }
+    await flushPromise;
+  };
+
+  return { scheduleFlush, drain };
+}

apps/server/src/services/inference/error-handler.ts

@@ -10,7 +10,7 @@ import { maybeFlagForCompaction } from './payload.js';
 import { insertParts, partsFromAssistantMessage } from './parts.js';
 import type { PartInsert } from './parts.js';
 import { stripToolMarkup } from './tool-call-parser.js';
-import type { InferenceContext, StreamResult, TurnArgs } from './turn.js';
+import type { InferenceContext, StreamResult, TurnArgs } from './types.js';
 
 export async function handleAbortOrError(
   ctx: InferenceContext,
@@ -95,6 +95,90 @@ export async function handleAbortOrError(
   }
 }
 
+// P5: the success-finalize atom shared by the wrap-up summaries
+// (sentinel-summaries.ts) and the synthesis pass (synthesisPipeline.ts). Both
+// previously hand-rolled this exact ceremony — n_ctx lookup, the complete
+// UPDATE (content/status/tokens/ctx/ctx_max/finished_at; NO model column), and
+// the message_complete frame with the full token fields. Single-sourcing it
+// means a message_complete frame-contract change lands in one place instead of
+// silently skipping the summary/synthesis paths.
+//
+// `beforeComplete` runs AFTER the UPDATE and BEFORE the message_complete frame
+// — synthesis uses it to write its kind='synthesis' part in the original order
+// (UPDATE → insertParts → message_complete), preserving timing exactly.
+//
+// NOTE: finalizeCompletion does NOT use this — it additionally writes the
+// `model` column, the text/reasoning/html_artifact parts, the compaction flag,
+// and the session_updated bump, which this atom deliberately omits (the summary
+// and synthesis paths handle those — or not — themselves).
+export async function finalizeStreamedRow(
+  ctx: InferenceContext,
+  opts: {
+    sessionId: string;
+    chatId: string;
+    messageId: string;
+    model: string;
+    content: string;
+    completionTokens: number | null;
+    promptTokens: number | null;
+    startedAt: string | null;
+    beforeComplete?: () => Promise<void>;
+  },
+): Promise<void> {
+  // v1.11.3: see executeToolPhase for the rationale.
+  const mctx = await modelContext.getModelContext(opts.model);
+  const nCtx = mctx?.n_ctx ?? null;
+  const [updated] = await ctx.sql<
+    { tokens_used: number | null; ctx_used: number | null; ctx_max: number | null; finished_at: string | null }[]
+  >`
+    UPDATE messages
+    SET content = ${opts.content},
+        status = 'complete',
+        tokens_used = ${opts.completionTokens},
+        ctx_used = ${opts.promptTokens},
+        ctx_max = ${nCtx},
+        finished_at = clock_timestamp()
+    WHERE id = ${opts.messageId}
+    RETURNING tokens_used, ctx_used, ctx_max, finished_at
+  `;
+  if (opts.beforeComplete) await opts.beforeComplete();
+  ctx.publish(opts.sessionId, {
+    type: 'message_complete',
+    message_id: opts.messageId,
+    chat_id: opts.chatId,
+    tokens_used: updated?.tokens_used ?? null,
+    ctx_used: updated?.ctx_used ?? null,
+    ctx_max: updated?.ctx_max ?? null,
+    started_at: opts.startedAt,
+    finished_at: updated?.finished_at ?? null,
+    model: opts.model,
+  });
+}
+
+// P5: minimal empty-finalize for the mistake-escalate path. The escalate
+// branch in runAssistantTurn stops the turn cap-hit-style; the next assistant
+// row is still 'streaming', so it's finalized as an empty complete row (no
+// tokens, no parts, no session bump — the escalate branch handles the sentinel
+// + chat_status itself). Centralizing the status-column write + message_complete
+// frame here keeps it next to the other finalize paths so a status-column
+// change is found in one place.
+export async function finalizeEmpty(
+  ctx: InferenceContext,
+  args: TurnArgs,
+): Promise<void> {
+  const { sessionId, chatId, assistantMessageId } = args;
+  await ctx.sql`
+    UPDATE messages
+    SET content = '', status = 'complete', finished_at = clock_timestamp()
+    WHERE id = ${assistantMessageId}
+  `;
+  ctx.publish(sessionId, {
+    type: 'message_complete',
+    message_id: assistantMessageId,
+    chat_id: chatId,
+  });
+}
+
 export async function finalizeCompletion(
   ctx: InferenceContext,
   args: TurnArgs,

apps/server/src/services/inference/index.ts

@@ -7,26 +7,17 @@
 export {
   createInferenceRunner,
   MAX_STEPS,
-  runAssistantTurn,
   runInference,
 } from './turn.js';
+// P5: the shared pipeline types moved from turn.ts to types.ts (breaking the
+// hub-and-leaf near-cycle). Re-exported here so the public surface is unchanged.
 export type {
   FramePublisher,
   InferenceContext,
   InferenceFrame,
   StreamResult,
   TurnArgs,
-} from './turn.js';
+} from './types.js';
 export type { ToolPhaseResult } from './tool-phase.js';
 export { detectDoomLoop, DOOM_LOOP_THRESHOLD } from './sentinels.js';
-export {
-  detectMistakePattern,
-  freshMistakeState,
-  recordStep,
-  MISTAKE_THRESHOLD,
-  MISTAKE_RECOVERY_NOTE,
-} from './mistake-tracker.js';
-export type { FailureKind, MistakeState } from './mistake-tracker.js';
 export { buildMessagesPayload } from './payload.js';
-export { generateToolUseSummary } from './tool-summaries.js';
-export type { ToolInfo } from './tool-summaries.js';

apps/server/src/services/inference/parts.ts

@@ -1,11 +1,10 @@
 import type { Sql } from '../../db.js';
 import type { ToolCall, ToolResult } from '../../types/api.js';
 
-// v1.13.0: dual-write helper. Every site that writes the legacy
-// messages.tool_calls / messages.tool_results JSON columns calls into here
-// to mirror the same data into message_parts rows. Reads still go to the
-// JSON columns; the swap to parts-as-source-of-truth happens in a later
-// v1.13 dispatch alongside the AI SDK streamText migration.
+// v1.13.0: message_parts write helpers. v1.13.20: legacy tool_calls/
+// tool_results JSON columns dropped; message_parts is the sole source of
+// truth. All writes go through insertParts / partsFromAssistantMessage /
+// partsFromToolMessage. Reads use the messages_with_parts view.
 
 // v1.13.13: 'synthesis' added. Schema CHECK constraint is updated in lockstep
 // (schema.sql adds 'synthesis' to message_parts_kind_chk on startup). The

apps/server/src/services/inference/payload.ts

@@ -10,7 +10,8 @@ import * as compaction from '../compaction.js';
 import { buildSystemPromptWithFingerprint } from '../system-prompt.js';
 import { isAnySentinel } from './sentinels.js';
 import { PRUNE_TRIGGER_TOKENS, prune } from './prune.js';
-import type { InferenceContext } from './turn.js';
+import type { InferenceContext } from './types.js';
+import { INFERENCE_MESSAGE_COLUMNS } from '../message-columns.js';
 
 export interface OpenAiMessage {
   role: 'system' | 'user' | 'assistant' | 'tool';
@@ -205,9 +206,7 @@ export async function loadContext(
   // v1.13.1-C: also pull reasoning_parts so assistant messages from
   // reasoning models can be replayed with their reasoning context preserved.
   const history = await sql<Message[]>`
-    SELECT id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq,
-           tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata,
-           reasoning_parts
+    SELECT ${sql.unsafe(INFERENCE_MESSAGE_COLUMNS)}
     FROM messages_with_parts
     WHERE chat_id = ${chatId} AND compacted_at IS NULL
     ORDER BY created_at ASC, id ASC

apps/server/src/services/inference/sentinel-summaries.ts

@@ -5,16 +5,16 @@ import type {
   Project,
   Session,
 } from '../../types/api.js';
-import * as modelContext from '../model-context.js';
 import { buildMessagesPayload } from './payload.js';
 import { DOOM_LOOP_THRESHOLD } from './sentinels.js';
-import { streamCompletion } from './stream-phase.js';
-import { DB_FLUSH_INTERVAL_MS } from './types.js';
+import { streamCompletion, samplerOptsFromAgent } from './stream-phase.js';
+import { createContentFlusher } from './content-flusher.js';
+import { finalizeStreamedRow } from './error-handler.js';
 import type {
   InferenceContext,
   StreamResult,
   TurnArgs,
-} from './turn.js';
+} from './types.js';
 
 // Synthetic system note appended to the cap-hit summary call. Verbatim from
 // the v1.8.2 spec — do not paraphrase: the model is more reliable when the
@@ -25,21 +25,50 @@ const CAP_HIT_SUMMARY_NOTE = (limit: number) =>
 const DOOM_LOOP_NOTE = (name: string) =>
   `You called ${name} with the same arguments ${DOOM_LOOP_THRESHOLD} times in a row. Stop calling it. Produce the best answer you can with what you have.`;
 
-export async function runCapHitSummary(
+// v1.14.0: step-cap wrap-up note. Names the step limit rather than the tool
+// budget. The sentinel reuses metadata.kind = 'cap_hit' so the frontend
+// CapHitSentinel component renders it without changes.
+const STEP_CAP_NOTE = (steps: number, cap: number) =>
+  `You've reached the step limit (${steps}/${cap} steps). Produce the best answer you can with what you have. Do not call more tools.`;
+
+// P5: the ONE generic wrap-up flow shared by the three sentinel summaries
+// (cap-hit, doom-loop, step-cap). Each reuses the in-flight assistant slot to
+// stream a short tools-disabled summary, finalizes via the same 3-outcome
+// branch (complete / cancelled / failed), bumps the session, then drops a
+// sentinel and the chat_status. The three differ only in:
+//   - `note`: the synthetic system instruction appended to the summary call.
+//   - `errorText`: the fallback used in the failed-status metadata + error frame.
+//   - sentinel timing: cap-hit inserts BEFORE the stream (`beforeStream`);
+//     doom-loop + step-cap insert AFTER the session bump (`afterSession`).
+//   - `logMsg` / `logFields`: per-kind log line + extra fields.
+// All three use error_reason / chat_status reason = 'summary_after_cap_failed'
+// (doom-loop reuses it deliberately — the user-visible failure mode is the
+// same "model gave up mid-summary"; the ErrorReason union is shared and the UI
+// surfaces a generic "summary failed" line for every sentinel path).
+interface WrapUpOpts {
+  note: string;
+  errorText: string;
+  logMsg: string;
+  logFields: Record<string, unknown>;
+  beforeStream?: () => Promise<void>;
+  afterSession?: () => Promise<void>;
+}
+
+async function runWrapUpSummary(
   ctx: InferenceContext,
   args: TurnArgs,
   session: Session,
   project: Project,
   history: Message[],
   agent: Agent | null,
-  budget: number,
+  opts: WrapUpOpts,
 ): Promise<void> {
   const { sessionId, chatId, assistantMessageId, signal } = args;
 
-  await insertCapHitSentinel(ctx, sessionId, chatId, agent, budget);
+  if (opts.beforeStream) await opts.beforeStream();
 
   const messages = await buildMessagesPayload(session, project, history, agent, ctx.log);
-  messages.push({ role: 'system', content: CAP_HIT_SUMMARY_NOTE(budget) });
+  messages.push({ role: 'system', content: opts.note });
 
   const startedRow = await ctx.sql<{ started_at: string }[]>`
     UPDATE messages
@@ -57,25 +86,7 @@ export async function runCapHitSummary(
   });
 
   let accumulated = '';
-  let pendingFlushTimer: NodeJS.Timeout | null = null;
-  let flushPromise: Promise<unknown> = Promise.resolve();
-  const flushNow = () => {
-    if (pendingFlushTimer) {
-      clearTimeout(pendingFlushTimer);
-      pendingFlushTimer = null;
-    }
-    const snapshot = accumulated;
-    flushPromise = flushPromise.then(() =>
-      ctx.sql`UPDATE messages SET content = ${snapshot} WHERE id = ${assistantMessageId}`
-    );
-  };
-  const scheduleFlush = () => {
-    if (pendingFlushTimer) return;
-    pendingFlushTimer = setTimeout(() => {
-      pendingFlushTimer = null;
-      flushNow();
-    }, DB_FLUSH_INTERVAL_MS);
-  };
+  const flusher = createContentFlusher(ctx.sql, assistantMessageId, () => accumulated);
 
   let summaryOk = false;
   let summarySoftCancelled = false;
@@ -86,7 +97,7 @@ export async function runCapHitSummary(
       ctx,
       session.model,
       messages,
-      { tools: null, temperature: agent?.temperature, top_p: agent?.top_p ?? undefined, top_k: agent?.top_k ?? undefined, min_p: agent?.min_p ?? undefined, presence_penalty: agent?.presence_penalty ?? undefined, top_n_sigma: agent?.top_n_sigma ?? undefined, dry_multiplier: agent?.dry_multiplier ?? undefined, dry_base: agent?.dry_base ?? undefined, dry_allowed_length: agent?.dry_allowed_length ?? undefined, dry_penalty_last_n: agent?.dry_penalty_last_n ?? undefined },
+      { tools: null, ...samplerOptsFromAgent(agent) },
       (delta) => {
         accumulated += delta;
         ctx.publish(sessionId, {
@@ -95,7 +106,7 @@ export async function runCapHitSummary(
           chat_id: chatId,
           content: delta,
         });
-        scheduleFlush();
+        flusher.scheduleFlush();
       },
       undefined,
       signal,
@@ -108,44 +119,23 @@ export async function runCapHitSummary(
       summaryError = err instanceof Error ? err.message : String(err);
     }
   } finally {
-    if (pendingFlushTimer) {
-      clearTimeout(pendingFlushTimer);
-      pendingFlushTimer = null;
-    }
-    await flushPromise;
+    await flusher.drain();
   }
 
-  // Finalize the summary message based on the three outcomes. The sentinel
-  // is inserted regardless so the user always has the Continue affordance —
-  // even on a partial / failed summary the chat history shows where the
-  // budget was hit.
+  // Finalize the summary message based on the three outcomes. The sentinel is
+  // inserted regardless (before or after, per opts) so the user always has the
+  // appropriate affordance — even on a partial / failed summary the chat
+  // history shows where the loop stopped.
   if (summaryOk && result) {
-    // v1.11.3: see executeToolPhase for the rationale.
-    const mctx = await modelContext.getModelContext(session.model);
-    const nCtx = mctx?.n_ctx ?? null;
-    const [updated] = await ctx.sql<
-      { tokens_used: number | null; ctx_used: number | null; ctx_max: number | null; finished_at: string | null }[]
-    >`
-      UPDATE messages
-      SET content = ${result.content},
-          status = 'complete',
-          tokens_used = ${result.completionTokens},
-          ctx_used = ${result.promptTokens},
-          ctx_max = ${nCtx},
-          finished_at = clock_timestamp()
-      WHERE id = ${assistantMessageId}
-      RETURNING tokens_used, ctx_used, ctx_max, finished_at
-    `;
-    ctx.publish(sessionId, {
-      type: 'message_complete',
-      message_id: assistantMessageId,
-      chat_id: chatId,
-      tokens_used: updated?.tokens_used ?? null,
-      ctx_used: updated?.ctx_used ?? null,
-      ctx_max: updated?.ctx_max ?? null,
-      started_at: startedAt,
-      finished_at: updated?.finished_at ?? null,
+    await finalizeStreamedRow(ctx, {
+      sessionId,
+      chatId,
+      messageId: assistantMessageId,
       model: session.model,
+      content: result.content,
+      completionTokens: result.completionTokens,
+      promptTokens: result.promptTokens,
+      startedAt,
     });
   } else if (summarySoftCancelled) {
     await ctx.sql`
@@ -164,7 +154,7 @@ export async function runCapHitSummary(
     const errMeta: MessageMetadata = {
       kind: 'error',
       error_reason: 'summary_after_cap_failed',
-      error_text: summaryError ?? 'summary failed',
+      error_text: summaryError ?? opts.errorText,
     };
     await ctx.sql`
       UPDATE messages
@@ -178,7 +168,7 @@ export async function runCapHitSummary(
       type: 'error',
       message_id: assistantMessageId,
       chat_id: chatId,
-      error: summaryError ?? 'summary failed',
+      error: summaryError ?? opts.errorText,
       reason: 'summary_after_cap_failed',
     });
   }
@@ -197,11 +187,11 @@ export async function runCapHitSummary(
     updated_at: sessRow!.updated_at,
   });
 
+  if (opts.afterSession) await opts.afterSession();
+
   // Status frame fires last so the dot color reflects the terminal state.
   // Success → idle, abort → idle (user-driven stop), error → error+reason.
-  if (summaryOk) {
-    ctx.publishUser({ type: 'chat_status', chat_id: chatId, status: 'idle', at: new Date().toISOString() });
-  } else if (summarySoftCancelled) {
+  if (summaryOk || summarySoftCancelled) {
     ctx.publishUser({ type: 'chat_status', chat_id: chatId, status: 'idle', at: new Date().toISOString() });
   } else {
     ctx.publishUser({
@@ -214,11 +204,113 @@ export async function runCapHitSummary(
   }
 
   ctx.log.info(
-    { sessionId, chatId, assistantMessageId, budget, summaryOk, summaryCancelled: summarySoftCancelled },
-    'inference cap-hit summary finished',
+    { sessionId, chatId, assistantMessageId, ...opts.logFields, summaryOk, summaryCancelled: summarySoftCancelled },
+    opts.logMsg,
   );
 }
 
+// v1.8.2: cap-hit summary flow. Called instead of erroring when the loop hits
+// its budget. The cap-hit sentinel is inserted FIRST (before the summary
+// stream) so the UI shows the Continue affordance regardless of summary
+// outcome.
+export async function runCapHitSummary(
+  ctx: InferenceContext,
+  args: TurnArgs,
+  session: Session,
+  project: Project,
+  history: Message[],
+  agent: Agent | null,
+  budget: number,
+): Promise<void> {
+  await runWrapUpSummary(ctx, args, session, project, history, agent, {
+    note: CAP_HIT_SUMMARY_NOTE(budget),
+    errorText: 'summary failed',
+    logMsg: 'inference cap-hit summary finished',
+    logFields: { budget },
+    beforeStream: () => insertCapHitSentinel(ctx, args.sessionId, args.chatId, agent, budget),
+  });
+}
+
+// v1.11.6: doom-loop wrap-up. The doom-loop sentinel is inserted AFTER the
+// session bump (no Continue affordance — continuing would re-trigger the loop
+// with the same tools available; the user needs to restate or switch agents).
+export async function runDoomLoopSummary(
+  ctx: InferenceContext,
+  args: TurnArgs,
+  session: Session,
+  project: Project,
+  history: Message[],
+  agent: Agent | null,
+  loop: { name: string; args: Record<string, unknown> },
+): Promise<void> {
+  await runWrapUpSummary(ctx, args, session, project, history, agent, {
+    note: DOOM_LOOP_NOTE(loop.name),
+    errorText: 'doom-loop summary failed',
+    logMsg: 'inference doom-loop summary finished',
+    logFields: { loopedTool: loop.name },
+    afterSession: () => insertDoomLoopSentinel(ctx, args.sessionId, args.chatId, loop),
+  });
+}
+
+// v1.14.0: step-cap wrap-up. Reuses the cap_hit sentinel (inserted AFTER the
+// session bump) so the frontend CapHitSentinel component renders it without
+// changes; the content text distinguishes step cap from budget.
+export async function runStepCapSummary(
+  ctx: InferenceContext,
+  args: TurnArgs,
+  session: Session,
+  project: Project,
+  history: Message[],
+  agent: Agent | null,
+  steps: number,
+  cap: number,
+): Promise<void> {
+  await runWrapUpSummary(ctx, args, session, project, history, agent, {
+    note: STEP_CAP_NOTE(steps, cap),
+    errorText: 'step-cap summary failed',
+    logMsg: 'inference step-cap summary finished',
+    logFields: { steps, cap },
+    afterSession: () => insertCapHitSentinel(ctx, args.sessionId, args.chatId, agent, cap),
+  });
+}
+
+// P5: the ONE INSERT + message_started → delta → message_complete frame
+// sequence shared by every sentinel inserter. The sentinel row is a
+// role='system', status='complete' message; the static content rides the same
+// streaming-frame path useSessionStream's reducer uses for assistant messages
+// (the delta carries the full text in one chunk).
+async function insertSentinel(
+  ctx: InferenceContext,
+  sessionId: string,
+  chatId: string,
+  metadata: MessageMetadata,
+  content: string,
+): Promise<void> {
+  const [row] = await ctx.sql<{ id: string }[]>`
+    INSERT INTO messages (session_id, chat_id, role, content, status, created_at, metadata)
+    VALUES (${sessionId}, ${chatId}, 'system', ${content}, 'complete', clock_timestamp(), ${ctx.sql.json(metadata as never)})
+    RETURNING id
+  `;
+  ctx.publish(sessionId, {
+    type: 'message_started',
+    message_id: row!.id,
+    chat_id: chatId,
+    role: 'system',
+  });
+  ctx.publish(sessionId, {
+    type: 'delta',
+    message_id: row!.id,
+    chat_id: chatId,
+    content,
+  });
+  ctx.publish(sessionId, {
+    type: 'message_complete',
+    message_id: row!.id,
+    chat_id: chatId,
+    metadata,
+  });
+}
+
 async function insertCapHitSentinel(
   ctx: InferenceContext,
   sessionId: string,
@@ -246,430 +338,7 @@ async function insertCapHitSentinel(
     can_continue: canContinue,
   };
   const content = `Reached tool budget (${budget}/${budget}). Continue to extend.`;
-
-  const [row] = await ctx.sql<{ id: string }[]>`
-    INSERT INTO messages (session_id, chat_id, role, content, status, created_at, metadata)
-    VALUES (${sessionId}, ${chatId}, 'system', ${content}, 'complete', clock_timestamp(), ${ctx.sql.json(metadata as never)})
-    RETURNING id
-  `;
-
-  // The sentinel content is static, but we still walk the standard frame
-  // sequence (started → delta → complete) so useSessionStream's reducer
-  // appends it via the same path it uses for streaming assistant messages.
-  // The delta carries the full text in one chunk.
-  ctx.publish(sessionId, {
-    type: 'message_started',
-    message_id: row!.id,
-    chat_id: chatId,
-    role: 'system',
-  });
-  ctx.publish(sessionId, {
-    type: 'delta',
-    message_id: row!.id,
-    chat_id: chatId,
-    content,
-  });
-  ctx.publish(sessionId, {
-    type: 'message_complete',
-    message_id: row!.id,
-    chat_id: chatId,
-    metadata,
-  });
-}
-
-// v1.11.6: doom-loop wrap-up. Mirrors runCapHitSummary structurally — same
-// in-flight-slot reuse, same tools-disabled streaming-summary call, same
-// post-finalize sentinel insert + chat_status drop. Differences:
-//   - synthetic note text comes from DOOM_LOOP_NOTE (names the looping tool)
-//   - sentinel metadata is { kind: 'doom_loop', tool_name, args, threshold }
-//     and has no Continue affordance (manual retry would just re-loop)
-//   - chat_status error path uses reason: 'doom_loop_summary_failed'
-// Kept as a clone rather than refactored into a shared helper because the
-// two summary paths still differ in error reason + sentinel shape; a third
-// sentinel would justify factoring out runWrapUpSummary(opts).
-export async function runDoomLoopSummary(
-  ctx: InferenceContext,
-  args: TurnArgs,
-  session: Session,
-  project: Project,
-  history: Message[],
-  agent: Agent | null,
-  loop: { name: string; args: Record<string, unknown> },
-): Promise<void> {
-  const { sessionId, chatId, assistantMessageId, signal } = args;
-
-  const messages = await buildMessagesPayload(session, project, history, agent, ctx.log);
-  messages.push({ role: 'system', content: DOOM_LOOP_NOTE(loop.name) });
-
-  const startedRow = await ctx.sql<{ started_at: string }[]>`
-    UPDATE messages
-    SET started_at = clock_timestamp()
-    WHERE id = ${assistantMessageId}
-    RETURNING started_at
-  `;
-  const startedAt = startedRow[0]?.started_at ?? null;
-
-  ctx.publish(sessionId, {
-    type: 'message_started',
-    message_id: assistantMessageId,
-    chat_id: chatId,
-    role: 'assistant',
-  });
-
-  let accumulated = '';
-  let pendingFlushTimer: NodeJS.Timeout | null = null;
-  let flushPromise: Promise<unknown> = Promise.resolve();
-  const flushNow = () => {
-    if (pendingFlushTimer) {
-      clearTimeout(pendingFlushTimer);
-      pendingFlushTimer = null;
-    }
-    const snapshot = accumulated;
-    flushPromise = flushPromise.then(() =>
-      ctx.sql`UPDATE messages SET content = ${snapshot} WHERE id = ${assistantMessageId}`
-    );
-  };
-  const scheduleFlush = () => {
-    if (pendingFlushTimer) return;
-    pendingFlushTimer = setTimeout(() => {
-      pendingFlushTimer = null;
-      flushNow();
-    }, DB_FLUSH_INTERVAL_MS);
-  };
-
-  let summaryOk = false;
-  let summarySoftCancelled = false;
-  let summaryError: string | null = null;
-  let result: StreamResult | null = null;
-  try {
-    result = await streamCompletion(
-      ctx,
-      session.model,
-      messages,
-      { tools: null, temperature: agent?.temperature, top_p: agent?.top_p ?? undefined, top_k: agent?.top_k ?? undefined, min_p: agent?.min_p ?? undefined, presence_penalty: agent?.presence_penalty ?? undefined, top_n_sigma: agent?.top_n_sigma ?? undefined, dry_multiplier: agent?.dry_multiplier ?? undefined, dry_base: agent?.dry_base ?? undefined, dry_allowed_length: agent?.dry_allowed_length ?? undefined, dry_penalty_last_n: agent?.dry_penalty_last_n ?? undefined },
-      (delta) => {
-        accumulated += delta;
-        ctx.publish(sessionId, {
-          type: 'delta',
-          message_id: assistantMessageId,
-          chat_id: chatId,
-          content: delta,
-        });
-        scheduleFlush();
-      },
-      undefined,
-      signal,
-    );
-    summaryOk = true;
-  } catch (err) {
-    if (err instanceof Error && err.name === 'AbortError') {
-      summarySoftCancelled = true;
-    } else {
-      summaryError = err instanceof Error ? err.message : String(err);
-    }
-  } finally {
-    if (pendingFlushTimer) {
-      clearTimeout(pendingFlushTimer);
-      pendingFlushTimer = null;
-    }
-    await flushPromise;
-  }
-
-  if (summaryOk && result) {
-    const mctx = await modelContext.getModelContext(session.model);
-    const nCtx = mctx?.n_ctx ?? null;
-    const [updated] = await ctx.sql<
-      { tokens_used: number | null; ctx_used: number | null; ctx_max: number | null; finished_at: string | null }[]
-    >`
-      UPDATE messages
-      SET content = ${result.content},
-          status = 'complete',
-          tokens_used = ${result.completionTokens},
-          ctx_used = ${result.promptTokens},
-          ctx_max = ${nCtx},
-          finished_at = clock_timestamp()
-      WHERE id = ${assistantMessageId}
-      RETURNING tokens_used, ctx_used, ctx_max, finished_at
-    `;
-    ctx.publish(sessionId, {
-      type: 'message_complete',
-      message_id: assistantMessageId,
-      chat_id: chatId,
-      tokens_used: updated?.tokens_used ?? null,
-      ctx_used: updated?.ctx_used ?? null,
-      ctx_max: updated?.ctx_max ?? null,
-      started_at: startedAt,
-      finished_at: updated?.finished_at ?? null,
-      model: session.model,
-    });
-  } else if (summarySoftCancelled) {
-    await ctx.sql`
-      UPDATE messages
-      SET content = ${accumulated},
-          status = 'cancelled',
-          finished_at = clock_timestamp()
-      WHERE id = ${assistantMessageId}
-    `;
-    ctx.publish(sessionId, {
-      type: 'message_complete',
-      message_id: assistantMessageId,
-      chat_id: chatId,
-    });
-  } else {
-    // Doom-loop summary failure reuses the existing summary_after_cap_failed
-    // error reason — the ErrorReason union is shared between sentinel paths
-    // and the UI surfaces a generic "summary failed" line for both. We don't
-    // add a new reason code because the user-visible failure mode is the
-    // same (model gave up mid-summary). Sentinel below still fires.
-    const errMeta: MessageMetadata = {
-      kind: 'error',
-      error_reason: 'summary_after_cap_failed',
-      error_text: summaryError ?? 'doom-loop summary failed',
-    };
-    await ctx.sql`
-      UPDATE messages
-      SET content = ${accumulated},
-          status = 'failed',
-          finished_at = clock_timestamp(),
-          metadata = ${ctx.sql.json(errMeta as never)}
-      WHERE id = ${assistantMessageId}
-    `;
-    ctx.publish(sessionId, {
-      type: 'error',
-      message_id: assistantMessageId,
-      chat_id: chatId,
-      error: summaryError ?? 'doom-loop summary failed',
-      reason: 'summary_after_cap_failed',
-    });
-  }
-
-  const [sessRow] = await ctx.sql<{ project_id: string; name: string; updated_at: string }[]>`
-    UPDATE sessions SET updated_at = clock_timestamp()
-    WHERE id = ${sessionId}
-    RETURNING project_id, name, updated_at
-  `;
-  ctx.publishUser({
-    type: 'session_updated',
-    session_id: sessionId,
-    project_id: sessRow!.project_id,
-    name: sessRow!.name,
-    updated_at: sessRow!.updated_at,
-  });
-
-  await insertDoomLoopSentinel(ctx, sessionId, chatId, loop);
-
-  if (summaryOk || summarySoftCancelled) {
-    ctx.publishUser({ type: 'chat_status', chat_id: chatId, status: 'idle', at: new Date().toISOString() });
-  } else {
-    ctx.publishUser({
-      type: 'chat_status',
-      chat_id: chatId,
-      status: 'error',
-      at: new Date().toISOString(),
-      reason: 'summary_after_cap_failed',
-    });
-  }
-
-  ctx.log.info(
-    { sessionId, chatId, assistantMessageId, loopedTool: loop.name, summaryOk, summaryCancelled: summarySoftCancelled },
-    'inference doom-loop summary finished',
-  );
-}
-
-// v1.14.0: step-cap wrap-up. Mirrors runCapHitSummary structurally — same
-// in-flight-slot reuse, same tools-disabled streaming-summary call, same
-// post-finalize sentinel insert + chat_status drop. Difference: the note
-// text names the step limit rather than the tool budget. Sentinel reuses
-// metadata.kind = 'cap_hit' so the frontend CapHitSentinel component
-// renders it without changes.
-const STEP_CAP_NOTE = (steps: number, cap: number) =>
-  `You've reached the step limit (${steps}/${cap} steps). Produce the best answer you can with what you have. Do not call more tools.`;
-
-export async function runStepCapSummary(
-  ctx: InferenceContext,
-  args: TurnArgs,
-  session: Session,
-  project: Project,
-  history: Message[],
-  agent: Agent | null,
-  steps: number,
-  cap: number,
-): Promise<void> {
-  const { sessionId, chatId, assistantMessageId, signal } = args;
-
-  const messages = await buildMessagesPayload(session, project, history, agent, ctx.log);
-  messages.push({ role: 'system', content: STEP_CAP_NOTE(steps, cap) });
-
-  const startedRow = await ctx.sql<{ started_at: string }[]>`
-    UPDATE messages
-    SET started_at = clock_timestamp()
-    WHERE id = ${assistantMessageId}
-    RETURNING started_at
-  `;
-  const startedAt = startedRow[0]?.started_at ?? null;
-
-  ctx.publish(sessionId, {
-    type: 'message_started',
-    message_id: assistantMessageId,
-    chat_id: chatId,
-    role: 'assistant',
-  });
-
-  let accumulated = '';
-  let pendingFlushTimer: NodeJS.Timeout | null = null;
-  let flushPromise: Promise<unknown> = Promise.resolve();
-  const flushNow = () => {
-    if (pendingFlushTimer) {
-      clearTimeout(pendingFlushTimer);
-      pendingFlushTimer = null;
-    }
-    const snapshot = accumulated;
-    flushPromise = flushPromise.then(() =>
-      ctx.sql`UPDATE messages SET content = ${snapshot} WHERE id = ${assistantMessageId}`
-    );
-  };
-  const scheduleFlush = () => {
-    if (pendingFlushTimer) return;
-    pendingFlushTimer = setTimeout(() => {
-      pendingFlushTimer = null;
-      flushNow();
-    }, DB_FLUSH_INTERVAL_MS);
-  };
-
-  let summaryOk = false;
-  let summarySoftCancelled = false;
-  let summaryError: string | null = null;
-  let result: StreamResult | null = null;
-  try {
-    result = await streamCompletion(
-      ctx,
-      session.model,
-      messages,
-      { tools: null, temperature: agent?.temperature, top_p: agent?.top_p ?? undefined, top_k: agent?.top_k ?? undefined, min_p: agent?.min_p ?? undefined, presence_penalty: agent?.presence_penalty ?? undefined, top_n_sigma: agent?.top_n_sigma ?? undefined, dry_multiplier: agent?.dry_multiplier ?? undefined, dry_base: agent?.dry_base ?? undefined, dry_allowed_length: agent?.dry_allowed_length ?? undefined, dry_penalty_last_n: agent?.dry_penalty_last_n ?? undefined },
-      (delta) => {
-        accumulated += delta;
-        ctx.publish(sessionId, {
-          type: 'delta',
-          message_id: assistantMessageId,
-          chat_id: chatId,
-          content: delta,
-        });
-        scheduleFlush();
-      },
-      undefined,
-      signal,
-    );
-    summaryOk = true;
-  } catch (err) {
-    if (err instanceof Error && err.name === 'AbortError') {
-      summarySoftCancelled = true;
-    } else {
-      summaryError = err instanceof Error ? err.message : String(err);
-    }
-  } finally {
-    if (pendingFlushTimer) {
-      clearTimeout(pendingFlushTimer);
-      pendingFlushTimer = null;
-    }
-    await flushPromise;
-  }
-
-  if (summaryOk && result) {
-    const mctx = await modelContext.getModelContext(session.model);
-    const nCtx = mctx?.n_ctx ?? null;
-    const [updated] = await ctx.sql<
-      { tokens_used: number | null; ctx_used: number | null; ctx_max: number | null; finished_at: string | null }[]
-    >`
-      UPDATE messages
-      SET content = ${result.content},
-          status = 'complete',
-          tokens_used = ${result.completionTokens},
-          ctx_used = ${result.promptTokens},
-          ctx_max = ${nCtx},
-          finished_at = clock_timestamp()
-      WHERE id = ${assistantMessageId}
-      RETURNING tokens_used, ctx_used, ctx_max, finished_at
-    `;
-    ctx.publish(sessionId, {
-      type: 'message_complete',
-      message_id: assistantMessageId,
-      chat_id: chatId,
-      tokens_used: updated?.tokens_used ?? null,
-      ctx_used: updated?.ctx_used ?? null,
-      ctx_max: updated?.ctx_max ?? null,
-      started_at: startedAt,
-      finished_at: updated?.finished_at ?? null,
-      model: session.model,
-    });
-  } else if (summarySoftCancelled) {
-    await ctx.sql`
-      UPDATE messages
-      SET content = ${accumulated},
-          status = 'cancelled',
-          finished_at = clock_timestamp()
-      WHERE id = ${assistantMessageId}
-    `;
-    ctx.publish(sessionId, {
-      type: 'message_complete',
-      message_id: assistantMessageId,
-      chat_id: chatId,
-    });
-  } else {
-    const errMeta: MessageMetadata = {
-      kind: 'error',
-      error_reason: 'summary_after_cap_failed',
-      error_text: summaryError ?? 'step-cap summary failed',
-    };
-    await ctx.sql`
-      UPDATE messages
-      SET content = ${accumulated},
-          status = 'failed',
-          finished_at = clock_timestamp(),
-          metadata = ${ctx.sql.json(errMeta as never)}
-      WHERE id = ${assistantMessageId}
-    `;
-    ctx.publish(sessionId, {
-      type: 'error',
-      message_id: assistantMessageId,
-      chat_id: chatId,
-      error: summaryError ?? 'step-cap summary failed',
-      reason: 'summary_after_cap_failed',
-    });
-  }
-
-  const [sessRow] = await ctx.sql<{ project_id: string; name: string; updated_at: string }[]>`
-    UPDATE sessions SET updated_at = clock_timestamp()
-    WHERE id = ${sessionId}
-    RETURNING project_id, name, updated_at
-  `;
-  ctx.publishUser({
-    type: 'session_updated',
-    session_id: sessionId,
-    project_id: sessRow!.project_id,
-    name: sessRow!.name,
-    updated_at: sessRow!.updated_at,
-  });
-
-  // Reuse cap_hit sentinel so the frontend CapHitSentinel component renders
-  // it without changes. The content text distinguishes step cap from budget.
-  await insertCapHitSentinel(ctx, sessionId, chatId, agent, cap);
-
-  if (summaryOk || summarySoftCancelled) {
-    ctx.publishUser({ type: 'chat_status', chat_id: chatId, status: 'idle', at: new Date().toISOString() });
-  } else {
-    ctx.publishUser({
-      type: 'chat_status',
-      chat_id: chatId,
-      status: 'error',
-      at: new Date().toISOString(),
-      reason: 'summary_after_cap_failed',
-    });
-  }
-
-  ctx.log.info(
-    { sessionId, chatId, assistantMessageId, steps, cap, summaryOk, summaryCancelled: summarySoftCancelled },
-    'inference step-cap summary finished',
-  );
+  await insertSentinel(ctx, sessionId, chatId, metadata, content);
 }
 
 async function insertDoomLoopSentinel(
@@ -689,39 +358,12 @@ async function insertDoomLoopSentinel(
     threshold: DOOM_LOOP_THRESHOLD,
   };
   const content = `Detected ${DOOM_LOOP_THRESHOLD} identical calls to ${loop.name}. Stopping the tool-call loop. Produce the best answer you can with what you have.`;
-
-  const [row] = await ctx.sql<{ id: string }[]>`
-    INSERT INTO messages (session_id, chat_id, role, content, status, created_at, metadata)
-    VALUES (${sessionId}, ${chatId}, 'system', ${content}, 'complete', clock_timestamp(), ${ctx.sql.json(metadata as never)})
-    RETURNING id
-  `;
-
-  // Standard frame sequence — same as cap-hit sentinel — so
-  // useSessionStream's reducer appends the row via the existing path.
-  ctx.publish(sessionId, {
-    type: 'message_started',
-    message_id: row!.id,
-    chat_id: chatId,
-    role: 'system',
-  });
-  ctx.publish(sessionId, {
-    type: 'delta',
-    message_id: row!.id,
-    chat_id: chatId,
-    content,
-  });
-  ctx.publish(sessionId, {
-    type: 'message_complete',
-    message_id: row!.id,
-    chat_id: chatId,
-    metadata,
-  });
+  await insertSentinel(ctx, sessionId, chatId, metadata, content);
 }
 
-// #12 MistakeTracker: heterogeneous-failure recovery sentinel. Mirrors
-// insertDoomLoopSentinel structurally — a role='system', status='complete' row
-// firing the standard message_started → delta → message_complete frame
-// sequence. Two variants distinguished by `escalated`:
+// #12 MistakeTracker: heterogeneous-failure recovery sentinel. A role='system',
+// status='complete' row firing the standard sentinel frame sequence. Two
+// variants distinguished by `escalated`:
 //   - escalated:false → a nudge fired; recovery guidance was injected into the
 //     model's next step and the loop continued. can_continue is true (the turn
 //     is still live).
@@ -744,30 +386,5 @@ export async function insertMistakeRecoverySentinel(
   const content = opts.escalated
     ? `Repeated different errors persisted after a recovery nudge (${opts.count} in a row). Stopping the tool-call loop.`
     : `Hit ${opts.count} different errors in a row. Injected recovery guidance and continuing.`;
-
-  const [row] = await ctx.sql<{ id: string }[]>`
-    INSERT INTO messages (session_id, chat_id, role, content, status, created_at, metadata)
-    VALUES (${sessionId}, ${chatId}, 'system', ${content}, 'complete', clock_timestamp(), ${ctx.sql.json(metadata as never)})
-    RETURNING id
-  `;
-
-  // Standard frame sequence — same as cap-hit / doom-loop sentinels.
-  ctx.publish(sessionId, {
-    type: 'message_started',
-    message_id: row!.id,
-    chat_id: chatId,
-    role: 'system',
-  });
-  ctx.publish(sessionId, {
-    type: 'delta',
-    message_id: row!.id,
-    chat_id: chatId,
-    content,
-  });
-  ctx.publish(sessionId, {
-    type: 'message_complete',
-    message_id: row!.id,
-    chat_id: chatId,
-    metadata,
-  });
+  await insertSentinel(ctx, sessionId, chatId, metadata, content);
 }

apps/server/src/services/inference/sentinels.ts

@@ -27,6 +27,10 @@ export function detectDoomLoop(
   return { name: ref.name, args: ref.args };
 }
 
+// All sentinel kinds. isAnySentinel and compaction.ts's local predicate both
+// consume this set — single source so a new kind can't be missed in one.
+export const SENTINEL_KINDS = new Set(['cap_hit', 'doom_loop', 'mistake_recovery']);
+
 export function isCapHitSentinel(m: Message): boolean {
   return (
     m.role === 'system' &&
@@ -61,5 +65,10 @@ export function isMistakeRecoverySentinel(m: Message): boolean {
 }
 
 export function isAnySentinel(m: Message): boolean {
-  return isCapHitSentinel(m) || isDoomLoopSentinel(m) || isMistakeRecoverySentinel(m);
+  return (
+    m.role === 'system' &&
+    m.metadata !== null &&
+    typeof m.metadata === 'object' &&
+    SENTINEL_KINDS.has((m.metadata as { kind?: unknown }).kind as string)
+  );
 }

apps/server/src/services/inference/step-decision.ts

@@ -0,0 +1,47 @@
+// P5 (SPLIT SKETCH 5): pure step-decision helpers for the runAssistantTurn
+// loop. These COMPOSE the existing decision predicates (detectDoomLoop,
+// detectMistakePattern) — they do not reimplement them — so the loop body in
+// turn.ts becomes a thin driver and the branch logic is unit-testable without
+// a DB, broker, or stream.
+
+import type { ToolCall } from '../../types/api.js';
+import { detectDoomLoop } from './sentinels.js';
+import { detectMistakePattern, type MistakeState } from './mistake-tracker.js';
+import type { ToolPhaseResult } from './tool-phase.js';
+
+// Top-of-loop gate, evaluated before the stream phase. Order matters and
+// matches the original inline checks exactly: doom-loop first (identical-repeat
+// guard), then the cumulative tool-call budget, otherwise proceed to stream.
+export type PreStepDecision =
+  | { kind: 'doom'; loop: { name: string; args: Record<string, unknown> } }
+  | { kind: 'budget' }
+  | { kind: 'stream' };
+
+export function decideStep(input: {
+  recentToolCalls: ToolCall[];
+  toolsUsed: number;
+  budget: number;
+}): PreStepDecision {
+  const loop = detectDoomLoop(input.recentToolCalls);
+  if (loop) return { kind: 'doom', loop };
+  if (input.toolsUsed >= input.budget) return { kind: 'budget' };
+  return { kind: 'stream' };
+}
+
+// Post-tool-phase decision, evaluated after the tool phase returns. 'stop'
+// covers the tool-phase's own non-'continue' actions ('paused' for user input,
+// 'synthesis_done'); on 'continue' the mistake-tracker pattern gates the
+// nudge/escalate/continue choice (detectMistakePattern is only consulted on the
+// 'continue' path, exactly as the original loop did).
+export type PostToolDecision = 'continue' | 'nudge' | 'escalate' | 'stop';
+
+export function decidePostToolAction(
+  action: ToolPhaseResult['action'],
+  mistakeTracker: MistakeState,
+): PostToolDecision {
+  if (action !== 'continue') return 'stop';
+  const mistake = detectMistakePattern(mistakeTracker);
+  if (mistake === 'nudge') return 'nudge';
+  if (mistake === 'escalate') return 'escalate';
+  return 'continue';
+}

apps/server/src/services/inference/stream-phase-adapter.ts

@@ -0,0 +1,405 @@
+// P5 (SPLIT SKETCH): the generic AI-SDK adapter, split out of stream-phase.ts.
+// This module is the v1.13.1-A streamText adapter and nothing else — it has NO
+// SQL, broker, or BooCode persistence dependencies (its only `ctx` access is
+// config + log), so it can be unit-tested without standing up a DB or broker.
+// stream-phase.ts (the I/O layer) re-exports the public names below so existing
+// importers (`./stream-phase.js`) are unchanged.
+
+import type { FastifyBaseLogger } from 'fastify';
+import type { Config } from '../../config.js';
+import type { Agent, ToolCall } from '../../types/api.js';
+import type { ToolJsonSchema } from '../tools.js';
+import type { OpenAiMessage } from './payload.js';
+import { extractToolCallBlocks } from './tool-call-parser.js';
+import type { StreamResult } from './types.js';
+import { upstreamModel } from './provider.js';
+import {
+  jsonSchema,
+  streamText,
+  tool,
+  type JSONValue,
+  type ModelMessage,
+  type ToolCallRepairFunction,
+} from 'ai';
+
+// The slice of InferenceContext the adapter actually needs. Narrowing it here
+// (instead of taking the full InferenceContext) keeps the adapter free of the
+// SQL/broker/publish surface. InferenceContext structurally satisfies this, so
+// callers pass their ctx unchanged.
+export interface StreamAdapterContext {
+  config: Config;
+  log: FastifyBaseLogger;
+}
+
+export interface StreamOptions {
+  // null = omit tools entirely (compact phase); [] = caller stripped all tools
+  // (rare; we still omit from the request body to avoid OpenAI 400).
+  tools: ToolJsonSchema[] | null;
+  temperature?: number;
+  top_p?: number | null;
+  top_k?: number | null;
+  min_p?: number | null;
+  presence_penalty?: number | null;
+  // v2.6 sampling-streamjson-tokens (#11): llama.cpp sampler extensions. These
+  // are NOT standard AI-SDK streamText options and are NOT serialized by the
+  // openai-compatible provider's standardized-settings path (topK is even
+  // explicitly dropped with an "unsupported feature: topK" warning). They reach
+  // llama-server only via providerOptions.openaiCompatible (see buildSamplerProviderOptions).
+  top_n_sigma?: number | null;
+  dry_multiplier?: number | null;
+  dry_base?: number | null;
+  dry_allowed_length?: number | null;
+  dry_penalty_last_n?: number | null;
+}
+
+// P5: the 10-field sampler-options literal that was copy-pasted at 4 sites
+// (the three sentinel summaries + executeStreamPhase). Builds the StreamOptions
+// sampler subset from an agent's frontmatter knobs. `temperature` is
+// `agent?.temperature` (already number|undefined); the nullable fields strip
+// null → undefined so they're omitted from the request body when unset. Keep
+// this in lockstep with the StreamOptions sampler fields — a new sampler knob
+// (the v2.7.3 dry_* family did this) is added here once instead of at 4 sites.
+export type SamplerOpts = Omit<StreamOptions, 'tools'>;
+
+export function samplerOptsFromAgent(agent: Agent | null): SamplerOpts {
+  return {
+    temperature: agent?.temperature,
+    top_p: agent?.top_p ?? undefined,
+    top_k: agent?.top_k ?? undefined,
+    min_p: agent?.min_p ?? undefined,
+    presence_penalty: agent?.presence_penalty ?? undefined,
+    top_n_sigma: agent?.top_n_sigma ?? undefined,
+    dry_multiplier: agent?.dry_multiplier ?? undefined,
+    dry_base: agent?.dry_base ?? undefined,
+    dry_allowed_length: agent?.dry_allowed_length ?? undefined,
+    dry_penalty_last_n: agent?.dry_penalty_last_n ?? undefined,
+  };
+}
+
+// v2.6 #11: build the providerOptions.openaiCompatible extraBody object for the
+// llama.cpp sampler extensions. @ai-sdk/openai-compatible (2.0.47) merges every
+// non-reserved key under providerOptions.openaiCompatible straight into the
+// chat-completion request body (see its getArgs: the Object.fromEntries spread
+// filtered against openaiCompatibleLanguageModelChatOptions.shape). This is the
+// ONLY working passthrough for these params:
+//   - top_k / min_p were latently dropped before this: top_k was passed as the
+//     AI-SDK `topK` setting which the openai-compatible provider rejects as
+//     unsupported; min_p was never passed to streamText at all.
+//   - top_n_sigma + the dry_* family have no AI-SDK equivalent.
+// Keys use llama-server's snake_case body names so they land verbatim.
+function buildSamplerProviderOptions(opts: StreamOptions): Record<string, number> | undefined {
+  const body: Record<string, number> = {};
+  if (typeof opts.top_k === 'number') body.top_k = opts.top_k;
+  if (typeof opts.min_p === 'number') body.min_p = opts.min_p;
+  if (typeof opts.top_n_sigma === 'number') body.top_n_sigma = opts.top_n_sigma;
+  if (typeof opts.dry_multiplier === 'number') body.dry_multiplier = opts.dry_multiplier;
+  if (typeof opts.dry_base === 'number') body.dry_base = opts.dry_base;
+  if (typeof opts.dry_allowed_length === 'number') body.dry_allowed_length = opts.dry_allowed_length;
+  if (typeof opts.dry_penalty_last_n === 'number') body.dry_penalty_last_n = opts.dry_penalty_last_n;
+  return Object.keys(body).length > 0 ? body : undefined;
+}
+
+// v1.13.1-A: convert BooCode's OpenAI-shaped history into AI SDK
+// ModelMessage[]. Tool result messages need a `toolName` field that the
+// OpenAI shape doesn't carry; we look it up by scanning earlier assistant
+// `tool_calls` entries for a matching id.
+function toModelMessages(messages: OpenAiMessage[]): ModelMessage[] {
+  const toolNameById = new Map<string, string>();
+  for (const m of messages) {
+    if (m.role === 'assistant' && m.tool_calls) {
+      for (const tc of m.tool_calls) {
+        toolNameById.set(tc.id, tc.function.name);
+      }
+    }
+  }
+  const out: ModelMessage[] = [];
+  for (const m of messages) {
+    if (m.role === 'system' || m.role === 'user') {
+      out.push({ role: m.role, content: m.content ?? '' });
+      continue;
+    }
+    if (m.role === 'assistant') {
+      const hasTools = m.tool_calls && m.tool_calls.length > 0;
+      const hasReasoning = typeof m.reasoning === 'string' && m.reasoning.length > 0;
+      if (!hasTools && !hasReasoning) {
+        // Bare text assistant (string content). null content + no tool_calls
+        // is degenerate but harmless to forward.
+        out.push({ role: 'assistant', content: m.content ?? '' });
+        continue;
+      }
+      // v1.13.1-C: AI SDK ReasoningPart precedes text + tool-calls in the
+      // assistant content array. Reasoning models (qwen3.6) consume their
+      // prior reasoning context to resume mid-thought across tool boundaries.
+      const parts: Array<
+        | { type: 'reasoning'; text: string }
+        | { type: 'text'; text: string }
+        | { type: 'tool-call'; toolCallId: string; toolName: string; input: unknown }
+      > = [];
+      if (hasReasoning) {
+        parts.push({ type: 'reasoning', text: m.reasoning! });
+      }
+      if (m.content && m.content.length > 0) {
+        parts.push({ type: 'text', text: m.content });
+      }
+      for (const tc of m.tool_calls ?? []) {
+        let input: unknown = {};
+        try {
+          input = tc.function.arguments.length > 0 ? JSON.parse(tc.function.arguments) : {};
+        } catch {
+          // Malformed args from a prior turn: pass through as a raw blob so
+          // the model sees the same shape it emitted. Wraps the string under
+          // _raw to match the buildMessagesPayload upstream convention.
+          input = { _raw: tc.function.arguments };
+        }
+        parts.push({ type: 'tool-call', toolCallId: tc.id, toolName: tc.function.name, input });
+      }
+      out.push({ role: 'assistant', content: parts });
+      continue;
+    }
+    if (m.role === 'tool') {
+      const toolCallId = m.tool_call_id ?? '';
+      const toolName = toolNameById.get(toolCallId) ?? 'unknown';
+      const raw = m.content ?? '';
+      let output: { type: 'text'; value: string } | { type: 'json'; value: JSONValue };
+      try {
+        // JSON.parse returns `any`; cast to JSONValue since the upstream
+        // tool_results column is already JSON-serializable by construction.
+        output = { type: 'json', value: JSON.parse(raw) as JSONValue };
+      } catch {
+        output = { type: 'text', value: raw };
+      }
+      out.push({
+        role: 'tool',
+        content: [{ type: 'tool-result', toolCallId, toolName, output }],
+      });
+      continue;
+    }
+  }
+  return out;
+}
+
+// Build the AI SDK tools record from BooCode's JSON-schema tool definitions.
+// No `execute` field: BooCode runs tools itself in tool-phase.ts; streamText
+// surfaces the tool-call parts via fullStream and we capture them for the
+// outer loop to dispatch.
+function buildAiTools(schemas: ToolJsonSchema[]): Record<string, ReturnType<typeof tool>> {
+  const out: Record<string, ReturnType<typeof tool>> = {};
+  for (const s of schemas) {
+    out[s.function.name] = tool({
+      description: s.function.description,
+      inputSchema: jsonSchema(s.function.parameters),
+    });
+  }
+  return out;
+}
+
+// v1.10.5 Qwen-coder XML fallback. Some local models (notably qwen3-coder via
+// llama-swap) emit tool calls as inline XML inside delta.content rather than
+// the structured tool_calls field. We extract them out of the streamed text
+// before flushing it to the client.
+//
+// Qwen shape:
+//   <tool_call>
+//   <function=NAME>
+//   <parameter=KEY>VALUE</parameter>
+//   ...
+//   </function>
+//   </tool_call>
+//
+// v1.13.16: also recognize Anthropic <invoke> markup that qwen3.6-35b-a3b-mxfp4
+// drifts to (training-data residue from Claude Code documentation):
+//   <invoke name="NAME">
+//   <parameter name="KEY">VALUE</parameter>
+//   </invoke>
+// Both formats share the synthetic xml_call_${idx} ID space; the counter
+// increments across whichever opener appears first. Multiple blocks may
+// appear back-to-back in either format and they never nest.
+export async function streamCompletion(
+  ctx: StreamAdapterContext,
+  model: string,
+  messages: OpenAiMessage[],
+  opts: StreamOptions,
+  onDelta: (content: string) => void,
+  onUsage: ((prompt: number | null, completion: number | null) => void) | undefined,
+  signal?: AbortSignal,
+  agent?: Agent | null,
+): Promise<StreamResult> {
+  const aiMessages = toModelMessages(messages);
+  const hasTools = opts.tools !== null && opts.tools.length > 0;
+  const aiTools = hasTools ? buildAiTools(opts.tools!) : undefined;
+
+  const startedAt = Date.now();
+  // v1.13.1-C: accumulate reasoning text across reasoning-delta parts.
+  // qwen3.6 emits these on a separate channel from text content; we capture
+  // them per stream so finalizeCompletion can dual-write a 'reasoning' part.
+  // Replaces the v1.13.1-A counter-only diagnostic.
+  let reasoningAccumulated = '';
+
+  // v1.13.3: experimental_repairToolCall keeps the stream alive when the
+  // model emits a malformed tool call (bad JSON args, unknown name, etc.).
+  // Without a repair function streamText throws and the WHOLE stream dies;
+  // with one, the SDK invokes us and we route the bad call through normally.
+  // Strategy: pass through unmodified. executeToolPhase's existing error
+  // path (unknown tool name → "unknown tool: X" result; zod-reject → tool
+  // 'X' rejected — fieldname: required) already gives the model a clean
+  // recovery surface on the next turn. Logging gives us visibility into
+  // how often qwen3.6 actually emits broken calls.
+  const repairToolCall: ToolCallRepairFunction<NonNullable<typeof aiTools>> = async ({
+    toolCall,
+    error,
+  }) => {
+    ctx.log.warn(
+      {
+        toolCallId: toolCall.toolCallId,
+        toolName: toolCall.toolName,
+        error: error.message,
+      },
+      'malformed tool call surfaced via repairToolCall',
+    );
+    return toolCall;
+  };
+
+  // v2.6 #11: llama.cpp sampler extensions (top_k, min_p, top_n_sigma, dry_*)
+  // ride providerOptions.openaiCompatible — they are NOT standardized streamText
+  // settings. NB: top_k used to be passed below as the AI-SDK `topK` setting;
+  // the openai-compatible provider dropped it with an "unsupported feature: topK"
+  // warning and min_p was never wired at all, so both were dead on the wire
+  // before this. They now go through the same extraBody path as the new params.
+  const samplerBody = buildSamplerProviderOptions(opts);
+
+  const result = streamText({
+    model: upstreamModel(ctx.config, model, agent ?? null),
+    messages: aiMessages,
+    ...(aiTools
+      ? { tools: aiTools, toolChoice: 'auto' as const, experimental_repairToolCall: repairToolCall }
+      : {}),
+    ...(typeof opts.temperature === 'number' ? { temperature: opts.temperature } : {}),
+    ...(typeof opts.top_p === 'number' ? { topP: opts.top_p } : {}),
+    ...(typeof opts.presence_penalty === 'number' ? { presencePenalty: opts.presence_penalty } : {}),
+    ...(samplerBody ? { providerOptions: { openaiCompatible: samplerBody } } : {}),
+    abortSignal: signal,
+  });
+
+  let content = '';
+  let pendingBuffer = '';
+  let finishReason: string | null = null;
+  // v1.13.1-A: AI SDK emits one `tool-call` part per fully-aggregated call,
+  // so we no longer need the OpenAI-index reassembly map the manual SSE
+  // parser used. XML tool calls extracted from text content go into the
+  // same flat list and keep the v1.10.5 synthetic id convention.
+  const toolCalls: ToolCall[] = [];
+
+  for await (const part of result.fullStream) {
+    switch (part.type) {
+      case 'text-delta': {
+        pendingBuffer += part.text;
+        // v1.13.16: unified extraction. The helper finds the earliest-opening
+        // complete <tool_call> or <invoke> block, flushes prose between/around
+        // them, holds any partial opener for the next chunk, and silently
+        // drops blocks that fail to parse (matches pre-v1.13.16 behavior).
+        const extracted = extractToolCallBlocks(pendingBuffer);
+        if (extracted.flushed.length > 0) {
+          content += extracted.flushed;
+          onDelta(extracted.flushed);
+        }
+        for (const call of extracted.calls) {
+          const synthIdx = toolCalls.length;
+          toolCalls.push({
+            id: `xml_call_${synthIdx}`,
+            name: call.name,
+            args: call.args,
+          });
+        }
+        pendingBuffer = extracted.remaining;
+        break;
+      }
+      case 'tool-call': {
+        // AI SDK has already parsed the input into an object. Match the
+        // ToolCall shape BooCode passes around in toolCallsBuffer downstream.
+        toolCalls.push({
+          id: part.toolCallId,
+          name: part.toolName,
+          args: (part.input ?? {}) as Record<string, unknown>,
+        });
+        break;
+      }
+      case 'reasoning-delta': {
+        // v1.13.1-C: accumulate; finalizeCompletion / executeToolPhase
+        // dual-write the resulting text as a kind='reasoning' part.
+        if (typeof part.text === 'string') {
+          reasoningAccumulated += part.text;
+        }
+        break;
+      }
+      case 'finish': {
+        if (typeof part.finishReason === 'string') {
+          finishReason = part.finishReason;
+        }
+        break;
+      }
+      case 'error': {
+        const err = part.error;
+        throw err instanceof Error ? err : new Error(String(err));
+      }
+      // Intentional no-op: start, start-step, text-start, text-end,
+      // reasoning-start, reasoning-end, source, file, tool-input-start,
+      // tool-input-delta, tool-input-end, tool-result, tool-error,
+      // finish-step, raw. We only care about the aggregated tool-call and
+      // text-delta paths above; the rest are AI SDK lifecycle/streaming
+      // breadcrumbs that don't change BooCode's persistence or WS contract.
+      default:
+        break;
+    }
+  }
+
+  // v1.13.1-A: drain any buffered partial XML opener as plain text. The
+  // pre-AI-SDK path did this on stream end too — better to leak `<tool_c`
+  // than vanish the text.
+  if (pendingBuffer.length > 0) {
+    content += pendingBuffer;
+    onDelta(pendingBuffer);
+    pendingBuffer = '';
+  }
+
+  // AI SDK v6 fullStream returns normally on abort; check signal explicitly.
+  // Without this throw the row would land as status='complete' with partial
+  // content instead of going through handleAbortOrError → status='cancelled'.
+  // Smoke D caught this in v1.13.1-A — don't refactor it away.
+  if (signal?.aborted) {
+    const abortErr = new Error('aborted');
+    abortErr.name = 'AbortError';
+    throw abortErr;
+  }
+
+  // Usage lands as a promise on the result; awaiting after fullStream is
+  // drained is safe. AI SDK v6 names: `inputTokens` / `outputTokens`.
+  let promptTokens: number | null = null;
+  let completionTokens: number | null = null;
+  try {
+    const usage = await result.usage;
+    if (typeof usage.inputTokens === 'number') promptTokens = usage.inputTokens;
+    if (typeof usage.outputTokens === 'number') completionTokens = usage.outputTokens;
+  } catch {
+    // Some providers omit usage on partial streams; leave both null.
+  }
+
+  if (onUsage && (promptTokens !== null || completionTokens !== null)) {
+    onUsage(promptTokens, completionTokens);
+  }
+
+  if (reasoningAccumulated.length > 0) {
+    ctx.log.debug(
+      { reasoningChars: reasoningAccumulated.length, model, elapsed_ms: Date.now() - startedAt },
+      'streamCompletion: captured reasoning',
+    );
+  }
+
+  return {
+    finishReason,
+    content,
+    toolCalls,
+    promptTokens,
+    completionTokens,
+    reasoning: reasoningAccumulated,
+  };
+}

apps/server/src/services/inference/stream-phase.ts

@@ -1,377 +1,34 @@
-import type {
-  Agent,
-  Session,
-  ToolCall,
-} from '../../types/api.js';
+// P5 (SPLIT SKETCH): stream-phase.ts is now the BooCode I/O layer for the
+// stream phase — `executeStreamPhase` owns the row UPDATE, message_started
+// frame, debounced content flush, throttled usage publish, model-context
+// lookup, and tool-whitelist filter. The generic AI-SDK adapter
+// (streamCompletion / toModelMessages / buildAiTools / sampler helpers) moved
+// to ./stream-phase-adapter.ts, which has no SQL/broker/publish deps and is
+// unit-testable on its own. The adapter's public names are re-exported below so
+// existing importers of './stream-phase.js' (sentinel-summaries, synthesis
+// pipeline, the helper tests) keep working unchanged.
+
+import type { Agent, Session } from '../../types/api.js';
 import * as modelContext from '../model-context.js';
 import { toolJsonSchemas, type ToolJsonSchema } from '../tools.js';
 import { matchToolGlob } from '../agents.js';
 import type { OpenAiMessage } from './payload.js';
-import { extractToolCallBlocks } from './tool-call-parser.js';
-import { DB_FLUSH_INTERVAL_MS, type StreamPhaseState } from './types.js';
+import { createContentFlusher } from './content-flusher.js';
 import type {
+  StreamPhaseState,
   InferenceContext,
   StreamResult,
   TurnArgs,
-} from './turn.js';
-import { upstreamModel } from './provider.js';
-import {
-  jsonSchema,
-  streamText,
-  tool,
-  type JSONValue,
-  type ModelMessage,
-  type ToolCallRepairFunction,
-} from 'ai';
+} from './types.js';
+import { streamCompletion, samplerOptsFromAgent } from './stream-phase-adapter.js';
 
-interface StreamOptions {
-  // null = omit tools entirely (compact phase); [] = caller stripped all tools
-  // (rare; we still omit from the request body to avoid OpenAI 400).
-  tools: ToolJsonSchema[] | null;
-  temperature?: number;
-  top_p?: number | null;
-  top_k?: number | null;
-  min_p?: number | null;
-  presence_penalty?: number | null;
-  // v2.6 sampling-streamjson-tokens (#11): llama.cpp sampler extensions. These
-  // are NOT standard AI-SDK streamText options and are NOT serialized by the
-  // openai-compatible provider's standardized-settings path (topK is even
-  // explicitly dropped with an "unsupported feature: topK" warning). They reach
-  // llama-server only via providerOptions.openaiCompatible (see buildSamplerProviderOptions).
-  top_n_sigma?: number | null;
-  dry_multiplier?: number | null;
-  dry_base?: number | null;
-  dry_allowed_length?: number | null;
-  dry_penalty_last_n?: number | null;
-}
-
-// v2.6 #11: build the providerOptions.openaiCompatible extraBody object for the
-// llama.cpp sampler extensions. @ai-sdk/openai-compatible (2.0.47) merges every
-// non-reserved key under providerOptions.openaiCompatible straight into the
-// chat-completion request body (see its getArgs: the Object.fromEntries spread
-// filtered against openaiCompatibleLanguageModelChatOptions.shape). This is the
-// ONLY working passthrough for these params:
-//   - top_k / min_p were latently dropped before this: top_k was passed as the
-//     AI-SDK `topK` setting which the openai-compatible provider rejects as
-//     unsupported; min_p was never passed to streamText at all.
-//   - top_n_sigma + the dry_* family have no AI-SDK equivalent.
-// Keys use llama-server's snake_case body names so they land verbatim.
-function buildSamplerProviderOptions(opts: StreamOptions): Record<string, number> | undefined {
-  const body: Record<string, number> = {};
-  if (typeof opts.top_k === 'number') body.top_k = opts.top_k;
-  if (typeof opts.min_p === 'number') body.min_p = opts.min_p;
-  if (typeof opts.top_n_sigma === 'number') body.top_n_sigma = opts.top_n_sigma;
-  if (typeof opts.dry_multiplier === 'number') body.dry_multiplier = opts.dry_multiplier;
-  if (typeof opts.dry_base === 'number') body.dry_base = opts.dry_base;
-  if (typeof opts.dry_allowed_length === 'number') body.dry_allowed_length = opts.dry_allowed_length;
-  if (typeof opts.dry_penalty_last_n === 'number') body.dry_penalty_last_n = opts.dry_penalty_last_n;
-  return Object.keys(body).length > 0 ? body : undefined;
-}
-
-// v1.13.1-A: convert BooCode's OpenAI-shaped history into AI SDK
-// ModelMessage[]. Tool result messages need a `toolName` field that the
-// OpenAI shape doesn't carry; we look it up by scanning earlier assistant
-// `tool_calls` entries for a matching id.
-function toModelMessages(messages: OpenAiMessage[]): ModelMessage[] {
-  const toolNameById = new Map<string, string>();
-  for (const m of messages) {
-    if (m.role === 'assistant' && m.tool_calls) {
-      for (const tc of m.tool_calls) {
-        toolNameById.set(tc.id, tc.function.name);
-      }
-    }
-  }
-  const out: ModelMessage[] = [];
-  for (const m of messages) {
-    if (m.role === 'system' || m.role === 'user') {
-      out.push({ role: m.role, content: m.content ?? '' });
-      continue;
-    }
-    if (m.role === 'assistant') {
-      const hasTools = m.tool_calls && m.tool_calls.length > 0;
-      const hasReasoning = typeof m.reasoning === 'string' && m.reasoning.length > 0;
-      if (!hasTools && !hasReasoning) {
-        // Bare text assistant (string content). null content + no tool_calls
-        // is degenerate but harmless to forward.
-        out.push({ role: 'assistant', content: m.content ?? '' });
-        continue;
-      }
-      // v1.13.1-C: AI SDK ReasoningPart precedes text + tool-calls in the
-      // assistant content array. Reasoning models (qwen3.6) consume their
-      // prior reasoning context to resume mid-thought across tool boundaries.
-      const parts: Array<
-        | { type: 'reasoning'; text: string }
-        | { type: 'text'; text: string }
-        | { type: 'tool-call'; toolCallId: string; toolName: string; input: unknown }
-      > = [];
-      if (hasReasoning) {
-        parts.push({ type: 'reasoning', text: m.reasoning! });
-      }
-      if (m.content && m.content.length > 0) {
-        parts.push({ type: 'text', text: m.content });
-      }
-      for (const tc of m.tool_calls ?? []) {
-        let input: unknown = {};
-        try {
-          input = tc.function.arguments.length > 0 ? JSON.parse(tc.function.arguments) : {};
-        } catch {
-          // Malformed args from a prior turn: pass through as a raw blob so
-          // the model sees the same shape it emitted. Wraps the string under
-          // _raw to match the buildMessagesPayload upstream convention.
-          input = { _raw: tc.function.arguments };
-        }
-        parts.push({ type: 'tool-call', toolCallId: tc.id, toolName: tc.function.name, input });
-      }
-      out.push({ role: 'assistant', content: parts });
-      continue;
-    }
-    if (m.role === 'tool') {
-      const toolCallId = m.tool_call_id ?? '';
-      const toolName = toolNameById.get(toolCallId) ?? 'unknown';
-      const raw = m.content ?? '';
-      let output: { type: 'text'; value: string } | { type: 'json'; value: JSONValue };
-      try {
-        // JSON.parse returns `any`; cast to JSONValue since the upstream
-        // tool_results column is already JSON-serializable by construction.
-        output = { type: 'json', value: JSON.parse(raw) as JSONValue };
-      } catch {
-        output = { type: 'text', value: raw };
-      }
-      out.push({
-        role: 'tool',
-        content: [{ type: 'tool-result', toolCallId, toolName, output }],
-      });
-      continue;
-    }
-  }
-  return out;
-}
-
-// Build the AI SDK tools record from BooCode's JSON-schema tool definitions.
-// No `execute` field: BooCode runs tools itself in tool-phase.ts; streamText
-// surfaces the tool-call parts via fullStream and we capture them for the
-// outer loop to dispatch.
-function buildAiTools(schemas: ToolJsonSchema[]): Record<string, ReturnType<typeof tool>> {
-  const out: Record<string, ReturnType<typeof tool>> = {};
-  for (const s of schemas) {
-    out[s.function.name] = tool({
-      description: s.function.description,
-      inputSchema: jsonSchema(s.function.parameters),
-    });
-  }
-  return out;
-}
-
-// v1.10.5 Qwen-coder XML fallback. Some local models (notably qwen3-coder via
-// llama-swap) emit tool calls as inline XML inside delta.content rather than
-// the structured tool_calls field. We extract them out of the streamed text
-// before flushing it to the client.
-//
-// Qwen shape:
-//   <tool_call>
-//   <function=NAME>
-//   <parameter=KEY>VALUE</parameter>
-//   ...
-//   </function>
-//   </tool_call>
-//
-// v1.13.16: also recognize Anthropic <invoke> markup that qwen3.6-35b-a3b-mxfp4
-// drifts to (training-data residue from Claude Code documentation):
-//   <invoke name="NAME">
-//   <parameter name="KEY">VALUE</parameter>
-//   </invoke>
-// Both formats share the synthetic xml_call_${idx} ID space; the counter
-// increments across whichever opener appears first. Multiple blocks may
-// appear back-to-back in either format and they never nest.
-export async function streamCompletion(
-  ctx: InferenceContext,
-  model: string,
-  messages: OpenAiMessage[],
-  opts: StreamOptions,
-  onDelta: (content: string) => void,
-  onUsage: ((prompt: number | null, completion: number | null) => void) | undefined,
-  signal?: AbortSignal,
-  agent?: Agent | null,
-): Promise<StreamResult> {
-  const aiMessages = toModelMessages(messages);
-  const hasTools = opts.tools !== null && opts.tools.length > 0;
-  const aiTools = hasTools ? buildAiTools(opts.tools!) : undefined;
-
-  const startedAt = Date.now();
-  // v1.13.1-C: accumulate reasoning text across reasoning-delta parts.
-  // qwen3.6 emits these on a separate channel from text content; we capture
-  // them per stream so finalizeCompletion can dual-write a 'reasoning' part.
-  // Replaces the v1.13.1-A counter-only diagnostic.
-  let reasoningAccumulated = '';
-
-  // v1.13.3: experimental_repairToolCall keeps the stream alive when the
-  // model emits a malformed tool call (bad JSON args, unknown name, etc.).
-  // Without a repair function streamText throws and the WHOLE stream dies;
-  // with one, the SDK invokes us and we route the bad call through normally.
-  // Strategy: pass through unmodified. executeToolPhase's existing error
-  // path (unknown tool name → "unknown tool: X" result; zod-reject → tool
-  // 'X' rejected — fieldname: required) already gives the model a clean
-  // recovery surface on the next turn. Logging gives us visibility into
-  // how often qwen3.6 actually emits broken calls.
-  const repairToolCall: ToolCallRepairFunction<NonNullable<typeof aiTools>> = async ({
-    toolCall,
-    error,
-  }) => {
-    ctx.log.warn(
-      {
-        toolCallId: toolCall.toolCallId,
-        toolName: toolCall.toolName,
-        error: error.message,
-      },
-      'malformed tool call surfaced via repairToolCall',
-    );
-    return toolCall;
-  };
-
-  // v2.6 #11: llama.cpp sampler extensions (top_k, min_p, top_n_sigma, dry_*)
-  // ride providerOptions.openaiCompatible — they are NOT standardized streamText
-  // settings. NB: top_k used to be passed below as the AI-SDK `topK` setting;
-  // the openai-compatible provider dropped it with an "unsupported feature: topK"
-  // warning and min_p was never wired at all, so both were dead on the wire
-  // before this. They now go through the same extraBody path as the new params.
-  const samplerBody = buildSamplerProviderOptions(opts);
-
-  const result = streamText({
-    model: upstreamModel(ctx.config, model, agent ?? null),
-    messages: aiMessages,
-    ...(aiTools
-      ? { tools: aiTools, toolChoice: 'auto' as const, experimental_repairToolCall: repairToolCall }
-      : {}),
-    ...(typeof opts.temperature === 'number' ? { temperature: opts.temperature } : {}),
-    ...(typeof opts.top_p === 'number' ? { topP: opts.top_p } : {}),
-    ...(typeof opts.presence_penalty === 'number' ? { presencePenalty: opts.presence_penalty } : {}),
-    ...(samplerBody ? { providerOptions: { openaiCompatible: samplerBody } } : {}),
-    abortSignal: signal,
-  });
-
-  let content = '';
-  let pendingBuffer = '';
-  let finishReason: string | null = null;
-  // v1.13.1-A: AI SDK emits one `tool-call` part per fully-aggregated call,
-  // so we no longer need the OpenAI-index reassembly map the manual SSE
-  // parser used. XML tool calls extracted from text content go into the
-  // same flat list and keep the v1.10.5 synthetic id convention.
-  const toolCalls: ToolCall[] = [];
-
-  for await (const part of result.fullStream) {
-    switch (part.type) {
-      case 'text-delta': {
-        pendingBuffer += part.text;
-        // v1.13.16: unified extraction. The helper finds the earliest-opening
-        // complete <tool_call> or <invoke> block, flushes prose between/around
-        // them, holds any partial opener for the next chunk, and silently
-        // drops blocks that fail to parse (matches pre-v1.13.16 behavior).
-        const extracted = extractToolCallBlocks(pendingBuffer);
-        if (extracted.flushed.length > 0) {
-          content += extracted.flushed;
-          onDelta(extracted.flushed);
-        }
-        for (const call of extracted.calls) {
-          const synthIdx = toolCalls.length;
-          toolCalls.push({
-            id: `xml_call_${synthIdx}`,
-            name: call.name,
-            args: call.args,
-          });
-        }
-        pendingBuffer = extracted.remaining;
-        break;
-      }
-      case 'tool-call': {
-        // AI SDK has already parsed the input into an object. Match the
-        // ToolCall shape BooCode passes around in toolCallsBuffer downstream.
-        toolCalls.push({
-          id: part.toolCallId,
-          name: part.toolName,
-          args: (part.input ?? {}) as Record<string, unknown>,
-        });
-        break;
-      }
-      case 'reasoning-delta': {
-        // v1.13.1-C: accumulate; finalizeCompletion / executeToolPhase
-        // dual-write the resulting text as a kind='reasoning' part.
-        if (typeof part.text === 'string') {
-          reasoningAccumulated += part.text;
-        }
-        break;
-      }
-      case 'finish': {
-        if (typeof part.finishReason === 'string') {
-          finishReason = part.finishReason;
-        }
-        break;
-      }
-      case 'error': {
-        const err = part.error;
-        throw err instanceof Error ? err : new Error(String(err));
-      }
-      // Intentional no-op: start, start-step, text-start, text-end,
-      // reasoning-start, reasoning-end, source, file, tool-input-start,
-      // tool-input-delta, tool-input-end, tool-result, tool-error,
-      // finish-step, raw. We only care about the aggregated tool-call and
-      // text-delta paths above; the rest are AI SDK lifecycle/streaming
-      // breadcrumbs that don't change BooCode's persistence or WS contract.
-      default:
-        break;
-    }
-  }
-
-  // v1.13.1-A: drain any buffered partial XML opener as plain text. The
-  // pre-AI-SDK path did this on stream end too — better to leak `<tool_c`
-  // than vanish the text.
-  if (pendingBuffer.length > 0) {
-    content += pendingBuffer;
-    onDelta(pendingBuffer);
-    pendingBuffer = '';
-  }
-
-  // AI SDK v6 fullStream returns normally on abort; check signal explicitly.
-  // Without this throw the row would land as status='complete' with partial
-  // content instead of going through handleAbortOrError → status='cancelled'.
-  // Smoke D caught this in v1.13.1-A — don't refactor it away.
-  if (signal?.aborted) {
-    const abortErr = new Error('aborted');
-    abortErr.name = 'AbortError';
-    throw abortErr;
-  }
-
-  // Usage lands as a promise on the result; awaiting after fullStream is
-  // drained is safe. AI SDK v6 names: `inputTokens` / `outputTokens`.
-  let promptTokens: number | null = null;
-  let completionTokens: number | null = null;
-  try {
-    const usage = await result.usage;
-    if (typeof usage.inputTokens === 'number') promptTokens = usage.inputTokens;
-    if (typeof usage.outputTokens === 'number') completionTokens = usage.outputTokens;
-  } catch {
-    // Some providers omit usage on partial streams; leave both null.
-  }
-
-  if (onUsage && (promptTokens !== null || completionTokens !== null)) {
-    onUsage(promptTokens, completionTokens);
-  }
-
-  if (reasoningAccumulated.length > 0) {
-    ctx.log.debug(
-      { reasoningChars: reasoningAccumulated.length, model, elapsed_ms: Date.now() - startedAt },
-      'streamCompletion: captured reasoning',
-    );
-  }
-
-  return {
-    finishReason,
-    content,
-    toolCalls,
-    promptTokens,
-    completionTokens,
-    reasoning: reasoningAccumulated,
-  };
-}
+export {
+  streamCompletion,
+  samplerOptsFromAgent,
+  type StreamOptions,
+  type SamplerOpts,
+  type StreamAdapterContext,
+} from './stream-phase-adapter.js';
 
 export async function executeStreamPhase(
   ctx: InferenceContext,
@@ -401,27 +58,7 @@ export async function executeStreamPhase(
     role: 'assistant',
   });
 
-  let pendingFlushTimer: NodeJS.Timeout | null = null;
-  let flushPromise: Promise<unknown> = Promise.resolve();
-
-  const flushNow = () => {
-    if (pendingFlushTimer) {
-      clearTimeout(pendingFlushTimer);
-      pendingFlushTimer = null;
-    }
-    const snapshot = state.accumulated;
-    flushPromise = flushPromise.then(() =>
-      ctx.sql`UPDATE messages SET content = ${snapshot} WHERE id = ${assistantMessageId}`
-    );
-  };
-
-  const scheduleFlush = () => {
-    if (pendingFlushTimer) return;
-    pendingFlushTimer = setTimeout(() => {
-      pendingFlushTimer = null;
-      flushNow();
-    }, DB_FLUSH_INTERVAL_MS);
-  };
+  const flusher = createContentFlusher(ctx.sql, assistantMessageId, () => state.accumulated);
 
   // Tool whitelist: if an agent is set, filter the global tool list to only the
   // tool names it allows. v1.15.0-mcp-multi: uses matchToolGlob for glob
@@ -434,17 +71,6 @@ export async function executeStreamPhase(
     ? toolJsonSchemas().filter((t) => matchToolGlob(t.function.name, agent.tools))
     : toolJsonSchemas()
   ).filter((t) => webToolsEnabled || !WEB_TOOL_NAMES.has(t.function.name));
-  const effectiveTemperature = agent?.temperature;
-  const effectiveTopP = agent?.top_p ?? undefined;
-  const effectiveTopK = agent?.top_k ?? undefined;
-  const effectiveMinP = agent?.min_p ?? undefined;
-  const effectivePresencePenalty = agent?.presence_penalty ?? undefined;
-  // v2.6 #11: llama.cpp sampler extensions, threaded the same way as top_k/min_p.
-  const effectiveTopNSigma = agent?.top_n_sigma ?? undefined;
-  const effectiveDryMultiplier = agent?.dry_multiplier ?? undefined;
-  const effectiveDryBase = agent?.dry_base ?? undefined;
-  const effectiveDryAllowedLength = agent?.dry_allowed_length ?? undefined;
-  const effectiveDryPenaltyLastN = agent?.dry_penalty_last_n ?? undefined;
 
   // v1.12.2: ctx_max lookup is cached after the first hit per model, so this
   // is a Map probe in steady state. We capture nCtx once at the top of the
@@ -484,16 +110,7 @@ export async function executeStreamPhase(
       messages,
       {
         tools: effectiveTools,
-        temperature: effectiveTemperature,
-        top_p: effectiveTopP,
-        top_k: effectiveTopK,
-        min_p: effectiveMinP,
-        presence_penalty: effectivePresencePenalty,
-        top_n_sigma: effectiveTopNSigma,
-        dry_multiplier: effectiveDryMultiplier,
-        dry_base: effectiveDryBase,
-        dry_allowed_length: effectiveDryAllowedLength,
-        dry_penalty_last_n: effectiveDryPenaltyLastN,
+        ...samplerOptsFromAgent(agent),
       },
       (delta) => {
         state.accumulated += delta;
@@ -504,7 +121,7 @@ export async function executeStreamPhase(
           content: delta,
         });
         ctx.log.debug({ sessionId, delta }, 'inference delta');
-        scheduleFlush();
+        flusher.scheduleFlush();
       },
       (prompt, completion) => {
         pendingUsage = { p: prompt, c: completion };
@@ -522,14 +139,10 @@ export async function executeStreamPhase(
       agent,
     );
   } finally {
-    if (pendingFlushTimer) {
-      clearTimeout(pendingFlushTimer);
-      pendingFlushTimer = null;
-    }
     if (usageTimer) {
       clearTimeout(usageTimer);
       usageTimer = null;
     }
-    await flushPromise;
+    await flusher.drain();
   }
 }

apps/server/src/services/inference/tool-phase.ts

@@ -22,7 +22,7 @@ import type {
   InferenceContext,
   StreamResult,
   TurnArgs,
-} from './turn.js';
+} from './types.js';
 // v1.13.13: synthesis pipeline — replaces the immediate recursive turn when
 // any of this batch's tool calls is in SYNTHESIS_TOOLS. Falls through to
 // recursion on synthesis failure (timeout / model error). See module header

apps/server/src/services/inference/tool-summaries.ts

@@ -1,81 +0,0 @@
-/**
- * v2.0.5: Tool-use summary generation.
- *
- * After a batch of tool calls completes, fire a cheap LLM call to generate
- * a "git-commit-subject-style" one-liner label describing what the tools
- * accomplished. Ported from the Qwen Code source recon.
- */
-import type { FastifyBaseLogger } from 'fastify';
-
-const TOOL_SUMMARY_SYSTEM_PROMPT = `Write a short summary label describing what these tool calls accomplished. Think git-commit-subject, not sentence. Past tense, most distinctive noun. Max 30 characters. Output ONLY the label.
-
-Examples:
-- Searched in auth/
-- Fixed NPE in UserService
-- Created signup endpoint
-- Read config.json
-- Ran failing tests`;
-
-const INPUT_TRUNCATE = 300;
-const MAX_SUMMARY_LENGTH = 100;
-
-export interface ToolInfo {
-  name: string;
-  input: string;
-  output: string;
-}
-
-export async function generateToolUseSummary(opts: {
-  tools: ToolInfo[];
-  llamaSwapUrl: string;
-  model: string;
-  log: FastifyBaseLogger;
-  signal?: AbortSignal;
-}): Promise<string | null> {
-  const { tools, llamaSwapUrl, model, log, signal } = opts;
-  if (tools.length === 0) return null;
-  if (signal?.aborted) return null;
-
-  const toolText = tools
-    .map(t => `Tool: ${t.name}\nInput: ${t.input.slice(0, INPUT_TRUNCATE)}\nOutput: ${t.output.slice(0, INPUT_TRUNCATE)}`)
-    .join('\n\n');
-
-  try {
-    const res = await fetch(`${llamaSwapUrl}/v1/chat/completions`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        model,
-        messages: [
-          { role: 'system', content: TOOL_SUMMARY_SYSTEM_PROMPT },
-          { role: 'user', content: toolText },
-        ],
-        max_tokens: 30,
-        temperature: 0.2,
-        stream: false,
-        chat_template_kwargs: { enable_thinking: false },
-      }),
-      signal,
-    });
-    if (!res.ok) {
-      log.debug({ status: res.status }, 'tool-summary: LLM request failed');
-      return null;
-    }
-    const data = await res.json() as { choices?: Array<{ message?: { content?: string } }> };
-    const raw = data.choices?.[0]?.message?.content?.trim() ?? '';
-    if (!raw) return null;
-    // Clean: strip quotes, "Label:" prefix, cap length
-    let cleaned = raw.split('\n')[0]?.trim() ?? '';
-    cleaned = cleaned
-      .replace(/^[-*•]\s+/, '')
-      .replace(/^["'`‘’“”]|["'`‘’“”]$/g, '')
-      .replace(/^(label|summary)\s*:\s*/i, '')
-      .trim();
-    return cleaned.length > MAX_SUMMARY_LENGTH
-      ? cleaned.slice(0, MAX_SUMMARY_LENGTH).trim()
-      : cleaned || null;
-  } catch (err) {
-    log.debug({ err: err instanceof Error ? err.message : String(err) }, 'tool-summary: error');
-    return null;
-  }
-}

apps/server/src/services/inference/turn-config.ts

@@ -0,0 +1,33 @@
+// P5 (SPLIT SKETCH 5): pure per-turn configuration resolved once at the top of
+// runAssistantTurn. No I/O — just the cap math + budget lookup so it can be
+// unit-tested without a DB or broker.
+
+import type { Agent } from '../../types/api.js';
+import { resolveToolBudget } from './budget.js';
+
+// v1.14.0: hard ceiling on the number of stream-and-tool iterations per
+// user-message turn. Per-agent cap via agent.steps is the primary knob;
+// MAX_STEPS is the safety ceiling. 200 is 4x the effective budget ceiling
+// (50 tool calls) — in practice budget fires first unless the model makes
+// many 0-tool-call iterations (which exit the loop via the non-tool finish
+// path anyway).
+export const MAX_STEPS = 200;
+
+export interface TurnConfig {
+  // min(agent.steps ?? Infinity, MAX_STEPS). The while loop runs while
+  // stepNumber < effectiveCap.
+  effectiveCap: number;
+  // cumulative tool-call budget for the turn (resolveToolBudget).
+  budget: number;
+  // effectiveCap === 0 → the model responds text-only (no tool execution).
+  isTextOnly: boolean;
+}
+
+export function resolveTurnConfig(agent: Agent | null): TurnConfig {
+  const budget = resolveToolBudget(agent);
+  // v1.14.0: effectiveCap = min(agent.steps ?? Infinity, MAX_STEPS).
+  // steps: 0 means "no tool calls allowed" — the first stream phase runs but
+  // any tool calls it emits are not executed (finalize as text-only).
+  const effectiveCap = Math.min(agent?.steps ?? Infinity, MAX_STEPS);
+  return { effectiveCap, budget, isTextOnly: effectiveCap === 0 };
+}

apps/server/src/services/inference/turn.ts

@@ -1,33 +1,21 @@
-import type { FastifyBaseLogger } from 'fastify';
-import type { Sql } from '../../db.js';
-import type { Config } from '../../config.js';
 import type {
   Agent,
-  ErrorReason,
   Message,
-  MessageMetadata,
   Project,
   Session,
-  ToolCall,
   UserStreamFrame,
 } from '../../types/api.js';
-import { ALL_TOOLS } from '../tools.js';
 import { resolveProjectRoot } from '../path_guard.js';
 import { maybeAutoNameChat } from '../auto_name.js';
 import { rewriteSearchQuery } from '../task-search-rewrite.js';
 import { getAgentById } from '../agents.js';
 import * as compaction from '../compaction.js';
-import type { Broker } from '../broker.js';
-import { resolveToolBudget } from './budget.js';
+import { resolveTurnConfig } from './turn-config.js';
+import { decideStep, decidePostToolAction } from './step-decision.js';
 import {
-  detectDoomLoop,
-} from './sentinels.js';
-import {
-  detectMistakePattern,
   freshMistakeState,
   recordStep,
   MISTAKE_RECOVERY_NOTE,
-  type MistakeState,
 } from './mistake-tracker.js';
 import {
   buildMessagesPayload,
@@ -35,13 +23,19 @@ import {
 } from './payload.js';
 import {
   finalizeCompletion,
+  finalizeEmpty,
   handleAbortOrError,
 } from './error-handler.js';
 import {
   executeStreamPhase,
 } from './stream-phase.js';
 import { executeToolPhase, type ToolPhaseResult } from './tool-phase.js';
-import type { StreamPhaseState } from './types.js';
+import type {
+  InferenceContext,
+  StreamPhaseState,
+  StreamResult,
+  TurnArgs,
+} from './types.js';
 import {
   runCapHitSummary,
   runDoomLoopSummary,
@@ -49,121 +43,24 @@ import {
   insertMistakeRecoverySentinel,
 } from './sentinel-summaries.js';
 
-// v1.14.0: hard ceiling on the number of stream-and-tool iterations per
-// user-message turn. Per-agent cap via agent.steps is the primary knob;
-// MAX_STEPS is the safety ceiling. 200 is 4x the effective budget ceiling
-// (50 tool calls) — in practice budget fires first unless the model makes
-// many 0-tool-call iterations (which exit the loop via the non-tool finish
-// path anyway).
-export const MAX_STEPS = 200;
+// P5: MAX_STEPS moved to ./turn-config.ts (with resolveTurnConfig). Re-exported
+// here so the public surface (index.ts → './turn.js') is unchanged.
+export { MAX_STEPS } from './turn-config.js';
 
 // v1.12.4: re-exported so external callers (tests, future consumers) keep
 // importing from services/inference.js as the public surface.
 export { detectDoomLoop, DOOM_LOOP_THRESHOLD } from './sentinels.js';
 export { buildMessagesPayload } from './payload.js';
 
-export interface InferenceFrame {
-  type:
-    | 'message_started'
-    | 'delta'
-    | 'tool_call'
-    | 'tool_result'
-    | 'message_complete'
-    | 'usage'
-    | 'messages_deleted'
-    | 'session_renamed'
-    | 'chat_renamed'
-    | 'error';
-  message_id?: string;
-  message_ids?: string[];
-  chat_id?: string;
-  tool_message_id?: string;
-  tool_call_id?: string;
-  // v1.8.2: 'system' added so cap-hit sentinel messages can announce themselves
-  // through the normal message_started → delta → message_complete sequence.
-  role?: 'assistant' | 'tool' | 'user' | 'system';
-  content?: string;
-  tool_call?: ToolCall;
-  output?: unknown;
-  truncated?: boolean;
-  error?: string;
-  // v1.8.2: structured error reason. Set on `type: 'error'` so the UI can
-  // surface a specific message; `error` stays the human-readable text.
-  reason?: ErrorReason;
-  // v1.8.2: piggybacks on `message_complete` so static or terminally-resolved
-  // messages can carry their persisted metadata to the live stream without a
-  // refetch (sentinels carry { kind: 'cap_hit', ... }; failed messages carry
-  // { kind: 'error', ... }).
-  metadata?: MessageMetadata | null;
-  tokens_used?: number | null;
-  ctx_used?: number | null;
-  ctx_max?: number | null;
-  completion_tokens?: number | null;
-  started_at?: string | null;
-  finished_at?: string | null;
-  model?: string;
-  session_id?: string;
-  name?: string;
-}
-
-export type FramePublisher = (sessionId: string, frame: InferenceFrame) => void;
-
-export interface InferenceContext {
-  sql: Sql;
-  config: Config;
-  log: FastifyBaseLogger;
-  publish: FramePublisher;
-  publishUser: (frame: UserStreamFrame) => void;
-  // v1.11: passed through so compaction.process can publish 'compacted'
-  // frames on the same session WS channel useSessionStream subscribes to.
-  // Compaction is the only path that needs the raw broker handle (regular
-  // inference goes through `publish`); keeping a separate field avoids
-  // tempting other code paths into bypassing the session-id binding.
-  broker: Broker;
-}
-
 // v1.12.4: payload assembly extracted to ./inference/payload.ts (tests
 // import buildMessagesPayload from this module, so a re-export below
 // preserves the public surface). Stream + tool phases extracted to
 // ./inference/stream-phase.ts and ./inference/tool-phase.ts.
-
-export interface StreamResult {
-  finishReason: string | null;
-  content: string;
-  toolCalls: ToolCall[];
-  promptTokens: number | null;
-  completionTokens: number | null;
-  // v1.13.1-C: reasoning text accumulated across reasoning-delta parts.
-  // Empty string when the model doesn't emit reasoning (most cases).
-  reasoning: string;
-}
-
-
-export interface TurnArgs {
-  sessionId: string;
-  chatId: string;
-  assistantMessageId: string;
-  // v1.8.2: cumulative tool calls executed this run. Compared against the
-  // resolved budget at the top of each turn. Replaces the older `depth`
-  // counter (which counted iterations, not invocations).
-  toolsUsed: number;
-  // v1.11.6: ordered tool calls executed in this user-message turn (across
-  // recursive runAssistantTurn invocations). Reset to [] at user-message
-  // boundaries by runInference, same as toolsUsed. Doom-loop check at the
-  // top of runAssistantTurn slices the last DOOM_LOOP_THRESHOLD entries.
-  recentToolCalls: ToolCall[];
-  // v#12 MistakeTracker: heterogeneous-failure recovery state. Loop-local,
-  // reset per runInference (user-message boundary) like recentToolCalls. Folds
-  // tool-phase outcomes via recordStep each iteration; detectMistakePattern
-  // gates the nudge/escalate decision.
-  mistakeTracker: MistakeState;
-  // v#12: transient model-facing recovery note set when a nudge fires. Consumed
-  // (appended as a role:'system' message + cleared) on the NEXT payload build.
-  // Never persisted — mirrors how the cap-hit/doom-loop notes live only inside
-  // the summary call's messages array.
-  pendingRecoveryNote?: string;
-  signal: AbortSignal | undefined;
-}
+//
+// P5: the shared pipeline types (InferenceFrame / FramePublisher /
+// InferenceContext / StreamResult / TurnArgs) moved to ./types.js to break the
+// turn.ts type-hub-and-leaf near-cycle. They are re-exported from there via
+// inference/index.ts for the public surface.
 
 
 export async function runAssistantTurn(
@@ -184,17 +81,13 @@ export async function runAssistantTurn(
   const agent = session.agent_id
     ? await getAgentById(project.path, session.agent_id)
     : null;
-  const budget = resolveToolBudget(agent);
-
-  // v1.14.0: effectiveCap = min(agent.steps ?? Infinity, MAX_STEPS).
-  // steps: 0 means "no tool calls allowed" — the first stream phase runs
-  // but if it emits tool calls they are not executed (finalize as text-only).
-  const effectiveCap = Math.min(agent?.steps ?? Infinity, MAX_STEPS);
+  // P5: pure per-turn config (budget + cap math + text-only flag).
+  const { effectiveCap, budget, isTextOnly } = resolveTurnConfig(agent);
 
   // steps: 0 special case — model responds text-only. The while loop would
   // never enter (effectiveCap === 0), so we handle it explicitly before the
   // loop. The model always gets at least one chance to respond with text.
-  if (effectiveCap === 0) {
+  if (isTextOnly) {
     const loaded = await loadContext(ctx.sql, sessionId, chatId);
     if (loaded) {
       await runTextOnlyTurn(ctx, args, loaded.session, loaded.project, loaded.history, agent);
@@ -214,20 +107,18 @@ export async function runAssistantTurn(
   let pendingRecoveryNote: string | undefined = args.pendingRecoveryNote;
 
   while (stepNumber < effectiveCap) {
-    // ---- doom-loop check (moved from top-of-function) ----
-    const loop = detectDoomLoop(recentToolCalls);
-    if (loop) {
+    // ---- top-of-loop gate: doom-loop, then budget (pure decision) ----
+    const decision = decideStep({ recentToolCalls, toolsUsed, budget });
+    if (decision.kind === 'doom') {
       // Need fresh history for the summary.
       const loaded = await loadContext(ctx.sql, sessionId, chatId);
       if (loaded) {
         const iterArgs: TurnArgs = { sessionId, chatId, assistantMessageId, toolsUsed, recentToolCalls, mistakeTracker, signal };
-        await runDoomLoopSummary(ctx, iterArgs, loaded.session, loaded.project, loaded.history, agent, loop);
+        await runDoomLoopSummary(ctx, iterArgs, loaded.session, loaded.project, loaded.history, agent, decision.loop);
       }
       break;
     }
-
-    // ---- budget check (moved from top-of-function) ----
-    if (toolsUsed >= budget) {
+    if (decision.kind === 'budget') {
       const loaded = await loadContext(ctx.sql, sessionId, chatId);
       if (loaded) {
         const iterArgs: TurnArgs = { sessionId, chatId, assistantMessageId, toolsUsed, recentToolCalls, mistakeTracker, signal };
@@ -235,6 +126,7 @@ export async function runAssistantTurn(
       }
       break;
     }
+    // decision.kind === 'stream' → proceed with compaction + stream + tools.
 
     // ---- compaction check ----
     // v1.11: if the prior turn flagged this chat for compaction, run it
@@ -345,19 +237,17 @@ export async function runAssistantTurn(
       recordStep(mistakeTracker, o);
     }
 
-    if (toolPhaseResult.action !== 'continue') {
-      // 'paused' (user input) or 'synthesis_done' — stop the loop. The turn is
-      // already ending, so neither a nudge nor an escalate would change the
-      // control flow; we skip the mistake decision here.
+    // v#12 MistakeTracker: post-tool decision (pure). 'stop' = the tool phase
+    // returned a non-'continue' action ('paused' for user input, or
+    // 'synthesis_done') — neither a nudge nor an escalate would change the
+    // control flow, so the mistake check is skipped. On 'continue' the
+    // heterogeneous-failure pattern gates nudge/escalate/continue. Complements
+    // the doom-loop gate above, which only catches *identical* repeats.
+    const post = decidePostToolAction(toolPhaseResult.action, mistakeTracker);
+    if (post === 'stop') {
       break;
     }
-
-    // v#12 MistakeTracker: heterogeneous-failure decision. Only evaluated on
-    // the 'continue' path (the only case where the loop would otherwise
-    // proceed to another step). Complements the doom-loop check above, which
-    // only catches *identical* repeats.
-    const mistake = detectMistakePattern(mistakeTracker);
-    if (mistake === 'nudge') {
+    if (post === 'nudge') {
       // Soft intervention: inject model-facing recovery guidance into the NEXT
       // step's payload, drop a UI sentinel, bump nudges, reset the streak, and
       // continue. The note is consumed (and cleared) at the top of the next
@@ -379,23 +269,16 @@ export async function runAssistantTurn(
       assistantMessageId = toolPhaseResult.nextAssistantId!;
       continue;
     }
-    if (mistake === 'escalate') {
+    if (post === 'escalate') {
       // The nudge didn't break the failure run — stop the turn (cap-hit-style)
       // to avoid burning the whole step budget on heterogeneous failures. The
-      // next assistant row is still 'streaming'; finalize it as a short note so
-      // the slot doesn't dangle, then drop the escalate sentinel.
+      // next assistant row is still 'streaming'; finalize it as an empty
+      // complete row so the slot doesn't dangle, then drop the escalate
+      // sentinel.
       const failureKinds = [...mistakeTracker.run];
       assistantMessageId = toolPhaseResult.nextAssistantId!;
-      await ctx.sql`
-        UPDATE messages
-        SET content = '', status = 'complete', finished_at = clock_timestamp()
-        WHERE id = ${assistantMessageId}
-      `;
-      ctx.publish(sessionId, {
-        type: 'message_complete',
-        message_id: assistantMessageId,
-        chat_id: chatId,
-      });
+      const escalateArgs: TurnArgs = { sessionId, chatId, assistantMessageId, toolsUsed, recentToolCalls, mistakeTracker, signal };
+      await finalizeEmpty(ctx, escalateArgs);
       await insertMistakeRecoverySentinel(ctx, sessionId, chatId, {
         failureKinds,
         count: failureKinds.length,
@@ -562,4 +445,3 @@ export function createInferenceRunner(
   };
 }
 
-export const _toolNames = ALL_TOOLS.map((t) => t.name);

apps/server/src/services/inference/types.ts

@@ -1,6 +1,25 @@
 // v1.12.4: shared inter-phase types/constants for the extracted phase files.
 // Lives here so stream-phase, tool-phase, and the summary functions still in
 // inference.ts can all reference the same definitions without circular imports.
+//
+// P5: the shared pipeline types (InferenceContext / TurnArgs / StreamResult /
+// InferenceFrame / FramePublisher) moved here from turn.ts. turn.ts was both the
+// type hub (every phase imported these from './turn.js') AND the orchestration
+// leaf (it imports functions back from payload/stream-phase/tool-phase/
+// error-handler/sentinel-summaries) — a hub-and-leaf near-cycle. Hosting the
+// shared types here (this module imports no inference functions) breaks it.
+
+import type { FastifyBaseLogger } from 'fastify';
+import type { Sql } from '../../db.js';
+import type { Config } from '../../config.js';
+import type {
+  ErrorReason,
+  MessageMetadata,
+  ToolCall,
+  UserStreamFrame,
+} from '../../types/api.js';
+import type { Broker } from '../broker.js';
+import type { MistakeState } from './mistake-tracker.js';
 
 export interface StreamPhaseState {
   accumulated: string;
@@ -11,3 +30,100 @@ export interface StreamPhaseState {
 // executeStreamPhase, runCapHitSummary, and runDoomLoopSummary — every site
 // that does a debounced content flush during streaming.
 export const DB_FLUSH_INTERVAL_MS = 500;
+
+export interface InferenceFrame {
+  type:
+    | 'message_started'
+    | 'delta'
+    | 'tool_call'
+    | 'tool_result'
+    | 'message_complete'
+    | 'usage'
+    | 'messages_deleted'
+    | 'session_renamed'
+    | 'chat_renamed'
+    | 'error';
+  message_id?: string;
+  message_ids?: string[];
+  chat_id?: string;
+  tool_message_id?: string;
+  tool_call_id?: string;
+  // v1.8.2: 'system' added so cap-hit sentinel messages can announce themselves
+  // through the normal message_started → delta → message_complete sequence.
+  role?: 'assistant' | 'tool' | 'user' | 'system';
+  content?: string;
+  tool_call?: ToolCall;
+  output?: unknown;
+  truncated?: boolean;
+  error?: string;
+  // v1.8.2: structured error reason. Set on `type: 'error'` so the UI can
+  // surface a specific message; `error` stays the human-readable text.
+  reason?: ErrorReason;
+  // v1.8.2: piggybacks on `message_complete` so static or terminally-resolved
+  // messages can carry their persisted metadata to the live stream without a
+  // refetch (sentinels carry { kind: 'cap_hit', ... }; failed messages carry
+  // { kind: 'error', ... }).
+  metadata?: MessageMetadata | null;
+  tokens_used?: number | null;
+  ctx_used?: number | null;
+  ctx_max?: number | null;
+  completion_tokens?: number | null;
+  started_at?: string | null;
+  finished_at?: string | null;
+  model?: string;
+  session_id?: string;
+  name?: string;
+}
+
+export type FramePublisher = (sessionId: string, frame: InferenceFrame) => void;
+
+export interface InferenceContext {
+  sql: Sql;
+  config: Config;
+  log: FastifyBaseLogger;
+  publish: FramePublisher;
+  publishUser: (frame: UserStreamFrame) => void;
+  // v1.11: passed through so compaction.process can publish 'compacted'
+  // frames on the same session WS channel useSessionStream subscribes to.
+  // Compaction is the only path that needs the raw broker handle (regular
+  // inference goes through `publish`); keeping a separate field avoids
+  // tempting other code paths into bypassing the session-id binding.
+  broker: Broker;
+}
+
+export interface StreamResult {
+  finishReason: string | null;
+  content: string;
+  toolCalls: ToolCall[];
+  promptTokens: number | null;
+  completionTokens: number | null;
+  // v1.13.1-C: reasoning text accumulated across reasoning-delta parts.
+  // Empty string when the model doesn't emit reasoning (most cases).
+  reasoning: string;
+}
+
+export interface TurnArgs {
+  sessionId: string;
+  chatId: string;
+  assistantMessageId: string;
+  // v1.8.2: cumulative tool calls executed this run. Compared against the
+  // resolved budget at the top of each turn. Replaces the older `depth`
+  // counter (which counted iterations, not invocations).
+  toolsUsed: number;
+  // v1.11.6: ordered tool calls executed in this user-message turn (across
+  // recursive runAssistantTurn invocations). Reset to [] at user-message
+  // boundaries by runInference, same as toolsUsed. Doom-loop check at the
+  // top of runAssistantTurn slices the last DOOM_LOOP_THRESHOLD entries.
+  recentToolCalls: ToolCall[];
+  // v#12 MistakeTracker: heterogeneous-failure recovery state. Loop-local,
+  // reset per runInference (user-message boundary) like recentToolCalls. Folds
+  // tool-phase outcomes via recordStep each iteration; detectMistakePattern
+  // gates the nudge/escalate decision.
+  mistakeTracker: MistakeState;
+  // v#12: transient model-facing recovery note set when a nudge fires. Consumed
+  // (appended as a role:'system' message + cleared) on the NEXT payload build.
+  // Never persisted — mirrors how the cap-hit/doom-loop notes live only inside
+  // the summary call's messages array.
+  pendingRecoveryNote?: string;
+  signal: AbortSignal | undefined;
+}

apps/server/src/services/message-columns.ts

@@ -0,0 +1,15 @@
+// Shared column projections for queries against the messages_with_parts view.
+// All sites that read the full Message wire shape for route responses use
+// MESSAGE_COLUMNS. The inference load path uses INFERENCE_MESSAGE_COLUMNS —
+// it adds reasoning_parts but omits the compaction-display fields
+// (summary, tail_start_id, compacted_at, model) that only the UI needs.
+
+export const MESSAGE_COLUMNS =
+  'id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq, ' +
+  'tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata, ' +
+  'summary, tail_start_id, compacted_at, model';
+
+export const INFERENCE_MESSAGE_COLUMNS =
+  'id, session_id, chat_id, role, content, kind, tool_calls, tool_results, status, last_seq, ' +
+  'tokens_used, ctx_used, ctx_max, started_at, finished_at, created_at, metadata, ' +
+  'reasoning_parts';

apps/server/src/services/model-context.ts

@@ -18,8 +18,6 @@
 
 export interface ModelContext {
   n_ctx: number;
-  total_slots: number;
-  fetched_at: number;
 }
 
 const NEGATIVE_TTL_MS = 60_000;
@@ -77,19 +75,13 @@ export async function getModelContext(model: string): Promise<ModelContext | nul
     }
     const body = (await res.json()) as {
       default_generation_settings?: { n_ctx?: number };
-      total_slots?: number;
     };
     const n_ctx = body?.default_generation_settings?.n_ctx;
     if (typeof n_ctx !== 'number' || n_ctx <= 0) {
       negativeCache.set(model, Date.now());
       return null;
     }
-    // total_slots is informational; default to 1 if missing rather than
-    // reject the whole response. Most local llama-swap setups run a
-    // single slot anyway.
-    const total_slots =
-      typeof body?.total_slots === 'number' && body.total_slots > 0 ? body.total_slots : 1;
-    const entry: ModelContext = { n_ctx, total_slots, fetched_at: Date.now() };
+    const entry: ModelContext = { n_ctx };
     positiveCache.set(model, entry);
     // Clear any stale negative entry so a future query sees the positive
     // hit cleanly (otherwise the negative TTL never expires from the map).

apps/server/src/services/read_tab_by_number.ts

@@ -3,7 +3,7 @@
 // stored in the session's workspace_panes envelope (WorkspaceState.tabNumbers),
 // keyed by chat id. Lives in its own file (not appended to tools.ts) so tests
 // can import the executor directly without dragging in the whole tool registry.
-// Registered in tools.ts ALL_TOOLS + READ_ONLY_TOOL_NAMES.
+// Registered in tools.ts ALL_TOOLS.
 
 import { z } from 'zod';
 import type { Sql } from '../db.js';

apps/server/src/services/skills.ts

@@ -1,6 +1,7 @@
 import { promises as fs } from 'node:fs';
 import { join, isAbsolute, basename } from 'node:path';
 import { pathGuard, PathScopeError } from './path_guard.js';
+import { stripQuotes } from '../utils/string-utils.js';
 
 // Batch 9.6: read-only skill library. Folders under /data/skills/<group>/<skill>/
 // contain a SKILL.md with YAML frontmatter (name + description) and a markdown
@@ -44,13 +45,6 @@ interface Frontmatter {
   description?: string;
 }
 
-function stripQuotes(s: string): string {
-  if (s.length >= 2 && (s[0] === '"' || s[0] === "'") && s[0] === s[s.length - 1]) {
-    return s.slice(1, -1);
-  }
-  return s;
-}
-
 function parseFrontmatter(yaml: string): Frontmatter {
   const fm: Frontmatter = {};
   for (const raw of yaml.split('\n')) {

apps/server/src/services/synthesisPipeline.ts

@@ -24,12 +24,12 @@ import { TOOLS_BY_NAME } from './tools.js';
 import { streamCompletion } from './inference/stream-phase.js';
 import { SYNTHESIS_SYSTEM_PROMPT } from './synthesisPrompt.js';
 import { insertParts } from './inference/parts.js';
-import * as modelContext from './model-context.js';
+import { finalizeStreamedRow } from './inference/error-handler.js';
 import { readTruncation } from './truncate.js';
 
 import type { Session } from '../types/api.js';
 import type { OpenAiMessage } from './inference/payload.js';
-import type { InferenceContext, TurnArgs } from './inference/turn.js';
+import type { InferenceContext, TurnArgs } from './inference/types.js';
 
 export const SYNTHESIS_TOOLS: ReadonlySet<string> = new Set([
   'get_codebase_overview',
@@ -192,44 +192,28 @@ export async function runSynthesisPass(p: SynthesisParams): Promise<boolean> {
       combinedSignal,
     );
 
-    const mctx = await modelContext.getModelContext(p.session.model);
-    const nCtx = mctx?.n_ctx ?? null;
-    const [updated] = await p.ctx.sql<
-      {
-        tokens_used: number | null;
-        ctx_used: number | null;
-        ctx_max: number | null;
-        finished_at: string | null;
-      }[]
-    >`
-      UPDATE messages
-      SET content = ${streamResult.content},
-          status = 'complete',
-          tokens_used = ${streamResult.completionTokens},
-          ctx_used = ${streamResult.promptTokens},
-          ctx_max = ${nCtx},
-          finished_at = clock_timestamp()
-      WHERE id = ${synthMessageId}
-      RETURNING tokens_used, ctx_used, ctx_max, finished_at
-    `;
-    await insertParts(p.ctx.sql, [
-      {
-        message_id: synthMessageId,
-        sequence: 0,
-        kind: 'synthesis',
-        payload: { text: streamResult.content },
-      },
-    ]);
-    p.ctx.publish(p.args.sessionId, {
-      type: 'message_complete',
-      message_id: synthMessageId,
-      chat_id: p.args.chatId,
-      tokens_used: updated?.tokens_used ?? null,
-      ctx_used: updated?.ctx_used ?? null,
-      ctx_max: updated?.ctx_max ?? null,
-      started_at: startedAt,
-      finished_at: updated?.finished_at ?? null,
+    // P5: the n_ctx lookup + complete UPDATE + message_complete frame are the
+    // shared success-finalize atom (finalizeStreamedRow). beforeComplete writes
+    // the kind='synthesis' part in the original order (UPDATE → insertParts →
+    // message_complete), preserving timing exactly.
+    await finalizeStreamedRow(p.ctx, {
+      sessionId: p.args.sessionId,
+      chatId: p.args.chatId,
+      messageId: synthMessageId,
       model: p.session.model,
+      content: streamResult.content,
+      completionTokens: streamResult.completionTokens,
+      promptTokens: streamResult.promptTokens,
+      startedAt,
+      beforeComplete: () =>
+        insertParts(p.ctx.sql, [
+          {
+            message_id: synthMessageId!,
+            sequence: 0,
+            kind: 'synthesis',
+            payload: { text: streamResult.content },
+          },
+        ]),
     });
     p.ctx.publishUser({
       type: 'chat_status',

apps/server/src/services/task-summary.ts

@@ -1,24 +0,0 @@
-import { taskModelCompletion } from './task-model.js';
-
-const SYSTEM_PROMPT =
-  'Summarize this conversation in one sentence, 15 words max. No quotes, no prefix.';
-
-const MAX_INPUT_CHARS = 1000;
-
-export async function oneLineSummary(
-  messages: Array<{ role: string; content: string }>,
-): Promise<string> {
-  const lastPairs = messages.slice(-6);
-  let input = lastPairs
-    .map((m) => `${m.role}: ${m.content}`)
-    .join('\n');
-  if (input.length > MAX_INPUT_CHARS) {
-    input = input.slice(0, MAX_INPUT_CHARS);
-  }
-  return taskModelCompletion({
-    system: SYSTEM_PROMPT,
-    user: input,
-    maxTokens: 30,
-    temperature: 0.3,
-  });
-}

apps/server/src/services/task-tags.ts

@@ -1,22 +0,0 @@
-import { taskModelCompletion } from './task-model.js';
-
-const SYSTEM_PROMPT =
-  'You tag chat sessions. Reply with 1 to 3 lowercase tags separated by commas. Tags should describe the topic. No explanation. Examples: "docker, deployment", "python, debugging", "react, styling".';
-
-export async function suggestTags(
-  userMessage: string,
-  assistantReply: string,
-): Promise<string[]> {
-  const input = `User: ${userMessage.slice(0, 300)}\nAssistant: ${assistantReply.slice(0, 300)}`;
-  const result = await taskModelCompletion({
-    system: SYSTEM_PROMPT,
-    user: input,
-    maxTokens: 30,
-    temperature: 0.3,
-  });
-  if (result.length === 0) return [];
-  return result
-    .split(',')
-    .map((t) => t.trim().toLowerCase())
-    .filter((t) => t.length > 0 && t.length <= 30);
-}

apps/server/src/services/tools.ts

@@ -1,844 +1,46 @@
-import { readFile, readdir, stat } from 'node:fs/promises';
-import { resolve, basename, relative } from 'node:path';
-import { z } from 'zod';
-import type { Sql } from '../db.js';
-import { pathGuard, PathScopeError } from './path_guard.js';
-import { isSecretPath, SecretBlockedError, filterSecretEntries } from './secret_guard.js';
-import { grep as fileOpsGrep, findFiles as fileOpsFindFiles } from './file_ops.js';
-import { getGitMeta } from './git_meta.js';
-import { findSkills, getSkillBody, getSkillResource } from './skills.js';
-import { webSearch } from './web_search.js';
-import { webFetch } from './web_fetch.js';
-import { readTruncation, truncateIfNeeded } from './truncate.js';
-// v1.12 Track B.2: codecontext tools. 8 wrappers re-exported from
-// tools/codecontext/index.ts. Each calls into services/codecontext_client.ts
-// which talks to the codecontext sidecar at http://codecontext:8080.
-import {
-  getCodebaseOverview,
-  getFileAnalysis,
-  getSymbolInfo,
-  searchSymbols,
-  getDependencies,
-  watchChanges,
-  getSemanticNeighborhoods,
-  getFrameworkAnalysis,
-  getBlastRadius,
-  getHotFiles,
-  getRoutes,
-  getMiddleware,
-} from './tools/codecontext/index.js';
-// v1.13.17-cross-repo-reads: cross-repo read grant request tool. Paired
-// with the pause-on-pending-grant branch in inference/tool-phase.ts and the
-// POST /api/chats/:id/grant_read_access endpoint in routes/messages.ts.
-import { requestReadAccess } from './request_read_access.js';
-// v2.6.x: read-only tool that reads a tab's transcript by its session-scoped
-// tab number. Needs DB/session context (ToolExecCtx 4th arg).
-import { readTabByNumber } from './read_tab_by_number.js';
-
-const MAX_FILE_BYTES = 5 * 1024 * 1024;
-const DEFAULT_VIEW_LINES = 200;
-const MAX_GREP_RESULTS = 200;
-const DEFAULT_GREP_RESULTS = 100;
-const MAX_FIND_RESULTS = 200;
-const DEFAULT_FIND_RESULTS = 100;
-const MAX_DIR_ENTRIES = 500;
-
-export interface ToolJsonSchema {
-  type: 'function';
-  function: {
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-  };
-}
-
-// v2.6.x: optional DB/session context threaded into a tool's execute(). Only
-// tools that need to read session-scoped DB state (e.g. read_tab_by_number)
-// use it; every other tool ignores the 4th arg. Kept optional so existing
-// 3-arg execute() implementations stay assignable (apps/coder consumes this
-// type from the compiled dist — the optional param keeps it backward-compatible).
-export interface ToolExecCtx {
-  sql: Sql;
-  sessionId: string;
-}
-
-export interface ToolDef<TInput> {
-  name: string;
-  description: string;
-  inputSchema: z.ZodType<TInput>;
-  jsonSchema: ToolJsonSchema;
-  // v1.13.17-cross-repo-reads: extraRoots is the session's
-  // allowed_read_paths, threaded through executeToolCall in tool-phase.ts.
-  // Only the filesystem tools (view_file, list_dir, grep, find_files,
-  // view_truncated_output) forward it to pathGuard; other tools accept the
-  // arg and ignore it. The execute signature stays compatible with
-  // pre-v1.13.17 callsites because the parameter is optional.
-  // v2.6.x: optional 4th param toolCtx carries DB/session context for tools
-  // that read session-scoped state (read_tab_by_number). Optional so 3-arg
-  // implementations remain assignable.
-  execute(
-    input: TInput,
-    projectRoot: string,
-    extraRoots?: readonly string[],
-    toolCtx?: ToolExecCtx,
-  ): Promise<unknown>;
-}
-
-const ViewFileInput = z.object({
-  path: z.string().min(1),
-  start_line: z.number().int().positive().optional(),
-  end_line: z.number().int().positive().optional(),
-});
-type ViewFileInputT = z.infer<typeof ViewFileInput>;
-
-export const viewFile: ToolDef<ViewFileInputT> = {
-  name: 'view_file',
-  description:
-    "Read a file under the project. Returns first 200 lines by default, or a slice via start_line/end_line (1-indexed, inclusive). Files larger than 5MB are refused. Output is truncated if longer than the slice; the response indicates truncation.",
-  inputSchema: ViewFileInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'view_file',
-      description:
-        "Read a file under the project. Returns first 200 lines by default, or a slice via start_line/end_line (1-indexed, inclusive). Files larger than 5MB are refused.",
-      parameters: {
-        type: 'object',
-        properties: {
-          path: { type: 'string', description: 'absolute or project-relative path' },
-          start_line: { type: 'integer', description: 'first line (1-indexed)' },
-          end_line: { type: 'integer', description: 'last line (1-indexed, inclusive)' },
-        },
-        required: ['path'],
-        additionalProperties: false,
-      },
-    },
-  },
-  async execute(input, projectRoot, extraRoots) {
-    const real = await pathGuard(projectRoot, input.path, extraRoots);
-    // v1.11.7: secret-file deny check. Test the project-relative path
-    // (matches the form continue.dev's patterns expect: basenames + dir
-    // segments). Throw a typed error so executeToolCall in inference.ts
-    // surfaces a clear "blocked" message to the LLM instead of silently
-    // returning content the user wanted hidden.
-    // v1.13.17: when the resolved path is outside the primary projectRoot
-    // (i.e. via an allowed_read_paths grant), `relative()` returns "../…"
-    // which won't match secret-file basename patterns. Re-anchor on the
-    // file's basename so the secret deny still fires across all grant roots.
-    const rel = relative(projectRoot, real);
-    const relPath = rel && !rel.startsWith('..') ? rel : basename(real);
-    if (isSecretPath(relPath)) {
-      throw new SecretBlockedError(relPath);
-    }
-    const s = await stat(real);
-    if (!s.isFile()) {
-      throw new PathScopeError(`not a file: ${input.path}`);
-    }
-    if (s.size > MAX_FILE_BYTES) {
-      throw new Error(`file too large (${s.size} bytes, max ${MAX_FILE_BYTES})`);
-    }
-    const raw = await readFile(real, 'utf8');
-    const lines = raw.split('\n');
-    const total = lines.length;
-    let start = input.start_line ?? 1;
-    let end = input.end_line ?? Math.min(total, start + DEFAULT_VIEW_LINES - 1);
-    if (input.start_line == null && input.end_line == null) {
-      end = Math.min(total, DEFAULT_VIEW_LINES);
-    }
-    if (start < 1) start = 1;
-    if (end > total) end = total;
-    if (end < start) end = start;
-    const slice = lines.slice(start - 1, end);
-    const content = slice.join('\n');
-    const truncated = total > end || start > 1;
-    // v1.13.5: stash the full file on tmpfs so the model can retrieve more
-    // via view_truncated_output(id) without re-reading the file (which it
-    // may not have project-relative-path access to in future agent setups).
-    // raw is bounded by MAX_FILE_BYTES (5MB), within truncateIfNeeded's cap.
-    const wrapped = await truncateIfNeeded({
-      fullContent: raw,
-      slicedContent: content,
-      wasTruncated: truncated,
-    });
-    return {
-      path: relative(projectRoot, real) || basename(real),
-      content: wrapped.content,
-      total_lines: total,
-      returned_lines: [start, end],
-      truncated: wrapped.truncated,
-      ...(wrapped.outputPath ? { outputPath: wrapped.outputPath } : {}),
-    };
-  },
-};
-
-const ListDirInput = z.object({
-  path: z.string().min(1),
-  show_hidden: z.boolean().optional(),
-});
-type ListDirInputT = z.infer<typeof ListDirInput>;
-
-export const listDir: ToolDef<ListDirInputT> = {
-  name: 'list_dir',
-  description: 'List entries in a directory (up to 500). Hidden files excluded unless show_hidden=true.',
-  inputSchema: ListDirInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'list_dir',
-      description:
-        'List entries in a directory (up to 500). Hidden files (dot-prefixed) excluded unless show_hidden=true.',
-      parameters: {
-        type: 'object',
-        properties: {
-          path: { type: 'string' },
-          show_hidden: { type: 'boolean' },
-        },
-        required: ['path'],
-        additionalProperties: false,
-      },
-    },
-  },
-  async execute(input, projectRoot, extraRoots) {
-    const real = await pathGuard(projectRoot, input.path, extraRoots);
-    const s = await stat(real);
-    if (!s.isDirectory()) {
-      throw new PathScopeError(`not a directory: ${input.path}`);
-    }
-    const entries = await readdir(real, { withFileTypes: true });
-    const filtered = input.show_hidden
-      ? entries
-      : entries.filter((e) => !e.name.startsWith('.'));
-    const total = filtered.length;
-    const wasTruncated = total > MAX_DIR_ENTRIES;
-    const relDir = relative(projectRoot, real) || '.';
-    // v1.13.5: when we'd truncate, render the FULL list to tmpfs so
-    // view_truncated_output can serve it. Stat sizes for all entries when
-    // truncating so the stored view matches the visible shape; this is the
-    // one extra cost for big directories, bounded by total entries (which
-    // is itself bounded by filesystem behavior).
-    const processOne = async (e: typeof filtered[number]) => {
-      const child = resolve(real, e.name);
-      let size: number | undefined;
-      if (e.isFile()) {
-        try {
-          const cs = await stat(child);
-          size = cs.size;
-        } catch { /* ignore */ }
-      }
-      return {
-        name: e.name,
-        type: e.isDirectory() ? ('dir' as const) : ('file' as const),
-        ...(size != null ? { size } : {}),
-      };
-    };
-    const slice = filtered.slice(0, MAX_DIR_ENTRIES);
-    const out = await Promise.all(slice.map(processOne));
-    // v1.11.7: filter entries whose project-relative path matches a secret
-    // pattern. The same filter applies to the full-list snapshot below so
-    // the stashed file never holds entries the slice would have hidden.
-    const secretFilter = filterSecretEntries(out, (e) =>
-      relDir === '.' ? e.name : `${relDir}/${e.name}`,
-    );
-    let outputPath: string | undefined;
-    if (wasTruncated) {
-      const fullProcessed = await Promise.all(filtered.map(processOne));
-      const fullFiltered = filterSecretEntries(fullProcessed, (e) =>
-        relDir === '.' ? e.name : `${relDir}/${e.name}`,
-      );
-      // One line per entry, view_truncated_output's line slicing semantics
-      // map cleanly. Format: "<type>\t<name>[\tsize=N]". Header documents
-      // the shape so the model can grep / regex without prior schema lookup.
-      const header = `# list_dir ${relDir} — ${fullFiltered.kept.length} entries`;
-      const lines = [header, ...fullFiltered.kept.map((e) => {
-        const sz = 'size' in e && e.size != null ? `\tsize=${e.size}` : '';
-        return `${e.type}\t${e.name}${sz}`;
-      })];
-      const wrapped = await truncateIfNeeded({
-        fullContent: lines.join('\n'),
-        slicedContent: '',
-        wasTruncated: true,
-      });
-      outputPath = wrapped.outputPath;
-    }
-    return {
-      path: relDir,
-      entries: secretFilter.kept,
-      total: secretFilter.kept.length,
-      truncated: wasTruncated,
-      ...(secretFilter.note ? { pathguard_note: secretFilter.note } : {}),
-      ...(outputPath ? { outputPath } : {}),
-    };
-  },
-};
-
-const GrepInput = z.object({
-  pattern: z.string().min(1),
-  path: z.string().optional(),
-  case_sensitive: z.boolean().optional(),
-  max_results: z.number().int().positive().optional(),
-  hidden: z.boolean().optional(),
-});
-type GrepInputT = z.infer<typeof GrepInput>;
-
-export const grep: ToolDef<GrepInputT> = {
-  name: 'grep',
-  description:
-    'Search file contents with ripgrep. Default path is project root. Max 100 results (200 cap).',
-  inputSchema: GrepInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'grep',
-      description:
-        'Search file contents with ripgrep. Returns up to 100 matches (cap 200). Set hidden=true to include dot-prefixed files.',
-      parameters: {
-        type: 'object',
-        properties: {
-          pattern: { type: 'string' },
-          path: { type: 'string' },
-          case_sensitive: { type: 'boolean' },
-          max_results: { type: 'integer' },
-          hidden: { type: 'boolean' },
-        },
-        required: ['pattern'],
-        additionalProperties: false,
-      },
-    },
-  },
-  async execute(input, projectRoot, extraRoots) {
-    const limit = Math.min(
-      Math.max(input.max_results ?? DEFAULT_GREP_RESULTS, 1),
-      MAX_GREP_RESULTS
-    );
-    // Delegate to file_ops.grep; reshape match objects to preserve LLM output format
-    // (file_ops uses {path, line, text}; tool output uses {path, line, content})
-    const result = await fileOpsGrep(projectRoot, input.pattern, {
-      path: input.path,
-      max_matches: limit,
-      case_sensitive: input.case_sensitive,
-      hidden: input.hidden,
-      extra_roots: extraRoots,
-    });
-    const reshaped = result.matches.map((m) => ({
-      path: m.path,
-      line: m.line,
-      content: m.text,
-    }));
-    // v1.11.7: drop matches whose source file is a known-secret pattern.
-    // file_ops.grep returns project-relative paths, so we feed them straight
-    // into isSecretPath. Multiple matches in the same secret file each get
-    // dropped individually — they all count in the hidden tally.
-    const secretFilter = filterSecretEntries(reshaped, (m) => m.path);
-    return {
-      matches: secretFilter.kept,
-      total: secretFilter.kept.length,
-      truncated: result.truncated,
-      ...(secretFilter.note ? { pathguard_note: secretFilter.note } : {}),
-    };
-  },
-};
-
-const FindFilesInput = z.object({
-  pattern: z.string().min(1),
-  path: z.string().optional(),
-  max_results: z.number().int().positive().optional(),
-});
-type FindFilesInputT = z.infer<typeof FindFilesInput>;
-
-export const findFiles: ToolDef<FindFilesInputT> = {
-  name: 'find_files',
-  description: 'Glob for filenames. Default path is project root. Max 100 results (200 cap).',
-  inputSchema: FindFilesInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'find_files',
-      description:
-        'Glob for filenames under a directory. Default path is project root. Max 100 results (cap 200). Pattern uses standard glob (e.g. "**/*.ts").',
-      parameters: {
-        type: 'object',
-        properties: {
-          pattern: { type: 'string' },
-          path: { type: 'string' },
-          max_results: { type: 'integer' },
-        },
-        required: ['pattern'],
-        additionalProperties: false,
-      },
-    },
-  },
-  async execute(input, projectRoot, extraRoots) {
-    const limit = Math.min(
-      Math.max(input.max_results ?? DEFAULT_FIND_RESULTS, 1),
-      MAX_FIND_RESULTS
-    );
-    // Delegate to file_ops.findFiles; reshape { files, total, truncated } to
-    // preserve the LLM-visible output format { paths, total, truncated }
-    const result = await fileOpsFindFiles(projectRoot, input.pattern, {
-      path: input.path,
-      max_results: limit,
-      extra_roots: extraRoots,
-    });
-    // v1.11.7: drop paths matching secret patterns. The original `total`
-    // from file_ops includes pre-truncation count; we report the visible
-    // count post-filter so the LLM can't infer hidden-count by subtraction.
-    const secretFilter = filterSecretEntries(result.files, (p) => p);
-    return {
-      paths: secretFilter.kept,
-      total: secretFilter.kept.length,
-      truncated: result.truncated,
-      ...(secretFilter.note ? { pathguard_note: secretFilter.note } : {}),
-    };
-  },
-};
-
-// v1.13.5: retrieves the full content of a previously-truncated tool output
-// via the opaque id stamped on the original tool_result. Line-based slicing
-// matches view_file's mental model so the model uses the same affordances.
-// Tmpfs-backed, 7-day TTL (see services/truncate.ts).
-const VIEW_TRUNCATED_DEFAULT_LINES = 200;
-
-const ViewTruncatedOutputInput = z.object({
-  id: z.string().regex(/^tr_[0-9a-v]{12}$/),
-  start_line: z.number().int().positive().optional(),
-  end_line: z.number().int().positive().optional(),
-});
-type ViewTruncatedOutputInputT = z.infer<typeof ViewTruncatedOutputInput>;
-
-export const viewTruncatedOutput: ToolDef<ViewTruncatedOutputInputT> = {
-  name: 'view_truncated_output',
-  description: `Retrieve the full content of a previously-truncated tool output by its outputPath id. When a tool returns { truncated: true, outputPath: "tr_..." }, call this to view the full content. Defaults to the first ${VIEW_TRUNCATED_DEFAULT_LINES} lines. Use start_line and end_line (1-indexed, inclusive) to slice. Stored for 7 days.`,
-  inputSchema: ViewTruncatedOutputInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'view_truncated_output',
-      description: `Retrieve the full content of a previously-truncated tool output by its outputPath id. Returns the first ${VIEW_TRUNCATED_DEFAULT_LINES} lines by default; use start_line/end_line to slice. Stored for 7 days.`,
-      parameters: {
-        type: 'object',
-        properties: {
-          id: { type: 'string', description: 'The outputPath value from an earlier truncated tool result (e.g. "tr_abc123def456").' },
-          start_line: { type: 'integer', description: 'First line (1-indexed). Default 1.' },
-          end_line: { type: 'integer', description: `Last line (1-indexed, inclusive). Default ${VIEW_TRUNCATED_DEFAULT_LINES} lines past start.` },
-        },
-        required: ['id'],
-        additionalProperties: false,
-      },
-    },
-  },
-  // view_truncated_output doesn't touch the filesystem — it pulls from tmpfs
-  // by opaque id. extraRoots is irrelevant here; declared for signature parity
-  // with the v1.13.17 ToolDef contract.
-  async execute(input, _projectRoot, _extraRoots) {
-    const content = await readTruncation(input.id);
-    if (content === null) {
-      return {
-        id: input.id,
-        content: '',
-        truncated: false,
-        error: `No truncation found for id "${input.id}". It may have been pruned (7-day TTL) or never existed.`,
-      };
-    }
-    const lines = content.split('\n');
-    const total = lines.length;
-    let start = input.start_line ?? 1;
-    let end = input.end_line ?? Math.min(total, start + VIEW_TRUNCATED_DEFAULT_LINES - 1);
-    if (start < 1) start = 1;
-    if (end > total) end = total;
-    if (end < start) end = start;
-    const slice = lines.slice(start - 1, end).join('\n');
-    // Re-slicing this view isn't truncation in the dual-write sense — the
-    // model already has the id; no point stashing the slice again.
-    const truncated = total > end || start > 1;
-    return {
-      id: input.id,
-      content: slice,
-      total_lines: total,
-      returned_lines: [start, end],
-      truncated,
-    };
-  },
-};
-
-// v1.8 Level 1 branch awareness: gives the model a read-only view of the
-// project's git state. No path input — operates on the inference-resolved
-// project root via getGitMeta. Subprocess runs with a 2s timeout (see git_meta).
-const GitStatusInput = z.object({}).strict();
-type GitStatusInputT = z.infer<typeof GitStatusInput>;
-
-export const gitStatus: ToolDef<GitStatusInputT> = {
-  name: 'git_status',
-  description:
-    "Returns the current git branch, whether the working tree is dirty, and ahead/behind counts vs upstream. Read-only. Use when you need to know which branch the user is currently working on.",
-  inputSchema: GitStatusInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'git_status',
-      description:
-        'Returns the current git branch, dirty flag, and ahead/behind counts vs upstream. Read-only.',
-      parameters: {
-        type: 'object',
-        properties: {},
-        additionalProperties: false,
-      },
-    },
-  },
-  async execute(_input, projectRoot) {
-    const meta = await getGitMeta(projectRoot);
-    if (meta === null) {
-      return { repo: false, branch: null, is_dirty: false, ahead: 0, behind: 0 };
-    }
-    return { repo: true, ...meta };
-  },
-};
-
-// Batch 9.6: skill_find, skill_use, skill_resource. Lazy-loaded markdown
-// playbooks at /data/skills/. Three tools rather than one to keep each call
-// cheap — the model lists, then loads, then optionally pulls support files.
-
-const SkillFindInput = z.object({
-  query: z.string().optional(),
-});
-type SkillFindInputT = z.infer<typeof SkillFindInput>;
-
-export const skillFind: ToolDef<SkillFindInputT> = {
-  name: 'skill_find',
-  description:
-    'Find skills (markdown playbooks under /data/skills) by name or description. Returns up to 5 matches. Empty query or "*" returns all available skills. Call this first to discover what skills are available.',
-  inputSchema: SkillFindInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'skill_find',
-      description:
-        'Find skills by name or description. Returns up to 5 matches. Empty or "*" returns all.',
-      parameters: {
-        type: 'object',
-        properties: {
-          query: { type: 'string', description: 'substring matched against skill name and description' },
-        },
-        additionalProperties: false,
-      },
-    },
-  },
-  async execute(input) {
-    return await findSkills(input.query ?? '');
-  },
-};
-
-const SkillUseInput = z.object({
-  name: z.string().min(1),
-});
-type SkillUseInputT = z.infer<typeof SkillUseInput>;
-
-export const skillUse: ToolDef<SkillUseInputT> = {
-  name: 'skill_use',
-  description:
-    "Load the full body of a skill's SKILL.md by name. Returns the markdown playbook to follow. Discover names via skill_find. Errors: unknown_skill.",
-  inputSchema: SkillUseInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'skill_use',
-      description: "Load the full body of a skill's SKILL.md by name.",
-      parameters: {
-        type: 'object',
-        properties: {
-          name: { type: 'string', description: 'skill name from skill_find' },
-        },
-        required: ['name'],
-        additionalProperties: false,
-      },
-    },
-  },
-  async execute(input) {
-    const body = await getSkillBody(input.name);
-    if (body === null) {
-      return { error: 'unknown_skill', message: `unknown skill: ${input.name}` };
-    }
-    return { body };
-  },
-};
-
-const SkillResourceInput = z.object({
-  name: z.string().min(1),
-  path: z.string().min(1),
-});
-type SkillResourceInputT = z.infer<typeof SkillResourceInput>;
-
-export const skillResource: ToolDef<SkillResourceInputT> = {
-  name: 'skill_resource',
-  description:
-    "Read a support file inside a skill's folder (e.g. references/root-cause-tracing.md). Path is relative to the skill folder. Use skill_use to read SKILL.md itself. Errors: unknown_skill, unknown_resource, path_escape.",
-  inputSchema: SkillResourceInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'skill_resource',
-      description: "Read a support file inside a skill's folder. Path is relative to the skill folder.",
-      parameters: {
-        type: 'object',
-        properties: {
-          name: { type: 'string', description: 'skill name' },
-          path: { type: 'string', description: 'relative path under the skill folder' },
-        },
-        required: ['name', 'path'],
-        additionalProperties: false,
-      },
-    },
-  },
-  async execute(input) {
-    const result = await getSkillResource(input.name, input.path);
-    if (!result.ok) {
-      return { error: result.code, message: result.message };
-    }
-    return { content: result.content };
-  },
-};
-
-// Batch 9.7: ask_user_input. Interactive elicitation. The model emits a tool
-// call with 1-3 structured questions; the inference loop PAUSES (does not
-// execute the tool server-side, does not recurse) and waits for the frontend
-// to POST /api/chats/:id/answer_user_input with the user's selections. See
-// routes/messages.ts for the resume path and services/inference.ts for the
-// pause branch in executeToolPhase.
-const AskUserInputInput = z.object({
-  questions: z
-    .array(
-      z.object({
-        question: z.string().min(1).max(200),
-        type: z.enum(['single_select', 'multi_select']),
-        options: z.array(z.string().min(1).max(80)).min(2).max(6),
-      }),
-    )
-    .min(1)
-    .max(3),
-});
-type AskUserInputInputT = z.infer<typeof AskUserInputInput>;
-
-export const askUserInput: ToolDef<AskUserInputInputT> = {
-  name: 'ask_user_input',
-  description:
-    "Ask the user 1-3 structured questions through an inline picker UI. Use when you genuinely need a choice the user must make (e.g. scope, options, preferences) before continuing. Each question has 2-6 options and accepts free-text answers in addition. The tool call pauses the conversation until the user submits — the next assistant turn sees their answers as the tool result. Do not use for trivial yes/no clarifications you could infer; prefer it over multi-paragraph speculation about what the user might want.",
-  inputSchema: AskUserInputInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'ask_user_input',
-      description:
-        'Ask the user 1-3 structured questions through an inline picker. Pauses the conversation until the user answers; the next turn sees their selections.',
-      parameters: {
-        type: 'object',
-        properties: {
-          questions: {
-            type: 'array',
-            minItems: 1,
-            maxItems: 3,
-            items: {
-              type: 'object',
-              properties: {
-                question: { type: 'string', description: '<=200 chars, shown to the user' },
-                type: {
-                  type: 'string',
-                  enum: ['single_select', 'multi_select'],
-                  description: 'single_select = at most one option; multi_select = any subset',
-                },
-                options: {
-                  type: 'array',
-                  minItems: 2,
-                  maxItems: 6,
-                  items: { type: 'string' },
-                  description: '2-6 strings, each <=80 chars; free-text input is always available alongside',
-                },
-              },
-              required: ['question', 'type', 'options'],
-              additionalProperties: false,
-            },
-          },
-        },
-        required: ['questions'],
-        additionalProperties: false,
-      },
-    },
-  },
-  // Server-side no-op. The "execution" of ask_user_input is the user's
-  // response, captured client-side and posted to /api/chats/:id/answer_user_input.
-  // The inference loop detects this tool by name and pauses before reaching
-  // executeToolCall — this fallback only runs if something bypasses that
-  // branch, in which case the pending sentinel matches the pause-path shape.
-  async execute(input) {
-    return { _pending: true, questions: input.questions };
-  },
-};
-
-// v1.13.3: alpha-sorted by tool.name at module load. llama.cpp's prompt
-// cache hits on byte-identical prefixes; the tool list lives near the top
-// of the system prompt, so any order drift would invalidate every cached
-// turn. Single source of truth for ordering lives here — toolJsonSchemas()
-// and TOOLS_BY_NAME inherit it.
-// v1.14.1-mcp-poc: changed from ReadonlyArray to let-bound mutable array
-// so appendMcpTools() can push MCP-discovered tools at startup.
-export let ALL_TOOLS: ToolDef<unknown>[] = [
-  viewFile as ToolDef<unknown>,
-  viewTruncatedOutput as ToolDef<unknown>,
-  listDir as ToolDef<unknown>,
-  grep as ToolDef<unknown>,
-  findFiles as ToolDef<unknown>,
-  gitStatus as ToolDef<unknown>,
-  skillFind as ToolDef<unknown>,
-  skillUse as ToolDef<unknown>,
-  skillResource as ToolDef<unknown>,
-  askUserInput as ToolDef<unknown>,
-  // v1.11.8: web tools. Gated per-chat via session.web_search_enabled
-  // (with project default fallback) — see effectiveTools filter in
-  // services/inference.ts.
-  webSearch as ToolDef<unknown>,
-  webFetch as ToolDef<unknown>,
-  // v1.12 Track B.2: codecontext tools. Backed by the codecontext sidecar
-  // container. All read-only. target_dir is resolved server-side from the
-  // project root in codecontext_client.ts (the LLM never supplies it).
-  getCodebaseOverview as ToolDef<unknown>,
-  getFileAnalysis as ToolDef<unknown>,
-  getSymbolInfo as ToolDef<unknown>,
-  searchSymbols as ToolDef<unknown>,
-  getDependencies as ToolDef<unknown>,
-  watchChanges as ToolDef<unknown>,
-  getSemanticNeighborhoods as ToolDef<unknown>,
-  getFrameworkAnalysis as ToolDef<unknown>,
-  // v1.16: codesight-merge tools. Backed by the same codecontext sidecar.
-  getBlastRadius as ToolDef<unknown>,
-  getHotFiles as ToolDef<unknown>,
-  getRoutes as ToolDef<unknown>,
-  getMiddleware as ToolDef<unknown>,
-  // v1.13.17-cross-repo-reads: paired with the pause-on-pending-grant
-  // branch in tool-phase.ts. Read-only — only ever READS files; the only
-  // state change is appending to sessions.allowed_read_paths via the
-  // grant endpoint, gated by user consent.
-  requestReadAccess as ToolDef<unknown>,
-  // v2.6.x: read a tab's transcript by its session-scoped tab number.
-  // Read-only; uses the ToolExecCtx 4th arg for DB/session access.
-  readTabByNumber as ToolDef<unknown>,
-].sort((a, b) => a.name.localeCompare(b.name));
-
-// v1.8.2: forward-compatible read-only whitelist. An agent whose `tools` is
-// fully contained in this set gets a generous default tool budget (30);
-// anything outside means the agent can mutate state and gets a tighter
-// default (10). Every tool in v1.8.2 happens to be read-only, so the
-// non-RO branch only takes effect once BooCoder lands write tools.
-// Batch 9.6: skill_* added; all still read-only.
-// Batch 9.7: ask_user_input added — it pauses execution but doesn't mutate
-// project state, so it belongs in the read-only set for budget purposes.
-export const READ_ONLY_TOOL_NAMES = [
-  'view_file',
-  'view_truncated_output',
-  'list_dir',
-  'grep',
-  'find_files',
-  'git_status',
-  'skill_find',
-  'skill_use',
-  'skill_resource',
-  'ask_user_input',
-  // v1.11.8: web tools don't mutate project state; counted as read-only
-  // for the budget-tier calculation (BUDGET_READ_ONLY=30) when an agent's
-  // toolset is fully contained in this list.
-  'web_search',
-  'web_fetch',
-  // v1.12 Track B.2: codecontext tools. Read-only — they call the
-  // codecontext sidecar which only analyzes files (never writes).
-  'get_codebase_overview',
-  'get_file_analysis',
-  'get_symbol_info',
-  'search_symbols',
-  'get_dependencies',
-  'watch_changes',
-  'get_semantic_neighborhoods',
-  'get_framework_analysis',
-  // v1.13.17-cross-repo-reads: pauses execution but doesn't mutate project
-  // state directly (the grant endpoint appends to sessions.allowed_read_paths
-  // only with user consent). Belongs in the read-only budget tier.
-  'request_read_access',
-  // v2.6.x: reads a tab's transcript from session-scoped DB state; never
-  // writes. Belongs in the read-only budget tier.
-  'read_tab_by_number',
-] as const;
-
-export let TOOLS_BY_NAME: Record<string, ToolDef<unknown>> = Object.fromEntries(
-  ALL_TOOLS.map((t) => [t.name, t])
-);
-
-// v1.14.1-mcp-poc: append MCP-discovered tools at startup. Called once
-// from index.ts after mcpClient.initialize(). Re-sorts ALL_TOOLS and
-// rebuilds TOOLS_BY_NAME. READ_ONLY_TOOL_NAMES is not rebuilt because
-// it's a const tuple used only for budget-tier checks; MCP tools are
-// individually checked via their category at budget resolution time —
-// they are all read_only by construction (the read-only guard in
-// mcp-client.ts rejects any tool with readOnlyHint: false).
-export function appendMcpTools(mcpTools: ToolDef<unknown>[]): void {
-  if (mcpTools.length === 0) return;
-  ALL_TOOLS = [...ALL_TOOLS, ...mcpTools].sort((a, b) => a.name.localeCompare(b.name));
-  TOOLS_BY_NAME = Object.fromEntries(ALL_TOOLS.map((t) => [t.name, t]));
-}
-
-// v1.13.15-tools: tiered tool loading. BOOCODE_TOOLS env var (`core` |
-// `standard` | `all`) filters the agent's tool whitelist before LLM dispatch.
-// Daily-driver token win on qwen3.6-35b-a3b — the 35B-A3B MoE benefits from
-// any prompt-cache stability win (fewer tools = shorter, more stable tool
-// schemas in the system prompt). Pattern lift from eyaltoledano/claude-task-
-// master (MIT + Commons Clause — pattern only, no code lift).
+// Tool registry barrel. The implementation was split into focused modules
+// under ./tools/ (Sketch 4) while this file stays the stable public surface:
+// every import of './tools.js' and the @boocode/server/tools subpath (consumed
+// by apps/coder) resolves through here unchanged. The exports-map path
+// (dist/services/tools.js) is preserved.
 //
-// The env var is a CEILING. It only narrows; never expands an agent's
-// declared whitelist. Default behavior (var unset) is unchanged: all tools.
-export const CORE_TOOL_NAMES = [
-  'view_file',
-  'list_dir',
-  'grep',
-  'find_files',
-] as const;
+//   ./tools/types.ts     — ToolDef / ToolJsonSchema / ToolExecCtx
+//   ./tools/fs-tools.ts  — filesystem ToolDefs (view_file/list_dir/grep/
+//                          find_files/view_truncated_output)
+//   ./tools/misc-tools.ts— git_status/skill_*/ask_user_input ToolDefs
+//   ./tools/registry.ts  — ALL_TOOLS/TOOLS_BY_NAME (register-through let
+//                          bindings), appendMcpTools, toolJsonSchemas
+//   ./tools/tiers.ts     — CORE/STANDARD names + module-load validation +
+//                          resolveToolTier
+//
+// Re-exporting the `let`-bound ALL_TOOLS / TOOLS_BY_NAME preserves the
+// register-through MCP-discovery contract: appendMcpTools() reassigns the
+// bindings in registry.ts and ESM live bindings make the mutation visible
+// through this barrel to every consumer (incl. apps/coder).
 
-export const STANDARD_TOOL_NAMES = [
-  ...CORE_TOOL_NAMES,
-  'web_search',
-  'web_fetch',
-  'git_status',
-  'get_codebase_overview',
-  'get_file_analysis',
-  'get_symbol_info',
-  'search_symbols',
-  'get_dependencies',
-  'watch_changes',
-  'get_semantic_neighborhoods',
-  'get_framework_analysis',
-] as const;
-
-// Module-load validation: every name in CORE / STANDARD must exist in
-// TOOLS_BY_NAME. Catches typos and stale tier definitions before they reach
-// production; server boot fails loudly rather than silently filtering valid
-// tools out of agent whitelists.
-for (const name of CORE_TOOL_NAMES) {
-  if (!TOOLS_BY_NAME[name]) {
-    throw new Error(`CORE_TOOL_NAMES references unknown tool: '${name}'`);
-  }
-}
-for (const name of STANDARD_TOOL_NAMES) {
-  if (!TOOLS_BY_NAME[name]) {
-    throw new Error(`STANDARD_TOOL_NAMES references unknown tool: '${name}'`);
-  }
-}
-
-export function resolveToolTier(tier: string | undefined): readonly string[] {
-  switch ((tier ?? 'all').toLowerCase()) {
-    case 'core':
-      return CORE_TOOL_NAMES;
-    case 'standard':
-      return STANDARD_TOOL_NAMES;
-    case 'all':
-    default:
-      return ALL_TOOLS.map((t) => t.name);
-  }
-}
-
-export function toolJsonSchemas(): ToolJsonSchema[] {
-  return ALL_TOOLS.map((t) => t.jsonSchema);
-}
+export type { ToolDef, ToolJsonSchema, ToolExecCtx } from './tools/types.js';
+export {
+  viewFile,
+  listDir,
+  grep,
+  findFiles,
+  viewTruncatedOutput,
+} from './tools/fs-tools.js';
+export {
+  gitStatus,
+  skillFind,
+  skillUse,
+  skillResource,
+  askUserInput,
+} from './tools/misc-tools.js';
+export {
+  ALL_TOOLS,
+  TOOLS_BY_NAME,
+  appendMcpTools,
+  toolJsonSchemas,
+} from './tools/registry.js';
+export {
+  CORE_TOOL_NAMES,
+  STANDARD_TOOL_NAMES,
+  resolveToolTier,
+} from './tools/tiers.js';

apps/server/src/services/tools/codecontext/factory.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { ToolDef } from '../types.js';
+import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+
+// Shared factory for the 12 codecontext shim ToolDefs.
+// Each shim provides name/schema/description/jsonParameters/mapArgs; the
+// factory builds the ToolDef and returns both the ToolDef and the standalone
+// execute function (used by tests that inject a custom fetcher).
+export function makeCodecontextTool<TInput>(opts: {
+  name: string;
+  schema: z.ZodType<TInput>;
+  description: string;
+  jsonParameters: Record<string, unknown>;
+  mapArgs: (input: TInput) => Record<string, unknown>;
+}): {
+  toolDef: ToolDef<TInput>;
+  execute: (input: TInput, projectPath: string, fetcher?: typeof fetch) => Promise<CodecontextResponse>;
+} {
+  const { name, schema, description, jsonParameters, mapArgs } = opts;
+
+  async function execute(
+    input: TInput,
+    projectPath: string,
+    fetcher: typeof fetch = fetch,
+  ): Promise<CodecontextResponse> {
+    return callCodecontext({ toolName: name, args: mapArgs(input), projectPath }, fetcher);
+  }
+
+  const toolDef: ToolDef<TInput> = {
+    name,
+    description,
+    inputSchema: schema,
+    jsonSchema: {
+      type: 'function',
+      function: { name, description, parameters: jsonParameters },
+    },
+    async execute(input, projectRoot) {
+      return execute(input, projectRoot);
+    },
+  };
+
+  return { toolDef, execute };
+}

apps/server/src/services/tools/codecontext/get_blast_radius.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetBlastRadiusInput = z.object({
   file_path: z.string().trim().min(1),
@@ -12,40 +11,23 @@ const DESCRIPTION =
   'Use to assess the impact of changing a file — "what breaks if I modify this?" ' +
   'Traverses the import graph in reverse via BFS. Results sorted by distance (closest dependents first).';
 
-export async function executeGetBlastRadius(
-  input: GetBlastRadiusInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  return callCodecontext(
-    { toolName: 'get_blast_radius', args: { file_path: input.file_path }, projectPath },
-    fetcher,
-  );
-}
-
-export const getBlastRadius: ToolDef<GetBlastRadiusInputT> = {
-  name: 'get_blast_radius',
-  description: DESCRIPTION,
-  inputSchema: GetBlastRadiusInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_blast_radius',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          file_path: {
-            type: 'string',
-            description: 'Absolute or project-relative path to the file to analyze.',
-          },
+const { toolDef: getBlastRadius, execute: executeGetBlastRadius } =
+  makeCodecontextTool<GetBlastRadiusInputT>({
+    name: 'get_blast_radius',
+    schema: GetBlastRadiusInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        file_path: {
+          type: 'string',
+          description: 'Absolute or project-relative path to the file to analyze.',
         },
-        required: ['file_path'],
-        additionalProperties: false,
       },
+      required: ['file_path'],
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetBlastRadius(input, projectRoot);
-  },
-};
+    mapArgs: (input) => ({ file_path: input.file_path }),
+  });
+
+export { getBlastRadius, executeGetBlastRadius };

apps/server/src/services/tools/codecontext/get_codebase_overview.ts

@@ -1,10 +1,5 @@
-// v1.12 Track B.2: codecontext wrapper — get_codebase_overview.
-// Pattern mirrors services/web_search.ts: pure executor + ToolDef wrapper.
-// target_dir is supplied by callCodecontext from the resolved project root.
-
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetCodebaseOverviewInput = z.object({
   include_stats: z.boolean().optional(),
@@ -17,43 +12,22 @@ const DESCRIPTION =
   'Tree-sitter coverage: full for JS/Python/Java/Go/Rust/C++. TypeScript symbols are approximate (uses JS grammar). ' +
   'PHP and SQL are not supported — fall back to view_file/grep for those.';
 
-export async function executeGetCodebaseOverview(
-  input: GetCodebaseOverviewInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  return callCodecontext(
-    {
-      toolName: 'get_codebase_overview',
-      args: { include_stats: input.include_stats ?? true },
-      projectPath,
-    },
-    fetcher,
-  );
-}
-
-export const getCodebaseOverview: ToolDef<GetCodebaseOverviewInputT> = {
-  name: 'get_codebase_overview',
-  description: DESCRIPTION,
-  inputSchema: GetCodebaseOverviewInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_codebase_overview',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          include_stats: {
-            type: 'boolean',
-            description: 'Include file count, symbol count, language stats. Defaults to true.',
-          },
+const { toolDef: getCodebaseOverview, execute: executeGetCodebaseOverview } =
+  makeCodecontextTool<GetCodebaseOverviewInputT>({
+    name: 'get_codebase_overview',
+    schema: GetCodebaseOverviewInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        include_stats: {
+          type: 'boolean',
+          description: 'Include file count, symbol count, language stats. Defaults to true.',
         },
-        additionalProperties: false,
       },
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetCodebaseOverview(input, projectRoot);
-  },
-};
+    mapArgs: (input) => ({ include_stats: input.include_stats ?? true }),
+  });
+
+export { getCodebaseOverview, executeGetCodebaseOverview };

apps/server/src/services/tools/codecontext/get_dependencies.ts

@@ -1,8 +1,5 @@
-// v1.12 Track B.2: codecontext wrapper — get_dependencies.
-
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetDependenciesInput = z.object({
   file_path: z.string().trim().optional(),
@@ -16,45 +13,31 @@ const DESCRIPTION =
   'Tree-sitter coverage: full for JS/Python/Java/Go/Rust/C++. TypeScript dependencies are approximate. ' +
   'PHP and SQL are not supported.';
 
-export async function executeGetDependencies(
-  input: GetDependenciesInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  const args: Record<string, unknown> = {
-    direction: input.direction ?? 'both',
-  };
-  if (input.file_path) args['file_path'] = input.file_path;
-  return callCodecontext({ toolName: 'get_dependencies', args, projectPath }, fetcher);
-}
-
-export const getDependencies: ToolDef<GetDependenciesInputT> = {
-  name: 'get_dependencies',
-  description: DESCRIPTION,
-  inputSchema: GetDependenciesInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_dependencies',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          file_path: {
-            type: 'string',
-            description: 'Narrow to a single file. Omit for a project-wide graph.',
-          },
-          direction: {
-            type: 'string',
-            enum: ['incoming', 'outgoing', 'both'],
-            description: 'Which edges to include. Defaults to "both".',
-          },
+const { toolDef: getDependencies, execute: executeGetDependencies } =
+  makeCodecontextTool<GetDependenciesInputT>({
+    name: 'get_dependencies',
+    schema: GetDependenciesInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        file_path: {
+          type: 'string',
+          description: 'Narrow to a single file. Omit for a project-wide graph.',
+        },
+        direction: {
+          type: 'string',
+          enum: ['incoming', 'outgoing', 'both'],
+          description: 'Which edges to include. Defaults to "both".',
         },
-        additionalProperties: false,
       },
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetDependencies(input, projectRoot);
-  },
-};
+    mapArgs: (input) => {
+      const args: Record<string, unknown> = { direction: input.direction ?? 'both' };
+      if (input.file_path) args['file_path'] = input.file_path;
+      return args;
+    },
+  });
+
+export { getDependencies, executeGetDependencies };

apps/server/src/services/tools/codecontext/get_file_analysis.ts

@@ -1,8 +1,5 @@
-// v1.12 Track B.2: codecontext wrapper — get_file_analysis.
-
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetFileAnalysisInput = z.object({
   file_path: z.string().trim().min(1),
@@ -15,44 +12,23 @@ const DESCRIPTION =
   'Tree-sitter coverage: full for JS/Python/Java/Go/Rust/C++. TypeScript symbols are approximate. ' +
   'PHP and SQL are not supported — fall back to view_file for those.';
 
-export async function executeGetFileAnalysis(
-  input: GetFileAnalysisInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  return callCodecontext(
-    {
-      toolName: 'get_file_analysis',
-      args: { file_path: input.file_path },
-      projectPath,
-    },
-    fetcher,
-  );
-}
-
-export const getFileAnalysis: ToolDef<GetFileAnalysisInputT> = {
-  name: 'get_file_analysis',
-  description: DESCRIPTION,
-  inputSchema: GetFileAnalysisInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_file_analysis',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          file_path: {
-            type: 'string',
-            description: 'Absolute or project-relative path to the file.',
-          },
+const { toolDef: getFileAnalysis, execute: executeGetFileAnalysis } =
+  makeCodecontextTool<GetFileAnalysisInputT>({
+    name: 'get_file_analysis',
+    schema: GetFileAnalysisInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        file_path: {
+          type: 'string',
+          description: 'Absolute or project-relative path to the file.',
         },
-        required: ['file_path'],
-        additionalProperties: false,
       },
+      required: ['file_path'],
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetFileAnalysis(input, projectRoot);
-  },
-};
+    mapArgs: (input) => ({ file_path: input.file_path }),
+  });
+
+export { getFileAnalysis, executeGetFileAnalysis };

apps/server/src/services/tools/codecontext/get_framework_analysis.ts

@@ -1,8 +1,5 @@
-// v1.12 Track B.2: codecontext wrapper — get_framework_analysis.
-
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetFrameworkAnalysisInput = z.object({
   framework: z.string().optional(),
@@ -16,43 +13,31 @@ const DESCRIPTION =
   'Tree-sitter coverage: full for JS/Python/Java/Go/Rust/C++. TypeScript is approximate. ' +
   'PHP and SQL are not supported.';
 
-export async function executeGetFrameworkAnalysis(
-  input: GetFrameworkAnalysisInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  const args: Record<string, unknown> = {};
-  if (input.framework) args['framework'] = input.framework;
-  if (input.include_stats !== undefined) args['include_stats'] = input.include_stats;
-  return callCodecontext({ toolName: 'get_framework_analysis', args, projectPath }, fetcher);
-}
-
-export const getFrameworkAnalysis: ToolDef<GetFrameworkAnalysisInputT> = {
-  name: 'get_framework_analysis',
-  description: DESCRIPTION,
-  inputSchema: GetFrameworkAnalysisInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_framework_analysis',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          framework: {
-            type: 'string',
-            description: 'Framework name. Auto-detected if omitted.',
-          },
-          include_stats: {
-            type: 'boolean',
-            description: 'Include component/hook/service counts.',
-          },
+const { toolDef: getFrameworkAnalysis, execute: executeGetFrameworkAnalysis } =
+  makeCodecontextTool<GetFrameworkAnalysisInputT>({
+    name: 'get_framework_analysis',
+    schema: GetFrameworkAnalysisInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        framework: {
+          type: 'string',
+          description: 'Framework name. Auto-detected if omitted.',
+        },
+        include_stats: {
+          type: 'boolean',
+          description: 'Include component/hook/service counts.',
         },
-        additionalProperties: false,
       },
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetFrameworkAnalysis(input, projectRoot);
-  },
-};
+    mapArgs: (input) => {
+      const args: Record<string, unknown> = {};
+      if (input.framework) args['framework'] = input.framework;
+      if (input.include_stats !== undefined) args['include_stats'] = input.include_stats;
+      return args;
+    },
+  });
+
+export { getFrameworkAnalysis, executeGetFrameworkAnalysis };

apps/server/src/services/tools/codecontext/get_hot_files.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetHotFilesInput = z.object({
   limit: z.number().int().min(1).max(100).optional(),
@@ -12,39 +11,22 @@ const DESCRIPTION =
   'Hot files are high-risk change targets — many other files depend on them. ' +
   'Use to identify core modules and assess refactoring risk.';
 
-export async function executeGetHotFiles(
-  input: GetHotFilesInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  return callCodecontext(
-    { toolName: 'get_hot_files', args: input.limit != null ? { limit: input.limit } : {}, projectPath },
-    fetcher,
-  );
-}
-
-export const getHotFiles: ToolDef<GetHotFilesInputT> = {
-  name: 'get_hot_files',
-  description: DESCRIPTION,
-  inputSchema: GetHotFilesInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_hot_files',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          limit: {
-            type: 'number',
-            description: 'Maximum number of files to return (default 20, max 100).',
-          },
+const { toolDef: getHotFiles, execute: executeGetHotFiles } =
+  makeCodecontextTool<GetHotFilesInputT>({
+    name: 'get_hot_files',
+    schema: GetHotFilesInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: 'Maximum number of files to return (default 20, max 100).',
         },
-        additionalProperties: false,
       },
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetHotFiles(input, projectRoot);
-  },
-};
+    mapArgs: (input) => (input.limit != null ? { limit: input.limit } : {}),
+  });
+
+export { getHotFiles, executeGetHotFiles };

apps/server/src/services/tools/codecontext/get_middleware.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetMiddlewareInput = z.object({});
 export type GetMiddlewareInputT = z.infer<typeof GetMiddlewareInput>;
@@ -11,31 +10,17 @@ const DESCRIPTION =
   'import names (@fastify/cors, helmet, etc.) and registration patterns ' +
   '(app.register, app.addHook, app.setErrorHandler).';
 
-export async function executeGetMiddleware(
-  _input: GetMiddlewareInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  return callCodecontext({ toolName: 'get_middleware', args: {}, projectPath }, fetcher);
-}
-
-export const getMiddleware: ToolDef<GetMiddlewareInputT> = {
-  name: 'get_middleware',
-  description: DESCRIPTION,
-  inputSchema: GetMiddlewareInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_middleware',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {},
-        additionalProperties: false,
-      },
+const { toolDef: getMiddleware, execute: executeGetMiddleware } =
+  makeCodecontextTool<GetMiddlewareInputT>({
+    name: 'get_middleware',
+    schema: GetMiddlewareInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetMiddleware(input, projectRoot);
-  },
-};
+    mapArgs: () => ({}),
+  });
+
+export { getMiddleware, executeGetMiddleware };

apps/server/src/services/tools/codecontext/get_routes.ts

@@ -1,6 +1,5 @@
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetRoutesInput = z.object({
   framework: z.string().trim().optional(),
@@ -13,38 +12,26 @@ const DESCRIPTION =
   'with method, path, file, line number, and inferred tags (db, auth, cache). ' +
   'Optional framework filter narrows to "fastify" or "express".';
 
-export async function executeGetRoutes(
-  input: GetRoutesInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  const args: Record<string, unknown> = {};
-  if (input.framework) args.framework = input.framework;
-  return callCodecontext({ toolName: 'get_routes', args, projectPath }, fetcher);
-}
-
-export const getRoutes: ToolDef<GetRoutesInputT> = {
-  name: 'get_routes',
-  description: DESCRIPTION,
-  inputSchema: GetRoutesInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_routes',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          framework: {
-            type: 'string',
-            description: 'Filter to a specific framework: "fastify" or "express". Omit for all.',
-          },
+const { toolDef: getRoutes, execute: executeGetRoutes } =
+  makeCodecontextTool<GetRoutesInputT>({
+    name: 'get_routes',
+    schema: GetRoutesInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        framework: {
+          type: 'string',
+          description: 'Filter to a specific framework: "fastify" or "express". Omit for all.',
         },
-        additionalProperties: false,
       },
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetRoutes(input, projectRoot);
-  },
-};
+    mapArgs: (input) => {
+      const args: Record<string, unknown> = {};
+      if (input.framework) args.framework = input.framework;
+      return args;
+    },
+  });
+
+export { getRoutes, executeGetRoutes };

apps/server/src/services/tools/codecontext/get_semantic_neighborhoods.ts

@@ -1,8 +1,5 @@
-// v1.12 Track B.2: codecontext wrapper — get_semantic_neighborhoods.
-
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetSemanticNeighborhoodsInput = z.object({
   file_path: z.string().trim().optional(),
@@ -20,54 +17,42 @@ const DESCRIPTION =
 
 const DEFAULT_MAX_RESULTS = 10;
 
-export async function executeGetSemanticNeighborhoods(
-  input: GetSemanticNeighborhoodsInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  const args: Record<string, unknown> = {
-    max_results: input.max_results ?? DEFAULT_MAX_RESULTS,
-  };
-  if (input.file_path) args['file_path'] = input.file_path;
-  if (input.include_basic !== undefined) args['include_basic'] = input.include_basic;
-  if (input.include_quality !== undefined) args['include_quality'] = input.include_quality;
-  return callCodecontext({ toolName: 'get_semantic_neighborhoods', args, projectPath }, fetcher);
-}
-
-export const getSemanticNeighborhoods: ToolDef<GetSemanticNeighborhoodsInputT> = {
-  name: 'get_semantic_neighborhoods',
-  description: DESCRIPTION,
-  inputSchema: GetSemanticNeighborhoodsInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_semantic_neighborhoods',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          file_path: {
-            type: 'string',
-            description: 'Anchor file for the neighborhood query. Omit for a project-wide view.',
-          },
-          include_basic: {
-            type: 'boolean',
-            description: 'Include the basic (import-based) neighborhood. Default true.',
-          },
-          include_quality: {
-            type: 'boolean',
-            description: 'Include code-quality metrics for the neighborhood. Default false.',
-          },
-          max_results: {
-            type: 'integer',
-            description: `Cap on neighborhoods returned. Defaults to ${DEFAULT_MAX_RESULTS}.`,
-          },
+const { toolDef: getSemanticNeighborhoods, execute: executeGetSemanticNeighborhoods } =
+  makeCodecontextTool<GetSemanticNeighborhoodsInputT>({
+    name: 'get_semantic_neighborhoods',
+    schema: GetSemanticNeighborhoodsInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        file_path: {
+          type: 'string',
+          description: 'Anchor file for the neighborhood query. Omit for a project-wide view.',
+        },
+        include_basic: {
+          type: 'boolean',
+          description: 'Include the basic (import-based) neighborhood. Default true.',
+        },
+        include_quality: {
+          type: 'boolean',
+          description: 'Include code-quality metrics for the neighborhood. Default false.',
+        },
+        max_results: {
+          type: 'integer',
+          description: `Cap on neighborhoods returned. Defaults to ${DEFAULT_MAX_RESULTS}.`,
         },
-        additionalProperties: false,
       },
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetSemanticNeighborhoods(input, projectRoot);
-  },
-};
+    mapArgs: (input) => {
+      const args: Record<string, unknown> = {
+        max_results: input.max_results ?? DEFAULT_MAX_RESULTS,
+      };
+      if (input.file_path) args['file_path'] = input.file_path;
+      if (input.include_basic !== undefined) args['include_basic'] = input.include_basic;
+      if (input.include_quality !== undefined) args['include_quality'] = input.include_quality;
+      return args;
+    },
+  });
+
+export { getSemanticNeighborhoods, executeGetSemanticNeighborhoods };

apps/server/src/services/tools/codecontext/get_symbol_info.ts

@@ -1,8 +1,5 @@
-// v1.12 Track B.2: codecontext wrapper — get_symbol_info.
-
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const GetSymbolInfoInput = z.object({
   symbol_name: z.string().min(1),
@@ -16,48 +13,36 @@ const DESCRIPTION =
   'Tree-sitter coverage: full for JS/Python/Java/Go/Rust/C++. TypeScript symbols are approximate (uses JS grammar). ' +
   'PHP and SQL are not supported — fall back to grep for those.';
 
-export async function executeGetSymbolInfo(
-  input: GetSymbolInfoInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  const args: Record<string, unknown> = { symbol_name: input.symbol_name };
-  if (input.file_path) args['file_path'] = input.file_path;
-  if (input.framework_type) args['framework_type'] = input.framework_type;
-  return callCodecontext({ toolName: 'get_symbol_info', args, projectPath }, fetcher);
-}
-
-export const getSymbolInfo: ToolDef<GetSymbolInfoInputT> = {
-  name: 'get_symbol_info',
-  description: DESCRIPTION,
-  inputSchema: GetSymbolInfoInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'get_symbol_info',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          symbol_name: {
-            type: 'string',
-            description: 'The symbol name to look up (case-sensitive).',
-          },
-          file_path: {
-            type: 'string',
-            description: 'Narrow to a specific file when the symbol name is ambiguous.',
-          },
-          framework_type: {
-            type: 'string',
-            description: 'Hint for framework-specific extraction (react|vue|svelte|django|fastapi|express|nest|…).',
-          },
+const { toolDef: getSymbolInfo, execute: executeGetSymbolInfo } =
+  makeCodecontextTool<GetSymbolInfoInputT>({
+    name: 'get_symbol_info',
+    schema: GetSymbolInfoInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        symbol_name: {
+          type: 'string',
+          description: 'The symbol name to look up (case-sensitive).',
+        },
+        file_path: {
+          type: 'string',
+          description: 'Narrow to a specific file when the symbol name is ambiguous.',
+        },
+        framework_type: {
+          type: 'string',
+          description: 'Hint for framework-specific extraction (react|vue|svelte|django|fastapi|express|nest|…).',
         },
-        required: ['symbol_name'],
-        additionalProperties: false,
       },
+      required: ['symbol_name'],
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeGetSymbolInfo(input, projectRoot);
-  },
-};
+    mapArgs: (input) => {
+      const args: Record<string, unknown> = { symbol_name: input.symbol_name };
+      if (input.file_path) args['file_path'] = input.file_path;
+      if (input.framework_type) args['framework_type'] = input.framework_type;
+      return args;
+    },
+  });
+
+export { getSymbolInfo, executeGetSymbolInfo };

apps/server/src/services/tools/codecontext/search_symbols.ts

@@ -1,8 +1,5 @@
-// v1.12 Track B.2: codecontext wrapper — search_symbols.
-
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const SearchSymbolsInput = z.object({
   query: z.string().min(1),
@@ -21,57 +18,45 @@ const DESCRIPTION =
 
 const DEFAULT_LIMIT = 20;
 
-export async function executeSearchSymbols(
-  input: SearchSymbolsInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  const args: Record<string, unknown> = {
-    query: input.query,
-    limit: input.limit ?? DEFAULT_LIMIT,
-  };
-  if (input.file_type) args['file_type'] = input.file_type;
-  if (input.symbol_type) args['symbol_type'] = input.symbol_type;
-  if (input.framework_type) args['framework_type'] = input.framework_type;
-  return callCodecontext({ toolName: 'search_symbols', args, projectPath }, fetcher);
-}
-
-export const searchSymbols: ToolDef<SearchSymbolsInputT> = {
-  name: 'search_symbols',
-  description: DESCRIPTION,
-  inputSchema: SearchSymbolsInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'search_symbols',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          query: { type: 'string', description: 'Substring or name fragment to match.' },
-          file_type: {
-            type: 'string',
-            description: 'Filter by file extension or language (e.g. "ts", "py", "go").',
-          },
-          symbol_type: {
-            type: 'string',
-            description: 'Filter by kind: function|class|method|variable|type|interface.',
-          },
-          framework_type: {
-            type: 'string',
-            description: 'Filter by framework context (react|vue|svelte|…).',
-          },
-          limit: {
-            type: 'integer',
-            description: `Max matches to return. Defaults to ${DEFAULT_LIMIT}.`,
-          },
+const { toolDef: searchSymbols, execute: executeSearchSymbols } =
+  makeCodecontextTool<SearchSymbolsInputT>({
+    name: 'search_symbols',
+    schema: SearchSymbolsInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Substring or name fragment to match.' },
+        file_type: {
+          type: 'string',
+          description: 'Filter by file extension or language (e.g. "ts", "py", "go").',
+        },
+        symbol_type: {
+          type: 'string',
+          description: 'Filter by kind: function|class|method|variable|type|interface.',
+        },
+        framework_type: {
+          type: 'string',
+          description: 'Filter by framework context (react|vue|svelte|…).',
+        },
+        limit: {
+          type: 'integer',
+          description: `Max matches to return. Defaults to ${DEFAULT_LIMIT}.`,
         },
-        required: ['query'],
-        additionalProperties: false,
       },
+      required: ['query'],
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeSearchSymbols(input, projectRoot);
-  },
-};
+    mapArgs: (input) => {
+      const args: Record<string, unknown> = {
+        query: input.query,
+        limit: input.limit ?? DEFAULT_LIMIT,
+      };
+      if (input.file_type) args['file_type'] = input.file_type;
+      if (input.symbol_type) args['symbol_type'] = input.symbol_type;
+      if (input.framework_type) args['framework_type'] = input.framework_type;
+      return args;
+    },
+  });
+
+export { searchSymbols, executeSearchSymbols };

apps/server/src/services/tools/codecontext/watch_changes.ts

@@ -1,8 +1,5 @@
-// v1.12 Track B.2: codecontext wrapper — watch_changes.
-
 import { z } from 'zod';
-import type { ToolDef } from '../../tools.js';
-import { callCodecontext, type CodecontextResponse } from '../../codecontext_client.js';
+import { makeCodecontextTool } from './factory.js';
 
 export const WatchChangesInput = z.object({
   enable: z.boolean(),
@@ -10,48 +7,27 @@ export const WatchChangesInput = z.object({
 export type WatchChangesInputT = z.infer<typeof WatchChangesInput>;
 
 const DESCRIPTION =
-  'Turn codecontext\'s file watcher on or off for this project. ' +
+  "Turn codecontext's file watcher on or off for this project. " +
   'When on, codecontext re-analyzes files in the background as they change (debounced). Default is on. ' +
-  'Disable temporarily if you\'re doing bulk edits and want to avoid analysis churn.';
+  "Disable temporarily if you're doing bulk edits and want to avoid analysis churn.";
 
-export async function executeWatchChanges(
-  input: WatchChangesInputT,
-  projectPath: string,
-  fetcher: typeof fetch = fetch,
-): Promise<CodecontextResponse> {
-  return callCodecontext(
-    {
-      toolName: 'watch_changes',
-      args: { enable: input.enable },
-      projectPath,
-    },
-    fetcher,
-  );
-}
-
-export const watchChanges: ToolDef<WatchChangesInputT> = {
-  name: 'watch_changes',
-  description: DESCRIPTION,
-  inputSchema: WatchChangesInput,
-  jsonSchema: {
-    type: 'function',
-    function: {
-      name: 'watch_changes',
-      description: DESCRIPTION,
-      parameters: {
-        type: 'object',
-        properties: {
-          enable: {
-            type: 'boolean',
-            description: 'true = enable the watcher; false = disable.',
-          },
+const { toolDef: watchChanges, execute: executeWatchChanges } =
+  makeCodecontextTool<WatchChangesInputT>({
+    name: 'watch_changes',
+    schema: WatchChangesInput,
+    description: DESCRIPTION,
+    jsonParameters: {
+      type: 'object',
+      properties: {
+        enable: {
+          type: 'boolean',
+          description: 'true = enable the watcher; false = disable.',
         },
-        required: ['enable'],
-        additionalProperties: false,
       },
+      required: ['enable'],
+      additionalProperties: false,
     },
-  },
-  async execute(input, projectRoot) {
-    return await executeWatchChanges(input, projectRoot);
-  },
-};
+    mapArgs: (input) => ({ enable: input.enable }),
+  });
+
+export { watchChanges, executeWatchChanges };

apps/server/src/services/tools/fs-tools.ts

@@ -0,0 +1,392 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { resolve, basename, relative } from 'node:path';
+import { z } from 'zod';
+import { pathGuard, PathScopeError } from '../path_guard.js';
+import { isSecretPath, SecretBlockedError, filterSecretEntries } from '../secret_guard.js';
+import { grep as fileOpsGrep, findFiles as fileOpsFindFiles } from '../file_ops.js';
+import { readTruncation, truncateIfNeeded } from '../truncate.js';
+import type { ToolDef } from './types.js';
+
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const DEFAULT_VIEW_LINES = 200;
+const MAX_GREP_RESULTS = 200;
+const DEFAULT_GREP_RESULTS = 100;
+const MAX_FIND_RESULTS = 200;
+const DEFAULT_FIND_RESULTS = 100;
+const MAX_DIR_ENTRIES = 500;
+
+const ViewFileInput = z.object({
+  path: z.string().min(1),
+  start_line: z.number().int().positive().optional(),
+  end_line: z.number().int().positive().optional(),
+});
+type ViewFileInputT = z.infer<typeof ViewFileInput>;
+
+export const viewFile: ToolDef<ViewFileInputT> = {
+  name: 'view_file',
+  description:
+    "Read a file under the project. Returns first 200 lines by default, or a slice via start_line/end_line (1-indexed, inclusive). Files larger than 5MB are refused. Output is truncated if longer than the slice; the response indicates truncation.",
+  inputSchema: ViewFileInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'view_file',
+      description:
+        "Read a file under the project. Returns first 200 lines by default, or a slice via start_line/end_line (1-indexed, inclusive). Files larger than 5MB are refused.",
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'absolute or project-relative path' },
+          start_line: { type: 'integer', description: 'first line (1-indexed)' },
+          end_line: { type: 'integer', description: 'last line (1-indexed, inclusive)' },
+        },
+        required: ['path'],
+        additionalProperties: false,
+      },
+    },
+  },
+  async execute(input, projectRoot, extraRoots) {
+    const real = await pathGuard(projectRoot, input.path, extraRoots);
+    // v1.11.7: secret-file deny check. Test the project-relative path
+    // (matches the form continue.dev's patterns expect: basenames + dir
+    // segments). Throw a typed error so executeToolCall in inference.ts
+    // surfaces a clear "blocked" message to the LLM instead of silently
+    // returning content the user wanted hidden.
+    // v1.13.17: when the resolved path is outside the primary projectRoot
+    // (i.e. via an allowed_read_paths grant), `relative()` returns "../…"
+    // which won't match secret-file basename patterns. Re-anchor on the
+    // file's basename so the secret deny still fires across all grant roots.
+    const rel = relative(projectRoot, real);
+    const relPath = rel && !rel.startsWith('..') ? rel : basename(real);
+    if (isSecretPath(relPath)) {
+      throw new SecretBlockedError(relPath);
+    }
+    const s = await stat(real);
+    if (!s.isFile()) {
+      throw new PathScopeError(`not a file: ${input.path}`);
+    }
+    if (s.size > MAX_FILE_BYTES) {
+      throw new Error(`file too large (${s.size} bytes, max ${MAX_FILE_BYTES})`);
+    }
+    const raw = await readFile(real, 'utf8');
+    const lines = raw.split('\n');
+    const total = lines.length;
+    let start = input.start_line ?? 1;
+    let end = input.end_line ?? Math.min(total, start + DEFAULT_VIEW_LINES - 1);
+    if (input.start_line == null && input.end_line == null) {
+      end = Math.min(total, DEFAULT_VIEW_LINES);
+    }
+    if (start < 1) start = 1;
+    if (end > total) end = total;
+    if (end < start) end = start;
+    const slice = lines.slice(start - 1, end);
+    const content = slice.join('\n');
+    const truncated = total > end || start > 1;
+    // v1.13.5: stash the full file on tmpfs so the model can retrieve more
+    // via view_truncated_output(id) without re-reading the file (which it
+    // may not have project-relative-path access to in future agent setups).
+    // raw is bounded by MAX_FILE_BYTES (5MB), within truncateIfNeeded's cap.
+    const wrapped = await truncateIfNeeded({
+      fullContent: raw,
+      slicedContent: content,
+      wasTruncated: truncated,
+    });
+    return {
+      path: relative(projectRoot, real) || basename(real),
+      content: wrapped.content,
+      total_lines: total,
+      returned_lines: [start, end],
+      truncated: wrapped.truncated,
+      ...(wrapped.outputPath ? { outputPath: wrapped.outputPath } : {}),
+    };
+  },
+};
+
+const ListDirInput = z.object({
+  path: z.string().min(1),
+  show_hidden: z.boolean().optional(),
+});
+type ListDirInputT = z.infer<typeof ListDirInput>;
+
+export const listDir: ToolDef<ListDirInputT> = {
+  name: 'list_dir',
+  description: 'List entries in a directory (up to 500). Hidden files excluded unless show_hidden=true.',
+  inputSchema: ListDirInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'list_dir',
+      description:
+        'List entries in a directory (up to 500). Hidden files (dot-prefixed) excluded unless show_hidden=true.',
+      parameters: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          show_hidden: { type: 'boolean' },
+        },
+        required: ['path'],
+        additionalProperties: false,
+      },
+    },
+  },
+  async execute(input, projectRoot, extraRoots) {
+    const real = await pathGuard(projectRoot, input.path, extraRoots);
+    const s = await stat(real);
+    if (!s.isDirectory()) {
+      throw new PathScopeError(`not a directory: ${input.path}`);
+    }
+    const entries = await readdir(real, { withFileTypes: true });
+    const filtered = input.show_hidden
+      ? entries
+      : entries.filter((e) => !e.name.startsWith('.'));
+    const total = filtered.length;
+    const wasTruncated = total > MAX_DIR_ENTRIES;
+    const relDir = relative(projectRoot, real) || '.';
+    // v1.13.5: when we'd truncate, render the FULL list to tmpfs so
+    // view_truncated_output can serve it. Stat sizes for all entries when
+    // truncating so the stored view matches the visible shape; this is the
+    // one extra cost for big directories, bounded by total entries (which
+    // is itself bounded by filesystem behavior).
+    const processOne = async (e: typeof filtered[number]) => {
+      const child = resolve(real, e.name);
+      let size: number | undefined;
+      if (e.isFile()) {
+        try {
+          const cs = await stat(child);
+          size = cs.size;
+        } catch { /* ignore */ }
+      }
+      return {
+        name: e.name,
+        type: e.isDirectory() ? ('dir' as const) : ('file' as const),
+        ...(size != null ? { size } : {}),
+      };
+    };
+    const slice = filtered.slice(0, MAX_DIR_ENTRIES);
+    const out = await Promise.all(slice.map(processOne));
+    // v1.11.7: filter entries whose project-relative path matches a secret
+    // pattern. The same filter applies to the full-list snapshot below so
+    // the stashed file never holds entries the slice would have hidden.
+    const secretFilter = filterSecretEntries(out, (e) =>
+      relDir === '.' ? e.name : `${relDir}/${e.name}`,
+    );
+    let outputPath: string | undefined;
+    if (wasTruncated) {
+      const fullProcessed = await Promise.all(filtered.map(processOne));
+      const fullFiltered = filterSecretEntries(fullProcessed, (e) =>
+        relDir === '.' ? e.name : `${relDir}/${e.name}`,
+      );
+      // One line per entry, view_truncated_output's line slicing semantics
+      // map cleanly. Format: "<type>\t<name>[\tsize=N]". Header documents
+      // the shape so the model can grep / regex without prior schema lookup.
+      const header = `# list_dir ${relDir} — ${fullFiltered.kept.length} entries`;
+      const lines = [header, ...fullFiltered.kept.map((e) => {
+        const sz = 'size' in e && e.size != null ? `\tsize=${e.size}` : '';
+        return `${e.type}\t${e.name}${sz}`;
+      })];
+      const wrapped = await truncateIfNeeded({
+        fullContent: lines.join('\n'),
+        slicedContent: '',
+        wasTruncated: true,
+      });
+      outputPath = wrapped.outputPath;
+    }
+    return {
+      path: relDir,
+      entries: secretFilter.kept,
+      total: secretFilter.kept.length,
+      truncated: wasTruncated,
+      ...(secretFilter.note ? { pathguard_note: secretFilter.note } : {}),
+      ...(outputPath ? { outputPath } : {}),
+    };
+  },
+};
+
+const GrepInput = z.object({
+  pattern: z.string().min(1),
+  path: z.string().optional(),
+  case_sensitive: z.boolean().optional(),
+  max_results: z.number().int().positive().optional(),
+  hidden: z.boolean().optional(),
+});
+type GrepInputT = z.infer<typeof GrepInput>;
+
+export const grep: ToolDef<GrepInputT> = {
+  name: 'grep',
+  description:
+    'Search file contents with ripgrep. Default path is project root. Max 100 results (200 cap).',
+  inputSchema: GrepInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'grep',
+      description:
+        'Search file contents with ripgrep. Returns up to 100 matches (cap 200). Set hidden=true to include dot-prefixed files.',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string' },
+          path: { type: 'string' },
+          case_sensitive: { type: 'boolean' },
+          max_results: { type: 'integer' },
+          hidden: { type: 'boolean' },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+      },
+    },
+  },
+  async execute(input, projectRoot, extraRoots) {
+    const limit = Math.min(
+      Math.max(input.max_results ?? DEFAULT_GREP_RESULTS, 1),
+      MAX_GREP_RESULTS
+    );
+    // Delegate to file_ops.grep; reshape match objects to preserve LLM output format
+    // (file_ops uses {path, line, text}; tool output uses {path, line, content})
+    const result = await fileOpsGrep(projectRoot, input.pattern, {
+      path: input.path,
+      max_matches: limit,
+      case_sensitive: input.case_sensitive,
+      hidden: input.hidden,
+      extra_roots: extraRoots,
+    });
+    const reshaped = result.matches.map((m) => ({
+      path: m.path,
+      line: m.line,
+      content: m.text,
+    }));
+    // v1.11.7: drop matches whose source file is a known-secret pattern.
+    // file_ops.grep returns project-relative paths, so we feed them straight
+    // into isSecretPath. Multiple matches in the same secret file each get
+    // dropped individually — they all count in the hidden tally.
+    const secretFilter = filterSecretEntries(reshaped, (m) => m.path);
+    return {
+      matches: secretFilter.kept,
+      total: secretFilter.kept.length,
+      truncated: result.truncated,
+      ...(secretFilter.note ? { pathguard_note: secretFilter.note } : {}),
+    };
+  },
+};
+
+const FindFilesInput = z.object({
+  pattern: z.string().min(1),
+  path: z.string().optional(),
+  max_results: z.number().int().positive().optional(),
+});
+type FindFilesInputT = z.infer<typeof FindFilesInput>;
+
+export const findFiles: ToolDef<FindFilesInputT> = {
+  name: 'find_files',
+  description: 'Glob for filenames. Default path is project root. Max 100 results (200 cap).',
+  inputSchema: FindFilesInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'find_files',
+      description:
+        'Glob for filenames under a directory. Default path is project root. Max 100 results (cap 200). Pattern uses standard glob (e.g. "**/*.ts").',
+      parameters: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string' },
+          path: { type: 'string' },
+          max_results: { type: 'integer' },
+        },
+        required: ['pattern'],
+        additionalProperties: false,
+      },
+    },
+  },
+  async execute(input, projectRoot, extraRoots) {
+    const limit = Math.min(
+      Math.max(input.max_results ?? DEFAULT_FIND_RESULTS, 1),
+      MAX_FIND_RESULTS
+    );
+    // Delegate to file_ops.findFiles; reshape { files, total, truncated } to
+    // preserve the LLM-visible output format { paths, total, truncated }
+    const result = await fileOpsFindFiles(projectRoot, input.pattern, {
+      path: input.path,
+      max_results: limit,
+      extra_roots: extraRoots,
+    });
+    // v1.11.7: drop paths matching secret patterns. The original `total`
+    // from file_ops includes pre-truncation count; we report the visible
+    // count post-filter so the LLM can't infer hidden-count by subtraction.
+    const secretFilter = filterSecretEntries(result.files, (p) => p);
+    return {
+      paths: secretFilter.kept,
+      total: secretFilter.kept.length,
+      truncated: result.truncated,
+      ...(secretFilter.note ? { pathguard_note: secretFilter.note } : {}),
+    };
+  },
+};
+
+// v1.13.5: retrieves the full content of a previously-truncated tool output
+// via the opaque id stamped on the original tool_result. Line-based slicing
+// matches view_file's mental model so the model uses the same affordances.
+// Tmpfs-backed, 7-day TTL (see services/truncate.ts).
+const VIEW_TRUNCATED_DEFAULT_LINES = 200;
+
+const ViewTruncatedOutputInput = z.object({
+  id: z.string().regex(/^tr_[0-9a-v]{12}$/),
+  start_line: z.number().int().positive().optional(),
+  end_line: z.number().int().positive().optional(),
+});
+type ViewTruncatedOutputInputT = z.infer<typeof ViewTruncatedOutputInput>;
+
+export const viewTruncatedOutput: ToolDef<ViewTruncatedOutputInputT> = {
+  name: 'view_truncated_output',
+  description: `Retrieve the full content of a previously-truncated tool output by its outputPath id. When a tool returns { truncated: true, outputPath: "tr_..." }, call this to view the full content. Defaults to the first ${VIEW_TRUNCATED_DEFAULT_LINES} lines. Use start_line and end_line (1-indexed, inclusive) to slice. Stored for 7 days.`,
+  inputSchema: ViewTruncatedOutputInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'view_truncated_output',
+      description: `Retrieve the full content of a previously-truncated tool output by its outputPath id. Returns the first ${VIEW_TRUNCATED_DEFAULT_LINES} lines by default; use start_line/end_line to slice. Stored for 7 days.`,
+      parameters: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'The outputPath value from an earlier truncated tool result (e.g. "tr_abc123def456").' },
+          start_line: { type: 'integer', description: 'First line (1-indexed). Default 1.' },
+          end_line: { type: 'integer', description: `Last line (1-indexed, inclusive). Default ${VIEW_TRUNCATED_DEFAULT_LINES} lines past start.` },
+        },
+        required: ['id'],
+        additionalProperties: false,
+      },
+    },
+  },
+  // view_truncated_output doesn't touch the filesystem — it pulls from tmpfs
+  // by opaque id. extraRoots is irrelevant here; declared for signature parity
+  // with the v1.13.17 ToolDef contract.
+  async execute(input, _projectRoot, _extraRoots) {
+    const content = await readTruncation(input.id);
+    if (content === null) {
+      return {
+        id: input.id,
+        content: '',
+        truncated: false,
+        error: `No truncation found for id "${input.id}". It may have been pruned (7-day TTL) or never existed.`,
+      };
+    }
+    const lines = content.split('\n');
+    const total = lines.length;
+    let start = input.start_line ?? 1;
+    let end = input.end_line ?? Math.min(total, start + VIEW_TRUNCATED_DEFAULT_LINES - 1);
+    if (start < 1) start = 1;
+    if (end > total) end = total;
+    if (end < start) end = start;
+    const slice = lines.slice(start - 1, end).join('\n');
+    // Re-slicing this view isn't truncation in the dual-write sense — the
+    // model already has the id; no point stashing the slice again.
+    const truncated = total > end || start > 1;
+    return {
+      id: input.id,
+      content: slice,
+      total_lines: total,
+      returned_lines: [start, end],
+      truncated,
+    };
+  },
+};

apps/server/src/services/tools/misc-tools.ts

@@ -0,0 +1,216 @@
+import { z } from 'zod';
+import { getGitMeta } from '../git_meta.js';
+import { findSkills, getSkillBody, getSkillResource } from '../skills.js';
+import type { ToolDef } from './types.js';
+
+// v1.8 Level 1 branch awareness: gives the model a read-only view of the
+// project's git state. No path input — operates on the inference-resolved
+// project root via getGitMeta. Subprocess runs with a 2s timeout (see git_meta).
+const GitStatusInput = z.object({}).strict();
+type GitStatusInputT = z.infer<typeof GitStatusInput>;
+
+export const gitStatus: ToolDef<GitStatusInputT> = {
+  name: 'git_status',
+  description:
+    "Returns the current git branch, whether the working tree is dirty, and ahead/behind counts vs upstream. Read-only. Use when you need to know which branch the user is currently working on.",
+  inputSchema: GitStatusInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'git_status',
+      description:
+        'Returns the current git branch, dirty flag, and ahead/behind counts vs upstream. Read-only.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+    },
+  },
+  async execute(_input, projectRoot) {
+    const meta = await getGitMeta(projectRoot);
+    if (meta === null) {
+      return { repo: false, branch: null, is_dirty: false, ahead: 0, behind: 0 };
+    }
+    return { repo: true, ...meta };
+  },
+};
+
+// Batch 9.6: skill_find, skill_use, skill_resource. Lazy-loaded markdown
+// playbooks at /data/skills/. Three tools rather than one to keep each call
+// cheap — the model lists, then loads, then optionally pulls support files.
+
+const SkillFindInput = z.object({
+  query: z.string().optional(),
+});
+type SkillFindInputT = z.infer<typeof SkillFindInput>;
+
+export const skillFind: ToolDef<SkillFindInputT> = {
+  name: 'skill_find',
+  description:
+    'Find skills (markdown playbooks under /data/skills) by name or description. Returns up to 5 matches. Empty query or "*" returns all available skills. Call this first to discover what skills are available.',
+  inputSchema: SkillFindInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'skill_find',
+      description:
+        'Find skills by name or description. Returns up to 5 matches. Empty or "*" returns all.',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'substring matched against skill name and description' },
+        },
+        additionalProperties: false,
+      },
+    },
+  },
+  async execute(input) {
+    return await findSkills(input.query ?? '');
+  },
+};
+
+const SkillUseInput = z.object({
+  name: z.string().min(1),
+});
+type SkillUseInputT = z.infer<typeof SkillUseInput>;
+
+export const skillUse: ToolDef<SkillUseInputT> = {
+  name: 'skill_use',
+  description:
+    "Load the full body of a skill's SKILL.md by name. Returns the markdown playbook to follow. Discover names via skill_find. Errors: unknown_skill.",
+  inputSchema: SkillUseInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'skill_use',
+      description: "Load the full body of a skill's SKILL.md by name.",
+      parameters: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'skill name from skill_find' },
+        },
+        required: ['name'],
+        additionalProperties: false,
+      },
+    },
+  },
+  async execute(input) {
+    const body = await getSkillBody(input.name);
+    if (body === null) {
+      return { error: 'unknown_skill', message: `unknown skill: ${input.name}` };
+    }
+    return { body };
+  },
+};
+
+const SkillResourceInput = z.object({
+  name: z.string().min(1),
+  path: z.string().min(1),
+});
+type SkillResourceInputT = z.infer<typeof SkillResourceInput>;
+
+export const skillResource: ToolDef<SkillResourceInputT> = {
+  name: 'skill_resource',
+  description:
+    "Read a support file inside a skill's folder (e.g. references/root-cause-tracing.md). Path is relative to the skill folder. Use skill_use to read SKILL.md itself. Errors: unknown_skill, unknown_resource, path_escape.",
+  inputSchema: SkillResourceInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'skill_resource',
+      description: "Read a support file inside a skill's folder. Path is relative to the skill folder.",
+      parameters: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'skill name' },
+          path: { type: 'string', description: 'relative path under the skill folder' },
+        },
+        required: ['name', 'path'],
+        additionalProperties: false,
+      },
+    },
+  },
+  async execute(input) {
+    const result = await getSkillResource(input.name, input.path);
+    if (!result.ok) {
+      return { error: result.code, message: result.message };
+    }
+    return { content: result.content };
+  },
+};
+
+// Batch 9.7: ask_user_input. Interactive elicitation. The model emits a tool
+// call with 1-3 structured questions; the inference loop PAUSES (does not
+// execute the tool server-side, does not recurse) and waits for the frontend
+// to POST /api/chats/:id/answer_user_input with the user's selections. See
+// routes/messages.ts for the resume path and services/inference.ts for the
+// pause branch in executeToolPhase.
+const AskUserInputInput = z.object({
+  questions: z
+    .array(
+      z.object({
+        question: z.string().min(1).max(200),
+        type: z.enum(['single_select', 'multi_select']),
+        options: z.array(z.string().min(1).max(80)).min(2).max(6),
+      }),
+    )
+    .min(1)
+    .max(3),
+});
+type AskUserInputInputT = z.infer<typeof AskUserInputInput>;
+
+export const askUserInput: ToolDef<AskUserInputInputT> = {
+  name: 'ask_user_input',
+  description:
+    "Ask the user 1-3 structured questions through an inline picker UI. Use when you genuinely need a choice the user must make (e.g. scope, options, preferences) before continuing. Each question has 2-6 options and accepts free-text answers in addition. The tool call pauses the conversation until the user submits — the next assistant turn sees their answers as the tool result. Do not use for trivial yes/no clarifications you could infer; prefer it over multi-paragraph speculation about what the user might want.",
+  inputSchema: AskUserInputInput,
+  jsonSchema: {
+    type: 'function',
+    function: {
+      name: 'ask_user_input',
+      description:
+        'Ask the user 1-3 structured questions through an inline picker. Pauses the conversation until the user answers; the next turn sees their selections.',
+      parameters: {
+        type: 'object',
+        properties: {
+          questions: {
+            type: 'array',
+            minItems: 1,
+            maxItems: 3,
+            items: {
+              type: 'object',
+              properties: {
+                question: { type: 'string', description: '<=200 chars, shown to the user' },
+                type: {
+                  type: 'string',
+                  enum: ['single_select', 'multi_select'],
+                  description: 'single_select = at most one option; multi_select = any subset',
+                },
+                options: {
+                  type: 'array',
+                  minItems: 2,
+                  maxItems: 6,
+                  items: { type: 'string' },
+                  description: '2-6 strings, each <=80 chars; free-text input is always available alongside',
+                },
+              },
+              required: ['question', 'type', 'options'],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ['questions'],
+        additionalProperties: false,
+      },
+    },
+  },
+  // Server-side no-op. The "execution" of ask_user_input is the user's
+  // response, captured client-side and posted to /api/chats/:id/answer_user_input.
+  // The inference loop detects this tool by name and pauses before reaching
+  // executeToolCall — this fallback only runs if something bypasses that
+  // branch, in which case the pending sentinel matches the pause-path shape.
+  async execute(input) {
+    return { _pending: true, questions: input.questions };
+  },
+};

apps/server/src/services/tools/registry.ts

@@ -0,0 +1,96 @@
+import type { ToolDef, ToolJsonSchema } from './types.js';
+import { viewFile, listDir, grep, findFiles, viewTruncatedOutput } from './fs-tools.js';
+import { gitStatus, skillFind, skillUse, skillResource, askUserInput } from './misc-tools.js';
+import { webSearch } from '../web_search.js';
+import { webFetch } from '../web_fetch.js';
+// v1.12 Track B.2: codecontext tools. 8 wrappers re-exported from
+// tools/codecontext/index.ts. Each calls into services/codecontext_client.ts
+// which talks to the codecontext sidecar at http://codecontext:8080.
+import {
+  getCodebaseOverview,
+  getFileAnalysis,
+  getSymbolInfo,
+  searchSymbols,
+  getDependencies,
+  watchChanges,
+  getSemanticNeighborhoods,
+  getFrameworkAnalysis,
+  getBlastRadius,
+  getHotFiles,
+  getRoutes,
+  getMiddleware,
+} from './codecontext/index.js';
+// v1.13.17-cross-repo-reads: cross-repo read grant request tool. Paired
+// with the pause-on-pending-grant branch in inference/tool-phase.ts and the
+// POST /api/chats/:id/grant_read_access endpoint in routes/messages.ts.
+import { requestReadAccess } from '../request_read_access.js';
+// v2.6.x: read-only tool that reads a tab's transcript by its session-scoped
+// tab number. Needs DB/session context (ToolExecCtx 4th arg).
+import { readTabByNumber } from '../read_tab_by_number.js';
+
+// v1.13.3: alpha-sorted by tool.name at module load. llama.cpp's prompt
+// cache hits on byte-identical prefixes; the tool list lives near the top
+// of the system prompt, so any order drift would invalidate every cached
+// turn. Single source of truth for ordering lives here — toolJsonSchemas()
+// and TOOLS_BY_NAME inherit it.
+// v1.14.1-mcp-poc: changed from ReadonlyArray to let-bound mutable array
+// so appendMcpTools() can push MCP-discovered tools at startup.
+export let ALL_TOOLS: ToolDef<unknown>[] = [
+  viewFile as ToolDef<unknown>,
+  viewTruncatedOutput as ToolDef<unknown>,
+  listDir as ToolDef<unknown>,
+  grep as ToolDef<unknown>,
+  findFiles as ToolDef<unknown>,
+  gitStatus as ToolDef<unknown>,
+  skillFind as ToolDef<unknown>,
+  skillUse as ToolDef<unknown>,
+  skillResource as ToolDef<unknown>,
+  askUserInput as ToolDef<unknown>,
+  // v1.11.8: web tools. Gated per-chat via session.web_search_enabled
+  // (with project default fallback) — see effectiveTools filter in
+  // services/inference.ts.
+  webSearch as ToolDef<unknown>,
+  webFetch as ToolDef<unknown>,
+  // v1.12 Track B.2: codecontext tools. Backed by the codecontext sidecar
+  // container. All read-only. target_dir is resolved server-side from the
+  // project root in codecontext_client.ts (the LLM never supplies it).
+  getCodebaseOverview as ToolDef<unknown>,
+  getFileAnalysis as ToolDef<unknown>,
+  getSymbolInfo as ToolDef<unknown>,
+  searchSymbols as ToolDef<unknown>,
+  getDependencies as ToolDef<unknown>,
+  watchChanges as ToolDef<unknown>,
+  getSemanticNeighborhoods as ToolDef<unknown>,
+  getFrameworkAnalysis as ToolDef<unknown>,
+  // v1.16: codesight-merge tools. Backed by the same codecontext sidecar.
+  getBlastRadius as ToolDef<unknown>,
+  getHotFiles as ToolDef<unknown>,
+  getRoutes as ToolDef<unknown>,
+  getMiddleware as ToolDef<unknown>,
+  // v1.13.17-cross-repo-reads: paired with the pause-on-pending-grant
+  // branch in tool-phase.ts. Read-only — only ever READS files; the only
+  // state change is appending to sessions.allowed_read_paths via the
+  // grant endpoint, gated by user consent.
+  requestReadAccess as ToolDef<unknown>,
+  // v2.6.x: read a tab's transcript by its session-scoped tab number.
+  // Read-only; uses the ToolExecCtx 4th arg for DB/session access.
+  readTabByNumber as ToolDef<unknown>,
+].sort((a, b) => a.name.localeCompare(b.name));
+
+export let TOOLS_BY_NAME: Record<string, ToolDef<unknown>> = Object.fromEntries(
+  ALL_TOOLS.map((t) => [t.name, t])
+);
+
+// v1.14.1-mcp-poc: append MCP-discovered tools at startup. Called once
+// from index.ts after mcpClient.initialize(). Re-sorts ALL_TOOLS and
+// rebuilds TOOLS_BY_NAME. MCP tools are all read-only by construction
+// (the read-only guard in mcp-client.ts rejects readOnlyHint: false).
+export function appendMcpTools(mcpTools: ToolDef<unknown>[]): void {
+  if (mcpTools.length === 0) return;
+  ALL_TOOLS = [...ALL_TOOLS, ...mcpTools].sort((a, b) => a.name.localeCompare(b.name));
+  TOOLS_BY_NAME = Object.fromEntries(ALL_TOOLS.map((t) => [t.name, t]));
+}
+
+export function toolJsonSchemas(): ToolJsonSchema[] {
+  return ALL_TOOLS.map((t) => t.jsonSchema);
+}

apps/server/src/services/tools/tiers.ts

@@ -0,0 +1,59 @@
+import { ALL_TOOLS, TOOLS_BY_NAME } from './registry.js';
+
+// v1.13.15-tools: tiered tool loading. BOOCODE_TOOLS env var (`core` |
+// `standard` | `all`) filters the agent's tool whitelist before LLM dispatch.
+// Daily-driver token win on qwen3.6-35b-a3b — the 35B-A3B MoE benefits from
+// any prompt-cache stability win (fewer tools = shorter, more stable tool
+// schemas in the system prompt). Pattern lift from eyaltoledano/claude-task-
+// master (MIT + Commons Clause — pattern only, no code lift).
+//
+// The env var is a CEILING. It only narrows; never expands an agent's
+// declared whitelist. Default behavior (var unset) is unchanged: all tools.
+export const CORE_TOOL_NAMES = [
+  'view_file',
+  'list_dir',
+  'grep',
+  'find_files',
+] as const;
+
+export const STANDARD_TOOL_NAMES = [
+  ...CORE_TOOL_NAMES,
+  'web_search',
+  'web_fetch',
+  'git_status',
+  'get_codebase_overview',
+  'get_file_analysis',
+  'get_symbol_info',
+  'search_symbols',
+  'get_dependencies',
+  'watch_changes',
+  'get_semantic_neighborhoods',
+  'get_framework_analysis',
+] as const;
+
+// Module-load validation: every name in CORE / STANDARD must exist in
+// TOOLS_BY_NAME. Catches typos and stale tier definitions before they reach
+// production; server boot fails loudly rather than silently filtering valid
+// tools out of agent whitelists.
+for (const name of CORE_TOOL_NAMES) {
+  if (!TOOLS_BY_NAME[name]) {
+    throw new Error(`CORE_TOOL_NAMES references unknown tool: '${name}'`);
+  }
+}
+for (const name of STANDARD_TOOL_NAMES) {
+  if (!TOOLS_BY_NAME[name]) {
+    throw new Error(`STANDARD_TOOL_NAMES references unknown tool: '${name}'`);
+  }
+}
+
+export function resolveToolTier(tier: string | undefined): readonly string[] {
+  switch ((tier ?? 'all').toLowerCase()) {
+    case 'core':
+      return CORE_TOOL_NAMES;
+    case 'standard':
+      return STANDARD_TOOL_NAMES;
+    case 'all':
+    default:
+      return ALL_TOOLS.map((t) => t.name);
+  }
+}

apps/server/src/services/tools/types.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+import type { Sql } from '../../db.js';
+
+export interface ToolJsonSchema {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+
+// v2.6.x: optional DB/session context threaded into a tool's execute(). Only
+// tools that need to read session-scoped DB state (e.g. read_tab_by_number)
+// use it; every other tool ignores the 4th arg. Kept optional so existing
+// 3-arg execute() implementations stay assignable (apps/coder consumes this
+// type from the compiled dist — the optional param keeps it backward-compatible).
+export interface ToolExecCtx {
+  sql: Sql;
+  sessionId: string;
+}
+
+export interface ToolDef<TInput> {
+  name: string;
+  description: string;
+  inputSchema: z.ZodType<TInput>;
+  jsonSchema: ToolJsonSchema;
+  // v1.13.17-cross-repo-reads: extraRoots is the session's
+  // allowed_read_paths, threaded through executeToolCall in tool-phase.ts.
+  // Only the filesystem tools (view_file, list_dir, grep, find_files,
+  // view_truncated_output) forward it to pathGuard; other tools accept the
+  // arg and ignore it. The execute signature stays compatible with
+  // pre-v1.13.17 callsites because the parameter is optional.
+  // v2.6.x: optional 4th param toolCtx carries DB/session context for tools
+  // that read session-scoped state (read_tab_by_number). Optional so 3-arg
+  // implementations remain assignable.
+  execute(
+    input: TInput,
+    projectRoot: string,
+    extraRoots?: readonly string[],
+    toolCtx?: ToolExecCtx,
+  ): Promise<unknown>;
+}