feat: #164 Stage B prep — add cancel_observed field to TurnResult

#164 Stage B requires exposing whether cancellation was observed at the
turn-result level. This commit adds the infrastructure field:

Changes:
- TurnResult.cancel_observed: bool = False (query_engine.py)
- _build_timeout_result() accepts cancel_observed parameter (runtime.py)
- Two timeout paths now pass cancel_event.is_set() to signal observation (runtime.py)
- bootstrap command includes cancel_observed in turn JSON (main.py)
- SCHEMAS.md documents Turn Result Fields with cancel_observed contract

Usage:
  When a turn timeout occurs, cancel_observed=true indicates that the
  engine observed the cancellation event being set. This allows callers
  to distinguish:
    - timeout with no cancel → infrastructure/network stall
    - timeout with cancel observed → cooperative cancellation was triggered

Backward compat:
  - Existing TurnResult construction without cancel_observed defaults to False
  - bootstrap JSON output still validates per SCHEMAS.md (new field is always present)

Test results: 182 passing, 3 skipped, zero regression.

Related: #161 (wall-clock timeout), #164 (cancellation observability protocol)
ROADMAP continues #164 with Stage C (test coverage for cancellation + turn envelope).
This commit is contained in:
YeonGyu-Kim
2026-04-22 19:44:47 +09:00
parent 290ab7e41f
commit 97c4b130dc
4 changed files with 28 additions and 3 deletions

View File

@@ -30,6 +30,19 @@ Every command response, success or error, carries:
---
## Turn Result Fields (Multi-Turn Sessions)
When a command's response includes a `turn` object (e.g., in `bootstrap` or `turn-loop`), it carries:
| Field | Type | Required | Notes |
|---|---|---|---|
| `prompt` | string | Yes | User input for this turn |
| `output` | string | Yes | Assistant response |
| `stop_reason` | enum | Yes | One of: `completed`, `timeout`, `cancelled`, `max_budget_reached`, `max_turns_reached` |
| `cancel_observed` | bool | Yes | #164 Stage B: cancellation was signaled and observed (#161/#164) |
---
## Error Envelope
When a command fails (exit code 1), responses carry: