Skip to content

Commit 62f3416

Browse files
committed
docs(agents): add task-state-invariants skill
Most task-lifecycle defects in this SDK are not wrong values: they are a correct value that reached one surface and not the others (persisted store, streaming subscribers, push notifications, the cluster task_events table, and the two separate v0.3 compat mappers). The existing rule layer routes mistakes to mistake-reflection and code style to docs/ai, but nothing tells a change agent which surfaces a status write must reach, so the same class keeps recurring: a2aproject#1276 (status.timestamp mapped for JSON-RPC/REST compat but not gRPC), a2aproject#1188 (handler resumes from a stale snapshot), a2aproject#1206/a2aproject#1411 (contextId inference disagrees between events and the stored task), and the review findings on a2aproject#1346 (stamping the copy instead of the event, and missing the CANCELED paths). Adds .agents/skills/task-state-invariants/SKILL.md with the invariant set (each claim anchored to current main), the sibling-surface checklist, the matching test files per surface, and the evidence expected in a PR, plus a one-line router pointer in AGENTS.md so agents actually load it. Signed-off-by: andy <linux2011@qq.com>
1 parent 2bddd06 commit 62f3416

2 files changed

Lines changed: 152 additions & 0 deletions

File tree

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
name: task-state-invariants
3+
description: Use when adding or changing code that writes A2A task state (Task, TaskStatus, TaskStatusUpdateEvent, TaskUpdater, task stores, push notifications, cluster event streams, v0.3 compat mappers), or when reviewing such a change — runs the sibling-surface propagation checklist so a state change or field lands on every surface (persisted store, streaming subscribers, push notification, event table, both compat transports) instead of only some of them. Not for style or type rules (read docs/ai/coding_conventions.md) and not the pre-commit gate (read docs/ai/mandatory_checks.md).
4+
---
5+
6+
# Task State Invariants
7+
8+
Implements the missing verification step for the task-lifecycle subsystem:
9+
`AGENTS.md` tells you to run the check sequence, and `evidence_rules.md`
10+
tells you to cite behavior, but neither tells you **which surfaces a task
11+
state change must reach**. Most bugs in this area are not wrong values —
12+
they are a correct value that reached one surface and not the others.
13+
14+
## When to load this skill
15+
16+
Trigger on ANY of these, without waiting for the user to ask:
17+
18+
- You write or mutate `TaskStatus`, `Task`, `TaskStatusUpdateEvent`, or
19+
`TaskArtifactUpdateEvent`.
20+
- You touch `TaskManager.save_task_event`, a `TaskStore`, a
21+
`VersionedTaskStore`, or `DatabaseTaskStore` column mapping.
22+
- You touch push notifications, the event queue/consumer, or the cluster
23+
event stream (`task_events`).
24+
- You add or rename a protocol field, or touch `compat/v0_3/`.
25+
- You transition a task to a terminal or interrupted state anywhere.
26+
- A reviewer comment says some surface "still gets the old value", "keeps
27+
the stale timestamp", or "is missing on the other transport".
28+
29+
If unsure whether this covers your change: load it. Checking the matrix is
30+
cheap; a half-propagated state ships a bug.
31+
32+
## The invariant set
33+
34+
Each claim is anchored to current `main`. Re-read the file before quoting.
35+
36+
1. **A terminal state must carry `status.timestamp`.**
37+
`TERMINAL_TASK_STATES` is defined once in `src/a2a/utils/constants.py:35`
38+
and imported everywhere else — never re-declare a local copy.
39+
`DatabaseTaskStore` derives `last_updated` from it
40+
(`src/a2a/server/tasks/database_task_store.py:152-157`), so an unstamped
41+
terminal state persists `NULL` and silently drops the task from
42+
`ListTasks` ordering and `status_timestamp_after` filtering.
43+
2. **Stamp the event, then copy — not the copy.**
44+
`TaskManager.save_task_event` replaces status wholesale with
45+
`task.status.CopyFrom(event.status)`
46+
(`src/a2a/server/tasks/task_manager.py:285`). That same event object is
47+
handed to streaming subscribers, push notifications, and the event table.
48+
Stamping the local `task` after the copy leaves the event unstamped, so
49+
the store is fixed and the other three surfaces stay broken.
50+
3. **`CopyFrom` inherits the previous timestamp.** A copy-then-set-state
51+
transition (for example the cancel path,
52+
`src/a2a/server/agent_execution/active_task.py:971-973`) reuses whatever
53+
timestamp the prior state had, so the terminal write looks like a
54+
`WORKING` update. Set `status.timestamp` explicitly on every transition
55+
you introduce.
56+
4. **Push delivery is best-effort and never task-affecting.**
57+
`_dispatch_notification` already contains delivery failures and returns
58+
a bool; `send_notification` is awaited inline from the consumer at
59+
`src/a2a/server/agent_execution/active_task.py:409`. Anything that can
60+
raise there (config-store reads, URL validators, custom senders) must not
61+
escape into the failure path, or a webhook hiccup rewrites a completed
62+
task to `FAILED`.
63+
5. **Every request must produce at least one event.** With zero events,
64+
`on_message_send` falls through to `active_task.get_task()`
65+
(`src/a2a/server/request_handlers/default_request_handler_v2.py:518-520`),
66+
which awaits `_task_created` with no timeout
67+
(`src/a2a/server/agent_execution/active_task.py:1115-1117`) and hangs the
68+
request, producer, and consumer forever. Guard before awaiting, or the
69+
fallback must be bounded.
70+
6. **Store and stream must agree.** A blocking call may return a shared
71+
snapshot while later events land on the store — the copy-on-yield caveat
72+
is documented in-code at
73+
`src/a2a/server/agent_execution/active_task.py:965-970` (tracked in
74+
#1175 / #1191). After any change here, assert `GetTask` equals what the
75+
caller received.
76+
7. **v0.3 compat has two independent mappers.** `compat/v0_3/proto_utils.py`
77+
serves the gRPC surface and `compat/v0_3/conversions.py` serves JSON-RPC
78+
and REST. A field mapped in one and not the other appears and disappears
79+
by transport — see #1276 (status timestamp dropped on gRPC only) and
80+
#1403. Any compat field change must touch and test both.
81+
8. **Continuation identity is inferred, not invented.** With only
82+
`message.task_id`, the SDK must reuse the task's `context_id`
83+
(A2A v1.0 §3.4.3); generating a fresh one makes events disagree with the
84+
stored task — see #1206 and the open follow-up #1411.
85+
86+
## Procedure
87+
88+
1. Name the surfaces your change writes. Default assumption: **all five** —
89+
persisted store, streaming subscribers, push notification, cluster event
90+
table, v0.3 compat (both mappers).
91+
2. Grep for the sibling call sites before editing:
92+
93+
```bash
94+
grep -rn "save_task_event\|CopyFrom\|send_notification\|enqueue_event" src/a2a
95+
```
96+
97+
3. For each surface you touch, add or update a test in the matching file:
98+
`tests/server/tasks/test_task_manager.py`,
99+
`tests/server/tasks/test_database_task_store.py`,
100+
`tests/server/agent_execution/test_active_task.py`,
101+
`tests/server/tasks/test_push_notification_sender.py`,
102+
`tests/compat/v0_3/test_proto_utils.py`,
103+
`tests/compat/v0_3/test_conversions.py`.
104+
4. Assert the **event object** as well as the stored task — not just the
105+
store — for any timestamp or field you propagate.
106+
5. If you added a field, state in the PR which transports carry it (REST,
107+
JSON-RPC, gRPC, v0.3 compat each).
108+
6. Then run the normal gate: `docs/ai/mandatory_checks.md`.
109+
110+
## Evidence for the PR
111+
112+
Per `docs/ai/evidence_rules.md`, a behavior claim needs control-flow
113+
evidence. For this subsystem, the minimum is:
114+
115+
- the surface list from step 1, with the file:line of each write;
116+
- a test per surface touched, named for the surface;
117+
- before/after output showing the surface that used to get the old value.
118+
119+
## Anti-patterns
120+
121+
- Fixing the store and assuming the stream follows. It does not — the event
122+
is published separately.
123+
- Re-declaring `TERMINAL_TASK_STATES` locally instead of importing it from
124+
`a2a.utils.constants`.
125+
- Testing compat through one transport and concluding the field works.
126+
- Silently returning `None` from an executor: no event means no task, and
127+
the caller blocks (invariant 5).
128+
- Letting an infrastructure exception (store read, URL validation) escape
129+
into the consumer failure path (invariant 4).
130+
131+
## Boundaries
132+
133+
- This skill does not replace `mandatory_checks.md`; it runs before that
134+
gate, not instead of it.
135+
- It does not decide scope. If a surface is intentionally out of scope,
136+
say so in the PR and link the issue that owns it.
137+
- If you find an invariant here violated in code, load
138+
`mistake-reflection` only if *you* introduced the error; otherwise report
139+
it as an issue with reproduction.
140+
141+
## Provenance
142+
143+
Derived from recurring defects in this subsystem and the review feedback on
144+
them: #1313/#1329 (invariant 4), #1330 (5), #1331 (1, 2, 3), #1188 (6),
145+
#1276 (7), #1206/#1411 (8), and community questions #248, #435, #40, #1224.

‎AGENTS.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,13 @@ You MUST do all of the following:
3434
When unsure: load the skill. False positives are free; false
3535
negatives are how the same mistake recurs.
3636

37+
4. **When changing task state** (or reviewing such a change), load the
38+
`task-state-invariants` skill at
39+
`.agents/skills/task-state-invariants/SKILL.md` before editing. It lists
40+
the sibling surfaces a status change must reach (persisted store,
41+
streaming subscribers, push notification, cluster event table, both v0.3
42+
compat mappers) so a correct value does not land on some of them only.
43+
3744

3845
## Optional extras
3946

0 commit comments

Comments
 (0)