mirror of
https://github.com/stablyai/orca.git
synced 2026-10-07 16:02:29 +00:00
Brennan Benson
8dc16a7df0
* fix(native-chat): a host admits structured sessions by client capability, not its own chat setting A host's experimentalStructuredNativeChat decided whether any paired client could reach agentSession.* at all, and whether session.tabs.* showed it structured tabs. That setting is the host user's own launch preference: whether a new agent opens as a chat or a terminal is decided by whoever launches it. Using it as admission control meant a client whose own preference was "structured chat" was refused on a host whose preference was "terminal", and chats opened while the setting was on were withheld from mobile once it was turned off. The gate now asks one thing: did the client advertise agent-session.structured.v1 (in-process callers negotiate nothing and are always admitted). Tab projection and restore follow the same rule. With the setting no longer gating anything, the separate cleanup gate (close, cancel, unsubscribe, release), which existed only so those kept working after the setting was switched off, is identical to the main gate and is folded into it. The settings listener that republished tabs when the setting changed is removed, since projection no longer depends on it. The host setting still picks the default for launches that start on the host itself (agent.launch from mobile, orchestration worker-start). * fix(native-chat): the desktop declares structured chat support to paired hosts The desktop renderer advertised agent-session.structured.v1 (and the Claude, turn-item and background-task capabilities that go with it) to its own main process but not to a paired Orca server. The server therefore refused every agentSession.* call from the desktop and stripped structured chat tabs out of the tab list it published to it, so a structured chat running on a paired server never appeared on the desktop, even though the renderer already mirrors a host's agent-session tabs and drives each one against the server that owns its workspace. The same renderer reads structured chats on either host, so the remote Electron list now carries the same structured-session capabilities as the local one, and the capability test pins that nothing is advertised only locally. * feat(native-chat): open structured chats on the paired server that owns the workspace With the structured-chat default on, an agent launched in a workspace that lives on a paired Orca server always opened as a terminal (or the terminal-backed chat view). Three things kept it off the structured path: the launch check refused every host but this machine, a remote workspace was handed to the host-published terminal path before the structured route was even considered, and the structured launch pipeline sent create and every follow-up call to this machine's runtime. A workspace's owning runtime is fixed, so the pipeline now derives it from the workspace instead of assuming this machine (structured-agent-session-owner.ts, the same derivation the chat pane already uses to read a session). The launch intent carries that target; the pre-create support check, create, the publication check and fence read, the launch prompt send, held option picks, the "focus this chat" marker, the placeholder tab's host, and tab close/purge all use it. The launch check now accepts a paired server and asks that server's own capabilities (read from the status the client already cached for it) rather than this machine's. An SSH workspace stays terminal-backed: no Orca runtime runs there. The host still answers createSupport before anything is created, so an older server that refuses shows the failure in the chat tab. A chat the user closed before its create landed is now also retired on the paired server when it publishes, as the local sync already does. Orchestration workers placed on another runtime are unchanged: federation creates terminal agents only. * fix(native-chat): negotiate client-chosen launch mode so released phones and old servers keep terminals Hosts advertise agent-session.structured.client-launch-mode.v1: they admit structured sessions by client capability alone. A remote client that does not advertise it (phones released before agent.launch) asks createSupport to pick the launch mode, so the host keeps answering that with its own setting, exactly as before. Cleanup methods keep their own named gate so a future admission condition cannot make close or cancel refusable. * refactor(runtime): keep the Electron client capability list in its own module protocol-version.ts is at its line budget; the list is what the desktop advertises to paired hosts, not the host's own contract. * fix(native-chat): the desktop declares it picks each launch mode itself Paired hosts and the desktop's own main process then answer createSupport by the workspace rather than by their own chat setting. * fix(native-chat): pin each structured chat to the host it was launched on - Route: a paired server opens a chat only when it advertises the client-chosen launch mode; an older server keeps its terminal. Its capabilities come from the store's host status, not the compatibility cache that is empty after boot or reconnect. - A launch command override is this machine's: the route applies it only locally, and a host's createSupport refuses on its own override. - The owning host is resolved once, from the same value the route used, and carried on the launch intent, its persisted record (legacy records load as local), the provisional tab and every mirrored chat tab. Close, purge, retry and reload read it instead of re-deriving it from a worktree id two hosts can share; an owner that cannot be named refuses. - Cancellation tombstones record their host: only that host's authoritative inventory retires one, restored cleanup closes it there, and a paired host's tombstone expires after 30 days if it never answers. - A paired server's frame settles launches it published, as the local inventory already does for this machine. * fix(native-chat): a paired server that declines a chat opens its terminal instead createSupport only reads, so both of its non-answers are settled before anything is created: - A paired server that answers it cannot run the chat (a WSL repo, a Claude account mismatch, its own launch command override) closes the chat tab and opens the terminal the route would have chosen, with a notice saying why. This machine's own decline stays a failed chat. - A host that could not be asked closes the chat tab and leaves one failure toast, instead of a lingering "could not confirm" chat. * test(native-chat): a provisional chat carries its launch's host and hands pre-create failures on * chore(native-chat): justify the two type assertions this change's lines touch * test(native-chat): state why each staged test fixture is cast * fix(native-chat): chats that already exist keep showing whatever the chat setting says The structured chat setting decides only what new agents open as. With it off, this machine's structured chats used to be hidden while the host, which no longer reads the setting, still reported them to the workspace activation gate, so a workspace holding only a chat opened empty. The local chat mirror and its startup restore now run whatever the setting says, the continue-after-restart offer follows the chats that exist, and the setting's copy says it applies to new agents. * fix(native-chat): the browser client keeps its host terminal on paired servers A browser client whose own preferences turn structured chat on took the structured route for every paired-server workspace, but its handshake never says it reads structured sessions, so the server refused the chat and the user got a failed chat tab where a host terminal used to open. The route for a paired host now also asks what this client advertises to it: the desktop's list does, the browser client's does not. Its handshake list is now a named constant the route reads, so the two cannot drift. The chat setting's copy now says it runs on paired Orca servers too; WSL and SSH hosts still use terminal chat. * fix(native-chat): a retried launch a paired server declines opens its terminal too A launch restored after a reload settles only through its Retry, so a declining paired server left a failed chat there while a first launch got the server's terminal and a notice. The chat's Retry now hands the same pre-create failures to the same replacement, carrying the prompt the launch had staged. * refactor(native-chat): a paired host's cancelled-chat record ends on its 30-day TTL The paired census re-read a host's whole inventory after every authoritative frame to retire tombstones, and a tombstone restored after a reload needed a second such frame, so in practice it retired nothing. A tombstone guards a random session id and is inert once stale; the chat is already closed on its host whenever a frame shows it. The census, its trigger in the mirror layer and its cleanup are removed; the owner-scoped tombstones, close-on-sight, the TTL and publication marking from frames stay. * fix(native-chat): a chat's pane and status read from the host recorded on its tab The chat pane and its sidebar status still derived the host from the workspace id, which two hosts can share; a paired chat in a non-active same-id workspace was read from this machine. Both now read the owner stamped on the tab, as close, purge and publication already do. * fix(native-chat): "Resume in chat" follows the terminal resume's host rule Agent Session History offered "Resume in chat" for a conversation recorded on this machine into a paired server's workspace, where its transcript does not exist. A chat now resumes a conversation only on the host that recorded it, as the terminal resume does, and that host is the one asked whether it can resume history. * fix(native-chat): the chat setting says older paired servers keep terminal chat * test(native-chat): pin that a host advertises the client-chosen launch mode * fix(native-chat): mirror this machine's chats only where it holds them Round 1 ran the local chat mirror for everyone so existing chats show whatever the setting says. That gave every desktop a permanent session-tabs listener, which turns on the runtime's phone replication paths, plus two full session-tab censuses at startup, and made the browser client mirror its remote host a second time. The runtime now says whether it holds structured chats: its structured host is built only when saved chats were restored at startup or a client created one here, and it announces the moment one is built. The mirror, the startup restore and the continue-after-restart offer run only when the setting launches chats or the host holds some, and never in the browser client. A chat a paired client creates here with the setting off still appears at once. The chat behaviour settings show wherever chats exist, and the setting's copy says it picks what new agents open as. The toggle-off teardown this made dead is removed. * test(native-chat): route a paired-server launch over the capability lists both sides really advertise * test(native-chat): record install listeners without a cast * fix(native-chat): a paired server admits a chat before any of it exists here The desktop opened a paired server's chat tab, launch record, queued prompt and focus intent before asking the server, so a "no" needed a replacement that undid and redid all of it, and every piece it missed was a bug: the workspace deselected, the caller told "failed" while a terminal ran its prompt, the caller's arguments and other queued prompts lost, and a create whose reply was lost treated as never sent. A paired launch now asks the server first and commits nothing until it answers. Admitted opens the chat as before. Declined runs the caller's own launch as the server's terminal, with the existing notice (a resume fails instead, having no terminal equivalent). Unreachable opens nothing and names the server in one toast. The new-tab launcher reports the host's surface for paired workspaces, as it did before paired chats, with the prompt delivery of whichever surface got the prompt. The replacement and its error classes are gone, and the probe inside a launch is back to its old meaning: a "no" is a failed chat with Retry, and no answer leaves "Could not confirm" with Retry and the prompt kept, here as on this machine. * fix(native-chat): mirror this machine's chats only once it holds one, not once its host is built Session history, resume preparation, terminal resume commands and replay-safe phone launches all build the structured host for users who never had a chat, which turned on the chat mirror and the structured-only settings rows until the next restart. The signal is now derived from the host's records (or a records file still owed its import) and pushed when the first chat is restored or created. A throwing listener no longer fails the install that fired it. * fix(native-chat): a fork's reveal never seeds a terminal beside the surface the launcher opens Forking into a paired-server workspace revealed it as if nothing would open there, so the reveal created a blank host terminal beside the forked chat (and beside a forked agent terminal on main). The launcher always opens the fork's surface itself, so the reveal now says so for every surface, as the fix-checks launch already does. * fix(native-chat): a declined direct launch keeps the caller's CLI args; an unreachable resume toasts once When a paired server declines a "Fix checks" chat in a new workspace, the terminal that opens instead now carries the recipe's saved CLI arguments, launch platform and launch source, as the terminal route did. "Resume in chat" to a server that cannot be reached showed the admission's "Could not reach" toast and the vault's generic one; the admission marks its failure notified and the vault adds nothing. * fix(native-chat): a declined background create opens its terminal without switching workspaces Since #23974 a worktree create the user moved away from must not pull them onto the new workspace. When a paired server declined that create's chat, the fallback terminal opened as a new agent tab, whose host create selects the workspace. The create now opens its own agent terminal the way main's background branch does: in place from the request's startup plan (so its CLI args carry), without selecting the workspace. A create the user is still watching keeps the new-tab fallback. * test(native-chat): name the launch's host in main's new outbox fence test Main's new staging-failure test calls settleStructuredAgentLaunchPrompt without the target this PR made required; it is a local launch, as in the sibling tests. * fix(native-chat): a paired server's new chat shows no model until the server reports the one it started A chat on a paired server starts with the server's saved model and options, but the picker showed this desktop's saved selection (or the catalog default) until the server reported a model, and a pick made in that window was remembered on the server under that guessed model. A paired launch now carries no desktop seed, and until the server reports its model the picker names no model and takes no picks. Local chats are unchanged. * test(native-chat): seed the paired repo without a cast The repo literal already satisfies Repo, so the changed-lines cast gate has nothing to excuse. * feat(native-chat): createSupport reports the saved selection a new chat on this host starts with A chat on a paired server starts with the server's saved model and options, which the desktop could not read, so its picker showed a guess. createSupport's answer, which the desktop already waits for before a paired launch, now also carries that seed as a new optional field (older clients ignore it). Create and createSupport read it through one resolver so they cannot drift. * fix(native-chat): a paired server's new chat shows the selection the server will start it with The paired server now names its saved model and options in the admission answer the desktop already waits for. That seed goes into the launch intent and its persisted record, so the picker shows the server's model at once, stays pickable like a local chat, and remembers picks on the server under that model; a reload shows the same. The locked picker remains only for a server too old to name a seed. Also moves host admission and launch-outcome tracking into their own modules: the latest main merge left structured-agent-session-launch.ts over the max-lines limit. * test(native-chat): expect the launch intent's new seed argument in exact-call assertions * refactor(protocol): move the Electron remote client capability list into its own module Merging main left protocol-version.ts one line over the max-lines limit on this branch. The list of capabilities the desktop advertises to a paired host moves, unchanged, into electron-remote-runtime-client-capabilities.ts, the module the next PR in the stack already uses for it; importers point there. * fix(native-chat): a paired chat with no saved server model is pickable; Retry shows the server's current seed A server whose user never saved a chat model sends no seed, and the desktop showed a locked, model-only picker for it, although that is the common case: no server that can admit a paired chat predates the seed field. Such a chat now behaves like a local chat with no saved model: the CLI default, pickable. The lock and its snapshot helper are gone. Retry kept the first admission's seed while the create probe, which already runs on every attempt, reported the server's current one and dropped it. The probe's seed now replaces a paired launch's seed and the picker's, so a retried chat shows what its create will run. * test(cross-version): stub the launch seed resolver createSupport now reads * test(protocol): pin the desktop capability divergence against what a paired server receives Every paired transport sends the shared remote base plus the Electron list, so the divergence test now compares that union with the renderer's local list instead of the declared Electron list. A capability added only to the shared base can no longer slip past it. The two base-only capabilities it surfaced are recorded: skills.install-result.v2 has no local caller; the authoritative-inventory label is read by the local tabs sync but dropped by main, and is marked unsettled. The turn-item and both background-task-stop capabilities were already sent through the shared base, so the Electron list no longer repeats them. The wire set is unchanged; this PR's real change on the wire is structured.v1, the Claude structured capability and the client launch-mode capability. * fix(native-chat): the desktop tells its own host it picks each launch mode, so retrying an existing chat works with the setting off * docs(native-chat): name the real exit for the released-phone createSupport rule * fix(native-chat): the route reads the capabilities a paired host actually receives The renderer decided whether a paired host would admit a chat from the desktop's Electron list, but every desktop transport sends that list plus the shared remote base. They agreed only because the route's checks happened to sit in both. The route input is now built with the same remoteRuntimeClientCapabilities the transports use (the browser client already sends its list as is), and a test pins each against the real handshake. * test(cross-version): a released client still gets the host-setting createSupport answer; a launch-mode client gets supported plus the seed * test(native-chat): let main's child-records test resolve each chat's owner Main's new test mocks worktree-runtime-owner with only the runtime environment id, but the status projection in this PR also resolves each structured chat's owner from the worktree. The mock keeps the module's real exports and overrides only what the test pins. * fix(deps): take #24204's lockfile that the merge reverted * test(native-chat): let the Codex child-approval e2e unit test resolve each chat's owner Its worktree-runtime-owner mock exported only the runtime environment id, but this PR's status projection also resolves each structured chat's owner from the worktree. The mock now keeps the module's real exports and overrides only that id, as structured-child-records-switch does. * test(native-chat): move the close-race launch cases into their own file Merging main added launch tests on both sides and took structured-agent-session-launch.test.ts past the 800-line limit. The three cases where a tab close races a launch move to structured-agent-session-launch-close-race.test.ts, with the same setup the other split launch suites copy.
Orca
中文 · 日本語 · 한국어 · Español · Français · Português
The AI Orchestrator for 100x builders.
Run Codex, ClaudeCode, OpenCode or Pi side-by-side — each in its own worktree, tracked in one place.
Download Orca
Features
Mobile CompanionMonitor and steer your agents from your phone — get notified when an agent finishes and send follow-ups from anywhere. |
 |
Parallel WorktreesFan one prompt across five agents, each in its own isolated git worktree — compare the results and merge the winner. |
 |
Terminal SplitsGhostty-class terminals with WebGL rendering, infinite splits, and scrollback that survives restarts. |
 |
Design ModeClick any UI element in a real Chromium window to send its HTML, CSS, and a cropped screenshot straight into your agent's prompt. |
 |
GitHub & Linear, NativeBrowse PRs, issues, and project boards in-app — open a worktree from any task and review without a context switch. |
 |
SSH WorktreesRun agents on a beefy remote box with full file editing, git, and terminals — auto-reconnect and port forwarding included. |
 |
Annotate AI DiffsDrop comments on any diff line and ship them back to the agent — review, edit, and commit without leaving Orca. |
 |
Drag Files to AgentsVS Code's editor with autosave everywhere — drag files or images straight into an agent prompt. |
 |
Orca CLIAgents drive Orca too — script every workflow with |
 |
Also in the box:
- Quick open — Search across worktrees, files, agents, commands, and repo context without leaving your flow.
- Account switcher & usage tracking — See Claude and Codex usage and rate-limit resets, and hot-swap accounts without re-logging in.
- Rich repo previews — Preview Markdown, images, PDFs, and repo docs in the workspace.
- Computer Use — Let agents operate desktop apps and visible UI when a workflow needs real interaction.
- Notifications and unread state — Know when an agent finishes or needs attention, then mark threads unread to come back later.
- And many, many more — we ship daily, so this list is perpetually behind. The changelog is the real feature list.
Supported Agents
Works with any CLI agent — if it runs in a terminal, it runs in Orca.
Claude Code
Codex
Grok
Cursor
GitHub Copilot
Muse
DeepSeek Harness
ZCode
OpenCode
MiMo Code
Amp
OpenClaude
Antigravity
Pi
oh-my-pi
Hermes Agent
Devin
Goose
Auggie
Autohand Code
Charm
Cline
CodeBuddy
Codebuff
Freebuff
Command Code
Continue
Droid
Kilocode
Kimi
Kiro
Mistral Vibe
Qwen Code
Rovo Dev
+ any CLI agent
Install
Desktop — macOS, Windows, Linux
- Download from onOrca.dev
- Or grab a build directly: macOS Apple Silicon · macOS Intel · Windows (.exe) · Linux AppImage · All builds
- Running
orca serveon a headless Linux server? See the headless Linux server guide.
Or via a package manager:
# macOS (Homebrew)
brew install --cask stablyai/orca/orca
# Arch Linux (AUR) — or stably-orca-git to build from source
yay -S stably-orca-bin
Mobile Companion — iOS, Android
Pair with your desktop app to monitor and steer your agents from your phone.
- iOS: Download on the App Store
- Android: Download APK 0.0.50 · Install guide
Community & Support
-
Discord: Join the community on Discord.
-
Twitter / X: Follow @orca_build for updates and announcements.
-
WeChat: Scan to join the Orca community WeChat group 11.
-
Feedback & Ideas: We ship fast. Missing something? Request a new feature.
-
Privacy: See the privacy & telemetry docs for what anonymous usage data Orca collects and how to opt out.
-
Show Support: Star this repo to follow along with our daily ships.
Developing
Want to contribute or run locally? See our CONTRIBUTING.md guide.
The relay that pairs the mobile app with a desktop host is also in this repository under
cloud/, with a separate pnpm workspace and setup guide.
Signed Builds
Windows code signing sponored/provided by SignPath.io, certificate by SignPath Foundation.
License
Orca is free and open source under the MIT License.