feat(api): server-side agent loop + conversations/messages schema #339

Merged

james merged 1 commit from 338-agent-loop into main 2026-06-29 01:04:49 +00:00

Conversation 1 Commits 1 Files changed 24 +3377 -20

james commented 2026-06-29 00:56:01 +00:00

Owner

Copy link

Implements the server-side agent loop (#338, ADR-0029 §2/§4/§6), non-streaming — the piece that makes the built-in agent actually run, wiring the #51 registry + commit path and the #337 provider adapters over normalized persistence.

What's in it

• Migration 025_conversations_messages (normalized per ADR-0029 §4) + entities + repositories. provider/model snapshotted onto the conversation from the user's #334 config at create time.
• runTurn / resumeTurn (lib/agent/loop.ts) with an injectable LlmClient (defaults to getLlmClientForUser; tests inject a fake — no live calls). Each round builds the request from buildSystemPrompt() + history + llmToolDefsFromRegistry() and calls client.generate. Read tools execute inline → tool result message; write tools propose-then-pause (conversation → awaiting_confirmation, proposal persisted, DB unmutated); MAX_TOOL_ROUNDS = 8 guard.
• Resume: the loop never self-confirms — the user commits/rejects via the existing #51 POST /api/agent/proposals/{id}/{commit,reject}; resumeTurn then feeds the proposal's terminal outcome back as the write tool's result and continues. The provider never sees the internal proposalId.
• Shared dispatch: the read-vs-write tool dispatch is extracted to lib/agent/tool-dispatch.ts and lib/mcp/server.ts is refactored to call it, so the MCP and built-in surfaces dispatch identically (the 14-test MCP suite is unchanged).
• 5 JSON routes (POST /api/conversations, .../{id}/messages, .../{id}/resume, list, get) + zod DTOs + OpenAPI. 409 llm_not_configured if the user hasn't set a provider (#334). Session or PAT → 401; cross-user conversation → 404.

Safety

• Per-user scoped end to end — ctx.userId comes only from the resolved identity, never the body/model; tools carry no user_id; cross-user conversations 404 (don't leak). LlmError/AgentError → clean RFC 7807 problems; the provider key never leaks.

Verification (full pre-ship set)

• typecheck + lint clean; semgrep (full CI pack set) — 0 findings; openapi:check up to date · coverage 116 pairs; @carol/api-client regen + typecheck clean.
• Full suite on BOTH engines: 1183 passed / 0 skipped (ephemeral Postgres — migration 025 + the conversations/messages repos proven on Postgres). New tests: loop (no-tool / read-round / write-pause-DB-unmutated / resume-after-commit / resume-after-reject / resume-precondition-409 / max-rounds / cross-user-404), HTTP (create→send→get / write-pause→commit→resume / cross-user 404 / 401 / no-config 409), and both DB schemas.

Streaming is the next ticket — SSE needs an adapter stream() that #337 deferred; this loop is non-streaming (JSON request/response). The chat UI follows that.

Closes #338

🤖 Generated with Claude Code

Implements the server-side **agent loop** (#338, ADR-0029 §2/§4/§6), **non-streaming** — the piece that makes the built-in agent actually run, wiring the #51 registry + commit path and the #337 provider adapters over normalized persistence. ## What's in it - **Migration `025_conversations_messages`** (normalized per ADR-0029 §4) + entities + repositories. `provider`/`model` snapshotted onto the conversation from the user's #334 config at create time. - **`runTurn` / `resumeTurn`** (`lib/agent/loop.ts`) with an **injectable `LlmClient`** (defaults to `getLlmClientForUser`; tests inject a fake — no live calls). Each round builds the request from `buildSystemPrompt()` + history + `llmToolDefsFromRegistry()` and calls `client.generate`. Read tools execute inline → `tool` result message; **write tools propose-then-pause** (conversation → `awaiting_confirmation`, proposal persisted, **DB unmutated**); `MAX_TOOL_ROUNDS = 8` guard. - **Resume**: the loop never self-confirms — the user commits/rejects via the existing #51 `POST /api/agent/proposals/{id}/{commit,reject}`; `resumeTurn` then feeds the proposal's terminal outcome back as the write tool's result and continues. The provider never sees the internal `proposalId`. - **Shared dispatch**: the read-vs-write tool dispatch is extracted to `lib/agent/tool-dispatch.ts` and `lib/mcp/server.ts` is **refactored to call it**, so the MCP and built-in surfaces dispatch identically (the 14-test MCP suite is unchanged). - **5 JSON routes** (`POST /api/conversations`, `.../{id}/messages`, `.../{id}/resume`, list, get) + zod DTOs + OpenAPI. `409 llm_not_configured` if the user hasn't set a provider (#334). Session or PAT → 401; **cross-user conversation → 404**. ## Safety - Per-user scoped end to end — `ctx.userId` comes only from the resolved identity, never the body/model; tools carry no `user_id`; cross-user conversations 404 (don't leak). `LlmError`/`AgentError` → clean RFC 7807 problems; the provider key never leaks. ## Verification (full pre-ship set) - typecheck + lint clean; **semgrep (full CI pack set) — 0 findings**; `openapi:check` up to date · coverage 116 pairs; `@carol/api-client` regen + typecheck clean. - **Full suite on BOTH engines: 1183 passed / 0 skipped** (ephemeral Postgres — migration 025 + the conversations/messages repos proven on Postgres). New tests: loop (no-tool / read-round / write-pause-DB-unmutated / resume-after-commit / resume-after-reject / resume-precondition-409 / max-rounds / cross-user-404), HTTP (create→send→get / write-pause→commit→resume / cross-user 404 / 401 / no-config 409), and both DB schemas. **Streaming is the next ticket** — SSE needs an adapter `stream()` that #337 deferred; this loop is non-streaming (JSON request/response). The chat UI follows that. Closes #338 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-29 00:56:01 +00:00

feat(api): server-side agent loop + conversations/messages schema ... e844c968f9

Implements the server-side agent loop (#338, ADR-0029 §2/§4/§6),
non-streaming. runTurn/resumeTurn over normalized conversations/messages
(migration 025), wiring the #51 tool registry + commit path and the #337
provider adapters with an injectable LlmClient (no live calls in tests).

Read tools execute inline and append a tool result; write tools
propose-then-pause (conversation → awaiting_confirmation, proposal
persisted, DB unmutated) and resume after the user commits/rejects via
the existing #51 /api/agent/proposals/{id}/{commit,reject} endpoints.
MAX_TOOL_ROUNDS guards against runaway loops. The read-vs-write dispatch
is extracted to lib/agent/tool-dispatch.ts and shared with the MCP
endpoint (lib/mcp/server.ts refactored to call it — MCP suite unchanged),
so both surfaces dispatch identically.

Adds 5 JSON routes (POST /api/conversations, .../{id}/messages,
.../{id}/resume, list, get) + zod DTOs + OpenAPI; provider/model are
snapshotted from the user's #334 config (409 llm_not_configured if
unset). Per-user scoped — a conversation owned by another user returns
404. Both-engine tests with a fake LLM client.

Closes #338

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

forgejo-actions commented 2026-06-29 01:02:02 +00:00

Copy link

📊 Test coverage

Patch coverage: no testable lines changed.

Overall (app/, lib/, db/, excluding UI per ADR-0019):

Metric	Value	Soft target
Lines	78.7% ✅	≥ 50%
Branches	70.3% ⚠️	≥ 75%
Functions	79.9%	informational

Soft thresholds per ADR-0019. Coverage is informational and does not block merge.

<!-- coverage-comment --> ## 📊 Test coverage **Patch coverage:** no testable lines changed. **Overall** (`app/`, `lib/`, `db/`, excluding UI per ADR-0019): | Metric | Value | Soft target | |---|---|---| | Lines | 78.7% ✅ | ≥ 50% | | Branches | 70.3% ⚠️ | ≥ 75% | | Functions | 79.9% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.

james merged commit 393cba36c6 into main 2026-06-29 01:04:49 +00:00

james deleted branch 338-agent-loop 2026-06-29 01:04:49 +00:00

james referenced this pull request from a commit 2026-06-29 01:04:49 +00:00

Merge pull request 'feat(api): server-side agent loop + conversations/messages schema' (#339) from 338-agent-loop into main

james referenced this pull request 2026-06-29 01:06:48 +00:00

feat(api): streaming agent turns — LlmClient.stream() + SSE chat endpoint #340

james referenced this pull request 2026-06-29 01:41:30 +00:00

feat(api): streaming agent turns — LlmClient.stream() + SSE chat endpoint #341

james referenced this pull request 2026-06-29 13:57:02 +00:00

MCP server endpoint (streamable HTTP, PAT-authed) #52

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

Authentication and authorization

  

area:ci

Forgejo Actions, build, test, security, release

  

area:db

Database abstraction, migrations, persistence

  

area:infra

Containerization, deployment, foundational tooling

  

area:native

React Native app (Android + Linux Flatpak)

  

area:pwa

PWA / web frontend

  

area:service

Backend service, API routes, persistence

  

epic

High-level tracker; links several feature tickets

  

feature

A user-facing feature

  

foundation

Foundational work that other tickets build on

No labels

area:auth

area:ci

area:db

area:infra

area:native

area:pwa

area:service

epic

feature

foundation

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

james/carol!339

No description provided.