# How "Ask" works (MEGA) — brief for building the same thing in Healy

## Correction first
The in-app chat does NOT use MCP. It calls tool functions directly inside the Next.js server.
MCP (`src/mcp/server.ts`) is a separate, optional, read-only wrapper over the same tools, run locally
over stdio for Claude Desktop/Code. Build the tool layer first; treat MCP as a thin extra.

## Stack
- Next.js 16 (App Router), React 19, TypeScript, Tailwind 4, vitest
- PocketBase via `pocketbase` SDK, superuser client on the server only (`pbAdmin()`)
- Model: MiniMax M3 via OpenAI-compatible endpoint (`https://api.minimax.io/v1`); Anthropic `claude-opus-5`
  behind the same interface. `CHAT_PROVIDER` selects.
- Streaming: SSE from `POST /api/chat` (plain `ReadableStream`; browser reads with `fetch`)
- Tool schemas: `zod` -> `zod-to-json-schema`
- UI markdown: `react-markdown` + `remark-gfm` mapped onto the app's own table styles

## Architecture
1. `src/lib/chat/` — provider-neutral core: `types.ts` (no SDK imports), `loop.ts` (model -> tools -> model,
   with max-iterations valve), `provider-anthropic.ts`, `provider-openai.ts` (one SDK each),
   `system-prompt.ts` (built per request: date + user memories), `think-filter.ts`.
2. `src/lib/agent/` — tools: `tools.ts` (read tools), `tools-actions.ts` (write tools), `load.ts` (fetching),
   `format.ts` (shaping + `display` strings), `resolve.ts` (name -> id), `query.ts` (generic `query_records`),
   `gateway.ts` (the write seam), `schema-cache.ts`.
3. `src/lib/metrics/` — ALL business calculations as pure tested functions, shared by dashboard and agent.
4. `/api/chat` — env gate, identify user, persist thread, run loop, stream events.
5. `/dashboard/chat` — client SSE reader, threads, attachments, confirm cards, charts, PDF.

## Rules that make it trustworthy
- The model never does arithmetic. Tools return finished numbers + preformatted `display`. Prompt bans
  sum/average/percent/"combined" and says what to do instead (list rows, say aggregate not available).
  The first wording failed a live probe — keep "combined value of top three" as a regression probe.
- Name resolution returns ambiguity lists instead of guessing.
- `query_records`: typed generic read, filters bound with `pb.filter()`, grouping/aggregation in JS.
- Tool failures go back to the model as error results and are logged server-side.

## Writes
Model calls `propose_changes` -> pending row in `ask_log` -> confirm card -> human presses Confirm ->
`applyAction` writes -> each op keeps a `before` snapshot -> Undo. Ops validated against live schema.
`authorize()` is the single permission seam with a `NEVER_WRITABLE` set (`_superusers`, `users`, chat tables).
Ops run sequentially so `$ref:` can reference records created earlier in the batch.
**For Healy: remove the `delete` op kind entirely** (union type, planner, apply). Decide deliberately
whether Undo may delete records the agent itself just created (recommended: yes, and nothing else).

## Gotchas
MiniMax
- M2/M2.7 are text-only. M3 is the first accepting BOTH `tools` and images. Test both together.
- Use the OpenAI-compatible route; the `/anthropic` shim mangles tool-call args.
- Reasoning streams inline in `<think>…</think>`; strip it with a stateful filter (tags split across chunks).
- Tool-call args arrive as string fragments per index; concatenate before `JSON.parse`.
- Key must be an Open Platform API key (not Token Plan subscription key, not Hailuo/MiniMax Agent).
- Image endpoint: `{base minus /v1}/v1/image_generation` (appending /v1 to base gave /v1/v1).
Anthropic
- `budget_tokens` and assistant prefill are removed (400). Use `thinking: {type: "adaptive"}`.
PocketBase
- `sort=-created` / `-updated` can 400 with an empty body. Sort a real field or use autodate fields.
- `getList(1, 500)` silently truncates; use `getFullList`.
- `fields:` that omits a date field makes later date logic silently skip rows.
- A detail-less 400 is usually a bad filter/sort; reproduce with a direct `getFullList`.
Chat plumbing
- History crosses JSON; types guarantee nothing. Normalise in the route (assistant turns arrive without `toolCalls`).
- Compare `Origin` to the `Host` header, not `request.url`.
- Agent loop needs more than 8 iterations for "read file -> match -> propose".

## Brief to give the Healy agent
> Build a chat agent for Healy shaped like MEGA's "Ask". Next.js + PocketBase, SSE from `POST /api/chat`.
> Provider-neutral loop with two adapters (MiniMax M3 via OpenAI-compatible endpoint; Anthropic fallback).
> Tools are zod-schema'd functions; all business maths lives in pure tested functions shared with the UI.
> Reads: typed tools per domain + generic `query_records`; model never does arithmetic; tools return `display`.
> Writes: create and update only, NO delete. Propose -> pending log row -> human confirm -> apply, with
> `before` snapshot and undo; validate against live schema; keep a never-writable list.
> API access: expose the same handlers as REST and as an MCP server, both authenticated.
> Also: strip `<think>`, reassemble fragmented tool args, normalise history at the route, log tool failures.

## Decide deliberately (API + MCP + writes)
- Auth: Ask used an `x-ask-user` header + shared PIN during testing. A create/update API or MCP surface needs
  real per-user authentication.
- MCP is headless (no human to confirm). Either keep MCP read-only, or let it only create PENDING actions a
  person confirms in the app (recommended).