From 09dd95d6328475036fe01f24fa81ba4caa5ac83d Mon Sep 17 00:00:00 2001 From: BingZ Date: Wed, 28 Oct 2026 14:46:57 +0800 Subject: [PATCH] docs(cli): document terminal read --json result fields and cursor roles (#13173) `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 --- src/cli/specs/core.ts | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/cli/specs/core.ts b/src/cli/specs/core.ts index 4288e431e69..bc41f53cd4e 100644 --- a/src/cli/specs/core.ts +++ b/src/cli/specs/core.ts @@ -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 --limit .', 'Useful for capturing the response to a command: read before sending, then read --cursor after waiting.' ], examples: [