feat(api): GET /api/agent/proposals/{id} — read a proposed agent write #343

Merged

james merged 2 commits from 342-proposal-read-endpoint into main 2026-06-29 02:17:54 +00:00

Conversation 1 Commits 2 Files changed 6 +391

james commented 2026-06-29 02:03:14 +00:00

Owner

Copy link

Write tools never mutate — they persist a ProposedChange (summary + structured diff + safe/destructive classification) as an agent_proposals row, and the conversation's awaiting_confirmation pause carries only the proposalId. There was no way to read that proposal back, so a client couldn't render what's about to change before committing/rejecting it. This adds the read side; commit/reject (#51) already exist.

What's in it

• GET /api/agent/proposals/{id} → ProposalDto: proposalId, action (safe_create|safe_update|destructive_update|destructive_delete), tool, entity{type,id}, summary, diff, status, createdAt, expiresAt. The original tool input stays server-side (apply-time replay detail).
• Per-user 404 — a proposal owned by another user, or missing, is a 404 (don't leak existence), matching the commit/reject discipline.
• Expiry is read-only — a still-pending proposal past its expiry reads as expired, computed without mutating (the commit path keeps its lazy expired persist; a GET must not write).
• zod DTO (lib/dto/proposal.ts), RFC 7807 errors, registered in the generated OpenAPI spec (committed openapi.json).

Verification (run locally on this branch)

• typecheck ✓ · lint ✓
• test against both engines (ephemeral Postgres via TEST_POSTGRES_URL): 1211 passed (+5 GET tests: 401, owner-read, cross-user 404, missing 404, pending-past-expiry → expired + asserts the row stays pending)
• openapi:check ✓ up to date · openapi:coverage 116 → 117 pairs
• semgrep (CI pack set) ✓ 0 findings on the new files

Out of scope

• The @carol/api-client hook for this endpoint (lands with the conversation hooks).
• The chat UI.

Part of epic #47; unblocks the chat-UI confirmation flow.

Closes #342

🤖 Generated with Claude Code

Write tools never mutate — they persist a `ProposedChange` (summary + structured diff + safe/destructive classification) as an `agent_proposals` row, and the conversation's `awaiting_confirmation` pause carries only the `proposalId`. There was no way to read that proposal back, so a client couldn't render *what's about to change* before committing/rejecting it. This adds the read side; commit/reject (#51) already exist. ## What's in it - **`GET /api/agent/proposals/{id}`** → `ProposalDto`: `proposalId`, `action` (`safe_create|safe_update|destructive_update|destructive_delete`), `tool`, `entity{type,id}`, `summary`, `diff`, `status`, `createdAt`, `expiresAt`. The original tool `input` stays server-side (apply-time replay detail). - **Per-user 404** — a proposal owned by another user, or missing, is a 404 (don't leak existence), matching the commit/reject discipline. - **Expiry is read-only** — a still-`pending` proposal past its expiry reads as `expired`, computed without mutating (the commit path keeps its lazy `expired` persist; a GET must not write). - zod DTO (`lib/dto/proposal.ts`), RFC 7807 errors, registered in the generated OpenAPI spec (committed `openapi.json`). ## Verification (run locally on this branch) - `typecheck` ✓ · `lint` ✓ - `test` against **both engines** (ephemeral Postgres via `TEST_POSTGRES_URL`): **1211 passed** (+5 GET tests: 401, owner-read, cross-user 404, missing 404, pending-past-expiry → `expired` + asserts the row stays `pending`) - `openapi:check` ✓ up to date · `openapi:coverage` 116 → **117** pairs - semgrep (CI pack set) ✓ 0 findings on the new files ## Out of scope - The `@carol/api-client` hook for this endpoint (lands with the conversation hooks). - The chat UI. Part of epic #47; unblocks the chat-UI confirmation flow. Closes #342 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-29 02:03:15 +00:00

feat(api): GET /api/agent/proposals/{id} — read a proposed agent write ... 1c9c2e4aa7

Write tools never mutate; they persist a ProposedChange (summary +
structured diff + safe/destructive classification) as an agent_proposals
row, and the conversation's awaiting_confirmation pause carries only the
proposalId. There was no way to read that proposal back, so a client
couldn't render what's about to change before committing/rejecting it.

Add a read endpoint returning a ProposalDto (proposalId, action, tool,
entity, summary, diff, status, createdAt, expiresAt). Per-user scoped: a
proposal owned by another user — or missing — is a 404 (don't leak
existence), matching the commit/reject discipline. A still-pending
proposal past its expiry reads as `expired`, computed read-only (the GET
never mutates; the commit path keeps its lazy expired persist). The
original tool input stays server-side.

Unblocks the chat-UI confirmation card and any MCP confirmation prompt.

Closes #342

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

forgejo-actions commented 2026-06-29 02:08:41 +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	79.3% ✅	≥ 50%
Branches	71.0% ⚠️	≥ 75%
Functions	80.3%	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 | 79.3% ✅ | ≥ 50% | | Branches | 71.0% ⚠️ | ≥ 75% | | Functions | 80.3% | informational | Soft thresholds per [ADR-0019](docs/adr/0019-coverage-soft-targets.md). Coverage is informational and does not block merge.

james added 1 commit 2026-06-29 02:10:37 +00:00

chore(api-client): regenerate types for the proposal-read endpoint ... 2a9595486d

The committed @carol/api-client generated client tracks openapi.json;
adding GET /api/agent/proposals/{id} drifted it. Regenerate so the
`check` gate passes and the new path + ProposalDto are typed for the
upcoming conversation hooks.

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

james merged commit af007e4152 into main 2026-06-29 02:17:54 +00:00

james deleted branch 342-proposal-read-endpoint 2026-06-29 02:17:55 +00:00

james referenced this pull request from a commit 2026-06-29 02:17:56 +00:00

Merge pull request 'feat(api): GET /api/agent/proposals/{id} — read a proposed agent write' (#343) from 342-proposal-read-endpoint into main

james referenced this pull request 2026-06-29 02:20:26 +00:00

feat(api-client): conversation + agent hooks + pure SSE streaming transport #344

james referenced this pull request from a commit 2026-06-29 02:27:18 +00:00

feat(api-client): conversation + agent hooks + pure SSE streaming transport

james referenced this pull request 2026-06-29 02:27:37 +00:00

feat(api-client): conversation + agent hooks + pure SSE streaming transport #345

james referenced this pull request 2026-06-29 09:46:32 +00:00

feat(client): built-in chat UI — streaming chat panel + inline write confirmations #346

james referenced this pull request 2026-06-29 09:58:32 +00:00

feat(client): built-in chat UI — streaming chat panel + inline write confirmations #347

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!343

No description provided.