From e63ede0462a63f73c4c4112367511f13388e9e85 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Mon, 27 Apr 2026 06:02:58 +0900 Subject: [PATCH] docs: add docs/API_REFERENCE.md (JSON envelope, error shape, output format contract) --- PARITY.md | 2 +- docs/API_REFERENCE.md | 174 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 175 insertions(+), 1 deletion(-) create mode 100644 docs/API_REFERENCE.md diff --git a/PARITY.md b/PARITY.md index fe7fcd9..e7e51d4 100644 --- a/PARITY.md +++ b/PARITY.md @@ -213,5 +213,5 @@ Repo documentation suite shipped during extended dogfood audit. Status: present/ | CODE_OF_CONDUCT.md | ✅ Present | Low | Contributor Covenant v2.1 | | .github/PULL_REQUEST_TEMPLATE.md | ✅ Present | Medium | Standardizes PR descriptions | | docs/CONFIGURATION.md | ✅ Present | High | env vars, settings.json, provider config — relates to #283, #285 | -| docs/API_REFERENCE.md | ❌ Missing | Medium | JSON envelope schema, output format contract | +| docs/API_REFERENCE.md | ✅ Present | Medium | JSON envelope schema, output format contract — #288, #266, #168c | | .github/ISSUE_TEMPLATE/bug_report.md | ✅ Present | #431 | Standard bug template with repro steps, environment, context sections | diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md new file mode 100644 index 0000000..688bf86 --- /dev/null +++ b/docs/API_REFERENCE.md @@ -0,0 +1,174 @@ +# API Reference — JSON Output Envelope Contract + +This document describes the machine-readable JSON output emitted by `claw` when +`--output-format json` is passed. All JSON envelopes are written to **stdout**. +Stderr is reserved for non-contractual diagnostics only (see pinpoint #168c). + +--- + +## Output Format Flag + +``` +claw [command] --output-format json +claw [command] --output-format text # default +``` + +When `json` is active, **all** output (success and error) is emitted as a single +JSON object on stdout. Consumers must not parse stderr for errors. + +--- + +## Success Envelope — `claw -p ` + +Full non-compact run (default): + +```json +{ + "message": "", + "model": "claude-opus-4-5", + "iterations": 3, + "auto_compaction": null, + "tool_uses": [...], + "tool_results": [...], + "prompt_cache_events": [...], + "usage": { + "input_tokens": 1234, + "output_tokens": 567, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 0 + }, + "estimated_cost": "$0.0123" +} +``` + +Compact run (`--compact`): + +```json +{ + "message": "", + "compact": true, + "model": "claude-opus-4-5", + "usage": { + "input_tokens": 1234, + "output_tokens": 567, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 0 + } +} +``` + +### Field Reference + +| Field | Type | Description | +|---|---|---| +| `message` | string | Final assistant reply text | +| `model` | string | Model identifier used for the turn | +| `iterations` | integer | Number of tool-use / re-prompt iterations | +| `compact` | boolean | Present and `true` when `--compact` mode was active | +| `auto_compaction` | object\|null | Non-null when auto-compaction fired (see below) | +| `tool_uses` | array | Tool calls made during the turn (TODO: verify schema) | +| `tool_results` | array | Results returned to the model (TODO: verify schema) | +| `prompt_cache_events` | array | Cache-hit/miss events (TODO: verify schema) | +| `usage.input_tokens` | integer | Input tokens billed | +| `usage.output_tokens` | integer | Output tokens billed | +| `usage.cache_creation_input_tokens` | integer | Tokens written to prompt cache | +| `usage.cache_read_input_tokens` | integer | Tokens served from prompt cache | +| `estimated_cost` | string | Human-readable USD cost estimate (e.g. `"$0.0123"`) | + +#### `auto_compaction` sub-object + +```json +{ + "removed_messages": 12, + "notice": "Auto-compacted: removed 12 messages to free context." +} +``` + +--- + +## Error Envelope + +When a command fails under `--output-format json`, an error envelope is written +to **stdout** (pinpoint #168c / #288): + +```json +{ + "type": "error", + "error": "", + "kind": "", + "hint": "" +} +``` + +### Error Envelope Fields + +| Field | Type | Description | +|---|---|---| +| `type` | string | Always `"error"` | +| `error` | string | Short prose description of the failure | +| `kind` | string | Machine-readable snake_case token (see §Error Kinds) | +| `hint` | string\|null | Optional remediation hint | + +### Error Kinds (selected) + +`kind` values are classified by `classify_error_kind()`. Common tokens include: + +- `not_yet_implemented` — command stub not yet shipped +- `config_error` — configuration file parse / validation failure +- `auth_error` — API key or credential problem +- `permission_denied` — tool-use permission denied +- `model_error` — upstream model API error + +See pinpoint #266 (typed-error-kind) for the full taxonomy. + +--- + +## Streaming Behavior + +`claw` always uses streaming internally (HTTP chunked transfer to the Anthropic +API) but the **JSON output envelope is emitted once**, after the turn completes. +There is no per-token or per-chunk JSON stream exposed to the caller. + +In REPL / interactive mode (`claw` with no `-p`) the JSON format applies only to +structured sub-commands, not to the interactive session itself. + +--- + +## Status Snapshot (`claw status`) + +```json +{ + "kind": "status", + "status": "ok", + "config_load_error": null, + "model": "claude-opus-4-5", + "model_source": "config", + "model_raw": null, + "permission_mode": "default", + "usage": { + "messages": 42, + "turns": 10, + "latest_total": 5678, + "cumulative_input": 12345, + "cumulative_output": 4567, + "cumulative_total": 16912, + "estimated_tokens": 16912 + }, + "workspace": { + "cwd": "/Users/you/project", + "project_root": "/Users/you/project", + "git_branch": "main", + "git_state": "clean", + "changed_files": 0 + } +} +``` + +--- + +## Related Pinpoints + +- **#288** — error-envelope stdout emission contract +- **#266** — typed-error-kind taxonomy +- **#168c** — `--output-format json` routes error envelopes to stdout +- **#247** — JSON envelope field preservation (hint / help text)