refactor(exa): share provider dispatch and usage recording

[iscekic]

No new behavior — existing search requests, results, and charges stay the same.

---

Summary

prepareExaRequest shares allowance checks, dispatch, and billing without a harness dependency; callers must supply freshly authorized user and organization context and call record separately.
send forwards cancellation and follows redirects by default; jsonOnly=true requests JavaScript Object Notation (JSON) and rejects redirects.
extractExaCostMicrodollars uses ExaCostResponseSchema, distinguishes zero from missing cost, and preserves invalid-cost exceptions; record charges neither zero nor missing costs.

Files

• apps/web/src/lib/exa-provider.ts — Source; added (A), 98 changed lines (+98/-0). Provides server-only operations using replica reads, stored-allowance fallback, per-request billing decisions, and user, organization, featureId, and type attribution. Keeps the existing EXA_API_KEY requirement, 500/402 responses, and monthlyAllowance/used fields. Converts positive costs to safe integer microdollars and logs upstream failures without changing their responses.

The legacy Exa POST contract retains search, contents, findSimilar, answer, and context, with unchanged authentication, organization access, responses, safe headers, and errors.
It delegates provider work while retaining stream removal, validated FEATURE_HEADER attribution, string type attribution, and cancellation.
Existing callers keep deferred after billing and cost-exception reporting; upstream failures still create no charge.

Files

• apps/web/src/app/api/exa/[...path]/route.ts — Source; modified (M), 146 changed lines (+18/-128). Replaces inline allowance, dispatch, and cost logic with provider calls. Keeps authentication before path validation, response cloning, validated attribution, and the safe response wrapper.

Tests: 1 file added — apps/web/src/lib/exa-provider.test.ts (Test; A; 137 changed lines, +137/-0). Uses dependency mocks to cover endpoint forwarding, stream removal, deferred billing, free/paid usage, attribution, missing/zero costs, JSON/redirect controls, and uncharged 429/503 responses.
Generated: 0 changed files.

---

Visual Changes

Visual Changes: N/A

Verification

This level has no reported manual tests. Live Exa checks belong to A32 and bot-e2e, and final runtime acceptance remains pending.

Reviewer Notes

Human steps: None before merge or after merge.

• The implementer reported 45 passing tests across the provider and legacy route suites with no-setup dependency mocks.
• The reviewer independently passed the provider suite, scoped lint, formatting, and whitespace checks.
• These checks do not prove live Exa behavior, real database writes, deployment, or final runtime acceptance.
• Continuous integration (CI) owns repository-wide type and build checks.
• Repository: Kilo-Org/cloud. Worktree: /Users/igor/Projects/.worktrees/shared-agent-harness-3bb0.
• Review range: shared-agent-harness-3bb0-s26...shared-agent-harness-3bb0-s27.

Runtime verification remains pending at the stack tip. This level shares Exa provider operations while preserving the legacy proxy contract.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. shared-agent-harness-3bb0 — chore(agent-harness): register workspaces and enforce CI boundaries #5632
2. shared-agent-harness-3bb0-s2 — feat(agent-harness): define portable domain and snapshots #5637
3. shared-agent-harness-3bb0-s3 — feat(agent-harness): define commands tools and permission policy #5639
4. shared-agent-harness-3bb0-s4 — feat(agent-harness): share client state and cursor recovery #5643
5. shared-agent-harness-3bb0-s5 — feat(agent-harness): persist command intents and execution receipts #5647
6. shared-agent-harness-3bb0-s6 — feat(db): add harness ingress grants and retirement fences #5655
7. shared-agent-harness-3bb0-s7 — feat(agent-harness): deliver legacy history and project durable text #5659
8. shared-agent-harness-3bb0-s8 — feat(agent-harness): authorize durable grants and registered clients #5662
9. shared-agent-harness-3bb0-s9 — feat(agent-harness): fence retirement and retry payload cleanup #5667
10. shared-agent-harness-3bb0-s10 — feat(agent-harness): persist authoritative state in SQLite #5675
11. shared-agent-harness-3bb0-s11 — feat(agent-harness): admit durable runs and revisioned commands #5678
12. shared-agent-harness-3bb0-s12 — feat(agent-harness): recover queued runs and stream checkpointed steps #5688
13. shared-agent-harness-3bb0-s13 — feat(agent-harness): resolve interactions and dispatch tools sequentially #5693
14. shared-agent-harness-3bb0-s14 — feat(agent-harness): fence designated client tool execution #5697
15. shared-agent-harness-3bb0-s15 — feat(agent-harness): synchronize durable snapshots and legacy history #5701
16. shared-agent-harness-3bb0-s16 — feat(agent-harness): reuse authorized invitations with durable replay #5704
17. shared-agent-harness-3bb0-s17 — feat(integrations): bound repository transport for harness reads #5710
18. shared-agent-harness-3bb0-s18 — feat(integrations): expose bounded authorized repository reads #5714
19. shared-agent-harness-3bb0-s19 — feat(agent-harness): expose named authorized resource reads #5718
20. shared-agent-harness-3bb0-s20 — feat(sessions): bound history transport for harness reads #5724
21. shared-agent-harness-3bb0-s21 — feat(agent-harness): read scoped Cloud Agent context and progress #5726
22. shared-agent-harness-3bb0-s22 — fix(agent-harness): preserve ordered Cloud Agent dispatch identity #5731
23. shared-agent-harness-3bb0-s23 — feat(agent-harness): hand coding work to authorized Cloud Agent sessions #5733
24. shared-agent-harness-3bb0-s24 — feat(agent-harness): authorize scoped MCP gateway connections #5737
25. shared-agent-harness-3bb0-s25 — feat(agent-harness): bound MCP gateway transport in the Worker #5740
26. shared-agent-harness-3bb0-s26 — feat(agent-harness): execute validated remote MCP tools #5743
27. shared-agent-harness-3bb0-s27 — refactor(exa): share provider dispatch and usage recording #5746 ← this PR
28. shared-agent-harness-3bb0-s28 — feat(agent-harness): authorize bounded web provider requests #5747
29. shared-agent-harness-3bb0-s29 — feat(agent-harness): normalize web sources and preserve citations #5749
30. shared-agent-harness-3bb0-s30 — feat(agent-harness): define closed internal operation contracts #5753
31. shared-agent-harness-3bb0-s31 — feat(agent-harness): authorize internal maintenance operations #5754
32. shared-agent-harness-3bb0-s32 — feat(agent-harness): authorize named Kilo operation dispatch #5755
33. shared-agent-harness-3bb0-s33 — feat(agent-harness): authorize internal provider operations #5757
34. shared-agent-harness-3bb0-s34 — feat(agent-harness): secure the internal operations endpoint #5758
35. shared-agent-harness-3bb0-s35 — feat(agent-harness): bound and sanitize model streams #5767
36. shared-agent-harness-3bb0-s36 — feat(agent-harness): secure billed model inference #5776
37. shared-agent-harness-3bb0-s37 — test(agent-harness): cover model gateway security boundaries #5777 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

Shared Exa provider extract preserves the legacy proxy contract for allowance, dispatch, and deferred billing; no correctness or security issues found.

Files Reviewed (3 files)

• apps/web/src/app/api/exa/[...path]/route.ts
• apps/web/src/lib/exa-provider.ts
• apps/web/src/lib/exa-provider.test.ts

---

_{Reviewed by grok-4.6 · Input: 199.4K · Output: 14K · Cached: 294.8K}

_{Review guidance: REVIEW.md from base branch shared-agent-harness-3bb0-s26}

[iscekic]

Closing: the owner stopped this workflow section. The branch is retained.