feat(triggers): per-trigger Claude --resume continuation across webhooks#71
Open
lsoldado wants to merge 1 commit intoEvolutionAPI:developfrom
Open
feat(triggers): per-trigger Claude --resume continuation across webhooks#71lsoldado wants to merge 1 commit intoEvolutionAPI:developfrom
lsoldado wants to merge 1 commit intoEvolutionAPI:developfrom
Conversation
…uation
Adds opt-in `claude --resume` continuation across consecutive webhooks
of the same logical thread (ClickUp task, GitHub PR, Linear issue).
Without this, every webhook spawned a fresh Claude subprocess that had
to re-read all prior comments, re-derive context, and re-fetch data via
API calls — losing 90%+ of the model's reasoning trace between turns.
## Why
Real-world incident driving this: 2026-05-02 ClickUp task 86c9kyquv.
User asked the Oracle for a marketing report (Phase 1, ~$3.21, 22min,
43k tokens), then 30 minutes later asked to "implement recommendation 3".
The fresh follow-up Oracle had to:
- Re-read the entire Google Doc via API call
- Re-derive what "rec 3" meant from raw text
- Re-discover the cuid Vitalmadente
- Re-fetch GA4/GBP/Ads data baseline
- LOSE the entire reasoning trace (rejected hypotheses, alternatives
considered) that the prior Oracle had in context
With session resume, the second Oracle inherits the full conversation
history — knows what was tried, what was rejected, and why — at zero
re-derivation cost.
## How — backend
- `Trigger.resume_sessions BOOLEAN` column (default false). Existing
triggers keep current "fresh subprocess" behaviour. Operator opts in
per-trigger via dashboard checkbox or YAML.
- `trigger_session_threads` table maps `(trigger_id, dedup_key)` →
`claude_session_id`. The dedup_key is extracted per-source by
`_extract_dedup_key()` in `routes/triggers.py`:
- ClickUp (source=custom + slug contains 'clickup'): task.id
- GitHub: pull_request.number / issue.number
- Linear: issue.id
Extensible for new sources.
- `run_claude(..., resume_session_id=...)` in `ADWs/runner.py`
prepends `--resume <id>` to the CLI invocation. Captures `session_id`
from output JSON and returns it for upsert. Silently no-ops on
non-Anthropic providers (OpenClaude doesn't expose --resume yet).
- `_execute_trigger` flow:
1. If `trigger.resume_sessions`: extract dedup_key, lookup prior
session_id from `trigger_session_threads`.
2. Pass to `run_claude` (None = fresh).
3. After run: if claude_session_id captured, upsert into
`trigger_session_threads`.
4. If resume failed (stale session): retry once without resume.
## How — UI
- `/settings → Sessions` tab (new):
* Default-on toggle for new triggers
* Auto-cleanup window (1-365 days) + daily cleanup hour (0-23)
* Force compaction turn count (1-500)
* Storage stats (count + disk usage of `~/.claude/projects/`)
* Live list of active threads with manual reset + bulk cleanup-stale
- Trigger edit form: "Enable session resume" checkbox with explanatory
inline tooltip.
## Endpoints
- `GET /api/settings/sessions` — global config + storage stats
- `PUT /api/settings/sessions` — update defaults
- `GET /api/sessions` — list active threads with staleness flag
- `DELETE /api/sessions/<id>` — manual reset
- `POST /api/sessions/cleanup-stale` — bulk delete rows older than
`auto_cleanup_days`
## Schema
Alembic migration `0012_clickup_session_resume.py`:
- ALTER `triggers` ADD `resume_sessions BOOLEAN NOT NULL DEFAULT FALSE`
- CREATE `trigger_session_threads` (id, trigger_id FK, dedup_key,
claude_session_id, last_used_at, created_at) with UNIQUE
(trigger_id, dedup_key) and index on (trigger_id, last_used_at).
- Reversible via downgrade().
## Backward compatibility
- All existing triggers keep `resume_sessions=false` (no behaviour change).
- `run_claude` callers unchanged unless they explicitly pass
`resume_session_id`.
- Schema migration is idempotent (checks `_has_column` / `_has_table`
before alter/create).
## Cost / quality impact (measured on 86c9kyquv)
Without resume (status quo):
- Oracle 1: 22min, 43k tok, $3.21
- Oracle 2 (re-read everything): 11min, 18k tok, $2.19
- Total: $5.40 + degraded continuity
With resume (projected, prompt cache + reused context):
- Oracle 1: 22min, 43k tok, $3.21
- Oracle 2 (resume): 4min, 8k tok, $0.80
- Total: ~$4.00, 25% saved + full reasoning continuity
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Reviewer's GuideImplements per-trigger opt‑in Claude session resume across webhooks by wiring a new resume_sessions flag on triggers through the backend runner, persistence layer, and UI, plus adding admin settings and cleanup endpoints for managing session threads and storage. Sequence diagram for trigger execution with Claude session resumesequenceDiagram
actor WebhookSource
participant Backend as BackendAPI
participant Exec as TriggerExecutor
participant Runner as Runner_run_claude
participant ClaudeCLI
participant DB
WebhookSource->>Backend: HTTP POST webhook
Backend->>Exec: _execute_trigger(trigger_id, execution_id, event_data)
Exec->>DB: load Trigger by id
DB-->>Exec: Trigger(resume_sessions, action_type, source, slug)
alt resume_sessions enabled and prompt_or_skill
Exec->>Exec: dedup_key = _extract_dedup_key(trigger, event_data)
Exec->>DB: lookup TriggerSessionThread(trigger_id, dedup_key)
DB-->>Exec: prior claude_session_id or None
Exec->>Runner: run_claude(prompt, log_name, timeout, agent, resume_session_id)
else resume disabled or no dedup_key
Exec->>Runner: run_claude(prompt, log_name, timeout, agent, resume_session_id=None)
end
Runner->>Runner: _get_provider_config()
Runner->>Runner: _spawn_cli(cli_command, prompt, agent, env, resume_session_id)
Runner->>ClaudeCLI: start process with --print [--resume session]
ClaudeCLI-->>Runner: JSON stdout(result, usage, session_id)
Runner-->>Exec: result{success, stderr, usage, session_id}
alt stale session error with resume
Exec->>Runner: run_claude(prompt, log_name_retry, timeout, agent, resume_session_id=None)
Runner->>ClaudeCLI: restart without --resume
ClaudeCLI-->>Runner: JSON stdout(new_session_id)
Runner-->>Exec: result{session_id}
end
alt trigger.resume_sessions and result.session_id and dedup_key
Exec->>DB: upsert TriggerSessionThread(trigger_id, dedup_key, session_id)
DB-->>Exec: ok
end
Exec-->>Backend: update TriggerExecution status and error
Backend-->>WebhookSource: HTTP 200 response
Sequence diagram for Sessions settings and admin endpointssequenceDiagram
actor Admin
participant UI as Frontend_SessionsTab
participant API as SettingsRoutes
participant DB as Database
participant FS as FileSystem
Admin->>UI: Open Settings Sessions tab
UI->>API: GET /api/settings/sessions
API->>FS: scan ~/.claude/projects for *.jsonl
FS-->>API: session_count, size_bytes
API->>DB: count TriggerSessionThread rows
DB-->>API: active_threads
API-->>UI: sessions config + storage + active_threads
Admin->>UI: Change cleanup_days or defaults
UI->>API: PUT /api/settings/sessions
API->>FS: write config/sessions.yaml
API->>DB: audit update_sessions_settings
API-->>UI: status ok
Admin->>UI: View Active session threads
UI->>API: GET /api/sessions
API->>DB: query TriggerSessionThread join Trigger limit 500
DB-->>API: rows with trigger_name, slug, timestamps
API-->>UI: sessions list with age_seconds and stale
Admin->>UI: Click Reset on a thread
UI->>API: DELETE /api/sessions/thread_id
API->>DB: delete TriggerSessionThread by id and audit
DB-->>API: commit
API-->>UI: status reset
Admin->>UI: Click Cleanup stale now
UI->>API: POST /api/sessions/cleanup-stale
API->>DB: delete rows last_used_at < cutoff
DB-->>API: deleted_count
API-->>UI: status ok, deleted
ER diagram for triggers and trigger_session_threadserDiagram
triggers {
int id PK
varchar name
varchar type
varchar source
varchar action_type
text action_payload
varchar agent
boolean enabled
boolean resume_sessions "default false"
}
trigger_session_threads {
int id PK
int trigger_id FK
text dedup_key
text claude_session_id
datetime last_used_at
datetime created_at
}
triggers ||--o{ trigger_session_threads : has_threads
%% Unique constraint and index (documented as attributes)
trigger_session_threads {
string uq_trigger_id_dedup_key "UNIQUE(trigger_id, dedup_key)"
string ix_trigger_last_used "INDEX(trigger_id, last_used_at)"
}
Class diagram for Trigger and TriggerSessionThread with session resumeclassDiagram
class Trigger {
+int id
+string name
+string type
+string source
+string action_type
+text action_payload
+string agent
+bool enabled
+bool resume_sessions
+bool from_yaml
+string remote_trigger_id
+text source_plugin
+dict to_dict(include_secret)
}
class TriggerSessionThread {
+int id
+int trigger_id
+text dedup_key
+text claude_session_id
+datetime last_used_at
+datetime created_at
+dict to_dict()
}
class TriggerExecution {
+int id
+int trigger_id
+string status
+text error
+datetime created_at
+datetime updated_at
}
Trigger "1" --> "*" TriggerSessionThread : maps_threads
Trigger "1" --> "*" TriggerExecution : executions
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- The stale-session retry logic in
_execute_triggerrelies on a substring check for'session'in stderr, which seems brittle; consider tightening this to look for a specific error code/message from the CLI or exposing a structured error to avoid accidentally retrying for unrelated failures. - The cleanup endpoint in
cleanup_stale_sessionscurrently calls.count()and then.delete()on the same query, which can be expensive on large tables; if you only use the deleted count for auditing, consider usingrows = q.all()andlen(rows)or database-specificRETURNINGto avoid a second full scan. - In
SessionsTab, the numeric inputs forauto_cleanup_days,cleanup_hour_local, andforce_compaction_turnscallsaveon every keystroke, which can spam/settings/sessionsupdates; adding a small debounce or an explicit 'Save' action would reduce unnecessary network calls and backend writes.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The stale-session retry logic in `_execute_trigger` relies on a substring check for `'session'` in stderr, which seems brittle; consider tightening this to look for a specific error code/message from the CLI or exposing a structured error to avoid accidentally retrying for unrelated failures.
- The cleanup endpoint in `cleanup_stale_sessions` currently calls `.count()` and then `.delete()` on the same query, which can be expensive on large tables; if you only use the deleted count for auditing, consider using `rows = q.all()` and `len(rows)` or database-specific `RETURNING` to avoid a second full scan.
- In `SessionsTab`, the numeric inputs for `auto_cleanup_days`, `cleanup_hour_local`, and `force_compaction_turns` call `save` on every keystroke, which can spam `/settings/sessions` updates; adding a small debounce or an explicit 'Save' action would reduce unnecessary network calls and backend writes.
## Individual Comments
### Comment 1
<location path="dashboard/backend/routes/settings.py" line_range="644-648" />
<code_context>
+ cfg = _load_sessions_config()
+ stale_days = cfg.get("auto_cleanup_days", 7)
+
+ rows = (
+ TriggerSessionThread.query
+ .order_by(TriggerSessionThread.last_used_at.desc())
+ .limit(500)
+ .all()
+ )
+ out = []
</code_context>
<issue_to_address>
**suggestion (performance):** `list_sessions` does an N+1 query pattern when resolving trigger names.
`TriggerSessionThread.query...all()` is followed by `Trigger.query.get(r.trigger_id)` inside the loop, causing one additional query per row (N+1). For installations with many active session threads this can be costly. Please either join `Trigger` in the initial query or load all needed triggers in a single `in_` query and map them by `id` to avoid the N+1 pattern.
```suggestion
out = []
# Preload all referenced triggers to avoid N+1 queries
trigger_ids = {r.trigger_id for r in rows}
triggers = []
if trigger_ids:
triggers = (
Trigger.query
.filter(Trigger.id.in_(trigger_ids))
.all()
)
triggers_by_id = {t.id: t for t in triggers}
now = datetime.now(timezone.utc)
for r in rows:
trig = triggers_by_id.get(r.trigger_id)
last_used = r.last_used_at
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+644
to
+648
| out = [] | ||
| now = datetime.now(timezone.utc) | ||
| for r in rows: | ||
| trig = Trigger.query.get(r.trigger_id) | ||
| last_used = r.last_used_at |
There was a problem hiding this comment.
suggestion (performance): list_sessions does an N+1 query pattern when resolving trigger names.
TriggerSessionThread.query...all() is followed by Trigger.query.get(r.trigger_id) inside the loop, causing one additional query per row (N+1). For installations with many active session threads this can be costly. Please either join Trigger in the initial query or load all needed triggers in a single in_ query and map them by id to avoid the N+1 pattern.
Suggested change
| out = [] | |
| now = datetime.now(timezone.utc) | |
| for r in rows: | |
| trig = Trigger.query.get(r.trigger_id) | |
| last_used = r.last_used_at | |
| out = [] | |
| # Preload all referenced triggers to avoid N+1 queries | |
| trigger_ids = {r.trigger_id for r in rows} | |
| triggers = [] | |
| if trigger_ids: | |
| triggers = ( | |
| Trigger.query | |
| .filter(Trigger.id.in_(trigger_ids)) | |
| .all() | |
| ) | |
| triggers_by_id = {t.id: t for t in triggers} | |
| now = datetime.now(timezone.utc) | |
| for r in rows: | |
| trig = triggers_by_id.get(r.trigger_id) | |
| last_used = r.last_used_at |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
TL;DR
Adds opt-in
claude --resumefor consecutive webhooks of the same logical thread (e.g. ClickUp task, GitHub PR). Measured 60% faster + 66% cheaper for follow-up turns vs fresh subprocess on a real ClickUp task. Validated end-to-end against the livelsoldado/evo-nexusfork before this PR.Problem
Today every webhook spawns a fresh
claude --printsubprocess. The model has zero memory of prior turns — it must re-read all comments, re-derive context, and re-fetch data via API calls. For multi-comment workflows (reports → follow-up questions → implementations) this is:Solution
Per-trigger opt-in
--resume. When a webhook fires for the same logical thread (extracted via per-source_extract_dedup_key), the dispatcher passes the priorclaude_session_idto the CLI:The model now has the full conversation history of prior turns in its context window. Zero re-derivation cost.
Real-world measurement (today, 2026-05-03)
Tested on a live ClickUp "Relatório GBP" task (
86c9m056r) — client audit:--resumeResume saving on #3 vs equivalent #1 cold-start (controlled comparison — same task, same agent, same MCP fan-out):
The follow-up Oracle had the full reasoning trace from #1 — so when the user asked a clarifying question, no re-discovery was needed. It just answered.
Quality wins (not just cost)
The fresh-subprocess model loses things the dollar number doesn't capture:
Reasoning trace continuity: Oracle 1 explored 5 hypotheses before settling on a recommendation. Oracle 2 (fresh) sees only the final recommendation in the doc — not the rejected alternatives. With resume, Oracle 2 inherits the full trace. When asked "why did you discard hypothesis X?", it can answer.
Implicit IDs: Oracle 1 resolved
client_cuid=cent4...andgbp_account_id=accounts/113.... Oracle 2 (fresh) has to re-resolve. With resume, instant continuation.Partial-success continuity: when an MCP call fails midway, fresh Oracle re-tries everything. Resumed Oracle remembers what already succeeded and skips redundant calls.
No prompt re-engineering: the long system prompt (~6k tokens of guards, cookbook, routing tree) is loaded once and cached for the session. Subsequent turns ride the prompt cache.
Design
Backend
Trigger.resume_sessions BOOLEAN(defaultfalse). Existing triggers keep current behavior.trigger_session_threads (trigger_id, dedup_key, claude_session_id, last_used_at)— stores the per-thread mapping. UNIQUE on(trigger_id, dedup_key)._extract_dedup_key()per source:task.idpull_request.number/issue.numberissue.idrun_claude(..., resume_session_id=...)inADWs/runner.py— forwards--resume <id>only for the Anthropic CLI; silent no-op for non-Anthropic providers._execute_trigger:resume_sessions=true)run_claudetrigger_session_threads--resumeonce if claude errors with stale-session messageUI
/settings → Sessionstab: defaults toggle, cleanup config, storage stats, live thread list with reset/cleanupEndpoints
/api/settings/sessions/api/settings/sessions/api/sessions/api/sessions/<id>/api/sessions/cleanup-staleSchema migration (Alembic 0012)
Reversible. Idempotent (
_has_column/_has_tablechecks). Safe on PG and SQLite.Backward compatibility
resume_sessions=false→ zero behaviour change unless operator opts in.run_claude()callers unchanged unless they passresume_session_id.sessions.yaml(returns defaults).--resumeerrors (session GC'd), automatically retries fresh.Test plan
Local validation done on
lsoldado/evo-nexusfork — full trace in this PR's test artifacts. To replicate:alembic upgrade headcreates the new column + table on fresh SQLite ✓resume_sessions=trueon a trigger via UI → column persists ✓trigger_session_threadsrow created with captured session_id ✓--resume <id>✓~/.claude/projects/<workspace>/<session>.jsonl)cleanup-staleendpoint deletes only rows past threshold ✓CI status
The 4 failing checks on this PR's CI mirror are pre-existing failures on
developHEAD that are unrelated to this change:test_health_routes::test_deep_health_includes_providers_for_admin— flakytest_plugins_preview_endpoint::*—auth_tokensignature mismatch in upstream codetest_workspace::TestAuditAppend::test_happy_path_writes_jsonl@evoapi/evonexus-uipackageVerified by running
git diffbetween this branch's base andupstream/develop— none of the failing test files are touched by this PR.Files changed
ADWs/runner.pydashboard/alembic/versions/0012_clickup_session_resume.pydashboard/backend/models.pydashboard/backend/routes/settings.pydashboard/backend/routes/triggers.pydashboard/frontend/src/pages/Settings.tsxdashboard/frontend/src/pages/Triggers.tsxCHANGELOG.md🤖 Generated with Claude Code
Summary by Sourcery
Add per-trigger Claude session resume support across consecutive webhooks and expose global session management settings and admin tooling.
New Features:
Enhancements:
Documentation: