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 2a1384e
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/air-extensions.md
+64Lines changed: 64 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -953,6 +953,8 @@ A client can also declare the ACP `clientCapabilities.session.notices`.
953
953
Then a `warning`, `configWarning`, or `deprecationNotice` notification goes out as an ACP `notice` session update.
954
954
It does not go out as a `sessionFailure` record. Errors still use `sessionFailure`.
955
955
956
+
A client that is not AIR can opt in without the AIR namespace, see [Client-neutral session failure](#client-neutral-session-failure).
957
+
956
958
### Record
957
959
958
960
```json
@@ -1040,6 +1042,68 @@ A retry warning stops being active when Codex produces turn content again.
1040
1042
A successful turn ends an active warning of that turn.
1041
1043
Recovery never removes the transcript record.
1042
1044
1045
+
### Client-neutral session failure
1046
+
1047
+
A client that is not AIR can get the same typed lane without the `_meta.jetbrains.air` namespace.
1048
+
It opts in with `initialize.clientCapabilities._meta`:
1049
+
1050
+
```json
1051
+
{ "sessionFailure": { "version": 1 } }
1052
+
```
1053
+
1054
+
- Accepted only when `sessionFailure` is an object whose `version` is an integer of at least 1. Anything else
1055
+
enables nothing.
1056
+
- The opt-in is an ACP v1 extension. The `initialize` answer of an opted-in client has the top-level
1057
+
`_meta.sessionFailure: {"version": 1}`.
1058
+
- ACP v2 ignores the opt-in: a v2 terminal failure is reported with `state_update.error`.
1059
+
1060
+
The opt-in selects the whole lane, not just where the record goes. The [delivery](#delivery), the identity,
1061
+
the [categories and actions](#categories-and-actions), the [title and details](#title-and-details), the
1062
+
[recovery](#recovery) and the `session.notices` rule are those of the AIR form. In particular:
1063
+
1064
+
- A terminal failure of the running turn ends the prompt with `stopReason: end_turn` and the record, not with agent
1065
+
text or a JSON-RPC error. A prompt that failed because the Codex process exited or the adapter failed
1066
+
unexpectedly does the same.
1067
+
- Records replace `_meta.codex.error`. Records or, with `session.notices`, ACP `notice` updates replace the
1068
+
`Warning:` and `Config warning:` text chunks.
1069
+
-`unauthorized` and HTTP 401 still end the prompt with the ACP `authRequired` error and no record.
1070
+
1071
+
The record goes in the top-level `_meta.sessionFailure` of a `session_info_update` or of the `PromptResponse`:
1072
+
1073
+
```json
1074
+
{
1075
+
"stopReason": "end_turn",
1076
+
"_meta": {
1077
+
"sessionFailure": {
1078
+
"version": 1,
1079
+
"id": "turn-7:error",
1080
+
"revision": 1,
1081
+
"category": "limit",
1082
+
"severity": "error",
1083
+
"title": "You've hit your usage limit.",
1084
+
"actions": [],
1085
+
"kind": "quota_exhausted"
1086
+
}
1087
+
}
1088
+
}
1089
+
```
1090
+
1091
+
It has the fields of the [AIR record](#record), plus `version` and:
1092
+
1093
+
| Field | Required | Type | Meaning |
1094
+
| --- | --- | --- | --- |
1095
+
|`kind`| yes | open string | The adapter's internal kind of the failure. Ignore a value that you do not know. |
1096
+
1097
+
The current kinds are `transport_lost`, `rate_limited`, `quota_exhausted`, `overloaded`, `context_exhausted`,
1098
+
`budget_exhausted`, `policy_denied`, `bad_request`, `provider_error`, `internal_error`, and `notice` for a warning
1099
+
record that comes from a Codex notice. A retry warning has the kind of its failure.
1100
+
1101
+
- Revisions of an id only increase for the whole connection, also across prompts and `session/load`, and a new
1102
+
session-scoped incident always gets a new id. A new adapter process starts over.
1103
+
- A client that declares both the AIR `sessionFailure` capability and the client-neutral opt-in gets only the
1104
+
client-neutral form. Its AIR capability list still names `sessionFailure`.
1105
+
- AIR clients that do not send the client-neutral opt-in get the AIR form, unchanged. The AIR record has no `kind`.
1106
+
1043
1107
## Native subagent sessions
1044
1108
1045
1109
The adapter implements the draft [ACP subagent RFD](https://github.com/agentclientprotocol/agent-client-protocol/pull/1992).
0 commit comments