superqode 2.4.29__tar.gz → 2.4.30__tar.gz

{superqode-2.4.29 → superqode-2.4.30}/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.30] - 2026-09-29
+
+### Added
+
+- Gemini CLI subscription discovery with Google sign-in setup and explicit
+  vendor-agent alternatives in the native harness model-source menu.
+- Account connections for OpenCode, fast-agent, Pi and omp, including
+  fast-agent Codex plan launch settings and reconnect support.
+- Native MiniMax Token Plan model access with a separate validated subscription
+  credential and endpoint.
+
+### Fixed
+
+- Keep subscription credentials separate from general API billing. Z.AI and
+  Alibaba Coding Plan choices explain supported-agent setup; Kimi and Copilot
+  alternatives explicitly identify their vendor harness.
+- Preserve the current agent and credentials when model setup fails, and
+  restore the saved native harness and exact model route on reconnect.
+- Retain ACP registry package versions, launch arguments, scoped environment
+  defaults and user-defined command overrides. Binary-only agents show
+  matching platform download and checksum guidance.
+- Apply subscription billing guards after child-environment overlays and keep
+  explicit Copilot tokens scoped to Copilot. OAuth/local agent health checks
+  require only explicitly declared environment variables.
+- Target the active Python environment and installed SuperQode version in SDK
+  setup hints; keep public installation guidance independent of the exporting
+  machine's installed extras.
+- Prevent interactive account and plan shortcuts from falling through to an
+  unrelated default provider in headless mode.
+- Correct connection documentation, readiness guidance, Gemini discovery and
+  Qoder/Poolside capability declarations, and refresh the published Hub catalog.
+
 ## [2.4.29] - 2026-09-29
 
 ### Added

{superqode-2.4.29 → superqode-2.4.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.4.29
+Version: 2.4.30
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>

{superqode-2.4.29 → superqode-2.4.30}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "2.4.29"
+version = "2.4.30"
 description = "The harness layer for coding agents"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/__init__.py

@@ -38,7 +38,7 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "2.4.29"
+__version__ = "2.4.30"
 
 # Stable, lightweight public extension surface.  Importing this package does
 # not discover or execute third-party extensions; discovery happens only when

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/acp/client.py

@@ -304,6 +304,9 @@ class ACPClient:
             # Applied last so a caller can override the defaults above.
             for name, value in (self.extra_env or {}).items():
                 env[str(name)] = str(value)
+            if self.subscription_vendor:
+                env, removed = subscription_child_env(self.subscription_vendor, env)
+                self.stripped_api_keys = list(dict.fromkeys([*self.stripped_api_keys, *removed]))
 
             # OpenCode's verbose logs are useful for debugging, but expensive on
             # normal runs because every non-JSON line has to be parsed and routed

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/agents/client.py

@@ -153,7 +153,9 @@ class ACPAgentManager:
         self.connection: ClientSideConnection | None = None
         self._response_queue: asyncio.Queue = asyncio.Queue()
 
-    async def connect_to_agent(self, command: str, cwd: str | None = None) -> bool:
+    async def connect_to_agent(
+        self, command: str, cwd: str | None = None, *, extra_env: dict[str, str] | None = None
+    ) -> bool:
         """Connect to an ACP agent.
 
         Args:
@@ -189,6 +191,7 @@ class ACPAgentManager:
                 stdin=asyncio.subprocess.PIPE,
                 stdout=asyncio.subprocess.PIPE,
                 cwd=cwd or os.getcwd(),
+                env={**os.environ, **extra_env} if extra_env else None,
             )
 
             if proc.stdin is None or proc.stdout is None:

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/agents/discovery.py

@@ -77,6 +77,7 @@ async def read_agents(include_registry: bool = False) -> dict[str, "Agent"]:
                     if file.name.endswith(".toml") and file.is_file():
                         try:
                             agent: "Agent" = tomllib.load(file.open("rb"))
+                            agent["user_defined"] = search_path == user_agent_dir
                             if agent.get("active", True):
                                 # Validate required fields
                                 required_fields = ["identity", "name", "short_name", "protocol"]
@@ -115,7 +116,16 @@ async def read_agents(include_registry: bool = False) -> dict[str, "Agent"]:
             for warning in warnings:
                 console.print(f"[yellow]Warning: {warning}[/yellow]")
 
-    agent_map = {agent["identity"]: agent for agent in agents}
+    agent_map = {}
+    for agent in agents:
+        if agent.get("user_defined"):
+            short_name = str(agent.get("short_name") or "").casefold()
+            agent_map = {
+                identity: existing
+                for identity, existing in agent_map.items()
+                if str(existing.get("short_name") or "").casefold() != short_name
+            }
+        agent_map[agent["identity"]] = agent
 
     # Ensure the bundled catalog has stable terminal groups even before the
     # first network refresh.
@@ -153,6 +163,12 @@ async def read_agents(include_registry: bool = False) -> dict[str, "Agent"]:
                 existing["registry_id"] = converted.get("registry_id", "")
                 existing["registry_version"] = converted.get("registry_version", "")
                 existing["registry_source"] = converted.get("registry_source", "")
+                existing["registry_license"] = converted.get("registry_license", "")
+                existing["registry_license_url"] = converted.get("registry_license_url", "")
+                if not existing.get("user_defined"):
+                    existing["launch_env"] = converted.get("launch_env", {})
+                    if converted.get("registry_source") == "official-registry":
+                        existing["run_command"] = converted["run_command"]
                 existing["catalog_tier"] = converted.get("catalog_tier", "all")
                 existing["recommended"] = converted.get("recommended", False)
                 existing["tags"] = sorted(

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/agents/schema.py

@@ -110,6 +110,10 @@ class Agent(TypedDict):
     welcome: NotRequired[str]
     """A Markdown document shown to the user when the conversation starts. Should contain a welcome message and any advice on getting started."""
     run_command: dict[OS, str]
+    launch_env: NotRequired[dict[str, str]]
+    user_defined: NotRequired[bool]
+    """Distribution defaults applied only to this agent's subprocess."""
+    required_env: NotRequired[list[str]]
     """Command to run the agent, by OS or wildcard."""
     actions: dict[OS, dict[Action, Command]]
     """Scripts to perform actions, typically at least to install the agent."""

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/app/harness_picker.py

@@ -13,6 +13,7 @@ VENDOR_HARNESS_IDS = (
     "kimi-code",
     "qwen-code",
     "antigravity",
+    "gemini-cli",
     "grok",
     "copilot",
     "cursor",
@@ -80,6 +81,11 @@ def harness_install_extra(entry) -> str:
     """Return the controlled SuperQode extra for an unavailable harness."""
     if bool(getattr(entry, "available", False)):
         return ""
+    return harness_source_extra(entry)
+
+
+def harness_source_extra(entry) -> str:
+    """Declared optional extra, independent of this machine's installation."""
     return _OPTIONAL_HARNESS_EXTRAS.get(str(getattr(entry, "source", "") or ""), "")
 
 

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/app/mixins/agent_run.py

@@ -2057,6 +2057,20 @@ class AgentRunMixin:
         # Closed/Open key paths set this at :connect time. Merge last so the
         # child sees the resolved key; never setdefault into SuperQode's env.
         # Only the agent the key was resolved for receives it.
+        selected_agent = getattr(get_session(), "connected_agent", None) or {}
+        override_name = f"SUPERQODE_{agent_type.upper().replace('-', '_')}_ACP_COMMAND"
+        if (
+            isinstance(selected_agent, dict)
+            and (
+                selected_agent.get("user_defined")
+                or (
+                    selected_agent.get("registry_source") == "official-registry"
+                    and agent_type not in {"prime-agent", "prime"}
+                )
+            )
+            and not os.getenv(override_name)
+        ):
+            command = selected_agent.get("run_command", {}).get("*", "") or command
         acp_extra_env = self._merge_acp_session_extra_env(agent_type, acp_extra_env)
 
         mode_label = {"auto": "🟢 AUTO", "ask": "🟡 ASK", "deny": "🔴 DENY"}.get(

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/app/mixins/commands_impl.py

@@ -805,7 +805,7 @@ class CommandImplMixin:
 
     def _show_vendor_runtime_setup(self, log) -> None:
         """Show optional vendor SDK and external CLI setup without installing."""
-        from superqode.providers.env_introspect import install_command
+        from superqode.providers.env_introspect import active_install_command as install_command
 
         text = Text()
         text.append("\n  Vendor runtime setup\n\n", style=f"bold {THEME['purple']}")
@@ -2871,7 +2871,7 @@ class CommandImplMixin:
                 style=THEME["text"],
             )
         if not sdk_ok:
-            from superqode.providers.env_introspect import install_command
+            from superqode.providers.env_introspect import active_install_command as install_command
 
             text.append("\n  SDK setup    ", style=THEME["muted"])
             text.append(f"{install_command('copilot-sdk')}\n", style=THEME["cyan"])
@@ -3199,7 +3199,7 @@ class CommandImplMixin:
             f"{feature} is provided by the GitHub Copilot SDK, and only the "
             "Copilot CLI route is available here."
         )
-        from superqode.providers.env_introspect import install_command
+        from superqode.providers.env_introspect import active_install_command as install_command
 
         log.add_info(f"Install the SDK with: {install_command('copilot-sdk')}")
         return True

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/app/mixins/connect.py

@@ -175,6 +175,23 @@ class ConnectMixin:
         # A harness that allows no providers for a mode must not offer the row:
         # selecting it would open a picker with nothing in it.
         offered = [row for row in profiles if self._key_models_row_offered(row.id)]
+        key_session = getattr(self, "_key_harness_session", None)
+        if key_session:
+            from superqode.providers.harness_catalog import get_entry
+            from superqode.providers.connection_profiles import ConnectionProfile
+
+            entry = get_entry(key_session.entry_id)
+            if entry and any(spec.mode == "subscription" for spec in entry.auth):
+                offered.append(
+                    ConnectionProfile(
+                        id=f"account-{entry.id}",
+                        label="Use this agent's subscription / account",
+                        description="Use the model and account configured in this agent; keeps its coding loop",
+                        connector="harness-account",
+                        runtime=entry.id,
+                        menu=menu,
+                    )
+                )
         return offered or profiles
 
     def _key_models_row_offered(self, row_id: str) -> bool:
@@ -770,6 +787,12 @@ class ConnectMixin:
     ) -> dict[str, str]:
         """Merge session extra env into the child env if it belongs to this agent."""
         merged = dict(acp_extra_env or {})
+        agent = getattr(get_session(), "connected_agent", None) or {}
+        if (
+            isinstance(agent, dict)
+            and agent.get("short_name", "").lower() == (agent_type or "").lower()
+        ):
+            merged = {**(agent.get("launch_env") or {}), **merged}
         extra = getattr(self, "_acp_extra_env", None) or {}
         owned = (getattr(self, "_acp_extra_env_agent", None) or "").strip().lower()
         current = (agent_type or "").strip().lower()
@@ -1514,7 +1537,7 @@ class ConnectMixin:
                     pass
         self._open_connect_screen(log)
         conn = profile.connector
-        if conn not in {"byok", "local", "key-harness"}:
+        if conn not in {"byok", "local", "key-harness", "harness-account"}:
             self._clear_key_harness_session()
         if getattr(profile, "id", "") == "copilot-acp" and log is not None:
             log.add_info(
@@ -1614,11 +1637,7 @@ class ConnectMixin:
         elif conn == "byok":
             # Subscription-plan entries reuse the direct-provider engine, but
             # that transport detail must not relabel their auth/billing as BYOK.
-            from superqode.providers.connection_profiles import CONNECT_MENU_PLAN
-
-            self._next_direct_auth_mode = (
-                "subscription" if getattr(profile, "menu", "") == CONNECT_MENU_PLAN else "byok"
-            )
+            self._next_direct_auth_mode = getattr(profile, "auth_mode", "") or "byok"
             self._direct_connection_profile_id = str(getattr(profile, "id", "") or "")
             # An acp-attach session keeps this picker: the selection is diverted
             # to the agent in _connect_byok_mode rather than at the menu.
@@ -1689,6 +1708,57 @@ class ConnectMixin:
             from superqode.providers.connection_profiles import CONNECT_MENU_PLAN
 
             self._show_connect_type_picker(log, menu=CONNECT_MENU_PLAN)
+        elif conn == "plan-guidance":
+            log.add_info(profile.unavailable_hint)
+            log.add_info(
+                "Your current harness and model have been kept. Choose the agent route explicitly to switch."
+            )
+        elif conn == "plan-agent":
+            from superqode.providers.connection_profiles import get_connection_profile
+
+            target = get_connection_profile(profile.acp_agent or "")
+            if target is None:
+                log.add_error("This account has no supported agent connection.")
+                return
+            log.add_info(
+                f"Using {target.label}'s coding loop through {target.transport or target.connector}."
+            )
+            self._dispatch_connection_profile(target, log)
+        elif conn == "harness-account":
+            from superqode.providers.harness_catalog import get_entry
+
+            key_session = getattr(self, "_key_harness_session", None)
+            entry = get_entry(key_session.entry_id if key_session else profile.runtime or "")
+            spec = (
+                next((s for s in entry.auth if s.mode == "subscription"), None) if entry else None
+            )
+            if not entry or not spec or not entry.acp_agent:
+                log.add_error("This harness does not expose a supported account route.")
+                return
+            from superqode.agents.registry import get_registry_agent_by_short_name
+            from superqode.commands.acp import check_agent_installed
+
+            agent_data = get_registry_agent_by_short_name(entry.acp_agent)
+            if agent_data and not check_agent_installed(agent_data):
+                installer = getattr(self, "_show_agent_install_picker", None)
+                if callable(installer) and installer(
+                    agent_data,
+                    log,
+                    on_ready=lambda: self._dispatch_connection_profile(profile, log),
+                ):
+                    return
+                log.add_info(f"Install {entry.label} first. {spec.notes}")
+                return
+            self._clear_key_harness_session()
+            self._clear_acp_extra_env()
+            self._acp_subscription_vendor = "codex" if entry.acp_agent == "fast-agent" else None
+            self._connecting_profile_id = f"account-{entry.id}"
+            log.add_info(
+                spec.notes
+                or "Using the agent's configured account and model; sign-in is checked by the agent."
+            )
+            self._connect_acp_cmd(entry.acp_agent, log)
+            self._set_acp_extra_env(dict(spec.account_env), entry.acp_agent)
         elif conn == "vendor-picker":
             from superqode.providers.connection_profiles import CONNECT_MENU_VENDORS
 
@@ -2823,7 +2893,6 @@ class ConnectMixin:
                 pass
         if self._redirect_harness_only_provider(provider, log):
             return
-        self._clear_acp_extra_env()
         if provider == "grok-cli":
             # The BYOK provider/model picker can reach this route without
             # passing through `:grok api`. Refresh the imported CLI credential
@@ -2859,25 +2928,19 @@ class ConnectMixin:
             )
             return
 
-        # Clear any existing ACP connection when switching to BYOK
-        if hasattr(self, "_acp_client") and self._acp_client:
-            # Disconnect ACP client if switching from ACP to BYOK
-            try:
-                if self._acp_loop_runner is not None:
-                    self._acp_loop_runner.run(self._acp_client.stop())
-                else:
-                    asyncio.create_task(self._acp_client.stop())
-            except Exception:
-                pass
-            self._acp_client = None
-            self._acp_client_key = None
+        # Validate plan credentials before disconnecting the current session.
+        # A missing plan key must never fall through to a global OpenAI key.
+        if provider_def.auth_mode == "subscription" and provider_def.env_vars:
+            from superqode.providers.credentials import provider_api_key
+
+            if not provider_api_key(provider_def):
+                log.add_error(
+                    f"{provider_def.name} requires its own subscription key "
+                    f"({', '.join(provider_def.env_vars)}). General API keys are not used. "
+                    f"Run superqode auth login {provider}."
+                )
+                return
 
-        # Clear session state
-        session = get_session()
-        if hasattr(session, "connected_agent"):
-            session.connected_agent = None
-        if hasattr(session, "acp_manager"):
-            session.acp_manager = None
         from superqode.providers.registry import ProviderCategory
         from superqode.pure_mode import PureMode
         from superqode.agent.system_prompts import SystemPromptLevel
@@ -2950,6 +3013,26 @@ class ConnectMixin:
                 log.write_feedback(t)
                 return
 
+        # Clear any existing ACP connection when switching to BYOK
+        self._clear_acp_extra_env()
+        if hasattr(self, "_acp_client") and self._acp_client:
+            # Disconnect ACP client if switching from ACP to BYOK
+            try:
+                if self._acp_loop_runner is not None:
+                    self._acp_loop_runner.run(self._acp_client.stop())
+                else:
+                    asyncio.create_task(self._acp_client.stop())
+            except Exception:
+                pass
+            self._acp_client = None
+            self._acp_client_key = None
+
+        # Clear session state
+        session = get_session()
+        if hasattr(session, "connected_agent"):
+            session.connected_agent = None
+        if hasattr(session, "acp_manager"):
+            session.acp_manager = None
         # Store previous provider for quick switching
         if hasattr(self, "current_provider") and self.current_provider:
             self._previous_provider = (self.current_provider, self.current_model)
@@ -3071,12 +3154,11 @@ class ConnectMixin:
         else:
             exec_mode = "byok"
 
-        requested_auth = str(getattr(self, "_direct_auth_mode", "") or "").lower()
         auth_mode = (
             "local"
             if exec_mode == "local"
             else "subscription"
-            if requested_auth == "subscription"
+            if provider_def.auth_mode == "subscription"
             else "byok"
         )
 
@@ -3159,7 +3241,7 @@ class ConnectMixin:
         title = (
             "Local Model Selected"
             if local
-            else "Subscription Connected"
+            else "Subscription Model Selected"
             if subscription
             else "Provider Connected"
         )
@@ -3179,6 +3261,26 @@ class ConnectMixin:
         t.append("    Model    ", style=THEME["muted"])
         t.append(model, style=f"bold {THEME['cyan']}")
         t.append("\n")
+        t.append("    Harness  ", style=THEME["muted"])
+        t.append(
+            str(getattr(self, "current_harness", "") or os.getenv("SUPERQODE_HARNESS", "core")),
+            style=THEME["text"],
+        )
+        t.append("\n")
+        from superqode.providers.dynamic import resolve_provider_def, resolve_base_url
+        from urllib.parse import urlsplit, urlunsplit
+
+        definition = resolve_provider_def(provider)
+        endpoint = resolve_base_url(definition) if definition else ""
+        if endpoint:
+            parsed = urlsplit(endpoint)
+            # Never display URL credentials or query tokens in the transcript.
+            public_endpoint = urlunsplit(
+                (parsed.scheme, parsed.netloc.rsplit("@", 1)[-1], parsed.path, "", "")
+            )
+            t.append("    Endpoint ", style=THEME["muted"])
+            t.append(public_endpoint, style=THEME["dim"])
+            t.append("\n")
         if host:
             t.append("    Host     ", style=THEME["muted"])
             t.append(host, style=THEME["dim"])
@@ -3186,6 +3288,8 @@ class ConnectMixin:
         t.append(
             "\n  Validating the local server..."
             if local
+            else "\n  Configured. Account access is verified on the first request."
+            if subscription
             else "\n  Ready. Type a message to start.",
             style=THEME["muted"],
         )
@@ -3213,7 +3317,9 @@ class ConnectMixin:
             dedupe_key=f"connection:{mode}:{provider}:{model}",
         )
         vendor_owned = False
-        harness = str(getattr(self, "current_harness", "") or "core")
+        harness = str(
+            getattr(self, "current_harness", "") or os.getenv("SUPERQODE_HARNESS", "core")
+        )
         key_session = getattr(self, "_key_harness_session", None)
         if key_session is not None:
             from superqode.providers.harness_catalog import get_entry
@@ -3408,12 +3514,48 @@ class ConnectMixin:
         provider = str(connection.get("provider") or "")
         model = str(connection.get("model") or "")
 
+        # Restore the agent/account route before considering any stale model
+        # fields from a previous native connection. This also restores account
+        # launch defaults (for example fast-agent's codexplan).
+        if acp_agent and profile_id:
+            from superqode.providers.connection_profiles import get_connection_profile
+
+            profile = get_connection_profile(profile_id)
+            if profile and profile.connector in {"acp", "harness-account"}:
+                self._dispatch_connection_profile(profile, log)
+                return
+
         if category == "acp" or (auth_mode == "acp" and not after_auth):
             if acp_agent:
                 self._connect_acp_cmd(acp_agent, log)
                 return
-        elif auth_mode == "subscription" and provider and model:
-            self._direct_auth_mode = "subscription"
+        elif (
+            provider
+            and model
+            and not after_auth
+            and (auth_mode == "subscription" or category in {"models", "plan"})
+        ):
+            saved_harness = str(connection.get("harness_id") or "")
+            if saved_harness:
+                from superqode.providers.dynamic import resolve_provider_def
+                from superqode.providers.credentials import provider_api_key
+                from superqode.pure_mode import PureMode
+
+                definition = resolve_provider_def(provider)
+                # Let the normal connector explain missing credentials without
+                # replacing the active harness first.
+                if definition and definition.env_vars and not provider_api_key(definition):
+                    self._connect_byok_mode(provider, model, log)
+                    return
+                try:
+                    pure = getattr(self, "_pure_mode", None) or PureMode()
+                    pure.select_harness(saved_harness)
+                except (FileNotFoundError, ValueError) as exc:
+                    log.add_error(f"Cannot restore harness {saved_harness}: {exc}")
+                    return
+                self._pure_mode = pure
+                os.environ["SUPERQODE_HARNESS"] = saved_harness
+            self._direct_auth_mode = auth_mode
             self._direct_connection_profile_id = profile_id
             self._connect_byok_mode(provider, model, log)
             return
@@ -3613,6 +3755,10 @@ class ConnectMixin:
                 badges = profile.badges
                 if is_highlighted and badges:
                     append_wrapped(" · ".join(badges), THEME["dim"])
+                if is_highlighted and profile.available and profile.verify_on_connect:
+                    append_wrapped(
+                        "Installed · account sign-in is verified on first use", THEME["muted"]
+                    )
                 if is_highlighted and not profile.available and profile.unavailable_hint:
                     append_wrapped(profile.unavailable_hint, THEME["warning"])
 
@@ -4205,7 +4351,7 @@ class ConnectMixin:
             profile_id=profile_id,
             acp_agent=acp_agent,
             openness="",
-            provider=str(getattr(self, "current_provider", "") or ""),
+            provider="",
             model=str(getattr(self, "current_model", "") or ""),
             transport="ACP",
             after_auth="",

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/commands/acp.py

@@ -460,13 +460,9 @@ def validate_agent_environment(agent: "Agent") -> list[str]:
     agent_name = agent.get("short_name", "").lower()
 
     # Define known environment variable requirements for agents
-    env_requirements = {
-        "claude": ["ANTHROPIC_API_KEY"],
-        "opencode": ["ZHIPUAI_API_KEY"],  # GLM-4.7 uses ZHIPUAI
-        "gemini": ["GOOGLE_API_KEY"],
-        "openai": ["OPENAI_API_KEY"],
-        "kimi": ["MOONSHOT_API_KEY"],
-    }
+    # Many agents support account sign-in and local models without API keys.
+    # Require only variables explicitly declared by this configured agent.
+    env_requirements = {agent_name: agent.get("required_env", [])}
 
     # Check if agent requires specific environment variables
     if agent_name in env_requirements:
@@ -625,7 +621,12 @@ async def connect_to_agent(agent_identifier: str, project_dir: str | None = None
     try:
         # Connect to the agent
         cwd = project_dir or os.getcwd()
-        success = await manager.connect_to_agent(run_command, cwd)
+        launch_env = agent.get("launch_env") or {}
+        success = (
+            await manager.connect_to_agent(run_command, cwd, extra_env=launch_env)
+            if launch_env
+            else await manager.connect_to_agent(run_command, cwd)
+        )
 
         if not success:
             _console.print(f"[red]Failed to connect to {agent['name']}.[/red]")

{superqode-2.4.29 → superqode-2.4.30}/src/superqode/harness/hub.py

@@ -7,7 +7,11 @@ from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any, Iterable
 
-from superqode.app.harness_picker import HarnessPickerItem, harness_picker_items
+from superqode.app.harness_picker import (
+    HarnessPickerItem,
+    harness_picker_items,
+    harness_source_extra,
+)
 
 
 HUB_SCHEMA_VERSION = "1.7"
@@ -97,6 +101,7 @@ def readiness_label(readiness: str) -> str:
 
 
 _DOCS_BY_ID = {
+    "gemini-cli": "https://geminicli.com/docs/get-started/authentication/",
     "codex": f"{DOCS_BASE}providers/codex/",
     "claude": f"{DOCS_BASE}providers/anthropic-claude/",
     "antigravity": f"{DOCS_BASE}providers/antigravity/",
@@ -121,6 +126,7 @@ _DOCS_BY_ID = {
 }
 
 _HOMEPAGE_BY_ID = {
+    "gemini-cli": "https://geminicli.com/",
     "codex": "https://openai.com/codex/",
     "claude": "https://www.anthropic.com/claude-code",
     "cursor": "https://cursor.com/",
@@ -193,6 +199,7 @@ _PROJECT_OPENNESS = HubOpenness("open", "Apache-2.0", PROJECT_REPOSITORY)
 #
 _LANGCHAIN_DEEPAGENTS = HubOpenness("open", "MIT", "https://github.com/langchain-ai/deepagents")
 _OPENNESS_BY_ID: dict[str, HubOpenness] = {
+    "gemini-cli": HubOpenness("open", "Apache-2.0", "https://github.com/google-gemini/gemini-cli"),
     "deepagents": _LANGCHAIN_DEEPAGENTS,
     "deepagents-code": _LANGCHAIN_DEEPAGENTS,
     "acp:deepagents": _LANGCHAIN_DEEPAGENTS,
@@ -766,6 +773,14 @@ class HubSetupStep:
 
 
 _SETUP_STEPS_BY_ID = {
+    "gemini-cli": (
+        HubSetupStep("Install Gemini CLI", "npm install -g @google/gemini-cli"),
+        HubSetupStep(
+            "Sign in with your Google plan account",
+            "gemini",
+            "Choose Sign in with Google for Google AI Pro / Ultra or Code Assist.",
+        ),
+    ),
     "codex": (
         HubSetupStep(
             "Install the SuperQode Codex integration",
@@ -1577,10 +1592,13 @@ def hub_record(
     details = (
         _connection_details(item) if item.kind in {"connection", "acp"} else _native_details(item)
     )
-    if portable_install_commands and item.install_extra:
+    # A public catalog must carry installation instructions even when the
+    # exporting machine already has this optional integration installed.
+    portable_extra = item.install_extra or harness_source_extra(item)
+    if portable_install_commands and portable_extra:
         from superqode.providers.env_introspect import install_command
 
-        command = install_command(item.install_extra)
+        command = install_command(portable_extra)
         details = {
             **details,
             "install_command": command,