stablyai / stablyai/orca

[Other]: `terminal read --help` does not document the `--json` result schema

Open
#7,433 0 comments 0 reactions 1 assignee Claimed by @OrcaWin View on GitHub
enhancement
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.