Files
archived-orca/src/cli/command-scoped-flag-help.ts
T
Kelvin AmoabaandYangNuoCheng c2e6ebbf0b feat(cli): read, message and wait on agent chats with orca chat list/read/send/wait (#40836)
* feat(cli): read and message agent chats with orca chat list/read/send

Carried over from #33115 (squashed onto current main; conflicts with chat rename resolved).

* feat(cli): wait for a chat to settle, read text from stdin, refuse paired hosts

chat send --wait and chat wait poll the history's working flag until the
chat is idle or waits on a question, keeping a queued message pending until
it runs. chat read is one history fetch and returns a cursor. Unattached
and paired-host refusals say what they mean.

* fix(cli): settle a held queued message, skip subagent rows, resolve chat list --worktree

* fix(cli): show chat errors, keep waiting through queue handoffs, return the whole settled turn

* fix(cli): settle any queued message the host will not send, show grouped questions and only answerable prompts

* test(cli): drive chat tests through a real client and fake timers

* fix(cli): describe chat --session, --wait and --state in command help

* fix(cli): report chat wait in chat list's states, reject unknown --state, flag truncated reads

* docs(cli): say chat wait settles on the chat's own turn; no truncated flag on held

* fix(cli): chat rename help asks for a session id, not a handle

---------

Co-authored-by: YangNuoCheng <42427439+YangNuoCheng@users.noreply.github.com>
2026-11-10 22:37:31 +00:00

149 lines
7.3 KiB
TypeScript

// File focus differs from terminal create's shared --focus help.
const FILE_OPEN_FOCUS_HELP =
"--focus Bring the user to the file (switches Orca's window to its worktree)"
const CHAT_SESSION_HELP =
'--session <id> Chat session id or handle from chat list or agent launch'
const COMMAND_SCOPED_FLAG_HELP: Record<string, Record<string, string>> = {
'chat rename': {
session: '--session <id> Chat session id from chat list or agent launch'
},
'chat list': {
state: '--state <state> Only chats in this state: working, blocked, waiting or done'
},
'chat read': { session: CHAT_SESSION_HELP },
'chat send': {
session: CHAT_SESSION_HELP,
wait: '--wait Wait until the chat finishes or needs your answer'
},
'chat wait': { session: CHAT_SESSION_HELP },
'extension reload': {
'extension-id':
'--extension-id <id> Installed unpacked extension ID; also accepted positionally',
path: '--path <folder> Source folder of exactly one installed unpacked extension'
},
'reference add': {
url: '--url <url-or-jira-key> Full review/issue URL or Jira key; use positionals or repeated --url',
'reference-site': '--reference-site <id> Jira site for bare keys; see orca jira connection'
},
'reference remove': {
url: '--url <url> Full review or issue URL; pass all URLs positionally or all as repeated --url',
key: '--key <key> Opaque key from reference list; repeat for several'
},
'computer get-app-state': {
query:
'--query <text> Show only elements whose line contains this text, with their ancestors'
},
'reference find': {
query: '--query <url-or-key> Full URL or native issue key such as STA-1234',
repo: '--repo <selector> Filter by workspace repository membership',
'include-archived': '--include-archived Include archived workspaces',
limit: '--limit <n> Maximum matching workspaces (default 50)'
},
'worktree create': {
branch: '--branch <name> Git branch name to use instead of the prefixed default',
reference:
'--reference <url-or-jira-key> Attach an issue/review URL or Jira key; repeat for several',
'reference-site': '--reference-site <id> Jira site for bare keys; see orca jira connection',
pr: '--pr <number> Linked GitHub pull request number',
'gitlab-issue': '--gitlab-issue <number|url> Linked GitLab issue in the source project',
'gitlab-mr': '--gitlab-mr <number|url> Linked GitLab merge request in the source project'
},
'skills get': {
full: '--full Print the full guide with bundled references',
reference: '--reference <name> Print one bundled reference by name',
references: '--references List the bundled reference names for a topic'
},
'plugin create': {
template: '--template <name> Template to scaffold from (see Usage)',
publisher: '--publisher <name> Repository owner; only for Orca older than 1.4.246',
id: '--id <id> Plugin id (default: the folder name)',
name: '--name <display name> Plugin name shown in Orca'
},
'environment update': {
force: '--force Restart over running terminals instead of deferring the update'
},
'environment recover': {
'accept-changed-state':
'--accept-changed-state Restore the prelaunch snapshot over state a rejected build changed',
yes: '--yes Confirm discarding what the rejected build changed'
},
'environment stop': {
yes: '--yes Confirm stopping the server and unlinking it from this machine'
},
'file open': {
line: '--line <n> Cursor line (1-based)',
column: '--column <n> Cursor column (1-based; requires --line)',
focus: FILE_OPEN_FOCUS_HELP
},
'file diff': {
focus: FILE_OPEN_FOCUS_HELP
},
'file open-changed': {
focus: FILE_OPEN_FOCUS_HELP
},
'skills install': {
agent: '--agent <names> Comma-separated install targets; default is detected agents'
},
'orchestration run-show': {
removed: '--removed List the Tasks, Dispatches and workers removed from this Run',
cursor: '--cursor <cursor> Cursor printed by the previous page of removed work'
},
'worktree set': {
unread: '--unread Mark the workspace unread in the sidebar',
read: '--read Mark the workspace read, clearing the unread dot'
},
search: {
query: '--query <text> Search text; also accepted as the positional argument',
scope: '--scope <corpus> conversation (user and assistant turns) or all (default)',
fresh: '--fresh Wait up to 5s for the host to reconcile its index first',
limit: '--limit <n> Hits per page (default 20, maximum 100)',
cursor: '--cursor <cursor> Opaque cursor printed by the previous page of this search',
agent: '--agent <id> Restrict to one agent; repeat for several',
path: '--path <path> Restrict to an execution-host path; repeat for several',
since: '--since <iso> Only sessions updated at or after this ISO 8601 timestamp',
sort: '--sort <order> relevance (default) or newest',
debug: '--debug Include the planner route the host used',
'index-status': '--index-status Report the index instead of searching'
},
ports: {
all: '--all List every listener on the workspace host, not just this workspace'
},
snapshot: {
interactive:
'--interactive Only interactive elements (buttons, inputs, links); no page text',
compact: '--compact Drop empty structural nodes',
depth: '--depth <n> Limit the tree to n levels',
selector: '--selector <css> Snapshot only the element matching this CSS selector',
urls: '--urls Include link URLs',
delta: '--delta Return only what changed since the last --delta snapshot',
full: '--full Return the whole tree and reset the --delta baseline'
},
screenshot: {
'if-changed':
'--if-changed Skip saving when the page looks the same as the last capture',
annotate: '--annotate Label interactive elements; label [N] is ref @eN'
},
exec: {
command: '--command <text> agent-browser command and arguments, e.g. "get text @e3"'
},
wait: {
selector: '--selector <sel> Wait for an element by ref or CSS selector',
timeout: '--timeout <ms> How long to wait for the condition, or a plain pause',
text: '--text <text> Wait until this text appears on the page',
url: '--url <pattern> Wait until the page URL contains this text or matches a glob',
load: '--load <state> Wait for load or domcontentloaded (networkidle only on quiet pages)',
fn: '--fn <js> Wait until this JavaScript expression is truthy',
state: '--state <state> With --selector, wait for hidden or visible'
},
download: {
selector: '--selector <ref> Element ref or CSS selector of the download link',
path: '--path <path> File path to save the download to'
}
}
export function formatCommandScopedFlagHelp(command: string, flag: string): string | undefined {
return COMMAND_SCOPED_FLAG_HELP[command]?.[flag]
}