diff --git a/docs/specification.md b/docs/specification.md index 13ecd6bfe..288329494 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -47424,14 +47424,14 @@ The **A2A Facade** (`cleveragents.a2a`) is the sole interface between the Presen ###### Session Management -Sessions are persistent conversation threads tied to an orchestrator actor. In v3.5.0, session lifecycle operations are fully functional via the A2A facade: +Sessions are persistent conversation threads tied to an orchestrator actor. In v3.5.0, session lifecycle operations remain part of the A2A/session workflow surface, not registry CRUD. Sessions are runtime conversation state, so they are not included in the `_cleveragents/registry/{entity}/*` entity set. -| A2A Extension Method | CLI Command | Description | +| A2A / Service Route | CLI Command | Description | |---------------------|-------------|-------------| -| `_cleveragents/registry/session/list` | `agents session list` | List all sessions | -| `_cleveragents/registry/session/show` | `agents session show SESSION_ID` | Get session details | -| `message/send` | `agents session tell` | Send a message to the session's orchestrator actor | -| `_cleveragents/registry/session/remove` | `agents session delete SESSION_ID` | Close and delete a session | +| `session/list` routes to `SessionWorkflow.list()` | `agents session list` | List all sessions | +| `session/load` routes to `SessionWorkflow.resume()` / `SessionService.get()` | `agents session show SESSION_ID` | Get session details | +| `message/send` routes to `SessionWorkflow.tell()` | `agents session tell` | Send a message to the session's orchestrator actor | +| `SessionService.delete()` via the session lifecycle command path | `agents session delete SESSION_ID` | Close and delete a session | When a session does not yet exist, `message/send` creates one implicitly. The session ID is returned in the Task metadata. Subsequent messages reference the session via the A2A `contextId` field. @@ -47679,7 +47679,7 @@ The Validation-Gated Apply subsystem ensures that changes are only applied to re ###### Validation Pipeline -The validation pipeline runs all attached validations against the sandbox changeset before allowing the Apply phase to proceed. An empty validation summary (no validations ran) is treated as a failed gate, because Apply must never proceed without validation evidence. +The validation pipeline runs during Execute, after sandbox changes are produced and before the plan can proceed to Apply. Apply checks the final validation summary/snapshot produced during Execute. An empty validation summary (no required validations ran) is treated as a failed gate, because Apply must never proceed without validation evidence. - **Required validations** (`mode: required`) — If any fail, Apply is blocked and the plan enters `constrained` state. - **Informational validations** (`mode: informational`) — Failures log a warning but do not block Apply. @@ -47688,10 +47688,10 @@ The validation pipeline runs all attached validations against the sandbox change The Apply gate is enforced by `PlanLifecycleService.apply_plan()`. The method: -1. Runs the validation pipeline against the sandbox changeset -2. If any required validation fails, transitions the plan to `constrained` state and raises `ValidationGateError` -3. If no validations ran, transitions the plan to `constrained` state and raises `ValidationGateError` -4. If all required validations pass, applies the sandbox changeset to real resources +1. Loads the final validation summary/snapshot recorded by the Execute phase +2. If any required validation failed, transitions the plan to `constrained` state and raises `ValidationGateError` +3. If no required validation ran, transitions the plan to `constrained` state and raises `ValidationGateError` +4. If all required validations passed, applies the sandbox changeset to real resources **Plan States After Validation:** @@ -47702,7 +47702,7 @@ The Apply gate is enforced by `PlanLifecycleService.apply_plan()`. The method: | Required validation failed | `constrained` | Fix issues, re-execute, or revert to Strategize | | Informational validation failed | `applying` then `applied` | Warning logged; apply proceeds | -The `require_approval_for_apply` guard adds a human approval gate before the validation pipeline runs. When set, the A2A Task enters `input-required` state and waits for user approval before proceeding to validation. +The `require_approval_for_apply` guard adds a human approval gate before Apply commits the sandbox changeset. When set, the A2A Task enters `input-required` state and waits for user approval before the apply gate checks the Execute-phase validation snapshot. ---