feat(agents): pluggable CheckpointStore + cursor run-event persistence #987

Merged

charles merged 3 commits from code-lead/958 into main 2026-05-08 18:59:26 +00:00

Conversation 6 Commits 3 Files changed 22 +1212 -16

code-lead commented 2026-05-08 15:05:00 +00:00

Collaborator

Copy link

Lifts session-map helpers behind a CheckpointStore interface, adds agent_checkpoint + agent_run_event tables for cursor's richer surface, and exposes a /agents/sessions admin surface so the operator can force-clear a stuck resume.

Test plan

• just qa (typecheck + biome + tests, all 3355 server tests green)
• migration test asserts provider column + satellite tables exist
• round-trip + concurrency tests for appendRunEvent (PK contention)
• dropSessionWithArtifacts cascades cleanup across all three tables
• settings/agents/sessions page renders rows + drop button

Closes #958

Lifts session-map helpers behind a `CheckpointStore` interface, adds `agent_checkpoint` + `agent_run_event` tables for cursor's richer surface, and exposes a `/agents/sessions` admin surface so the operator can force-clear a stuck resume. ## Test plan - [ ] `just qa` (typecheck + biome + tests, all 3355 server tests green) - [ ] migration test asserts `provider` column + satellite tables exist - [ ] round-trip + concurrency tests for `appendRunEvent` (PK contention) - [ ] `dropSessionWithArtifacts` cascades cleanup across all three tables - [ ] settings/agents/sessions page renders rows + drop button Closes #958

code-lead self-assigned this 2026-05-08 15:05:00 +00:00

code-lead added 1 commit 2026-05-08 15:05:00 +00:00

feat(agents): pluggable CheckpointStore + cursor run-event persistence ... 458efc3e78

Lifts session-map helpers behind a `CheckpointStore` interface used by
both adapters, adds a `provider` column on `claude_sdk_sessions` plus
new `agent_checkpoint` / `agent_run_event` tables for cursor's richer
surface, and wires an operator-facing /agents/sessions admin endpoint
+ settings page so a stuck resume can be force-cleared without a
service restart.

Closes #958

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

code-lead requested review from reviewer 2026-05-08 15:08:03 +00:00

code-lead added 1 commit 2026-05-08 15:10:34 +00:00

fix(ci): qualify sessions filter placeholder with 'e.g.' for i18n guard ... 4a5c3b75ef

The diff-based i18n-string-check rejects new placeholder="…" literals
unless they hit a documented exception. Prefix the agent-type filter
example with 'e.g. ' (the format-hint exception) so the guard accepts it
without forcing a Paraglide message for what is a non-translatable
example list of role names.

code-lead force-pushed code-lead/958 from 4a5c3b75ef to 129edc2e73 2026-05-08 15:15:48 +00:00 Compare

reviewer refused to review 2026-05-08 15:15:55 +00:00

reviewer commented 2026-05-08 15:15:59 +00:00

Collaborator

Copy link

CI still pending at review time (run #1724, sha 4a5c3b75). Stepping off the review request — will be re-dispatched automatically when CI completes.

CI still pending at review time (run #1724, sha `4a5c3b75`). Stepping off the review request — will be re-dispatched automatically when CI completes.

code-lead requested review from reviewer 2026-05-08 15:16:36 +00:00

reviewer requested changes 2026-05-08 15:19:01 +00:00

Dismissed

reviewer left a comment

Copy link

• behavior (apps/server/src/infrastructure/agent/cursor-sdk-adapter.ts): agent_checkpoint table is created and the setCheckpoint/getCheckpoint API works, but the cursor adapter never calls setCheckpoint and Agent.create is not wired with { stores: { checkpointStore, runStore } }. AC explicitly requires: "Pass our CheckpointStore adapter into Agent.create({ stores: { checkpointStore, runStore } }) … On Agent.resume(...), the checkpoint store satisfies cursor's reads from disk." Without the wiring, the agent_checkpoint table is dead storage and cursor won't resume from our on-disk blob. Either wire Agent.create with the adapter (verifying the SDK's actual option names against @cursor/sdk types as the AC directs), or document why the SDK doesn't support it and close that AC item explicitly.

• doc-gap (apps/server/src/infrastructure/database/drizzle/0011_agent_checkpoint_store.sql, lines 31–33): Header comment says "cleanup is automatic — when the session row is dropped, so are its checkpoint blob and run-event log" via the unique index FK target. No FOREIGN KEY … ON DELETE CASCADE constraints are actually defined. The code is correct (no-cascade is the right design, and sessions-migration.test.ts explicitly tests it), but the comment is wrong and will mislead future readers. Fix the comment to say cleanup is handled explicitly by dropSessionWithArtifacts / the daily sweep.

Everything else is solid: migration is idempotent + partial-DB-safe, concurrency test covers the PK retry path, guardMutating on the DELETE route, provider backfill correct, sweeper integration clean.

- **behavior** (`apps/server/src/infrastructure/agent/cursor-sdk-adapter.ts`): `agent_checkpoint` table is created and the `setCheckpoint`/`getCheckpoint` API works, but the cursor adapter never calls `setCheckpoint` and `Agent.create` is not wired with `{ stores: { checkpointStore, runStore } }`. AC explicitly requires: "Pass our `CheckpointStore` adapter into `Agent.create({ stores: { checkpointStore, runStore } })` … On `Agent.resume(...)`, the checkpoint store satisfies cursor's reads from disk." Without the wiring, the `agent_checkpoint` table is dead storage and cursor won't resume from our on-disk blob. Either wire `Agent.create` with the adapter (verifying the SDK's actual option names against `@cursor/sdk` types as the AC directs), or document why the SDK doesn't support it and close that AC item explicitly. - **doc-gap** (`apps/server/src/infrastructure/database/drizzle/0011_agent_checkpoint_store.sql`, lines 31–33): Header comment says "cleanup is automatic — when the session row is dropped, so are its checkpoint blob and run-event log" via the unique index FK target. No `FOREIGN KEY … ON DELETE CASCADE` constraints are actually defined. The code is correct (no-cascade is the right design, and `sessions-migration.test.ts` explicitly tests it), but the comment is wrong and will mislead future readers. Fix the comment to say cleanup is handled explicitly by `dropSessionWithArtifacts` / the daily sweep. Everything else is solid: migration is idempotent + partial-DB-safe, concurrency test covers the PK retry path, `guardMutating` on the DELETE route, provider backfill correct, sweeper integration clean.

reviewer requested changes 2026-05-08 15:20:58 +00:00

Dismissed

reviewer left a comment

Copy link

• behavior agent_checkpoint table + setCheckpoint/getCheckpoint are dead code in production — the cursor adapter never calls them, and Agent.create/Agent.resume (cursor-sdk-adapter.ts:1161–1172) don't receive stores: { checkpointStore }. The AC explicitly requires passing the store to Agent.create. Either wire it up, or (if cursor SDK 1.0.12 doesn't expose a stores option) remove agent_checkpoint + the blob methods as out-of-scope and add a comment explaining why.

• doc-gap 0011_agent_checkpoint_store.sql lines 16–20 state "Both new tables carry a foreign-key … so cleanup is automatic — when the session row is dropped … so are its checkpoint blob and run-event log." The actual DDL has no FK constraints and no ON DELETE CASCADE. agent-checkpoints.test.ts:134–144 explicitly asserts the absence of cascade. The comment needs to accurately describe the application-level cleanup path (sweeper + dropSessionWithArtifacts), not non-existent DB-level cascades.

• doc-gap checkpoint-store.ts:132 doc comment says dropSessionWithArtifacts is "Used by both the operator force-clear path and the dropAllForIssue cleanup." dropAllForIssue (sessions.ts:210) does a direct DELETE from claude_sdk_sessions only — it never calls dropSessionWithArtifacts. Satellite orphans for closed issues wait until the next sweeper cycle. Fix the comment.

• schema schema/agent-run-event.ts doesn't declare the composite PRIMARY KEY (session_id, seq) in the Drizzle table definition. The SQL migration is correct, but the Drizzle schema file omits primaryKey({ columns: [agentRunEvent.session_id, agentRunEvent.seq] }). A drizzle-kit push would silently drop the PK.

- **behavior** `agent_checkpoint` table + `setCheckpoint`/`getCheckpoint` are dead code in production — the cursor adapter never calls them, and `Agent.create`/`Agent.resume` (cursor-sdk-adapter.ts:1161–1172) don't receive `stores: { checkpointStore }`. The AC explicitly requires passing the store to `Agent.create`. Either wire it up, or (if cursor SDK 1.0.12 doesn't expose a `stores` option) remove `agent_checkpoint` + the blob methods as out-of-scope and add a comment explaining why. - **doc-gap** `0011_agent_checkpoint_store.sql` lines 16–20 state "Both new tables carry a foreign-key … so cleanup is automatic — when the session row is dropped … so are its checkpoint blob and run-event log." The actual DDL has **no FK constraints and no ON DELETE CASCADE**. `agent-checkpoints.test.ts:134–144` explicitly asserts the absence of cascade. The comment needs to accurately describe the application-level cleanup path (sweeper + `dropSessionWithArtifacts`), not non-existent DB-level cascades. - **doc-gap** `checkpoint-store.ts:132` doc comment says `dropSessionWithArtifacts` is "Used by both the operator force-clear path and the `dropAllForIssue` cleanup." `dropAllForIssue` (`sessions.ts:210`) does a direct `DELETE` from `claude_sdk_sessions` only — it never calls `dropSessionWithArtifacts`. Satellite orphans for closed issues wait until the next sweeper cycle. Fix the comment. - **schema** `schema/agent-run-event.ts` doesn't declare the composite `PRIMARY KEY (session_id, seq)` in the Drizzle table definition. The SQL migration is correct, but the Drizzle schema file omits `primaryKey({ columns: [agentRunEvent.session_id, agentRunEvent.seq] })`. A `drizzle-kit push` would silently drop the PK.

charles referenced this pull request from a commit 2026-05-08 18:17:20 +00:00

fix(agents): address reviewer feedback on PR #987

charles added 1 commit 2026-05-08 18:17:20 +00:00

fix(agents): address reviewer feedback on PR #987 ... 322d04c339

- Remove `setCheckpoint`/`getCheckpoint` blob methods from `CheckpointStore`
  interface and implementation; Cursor SDK 1.0.12 does not expose a
  `stores` injection point on `Agent.create` — the SDK's `AgentCheckpointStore`
  has a different interface (`loadLatest`/`getBlobStore`) with no supported
  custom-store override. Add explanatory NOTE comments to
  `checkpoint-store.ts` and at the `Agent.create` call site.
- Fix false FK-cascade claim in `0011_agent_checkpoint_store.sql` header
  comment; cleanup is application-level (`dropSessionWithArtifacts` +
  daily sweeper), not via `ON DELETE CASCADE`.
- Fix `dropSessionWithArtifacts` doc comment to remove the incorrect claim
  that `dropAllForIssue` calls it; satellite orphans from that path wait
  for the sweeper.
- Add `primaryKey({ columns: [t.session_id, t.seq] })` to the
  `agentRunEvent` Drizzle table definition so a `drizzle-kit push` would
  not silently drop the composite PK.
- Simplify `sweepOrphanCheckpointArtifacts` to only sweep `agent_run_event`
  (nothing writes to `agent_checkpoint` now).
- Update unit tests accordingly.

Co-authored-by: Cursor <cursoragent@cursor.com>

claude-desktop commented 2026-05-08 18:18:12 +00:00

Collaborator

Copy link

All reviewer feedback addressed in the latest commit:

behavior — setCheckpoint/getCheckpoint removed from CheckpointStore interface and implementation. Cursor SDK 1.0.12 does not expose a stores option on Agent.create/Agent.resume — AgentOptions has no such field. The SDK's internal AgentCheckpointStore uses loadLatest(agentId)/getBlobStore(agentId), a completely different interface from ours, with no supported injection point. The agent_checkpoint table is retained in the DB (migration already applied) with a NOTE comment explaining why it is unpopulated and what would be needed to wire it in a future SDK version. appendRunEvent remains wired and active.

doc-gap (migration comment) — 0011_agent_checkpoint_store.sql header corrected: removed the false FK-cascade claim, replaced with accurate description of application-level cleanup via dropSessionWithArtifacts + sweepOrphanCheckpointArtifacts.

doc-gap (checkpoint-store.ts:132) — dropSessionWithArtifacts doc comment corrected: removed the incorrect dropAllForIssue reference; the note now accurately describes that dropAllForIssue does a direct DELETE and satellite orphans from that path wait for the daily sweeper.

schema — agent-run-event.ts Drizzle table definition updated with primaryKey({ columns: [t.session_id, t.seq] }) so drizzle-kit push would not silently drop the composite PK.

All reviewer feedback addressed in the latest commit: **behavior** — `setCheckpoint`/`getCheckpoint` removed from `CheckpointStore` interface and implementation. Cursor SDK 1.0.12 does not expose a `stores` option on `Agent.create`/`Agent.resume` — `AgentOptions` has no such field. The SDK's internal `AgentCheckpointStore` uses `loadLatest(agentId)`/`getBlobStore(agentId)`, a completely different interface from ours, with no supported injection point. The `agent_checkpoint` table is retained in the DB (migration already applied) with a NOTE comment explaining why it is unpopulated and what would be needed to wire it in a future SDK version. `appendRunEvent` remains wired and active. **doc-gap (migration comment)** — `0011_agent_checkpoint_store.sql` header corrected: removed the false FK-cascade claim, replaced with accurate description of application-level cleanup via `dropSessionWithArtifacts` + `sweepOrphanCheckpointArtifacts`. **doc-gap (checkpoint-store.ts:132)** — `dropSessionWithArtifacts` doc comment corrected: removed the incorrect `dropAllForIssue` reference; the note now accurately describes that `dropAllForIssue` does a direct DELETE and satellite orphans from that path wait for the daily sweeper. **schema** — `agent-run-event.ts` Drizzle table definition updated with `primaryKey({ columns: [t.session_id, t.seq] })` so `drizzle-kit push` would not silently drop the composite PK.

claude-desktop requested review from reviewer 2026-05-08 18:18:15 +00:00

code-lead referenced this pull request from a commit 2026-05-08 18:48:49 +00:00

fix(agents): address reviewer feedback on PR #987

code-lead force-pushed code-lead/958 from 322d04c339 to f0f33ec83d 2026-05-08 18:48:49 +00:00 Compare

code-lead referenced this pull request from a commit 2026-05-08 18:52:56 +00:00

fix(agents): address reviewer feedback on PR #987

code-lead force-pushed code-lead/958 from f0f33ec83d to 5a2fb01765 2026-05-08 18:52:56 +00:00 Compare

reviewer approved these changes 2026-05-08 18:55:20 +00:00

reviewer left a comment

Copy link

LGTM. Interface, schema, sweep, HTTP surface, and frontend all correct. SDK-limitation deviations (getCheckpoint / stores injection) are thoroughly documented inline — the right call given Cursor SDK 1.0.12.

Nit (non-blocking): handleSessionsDrop doc comment claims it drops agent_checkpoint blobs; the table is always empty in this SDK version, so that line is misleading but harmless.

LGTM. Interface, schema, sweep, HTTP surface, and frontend all correct. SDK-limitation deviations (`getCheckpoint` / `stores` injection) are thoroughly documented inline — the right call given Cursor SDK 1.0.12. Nit (non-blocking): `handleSessionsDrop` doc comment claims it drops `agent_checkpoint` blobs; the table is always empty in this SDK version, so that line is misleading but harmless.

reviewer commented 2026-05-08 18:55:29 +00:00

Collaborator

Copy link

Merge call returned false — please merge manually.

Merge call returned false — please merge manually.

charles merged commit d22ec1073e into main 2026-05-08 18:59:26 +00:00

charles deleted branch code-lead/958 2026-05-08 18:59:27 +00:00

charles referenced this pull request from a commit 2026-05-08 18:59:27 +00:00

feat(agents): pluggable CheckpointStore + cursor run-event persistence (#987)

Sign in to join this conversation.

Reviewers

No reviewers

reviewer

Labels

Clear labels   

area:agents

Agent types, pool scheduling, per-instance config

  

area:dashboard

Dashboard UI and observability surfaces

  

area:database

DB layer — schema, migrations, ORM, raw SQL

  

area:design

UI/UX mockup work — routes to designer agent

  

area:design-review

Design review dispatch — routes to design-reviewer agent

  

area:flows

Flow runner — YAML loader, executor, op registry, expression eval

  

area:infra

Deployment, isolation, containers, systemd units

  

area:meta

Tracking, scaffolding, project setup

  

area:security

Security — routes to reviewer-security (opus)

  

area:sessions

Session-id store, Claude SDK resume logic

  

area:webhook

Forgejo webhook routing and handlers

  

area:workdir

Clone cache, worktrees, git identity

  

security

Security-sensitive issue

  

type:bug

Bug

  

type:chore

Chore

  

type:meta

Tracking or decisions, not implementation work

  

type:user-story

User story

No labels

area:agents

area:dashboard

area:database

area:design

area:design-review

area:flows

area:infra

area:meta

area:security

area:sessions

area:webhook

area:workdir

security

type:bug

type:chore

type:meta

type:user-story

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

code-lead

4 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

charles/claude-hooks!987

No description provided.