---
id: TASK-3
title: Build read-only savings agent with tool calls
status: Done
assignee: []
created_date: '2026-06-15 19:02'
updated_date: '2026-06-15 19:54'
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 -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Closed as Done after explicit user confirmation to mark all tasks done.
<!-- SECTION:FINAL_SUMMARY:END -->