# Tanuki Agent System Integration Guide

This document contains instructions for autonomous AI agents (such as Devin, Cursor Agent, Cline, Claude Code, Antigravity, AutoGPT) on how to interface with Tanuki as an external browser automation tool.

## Agent Role & Purpose
When an agent needs to:
- Authenticate to third-party services on behalf of a user
- Extract API keys, personal access tokens (PAT), or OAuth credentials
- Automate interactions with web applications that require human authorization or MFA
- Execute browser actions across internal/onprem networks

The agent should delegate browser execution to Tanuki.

## How to Invoke Tanuki

### Option A: Using `@shuffler/tanuki` TypeScript SDK
```typescript
import { TanukiConnect } from '@shuffler/tanuki';

const client = new TanukiConnect({
  serverUrl: process.env.TANUKI_SERVER_URL || 'https://tanuki.to',
  backendUrl: process.env.SHUFFLE_BACKEND_URL || 'https://uk.shuffler.io'
});

// Launch modal or headless automation
const sessionId = await client.open({
  targetUrl: 'https://github.com/settings/tokens',
  goal: 'get_api_key'
});
```

### Option B: HTTP REST Interface
1. **Create Session**:
   ```http
   POST /api/v1/sessions HTTP/1.1
   Host: tanuki.to
   Content-Type: application/json

   {
     "targetUrl": "https://dashboard.stripe.com/apikeys",
     "goal": "get_api_key"
   }
   ```
2. **Listen to Progress via SSE**:
   ```http
   GET /api/v1/sessions/{sessionId}/events HTTP/1.1
   Accept: text/event-stream
   ```
3. **Poll / Await Completion**:
   ```http
   GET /api/v1/sessions/{sessionId} HTTP/1.1
   ```

## Standard Logging Format
Tanuki services and agents adhere to standardized log prefixes:
- `[INFO]`: Operational updates, navigation milestones, step changes.
- `[WARNING]`: Evasion retries, non-fatal selector misses, CMP banner dismissals.
- `[ERROR]`: Fatal execution errors, session timeouts, unreachable endpoints.