from gaia.connectors.registry import REGISTRY

for spec in REGISTRY.all():
    print(spec.id, spec.type, spec.display_name)
# google         oauth_pkce   Google
# github         mcp_server   GitHub
# brave          mcp_server   Brave Search
# ...

import asyncio
import gaia.connectors as conn


async def main():
    # 1. Run the OAuth PKCE flow (opens system browser).
    info = await conn.start_authorization(
        "google",
        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
    )
    print("Open this URL:", info["authorization_url"])
    state = await conn.complete_authorization(info["flow_id"])
    print("Connected as", state["account_email"])

    # 2. Grant a named agent the scopes it needs.
    conn.grant_agent(
        connector_id="google",
        agent_id="my-agent",
        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
    )

    # A grant cannot exceed what the connector's catalog entry advertises: a
    # scope outside `available_scopes` raises ScopeNotAllowedError, and an
    # unknown connector id raises UnknownConnectorError (both subclass
    # ConnectorsError). Revoking is never gated this way — taking access away
    # always works, even for a connector that has left the catalog.

    # 3. Fetch a short-lived access token (refresh is automatic).
    #    Always name the scopes you need: a call that names none is refused
    #    rather than silently skipping the grant check.
    token = await conn.get_access_token(
        provider="google",
        scopes=["https://www.googleapis.com/auth/gmail.readonly"],
        agent_id="my-agent",
    )
    print("Bearer token:", token[:8], "…")


asyncio.run(main())

import gaia.connectors as conn

summary = conn.import_forwarded_connection(
    provider="google",
    client_id="<host-app-client-id>.apps.googleusercontent.com",
    client_secret="<host-app-client-secret>",
    refresh_token="<user-refresh-token>",
    scopes=[
        "https://www.googleapis.com/auth/gmail.modify",
        "https://www.googleapis.com/auth/gmail.send",
        "https://www.googleapis.com/auth/calendar.events",
    ],
    account_email="[email protected]",   # display-only in v1
    grant_agents=["installed:gaia"],        # agents that may use it
)
# summary carries metadata only — never the refresh token or client secret.

curl -X POST http://localhost:4200/v1/connections/google \
  -H "X-Gaia-UI: 1" -H "Content-Type: application/json" \
  -d '{
        "client_id": "<host-app-client-id>",
        "client_secret": "<host-app-client-secret>",
        "refresh_token": "<user-refresh-token>",
        "scopes": ["https://www.googleapis.com/auth/gmail.modify",
                   "https://www.googleapis.com/auth/gmail.send",
                   "https://www.googleapis.com/auth/calendar.events"],
        "account_email": "[email protected]",
        "grant_agents": ["installed:gaia"]
      }'

from gaia.connectors.handler import configure, get_credential

# Configure — stores the key in the OS keyring.
await configure("mcp-github", {"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."})

# Retrieve — used by the MCP bridge to launch the server.
creds = await get_credential("mcp-github")
# {"env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."}, "command": "npx", "args": [...]}

# OAuth: connect and authorize
gaia connectors connect google \
    --scopes https://www.googleapis.com/auth/gmail.readonly

# MCP: supply API key(s)
gaia connectors configure mcp-github --set GITHUB_PERSONAL_ACCESS_TOKEN=ghp_…
gaia connectors configure brave  --set BRAVE_API_KEY=BSA…

# Check status of all connectors
gaia connectors status
#  google                          [oauth_pkce]  configured ([email protected])
#  github                          [mcp_server]  configured
#  brave                           [mcp_server]  not configured

# Test health of a configured connector
gaia connectors test github

# Per-agent grants (every connector type)
gaia connectors grants grant google builtin:chat \
    --scopes https://www.googleapis.com/auth/gmail.readonly
gaia connectors grants list google
gaia connectors grants revoke google builtin:chat

# `grant` exits 1 if the scope is outside the connector's available_scopes or
# the connector id is not in the catalog — `gaia connectors list` shows the
# ids, `gaia connectors list <id>` its scopes. `revoke` is never gated that
# way: taking access away always works.

# NOTE: the Agent UI grants on connect (#2117): POST
# /api/connectors/{id}/authorize accepts grant_agents (namespaced agent
# ids); the router resolves each agent's REQUIRED_CONNECTORS scopes and
# the OAuth callback commits the grants the moment the token exchange
# succeeds. Explicit CLI grants remain the path for scripts and headless
# setups.

# Per-agent activations — gate which agents see this MCP server's tools.
# Activations apply to mcp_server connectors only; OAuth connectors are
# rejected with exit 3 (use per-scope grants above instead).
gaia connectors activations activate mcp-github builtin:chat \
    --scopes use   # --scopes is only consulted when no prior grant exists
gaia connectors activations list mcp-github
gaia connectors activations deactivate mcp-github builtin:chat

# Disconnect
gaia connectors disconnect google

from typing import ClassVar, List
from gaia.agents.base.agent import Agent
from gaia.connectors import ConnectorRequirement, get_access_token_sync
from gaia.agents.base.tools import tool


class GmailAgent(Agent):
    AGENT_ID = "gmail_demo"
    AGENT_NAME = "Gmail Demo"
    AGENT_DESCRIPTION = "Lists 5 newest Gmail subjects."
    CONVERSATION_STARTERS = ["List my newest emails"]

    REQUIRED_CONNECTORS: ClassVar[List[ConnectorRequirement]] = [
        ConnectorRequirement(
            connector_id="google",
            scopes=["https://www.googleapis.com/auth/gmail.readonly"],
            reason="Read your inbox to summarize the 5 newest messages",
        ),
    ]

    def _register_tools(self):
        self._register("list_recent_subjects", self._list_recent_subjects)

    @tool()
    def _list_recent_subjects(self) -> list[str]:
        """List the 5 newest Gmail subjects."""
        token = get_access_token_sync(
            provider="google",
            scopes=["https://www.googleapis.com/auth/gmail.readonly"],
        )
        import requests
        r = requests.get(
            "https://gmail.googleapis.com/gmail/v1/users/me/messages",
            params={"maxResults": 5},
            headers={"Authorization": f"Bearer {token}"},
            timeout=10,
        )
        r.raise_for_status()
        return [m["id"] for m in r.json().get("messages", [])]

class MyAgent(Agent):
    CONSUMES_MCP_SERVERS: ClassVar[bool] = True

grant exists for (connector_id, agent_id)  AND  is_agent_active(...)

from gaia.connectors import activate, deactivate

# Activate (auto-grants if no prior grant exists). mcp-github is the
# catalog id for the GitHub MCP server; activations only accept
# mcp_server connectors.
activate("mcp-github", "builtin:chat", scopes_for_grant=["use"])

# Deactivate (preserves grant — re-activate is one click)
deactivate("mcp-github", "builtin:chat")

gaia connectors activations activate mcp-github builtin:chat --scopes use
gaia connectors activations list mcp-github
gaia connectors activations deactivate mcp-github builtin:chat

GET    /api/connectors/{id}/activations
PUT    /api/connectors/{id}/activations/{agent_id}     # body: {"scopes": [...]}?
DELETE /api/connectors/{id}/activations/{agent_id}

_MY_SERVICE = ConnectorSpec(
    id="mcp-my-service",
    display_name="My Service",
    icon="🔌",
    category="dev-tools",
    tier=1,
    type="mcp_server",
    description="Integrates My Service via MCP.",
    mcp_command="npx",
    mcp_args=("-y", "@my/[email protected]"),
    mcp_env_keys=("MY_SERVICE_API_KEY",),
    config_schema=(
        ConfigField(
            key="MY_SERVICE_API_KEY",
            label="My Service API Key",
            kind="secret",
            secret=True,
        ),
    ),
)