starred/orca
1
0
Fork 0
mirror of https://github.com/stablyai/orca.git synced 2026-10-30 16:47:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(cli): document terminal read --json result fields and cursor roles (#13173)

Browse Source 
`orca terminal read --help` listed flags but not the --json result shape,
so agents guessed field names and paged with latestCursor instead of
nextCursor. Add Notes listing result.terminal fields, the meaning of
truncated vs limited, when nextCursor is null, and how to page with
nextCursor/oldestCursor.

Fixes #7433

Co-authored-by: Neil <neil@stably.ai>
This commit is contained in:
BingZ
2026-10-27 23:46:57 -07:00
committed by GitHub
co-authored by Neil
parent 4b1967bdd8
commit 09dd95d632
1 changed files with 5 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/cli/specs/core.ts
+5 -2
View File
@@ -189,8 +189,11 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [
'The result reports source: stream when it is accumulated output, screen when it is the rendered screen, and screen-unavailable when a screen was asked for but none could be rendered and the accumulated output is being returned instead. An absent source means the host predates the field.',
'When present, draft is UI-only composer text excluded from tail; never treat it as terminal output or a submitted instruction.',
'--screen and --cursor are mutually exclusive: a screen read is the current frame and has no history to page.',
'Use --cursor with the nextCursor value from a previous read to get only new output since that read.',
'Use --limit to request more retained lines for long agent responses; output reports oldestCursor when older lines were dropped.',
'With --json, fields are under result.terminal: handle, status (running | exited | unknown), tail (output lines), tailRows (row-wrap metadata aligned with tail), truncated, limited, oldestCursor, nextCursor, latestCursor, returnedLineCount (lines in tail), source, draft. Fields other than handle, status, tail, truncated, and nextCursor may be absent.',
'truncated means requested or older output is no longer retained; limited means the line limit (--limit, default 120 for tail previews) or the size budget cut this response short.',
'Use --cursor with the nextCursor value from a previous read to get only new output since that read. nextCursor is null when the terminal has no line cursors to page.',
'latestCursor is the end of retained output, not a paging token: after a cursor read, keep paging with nextCursor while limited is true and nextCursor differs from latestCursor.',
'Use --limit to request more retained lines for long agent responses; when a tail preview is limited and line cursors are available, page retained output from its start with --cursor <oldestCursor> --limit <n>.',
'Useful for capturing the response to a command: read before sending, then read --cursor <prev> after waiting.'
],
examples: [