thebird 1.2.3 → 1.2.5

package/CLAUDE.md

@@ -0,0 +1,116 @@
+# thebird Development Notes
+
+## Architecture Overview
+
+**thebird** is an Anthropic SDK adapter that translates message format and tool calls to multiple LLM providers (Gemini, OpenAI-compatible APIs). It's a drop-in bridge — you write Anthropic-format code, thebird routes to any provider.
+
+### Message Translation
+
+Anthropic format:
+```js
+[{ role: 'user', content: [
+  { type: 'text', text: '...' },
+  { type: 'image', source: { type: 'base64', media_type: 'image/png', data: '...' } }
+] }]
+```
+
+Translates to provider-native format:
+- **Gemini**: `parts: [{ text: '...' }, { inlineData: { mimeType: '...', data: '...' } }]`
+- **OpenAI**: `content: [{ type: 'text', text: '...' }, { type: 'image_url', image_url: { url: '...' } }]`
+
+### Tool Calling
+
+Anthropic tool schema → provider native → normalized response back to Anthropic format.
+
+Streaming events (all events are Anthropic-compatible):
+- `text-delta`, `tool-use-start`, `tool-use-delta`, `message-start`, `message-stop`
+
+### Routing (Multi-Provider)
+
+`createRouter()` picks provider+model per request based on:
+1. `taskType` (e.g., 'think', 'background', 'longContext')
+2. Token count vs `longContextThreshold`
+
+Routes are defined as `provider,model` strings in config.
+
+### Transformers
+
+Some providers need field adjustments:
+- `deepseek`: strips `cache_control`, `repetition_penalty`
+- `groq`: removes `top_k`
+- `reasoning`: moves `reasoning_content` to `_reasoning`
+
+Applied automatically during request building.
+
+## gembird — Image Generation via Browser
+
+**gembird** generates 4-view product images (front, back, left-side, right-side) using Gemini's web UI.
+
+### Why Browser Automation?
+
+Gemini API free tier has 0 quota for image generation. Web UI works without limits. Tradeoff: slower than API, depends on UI stability, but no quota needed.
+
+### Workflow
+
+1. Playwright CDP connection to Chrome on `localhost:9222`
+2. Navigate to gemini.google.com
+3. For each view:
+   - Type prompt asking for that view
+   - Poll for new `<img alt="AI generated">` (120s timeout)
+   - Extract via canvas: `canvas.drawImage(img) → canvas.toDataURL('image/png')`
+   - POST base64 to local HTTP save server
+4. Save 4 PNGs to output dir
+
+### CLI
+
+```bash
+node index.js "prompt"
+node index.js --image ref.png "prompt"
+node index.js --output ./dir "prompt"
+```
+
+Arguments parsed in index.js lines 144-172.
+
+### Observability
+
+- Chrome console logs Gemini errors
+- 120s timeout is conservative; real generation ~30-60s
+- If extraction fails, check `img[alt*="AI generated"]` selector
+
+## Development Constraints
+
+- Max 200 lines per file (split before hitting limit)
+- No comments
+- No test files
+- No hardcoded values
+- Errors throw with context (no silent failures)
+- Messages must stay Anthropic-compatible (other code depends on this contract)
+- Tool schemas must translate cleanly to all providers
+
+## Testing
+
+No test files. Validation via:
+- `examples/basic-chat.js`: Single-turn Anthropic format → Gemini
+- `examples/streaming.js`: Streaming events
+- `examples/tool-use.js`: Tool calling and tool result handling
+- `examples/vision.js`: Image blocks (base64, URL, inline)
+- `examples/multi-turn.js`: Multi-turn chat with context
+
+Run examples against real Gemini API to validate message translation.
+
+## Known Issues & Workarounds
+
+- Gemini API doesn't support `tool_choice: 'required'` — treated as `'auto'`
+- Some models have different tool naming conventions — check provider docs
+- Streaming response parsing varies by provider — see lib/providers/ for details
+- OAuth tokens expire — gembird uses browser session instead of capturing tokens
+
+## Files
+
+- `lib/convert.js`: Message/tool translation logic
+- `lib/client.js`: Provider client factory
+- `lib/errors.js`: Error handling and retry logic
+- `lib/providers/`: Provider-specific streaming implementations
+- `index.js`: Main entry point, streaming and generation wrappers
+- `index.d.ts`: TypeScript type definitions
+- `examples/`: Working examples using Anthropic SDK format

package/index.js

@@ -170,4 +170,7 @@ async function generateRouter(params) {
   return createRouter(config).generate(params);
 }
 
-module.exports = { streamGemini, generateGemini, streamRouter, generateRouter, createRouter, convertMessages, convertTools, cleanSchema, GeminiError };
+const { cloudGenerate, streamCloud, cloudStream } = require('./lib/cloud-generate');
+const { ensureAuth, login: oauthLogin } = require('./lib/oauth');
+
+module.exports = { streamGemini, generateGemini, streamRouter, generateRouter, createRouter, convertMessages, convertTools, cleanSchema, GeminiError, cloudGenerate, streamCloud, cloudStream, ensureAuth, oauthLogin };

package/lib/cloud-generate.js

@@ -0,0 +1,119 @@
+const { convertMessages, convertTools, cleanSchema, extractModelId, buildConfig } = require('./convert');
+const { ensureAuth, CODE_ASSIST_BASE, CODE_ASSIST_HEADERS } = require('./oauth');
+const crypto = require('crypto');
+
+function buildUserAgent(model) {
+  return `gemini-cli/0.30.0 (node; ${process.platform}) model/${model || 'unknown'}`;
+}
+
+async function cloudGenerate({ model, system, messages, tools, temperature, maxOutputTokens, topP, topK, safetySettings, responseModalities, authPort }) {
+  const tokens = await ensureAuth(authPort);
+  const modelId = extractModelId(model);
+  const contents = convertMessages(messages);
+  const { config } = buildConfig({ system, tools, temperature, maxOutputTokens, topP, topK, safetySettings, responseModalities });
+
+  const request = { contents };
+  if (config.systemInstruction) request.systemInstruction = { parts: [{ text: config.systemInstruction }] };
+  if (config.tools) request.tools = config.tools;
+  const genConfig = {};
+  if (config.maxOutputTokens) genConfig.maxOutputTokens = config.maxOutputTokens;
+  if (config.temperature != null) genConfig.temperature = config.temperature;
+  if (config.topP != null) genConfig.topP = config.topP;
+  if (config.topK != null) genConfig.topK = config.topK;
+  if (config.responseModalities) genConfig.responseModalities = config.responseModalities;
+  if (Object.keys(genConfig).length) request.generationConfig = genConfig;
+
+  const envelope = { project: tokens.projectId, model: modelId, user_prompt_id: crypto.randomUUID(), request };
+
+  const res = await fetch(`${CODE_ASSIST_BASE}:generateContent`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${tokens.accessToken}`,
+      'User-Agent': buildUserAgent(modelId),
+      'x-activity-request-id': crypto.randomUUID(),
+      ...CODE_ASSIST_HEADERS
+    },
+    body: JSON.stringify(envelope)
+  });
+
+  if (!res.ok) throw new Error(`Cloud generate failed (${res.status}): ${await res.text()}`);
+  const data = await res.json();
+  const inner = data.response || data;
+  const candidate = inner.candidates?.[0];
+  if (!candidate) throw new Error('No candidates returned');
+  const allParts = candidate.content?.parts || [];
+  const text = allParts.filter(p => p.text && !p.thought).map(p => p.text).join('');
+  return { text, parts: allParts, response: inner };
+}
+
+async function* cloudStream({ model, system, messages, tools, onStepFinish, temperature, maxOutputTokens, topP, topK, safetySettings, responseModalities, authPort }) {
+  const tokens = await ensureAuth(authPort);
+  const modelId = extractModelId(model);
+  const contents = convertMessages(messages);
+  const { config } = buildConfig({ system, tools, temperature, maxOutputTokens, topP, topK, safetySettings, responseModalities });
+
+  const request = { contents };
+  if (config.systemInstruction) request.systemInstruction = { parts: [{ text: config.systemInstruction }] };
+  if (config.tools) request.tools = config.tools;
+  const genConfig = {};
+  if (config.maxOutputTokens) genConfig.maxOutputTokens = config.maxOutputTokens;
+  if (config.temperature != null) genConfig.temperature = config.temperature;
+  if (config.topP != null) genConfig.topP = config.topP;
+  if (config.topK != null) genConfig.topK = config.topK;
+  if (config.responseModalities) genConfig.responseModalities = config.responseModalities;
+  if (Object.keys(genConfig).length) request.generationConfig = genConfig;
+
+  const envelope = { project: tokens.projectId, model: modelId, user_prompt_id: crypto.randomUUID(), request };
+
+  const res = await fetch(`${CODE_ASSIST_BASE}:streamGenerateContent?alt=sse`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${tokens.accessToken}`,
+      'User-Agent': buildUserAgent(modelId),
+      'x-activity-request-id': crypto.randomUUID(),
+      Accept: 'text/event-stream',
+      ...CODE_ASSIST_HEADERS
+    },
+    body: JSON.stringify(envelope)
+  });
+
+  if (!res.ok) throw new Error(`Cloud stream failed (${res.status}): ${await res.text()}`);
+
+  yield { type: 'start-step' };
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('data:')) continue;
+      const json = trimmed.slice(5).trim();
+      if (!json || json === '[DONE]') continue;
+      try {
+        const parsed = JSON.parse(json);
+        const inner = parsed.response || parsed;
+        const parts = inner.candidates?.[0]?.content?.parts || [];
+        for (const part of parts) {
+          if (part.text && !part.thought) yield { type: 'text-delta', textDelta: part.text };
+          if (part.inlineData) yield { type: 'image-data', inlineData: part.inlineData };
+        }
+      } catch {}
+    }
+  }
+  yield { type: 'finish-step', finishReason: 'stop' };
+  if (onStepFinish) await onStepFinish();
+}
+
+function streamCloud(params) {
+  return { fullStream: cloudStream(params), warnings: Promise.resolve([]) };
+}
+
+module.exports = { cloudGenerate, cloudStream, streamCloud };

package/lib/oauth.js

@@ -0,0 +1,133 @@
+const http = require('http');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const CLIENT_ID = process.env.GOOGLE_OAUTH_CLIENT_ID || '';
+const CLIENT_SECRET = process.env.GOOGLE_OAUTH_CLIENT_SECRET || '';
+const SCOPES = 'https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile';
+const AUTH_URL = 'https://accounts.google.com/o/oauth2/v2/auth';
+const TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const CODE_ASSIST_BASE = 'https://cloudcode-pa.googleapis.com/v1internal';
+const CODE_ASSIST_HEADERS = { 'X-Goog-Api-Client': 'gl-node/22.17.0', 'Client-Metadata': 'ideType=IDE_UNSPECIFIED,platform=PLATFORM_UNSPECIFIED,pluginType=GEMINI' };
+const TOKEN_PATH = path.join(process.env.HOME || process.env.USERPROFILE || '.', '.thebird', 'oauth-tokens.json');
+
+function base64url(buf) {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function generatePkce() {
+  const verifier = base64url(crypto.randomBytes(32));
+  const challenge = base64url(crypto.createHash('sha256').update(verifier).digest());
+  return { verifier, challenge };
+}
+
+function readTokens() {
+  try { return JSON.parse(fs.readFileSync(TOKEN_PATH, 'utf8')); } catch { return null; }
+}
+
+function writeTokens(tokens) {
+  fs.mkdirSync(path.dirname(TOKEN_PATH), { recursive: true });
+  fs.writeFileSync(TOKEN_PATH, JSON.stringify(tokens, null, 2));
+}
+
+async function refreshAccessToken(refreshToken) {
+  const res = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: CLIENT_ID, client_secret: CLIENT_SECRET })
+  });
+  if (!res.ok) throw new Error('Token refresh failed: ' + await res.text());
+  const data = await res.json();
+  return { accessToken: data.access_token, refreshToken: data.refresh_token || refreshToken, expiresAt: Date.now() + data.expires_in * 1000 };
+}
+
+async function getValidToken() {
+  const tokens = readTokens();
+  if (!tokens?.refreshToken) return null;
+  if (tokens.expiresAt && tokens.expiresAt > Date.now() + 60000) return tokens;
+  const refreshed = await refreshAccessToken(tokens.refreshToken);
+  const updated = { ...tokens, ...refreshed };
+  writeTokens(updated);
+  return updated;
+}
+
+async function resolveProject(accessToken) {
+  const res = await fetch(`${CODE_ASSIST_BASE}:loadCodeAssist`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${accessToken}`, ...CODE_ASSIST_HEADERS },
+    body: JSON.stringify({ metadata: { ideType: 'IDE_UNSPECIFIED', platform: 'PLATFORM_UNSPECIFIED', pluginType: 'GEMINI' } })
+  });
+  if (!res.ok) throw new Error('Failed to load Code Assist project');
+  const data = await res.json();
+  const proj = data.cloudaicompanionProject;
+  if (proj) return typeof proj === 'string' ? proj : proj.id;
+  const tier = data.allowedTiers?.find(t => t.id === 'free-tier') || data.allowedTiers?.[0];
+  if (!tier) throw new Error('No eligible tier: ' + (data.ineligibleTiers?.[0]?.reasonMessage || 'unknown'));
+  const obRes = await fetch(`${CODE_ASSIST_BASE}:onboardUser`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${accessToken}`, ...CODE_ASSIST_HEADERS },
+    body: JSON.stringify({ tierId: tier.id || 'legacy-tier', metadata: { ideType: 'IDE_UNSPECIFIED', platform: 'PLATFORM_UNSPECIFIED', pluginType: 'GEMINI' } })
+  });
+  if (!obRes.ok) throw new Error('Onboarding failed');
+  let op = await obRes.json();
+  for (let i = 0; i < 10 && !op.done && op.name; i++) {
+    await new Promise(r => setTimeout(r, 5000));
+    const pollRes = await fetch(`${CODE_ASSIST_BASE}/${op.name}`, { headers: { Authorization: `Bearer ${accessToken}`, ...CODE_ASSIST_HEADERS } });
+    if (pollRes.ok) op = await pollRes.json();
+  }
+  return op.response?.cloudaicompanionProject?.id;
+}
+
+function login(port) {
+  return new Promise((resolve, reject) => {
+    const { verifier, challenge } = generatePkce();
+    const state = crypto.randomBytes(32).toString('hex');
+    const callbackUrl = `http://localhost:${port}/callback`;
+    const url = new URL(AUTH_URL);
+    url.searchParams.set('client_id', CLIENT_ID);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('redirect_uri', callbackUrl);
+    url.searchParams.set('scope', SCOPES);
+    url.searchParams.set('code_challenge', challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('state', state);
+    url.searchParams.set('access_type', 'offline');
+    url.searchParams.set('prompt', 'consent');
+
+    const server = http.createServer(async (req, res) => {
+      const u = new URL(req.url, `http://localhost:${port}`);
+      if (!u.pathname.startsWith('/callback')) { res.end('waiting...'); return; }
+      if (u.searchParams.get('state') !== state) { res.end('Invalid state'); server.close(); reject(new Error('Invalid state')); return; }
+      const code = u.searchParams.get('code');
+      try {
+        const tokRes = await fetch(TOKEN_URL, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+          body: new URLSearchParams({ client_id: CLIENT_ID, client_secret: CLIENT_SECRET, code, grant_type: 'authorization_code', redirect_uri: callbackUrl, code_verifier: verifier })
+        });
+        if (!tokRes.ok) throw new Error('Token exchange failed: ' + await tokRes.text());
+        const payload = await tokRes.json();
+        if (!payload.refresh_token) throw new Error('No refresh token — ensure prompt=consent');
+        const projectId = await resolveProject(payload.access_token);
+        const tokens = { accessToken: payload.access_token, refreshToken: payload.refresh_token, expiresAt: Date.now() + payload.expires_in * 1000, projectId };
+        writeTokens(tokens);
+        res.end('Authenticated! You can close this tab.');
+        server.close();
+        resolve(tokens);
+      } catch (e) { res.end('Error: ' + e.message); server.close(); reject(e); }
+    });
+    server.listen(port, () => {
+      console.log(`Open this URL to authenticate:\n${url.toString()}\n`);
+      try { const { exec } = require('child_process'); exec(`start "" "${url.toString()}"`); } catch {}
+    });
+  });
+}
+
+async function ensureAuth(port) {
+  const existing = await getValidToken();
+  if (existing?.accessToken && existing?.projectId) return existing;
+  return login(port || 8585);
+}
+
+module.exports = { login, ensureAuth, getValidToken, readTokens, writeTokens, resolveProject, CODE_ASSIST_BASE, CODE_ASSIST_HEADERS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thebird",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Anthropic SDK to Gemini streaming bridge — drop-in proxy that translates Anthropic message format and tool calls to Google Gemini",
   "main": "index.js",
   "types": "index.d.ts",