mirror of
https://github.com/stablyai/orca.git
synced 2026-09-25 00:02:35 +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
63 lines
3.4 KiB
Markdown
63 lines
3.4 KiB
Markdown
# Artifact and skill publishing commands
|
|
|
|
The publish gate and its recovery are in the guide body. This is the command surface behind it.
|
|
|
|
## Artifacts
|
|
|
|
```text
|
|
ORCA artifacts share <file> --json
|
|
ORCA artifacts update <file> --json
|
|
ORCA artifacts unshare <file> --json
|
|
ORCA artifacts list [--cursor <cursor>] --json
|
|
ORCA artifacts delete <id> --json
|
|
```
|
|
|
|
- `share`, `update`, and `unshare` accept `.html`, `.htm`, `.md`, and `.markdown` files.
|
|
- `share` saves the returned edit token in the active Orca profile and never includes it
|
|
in CLI output. `update` and `unshare` look up that record by the resolved local file
|
|
path, so use the same path and Orca profile that originally shared the file.
|
|
- `list` returns one page of artifacts owned by the signed-in account. If JSON output has
|
|
`nextCursor`, pass it back with `--cursor <cursor>`. `delete <id>` deletes an account-owned
|
|
artifact by the id returned from `list`; it does not need the original local file or its
|
|
edit-token record.
|
|
- Relative HTML assets are not uploaded. Share a self-contained HTML file or use absolute
|
|
asset URLs.
|
|
- If an upload exceeds the CLI transport limit, use the browser upload page as directed
|
|
by the error.
|
|
- For local or staging development, `--api-url <url>` overrides the artifact service;
|
|
`ORCA_ARTIFACTS_API_URL` provides the same override for the session.
|
|
- `ORCA_CLOUD_AUTH_TOKEN` is a development-only authentication override. Prefer the active
|
|
Orca profile's normal PropelAuth session and never expose the token in logs or agent output.
|
|
|
|
## Skill sharing
|
|
|
|
Agents can publish one or more installed skills behind one unlisted link through the
|
|
signed-in Orca account. The user must first grant the separate, default-off permission in
|
|
Settings → Share Skills ("Allow agents and the Orca CLI to publish skill links"). There is
|
|
no CLI or RPC way to grant it. Manual publishing from the reviewed desktop flow remains
|
|
available without this agent permission.
|
|
|
|
```text
|
|
ORCA skills installed --json
|
|
ORCA skills share --skill <selector> [--skill <selector> ...] --bundle-name <name> --json
|
|
```
|
|
|
|
- `skills installed` returns safe discovery IDs and names. It does not expose local skill
|
|
paths in CLI output. Sharing then verifies that each `SKILL.md` declares a portable
|
|
lowercase name containing only letters, numbers, and hyphens.
|
|
- Each `--skill` must be an exact discovery ID or an unambiguous installed-skill name.
|
|
Use IDs when names collide.
|
|
- Multiple `--skill` flags create one bundle and one link. `--all` and arbitrary paths are
|
|
intentionally unsupported; name every skill the user asked to publish.
|
|
- Skill folders can contain scripts, configuration, or credentials. The permission is
|
|
authority, not intent: publish only the skills the user named and never widen the set.
|
|
- A denied command fails with `agent_skill_sharing_disabled`. Do not retry; ask the user to
|
|
enable the switch in the desktop app if they want this action.
|
|
- Orca stages one agent-published bundle at a time per host. If another publish is active,
|
|
wait for it to finish before retrying `agent_skill_sharing_busy`.
|
|
- Run the command in an Orca terminal on the machine that stores the skills. Forwarded WSL,
|
|
SSH, and paired-runtime invocations fail before discovery so Orca cannot read from the
|
|
wrong filesystem.
|
|
- The JSON result contains the unlisted URL and public share/package/version IDs. It never
|
|
includes cloud authentication tokens.
|