diff --git a/TELEPORTATION_ONE_PAGER.md b/TELEPORTATION_ONE_PAGER.md new file mode 100644 index 0000000000..4eba71d29c --- /dev/null +++ b/TELEPORTATION_ONE_PAGER.md @@ -0,0 +1,96 @@ +# One-Pager: Session Teleportation (External Tool Resumption) + +## 1. Objective + +Enable Gemini CLI users to seamlessly resume work sessions (trajectories) that +were originated and executed in external coding tools or IDE extensions. This +"teleportation" of sessions establishes Gemini CLI as a centralized hub for +AI-assisted development across various environments. + +## 2. Background & Motivation + +Developers frequently switch between multiple tools (e.g., IDE extensions, +web-based coding assistants, and the terminal). Currently, context is +fragmented; a session started in an external tool cannot be natively continued +in Gemini CLI. By allowing Gemini CLI to parse and ingest trajectories from +these external tools, we prevent context loss, avoid duplicate work, and +significantly enhance developer productivity. + +## 3. Goals & Non-Goals + +**Goals:** + +- Provide a standardized abstraction (`TrajectoryProvider`) for fetching + external session histories. +- Implement a core translation layer (`teleporter` module) to map external tool + actions (e.g., `find`, `search_web`, `read_url`, `write_to_file`) to Gemini + CLI's native tool formats. +- Update the `/resume` CLI command to display and filter these external sessions + alongside native ones. +- Support dynamic loading of new trajectory providers via the extension system. + +**Non-Goals:** + +- Two-way sync: We do not intend to export Gemini CLI sessions back to the + originating external tool in this phase. +- Perfect fidelity for unsupported external tools: Only explicitly supported and + mapped tools will be translated. Others will be gracefully ignored or logged + as plain text. + +## 4. Proposed Design / Architecture + +The design revolves around a pluggable architecture that decouples the fetching +of external trajectories from the core CLI logic. + +### 4.1. `TrajectoryProvider` Interface + +A standard contract that external extensions implement. It defines methods for: + +- Retrieving a list of available sessions. +- Fetching the full trajectory payload for a specific session ID. +- Providing metadata (display name, icon, source tool name) for the CLI UI. + +### 4.2. Core `teleporter` Module + +This module acts as the ingestion engine. It performs: + +- **Deserialization:** Parsing the raw JSON/format of the external tool. +- **Conversion:** Mapping external tool calls (e.g., an Antigravity `search_web` + call) into the equivalent Gemini CLI tool call format, ensuring the LLM + understands the historical context correctly. +- **Validation:** Ensuring the resulting session history conforms to Gemini + CLI's internal session schema. + +### 4.3. UI Integration (`/resume`) + +The `SessionBrowser` UI will be updated to handle multiple sources. + +- Introduce dynamic tabs or source filters in the TUI (Terminal UI). +- Display metadata (e.g., "Imported from Tool X", timestamps) to help users + distinguish between native and teleported sessions. + +### 4.4. Extension Manager Updates + +Enhance the existing `extensionLoader` to discover, load, and register plugins +that implement the `TrajectoryProvider` interface dynamically at runtime. + +## 5. Rollout Plan + +The implementation is broken down into incremental PRs tracked by Epic #22801: + +1. **Define Core Interfaces:** Establish `TrajectoryProvider`. +2. **Implement Translation Logic:** Build the `teleporter` module with initial + conversion mappings. +3. **UI Updates:** Hook the providers into the `/resume` interface. +4. **Extension Support:** Enable dynamic loading of providers. +5. **Documentation:** Publish `TELEPORTATION.md` outlining how to build new + providers. + +## 6. Security & Privacy + +- **Local First:** Trajectories should be read from local filesystem artifacts + or secure local IPC mechanisms where possible, avoiding unnecessary network + calls. +- **Data Sanitization:** The conversion process must not execute any historical + commands; it strictly translates historical records into past-tense context + for the LLM. diff --git a/packages/cli/src/ui/components/SessionBrowser.tsx b/packages/cli/src/ui/components/SessionBrowser.tsx index 544771ba49..6b4fb65f36 100644 --- a/packages/cli/src/ui/components/SessionBrowser.tsx +++ b/packages/cli/src/ui/components/SessionBrowser.tsx @@ -14,7 +14,7 @@ import { useKeypress } from '../hooks/useKeypress.js'; import path from 'node:path'; import { pathToFileURL } from 'node:url'; import { type Config } from '@google/gemini-cli-core'; -import type { SessionInfo, TextMatch } from '../../utils/sessionUtils.js'; +import type { SessionInfo } from '../../utils/sessionUtils.js'; import { formatRelativeTime, getSessionFiles,