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/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) }
     },