Compatibility

Stable in v1Copy Anchor Link

These keep their names, shapes and meaning for as long as the app serves v1:

• The transport: loopback TCP, one line per request, one line per answer, and the streaming of SubscribeAgents.
• The envelope (api_version, token, from, request), the "Client" and Terminal callers, and Hello.
• The requests and responses in Agents, Messages and screens, Workers, Sessions, worktrees, files and changes, Kraddies and automations, Memory, and RunVariants and PickVariant, with the fields shown.
• The agent states, coarse states, event kinds and reasons; seq, stream, the snapshot and resume rules and the heartbeat.
• The error codes and the CLI's exit codes.
• The discovery file's fields and the KRAD_ADE_* variables.
• App event records with api 1, their kinds and fields, and the webhook headers and signature.

How v1 changesCopy Anchor Link

Only by addition: new requests, new response kinds, new optional fields, new error codes, states or reasons.

• The app ignores fields it does not know in a request.
• Clients should do the same with answers, and treat an unknown response kind or code as a refusal they do not understand.
• A change that would break a v1 client gets a new api_version. The app answers only the version it serves and refuses any other with unsupported_api_version.

Not stableCopy Anchor Link

• The text of messages and of the CLI's plain output; use --json.
• The display text in next_run, last_outcome, schedule and triggers.
• The body of Variants answers.
• The requests the app's integrations use: Hook, Status, Ask, Askpass, Code, Tools and ExtensionTool.