[Other]: `terminal read --help` does not document the `--json` result schema
- Dominant language
- TypeScript
- Stars
- 72.1k
- Forks
- 4.7k
- Avg merge
- 14h 54m
- Merged PRs (30d)
- 520
Description
Short summary: the `--json` result schema for `terminal read` is undocumented; consumers have to guess the field names.
`orca terminal read --help` documents only the input flags `--terminal` / `--cursor` / `--limit` / `--json`. It does not describe the structure of the `--json` result at all.
The actual shape (the `RuntimeTerminalRead` type in `src/shared/runtime-types.ts`, wrapped by the handler as `{ terminal: RuntimeTerminalRead }`) is:
result.terminal = {
handle: string
status: RuntimeTerminalState
tail: string[]
truncated: boolean
limited?: boolean
oldestCursor?: string
nextCursor: string | null // paging cursor — pass to the next --cursor
latestCursor?: string
returnedLineCount?: number
}
I spent a diagnostic cycle concluding a dispatched prompt "never arrived" because I read the wrong field — the prompt had arrived, the agent was just still spinning. The `--cursor` paging workflow in particular depends on `nextCursor` (distinct from `latestCursor`), which is not surfaced anywhere in `--help`.
**What would help**
Document the `result.terminal.*` schema in `terminal read --help`, with at least: `status`, `tail[]`, `truncated`, `limited`, `oldestCursor` / `nextCursor` / `latestCursor` (and which one drives `--cursor` paging), and `returnedLineCount`. Today the only place these fields are surfaced is the human formatter in `src/cli/terminal-format.ts`, as loose `cursor:` / `latest cursor:` text lines.
Contributor guide
Assessment
This issue has not been assessed yet.