cleveragents/cleveragents-core

Fork 3

UAT: A2A Task lifecycle model missing — no `A2aTask` model with `submitted`/`working`/`completed`/`failed`/`canceled`/`input-required` states #3639

New issue

Open

opened 2026-04-05 21:02:32 +00:00 by freemo · 1 comment

freemo commented

2026-04-05 21:02:32 +00:00

Owner

Metadata

Branch: fix/v3.6-a2a-task-lifecycle-model
Commit Message: fix(a2a): add A2aTask model with TaskState enum and typed task event models
Milestone: v3.6.0
Parent Epic: #366

Background and Context

Per docs/specification.md (line 23425):

A2A uses a Task-centric model: each message/send or message/stream creates or updates a Task that tracks the lifecycle of the interaction. Tasks transition through states: submitted → working → completed (or failed, canceled, input-required).

The spec also defines (lines 43350–43351):

Event Type	Description	Payload
`TaskStatusUpdateEvent`	Agent produces response tokens, task state changes, automation profile switched	`status` (state + message with agent response Parts)
`TaskArtifactUpdateEvent`	Plan artifacts, tool invocation results, generated outputs	`artifact` (named artifact with Parts)

And (line 23444):

| Task input-required state | Human-in-the-loop approval — maps to automation profile gates |

Current Behavior

src/cleveragents/a2a/models.py contains only:

A2aRequest — JSON-RPC 2.0 request envelope
A2aResponse — JSON-RPC 2.0 response envelope
A2aEvent — generic event with event_type, plan_id, data
A2aErrorDetail — error payload

There is no A2aTask model with:

task_id: str — unique task identifier
state: TaskState — enum of submitted, working, completed, failed, canceled, input-required
message: dict — the message that created/updated the task
artifacts: list — task artifacts (for TaskArtifactUpdateEvent)
created_at: str — timestamp

There is no TaskState enum defining the valid states.

The A2aEvent model uses a generic event_type: str field instead of typed task state events. The TaskStatusUpdateEvent and TaskArtifactUpdateEvent constants in events.py are just string constants — there are no corresponding Pydantic models.

Expected Behavior

Per the spec, the A2A models module must include:

TaskState enum with values: submitted, working, completed, failed, canceled, input-required
A2aTask Pydantic model with task_id, state, message, artifacts, timestamps
TaskStatusUpdate model for TaskStatusUpdateEvent payloads (with state, message with agent response Parts)
TaskArtifactUpdate model for TaskArtifactUpdateEvent payloads (with artifact containing named Parts)

These models are required by the message/send and message/stream handlers (tracked in #3590) to return properly typed Task responses.

Steps to Reproduce

from cleveragents.a2a import models

# These should exist but don't:
# models.A2aTask
# models.TaskState
# models.TaskState.submitted
# models.TaskState.working
# models.TaskState.completed
# models.TaskState.failed
# models.TaskState.canceled
# models.TaskState.input_required

Impact

Without the Task lifecycle model, the message/send and message/stream operations (tracked in #3590) cannot return properly structured Task responses. This is a prerequisite for implementing the core A2A conversation protocol.

Code Location

src/cleveragents/a2a/models.py — missing A2aTask, TaskState, TaskStatusUpdate, TaskArtifactUpdate models
src/cleveragents/a2a/events.py — TASK_STATUS_UPDATE and TASK_ARTIFACT_UPDATE constants exist but no typed models

Subtasks

Add TaskState enum to src/cleveragents/a2a/models.py with values: submitted, working, completed, failed, canceled, input-required
Add A2aTask Pydantic model to src/cleveragents/a2a/models.py with fields: task_id: str, state: TaskState, message: dict, artifacts: list, created_at: str
Add TaskStatusUpdate Pydantic model for TaskStatusUpdateEvent payloads (fields: state: TaskState, message: dict)
Add TaskArtifactUpdate Pydantic model for TaskArtifactUpdateEvent payloads (fields: artifact: dict with named Parts)
Export all new models from src/cleveragents/a2a/__init__.py
Tests (Behave): Add scenarios in features/ asserting TaskState enum values match the spec, A2aTask can be instantiated with all valid states, and state transitions are validated
Tests (Behave): Add scenarios verifying TaskStatusUpdate and TaskArtifactUpdate models serialize/deserialize correctly
Tests (Robot): Add integration test verifying A2aTask model is importable and all TaskState values are accessible
Verify coverage ≥ 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
TaskState enum exists in src/cleveragents/a2a/models.py with all 6 spec-required values: submitted, working, completed, failed, canceled, input-required
A2aTask Pydantic model exists with task_id, state, message, artifacts, and created_at fields
TaskStatusUpdate and TaskArtifactUpdate Pydantic models exist and are correctly typed
All new models are exported from the a2a package __init__.py
Pyright type checking passes with no suppressions (nox -e typecheck)
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(a2a): add A2aTask model with TaskState enum and typed task event models), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/v3.6-a2a-task-lifecycle-model).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage ≥ 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/v3.6-a2a-task-lifecycle-model` - **Commit Message**: `fix(a2a): add A2aTask model with TaskState enum and typed task event models` - **Milestone**: v3.6.0 - **Parent Epic**: #366 ## Background and Context Per `docs/specification.md` (line 23425): > A2A uses a **Task-centric model**: each `message/send` or `message/stream` creates or updates a Task that tracks the lifecycle of the interaction. Tasks transition through states: `submitted` → `working` → `completed` (or `failed`, `canceled`, `input-required`). The spec also defines (lines 43350–43351): | Event Type | Description | Payload | |---|---|---| | `TaskStatusUpdateEvent` | Agent produces response tokens, task state changes, automation profile switched | `status` (state + message with agent response Parts) | | `TaskArtifactUpdateEvent` | Plan artifacts, tool invocation results, generated outputs | `artifact` (named artifact with Parts) | And (line 23444): > | Task `input-required` state | Human-in-the-loop approval — maps to automation profile gates | ## Current Behavior `src/cleveragents/a2a/models.py` contains only: - `A2aRequest` — JSON-RPC 2.0 request envelope - `A2aResponse` — JSON-RPC 2.0 response envelope - `A2aEvent` — generic event with `event_type`, `plan_id`, `data` - `A2aErrorDetail` — error payload There is **no `A2aTask` model** with: - `task_id: str` — unique task identifier - `state: TaskState` — enum of `submitted`, `working`, `completed`, `failed`, `canceled`, `input-required` - `message: dict` — the message that created/updated the task - `artifacts: list` — task artifacts (for `TaskArtifactUpdateEvent`) - `created_at: str` — timestamp There is **no `TaskState` enum** defining the valid states. The `A2aEvent` model uses a generic `event_type: str` field instead of typed task state events. The `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` constants in `events.py` are just string constants — there are no corresponding Pydantic models. ## Expected Behavior Per the spec, the A2A models module must include: 1. `TaskState` enum with values: `submitted`, `working`, `completed`, `failed`, `canceled`, `input-required` 2. `A2aTask` Pydantic model with `task_id`, `state`, `message`, `artifacts`, timestamps 3. `TaskStatusUpdate` model for `TaskStatusUpdateEvent` payloads (with `state`, `message` with agent response Parts) 4. `TaskArtifactUpdate` model for `TaskArtifactUpdateEvent` payloads (with `artifact` containing named Parts) These models are required by the `message/send` and `message/stream` handlers (tracked in #3590) to return properly typed Task responses. ## Steps to Reproduce ```python from cleveragents.a2a import models # These should exist but don't: # models.A2aTask # models.TaskState # models.TaskState.submitted # models.TaskState.working # models.TaskState.completed # models.TaskState.failed # models.TaskState.canceled # models.TaskState.input_required ``` ## Impact Without the Task lifecycle model, the `message/send` and `message/stream` operations (tracked in #3590) cannot return properly structured Task responses. This is a prerequisite for implementing the core A2A conversation protocol. ## Code Location - `src/cleveragents/a2a/models.py` — missing `A2aTask`, `TaskState`, `TaskStatusUpdate`, `TaskArtifactUpdate` models - `src/cleveragents/a2a/events.py` — `TASK_STATUS_UPDATE` and `TASK_ARTIFACT_UPDATE` constants exist but no typed models ## Subtasks - [ ] Add `TaskState` enum to `src/cleveragents/a2a/models.py` with values: `submitted`, `working`, `completed`, `failed`, `canceled`, `input-required` - [ ] Add `A2aTask` Pydantic model to `src/cleveragents/a2a/models.py` with fields: `task_id: str`, `state: TaskState`, `message: dict`, `artifacts: list`, `created_at: str` - [ ] Add `TaskStatusUpdate` Pydantic model for `TaskStatusUpdateEvent` payloads (fields: `state: TaskState`, `message: dict`) - [ ] Add `TaskArtifactUpdate` Pydantic model for `TaskArtifactUpdateEvent` payloads (fields: `artifact: dict` with named Parts) - [ ] Export all new models from `src/cleveragents/a2a/__init__.py` - [ ] Tests (Behave): Add scenarios in `features/` asserting `TaskState` enum values match the spec, `A2aTask` can be instantiated with all valid states, and state transitions are validated - [ ] Tests (Behave): Add scenarios verifying `TaskStatusUpdate` and `TaskArtifactUpdate` models serialize/deserialize correctly - [ ] Tests (Robot): Add integration test verifying `A2aTask` model is importable and all `TaskState` values are accessible - [ ] Verify coverage ≥ 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - [ ] All subtasks above are completed and checked off. - [ ] `TaskState` enum exists in `src/cleveragents/a2a/models.py` with all 6 spec-required values: `submitted`, `working`, `completed`, `failed`, `canceled`, `input-required` - [ ] `A2aTask` Pydantic model exists with `task_id`, `state`, `message`, `artifacts`, and `created_at` fields - [ ] `TaskStatusUpdate` and `TaskArtifactUpdate` Pydantic models exist and are correctly typed - [ ] All new models are exported from the `a2a` package `__init__.py` - [ ] Pyright type checking passes with no suppressions (`nox -e typecheck`) - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(a2a): add A2aTask model with TaskState enum and typed task event models`), followed by a blank line, then additional lines providing relevant details about the implementation. - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/v3.6-a2a-task-lifecycle-model`). - [ ] The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - [ ] All nox stages pass. - [ ] Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.6.0 milestone

2026-04-05 21:02:37 +00:00

freemo added a new dependency

2026-04-05 21:02:47 +00:00

#366 Epic: Post-MVP Deferred Work

freemo referenced this issue

2026-04-05 21:07:38 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue

2026-04-05 21:24:08 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo commented

2026-04-05 22:12:51 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Critical — The A2A Task lifecycle model is entirely missing. Without A2aTask, TaskState, TaskStatusUpdate, and TaskArtifactUpdate models, the core A2A conversation protocol (message/send, message/stream) cannot return properly typed Task responses. This blocks #3590.
Milestone: v3.6.0 (already assigned — A2A protocol compliance is in scope)
Story Points: 5 — L — Requires creating 4 new Pydantic models, a new enum, exporting from __init__.py, plus comprehensive Behave and Robot tests. Moderate complexity due to spec alignment requirements.
MoSCoW: Must Have — The spec explicitly defines the Task-centric model as the foundation of A2A interactions. Without these models, the A2A protocol is non-functional. This is a prerequisite for core A2A operations.
Parent Epic: #366

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical — The A2A Task lifecycle model is entirely missing. Without `A2aTask`, `TaskState`, `TaskStatusUpdate`, and `TaskArtifactUpdate` models, the core A2A conversation protocol (`message/send`, `message/stream`) cannot return properly typed Task responses. This blocks #3590. - **Milestone**: v3.6.0 (already assigned — A2A protocol compliance is in scope) - **Story Points**: 5 — L — Requires creating 4 new Pydantic models, a new enum, exporting from `__init__.py`, plus comprehensive Behave and Robot tests. Moderate complexity due to spec alignment requirements. - **MoSCoW**: Must Have — The spec explicitly defines the Task-centric model as the foundation of A2A interactions. Without these models, the A2A protocol is non-functional. This is a prerequisite for core A2A operations. - **Parent Epic**: #366 --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-05 22:16:05 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 (Resumed) #3654