Safe migration workstream: Antigravity CLI and Gemini CLI into OpenAI CLI

[knowledge0101010-lang]

This issue tracks a safe, phased migration plan to absorb useful behavior from Antigravity CLI and Gemini CLI packaging into OpenAI CLI.

Scope:

• Antigravity CLI terminal-agent behaviors
• Antigravity SDK concepts that are reusable in a CLI
• Gemini CLI packaging/command-distribution lessons
• OpenAI Apps SDK alignment where applicable

Read-only facts gathered so far:

• openai-cli is a Go CLI with cmd/openai, internal, pkg/cmd, and scripts.
• The CLI already supports resource-based commands, file arguments, auth env vars, and a Go SDK link path.
• Antigravity CLI emphasizes permissioned edits, command execution, SSH sessions, and Google Sign-In/keyring auth.
• The Antigravity Python SDK exposes agent/session/tooling primitives, triggers, hooks, and MCP integration.

Planned phases:

1. File-map the CLI surface in cmd/openai, internal, pkg/cmd, and scripts.
2. Identify reusable agent-session abstractions and OpenAI-native telemetry events.
3. Separate auth, install, and deploy path changes from agent behavior changes.
4. Draft a minimal first PR that only adds the new abstractions and compatibility seams.
5. Follow with telemetry, auth, and UX PRs.

Non-goals for the first PR:

• No package rename.
• No destructive behavior changes.
• No unrelated refactors.
• No attempt to mirror Google-only auth or telemetry.

Deliverables:

• A file-level migration map.
• A PR sequence.
• A list of compatibility gaps and adapter requirements.
• A clear boundary between OpenAI CLI core behavior and imported agent ergonomics.

[knowledge0101010-lang]

Safe execution plan

I have not started code edits yet. This comment converts the migration into file-level work so the next PR can proceed safely.

1) File-level map to inspect first

• cmd/openai/* for top-level command wiring, flags, and subcommand registration.
• internal/* for auth, API transport, telemetry, session state, and any command execution hooks.
• pkg/cmd/* for reusable command abstractions and shared CLI behavior.
• scripts/* for install/update/release behavior.
• README.md and usage docs for user-facing command semantics and auth/install copy.

2) Work items to split into PRs

1. Surface map PR

   • Document the existing command surface and where an Antigravity-like agent layer can fit.
   • Mark hard boundaries where OpenAI CLI should stay resource-first instead of becoming a full agent shell.

2. Telemetry PR

   • Define OpenAI-native telemetry events for session start, prompt submit, tool call, file edit, approval, and command execution.
   • Keep telemetry independent of Google/Antigravity assumptions.

3. Auth PR

   • Replace or isolate any Google-specific login concepts.
   • Keep only OpenAI-compatible auth paths and document unsupported external flows.

4. Install/Deploy PR

   • Review scripts/* and packaging scripts for any hard-coded vendor assumptions.
   • Make install/update behavior distribution-agnostic where possible.

5. UX/Command PR

   • Add only the command-shell ergonomics that fit the current OpenAI CLI architecture.
   • Preserve current command semantics unless the change is explicitly part of the migration.

3) Safety gates

• No destructive refactors in the first pass.
• No package rename in the first pass.
• No telemetry changes without a clear event contract.
• No auth changes without a documented fallback and rollback path.
• No GitLab-specific or Google-specific assumptions in new code.

4) Definition of done for the first safe pass

• The migration boundaries are documented.
• The PR sequence is clear.
• The files to touch next are listed.
• The remaining compatibility gaps are explicit.

[knowledge0101010-lang]

File-level candidates for the first PR

Based on the current openai-cli surface, these are the safest first-pass files to touch or reference.

Core entry and runtime wiring

• cmd/openai/main.go
  • Entry point, autocomplete bootstrap, base URL validation, and error formatting.
• pkg/cmd/cmd.go
  • Root command tree, global flags, command registration, and manpage generation.
• pkg/cmd/cmdutil.go
  • Shared output formatting, pager behavior, response rendering, and request headers.

Request parsing and parameter plumbing

• pkg/cmd/flagoptions.go
  • File embedding, stdin parsing, request body assembly, and the best place to introduce a unified agent-session or telemetry seam.
• internal/requestflag/requestflag.go
  • Flag metadata, request-body mapping, stdin-to-flag translation, and inner-flag behavior.
• pkg/cmd/completion.go
  • Completion behavior for nested command trees and file-aware completions.
• internal/autocomplete/autocomplete.go
  • Shell completion script generation and command navigation heuristics.

Representative command handlers to use as migration patterns

• pkg/cmd/conversation.go
  • Shows how CLI handlers map to generated SDK calls and output formatting.
• Any other handler files under pkg/cmd that already use the same client -> options -> response -> ShowJSON pattern.

Files to keep in the first pass only as references, not targets

• scripts/run
• scripts/link
• README.md

Why these files

• main.go and pkg/cmd/cmd.go define the process boundary.
• flagoptions.go and requestflag.go define the request lifecycle, which is the cleanest place to hook agent-session, telemetry, and approval-related state.
• cmdutil.go centralizes rendering and output behavior, which is where agentic UI behavior can be kept consistent without scattering changes across commands.
• completion.go and autocomplete.go cover user-facing shell ergonomics and should be kept stable until the core migration is settled.

PR draft

Title

Introduce safe agent-session seams for OpenAI CLI migration

Summary

This PR introduces non-destructive seams for a future migration from Antigravity-style CLI behavior into OpenAI CLI, without changing the current resource-first command model.

Scope

• Add a small internal abstraction for session/telemetry metadata.
• Thread that abstraction through request assembly and response rendering points.
• Leave command semantics unchanged.
• Keep install, auth, and packaging behavior intact.

Explicit non-goals

• No package rename.
• No auth overhaul.
• No command tree redesign.
• No behavioral changes to existing API-resource commands.
• No Google-specific or GitLab-specific logic.

Acceptance criteria

• Existing commands still work.
• Autocomplete still works.
• File argument handling still works.
• The new seam is visible in the request path and can support later telemetry/auth/agent work.
• The PR is small enough to review independently of the larger migration.

Follow-up PR sequence

1. Telemetry contract and event emission.
2. Auth/session normalization.
3. Agent-style UX and approval flow.
4. Install/deploy cleanup.
5. Optional Rust-migration planning for any importable CLI subpackages.

Recommended next implementation slice

If we begin code edits later, start in pkg/cmd/flagoptions.go and pkg/cmd/cmdutil.go, then add the minimum supporting types near internal/requestflag/requestflag.go or a new small internal package dedicated to session metadata.

[knowledge0101010-lang]

Metacognitive correctness gate

Before any code edits, apply an explicit intent-check pass so the migration does not drift.

Intent to verify

• The goal is to preserve the current openai-cli resource-first architecture while adding safe seams for Antigravity-style agent behavior.
• The first PR must not change command semantics, auth flow, install flow, or packaging.
• Any new telemetry must be additive and OpenAI-native, not a Google/Antigravity import.
• Any session abstraction must be minimal and optional, not a hidden behavior change.

Questions the implementation must answer

1. What exact user workflow is being improved?
2. Which files are the minimum surface for that workflow?
3. What would break if we removed the new abstraction?
4. Does any new code leak Google-specific or GitLab-specific assumptions?
5. Can the change be reversed without changing user-facing behavior?

Validation checklist

• Existing commands still parse and run.
• --help and completion output still work.
• @file and stdin behaviors still work.
• The new seam is isolated enough to support later telemetry or session hooks.
• No unrelated refactors were introduced.

Reviewer rule

If any answer is uncertain, stop and reduce the scope before coding. The safe default is to keep the migration seam narrower, not broader.