feat: add read-only savings agent tools

backlog/tasks/task-3 - Build-read-only-savings-agent-with-tool-calls.md

@@ -0,0 +1,53 @@
+---
+id: TASK-3
+title: Build read-only savings agent with tool calls
+status: In Progress
+assignee: []
+created_date: '2026-06-15 19:02'
+updated_date: '2026-06-15 19:11'
+labels: []
+dependencies: []
+priority: high
+ordinal: 3000
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Convert Talk to Savings from a prompt-packed chat into a read-only AI SDK tool-calling agent with deterministic transaction retrieval, spending summaries, forecasts, and compact frontend tool traces.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 Savings chat action uses AI SDK tool calls with a bounded multi-step loop and returns a compact tool trace
+- [x] #2 Read-only transaction retrieval tool supports selected scope, bounded custom ranges, account/category/search filters, exact totals, sanitized rows, and hasMore
+- [x] #3 Spending summary and cashflow forecast tools compute deterministic aggregates without model-invented math
+- [x] #4 Frontend remains localStorage-backed, loads legacy chats, and renders compact tool traces under assistant answers
+- [x] #5 Focused Convex tests, build, and targeted lint verification pass or known blockers are documented
+<!-- AC:END -->
+
+## Implementation Plan
+
+<!-- SECTION:PLAN:BEGIN -->
+1. Write failing Convex tests for read-only tool queries and traces
+2. Implement internal read-only savings agent tool queries
+3. Switch savingsChat.ask to AI SDK tool calling with bounded multi-step loop
+4. Update frontend chat messages and compact tool trace rendering
+5. Run focused tests, build, targeted lint, and record verification notes
+<!-- SECTION:PLAN:END -->
+
+## Implementation Notes
+
+<!-- SECTION:NOTES:BEGIN -->
+Implementation complete pending user confirmation.
+
+Subagents:
+- Frontend UX worker updated src/pages/SavingsChatPage.tsx for legacy-safe localStorage message normalization and compact assistant tool traces.
+- QA explorer reviewed Convex test strategy and confirmed mock AI SDK approach for ask() coverage.
+
+Verification:
+- PASS npx vitest convex/savingsChat.test.ts --run (8 tests)
+- PASS npx eslint convex/savingsChat.ts convex/savingsChat.test.ts src/pages/SavingsChatPage.tsx
+- PASS npm run build
+- BLOCKED npm run lint on pre-existing unrelated files: convex/bank/comdirectProvider.ts, convex/bank/config.ts, src/components/import/TanAwaitDialog.tsx, layout/ui fast-refresh exports, SettingsPage.tsx, generated eslint-disable warnings, and existing React compiler warnings. No TASK-3 touched file appears in the full-lint error list.
+<!-- SECTION:NOTES:END -->