mirror of
https://github.com/stablyai/orca.git
synced 2026-10-30 08:37:49 +00:00
Jinwoo Hong
fb322046e8
* 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
119 lines
7.4 KiB
Markdown
119 lines
7.4 KiB
Markdown
---
|
|
name: orca-emulator-android
|
|
description: >-
|
|
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.
|
|
license: 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
|
|
|
|
```text
|
|
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.
|