feat(ai): job-shaped AI service with OpenAI-compatible backend, extraction-first; stop extracting every inbox document twice (#1740)

* feat(ai): job-shaped AI service with OpenAI-compatible backend, extraction-first; stop extracting every inbox document twice

Sovereign plan WS1 PR1 (#1406 Tier 2, extraction-first, aligned with the
AI surface audit).

lib/ai grows a job-shaped service (generateText / generateStructured /
extractFromDocument; no streaming members yet, see plan rule R3):
- services/anthropic-family delegates to the existing createAiClient()
  and sends the exact request literals the inbox extractor sent before
  (request-shape tests deep-equal them), so hosted Bedrock stays
  byte-identical.
- services/openai-compatible talks to any chat-completions endpoint
  (BYO Swedish provider) via Vercel AI SDK 6.x, exact-pinned and
  guarded: images as parts, PDFs rasterized with poppler (AI_PDF_MODE)
  or sent natively, AI_VISION / AI_STRICT_JSON declared, honest skips
  (ai_no_vision, pdf_rasterizer_missing) instead of fake failures.
- config.ts: AI_PROVIDER/AI_BASE_URL/AI_API_KEY/AI_MODEL and per-tier
  AI_*_MODEL with the legacy BEDROCK_* names kept as the same overrides;
  getAiStatus() is the single source of truth for "is AI wired up".
- provider.ts: openai-compatible in the auto-detect chain (after Bedrock
  and the direct API); createAiClient() refuses it loudly.

Document extraction moves onto the service and gets the audit's fixes:
- Inbox documents were extracted TWICE (pipeline A ran inside
  uploadDocument() before the inbox row existed, so its dedupe branch
  never fired; 3 707 + 1 666 calls / 30 d). The inbox now declares
  extractionOwner on the upload, the extension yields, and the inbox
  mirrors its single outcome onto document_attachments from every
  writer (sync, deferred, attach, retry, MCP).
- Every "no extraction will ever happen" outcome is stamped
  (skipped:no_ai_entitlement / ai_unconfigured / system_generated /
  ...); the status route maps the quiet ones to 'disabled' on the first
  poll instead of a 30 s client timeout. Prod showed 309 of the 327
  never-extracted uploads were the paywall working silently.
- Self-generated documents (our own invoice PDFs, payout files) are no
  longer OCR'd.
- Agent invoke answers 503 ai_unconfigured when the deployment has no
  assistant backend, distinct from the paywall.

Guard: new direct-ai-client antipattern check (shrink-only allowlist of
the pre-abstraction SDK callers) plus exact pins for @anthropic-ai/sdk,
ai and @ai-sdk/openai-compatible.

Verified: 15 958 unit tests green, guards, lint ratchet, typecheck, and a
live smoke against hosted Bedrock through the new service (ping, streamed
tool turn, thinking+cache, PDF extraction).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(ai): make AI_API_KEY optional for OpenAI-compatible endpoints (keyless local model servers)

A local model server (llama.cpp's server, Ollama /v1, LM Studio, vLLM)
usually has no auth. Before, the OpenAI-compatible backend required both
AI_BASE_URL and AI_API_KEY to count as configured, so running Accounted on a
local model meant setting a meaningless placeholder key.

- resolveAiProvider / hasAiCredentials: a base URL alone is now enough.
- services/openai-compatible: only send Authorization: Bearer when AI_API_KEY
  is set, so a keyless server is never handed an empty bearer; a hosted
  provider that needs a key still sets it.
- Docs (SELF-HOSTING Option 3: local-model example, key marked optional),
  DECISIONS.

Verified: with no AI_API_KEY, just AI_BASE_URL + AI_MODEL, getAiStatus()
reports configured=true / provider=openai-compatible (live). lib/ai suite
71 green; tsc, guards, lint clean. Bedrock/Anthropic logic unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

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

app/api/agent/__tests__/invoke.test.ts

@@ -50,6 +50,13 @@ vi.mock('@/lib/agent/intents/registry', () => ({
   getIntent: (...args: unknown[]) => getIntentMock(...args),
 }))
 
+// Deployment-level AI availability (distinct from the per-company paywall).
+// Default: available, so the ownership tests below exercise the real flow.
+const aiStatusMock = vi.fn()
+vi.mock('@/lib/ai', () => ({
+  getAiStatus: () => aiStatusMock(),
+}))
+
 const runChatTurnMock = vi.fn()
 vi.mock('@/lib/agent/chat/run-turn', () => ({
   runChatTurn: (...args: unknown[]) => runChatTurnMock(...args),
@@ -92,6 +99,7 @@ beforeEach(() => {
   checkRateMock.mockResolvedValue({ ok: true })
   getIntentMock.mockReturnValue({ id: 'general.help', sheetTitle: 'Assistenten' })
   runChatTurnMock.mockResolvedValue(undefined)
+  aiStatusMock.mockReturnValue({ configured: true, assistantAvailable: true, provider: 'bedrock' })
 })
 
 describe('POST /api/agent/invoke', () => {
@@ -119,6 +127,20 @@ describe('POST /api/agent/invoke', () => {
     expect(status).toBe(400)
   })
 
+  // A self-host without an AI key, or on an OpenAI-compatible endpoint the
+  // chat loop does not speak yet: say so up front with a distinct code, never
+  // open a stream that dies on the first model call, never confuse it with
+  // the paywall.
+  it('returns 503 ai_unconfigured when the deployment has no assistant backend', async () => {
+    aiStatusMock.mockReturnValue({ configured: false, assistantAvailable: false, provider: 'bedrock' })
+    enqueuePreamble()
+    const res = await POST(createMockRequest('/api/agent/invoke', { method: 'POST', body: body() }))
+    const { status, body: json } = await parseJsonResponse<{ error: string; code: string }>(res)
+    expect(status).toBe(503)
+    expect(json.code).toBe('ai_unconfigured')
+    expect(runChatTurnMock).not.toHaveBeenCalled()
+  })
+
   it('returns 403 when the user is not a member of the company', async () => {
     enqueue({ data: null }) // company_members: no row
     const res = await POST(createMockRequest('/api/agent/invoke', { method: 'POST', body: body() }))

app/api/agent/invoke/route.ts

@@ -7,6 +7,7 @@ import { getActiveCompanyId } from '@/lib/company/context'
 import { getIntent } from '@/lib/agent/intents/registry'
 import { checkAgentRateLimit, agentRateLimitResponseBody } from '@/lib/rate-limits/agent'
 import { runChatTurn, friendlyModelError } from '@/lib/agent/chat/run-turn'
+import { getAiStatus } from '@/lib/ai'
 import { guardSandbox } from '@/lib/sandbox/guard'
 import { requireCapability } from '@/lib/entitlements/has-capability'
 import { CAPABILITY } from '@/lib/entitlements/keys'
@@ -117,6 +118,20 @@ export async function POST(request: Request) {
   const capBlocked = await requireCapability(supabase, companyId, CAPABILITY.ai)
   if (capBlocked) return capBlocked
 
+  // Distinct from the paywall: the deployment has no AI backend the chat
+  // loop can run on (no credentials, or an OpenAI-compatible endpoint, which
+  // the loop does not speak yet). Answer up front instead of opening a
+  // stream that dies on the first model call.
+  if (!getAiStatus().assistantAvailable) {
+    return NextResponse.json(
+      {
+        error: 'Assistenten är inte konfigurerad på den här installationen.',
+        code: 'ai_unconfigured',
+      },
+      { status: 503 },
+    )
+  }
+
   // Resolve the conversation BEFORE any side effect below (the onboarding
   // intake stamp): a request that is about to be rejected must not write.
   let conversationId = body.conversation_id ?? null