mirror of https://github.com/stablyai/orca.git synced 2026-10-30 08:37:49 +00:00

Files

T

Jinwoo Hong fb322046e8 skills: rewrite and trim the seven non-orchestration guides (#19128 )

* skills: rewrite the seven non-orchestration guides to one outcome-first standard

Every guide leads with Result / Done / Safe failure, states conditions instead of case lists, keeps one done bar and one autonomy envelope, and loads references at the point of use via `skills get <topic> --full`. orca-cli drops from 424 to 260 always-loaded lines with three references; orca-per-workspace-env from 794 to 397 with five.

Defects fixed in shipped guides: `emulator camera` (no such command), iOS `permissions` (backend refuses it), Android pane described as in development, `relayGracePeriodSeconds: 0` documented as immediate teardown (it is unbounded), doctor `ok: true` hiding `warn`, an SSH exemplar setting both `jumpHost` and `proxyCommand`, a provisioned-root fetch from `origin`, and the Linear unconfirmed-write rule keyed on four verbs when ten emit it.

The resolver ladder, placeholder rule, and older-binary fallback shared by every installable SKILL.md now come from one skill-stubs/_shared/cli-resolution.md fragment composed by the generator, which also bundles per-guide references into --full. New guards: every ORCA invocation and flag resolves against COMMAND_SPECS, descriptions carry no angle-bracket tokens, reference routing is checked both ways, and an always-loaded size ratchet (300 lines) that guides may leave but never join.

* skills: address review on the SSH recipe and the parity guard

- ssh-host create script: route the bootstrap ssh through the chosen jump host or proxy command, refuse both at once, use StrictHostKeyChecking=accept-new instead of a blind ssh-keyscan append, and pass gh_token/project_root/repo_url/repo_ref to the remote bash via printf %q so a quote in a value cannot break out of the command.
- per-workspace-env envelope: the step-10 workspace test the user asked for is no longer forbidden by the same paragraph.
- linear guides: name the full verb, ORCA linear list-issues.
- parity guard: a prefix reference such as ORCA linear --help or ORCA emulator --webcam now has its flags checked against every command under that prefix; only an exact path or an explicit ... was checked before.

* skills: tighten prose in the seven rewritten guides

Shorter outcome spines, one idea per sentence, no restated rationale after a rule. No rule, command, or pinned phrase changes; 47 net lines fewer across the guides and references.

* skills: route orca-cli and per-workspace-env gates through --reference

Both guides told agents to load --full at a gate because the per-reference
selector did not exist when they were written. Now that main serves
`skills get <topic> --reference references/<file>.md`, load only the
named file and keep --full as the fallback for an older CLI, matching the
orchestration kernel.

* skills: drop outcome-spine boilerplate from the CLI-wrapper guides

The Result/Done/Safe-failure preambles and Next Action closers restated
rules the body already carries. Agents stop fine without them, and for
a CLI wrapper the command surface is the guide. Keeps the one substantive
rule computer-use's Done block added (never report unverified as success)
inside Action Rules. orchestration and per-workspace-env keep theirs:
those are multi-step workflows where the done bar is load-bearing.

(cherry picked from commit 44a74baf73)

* skills: trim the guides and stubs to what agents actually need

- Drop the Result/Done/Safe-failure preambles and Next Action closers from
  the six CLI-wrapper guides; the one substantive rule (never report an
  unverified computer-use action as success) moves into Action Rules.
- Drop the 'guide may be stale, trust --help' lines: the guide is served by
  the binary that runs the commands, so it cannot be stale relative to it.
- Drop the status --json / open --json preflight from every guide; the stub
  no-guessing paragraph now says to start Orca only when a command reports
  it is not running.
- Cut the ORCA placeholder paragraph in each guide to one line that points
  back at the stub's resolution.
- Trim the orchestration, orca-cli, and computer-use descriptions to trigger
  phrases plus one line of scope.
- Remove the older-binary fallback section from every stub (and its two
  shared blocks); a binary without skills get gets one sentence.
- Remove the guide size ratchet test.

* skills: apply independent review cleanup

* skills: clarify guide loading and Linear command discovery

* skills: harden environment recipe examples

* test: complete branch rename journal doubles

* skills: clarify custom Codex launch and refresh model example

* test: deduplicate journal fix now present on main

2026-09-07 00:03:48 -04:00

7.4 KiB

Raw Blame History

name, description, license

name	description	license
orca-emulator-android	Android device and emulator control from inside Orca over adb, with the live device view in Orca's emulator pane. Use when driving an adb-connected emulator or phone on Windows, Linux, or macOS: booting AVDs, taps, swipes, typing, hardware buttons, rotation, app install and launch, runtime permissions, the accessibility tree, and logcat. For an iOS simulator use the iOS emulator skill; build the APK with Gradle first.	Apache-2.0

Orca Emulator (Android)

ORCA is a placeholder for the executable you resolved in the stub; substitute it before running.

Command surface

The Android backend shells out to the Android SDK (adb, emulator, avdmanager) that Android Studio installs, so it runs on Windows, Linux, and macOS. Input uses adb shell input, with no extra streaming server.

ORCA emulator --help lists the wrapped verbs. Anything else goes through ORCA emulator exec --command "<adb shell command>", which runs adb -s <serial> shell <command> with the string unvalidated.

install, launch, permissions, and logcat are Android-only and fail against an iOS device with emulator_unsupported. tap, type, gesture, button, rotate, ax, and exec work on both backends, with backend-specific output for ax — a uiautomator node tree on Android, a serve-sim node tree on iOS.

Camera and sensor injection are not wrapped; Android virtual-scene is out of scope. Device control is local to the host that owns the SDK, so remote and SSH device control is out of scope.

Prerequisites

Android Studio or the Android SDK installed, with ANDROID_HOME or ANDROID_SDK_ROOT set. Orca also checks the per-OS default location (%LOCALAPPDATA%\Android\Sdk, ~/Library/Android/sdk, ~/Android/Sdk).
adb and emulator on the SDK path, plus at least one AVD (Android Studio ▸ Device Manager) or a connected device with USB debugging.
A booted, adb-visible device before any input or capability command. A shutdown AVD is listed with state: shutdown and must be started first, by ORCA emulator attach, Android Studio, or emulator @<avd>.

Orca returns a clear message when the SDK is missing (Android SDK not found. Install Android Studio and set ANDROID_HOME.).

Operations

Use --json for agent-driven calls. Unqualified commands target the worktree's active device.

Goal	Command	Constraint
List devices + AVDs	`ORCA emulator devices --json`	Every backend's devices with a platform column, booted and shutdown.
Attach / make active	`ORCA emulator attach <avd-name-or-serial> --json`	Given an AVD name, boots it first. Makes the device active for the worktree.
Single tap	`ORCA emulator tap <x> <y> --json`	Normalized 0..1 coordinates.
Swipe / gesture	`ORCA emulator gesture '<json>' --json`	adb approximates the path by its endpoints, first point to last.
Type text	`ORCA emulator type "user@example.com" --json`	US-ASCII, spaces handled, no newlines.
Hardware button	`ORCA emulator button back --json`	`home`, `back`, `recents`, `power`, `volume_up`, `volume_down`.
Rotate	`ORCA emulator rotate landscape_left --json`	Sets `user_rotation` and disables auto-rotate.
Install an APK	`ORCA emulator install ./app-debug.apk --reinstall --json`	`--reinstall` passes `-r`.
Launch an app	`ORCA emulator launch com.acme.app --activity .MainActivity --json`	Omit `--activity` to launch the default LAUNCHER activity.
Runtime permission	`ORCA emulator permissions grant com.acme.app android.permission.CAMERA --json`	Positional order is `<grant\|revoke> <package> <permission>`; `reset` takes no positionals and clears all runtime grants.
Accessibility tree	`ORCA emulator ax --json`	`uiautomator dump` parsed to a node tree.
Logcat (one-shot)	`ORCA emulator logcat --lines 200 --json`	Dumps recent lines, parsed to entries.
Raw adb shell	`ORCA emulator exec --command "getprop ro.build.version.sdk" --json`	Runs `adb -s <serial> shell <command>`.
Stop the helper	`ORCA emulator kill --json`	Leaves the device booted.
Stop and power off	`ORCA emulator shutdown --json`	Stops the helper and shuts the device down.

Targeting

attach, or opening the emulator pane, makes one device active per worktree, and unqualified commands target it. Pass a selector only to override that or reach a second device.

--device <serial> such as emulator-5554, from ORCA emulator devices. An AVD name resolves only once that AVD is booted.
--emulator <id> is an alternative spelling of --device: the bridge resolves both through the same device lookup.
--worktree id:<fullWorktreeId> or --worktree active. The full id is the exact <repo-id>::<path> value returned by ORCA worktree list --json; a bare repo id is not valid here.
--worktree all drops worktree scoping on every verb, not only on listing, so a mutating command passed all runs unscoped. Use it only for listing.
ORCA emulator devices is global and lists every backend; the other verbs route to the backend that owns the resolved device.

Constraints

All coordinates are normalized 0..1 with a top-left origin, never pixels. Orca scales them to the device's live resolution.
Prefer tap over gesture for a single tap.
type uses adb shell input text: US-ASCII only, spaces handled, newlines not. Use the app UI directly for unicode-heavy input.
gesture is a straight swipe between the first and last point, so it fits scrolling and swiping but not a true multi-touch path.
Run kill when you are done. A helper left running holds the device until Orca quits.

Examples

ORCA emulator devices --json
ORCA emulator attach emulator-5554 --json
ORCA emulator tap 0.5 0.85 --json
ORCA emulator type "hello world" --json
ORCA emulator button recents --json
ORCA emulator install ./app-debug.apk --reinstall --json
ORCA emulator launch com.acme.app --json
ORCA emulator permissions grant com.acme.app android.permission.CAMERA --json
ORCA emulator ax --json
ORCA emulator logcat --lines 100 --json
ORCA emulator kill --json

See also: orca-emulator for iOS simulators, orca-cli for terminals, worktrees, and the built-in browser, and computer-use for desktop UI outside the emulator.

7.4 KiB Raw Blame History