Advisory Desk

financialTools is an array of Anthropic Tool definitions exported from src/lib/chat/tools.ts, lines 7 to 390. It holds twenty definitions: twelve financial, eight payroll and compensation. Each has a matching …Input interface, and the twenty are unioned into an exported ToolInput type.

Four structural invariants are checked across the whole array rather than tool by tool: every name is unique, every description exceeds ten characters after trimming, every input_schema.type is 'object', and every schema defines a properties object. A tool added without a real description fails the suite.

$ npm test -- __tests__/lib/chat/tools.test.ts

> gogenticcfo@0.1.0 test
> jest __tests__/lib/chat/tools.test.ts

FAIL __tests__/lib/chat/tools.test.ts
  Financial Tools
    Tool Definitions
      ✓ should export an array of tools
      ✗ should have exactly 19 tools defined (12 financial + 7 payroll)

  ● Financial Tools › Tool Definitions › should have exactly 19 tools defined

    expect(received).toHaveLength(expected)

    Expected length: 19
    Received length: 20
    Received array:  [ … ]

      11 |     it('should have exactly 19 tools defined (12 financial + 7 payroll)', () => {
    > 12 |       expect(financialTools).toHaveLength(19);
         |                              ^

Reconstructed from the committed sources: the assertion at tools.test.ts:12 and the twenty name: entries in tools.ts. The array dump is elided. The remaining 77 assertions in the file address individual tools and are unaffected.

Parameters and their enumerations, read directly from the exported schemas. The required column is significant: only four of the twenty tools declare a required parameter at all, so the model can call most of them bare and refine afterwards.

Source: src/lib/chat/tools.ts. Only four of the twenty tools declare a required array: get_metrics, calculate, get_trends and get_monthly_metrics.

The twentieth tool, get_team_compensation, is the newest. Its description spans both payroll sources: W2 employees from the Gusto-originated journal entries and 1099 contractors from QuickBooks, split across five employment classifications. See Sheet 4.

handleToolCall(name, input, userId) is the only entry point. It returns a JSON string in every case, including failure — a test iterates all eleven implemented handlers plus one nonexistent name and asserts JSON.parse never throws on any of them. Errors are values, not exceptions.

handleToolCall('unknown_tool', {}, userId)
  → '{"error":"Unknown tool: unknown_tool"}'

// a rejected database call is caught and surfaced the same way
// with the underlying message preserved verbatim:
  → { error: 'Database error' }
  → { error: 'Aggregation failed' }
  → { error: 'Settings query failed' }

Bounds on query_transactions

The fifty-row ceiling is why TASKS.md 9.1 added both an aggregate mode — SQL aggregation with no limit — and “a warning when hitting the 50 transaction limit”, so a truncated answer announces itself rather than silently under-reporting.

Response vocabulary

Handlers return prose-ready values alongside raw ones, so the model does not have to format currency itself and cannot get it wrong.

Tool results are cached in a process-local Map, keyed by user, for sixty seconds. Four tests exist for this one property, under a describe block named “Multi-tenant cache isolation”.

const cache = new Map<string, { data: string; expires: number }>();
const CACHE_TTL = 60 * 1000; // 1 minute

// every lookup is namespaced by the caller
const cacheKey = `${userId}:${key}`;

There is no size cap and no background eviction — an expired entry is deleted lazily, on the next read that misses it. Because the map lives in module scope, each serverless instance keeps its own copy and a warm instance is the only place a hit can occur.

What is cached, and what is not

The test design is worth describing because it proves the negative rather than the positive. Each test primes the cache for one user, then arranges the database mock to return the wrong user's data on the next call. If the cache leaked, the second user would receive the first user's figures; if it were absent, the first user's repeat call would pick up the deliberately mismatched fixture. Both directions are asserted.

// 1. populate user A's cache
mockDb._setResults([userAAccounts]);
await handleToolCall('get_accounts', {}, TEST_USER_ID);   // A's data

// 2. user B must NOT be served from A's entry
mockDb._setResults([userBAccounts]);
await handleToolCall('get_accounts', {}, OTHER_USER_ID);  // B's data

// 3. A repeats — the mock is loaded with B's data, so a cache
//    miss here would return the wrong figures. It returns A's.
mockDb._setResults([userBAccounts]);
await handleToolCall('get_accounts', {}, TEST_USER_ID);   // still A's data

clearCache() is exported alongside handleToolCall and safeEvaluate, and is called in beforeEach throughout the suite so that no test inherits another's cached state.

Language models are unreliable at arithmetic, so the agent is given a calculator. It could not be eval, so safeEvaluate is a hand-written expression parser with 46 tests of its own.

What it refuses

The last three sit in a describe block titled “should reject potentially dangerous input”. They are caught by the same character allow-list that rejects x, which is the point: the parser has no escape hatch to close, because it never had one.

Division by zero throws rather than returning Infinity. In a financial context that is the right call — a runway of Infinity is meaningful and is handled explicitly by get_metrics, but an accidental infinity arriving out of a calculator would be indistinguishable from it.

POST /api/chat answers with a stream of newline-delimited data: frames. Five event types travel over it, and the client is written to survive anything else that arrives.

The same model identifier appears in exactly one other place, src/lib/ai/categorize.ts, also at max_tokens: 4096. Those two call sites are the entire model surface of the application.

Frame handling

Framing

Lines of the form data: <json>\n — a single newline, not the blank-line terminator of canonical SSE. The reader splits on newlines and inspects the prefix.

Unknown prefixes

A line beginning event: message is skipped silently. The client reads only data:.

Empty payload

data: with nothing after it is skipped.

Malformed JSON

Logged via console.warn; the loop continues and later valid frames are still processed. One bad frame does not abort a response.

An error frame

Caught by an inner handler and warned, deliberately not promoted to the context's error state — a mid-stream tool failure does not blank the answer already rendered.

Request validation

chatRequestSchema is exported separately from the route handler so it can be tested in isolation, and it is strict in both directions.

Whitespace is not trimmed: ' ' satisfies the minimum-length rule. The empty-message guard that actually matters lives in the client, which refuses to call the endpoint at all for an empty or whitespace-only input.

Two implementations coexist. useChat is a self-contained hook that talks only to /api/chat, handles only text frames and explicitly ignores the rest. ChatContext is the one the application mounts: it adds persistence, conversation switching, tool status and cancellation. Both are tested; only the context is reachable from the running app. message-list.tsx imports the hook's Message type and nothing else from it.

messages: Message[]                 // { id, dbId?, role, content, createdAt }
isLoading: boolean
error: string | null
isOpen: boolean
toolStatus: { isActive: boolean; toolName: string | null }
conversationId: string | null
conversations: Conversation[]
isLoadingConversations: boolean

setIsOpen(open)          sendMessage(content)      clearMessages()
cancelRequest()          loadConversations()       selectConversation(id)
createNewConversation()  deleteConversation(id)

Eight values and eight functions. useChatContext() throws 'useChatContext must be used within a ChatProvider' outside the provider — the provider is mounted once, in src/app/(dashboard)/layout.tsx, wrapping the entire dashboard.

Three properties of the context worth naming

No stale history

The message array is mirrored into a ref so that the request body always carries the current history rather than the array captured when the handler was created. The test is exact: the first call sends one message, the second sends three — the original question, the assistant's reply, and the new question.

Aborts are not errors

Sending a second message while the first is still streaming aborts the first. A rejection whose name is 'AbortError' is asserted not to set the error state. clearMessages() aborts too.

The finally block

After every send — success, abrupt stream end, network rejection, or a non-OK response — isLoading returns to false and toolStatus resets to { isActive: false, toolName: null }. Four separate tests assert this, one per exit path, so the interface cannot be left showing a spinner.

Retry policy on the client

A fetchWithRetry(url, options, maxRetries = 2) wrapper sits in front of the chat call. A 4xx returns immediately; a 5xx or a network failure is retried with exponential backoff of 1000 × 2attempt milliseconds — one second, then two. Client faults surface at once as Chat request failed.

Rendering a partial answer

Streamed markdown is, by definition, usually invalid — a code fence may be open, a link half-written, a bold run unterminated. sanitizeStreamingMarkdown repairs the string before each render so the view never flickers through a broken parse.

What the panel says while it works

ToolStatusIndicator maps a tool name to a phrase. It is a role="status" region with aria-live="polite", so a screen reader announces the change without interrupting.

Eight of the twenty tools have a bespoke phrase. The remaining twelve — including all eight payroll tools — fall through to Working…. The map is a module constant, TOOL_DISPLAY_CONFIG, in src/components/chat/tool-status-indicator.tsx.

Opening prompts

An empty conversation offers four fixed suggestions under the heading Try asking:. They map onto the four headline metrics the dashboard already computes, which is what makes them answerable in a single tool call.

Prompt strings are asserted verbatim in __tests__/components/chat/suggested-prompts.test.tsx. The tool mapping in the right-hand column is inference, not assertion — no test connects a prompt to a tool.