You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 07549bd
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: EVENTS.md
+37-12Lines changed: 37 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -13,7 +13,7 @@ When the parsed `aictrl run --format json` handler starts, the CLI emits newline
13
13
14
14
`invocationID` is present on every event from `run --format json`. `sessionID` is present only after a real session has been created; invocation events never fabricate one.
15
15
16
-
The schema is versioned via `invocation_start.schemaVersion` and `session_start.schemaVersion`. This document describes **schema version `"1"`**. Consumers should pin to this version and treat unknown fields as forward-compatible additions.
16
+
The schema is versioned via `invocation_start.schemaVersion` and `session_start.schemaVersion`. This document describes **schema version `"1"`**. Consumers should pin to this version and treat unknown fields and event types as forward-compatible additions. The `retry` event is an additive event type, so `SCHEMA_VERSION` remains `"1"`.
17
17
18
18
The invocation envelope covers accepted `run --format json` executions from the first line of the parsed handler through validation, bootstrap, session creation, and execution. Argument-parser failures, other commands, and process-global uncaught exceptions or unhandled rejections are outside this contract.
19
19
@@ -176,6 +176,28 @@ Emitted immediately before `session_complete` when the session terminates abnorm
176
176
177
177
## Message Events
178
178
179
+
### `retry`
180
+
181
+
Emitted when a primary-session model attempt fails with a retryable error and the CLI schedules another attempt. This includes a thought-only `unknown` finish with no tool call or non-empty text. It is not emitted after retries are exhausted or for an `unknown` finish that includes text or a tool call.
-`attempt` (number, **required**) — retry number, starting at 1.
197
+
-`code` (string, **required**) — safe retry reason: `no_finish_reason`, `rate_limited`, `overloaded`, `server_error`, `network`, or `unknown`. Provider error text is omitted from this event.
198
+
-`retry.code``rate_limited` maps to `session_error.reason``rate_limit`; `no_finish_reason`, `overloaded`, `server_error`, and `network` are retry-only codes.
199
+
-`next` (number, **required**) — scheduled next-attempt time in Unix milliseconds.
200
+
179
201
### `message_complete`
180
202
181
203
Emitted when a primary-session assistant message finishes (one per LLM turn). Child-session assistant messages are
@@ -234,17 +256,20 @@ For compatibility with sessions written before usage provenance was persisted, a
234
256
235
257
A provider can finish an HTTP stream normally while reporting a failed model turn. `error` and `content-filter` finishes persist a nonretryable `APIError` with `data.metadata.finishReason`; they emit `message_complete.status: "error"`, `session_error.reason: "provider"`, a populated `session_complete.error`, and `invocation_complete.status: "error"`. Headless execution exits 1 after flushing output. Partial text, completed tools, and reported usage remain available. No automatic recovery is attempted.
| Cancellation / stream timeout | Existing cancellation and timeout lifecycle; not reclassified as a provider finish error. |
259
+
An `unknown` finish is triaged by delivered output. Nonempty text becomes `stop`; a delivered tool call continues the loop. With neither, the attempt is retried, its output parts and usage are rolled back, and a `retry` event is emitted for each scheduled retry. Snapshot patch parts remain available for reverting file changes from failed attempts. Exhaustion produces a terminal error with `data.metadata.finishReason: "unknown"`. A pending tool input alone does not count as a delivered call. The agent step cap emits a terminal error; when it applies to an unfinished model turn, the provider's finish reason is preserved rather than rewritten as `stop`.
|`error`| Failed model turn; session/invocation failure and exit 1. |
264
+
|`content-filter`| Failed model turn with a visible content-filter message; exit 1. |
265
+
|`stop`| Completed turn, including empty output. |
266
+
|`tool-calls`| Completed model turn; run tools and continue the session loop. |
267
+
|`length`| Existing behavior: completed turn; preserve the reason so consumers can identify truncation. |
268
+
|`unknown`| Text becomes `stop`; a delivered tool call continues; no visible output retries, then fails on exhaustion. |
269
+
| Agent step cap | Terminal error; preserve the unfinished model turn's provider finish, or emit a session-level error after a subtask or compaction. |
270
+
| Other nonempty finish | Existing behavior: end the loop without inferring failure from an unfamiliar reason. |
| Cancellation / stream timeout | Existing cancellation and timeout lifecycle; not reclassified as a provider finish error. |
248
273
249
274
With pinned Google SDK 2.0.54, `IMAGE_SAFETY`, `RECITATION`, `SAFETY`, `BLOCKLIST`, `PROHIBITED_CONTENT`, and `SPII` map to `content-filter`; `MALFORMED_FUNCTION_CALL` maps to `error`. `OTHER` and `FINISH_REASON_UNSPECIFIED` map to `other`, while `LANGUAGE` maps to `unknown`. These last mappings retain the behavior above; they do not prove successful task completion. Consumers can distinguish `other` from `stop` using `message_complete.finish`.
0 commit comments