#12384: feat(cli): add --stream-json flag for live NDJSON streaming

## Summary Add a `--stream-json` flag to `openclaw agent --agent <id> --message <text>` that streams NDJSON events to stdout in real time during an agent run. This enables external frontends to consume live agent events (text deltas, tool calls, thinking/reasoning, lifecycle phases) without polling — particularly useful for **AI SDK's `useChat()` capability** and similar streaming interfaces. Many frontends would want to consume live agent events from within a sandbox, where only way to receive live events out would be the live terminal output stream. This helps with exactly that. For a working example of a Next.js frontend consuming `--stream-json` via AI SDK's `useChat()`, see: https://github.com/kumarabhirup/openclaw-ai-sdk/tree/main/apps/web ### What it does ```bash openclaw agent --agent main --message "Hello" --stream-json ``` Outputs one JSON object per line (NDJSON) as the agent runs: ```jsonl {"event":"agent","runId":"...","stream":"lifecycle","data":{"phase":"start"}} {"event":"agent","runId":"...","stream":"thinking","data":{"delta":"Let me..."}} {"event":"agent","runId":"...","stream":"assistant","data":{"delta":"Hello!"}} {"event":"result","runId":"...","status":"ok","payloads":[{"text":"Hello!"}]} ``` ### Changes - **CLI**: register `--stream-json` option (mutually exclusive with `--json`) - **Gateway path**: new `agentViaGatewayStreamJson()` uses `callGateway`'s new `onEvent` callback to relay each gateway event as an NDJSON line - **Embedded path**: subscribe to `onAgentEvent` bus and emit matching events as NDJSON when `--stream-json` is active - **Reasoning/thinking**: emit reasoning deltas as agent events unconditionally so NDJSON/SSE consumers receive thinking content - **`callGateway`**: add `onEvent` callback option, wired through to `GatewayClient`'s existing event handler - **Tests**: 3 new tests covering gateway streaming, embedded passthrough, and NDJSON line format ## Test plan - [x] `pnpm test -- src/commands/agent-via-gateway.test.ts` — all 6 tests pass (3 existing + 3 new) - [x] `pnpm tsgo` — no type errors - [x] Lint clean — no new warnings <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR adds a `--stream-json` flag to `openclaw agent` to stream live NDJSON events to stdout during an agent run. It does this by (1) adding an `onEvent` callback to `callGateway` so gateway events can be relayed as NDJSON, and (2) subscribing to the embedded agent event bus (`onAgentEvent`) to emit matching NDJSON lines locally. It also changes embedded message handling to emit `<think>` reasoning deltas as agent events unconditionally so streaming consumers can receive them. Main integration points are `src/cli/program/register.agent.ts` (flag registration + `--json` exclusivity), `src/commands/agent-via-gateway.ts` (new streaming gateway path + NDJSON writer), `src/commands/agent.ts` (embedded NDJSON subscription), and `src/gateway/call.ts` (wiring `onEvent` into the gateway client request). <h3>Confidence Score: 2/5</h3> - This PR likely needs fixes before merge due to at least one test-suite breaking issue and stream correctness concerns. - Score is reduced because the modified test file appears to have mismatched closing braces/describe blocks that would break tests, and because the NDJSON streaming path can be corrupted by any other stdout output (especially on errors), which would break downstream consumers relying on valid NDJSON. - src/commands/agent-via-gateway.test.ts, src/commands/agent-via-gateway.ts, src/commands/agent.ts <!-- greptile_other_comments_section --> _{(2/5) Greptile learns from your feedback when you react with thumbs up/down!} <!-- /greptile_comment -->