feat(chat): run the agent CLI the user installed, and open ACP agents straight into chat
Summary
- Chat harnesses run whichever agent CLI the user has installed, resolved the way a Superset terminal resolves it — nothing is bundled.
- Removes 531 MB of 2.1 GB from the packaged app: the Claude and Codex binaries.
- Fixes the reported outage — every
claude-acpsession failed withsession/new: Internal errorin packaged builds. opencode-acpandgemini-acpregister for the first time, behind version floors that tell a reader what to install.- With the
ACP_CHATflag on, Claude, Codex and Pi open straight into chat from the new-workspace screen, the launcher and preset buttons, instead of starting the CLI and swapping to chat. - The chat sends attachments (+ menu and drag and drop) and has a model / effort picker driven by what each agent advertises over ACP.
Why / Context
Reported on canary 1.33.0-canary.20261002003403: ACP chat errored on every session.
claude-agent-acp locates its CLI with require.resolve, which in a packaged build returns a path inside app.asar. Electron's patched fs makes that path readable, so resolution succeeds and looks normal — but spawn ends at execve, which has no asar awareness: it walks the path, hits app.asar (a regular file), and fails ENOTDIR. The agent reported that as JSON-RPC -32603.
[agent stderr] claude auth status failed: spawn ENOTDIR
[agent →] {"id":2,"error":{"code":-32603,"message":"Internal error","data":{"details":"spawn ENOTDIR"}}}
ASAR -> error: spawnSync …/app.asar/…/claude ENOTDIR
UNPACKED -> error: none status: 0 out: 2.1.284 (Claude Code)
It could not reproduce locally: with no archive, resolve and exec agree. Only packaging splits them, which is why it reached canary.
Making the bundled binary spawnable was the first fix, and it raised the better question: why bundle a CLI at all, when the user keeps one current, terminals already run that one, and this file's own comment says bundling Gemini's ~98 MB is why the ACP registry "fetches on demand rather than shipping agents inside the editor" — while we shipped something 5× larger.
How It Works
Resolution mirrors a terminal: the ~/.superset/bin/<agent> wrapper that setupAgentIntegrations() provisions, else the install on PATH resolved to an absolute path. Both must pass an executable check, so a stale wrapper or a directory cannot shadow a working CLI.
The launch env is buildV2TerminalEnv — the same function every PTY is built from, so the two cannot drift — plus the two things terminals get outside it: resolveDefaultAccountTerminalEnv(db) for the Usage-tab account, and ~/.superset/bin first on PATH, which terminals pick up from the shell bootstrap that a directly spawned agent never runs. That PATH is what puts the superset CLI and the agent wrappers in reach. Ambient ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN are stripped inside the builder, so no path can hand an agent a key instead of the user's own login.
Measured against a terminal, the remaining diff is two keys, both intentional:
MISSING (0): none
DIFFERENT (2):
PATH: terminal=/usr/bin:/bin | agent=~/.superset/bin:/usr/bin:/bin
SUPERSET_TERMINAL_ID: terminal=t | agent=
acpCatalogue.ts is the harness table: binary, args, minVersion, the optional translator (adapter + executableEnv as a pair the type enforces), an upgrade command, and a note recording the evidence for each floor. The floor travels with args because the invocation moves with the version — gemini renamed --experimental-acp to --acp, and sending --acp to a CLI that predates it prints usage and exits 0, which reads as a crash.
| harness | CLI | bundled translator |
|---|---|---|
claude-acp | user's claude via CLAUDE_CODE_EXECUTABLE | adapter JS, 1.6 MB |
codex-acp | user's codex via CODEX_PATH | adapter JS, 1.5 MB |
pi-acp | user's pi via PI_ACP_PI_COMMAND | adapter JS |
gemini-acp | user's gemini --acp | none, speaks ACP itself |
opencode-acp | user's opencode acp | none, speaks ACP itself |
Plumbing. AcpAdapter gains launch, awaited once per session and returning early if dispose lands first; throwing from it surfaces as the session's error notice, which is how a floor reports itself. ClaudeAdapter gains resolveEnv, since its start is synchronous. claude-code moved too — it is the ChatV3Pane default and resolved the same bundled binary through the SDK, so leaving it would have kept 216 MB and left that harness broken in packaged builds.
Chat-first launch, attachments, model picker (ACP_CHAT flag)
Everything in this section is gated on ACP_CHAT. With the flag off, every launch path runs the terminal exactly as before; the new chat UI renders only inside the ACP chat pane (and the Chat v3 pane, behind its own flag).
Opening the chat directly. Before, an agent always started as a pty and the pane switched to chat once the agent reported a session id. Codex reports none until its first prompt, so a Codex terminal never became a chat, and Claude ran twice (CLI, then chat). Now:
useAgentSessionLauncherexposesopenAgentChat, which waits for the flag (useAwaitAcpChatEnabled: up to 2s while PostHog loads, then treats it as off), reads the agent configs withensureQueryData, and adds a chat pane stamped with the agent's preset id.- The new-workspace screen queues prompt, attachments, model and mode through the existing
pendingChatHandoffinstead ofagents.run. - Preset buttons linked to a chat-capable agent go through
openAgentChatfor single-pane plans. - Chat panes are keyed by terminal id. Without the key, a new chat tab reused the previous tab's
AcpChatPaneinstance, whoseattachingref was already true, and stayed on "Starting the agent…".
Attachments over ACP. toAcpPrompt sends images as image blocks when the agent advertises promptCapabilities.image, and everything else as resource_links to the stored file. The host reads attachments via resolveAttachmentPath. The chat composer uploads files from + and drag and drop with attachments.upload before sending, and allows attachment-only messages.
Model picker. The ACP adapter now reads configOptions from session/new and config_option_update, and emits them as SessionState.configOptions. v1 agents key options by id, v2 by configId; the wire schema accepts both. A new setConfigOption command (protocol → runtime → router → session client → useChatSession) calls session/set_config_option, shows the new value immediately, and rolls back with a notice if the agent rejects it. The composer renders model and thought_level options in a new toolbarEnd slot on chat-ui's PromptInput. A model or mode chosen before the chat existed is applied after session/new when the agent offers it; previously the ACP adapter ignored both.
What agents advertise today:
| agent | model | effort |
|---|---|---|
Claude (claude-agent-acp 0.85) | yes | yes (thought_level) |
Codex (codex-acp 2.1) | yes | no (only via its legacy models list, not shown) |
Styling. globals.css now scans packages/chat-ui for Tailwind classes. Desktop never did, so composer utilities used only there were never generated (this was the placeholder/input misalignment).
Manual QA Checklist
Verified here, against a machine with a useful spread of versions
-
claude-acp→ live session through~/.superset/bin/claude -
opencode-acp→ live session; previously could not register at all -
gemini-acp→ gated: "gemini 0.62.0 or newer is needed for chat, and 0.2.1 is installed. Upgrade with: npm i -g @google/gemini-cli@latest" -
codex-acp→ gated, catching a broken install rather than a missing one (localcodexfails with its ownspawn … ENOENT) -
pi-acp→ gated with no floor, so the message asks only for an install - Env parity: 0 keys missing vs
buildV2TerminalEnv; in sandbox mode the firewall CA vars,IS_SANDBOX, and a normalizedLANGall present -
ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKENabsent from the built env (canary value, checked across every value) - A Windows-style base env with
Pathkeeps its search path and gets the bin dir prepended to the same key
Chat-first launch, verified in the dev app over CDP
- New workspace with "hi": chat at ~4s, no xterm at any 500ms sample, Claude replied
- Codex preset opens a chat directly (previously stayed a terminal)
- Two chats opened back to back both start (previously the second hung)
- Model picker lists Claude's models and effort; switching to Sonnet 5.5 is accepted. Codex lists its models
- Picker popover is capped at 384px and scrolls (Claude's list is 865px)
- + menu: "Attach files" opens the file picker; attached files render as pills
- A file attached in the chat reaches the agent end to end
Packaged build — not verified, see Known Limitations
- A
claude-acpand aclaude-codesession both start - ~531 MB smaller; no
@anthropic-ai/claude-agent-sdk-*or@openai/codex*underapp.asar.unpacked - A machine with no agent CLI shows the install message rather than hanging
- Claude account selection from the Usage tab applies to a chat session
Testing
tsc --noEmitclean on@superset/chat-runtime,@superset/host-service,@superset/agent-setupbun testhost-servicesrc/chat-v3+src/terminal: 292 pass / 0 fail; chat-runtime: 159 pass / 2 skip / 0 failsherifclean,biome checkclean- Chat-first work: desktop
tsc --noEmitclean; chat + chat-runtime 208 pass / 0 fail, including adapter tests for v1 config options, optimistic set, and applying (or skipping) the start model;check:i18nclean - Pre-existing failures confirmed unrelated:
src/events/git-watcher.test.tsis 13 pass / 9 fail both with and without this branch (stash-and-compare). The full host-service suite's 46 failures are all watcher / dial-retry / terminal-daemon timing tests.
Design Decisions
- Why
CLAUDE_CODE_EXECUTABLEand friends: each adapter's own documented escape hatch, checked before it resolves anything, so no fork is needed and upgrades keep working. - Why floors gate at session start, not registration: probing a version spawns a process, and registration is synchronous for every harness at mount. Reporting when someone opens a chat puts the message where they are.
- Why
minVersionis not "latest": a floor at latest rejects CLIs that demonstrably work —claude2.1.226 drives the adapter identically to 2.1.286. Latest is also wrong to display: hardcoded it goes stale, so the message names required-vs-found plus the upgrade command. - Why unparseable versions pass: the floors guard against a CLI too old to speak the protocol, not against builds from source.
- Why
SUPERSET_TERMINAL_IDis empty: it is what the wrappers and the notify hook gate on, and chat is not a terminal. A fabricated id would register phantom terminals through the hook endpoint.
Known Limitations
- The packaged build is not verified. Every piece is verified in isolation and the whole flow in dev, but the assembled app needs
bash scripts/release-canary.sh. That is the merge gate. - Hooks do not run for chat sessions.
notify-hook.template.shexits early withoutSUPERSET_TERMINAL_ID, so chimes and task nudges are terminal-only. The account does apply, through the env overlay rather than the wrapper. - Two floors are conservative, not pinned.
gemini-acp0.62.0 andcodex-acp0.160.0 sit at latest-at-authoring because I could not pin when--acplanded or which release addedcodex app-server. The native codex adapter'sMIN_CODEX_VERSIONis 0.143.0, which is where to start. - Windows is unproven. The wrapper is a POSIX bash script and is skipped there, so Windows falls back to PATH discovery with no account overlay and no hooks. Selection is honest — only directly executable extensions are candidates — but untested.
claude-codecan still race host boot. Itsstartis synchronous and cannot await the login-shell snapshot, so a session opened during the probe gets an actionable "chat is still starting up" error instead of waiting. The ACP harnesses await it properly.- Requires an installed CLI. The deliberate trade for 531 MB, matching what terminals already do.
- Not translated.
host-serviceimports Lingui nowhere and is not inENFORCED_DIRS; the adapter's existing notices are plain English too.
Known Limitations (chat-first)
- Effort chosen on the new-workspace screen is not carried into chat.
createSessionhas no effort field; the picker in the chat sets it. - Opening a chat-capable preset can wait up to 2s while PostHog loads flags, since the launch has to know which surface to open.
Follow-ups
- One launch path.
claude-code, the ACP harnesses, and nativecodexeach resolve differently today — nativecodexstill spawns a barecodexon rawprocess.envwith no account overlay and its own floor. One asyncresolveAgentLaunchfeeding every adapter would removeresolveEnv, the placeholdercommand, and the duplicate floors, and would close theclaude-coderace above. - Share the env assembly.
agentEnv.tsrepeats whatterminal.tsdoes aroundbuildV2TerminalEnv; one helper would remove the drift risk. - Diagnosability.
acpAdapter'sonStderr: () => undefineddiscards agent stderr andAcpRpcErrorkeeps onlymessage, dropping thedatathat carriedspawn ENOTDIR. That string would have saved the investigation. - Pin the two conservative floors and lower them.
Risks / Rollout
- Risk: moderate, concentrated in resolution rather than logic. Chat now depends on the user's machine; the failure mode is a clear message at session start, and the env is the same snapshot terminals already trust.
- Rollout: canary first — the packaging step is the only unverified part, and the part that matters.
- Rollback: revert. Nothing persists; the next session resolves the old way. Reverting also restores the original outage, so prefer fixing forward.