EvoScientist/docs/stream-json.md

# `stream-json` output protocol

`EvoSci --output-format stream-json` runs a single-shot (`-p`) session and emits
EvoScientist's **native event stream** as line-delimited JSON (JSONL) on stdout —
one self-describing JSON object per line. This is the integration surface for
programmatic clients that drive EvoScientist headlessly (for example, an agent
runtime that assigns work and renders live progress).

```bash
EvoSci -p "Summarize the attention mechanism into notes.md" \
       --output-format stream-json \
       --auto-mode \
       --workdir /path/to/task
```

## Stream contract

- **stdout is pure JSONL.** Every line is one complete JSON object. Parse it with
  a line reader + `json.loads` per line. Nothing else is written to stdout.
- **stderr carries everything human** — status lines ("Loading agent…"),
  separators, the resume hint, and error panels. A consumer should treat stderr
  as logs, not protocol.
- **Each object has a `type` field** used for dispatch. A consumer that does not
  recognize a `type` should **ignore that line** rather than fail — new event
  types may be added over time, and the protocol is forward-compatible by design.
- **The stream ends with a `done` event** carrying the final response text. On an
  unhandled failure an `error` event is emitted instead/also.
- **Unattended by default.** `stream-json` is headless, so `--auto-mode` is
  enabled automatically: approval and `ask_user` gates are auto-handled and the
  run proceeds straight to its `done` event. Pass `--no-auto-mode` to opt out —
  a human-in-the-loop `interrupt` / `ask_user` is then emitted as a normal event
  and the single-shot run ends right after it (`… → interrupt → done → EOF`). It
  does **not** block waiting for input, but it also stops before finishing the
  task; answering the event requires re-invoking with `--resume` (experimental).

## Event types

Each line is a self-contained JSON object with a `type` field. Most fields are
scalars, but some events carry nested payloads (e.g. `args`, `action_requests`,
`questions`) — parse each line as a full object, not a flat key/value map. The
fields beyond `type` are listed below.

| `type`                 | Fields                                                      | Meaning |
|------------------------|------------------------------------------------------------|---------|
| `thinking`             | `content`, `id`                                            | Model reasoning text |
| `text`                 | `content`                                                 | Assistant output text |
| `tool_call`            | `name`, `args`, `id`                                      | Tool invocation |
| `tool_result`          | `name`, `content`, `success`, `id`                       | Tool result (`id` matches the `tool_call`) |
| `subagent_start`       | `name`, `description`                                     | Sub-agent delegation begins |
| `subagent_tool_call`   | `subagent`, `name`, `args`, `id`                          | Tool call inside a sub-agent |
| `subagent_tool_result` | `subagent`, `name`, `content`, `success`, `id`            | Tool result inside a sub-agent |
| `subagent_text`        | `subagent`, `content`, `instance_id`                      | Text from a sub-agent |
| `subagent_end`         | `name`                                                    | Sub-agent delegation completes |
| `tool_selection`       | `tools`                                                   | Tool-selector middleware picked tools |
| `summarization_start`  | —                                                         | Context summarization begins |
| `summarization`        | `content`                                                 | Context summarization output |
| `usage_stats`          | `input_tokens`, `output_tokens`                           | Token usage |
| `interrupt`            | `interrupt_id`, `action_requests`, `review_configs`      | HITL approval interrupt |
| `ask_user`             | `interrupt_id`, `questions`, `tool_call_id`              | Agent-initiated clarifying question |
| `error`                | `message`                                                | Error during the run |
| `done`                 | `content`, `response`                                     | Final response; end of stream |

## Example transcript

```jsonl
{"type": "thinking", "content": "I should write the notes file.", "id": 0}
{"type": "tool_call", "name": "write_file", "args": {"path": "notes.md", "content": "..."}, "id": "call_1"}
{"type": "tool_result", "name": "write_file", "content": "wrote 412 bytes", "success": true, "id": "call_1"}
{"type": "text", "content": "Done — notes.md now summarizes attention."}
{"type": "usage_stats", "input_tokens": 5123, "output_tokens": 388}
{"type": "done", "content": "Done — notes.md now summarizes attention.", "response": "Done — notes.md now summarizes attention."}
```

## Notes for client implementers

- Read stdout line by line; do not assume a single JSON document.
- Accumulate `text` events for the running assistant message; the terminal
  `done.response` is the authoritative final text.
- `tool_call` / `tool_result` correlate by `id`.
- Token usage may arrive across multiple `usage_stats` events; sum them.
- Treat unknown `type` values and unknown fields as non-fatal.