Google OAuth Integration

This skill documents the complete Google OAuth integration architecture in Orient, including token storage, tool registration, and debugging procedures.

Triggers

Use this skill when:

• Setting up Google OAuth for a new package or service
• Debugging "Unknown tool" errors for Google tools (Calendar, Gmail, Tasks)
• Understanding token storage and refresh mechanics
• Adding new Google service tools to the ToolExecutorRegistry

Token Storage Architecture

Token File Location

Google OAuth tokens are stored in JSON files at:

{cwd}/data/oauth-tokens/google-oauth.json

CRITICAL: The path is resolved using process.cwd(), meaning different packages look in different locations:

• Dashboard: packages/dashboard/data/oauth-tokens/google-oauth.json
• Slack bot: packages/bot-slack/data/oauth-tokens/google-oauth.json
• WhatsApp bot: packages/bot-whatsapp/data/oauth-tokens/google-oauth.json
• Project root: data/oauth-tokens/google-oauth.json

Symlink Setup (Required for Multi-Package Access)

Since the dashboard is typically where users connect their Google accounts, other packages need symlinks to access the same tokens:

# For bot-slack
mkdir -p packages/bot-slack/data/oauth-tokens
ln -sf $(pwd)/packages/dashboard/data/oauth-tokens/google-oauth.json \
       packages/bot-slack/data/oauth-tokens/google-oauth.json

# For bot-whatsapp
mkdir -p packages/bot-whatsapp/data/oauth-tokens
ln -sf $(pwd)/packages/dashboard/data/oauth-tokens/google-oauth.json \
       packages/bot-whatsapp/data/oauth-tokens/google-oauth.json

# For project root (used by MCP servers)
mkdir -p data/oauth-tokens
ln -sf $(pwd)/packages/dashboard/data/oauth-tokens/google-oauth.json \
       data/oauth-tokens/google-oauth.json

Token File Structure

{
  "accounts": {
    "user@gmail.com": {
      "email": "user@gmail.com",
      "displayName": "User Name",
      "accessToken": "ya29...",
      "refreshToken": "1//...",
      "expiresAt": 1768578677699,
      "scopes": [
        "https://www.googleapis.com/auth/calendar",
        "https://www.googleapis.com/auth/gmail.modify"
      ],
      "connectedAt": 1768552923717,
      "lastRefreshAt": 1768575078699
    }
  },
  "pendingStates": {}
}

Environment Variables

Required environment variables in .env:

# OAuth Client Credentials (from Google Cloud Console)
GOOGLE_OAUTH_CLIENT_ID=<your-client-id>.apps.googleusercontent.com
GOOGLE_OAUTH_CLIENT_SECRET=GOCSPX-<your-secret>

# Callback URL (must match Google Cloud Console)
GOOGLE_OAUTH_CALLBACK_URL=http://localhost/api/auth/google/callback

The OAuth service loads credentials in this priority order:

1. Secrets database (GOOGLE_OAUTH_CLIENT_ID, GOOGLE_OAUTH_CLIENT_SECRET)
2. Environment variables
3. Credentials file: credentials/client_secret_*.json

Tool Registration Architecture

Two Registration Systems

Orient has two tool registration systems:

1. ToolRegistry (Discovery only)

   • Location: packages/agents/src/services/toolRegistry.ts
   • Used by: discover_tools for listing available tools
   • Does NOT execute tools

2. ToolExecutorRegistry (Execution)

   • Location: packages/agents/src/services/toolRegistry.ts
   • Used by: executeToolCallFromRegistry() in packages/mcp-servers/src/tool-executor.ts
   • Actually runs the tool code

Registering New Google Tools

To add a new Google tool, register it in the registerGoogleToolHandlers() function:

// In packages/agents/src/services/toolRegistry.ts

function registerGoogleToolHandlers(registry: ToolExecutorRegistry): void {
  const registerHandlers = async () => {
    const { getCalendarService, getGoogleOAuthService } =
      await import('@orientbot/integrations/google');

    // Register handler
    registry.registerHandler('google_calendar_list_events', async (args) => {
      const calendar = getCalendarService();
      const events = await calendar.listEvents(options, accountEmail);
      return createToolResult(JSON.stringify(events, null, 2));
    });
  };

  void registerHandlers();
}

Legacy vs Modern Registration

Important: The assistant-server (used by Slack/WhatsApp bots) uses base-server.ts which ONLY uses ToolExecutorRegistry. It does NOT fall back to the legacy switch statement unless setLegacyExecutor() is called.

Token Refresh Mechanics

The OAuth service in packages/integrations/src/google/oauth.ts handles automatic token refresh:

async getAuthClient(email: string): Promise<Auth.OAuth2Client> {
  const account = this.data.accounts[email];

  // Check if token needs refresh (expired or expiring in < 5 min)
  if (Date.now() > account.expiresAt - 5 * 60 * 1000) {
    const { credentials } = await client.refreshAccessToken();
    account.accessToken = credentials.access_token;
    account.expiresAt = credentials.expiry_date;
    this.saveData();
  }

  return client;
}

Key points:

• Tokens are refreshed automatically 5 minutes before expiration
• Requires valid refresh_token from initial OAuth consent
• Requires OAuth credentials (client ID/secret) to be accessible

Debugging "Unknown Tool" Errors

When Google tools return {"error":"Unknown tool: google_calendar_list_events"}:

Step 1: Check Tool Discovery

# Tool should appear in discover_tools output
curl -X POST http://localhost:4099/... -d '{"tool":"discover_tools","args":{"mode":"search","query":"calendar"}}'

If tool appears in discovery but not execution, it's registered in ToolRegistry but not ToolExecutorRegistry.

Step 2: Check ToolExecutorRegistry Registration

Look for the tool in packages/agents/src/services/toolRegistry.ts:

// Should see this in registerGoogleToolHandlers():
registry.registerHandler('google_calendar_list_events', async (args) => { ... });

Step 3: Verify Build and Restart

# Rebuild affected packages
pnpm --filter @orientbot/agents build
pnpm --filter @orientbot/mcp-servers build

# Copy to root dist (used by OpenCode)
cp packages/mcp-servers/dist/*.js dist/mcp-servers/

# Kill existing MCP server processes
ps aux | grep "assistant-server\|coding-server" | grep -v grep | awk '{print $2}' | xargs kill

# OpenCode will spawn fresh processes on next tool call

Step 4: Check MCP Server Logs

tail -f logs/mcp-debug-*.log | grep -i "calendar\|google\|unknown"

Look for:

• "Registered tool" - Tool was registered
• "Unknown tool" - Tool not found in any executor
• Error messages during handler registration

Common Issues

Issue: Tokens not found

Symptom: "No Google account connected" Cause: Token file not found at CWD path Fix: Create symlinks as documented above

Issue: Token refresh fails

Symptom: "Failed to refresh token" Cause: OAuth credentials not accessible Fix: Ensure GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET are set

Issue: Tool returns "Unknown tool"

Symptom: {"error":"Unknown tool: google_calendar_list_events"} Cause: Tool not registered in ToolExecutorRegistry Fix: Add handler in registerGoogleToolHandlers() and rebuild

Issue: Stale MCP server

Symptom: Changes not taking effect Cause: Old MCP server process still running Fix: Kill old processes, OpenCode will spawn new ones

Files Reference