feat(api): GET /api/agent/audit — the user's agent write history #349

Merged

james merged 1 commit from 348-audit-log-api into main 2026-06-29 11:45:51 +00:00

Conversation 1 Commits 1 Files changed 8 +547

james commented 2026-06-29 11:32:00 +00:00

Owner

Copy link

First half of epic #47's "audit log + undo" linked ticket: the read surface over the already-captured trail. The commit path writes one append-only audit_events row per applied proposal with before/after snapshots (#51, migration 023), but there was no way to list them — so the PWA can't show "what Carol changed." Undo is deliberately a separate follow-up (reversal semantics need their own design: conflict detection, re-creating ids, child rows, whether undo is itself audited).

What's in it

• GET /api/agent/audit — cursor-paginated (newest first) list of the authenticated user's audit events → AuditEventDto (id, entityType, entityId, action, tool, before, after decoded from JSON to structured values — null on create/delete, proposalId, createdAt).
• Per-user scoped — a user only ever sees their own trail.
• AuditEventsRepository.listPageByUser — keyset pagination on (created_at, id), mirroring the conversations list; the existing listByUser (returns all) stays for internal callers/tests.
• zod DTO, registered in the OpenAPI spec; api-client types regenerated (both drift gates green).

Verification (run locally on this branch)

• typecheck ✓ · lint ✓
• test against both engines (ephemeral Postgres): 1217 passed, 0 skipped (+6: a dual-engine listPageByUser pagination test + 4 route tests — 401, decoded before/after newest-first, cross-user isolation, next_cursor paging)
• @carol/api-client test ✓ 40 passed · openapi:check ✓ · openapi:coverage 117 → 118 · api-client check ✓ up to date
• semgrep (CI pack set) ✓ 0 findings on the new files

Out of scope (follow-ups)

• Undo — POST /api/agent/audit/{id}/undo. Own ticket + design.
• The @carol/api-client hook + history UI.

Part of epic #47.

Closes #348

🤖 Generated with Claude Code

First half of epic #47's "audit log + undo" linked ticket: the **read** surface over the already-captured trail. The commit path writes one append-only `audit_events` row per applied proposal with before/after snapshots (#51, migration 023), but there was no way to list them — so the PWA can't show "what Carol changed." Undo is deliberately a **separate follow-up** (reversal semantics need their own design: conflict detection, re-creating ids, child rows, whether undo is itself audited). ## What's in it - **`GET /api/agent/audit`** — cursor-paginated (newest first) list of the authenticated user's audit events → `AuditEventDto` (`id`, `entityType`, `entityId`, `action`, `tool`, `before`, `after` decoded from JSON to structured values — null on create/delete, `proposalId`, `createdAt`). - **Per-user scoped** — a user only ever sees their own trail. - **`AuditEventsRepository.listPageByUser`** — keyset pagination on `(created_at, id)`, mirroring the conversations list; the existing `listByUser` (returns all) stays for internal callers/tests. - zod DTO, registered in the OpenAPI spec; api-client types regenerated (both drift gates green). ## Verification (run locally on this branch) - `typecheck` ✓ · `lint` ✓ - `test` against **both engines** (ephemeral Postgres): **1217 passed, 0 skipped** (+6: a dual-engine `listPageByUser` pagination test + 4 route tests — 401, decoded before/after newest-first, cross-user isolation, `next_cursor` paging) - `@carol/api-client test` ✓ 40 passed · `openapi:check` ✓ · `openapi:coverage` 117 → **118** · api-client `check` ✓ up to date - semgrep (CI pack set) ✓ 0 findings on the new files ## Out of scope (follow-ups) - **Undo** — `POST /api/agent/audit/{id}/undo`. Own ticket + design. - The `@carol/api-client` hook + history UI. Part of epic #47. Closes #348 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james added 1 commit 2026-06-29 11:32:00 +00:00

feat(api): GET /api/agent/audit — the user's agent write history ... 6b1798eede

The commit path already records an append-only audit_events row per
applied proposal with before/after snapshots (#51, migration 023), but
there was no way to read them back. Add the list endpoint so the PWA can
show "what Carol changed" (and, later, offer undo).

- AuditEventsRepository.listPageByUser: cursor-paginated newest-first
  page on the (created_at, id) keyset, mirroring the conversations list.
  The existing listByUser (returns all) stays for internal callers/tests.
- lib/dto/audit.ts: AuditEventDto — decodes the before/after JSON
  snapshots to structured values (null on create/delete).
- GET /api/agent/audit: per-user scoped (a user only sees their own
  trail), cursor-paginated, registered in the OpenAPI spec; api-client
  types regenerated.

Undo is a separate follow-up (reversal semantics need their own design).

Closes #348

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

forgejo-actions commented 2026-06-29 11:42:25 +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.1% ⚠️	≥ 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.1% ⚠️ | ≥ 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 merged commit 7b95d97563 into main 2026-06-29 11:45:51 +00:00

james deleted branch 348-audit-log-api 2026-06-29 11:45:52 +00:00

james referenced this pull request from a commit 2026-06-29 11:45:53 +00:00

Merge pull request 'feat(api): GET /api/agent/audit — the user's agent write history' (#349) from 348-audit-log-api into main

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

No description provided.