ADR: Agent runtime architecture #48

New issue

Closed

opened 2026-06-14 19:51:59 +00:00 by james · 0 comments

james commented

2026-06-14 19:51:59 +00:00

Owner

Write an ADR resolving the load-bearing technical choices for the agent runtime before any code lands.

Scope — the ADR must answer

Provider strategy. Anthropic-only? Multi-provider via a thin abstraction? Local-only via Ollama? Pluggable per-user in settings? Default for self-hosters who want zero third-party calls.
Where the agent loop runs. Server-side (a Next.js route handler holds the conversation, streams tokens back) vs client-side (browser orchestrates). Server-side is mandatory for MCP clients since they can't reach the browser; whether the PWA reuses that endpoint or has its own loop is the open question.
Streaming transport. SSE vs the Vercel AI SDK stream protocol vs WebSocket. Must work behind the existing auth middleware and not break the PWA's offline shell.
Conversation persistence schema. conversations and messages tables (per-user FK as always). Decide message shape: raw provider messages or a normalised form. How tool-call rounds are represented in storage.
API key handling. Where the user's provider key lives (DB row, env var, neither). Encryption at rest if DB. Per-user vs per-instance.
Write-confirmation handoff. Write tools return proposed changes; the runtime must support a "paused conversation waiting for confirmation" state. How that's modelled (a paused message, a pending-action row, etc.) and how the conversation resumes when the user clicks confirm in the PWA or a commit hits via MCP.

Follow the ADR format in docs/adr/0001-record-architecture-decisions.md.

Acceptance criteria

ADR written and accepted, covering every bullet in Scope.
ADR linked from docs/adr/README.md.
No code in this ticket — pure design. Implementation lands in the chat UI and MCP tickets that reference this ADR.

Part of epic #47. Should land before the chat UI, domain tool surface, and MCP endpoint tickets — those reference its decisions.

Write an ADR resolving the load-bearing technical choices for the agent runtime before any code lands. ## Scope — the ADR must answer - **Provider strategy.** Anthropic-only? Multi-provider via a thin abstraction? Local-only via Ollama? Pluggable per-user in settings? Default for self-hosters who want zero third-party calls. - **Where the agent loop runs.** Server-side (a Next.js route handler holds the conversation, streams tokens back) vs client-side (browser orchestrates). Server-side is mandatory for MCP clients since they can't reach the browser; whether the PWA reuses that endpoint or has its own loop is the open question. - **Streaming transport.** SSE vs the Vercel AI SDK stream protocol vs WebSocket. Must work behind the existing auth middleware and not break the PWA's offline shell. - **Conversation persistence schema.** `conversations` and `messages` tables (per-user FK as always). Decide message shape: raw provider messages or a normalised form. How tool-call rounds are represented in storage. - **API key handling.** Where the user's provider key lives (DB row, env var, neither). Encryption at rest if DB. Per-user vs per-instance. - **Write-confirmation handoff.** Write tools return proposed changes; the runtime must support a "paused conversation waiting for confirmation" state. How that's modelled (a paused message, a pending-action row, etc.) and how the conversation resumes when the user clicks confirm in the PWA or a commit hits via MCP. Follow the ADR format in `docs/adr/0001-record-architecture-decisions.md`. ## Acceptance criteria - [ ] ADR written and accepted, covering every bullet in Scope. - [ ] ADR linked from `docs/adr/README.md`. - [ ] No code in this ticket — pure design. Implementation lands in the chat UI and MCP tickets that reference this ADR. Part of epic #47. Should land before the chat UI, domain tool surface, and MCP endpoint tickets — those reference its decisions.

james added the

area:service

label

2026-06-14 19:52:46 +00:00

james referenced this issue

2026-06-19 13:26:31 +00:00

Generate résumé tailored to an application (deferred) #134

james referenced this issue from a commit

2026-06-28 19:19:44 +00:00

docs(adr): ADR-0029 agent runtime architecture

james referenced this issue from a pull request that will close it,

2026-06-28 19:20:00 +00:00