main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-ai-agents-dev description: >- Maintainer design notes for Hydrogen's AI agent support on Linux: golden-image vs user installs, auth oracles, how sign-in is driven, the VS Code toolbar and the Manage AIs dialog. Use before touching agent_harness.rs, PanelAiAccounts.svelte or ai-titlebar.js. disable-model-invocation: true

Hydrogen AI agents: how it is built

One record per AI, owned by Hydrogen, drives everything the user sees: the first-landing "Choose your AI" dialog, the Manage AIs dialog, the VS Code toolbar buttons, and the Welcome page line. This skill is the map. The user-facing how-to is hydrogen-ai-agents.

The pieces

piece where job
Provider table + /agents/* routes src-tauri/crates/hydrogen-control/src/agent_harness.rs the truth: detect, oracle, install, login, logout, facts, publish agent-bar.json
Choose your AI / Manage AIs dialog src/lib/components/editor/panels/PanelAiAccounts.svelte (mounted as an overlay by PanelVisualStudioCode) renders /agents/catalog + /agents/facts, drives sign-in
toolbar buttons + AI menu adom-vscode browser/ai-titlebar.js (injected into workbench.html) and extension/src/extension.ts (/ai/* routes on :8821) draws one button per installed AI, opens threads, "Manage AIs" row
golden image the golden image repo, image/bake-in-distro.sh bakes Claude Code + Codex extensions, the claude/codex wrappers, adom-vscode, bootstrap
converge on every workspace hydrogen-bootstrap install.sh sections 4b to 4d first-run flags, wrapper repair, duplicate removal
exec transport adom-vscode POST /exec on :8821 (container_exec) every probe runs through it, never one root-helper exec per probe (on Linux each helper exec is a sudo -n call)

Golden image versus user install

Baked (present on every fresh workspace): the Claude Code and Codex VS Code extensions, the ~/.local/bin/claude and ~/.local/bin/codex wrappers, adom-vscode, adom-theme, the hydrogen-* skills. Installed by the user from Manage AIs: Kimi Code and Antigravity, each as extension + CLI in one click (POST /agents/install {key}; the CLI through the provider's install_cmd). On Linux the extension half runs code-server's own CLI in a clean environment (hydrogen_log::host::CODE_SERVER_CLI, extension_cli_install): from the exec route's VS Code environment it hit the remote-CLI shim, printed garbage and installed nothing ("JSON Parse error" toasts).

Why this split: the two baked AIs are what every Adom user gets signed in on day one, and their extensions are large (235 MB and 620 MB) so baking saves the download. Kimi and Antigravity stay optional; their installs are cheap and their sign-ins need a Google or Kimi account the user may not have.

The no-duplicates rule (John, 2026-09-20)

"I'm trying to achieve no redundancy of code across the vscode extension and the cli/tui."

  • Where the extension ships the CLI (Claude Code: resources/native-binary/claude; Codex: bin/linux-x86_64/codex), the PATH command is a tiny wrapper that resolves the newest extension folder on every run and execs that binary. No second binary, ever.
  • The Claude wrapper exports DISABLE_AUTOUPDATER=1. Without it, Claude Code's own updater (installMethod "native" in ~/.claude.json) downloads a full second binary into ~/.local/share/claude/versions on an interactive launch, even when already current. AdomLapper had four of them (825 MB); arav-rog got one during a sign-in pty.
  • Antigravity's extension downloads its own agy to ~/.gemini/bin/agy. install_cmd and detect_cmd link ~/.local/bin/agy to it and only run the public installer when no copy exists. The first cut always ran the installer and left two identical 214 MB binaries.
  • Kimi's extension ships no CLI, so ~/.kimi-code/bin/kimi (2.x) is the only copy and is legitimate.
  • hydrogen-bootstrap converges every workspace: 4c patches an old wrapper with DISABLE_AUTOUPDATER and deletes orphaned ~/.local/share/claude; 4d removes an npm @openai/codex or @anthropic-ai/claude-code under ~/.local/lib when the extension's binary exists and rewrites the wrapper if it was overwritten or emptied.
  • GET /agents/facts measures all of it in the container (extension folder, CLI kind and bytes, data dirs, and a dupes list) and the dialog's "?" tooltip shows it, so a regression is visible to the user without anyone reading logs.

Desktop apps: the host_app kind (Grok Bot)

Provider.host_app names an Adom Bridge verb prefix (grok). Such a provider has nothing in the workspace: host_app_state asks ab (<prefix>_readiness, <prefix>_status.webhookBound). On Linux ab may not be installed yet (Hydrogen installs it only when a Linux build is published for the account), so a bridge that does not answer is reported as "needs Adom Bridge, which is not running", never as unknown (unknown kept the first-run sign-in check waiting forever). Send bridge verbs with ad::send_verb_timeout (no app field) and treat ab's "Unknown verb" as "bridge not installed". adom-vscode draws nothing for a host app.

Sign-in: detection (the oracles)

Each Provider has an oracle_cmd, a shell command run in the container whose stdout decides "signed in". Rules learned the hard way:

  • Read state, never make a network call. Antigravity's first oracle was agy -p 'ok'; when the account hit Google's 429 quota the dialog showed "Sign in" over a valid session. Now it checks ~/.gemini/antigravity-cli/antigravity-oauth-token for a refresh token.
  • Kimi 2.x keeps [providers."managed:kimi-code".oauth] in config.toml plus credentials/kimi-code*.json; the oracle globs the credentials dir (or an API key).
  • Codex: codex login status, falling back to ~/.codex/auth.json. Claude: the shared ~/.claude/.credentials.json (the extension writes it, the CLI reads it).
  • Oracles are cached (FAST_ORACLE_TTL 5 s, ORACLE_IN_FLIGHT guard) because the catalog is polled by several surfaces at once. Slow oracles are marked oracle_slow and cached longer.
  • A failed probe is "unknown", never "not installed" (detect() returns Err on transport failure). Right after an update relaunch the exec route settles for a few seconds; the first cut read every AI as absent and raised the first-landing dialog on a signed-in box.

shared_auth on the Provider says whether one sign-in covers the extension and the CLI. Claude, Codex and Kimi share a credential store. Antigravity does not, but Hydrogen makes it shared: the extension's agy server keeps its Google login in ~/.gemini/jetski-standalone-oauth-token and the CLI in ~/.gemini/antigravity-cli/antigravity-oauth-token, both for the SAME OAuth client (identical aud in the id_token, VERIFIED 2026-09-20) in the same JSON shape. The oracle reads both and copies whichever exists to the missing side (mode 600), so a panel sign-in signs the CLI in and a CLI sign-in signs the extension in. One limit, measured: the panel's webview keeps its Welcome screen until the window reloads (restarting the agy server or re-opening the side bar does not refresh it), so after a CLI-side sign-in the dialog offers "Reload VS Code now". shared_auth_note carries that explanation into the tooltip. ext_separate_signin still marks Antigravity so the dialog's primary Sign in opens the panel (extension first). Sign-out removes both token files. Before this, Hydrogen ignored the extension's file and showed "Sign in" over a signed-in panel (John, 2026-09-20).

Sign-in: driving it for the user

POST /agents/login {key} runs the provider's login_cmd under a pty in the container with BROWSER= pointed at a capture script, then GET /agents/login-url streams what the panel needs: the consent URL (captured from $BROWSER or regexed out of the transcript with url_regex), a device code (code_regex, Codex), and needs_input when the transcript matches input_prompt_regex (the CLI wants a code pasted back). auto_input types menu answers (Antigravity's "Select login method" wants Enter). The session ends when the oracle flips or on /agents/login-stop.

Per AI:

  • Claude: the CLI's OAuth in the browser. Hydrogen cannot raise the consent window for the user on Linux (raise_window_for_user is a no-op here).
  • Codex: device code shown in the dialog, user types it on the page.
  • Kimi: device flow against kimi.ai. install_cmd writes global into ~/.kimi-code/region (the installer wrote mainland-cn, which sends the user to a WeChat page and the poll never completes). The 2.x login also moves aside a 0.8.x extension-written config.toml that lacks per-model protocol (it made every prompt refuse).
  • Antigravity: the extension is primary (John: "stop giving preference to the tui"). The dialog's Sign in opens the extension's panel through POST /agents/open-panel, counts down "closing this dialog in 3, 2, 1" and closes so the panel is not hidden behind it. The CLI sign-in is the secondary link; its flow ends on antigravity.google/oauth-callback, a paste-only page, so the dialog shows a paste box (paste_code) feeding POST /agents/login-input {key, value b64}. No clipboard sniffing (John: "just give me a box to paste the code into").

On Linux, Manage AIs sign-ins (signin: true) and known sign-in hosts open straight in the system browser (no picker countdown, no in-app tab: Codex's page refuses to be embedded).

Codex and Claude Code's shell sandbox is bubblewrap. On Ubuntu 23.10+ the host's kernel.apparmor_restrict_unprivileged_userns=1 breaks it; Hydrogen's helper loads /etc/apparmor.d/adom-hydrogen-bwrap at machine start. A "needs access to create user namespaces" error means that profile is not loaded.

First-run state for the Claude TUI lives in ~/.claude.json (hasCompletedOnboarding, theme, per-folder hasTrustDialogAccepted); the extension never writes it, so a signed-in user still saw the wizard in a terminal. hydrogen-bootstrap 4b seeds those keys.

The toolbar button decision

Hydrogen writes ~/.adom/agent-bar.json whenever an oracle result changes: {"authed":[keys], "agents":[{key, cli, extension, extension_id, authed}]}. adom-vscode watches it (fs.watchFile) and its /ai/providers merges it with the extension list:

  • installed = extension || cli. A main toolbar button appears only when installed, and it opens the extension surface (tab or side bar), never the TUI.
  • TUI buttons exist for people who like them: off by default, added in the icon chooser, and only offered when the CLI exists.
  • Antigravity's default surface is the side bar: its "editor tab" mode waits on a remote tunnel that never connects under code-server.
  • The AI menu lists installed AIs plus an "Install the X extension" row when only the CLI is present, and a "Your AIs / Manage AIs" row that calls Hydrogen POST /agents/present {manage:true} through the control URL in ~/.adom/hydrogen-control-url.

Signing in therefore lights the button by itself; nothing reloads.

Keeping the Manage AIs dialog honest

  • Every row is rendered from /agents/catalog (installed, authed, extension, has_login, has_apikey, has_install, shared_auth, extension_signin_separate). The pill says "Signed in · extension + CLI" when shared_auth, else "CLI signed in" plus "extension: own sign-in". The button says "Sign in" when one sign-in covers both, "Sign in extension" when it does not.
  • The "?" opens a tooltip from /agents/facts: extension id, version, bytes; the CLI as a wrapper (0 MB extra), an extension-downloaded copy, a pip package, an npm package or a standalone binary with its bytes; the sign-in model; data dirs; duplicates; total. It is positioned from the button's measured rect as a sibling of the dialog inside the overlay. Rendering it in flow made the dialog grow and re-centre, slid the "?" out from under the cursor, and looped (John: "the worst human experience ever"). Nothing in that tooltip may change layout.
  • One shared record per AI: the dialog, the toolbar and the Welcome line never compute their own state; they read Hydrogen's. Sign out goes through /agents/logout (provider logout_cmd, plus ext_logout_cmd for Kimi's extension) so all three surfaces flip together.
  • The dialog is draggable by its header and has a close X; the first-landing variant has "I'll do this later" and "Continue".

Ship checklist for a change here

  1. Hydrogen for Linux: scripts/linux-build.sh (deb, rpm, AppImage), or scripts/linux-build-jammy.sh for the glibc 2.34 floor; install on the Linux test VMs and check /buildinfo. Releases go out through the manifest's linux section (scripts/publish-version-json.sh --linux-*).
  2. adom-vscode: bash build.sh, bash scripts/release-wiki.sh (stamp guards, pushes main). Workspaces pull it with adom-wiki pkg update adom/adom-vscode.
  3. hydrogen-bootstrap: bump package.json, prepublish-check.sh, adom-wiki pkg publish --org adom --yes. Test any new converge block on a test box first; it runs on every workspace.
  4. Golden image: the golden image repo's scripts/bake-weekly.sh then pin-golden.sh; wrapper text in image/bake-in-distro.sh must match what bootstrap 4d writes.
  5. Verify with GET /agents/catalog and GET /agents/facts?fresh=1 on a box, then look at the dialog (screenshot), not just the JSON.