* feat(cli): orca search over the agent session index
`orca search <query>` calls PR 5's `aiVault.searchSessions` over the CLI's
existing runtime RPC, against the host `--environment` / `--pairing-code`
selects and no other. `orca search --index-status` calls `aiVault.searchStatus`.
It is the proof the contract works with no panel.
Every flag maps onto a contract field and nothing else: `--scope`, `--fresh`,
`--limit`, `--cursor`, repeatable `--agent` and `--path`, `--since`, `--sort`,
`--debug`, `--json`. No fan-out, no merged output, no `--host`.
One command rather than a `search status` subcommand: the query is a bare
positional, so `orca search status` could not be told apart from searching for
the word "status". `--status` is unavailable because `orchestration task-list
--status <state>` already owns the name as a valued flag.
No new runtime capability. PR 5 decided an explicit `method_not_found` refusal
maps to `unavailable/no-service`, so reusing `createSessionSearchClient` gives
an old host a plain "this host runs no session search service" answer at exit 0
instead of a raw JSON-RPC error.
`CommandSpec.repeatableFlags` scopes repeatability per command, because
`--agent` must repeat for search and stay single-valued for `worktree create`.
`help.ts` sat exactly at max-lines, so `skills-command-flag-help.ts` becomes
`command-scoped-flag-help.ts` carrying both tables at the same call-site size.
* refactor(cli): drop the search type assertions main's casting gate now rejects
Main gained a `consistent-type-assertions: never` scan in the changed-code gate
after this branch was cut, and it reported twelve assertions in the new files.
The four in the argument parser were avoidable. `readEnum` now keeps the value
`find` returns, which already carries the narrow type, and the agent filter goes
through an `isAiVaultAgent` predicate over a `Set<string>` instead of widening
the agent tuple.
The test now narrows the printed envelope by shape and re-reads the printed
result through `AiVaultSearchResponseSchema`, so the JSON assertions are checked
rather than claimed, and the flag table is typed so its callback needs no cast.
One assertion is left, for the structural fake client, with the SAFETY rationale
AGENTS.md requires.
* fix(cli): sanitize host strings and scope pre-command repeatable flags
Route every host-supplied string the search formatter prints through the
escape stripper, and resolve the repeatable-flag set from the command
tokens ahead when a flag sits before the command.
* refactor(cli): resolve repeatable flag rules once per command
* fix(cli): clarify session search availability and SSH scope
* feat(cli): hide orca search until the settings toggle ships
`orca search` stays dispatchable but leaves every discovery surface: root
help, group help, unknown-command suggestions, and `agent-context --json`.
`buildAgentContext` did not filter hidden specs, so it also stops leaking
the hidden `terminal stop`.
* feat(cli): make the CLI self-correcting and self-describing for agents
Agents build a generalized model of how CLIs work and apply it to every
tool. When orca diverged — `rm` where git uses `remove` — a reasonable
first guess (`orca worktree remove`) dead-ended on a bare "Unknown
command" with no path forward. This makes the CLI degrade gracefully when
the orca-cli skill isn't loaded in context.
- First-class CommandSpec.aliases, resolved to the canonical path before
dispatch (no new handler registrations). `worktree remove`/`delete` now
resolve to `rm`; the ad-hoc `terminal focus` duplicate spec/handler is
migrated onto the mechanism.
- Did-you-mean suggestions on unknown commands and unknown flags, ranked
by edit distance over the live registry, surfaced in both stderr and
--json error.data (reusing the existing nextSteps channel).
- `orca agent-context [--json]`: a versioned, machine-readable dump of the
command schema. Pure local read (no RPC), so it works over SSH and when
the app isn't running.
- CI guards: specs<->handlers parity, and a vocabulary policy that fails
on new off-policy deletion/read verbs (existing ones grandfathered).
* Address PR review feedback (#6303)
- agent-context now emits each command's effective flag set (globals +
conditional --page), not just allowedFlags, so the schema no longer
under-reports --json/--help. Shared as effectiveAllowedFlags() between
validation and the schema.
- Collision check now covers alias paths too, so a duplicate alias that
would silently shadow a real command fails the build.
* fix(cli): harden agent recovery and introspection
Co-authored-by: Orca <help@stably.ai>
---------
Co-authored-by: Jinwoo-H <jinwoo0825@gmail.com>
Co-authored-by: Orca <help@stably.ai>
Jinwoo Hong
