Skip to content

fix(orchestration): resolve bare agent ids when launch binary differs - #12177

Closed
octu0 wants to merge 1 commit into
stablyai:mainfrom
octu0:fix/worker-start-agent-id-launch
Closed

octu0 wants to merge 1 commit into
stablyai:mainfrom
octu0:fix/worker-start-agent-id-launch

Conversation

@octu0

@octu0 octu0 commented Aug 3, 2026 •

Copy link
Copy Markdown
Contributor

Summary

orca orchestration worker-start --agent <id> creates a worker terminal with command set to the agent id (e.g. antigravity, cursor). Bare-agent resolution only matched launch binaries (agy, cursor-agent), so agents whose id ≠ binary were treated as raw shell commands:

  • no launchAgent / launchConfig
  • no ORCA_AGENT_LAUNCH_TOKEN (weaker hook attribution)
  • Settings YOLO / default args not applied via the normal startup plan
  • readiness fell back to slow screen scraping → frequent agent_readiness timeouts and runtime_unavailable races (especially Antigravity)

This change accepts an enabled bare TuiAgent id in resolveBareAgentLaunchCommand, so worker-start/federation launches resolve the real launch command the same way as the agent picker (e.g. antigravity → agy --dangerously-skip-permissions with launch metadata).

Agents where id already equals the binary (claude, codex, …) are unchanged. Disabled agents still run as raw commands (same as before for disabled bare binaries).

Current workaround (pre-fix / still useful locally)

Until this lands, operators often paper over the missing antigravity PATH entry with a wrapper, because worker-start literally execs the string antigravity instead of agy:

#!/usr/bin/env bash
exec agy --dangerously-skip-permissions "$@"

(write to /usr/local/bin/antigravity)

What that workaround does and does not fix:

With wrapper only After this PR
worker-start --agent antigravity finds a command on PATH yes (runs wrapper → agy) yes (Orca launches agy directly)
Settings defaults / YOLO via buildAgentStartupPlan no yes
launchAgent + ORCA_AGENT_LAUNCH_TOKEN (hooks) no yes
Same path as UI agent picker no yes

So the wrapper is a local PATH shim, not a substitute for proper agent-id resolution. After this fix, worker-start --agent antigravity should not need /usr/local/bin/antigravity. The wrapper can remain for manual orca terminal create --command antigravity if someone still types the id as a shell command.

Screenshots

No visual change

Testing

  • pnpm lint — passed
  • pnpm typecheck — passed
  • pnpm test — 43520 passed, 81 skipped; 2 failed unrelated to this PR (see Notes)
  • pnpm build — passed
  • Added or updated high-quality tests that would catch regressions, or explained why tests were not needed

New coverage in orca-runtime.test.ts:

  • bare antigravity id → agy + YOLO args + launchAgent + launch token
  • bare cursor id → cursor-agent + YOLO args + launch metadata
  • disabled bare antigravity id stays a raw antigravity command (no agent wrapping)

Targeted: pnpm exec vitest run src/main/runtime/orca-runtime.test.ts -t "bare agent" → 9 passed

AI Review Report

Reviewed the change for orchestration worker-start / federation terminal create paths.

Main risks checked

  • Cross-platform (macOS / Linux / Windows): resolution is string-level before shell quoting; Windows quoting still goes through existing buildAgentStartupPlan / shell helpers. No shortcut, label, or path changes.
  • SSH / remote / local: still uses getTuiAgentLaunchCommand(..., { isRemote }) and the same Settings defaults path as other bare agent creates; remote Windows shell quoting behavior unchanged.
  • Agent compatibility: fixes agents where id ≠ launch binary (antigravity→agy, cursor→cursor-agent, and the same class for kiro, aug, etc.). Agents with id === binary keep matching via the existing launchCmd loop. Multi-token commands (codex exec …) still fail bare match and stay raw shell.
  • Performance: one extra isTuiAgent check on bare creates only; no hot-path render/PTY work.
  • UI quality: N/A (no UI).
  • Security: only enables agent startup wrapping for known enabled TuiAgent ids; does not broaden arbitrary command execution. Disabled agents are not auto-wrapped.

Flagged / verified

  • Confirmed worker-start still passes command: args.agent (id string); fixing resolution is the minimal durable fix vs. only changing the worker topology call site.
  • Confirmed UI picker already used buildAgentStartupPlan({ agent }) and was not broken; this aligns the bare-command path with that behavior.
  • Confirmed the historical /usr/local/bin/antigravity workaround only papered over PATH lookup and does not attach launch metadata — documented above for reviewers who have seen that shim in the wild.

Security Audit

  • Command execution: bare create still only auto-wraps when the entire command string is an enabled agent id or a known launch binary/override. User-authored multi-arg commands remain untouched.
  • No new IPC, auth, secrets, or dependency surface.
  • Path handling: unchanged.
  • Follow-up: none required for this fix. Optional later cleanup: worker-start could pass a structured agent field instead of overloading command, but that is a larger API change and not required once id resolution works.

Notes

  • Unrelated test failures on this machine: src/relay/agent-exec-handler.test.ts (2 tests) failed because the host shell already exports GIT_CONFIG_COUNT=2 / GIT_CONFIG_KEY_*, so the handler ends up with GIT_CONFIG_COUNT=4 while the test expects 2. Not touched by this PR; re-run those tests in a clean env (unset GIT_CONFIG_*) to confirm green. Full suite otherwise: 4074 files passed.

worker-start passes createTerminal command as the agent id (e.g.
antigravity). Bare-command resolution only matched launch binaries
(agy), so those workers skipped Settings defaults, launchAgent, and
ORCA_AGENT_LAUNCH_TOKEN. Accept enabled TuiAgent ids as bare launches.
@coderabbitai

coderabbitai Bot commented Aug 3, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

The runtime now recognizes enabled bare TUI agent identifiers during command resolution. antigravity resolves to agy, and cursor resolves to cursor-agent. The original agent ID, launchAgent, and a launch token are preserved or injected for these launches. Disabled agents continue to use the raw command without launch metadata or tokens. Tests cover both enabled and disabled agent behavior.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly summarizes the main change: resolving bare agent IDs when their launch binaries differ.
Description check ✅ Passed The description covers the required sections, user-visible behavior, testing, review risks, security, platform checks, and unrelated test failures.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1


ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8efb6d30-a794-4870-aa3d-8a75086fdfc1

📥 Commits

Reviewing files that changed from the base of the PR and between bcf7d1d and 031abab.

📒 Files selected for processing (2)
  • src/main/runtime/orca-runtime.test.ts
  • src/main/runtime/orca-runtime.ts

Comment on lines +12757 to +12759
// Why: orchestration worker-start passes command: <agent id>; antigravity's
// binary is `agy`, so matching only launchCmd left this path as a raw shell
// string without launchAgent / launch token.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Reduce this comment to one line.

Keep only the non-obvious reason for the test. The three-line explanation exceeds the TypeScript comment guideline.

As per coding guidelines, comments must be concise, limited to non-obvious information, and preferably one line.

Source: Coding guidelines

@greptile-apps

greptile-apps Bot commented Aug 3, 2026

Copy link
Copy Markdown

Greptile Summary

Fixes resolveBareAgentLaunchCommand so that worker-start --agent <id> correctly resolves agents whose TuiAgent ID differs from their launch binary (e.g. antigravity → agy, cursor → cursor-agent, kiro → kiro-cli chat --tui). Previously only the launch-binary string was compared, leaving these agents as raw shell commands with no launchAgent, ORCA_AGENT_LAUNCH_TOKEN, or Settings-default application.

  • Adds an early-return guard in resolveBareAgentLaunchCommand that matches isTuiAgent(command) && isTuiAgentEnabled(command, ...) before the existing binary-match loop, returning the agent ID so buildAgentStartupPlan can apply the correct launch command, overrides, and env.
  • Disabled agents bypass the early return and fall through to the existing loop (which also skips them), preserving raw-command behaviour for disabled entries.
  • Three new tests cover the antigravity → agy, cursor → cursor-agent, and disabled-antigravity-stays-raw cases.

Confidence Score: 4/5

Safe to merge; the change is small and well-contained, touching only the agent-ID resolution path before any command is actually executed.

The core logic is correct — isTuiAgent is a compile-time allowlist, disabled agents fall through to the existing loop, and all override/platform/env work is delegated to buildAgentStartupPlan unchanged. The subtle ordering concern (the early return now takes priority over cmdOverrides entries that happen to equal another agent's bare ID as a launch-command string) is a real but exceedingly unlikely edge case.

Files Needing Attention: src/main/runtime/orca-runtime.ts — specifically the ordering of the new early-return relative to the cmdOverride loop.

Important Files Changed

Filename Overview
src/main/runtime/orca-runtime.ts Adds an early-return in resolveBareAgentLaunchCommand to match bare TuiAgent IDs before the existing launch-binary loop; correctly gates on isTuiAgentEnabled and defers override/platform logic to buildAgentStartupPlan
src/main/runtime/orca-runtime.test.ts Adds three targeted tests: bare antigravity id resolves to agy + launch metadata, bare cursor id resolves to cursor-agent, and disabled bare antigravity id stays a raw command

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["worker-start --agent id\ne.g. antigravity, cursor"] --> B["resolveBareAgentLaunchCommand"]
    B --> C{"isTuiAgent\ncommand"}
    C -- No --> E{"Loop: command matches\nlaunchCmd or cmdOverride?"}
    C -- Yes --> D{"isTuiAgentEnabled\ncommand, disabled"}
    D -- No --> E
    D -- Yes --> F["Return TuiAgent id\nNEW PATH"]
    E -- Match --> G["Return TuiAgent id\nexisting path"]
    E -- No match --> H["Return null\nraw shell command"]
    F --> I["buildAgentStartupPlan\nresolves launchCmd + overrides\nagentDefaultArgs + env"]
    G --> I
    I --> J["createTerminal\ncommand = real binary\nlaunchAgent = agent id\nORCA_AGENT_LAUNCH_TOKEN set"]
    H --> K["createTerminal\ncommand = raw string\nno launch metadata"]
Loading

Reviews (1): Last reviewed commit: "fix(orchestration): resolve bare agent i..." | Re-trigger Greptile

Comment on lines +1381 to +1383
if (isTuiAgent(command) && isTuiAgentEnabled(command, args.settings.disabledTuiAgents)) {
return command
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Early-return bypasses cmdOverride-as-command matching

The new isTuiAgent check runs before the existing loop that also compares command against each agent's agentCmdOverrides entry. If an operator has ever set agentCmdOverrides['someAgent'] = 'antigravity' (using another agent's bare ID as a custom launch path for that agent), command = 'antigravity' would previously resolve to 'someAgent' via the override branch, but now resolves to 'antigravity' via this early return. In practice this configuration pattern is unlikely (and arguably nonsensical), but the priority shift is undocumented and could surprise anyone who relied on it.

Comment on lines 12734 to 12840
expect(spawnCall?.env?.ORCA_AGENT_LAUNCH_TOKEN).toBeUndefined()
})

it('resolves bare agent ids whose launch binary differs from the id', async () => {
const spawn = vi.fn().mockResolvedValue({ id: 'pty-bg' })
const runtimeStore = {
...store,
getSettings: () => ({
...store.getSettings(),
disabledTuiAgents: [],
agentCmdOverrides: {},
agentDefaultArgs: { antigravity: '--dangerously-skip-permissions' },
agentDefaultEnv: {}
})
}
const runtime = new OrcaRuntimeService(runtimeStore)
runtime.setPtyController({
spawn,
write: () => true,
kill: () => true,
getForegroundProcess: async () => null
})

// Why: orchestration worker-start passes command: <agent id>; antigravity's
// binary is `agy`, so matching only launchCmd left this path as a raw shell
// string without launchAgent / launch token.
await runtime.createTerminal(`path:${TEST_WORKTREE_PATH}`, {
command: 'antigravity',
title: 'worker'
})

const spawnCall = spawn.mock.calls[0]?.[0] as
| { command?: string; env?: Record<string, string>; launchAgent?: string }
| undefined
expect(spawnCall?.command).toBe("agy '--dangerously-skip-permissions'")
expect(spawnCall?.launchAgent).toBe('antigravity')
expect(spawnCall?.env?.ORCA_AGENT_LAUNCH_TOKEN).toMatch(UUID_RE)
})

it('resolves bare cursor agent ids to the cursor-agent launch binary', async () => {
const spawn = vi.fn().mockResolvedValue({ id: 'pty-bg' })
const runtimeStore = {
...store,
getSettings: () => ({
...store.getSettings(),
disabledTuiAgents: [],
agentCmdOverrides: {},
agentDefaultArgs: { cursor: '--yolo' },
agentDefaultEnv: {}
})
}
const runtime = new OrcaRuntimeService(runtimeStore)
runtime.setPtyController({
spawn,
write: () => true,
kill: () => true,
getForegroundProcess: async () => null
})

await runtime.createTerminal(`path:${TEST_WORKTREE_PATH}`, {
command: 'cursor',
title: 'worker'
})

const spawnCall = spawn.mock.calls[0]?.[0] as
| { command?: string; launchAgent?: string; env?: Record<string, string> }
| undefined
expect(spawnCall?.command).toBe("cursor-agent '--yolo'")
expect(spawnCall?.launchAgent).toBe('cursor')
expect(spawnCall?.env?.ORCA_AGENT_LAUNCH_TOKEN).toMatch(UUID_RE)
})

it('keeps disabled bare agent id terminal creates unchanged', async () => {
const spawn = vi.fn().mockResolvedValue({ id: 'pty-bg' })
const runtimeStore = {
...store,
getSettings: () => ({
...store.getSettings(),
disabledTuiAgents: ['antigravity' as const],
agentCmdOverrides: {},
agentDefaultArgs: { antigravity: '--dangerously-skip-permissions' },
agentDefaultEnv: {}
})
}
const runtime = new OrcaRuntimeService(runtimeStore)
runtime.setPtyController({
spawn,
write: () => true,
kill: () => true,
getForegroundProcess: async () => null
})

await runtime.createTerminal(`path:${TEST_WORKTREE_PATH}`, {
command: 'antigravity'
})

const spawnCall = spawn.mock.calls[0]?.[0] as
| { command?: string; env?: Record<string, string>; launchAgent?: string }
| undefined
expect(spawnCall?.command).toBe('antigravity')
expect(spawnCall?.launchAgent).toBeUndefined()
expect(spawnCall?.env?.ORCA_AGENT_LAUNCH_TOKEN).toBeUndefined()
})

it('sends Settings agent defaults through renderer-backed bare agent terminal creates', async () => {
const runtimeStore = {
...store,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 No test for multi-token launchCmd agents resolved via bare ID

The fix unblocks several agents beyond antigravity and cursor — notably kiro (launchCmd: 'kiro-cli chat --tui'), aug (auggie), and command-code (command-code --trust). These are the cases where the old binary-match loop was most broken (multi-token launchCmd made it even harder to accidentally pass the right string via worker-start). A test confirming that command: 'kiro' produces kiro-cli chat --tui ... would close the obvious regression vector for those agents and document the intended behaviour for reviewers of future kiro/aug config changes.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@Jinwoo-H

Jinwoo-H commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

Thanks @octu0 for the careful report, tests, and investigation of the launch-token/default-args gap. I rechecked this against current main and am closing it as superseded by #12148.

Measured topology: current main is 473442865413787443f47ff6e08059ede241624f; this PR remains at 031abab23c8219a97a6bf5bbc4e3a7f8fb3cb2b3, one unique commit from merge-base 0c2893695c5d558b84dfb07d89ddbfdbf1081511, while main is 158 commits ahead. Rebased on current main, the change is 28a7a08d0258328f6ce732e8aa34c03a88f877e4; reverting it at 71ff101c1ab5c70cff9176add347bb68e4cf7990 restores the exact current-main tree (0255335f1c686ff2ec70b03ad2af7e95ff34471f).

Merged #12148 (95c431f5c356d7545aec7f422c43514831b46ebf) already passes explicit startupAgent identity through local, federated, new-worktree, and folder-workspace worker paths. Real Electron/PTy orchestration checks with a PATH-only Cursor fixture, plus focused contract tests, showed current main/revert and the candidate all launch worker-start correctly, so this candidate's resolver branch is unreachable there. Its remaining effect is unsafe to land: it changes user-authored terminal create --command cursor into cursor-agent --yolo with defaults/trust/token side effects, and it takes priority over existing agentCmdOverrides inference.

A current-main reproduction showing worker-start still reaches resolveBareAgentLaunchCommand without explicit startupAgent, or a distinct failing worker topology not covered by #12148, would justify reopening. Thanks again for digging into this and documenting it thoroughly.

@Jinwoo-H Jinwoo-H closed this Aug 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants