feat(agent): let the single-call assistant read the ledger via read-only MCP tools (#1767)

The /chat assistant (audit Option A / rip) shipped in #1759 reading only the
company name + entity type, so it answered "jag har ingen bokföringsdata" to
every figures question ("vad är min största utgiftspost?"). It now behaves like
an MCP client: it answers over a bounded, READ-only tool loop across the same
MCP read tools the old streaming assistant had, plus an always-on company
snapshot as the backstop.

Provider-agnostic by construction, so it still runs on a local model:
- lib/ai generateText gains optional `tools` + `maxSteps`. The OpenAI-compatible
  service forwards them to the Vercel AI SDK (stopWhen: stepCountIs), which runs
  the loop; the Anthropic-family service hand-rolls a small loop against
  messages.create. Kept on the raw Anthropic SDK: no new deps, and the no-tools
  path is byte-identical, so hosted extraction/composer/etc. are unchanged.
- lib/agent/ask/ledger-tools.ts: the read slice of general.help's whitelist
  (income statement, VAT, ledgers, query_journal, reskontror, lists…) from
  agentToolRegistry, dispatched with the agent_chat actor run-turn uses. Write/
  staging + memory-write tools are excluded; readOnlyHint/destructiveHint are
  re-checked. Empty in a core-only build → snapshot-only, graceful.
- lib/agent/ask/snapshot.ts: a compact company_settings + deadlines block so a
  model that can't/won't call tools still answers status questions. Never carries
  figures (those come from the live tools).
- ask-service attaches tools + snapshot when a userId is present and uses a
  tool-aware system prompt; the route calls ensureInitialized() so the registry
  is populated and threads userId/conversationId through.

Works on Bedrock and on any local model with function-calling (Qwen). Tests:
the anthropic hand-rolled loop (tool call → result → answer, is_error handling,
step-budget forced answer), openai tool forwarding, the read-only adapter
filter, the snapshot format, and the ask-service wiring. 457 agent+ai tests
green, lint/guards clean.

Co-authored-by: Jakob Wennberg <311770904+jakobwennberg-oss@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

lib/ai/__tests__/anthropic-family.test.ts

@@ -186,3 +186,117 @@ describe('buildAnthropicDocumentContent', () => {
     ])
   })
 })
+
+describe('generateText read-only tool loop', () => {
+  it('calls a tool, feeds the JSON result back, and returns the final answer with summed usage', async () => {
+    const execute = vi.fn().mockResolvedValue({ largest: '5010', amount: 12345 })
+    const svc = createAnthropicFamilyService(readAiConfig())
+
+    // Turn 1: the model asks for a report.
+    mockCreate.mockResolvedValueOnce({
+      stop_reason: 'tool_use',
+      content: [
+        { type: 'text', text: 'Kollar.' },
+        { type: 'tool_use', id: 'tu_1', name: 'gnubok_get_income_statement', input: { period: '2026-07' } },
+      ],
+      usage: { input_tokens: 10, output_tokens: 5 },
+    })
+    // Turn 2: the model answers with the figure.
+    mockCreate.mockResolvedValueOnce({
+      stop_reason: 'end_turn',
+      content: [{ type: 'text', text: 'Din största utgift är 12 345 kr (konto 5010).' }],
+      usage: { input_tokens: 20, output_tokens: 8 },
+    })
+
+    const result = await svc.generateText({
+      tier: 'assistant',
+      system: 'S',
+      prompt: 'Vad är min största utgift?',
+      maxTokens: 500,
+      tools: [
+        { name: 'gnubok_get_income_statement', description: 'd', jsonSchema: { type: 'object' }, execute },
+      ],
+      maxSteps: 4,
+    })
+
+    expect(execute).toHaveBeenCalledWith({ period: '2026-07' })
+    expect(result.text).toBe('Din största utgift är 12 345 kr (konto 5010).')
+    expect(mockCreate).toHaveBeenCalledTimes(2)
+
+    // First turn carries the tools; second turn carries the tool_result.
+    expect(mockCreate.mock.calls[0][0].tools[0].name).toBe('gnubok_get_income_statement')
+    const secondMessages = mockCreate.mock.calls[1][0].messages
+    expect(secondMessages).toHaveLength(3) // user, assistant(tool_use), user(tool_result)
+    const toolResult = secondMessages[2].content[0]
+    expect(toolResult.type).toBe('tool_result')
+    expect(toolResult.tool_use_id).toBe('tu_1')
+    expect(JSON.parse(toolResult.content)).toEqual({ largest: '5010', amount: 12345 })
+
+    // Usage summed across both turns.
+    expect(result.usage.inputTokens).toBe(30)
+    expect(result.usage.outputTokens).toBe(13)
+  })
+
+  it('surfaces a tool failure as an is_error result rather than throwing', async () => {
+    const execute = vi.fn().mockRejectedValue(new Error('report timeout'))
+    const svc = createAnthropicFamilyService(readAiConfig())
+    mockCreate.mockResolvedValueOnce({
+      stop_reason: 'tool_use',
+      content: [{ type: 'tool_use', id: 'tu', name: 'gnubok_get_vat_report', input: {} }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+    })
+    mockCreate.mockResolvedValueOnce({
+      stop_reason: 'end_turn',
+      content: [{ type: 'text', text: 'Kunde inte hämta momsrapporten just nu.' }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+    })
+    const result = await svc.generateText({
+      tier: 'assistant',
+      prompt: 'Momsen?',
+      maxTokens: 100,
+      tools: [{ name: 'gnubok_get_vat_report', description: 'd', jsonSchema: {}, execute }],
+    })
+    const toolResult = mockCreate.mock.calls[1][0].messages[2].content[0]
+    expect(toolResult.is_error).toBe(true)
+    expect(JSON.parse(toolResult.content).error).toContain('report timeout')
+    expect(result.text).toBe('Kunde inte hämta momsrapporten just nu.')
+  })
+
+  it('forces a final tools-off answer when the step budget is exhausted', async () => {
+    const execute = vi.fn().mockResolvedValue({ ok: true })
+    const svc = createAnthropicFamilyService(readAiConfig())
+    // Every turn keeps asking for the tool → never terminates on its own.
+    mockCreate.mockResolvedValue({
+      stop_reason: 'tool_use',
+      content: [{ type: 'tool_use', id: 'tu', name: 't', input: {} }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+    })
+    // The forced final turn (index 2) returns real text.
+    mockCreate.mockResolvedValueOnce({
+      stop_reason: 'tool_use',
+      content: [{ type: 'tool_use', id: 'tu', name: 't', input: {} }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+    })
+    mockCreate.mockResolvedValueOnce({
+      stop_reason: 'tool_use',
+      content: [{ type: 'tool_use', id: 'tu', name: 't', input: {} }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+    })
+    mockCreate.mockResolvedValueOnce({
+      stop_reason: 'end_turn',
+      content: [{ type: 'text', text: 'Sammanfattning utan fler verktygsanrop.' }],
+      usage: { input_tokens: 1, output_tokens: 1 },
+    })
+    const result = await svc.generateText({
+      tier: 'assistant',
+      prompt: 'x',
+      maxTokens: 100,
+      tools: [{ name: 't', description: 'd', jsonSchema: {}, execute }],
+      maxSteps: 2,
+    })
+    // 2 loop turns + 1 forced final = 3 calls; the final call omits tools.
+    expect(mockCreate).toHaveBeenCalledTimes(3)
+    expect(mockCreate.mock.calls[2][0].tools).toBeUndefined()
+    expect(result.text).toBe('Sammanfattning utan fler verktygsanrop.')
+  })
+})

lib/ai/__tests__/openai-compatible.test.ts

@@ -102,6 +102,31 @@ describe('createOpenAICompatibleService', () => {
     })
   })
 
+  it('generateText forwards read-only tools to the model when provided', async () => {
+    const svc = createOpenAICompatibleService(readAiConfig())
+    const execute = vi.fn().mockResolvedValue({ ok: true })
+    await svc.generateText({
+      tier: 'assistant',
+      prompt: 'Vad är min största utgift?',
+      maxTokens: 50,
+      tools: [
+        { name: 'gnubok_get_income_statement', description: 'd', jsonSchema: { type: 'object' }, execute },
+      ],
+      maxSteps: 4,
+    })
+    // The AI SDK converts our defs and hands them to the model on the wire.
+    const passedTools = doGenerate.mock.calls[0][0].tools as Array<{ name: string }>
+    expect(Array.isArray(passedTools)).toBe(true)
+    expect(passedTools.some((t) => t.name === 'gnubok_get_income_statement')).toBe(true)
+  })
+
+  it('generateText attaches no tools when none are provided (plain single call)', async () => {
+    const svc = createOpenAICompatibleService(readAiConfig())
+    await svc.generateText({ tier: 'assistant', prompt: 'Hej', maxTokens: 50 })
+    const passedTools = doGenerate.mock.calls[0][0].tools
+    expect(passedTools == null || (Array.isArray(passedTools) && passedTools.length === 0)).toBe(true)
+  })
+
   it('extractFromDocument sends an image as an image part followed by the instruction', async () => {
     const svc = createOpenAICompatibleService(readAiConfig())
     const jpeg = Buffer.from('JPEG')

lib/ai/index.ts

@@ -10,6 +10,7 @@ export type {
   AiPdfMode,
   AiProviderKind,
   AiService,
+  AiToolDef,
   AiStatus,
   AiTier,
   AiUsage,

lib/ai/services/anthropic-family.ts

@@ -6,6 +6,7 @@ import type {
   AiDocumentInput,
   AiService,
   AiTier,
+  AiToolDef,
   AiUsage,
   ExtractFromDocumentRequest,
   ExtractFromDocumentResult,
@@ -15,6 +16,26 @@ import type {
   GenerateTextResult,
 } from '../types'
 
+const DEFAULT_MAX_STEPS = 4
+
+const EMPTY_USAGE: AiUsage = {
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheCreationInputTokens: 0,
+  cacheReadInputTokens: 0,
+}
+
+/** Sum usage across the turns of a tool loop so the reported cost is truthful. */
+function addUsage(a: AiUsage, b: AiUsage): AiUsage {
+  const s = (x: number | null, y: number | null) => (x ?? 0) + (y ?? 0)
+  return {
+    inputTokens: s(a.inputTokens, b.inputTokens),
+    outputTokens: s(a.outputTokens, b.outputTokens),
+    cacheCreationInputTokens: s(a.cacheCreationInputTokens, b.cacheCreationInputTokens),
+    cacheReadInputTokens: s(a.cacheReadInputTokens, b.cacheReadInputTokens),
+  }
+}
+
 /**
  * The Anthropic family (AWS Bedrock and the direct API) behind the job-shaped
  * interface. Delegates to the existing client factory and builds the EXACT
@@ -93,14 +114,78 @@ export function createAnthropicFamilyService(cfg: ResolvedAiConfig): AiService {
 
     async generateText(req: GenerateTextRequest): Promise<GenerateTextResult> {
       const model = modelFor(req.tier)
-      const params: MessageCreateParams = {
+
+      // Fast path (unchanged: keeps hosted byte-identical for every non-tool
+      // caller, which is all of them today): one turn, no tools.
+      if (!req.tools || req.tools.length === 0) {
+        const params: MessageCreateParams = {
+          model,
+          max_tokens: req.maxTokens,
+          ...(req.system ? { system: req.system } : {}),
+          messages: [{ role: 'user', content: req.prompt }],
+        }
+        const resp = await getClient().messages.create(params)
+        return { text: textOf(resp), model, usage: usageOf(resp) }
+      }
+
+      // Bounded read-only tool loop. The same dispatch shape run-turn.ts uses,
+      // minus streaming and staging: the model asks for a report, we run it,
+      // feed the JSON back, repeat up to maxSteps model turns, then answer.
+      const tools: Anthropic.Messages.Tool[] = req.tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        input_schema: t.jsonSchema as Anthropic.Messages.Tool['input_schema'],
+      }))
+      const byName = new Map<string, AiToolDef>(req.tools.map((t) => [t.name, t]))
+      const messages: Anthropic.Messages.MessageParam[] = [{ role: 'user', content: req.prompt }]
+      const maxSteps = req.maxSteps ?? DEFAULT_MAX_STEPS
+      let usage = EMPTY_USAGE
+
+      for (let step = 0; step < maxSteps; step++) {
+        const resp = await getClient().messages.create({
+          model,
+          max_tokens: req.maxTokens,
+          ...(req.system ? { system: req.system } : {}),
+          tools,
+          messages,
+        })
+        usage = addUsage(usage, usageOf(resp))
+        if (resp.stop_reason !== 'tool_use') {
+          return { text: textOf(resp), model, usage }
+        }
+
+        messages.push({ role: 'assistant', content: resp.content })
+        const results: Anthropic.Messages.ContentBlockParam[] = []
+        for (const block of resp.content) {
+          if (block.type !== 'tool_use') continue
+          const def = byName.get(block.name)
+          let content: string
+          let isError = false
+          try {
+            if (!def) {
+              isError = true
+              content = JSON.stringify({ error: `Verktyget ${block.name} är inte tillgängligt.` })
+            } else {
+              const out = await def.execute((block.input ?? {}) as Record<string, unknown>)
+              content = JSON.stringify(out ?? null)
+            }
+          } catch (err) {
+            isError = true
+            content = JSON.stringify({ error: err instanceof Error ? err.message : 'Tool failed' })
+          }
+          results.push({ type: 'tool_result', tool_use_id: block.id, content, is_error: isError })
+        }
+        messages.push({ role: 'user', content: results })
+      }
+
+      // Spent the step budget without a final answer: force one with tools off.
+      const final = await getClient().messages.create({
         model,
         max_tokens: req.maxTokens,
         ...(req.system ? { system: req.system } : {}),
-        messages: [{ role: 'user', content: req.prompt }],
-      }
-      const resp = await getClient().messages.create(params)
-      return { text: textOf(resp), model, usage: usageOf(resp) }
+        messages,
+      })
+      return { text: textOf(final), model, usage: addUsage(usage, usageOf(final)) }
     },
 
     async generateStructured(req: GenerateStructuredRequest): Promise<GenerateStructuredResult> {

lib/ai/services/openai-compatible.ts

@@ -1,5 +1,14 @@
 import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
-import { generateText, jsonSchema, Output, type ModelMessage, type UserContent } from 'ai'
+import {
+  generateText,
+  jsonSchema,
+  Output,
+  stepCountIs,
+  tool,
+  type ModelMessage,
+  type ToolSet,
+  type UserContent,
+} from 'ai'
 import { capabilitiesFor, type ResolvedAiConfig } from '../config'
 import { extractJsonObject } from '../json'
 import { rasterizePdf } from '../rasterize-pdf'
@@ -7,6 +16,7 @@ import type {
   AiDocumentInput,
   AiService,
   AiTier,
+  AiToolDef,
   AiUsage,
   ExtractFromDocumentRequest,
   ExtractFromDocumentResult,
@@ -17,6 +27,31 @@ import type {
   GenerateTextResult,
 } from '../types'
 
+const DEFAULT_MAX_STEPS = 4
+
+/**
+ * Map our provider-agnostic tool defs onto the AI SDK's tool() shape. The SDK
+ * runs the loop itself (calls execute, feeds the result back) up to the
+ * stopWhen bound. Returns undefined when there is nothing to attach.
+ */
+function toSdkTools(defs: AiToolDef[] | undefined): ToolSet | undefined {
+  if (!defs || defs.length === 0) return undefined
+  const out: ToolSet = {}
+  for (const def of defs) {
+    out[def.name] = tool({
+      description: def.description,
+      inputSchema: jsonSchema<Record<string, unknown>>(def.jsonSchema),
+      execute: async (args) => {
+        const result = await def.execute((args ?? {}) as Record<string, unknown>)
+        // The SDK serialises whatever we return as the tool result; null is a
+        // valid "nothing" that a model reads fine, undefined is not.
+        return result ?? null
+      },
+    })
+  }
+  return out
+}
+
 /**
  * Any endpoint speaking the OpenAI chat-completions API, through the Vercel
  * AI SDK's openai-compatible provider. This is the sovereign self-host path:
@@ -122,11 +157,15 @@ export function createOpenAICompatibleService(cfg: ResolvedAiConfig): AiService
 
     async generateText(req: GenerateTextRequest): Promise<GenerateTextResult> {
       const model = modelFor(req.tier)
+      // Only attach tools when the configured model advertises tool use; a
+      // text-only local model still answers, just from the prompt (+ snapshot).
+      const tools = capabilities.toolUse ? toSdkTools(req.tools) : undefined
       const result = await generateText({
         model: provider(model),
         ...(req.system ? { system: req.system } : {}),
         prompt: req.prompt,
         maxOutputTokens: req.maxTokens,
+        ...(tools ? { tools, stopWhen: stepCountIs(req.maxSteps ?? DEFAULT_MAX_STEPS) } : {}),
       })
       return { text: result.text.trim(), model, usage: usageOf(result) }
     },

lib/ai/types.ts

@@ -48,11 +48,39 @@ export interface AiUsage {
   cacheReadInputTokens: number | null
 }
 
+/**
+ * A tool the model may call during a bounded generateText loop.
+ *
+ * Provider-agnostic by construction: the OpenAI-compatible service maps it to
+ * a Vercel AI SDK `tool()` and lets the SDK drive the loop; the Anthropic-
+ * family service maps it to a Messages `tool` block and runs the loop by hand.
+ * `execute` runs the tool and returns any JSON-serialisable value, which is
+ * fed back to the model as the tool result. Only ever pass READ-only tools:
+ * this path has no approval-card surface for staged writes.
+ */
+export interface AiToolDef {
+  name: string
+  description: string
+  /** JSON Schema (draft-07 subset) for the tool's arguments. */
+  jsonSchema: Record<string, unknown>
+  execute: (args: Record<string, unknown>) => Promise<unknown>
+}
+
 export interface GenerateTextRequest {
   tier: AiTier
   system?: string
   prompt: string
   maxTokens: number
+  /**
+   * Read-only tools the model may call to gather data before answering. When
+   * present AND the backend supports tool use (capabilities.toolUse), the
+   * service runs a bounded tool loop of up to `maxSteps` model turns; a
+   * backend without tool support ignores them and answers from the prompt
+   * alone (so a snapshot in the prompt is the fallback grounding).
+   */
+  tools?: AiToolDef[]
+  /** Max model turns in the tool loop (default 4). Ignored when `tools` is absent. */
+  maxSteps?: number
 }
 
 export interface GenerateTextResult {