From 2be411db16c3ae5b97c5b0015dfb4a239a10a89b Mon Sep 17 00:00:00 2001 From: Joshua Buss Date: Mon, 3 Aug 2026 14:50:31 -0700 Subject: [PATCH] skill: document the change feed Agents reading the skill would not otherwise know /changes exists, so a refreshed list_changes tool arrives with no explanation of what it is for. Records the two things that bite in practice: the cursor is opaque and bound to the scope that produced it, so it must not be constructed by hand or carried across a workspace or kind filter; and the MCP tool list is fixed at session connect, so a session older than the feature will not see list_changes until it reconnects. --- skills/tracker/SKILL.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/skills/tracker/SKILL.md b/skills/tracker/SKILL.md index a3ffc31..7aaec7e 100644 --- a/skills/tracker/SKILL.md +++ b/skills/tracker/SKILL.md @@ -113,6 +113,37 @@ it needs instead of linking to docs that will not resolve. last activity. Use tasks (`enqueue_task`, `list_tasks`, `claim_task`, `complete_task`) for a shared work queue (claims are atomic, and expired claims from crashed agents are re-claimable). +5. **Being woken on change** — see below. Prefer this to polling. + +## The change feed (v1.5.0+) + +Every mutation appends an event, so you can react to change instead of asking +repeatedly whether anything happened. + +- `list_changes` (MCP) / `GET /changes?since=&kind=&limit=` — cursor-paged +- `GET /changes/stream` — Server-Sent Events, one frame per event + +```bash +curl -sN /changes/stream -H "X-Actor: " | grep --line-buffered '^data: ' +``` + +`since` is an **opaque cursor** — omit it on the first call, then pass back +`next_cursor`, or the SSE `id:` field, which carries the same value. Do not +construct one by hand; the format is deliberately not a number. + +A cursor is **bound to the scope that produced it** — the workspace and the +`kind` filter. Reusing one under a different scope returns 400 rather than +silently skipping events. It is a resumption hint, not a capability: row +visibility is still enforced by the database. + +Two operational notes: + +- **The MCP tool list is fixed when your session connects.** A session that + started before the server gained `list_changes` will not have it until it + reconnects. The HTTP endpoints work regardless, and are the better choice for + a long-running watcher. +- The feed starts at the deploy that introduced it; there is no backfill of + history from before that point. ## Etiquette