Initial public release of Warp.
Repo-Sync-Origin: warpdotdev/warp-internal@12af1d983b
This commit is contained in:
David Stern
@@ -0,0 +1,137 @@
|
||||
# Product Spec: Gemini CLI Plugin Install & Update Flow
|
||||
|
||||
Linear: [APP-4067](https://linear.app/warpdotdev/issue/APP-4067/enable-gemini-notifications)
|
||||
Figma: none provided
|
||||
|
||||
## Summary
|
||||
|
||||
Add install and update chip support for the Gemini CLI Warp plugin (`gemini-warp`), matching the existing Claude Code chip UX. Enable the listener so Warp processes structured notifications from Gemini sessions (session status, permission requests, task completion).
|
||||
|
||||
## Problem
|
||||
|
||||
The `gemini-warp` extension already exists and uses the same structured OSC 777 notification protocol as Claude Code (`warp://cli-agent` title, JSON body with `agent: "gemini"`). However, Warp currently ignores these notifications because:
|
||||
|
||||
1. `create_handler` in the listener returns `None` for `CLIAgent::Gemini`.
|
||||
2. `plugin_manager_for` returns `None` for `CLIAgent::Gemini` — there's no install/update chip.
|
||||
3. There is no `GeminiNotifications` feature flag to gate the rollout.
|
||||
|
||||
## Goals
|
||||
|
||||
- Gemini users see install/update chips that prompt them to set up the plugin.
|
||||
- Clicking the chip auto-installs or auto-updates the plugin (Gemini CLI has first-class extension management commands).
|
||||
- A manual instructions fallback is available for cases where auto-install fails.
|
||||
- Structured notifications from the Gemini plugin are received and displayed (session status, blocked/success states, permission requests).
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Changing the gemini-warp plugin itself (it's maintained separately in `warpdotdev/gemini-cli-warp`).
|
||||
- Platform plugin / Oz harness support for Gemini (future work).
|
||||
|
||||
## How Gemini CLI Extensions Work
|
||||
|
||||
Gemini CLI has a first-class extension system:
|
||||
|
||||
- **Install**: `gemini extensions install <github-url-or-local-path>` — copies the extension into `~/.gemini/extensions/<name>/`.
|
||||
- **Update**: `gemini extensions update <name>` — pulls the latest version from the source.
|
||||
- **Uninstall**: `gemini extensions uninstall <name>`.
|
||||
- **Manifest**: Each extension has a `gemini-extension.json` with `name`, `version`, `description`, and hook/MCP/command definitions.
|
||||
- **Hooks**: Defined in `hooks/hooks.json` within the extension directory (not in the manifest). The gemini-warp plugin uses `SessionStart`, `AfterAgent`, `Notification`, `BeforeAgent`, and `AfterTool` hooks.
|
||||
|
||||
Key difference from Claude Code: Gemini extensions install from a GitHub URL directly (no separate marketplace add step). The install and update are each a single CLI command.
|
||||
|
||||
Key difference from OpenCode: Gemini CLI *does* have CLI commands for extension management, so auto-install and auto-update are viable.
|
||||
|
||||
## User Experience
|
||||
|
||||
### Install Chip
|
||||
|
||||
When a user starts a Gemini session and the plugin has never connected (no listener, no `plugin_version` reported):
|
||||
|
||||
- A green chip appears: "Notifications setup instructions"
|
||||
- Clicking triggers auto-install via `gemini extensions install https://github.com/warpdotdev/gemini-cli-warp --consent`.
|
||||
- `--consent` skips the interactive confirmation prompt that would block the non-interactive shell execution.
|
||||
- On success, a toast confirms installation and tells the user to restart Gemini.
|
||||
- On failure, a toast appears with an error, and the user can click the info (ⓘ) button to open manual instructions in a split pane.
|
||||
|
||||
**Manual install instructions (split pane):**
|
||||
- Title: "Install Warp Plugin for Gemini CLI"
|
||||
- Subtitle: "Run the following command, then restart Gemini CLI."
|
||||
- Steps:
|
||||
1. "Install the Warp extension" — command: `gemini extensions install https://github.com/warpdotdev/gemini-cli-warp --consent`
|
||||
- Post-install notes: "Restart Gemini CLI to activate the plugin."
|
||||
|
||||
### Update Chip
|
||||
|
||||
When the plugin is connected but reports a version below `MINIMUM_PLUGIN_VERSION`:
|
||||
|
||||
- Label: "Plugin update available"
|
||||
- Clicking triggers auto-update via `gemini extensions update gemini-warp`.
|
||||
- The extension name is `gemini-warp` (the installed directory name under `~/.gemini/extensions/`).
|
||||
- On success, a toast confirms the update and tells the user to restart Gemini.
|
||||
- On failure, a toast appears with an error, and the user can click the info (ⓘ) button to open manual instructions in a split pane.
|
||||
|
||||
**Manual update instructions (split pane):**
|
||||
- Title: "Update Warp Plugin for Gemini CLI"
|
||||
- Subtitle: "Run the following command, then restart Gemini CLI."
|
||||
- Steps:
|
||||
1. "Update the Warp extension" — command: `gemini extensions update gemini-warp`
|
||||
- Post-install notes: "Restart Gemini CLI to activate the update."
|
||||
|
||||
### Version Detection
|
||||
|
||||
Two signals, matching the Claude Code pattern:
|
||||
|
||||
1. **Filesystem check**: `~/.gemini/extensions/gemini-warp/gemini-extension.json` — read the `version` field to determine if the plugin is installed and whether it's outdated. Symlinks are followed (supports `gemini extensions link`).
|
||||
2. **Runtime signal**: `plugin_version` field from the `SessionStart` event (emitted by `on-session-start.sh` in the plugin).
|
||||
|
||||
The filesystem check eliminates install chip flicker (the chip never appears if the plugin is already on disk) and enables update detection before the plugin connects.
|
||||
|
||||
### Notification Listening
|
||||
|
||||
Once the plugin is installed, the Gemini session handler works identically to Claude Code / OpenCode: the `DefaultSessionListener` receives structured JSON events and forwards them to the sessions model. No special parsing is needed — the plugin already speaks the same protocol.
|
||||
|
||||
### Chip Visibility Logic
|
||||
|
||||
Same as Claude Code:
|
||||
|
||||
1. Plugin connected, version >= minimum → **no chip**
|
||||
2. Plugin connected, version < minimum → **update chip**
|
||||
3. No listener, plugin installed on disk with version >= minimum → **no chip** (wait for connection)
|
||||
4. No listener, plugin installed on disk with version < minimum → **update chip**
|
||||
5. No listener, plugin not installed on disk → **install chip** (unless dismissed)
|
||||
6. Chip dismissed → **no chip** (install and update have independent dismiss state)
|
||||
7. Notifications disabled in settings → **no chip**
|
||||
|
||||
### Dismiss Behavior
|
||||
|
||||
Same as Claude Code / OpenCode: install chip and update chip have independent dismiss state. The update chip tracks which minimum version was dismissed; a new minimum causes it to reappear.
|
||||
|
||||
## Edge Cases
|
||||
|
||||
- **Plugin installed via `gemini extensions link` (symlink):** Filesystem check follows symlinks, so linked extensions are detected as installed. Version is read from the symlinked `gemini-extension.json`.
|
||||
- **`gemini` CLI not on PATH:** Auto-install fails; user sees error toast and can use the manual instructions pane. The manual instructions pane commands will also need `gemini` on PATH, but the user can adapt (e.g. use full path or install Gemini CLI).
|
||||
- **Extension already installed:** `gemini extensions install` may fail or warn. This is fine — the user already has the plugin.
|
||||
- **SSH sessions:** Same experience as local. The `gemini` CLI must be available on the remote host. Filesystem checks don't apply to remote sessions (same as Claude Code).
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. Starting a Gemini CLI session in Warp when the plugin is not installed shows a green install chip.
|
||||
2. Clicking the install chip runs `gemini extensions install` and shows a success/failure toast.
|
||||
3. After restart, the plugin connects, notifications appear in the inbox, and the chip disappears.
|
||||
4. When the plugin reports a version below `MINIMUM_PLUGIN_VERSION`, an update chip appears.
|
||||
5. Clicking the update chip runs `gemini extensions update gemini-warp` and shows a success/failure toast.
|
||||
6. The info (ⓘ) button opens a split pane with manual instructions (not a modal).
|
||||
7. Dismissing the chips works identically to other agents (independent dismiss state, version-tracked update dismiss).
|
||||
8. Gemini notifications (stop, blocked, permission request) surface in the agent inbox when HOANotifications is enabled.
|
||||
9. The install/update chip is gated behind both `HOANotifications` and `GeminiNotifications` feature flags. Notification listening only requires `HOANotifications` (consistent with other agents).
|
||||
|
||||
## Validation
|
||||
|
||||
- Unit tests: `GeminiPluginManager` trait implementations (minimum version, can_auto_install, install/update instructions).
|
||||
- Unit tests: `is_installed()` / `needs_update()` filesystem detection with temp directories.
|
||||
- Unit tests: `is_agent_supported` returns `true` for `CLIAgent::Gemini` when feature flags are enabled.
|
||||
- Unit tests: `plugin_manager_for(CLIAgent::Gemini)` returns `Some(...)` when flags are enabled.
|
||||
- Manual testing: full install flow with a real Gemini CLI session.
|
||||
- Manual testing: update flow — verify `gemini extensions update` pulls new version.
|
||||
- Manual testing: notification flow — verify stop, blocked, permission request notifications appear.
|
||||
|
||||
Reference in New Issue
Block a user