charles/claude-hooks
1
0
Fork 0
Code Issues 10 Pull requests Projects Releases Packages 1 Wiki Activity Actions

Sessions store + resume — disk-backed map and delta-prompt flow #6

New issue
Closed
opened 2026-04-16 22:44:42 +00:00 by claude-desktop · 0 comments
claude-desktop commented 2026-04-16 22:44:42 +00:00
Collaborator
Copy link

User story

As an agent re-dispatched on the same issue or PR, I want to resume my previous Claude Agent SDK session so that I retain the context I built up before, and the dispatcher only needs to send a delta prompt instead of replaying the whole skill template.

Note (2026-04-17): PR #16 landed sessionKey() and a dropSession() stub in src/main.ts. This story replaces the stub with the real disk-backed implementation and moves both symbols into src/sessions.ts; the /reset endpoint should continue to work unchanged.

Acceptance criteria

Sessions store (src/sessions.ts)

  • sessionKey(agent, repo, issue_or_pr_number): string — returns e.g. "boss:charles/peon:4" (moved from main.ts)
  • getSession(key): Promise<string | null> — returns the persisted session id, if any
  • setSession(key, id): Promise<void> — writes through to disk
  • dropSession(key): Promise<boolean> — replaces the main.ts stub; returns true when an entry was removed
  • dropAllForIssue(repo, issue_or_pr_number): Promise<void> — drops every agent's session for that issue
  • Backing store: ~/.local/state/claude-hooks/sessions.json, atomic writes via tmp + rename
  • Concurrent writes from multiple workers are safe (mutex or last-writer-wins-with-merge — choose and document)

runAgent integration (src/main.ts)

  • Compute sessionKey at task start (swap the import from ./main to ./sessions)
  • If getSession(key) returns an id, pass resume: id to query(); otherwise fresh session
  • Capture the session id from the first SDK message that carries it (path identified in the spike); call setSession(key, id)
  • If query() throws because the resumed session expired or is unknown, automatically retry once with a fresh session and log a warning
  • Cleanup webhooks (cleanup.ts) call dropAllForIssue
  • /reset endpoint in main.ts swaps its stub call for dropSession from ./sessions

Skill prompt: delta vs. full

  • When getSession returns null → use the full skill template as today
  • When resuming → send a short delta prompt (e.g. "The reviewer requested changes: <body>. Address them."); do not re-send the full template
  • Delta prompt content lives in the existing skills/ directory as a separate file per event type (or as an explicit branch in the skill template); pick one and document

Tests (src/sessions.test.ts)

  • Round-trip: set, get, drop
  • Atomic write: kill-mid-write simulation (or just verify temp+rename pattern) does not leave a partial file
  • Concurrent set from two workers: both writes land, no data loss
  • /reset tests in main.test.ts are updated to assert against the real dropSession (drop the "always false" stub expectation)

Out of scope

  • Sweeper for missed cleanup webhooks (#7)
  • Dashboard surfacing of session counts (later story)
  • Skill prompt content quality tuning (separate follow-up — this story only enforces the delta-vs-full split)

References

  • Discussion: chat history, "Phase 2 — session resumption"
  • Spike output (issue #2) — confirms which SDK message carries session_id
  • main.ts stubs added in PR #16 (commit c882b6a)

Dependencies

  • Blocked by: none open (#5 merged in PR #14)
  • Blocks: #7
  • Branch off: main
  • Full graph: #10
## User story As an **agent re-dispatched on the same issue or PR**, I want to resume my previous Claude Agent SDK session so that I retain the context I built up before, and the dispatcher only needs to send a delta prompt instead of replaying the whole skill template. > **Note (2026-04-17):** PR #16 landed `sessionKey()` and a `dropSession()` stub in `src/main.ts`. This story replaces the stub with the real disk-backed implementation and moves both symbols into `src/sessions.ts`; the `/reset` endpoint should continue to work unchanged. ## Acceptance criteria ### Sessions store (`src/sessions.ts`) - [ ] `sessionKey(agent, repo, issue_or_pr_number): string` — returns e.g. `"boss:charles/peon:4"` (moved from `main.ts`) - [ ] `getSession(key): Promise<string | null>` — returns the persisted session id, if any - [ ] `setSession(key, id): Promise<void>` — writes through to disk - [ ] `dropSession(key): Promise<boolean>` — replaces the main.ts stub; returns `true` when an entry was removed - [ ] `dropAllForIssue(repo, issue_or_pr_number): Promise<void>` — drops every agent's session for that issue - [ ] Backing store: `~/.local/state/claude-hooks/sessions.json`, atomic writes via `tmp + rename` - [ ] Concurrent writes from multiple workers are safe (mutex or last-writer-wins-with-merge — choose and document) ### `runAgent` integration (`src/main.ts`) - [ ] Compute `sessionKey` at task start (swap the import from `./main` to `./sessions`) - [ ] If `getSession(key)` returns an id, pass `resume: id` to `query()`; otherwise fresh session - [ ] Capture the session id from the first SDK message that carries it (path identified in the spike); call `setSession(key, id)` - [ ] If `query()` throws because the resumed session expired or is unknown, automatically retry once with a fresh session and log a warning - [ ] Cleanup webhooks (`cleanup.ts`) call `dropAllForIssue` - [ ] `/reset` endpoint in `main.ts` swaps its stub call for `dropSession` from `./sessions` ### Skill prompt: delta vs. full - [ ] When `getSession` returns null → use the full skill template as today - [ ] When resuming → send a short delta prompt (e.g. `"The reviewer requested changes: <body>. Address them."`); do not re-send the full template - [ ] Delta prompt content lives in the existing `skills/` directory as a separate file per event type (or as an explicit branch in the skill template); pick one and document ### Tests (`src/sessions.test.ts`) - [ ] Round-trip: `set`, `get`, `drop` - [ ] Atomic write: kill-mid-write simulation (or just verify temp+rename pattern) does not leave a partial file - [ ] Concurrent set from two workers: both writes land, no data loss - [ ] `/reset` tests in `main.test.ts` are updated to assert against the real `dropSession` (drop the "always false" stub expectation) ## Out of scope - Sweeper for missed cleanup webhooks (#7) - Dashboard surfacing of session counts (later story) - Skill prompt content quality tuning (separate follow-up — this story only enforces the delta-vs-full split) ## References - Discussion: chat history, "Phase 2 — session resumption" - Spike output (issue #2) — confirms which SDK message carries `session_id` - `main.ts` stubs added in PR #16 (commit `c882b6a`) ## Dependencies - **Blocked by:** none open (#5 merged in PR #14) - **Blocks:** #7 - **Branch off:** `main` - **Full graph:** #10
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
chore/sync-pre-push-from-forge-base
fix/flows-yaml-dispatch-identity
feat/board-tap-to-assign
dev/1107
code-lead/1106
code-lead/1108
dev/1104
code-lead/1103
code-lead/1080
dev/1087
feat/flows-yaml-ci-events
chore/board-drop-stalled-and-density-controls
fix/flows-yaml-routes-always-register
flows-yaml/api-defaults
dev/1023
fix/event-log-history-bleed
fix/janitor-fix-ci-logs-and-cap
dev/1022
fix/board-card-provider
code-lead/1036
dev/1025
code-lead/1020
dev/1017
code-lead/1026
feat/web-shortcut-registry-1018
dev/1015
code-lead/1009
code-lead/1008
dev/975
dev/969
dev/973
dev/967
code-lead/968
code-lead/953
dev/970
dev/976
code-lead/966
code-lead/956
code-lead/951
dev/962
dev/963
dev/977
dev/955
dev/983
dev/961
dev/974
code-lead/950
code-lead/939
dev/941
dev/940
dev/937
dev/938
dev/936
dev/935
feat/web-i18n-fr-locale
feat/spec-editor-ui-polish
chore/drop-legacy-compat
fix/skills-drop-preview-pane
fix/882-skills-safety-rail
dev/911
dev/909
dev/923
dev/917
dev/915
feat/879-sr11-m2-drop-legacy-skill
code-lead/873
dev/881
code-lead/869
dev/867
code-lead/845
code-lead/843
code-lead/844
dev/837
dev/861
dev/849
code-lead/837
code-lead/842
fix/dedup-rebase-inflight
dev/838
code-lead/847
dev/833
code-lead/848
pr/838
code-lead/841
feat/settings-save-bar/836
code-lead/840
dev/846
code-lead/839
dev/832
fix/board-sse-stale-cache
dev/834
dev/835
feat/settings-breadcrumbs
feat/forge-oauth-credentials
refactor/service-config-consolidation
feat/agent-tokens-to-secrets
feat/gitlab-oauth-to-db
feat/authelia-rip-and-voice-fixes
fix/rebase-storm-and-dead-letter
code-lead/797
code-lead/796
dev/811
code-lead/798
dev/810
code-lead/795
dev/808
code-lead/794
dev/805
dev/802
dev/803
feat/avatar-menu-settings-entry
feat/per-agent-token-tracking
dev/793
dev/747
dev/752
code-lead/790
code-lead/759
dev/756
dev/760
dev/741
dev/767
dev/740
dev/709
dev/644
dev/637
boss/614
dev/600
dev/611
dev/585
fix/login-bonus-fixes
boss/544
dev/542
refactor/api-prefix-and-session-gate
dev/489
boss/531
boss/518
dev/499
boss/516
dev/530
dev/517
dev/519
dev/515
dev/522
dev/503
dev/471
boss/329
dev/417
dev/418
dev/402
boss/327
dev/334
dev/332
boss/326
boss/325
dev/331
boss/324
boss/323
boss/322
dev/294
test/s11-task-analytics
dev/262
boss/270
dev/268
foreman/ui-consolidation-spec
dev/234
boss/196
boss/176
boss/164
fix/124-session-persist-bind
boss/52
dev/87
boss/73
dev/77
dev/81
dev/82
boss/79
dev/42
dev/35
boss/7
No results found.
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
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
code-lead
1 participant
Notifications
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#6
No description provided.