thebird 1.2.101 → 1.2.103

package/.gm/lastskill

@@ -1 +1 @@
-gm:gm-execute
+gm:update-docs

package/CLAUDE.md

@@ -2,9 +2,22 @@
 
 ## 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.
+**thebird** is the web OS shell — browser-native terminal, agentic chat, and file system. All Anthropic-format message translation, routing, streaming, and tool calling is owned by **[acptoapi](https://github.com/AnEntrypoint/acptoapi)** (`node_modules/acptoapi`). thebird depends on acptoapi as an npm package (`file:../acptoapi` locally, npm in CI).
 
-### Message Translation
+```
+thebird (web OS)
+  ├── docs/          — browser UI (chat, terminal, preview, shell)
+  ├── serve.js       — static file server for docs/
+  ├── server.js      — Anthropic-compat HTTP proxy (uses acptoapi)
+  ├── index.js       — re-exports acptoapi
+  └── node_modules/acptoapi/
+        ├── lib/convert.js     — Anthropic↔Gemini message translation
+        ├── lib/providers/     — OpenAI-compat + ACP providers
+        ├── lib/router-stream.js — multi-provider routing
+        └── index.js           — streamGemini, generateGemini, createRouter, ...
+```
+
+### Message Translation (in acptoapi)
 
 Anthropic format:
 ```js
@@ -18,14 +31,14 @@ Translates to provider-native format:
 - **Gemini**: `parts: [{ text: '...' }, { inlineData: { mimeType: '...', data: '...' } }]`
 - **OpenAI**: `content: [{ type: 'text', text: '...' }, { type: 'image_url', image_url: { url: '...' } }]`
 
-### Tool Calling
+### Tool Calling (in acptoapi)
 
 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)
+### Routing (Multi-Provider, in acptoapi)
 
 `createRouter()` picks provider+model per request based on:
 1. `taskType` (e.g., 'think', 'background', 'longContext')
@@ -191,6 +204,14 @@ UI consumes via 3 channels: `onChunk(delta)` text streaming | `onEvent(ev)` badg
 
 ## Files
 
+- `index.js`: Re-exports all of acptoapi
+- `server.js`: Anthropic-compatible HTTP proxy using acptoapi (streamGemini/generateGemini)
+- `serve.js`: Static file server for docs/ (COEP/COOP headers for WebContainer)
+- `package.json`: depends on `acptoapi` (file:../acptoapi locally, npm in CI)
+- `docs/shell-builtins.js`: FS/IO builtins (ls/cat/echo/cd/mkdir/rm/cp/mv/touch/head/tail/wc) — imports makeTextBuiltins
+- `docs/shell-builtins-text.js`: Text-processing builtins (grep/sed/sort/uniq/tr) + env/export/clear/history/which/exit/true/false/printenv
+
+**acptoapi** (owned by `c:/dev/acptoapi`, installed as npm dep):
 - `lib/convert.js`: Message/tool translation logic
 - `lib/client.js`: Provider client factory
 - `lib/errors.js`: Typed error hierarchy (BridgeError, AuthError, RateLimitError, etc.), classifyError, redactKeys, withRetry
@@ -202,10 +223,6 @@ UI consumes via 3 channels: `onChunk(delta)` text streaming | `onEvent(ev)` badg
 - `index.js`: Main entry point, Gemini streaming/generation, re-exports
 - `index.d.ts`: TypeScript type definitions
 - `examples/`: Working examples using Anthropic SDK format
-- `wasi/cli.ts`: Deno streaming CLI — `deno run --allow-net --allow-env wasi/cli.ts [--model M] [--system S] <prompt>`
-- `deno.json`: tasks `cli` (run) and `cli:compile` (→ `dist/thebird` binary)
-- `docs/shell-builtins.js`: FS/IO builtins (ls/cat/echo/cd/mkdir/rm/cp/mv/touch/head/tail/wc) — imports makeTextBuiltins
-- `docs/shell-builtins-text.js`: Text-processing builtins (grep/sed/sort/uniq/tr) + env/export/clear/history/which/exit/true/false/printenv
 
 ## WebContainer Terminal in docs/
 

package/README.md

@@ -1,255 +1,43 @@
 # thebird
 
-Anthropic SDK to multi-provider bridge. Drop-in adapter that translates Anthropic-style messages, tool calls, and content blocks to Google Gemini or any OpenAI-compatible API — with routing, transformers, streaming, vision, retry logic, and full TypeScript types.
+Web OS — browser-native terminal, agentic chat, and file system powered by WebContainer and IndexedDB. Anthropic-format message routing is handled by [acptoapi](https://github.com/AnEntrypoint/acptoapi).
 
-## How It Works
+## Live Demo
 
-thebird accepts **Anthropic SDK message format** — the same `{ role, content }` structure you use with `@anthropic-ai/sdk` — and translates it to Gemini or any OpenAI-compatible API. No proxy server needed. You write Anthropic-format messages, thebird streams them through Gemini.
+**[anentrypoint.github.io/thebird](https://anentrypoint.github.io/thebird/)**
 
-```
-Anthropic SDK format  →  thebird  →  Gemini / OpenAI-compatible API
-     (messages)         (bridge)         (native streaming)
-```
-
-This means you can use `@anthropic-ai/sdk` to build your messages and tool definitions, then pass them directly to thebird for execution against Gemini models.
-
-## Install
-
-```bash
-npm install thebird @anthropic-ai/sdk
-```
-
-## Quick Start
-
-**Anthropic SDK format → Gemini (streaming)**
-
-```js
-const Anthropic = require('@anthropic-ai/sdk');
-const { streamGemini } = require('thebird');
-
-// Build messages using Anthropic SDK format — same structure as client.messages.create()
-const messages = [
-  { role: 'user', content: 'Count from 1 to 5.' }
-];
-
-// Stream through Gemini — no server, no proxy
-const { fullStream } = streamGemini({
-  model: 'gemini-3-flash-preview',
-  system: 'You are a helpful assistant.',
-  messages
-});
-
-for await (const event of fullStream) {
-  if (event.type === 'text-delta') process.stdout.write(event.textDelta);
-}
-```
-
-**Anthropic SDK format → Gemini (non-streaming)**
-
-```js
-const { generateGemini } = require('thebird');
-
-const { text } = await generateGemini({
-  model: 'gemini-3-flash-preview',
-  messages: [{ role: 'user', content: 'Hello!' }]
-});
-console.log(text);
-```
-
-**Multi-provider router**
-
-```js
-const { createRouter } = require('thebird');
-
-const router = createRouter({
-  Providers: [
-    { name: 'deepseek', api_base_url: 'https://api.deepseek.com/chat/completions', api_key: process.env.DEEPSEEK_API_KEY, models: ['deepseek-chat', 'deepseek-reasoner'], transformer: { use: ['deepseek'] } },
-    { name: 'gemini',   api_base_url: 'https://generativelanguage.googleapis.com/v1beta/models/', api_key: process.env.GEMINI_API_KEY, models: ['gemini-2.5-pro'] },
-    { name: 'ollama',   api_base_url: 'http://localhost:11434/v1/chat/completions', api_key: 'ollama', models: ['qwen2.5-coder:latest'] },
-  ],
-  Router: {
-    default: 'deepseek,deepseek-chat',
-    background: 'ollama,qwen2.5-coder:latest',
-    think: 'deepseek,deepseek-reasoner',
-    longContext: 'gemini,gemini-2.5-pro',
-    longContextThreshold: 60000,
-  }
-});
-
-// Stream — routes automatically based on taskType and token count
-const { fullStream } = router.stream({ messages, taskType: 'think' });
-for await (const event of fullStream) {
-  if (event.type === 'text-delta') process.stdout.write(event.textDelta);
-}
-
-// Generate
-const { text } = await router.generate({ messages });
-```
-
-**File-based config** — place config at `~/.thebird/config.json` (or set `THEBIRD_CONFIG` env) and use the auto-loading shorthand:
-
-```js
-const { streamRouter, generateRouter } = require('thebird');
-const { fullStream } = streamRouter({ messages, taskType: 'background' });
-```
-
-## Routing
-
-`createRouter` / `streamRouter` pick a provider+model per request:
-
-| Route key | Trigger |
-|---|---|
-| `default` | Any request not matched by another rule |
-| `background` | `taskType: 'background'` |
-| `think` | `taskType: 'think'` |
-| `webSearch` | `taskType: 'webSearch'` |
-| `image` | `taskType: 'image'` |
-| `longContext` | Estimated token count > `longContextThreshold` (default 60 000) |
-| subagent tag | First user message starts with `<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>` |
-| custom function | `customRouter: async (params, cfg) => 'provider,model'` in config |
-
-Route values are `"providerName,modelName"` strings matching a `Providers` entry.
-
-## Transformers
-
-Apply per-provider request/response transformations. Set on the provider's `transformer.use` array.
-
-```json
-{
-  "name": "deepseek",
-  "transformer": {
-    "use": ["deepseek"],
-    "deepseek-chat": { "use": [["maxtoken", { "max_tokens": 8192 }], "tooluse"] }
-  }
-}
-```
-
-Built-in transformers:
-
-| Name | Effect |
-|---|---|
-| `deepseek` | Strips `cache_control`, normalises system to string |
-| `openrouter` | Adds `HTTP-Referer` / `X-Title` headers; optional `provider` routing |
-| `maxtoken` | Sets `max_tokens` to the given value |
-| `tooluse` | Adds `tool_choice: {type:"required"}` when tools are present |
-| `cleancache` | Strips all `cache_control` fields recursively |
-| `reasoning` | Moves `reasoning_content` to `_reasoning` in response |
-| `sampling` | Removes `top_k` / `repetition_penalty` |
-| `groq` | Removes `top_k` |
-
-Pass options as a nested array: `["maxtoken", { "max_tokens": 16384 }]`.
-
-## Config File
-
-`~/.thebird/config.json` (or `THEBIRD_CONFIG` env var) — same schema as the inline config object. Supports `$VAR` / `${VAR}` environment variable interpolation anywhere in the file.
-
-```json
-{
-  "Providers": [
-    { "name": "openrouter", "api_base_url": "https://openrouter.ai/api/v1/chat/completions", "api_key": "$OPENROUTER_API_KEY", "models": ["google/gemini-2.5-pro-preview"], "transformer": { "use": ["openrouter"] } }
-  ],
-  "Router": { "default": "openrouter,google/gemini-2.5-pro-preview" }
-}
-```
-
-## Error Handling
-
-thebird uses a typed error hierarchy. All errors extend `BridgeError`:
+- **Chat tab** — Agentic chat via `acptoapi` running in-browser (`docs/vendor/thebird-browser.js`). Tools: `read_file`, `write_file`, `list_files` (IDB-backed), `run_command`, `read_terminal`, `send_to_terminal`. No proxy server required. API key stored in localStorage.
+- **Terminal tab** — Browser-native POSIX shell (xstate v5 state machine, V8 eval) backed by IndexedDB filesystem. Built-in: `ls`, `cat`, `cd`, `pwd`, `mkdir`, `rm`, `cp`, `mv`, `echo`, `env`, `export`, `node`, `npm install`. Node REPL with persistent scope, `require()` from IDB node_modules, `http.createServer` polyfill.
+- **Preview tab** — iframe served by a service worker reading files from IDB at `/preview/*`. Hot-reloads 5s after any file write.
 
-| Error | Status | Retryable | When |
-|---|---|---|---|
-| `AuthError` | 401, 403 | No | Invalid API key |
-| `RateLimitError` | 429 | Yes | Quota exceeded |
-| `TimeoutError` | 408 | Yes | Stream chunk timeout |
-| `ContextWindowError` | 413 | No | Input too long |
-| `ContentPolicyError` | 451 | No | Safety filter triggered |
-| `ProviderError` | 5xx | Yes | Upstream server error |
+All JS and CSS dependencies are vendored locally in `docs/vendor/` — no CDN required at runtime.
 
-`GeminiError` is an alias for `BridgeError` (backwards compatible). API keys are auto-redacted in error messages.
+## Architecture
 
-```js
-const { classifyError, BridgeError } = require('thebird');
-try { /* ... */ } catch (err) {
-  if (err instanceof BridgeError && err.retryable) { /* retry */ }
-}
 ```
-
-## Streaming Resilience
-
-Pass `streamGuard` to protect against stalled or looping streams:
-
-```js
-streamGemini({
-  messages,
-  streamGuard: { chunkTimeoutMs: 30000, maxRepeats: 100 }
-});
+thebird (web OS shell)
+  └── acptoapi (npm)        ← Anthropic format → Gemini / OpenAI-compat bridge
+        └── @google/genai   ← Gemini native streaming
 ```
 
-- **Chunk timeout** — throws `TimeoutError` if no chunk received within the timeout (default 30s)
-- **Repeat detection** — throws if the same chunk appears consecutively N times (default 100)
+thebird is the web OS. `acptoapi` owns all Anthropic↔provider translation, streaming, routing, transformers, and TypeScript types. `server.js` exposes a local Anthropic-compatible proxy backed by acptoapi.
 
-## Circuit Breaker
+## Local Dev
 
-The router tracks per-provider failures. After consecutive failures exceed the threshold, the provider is temporarily skipped:
-
-```js
-createRouter({
-  Providers: [/* ... */],
-  circuitBreaker: { maxFailures: 5, cooldownMs: 60000 }
-});
-```
-
-## Provider Capabilities
-
-Declare what each provider supports. Unsupported features are stripped automatically with warnings:
-
-```json
-{
-  "name": "groq",
-  "api_base_url": "...",
-  "api_key": "$GROQ_API_KEY",
-  "capabilities": { "vision": false, "jsonMode": true }
-}
+```bash
+npm install
+node serve.js      # serves docs/ at http://localhost:8080
+node server.js     # Anthropic-compat proxy at http://localhost:3456 (needs GEMINI_API_KEY)
 ```
 
-Defaults: `streaming: true, toolUse: true, vision: true, systemMessage: true, jsonMode: false`.
+## acptoapi
 
-## Gemini Direct API
+For the Anthropic-to-provider bridge (streaming, routing, tool calls, vision, retry logic, TypeScript types), see [acptoapi](https://github.com/AnEntrypoint/acptoapi).
 
-`streamGemini` / `generateGemini` bypass routing and call Gemini natively via `@google/genai`. Requires `GEMINI_API_KEY`.
-
-## Message Format
-
-Messages follow the Anthropic SDK format. All image block variants are supported:
-
-```js
-{ role: 'user', content: [
-  { type: 'text', text: 'Describe this image.' },
-  { type: 'image', source: { type: 'base64', media_type: 'image/png', data: '...' } }
-]}
+```bash
+npm install acptoapi
 ```
 
-## Streaming Events
-
-| Event | Fields | Description |
-|---|---|---|
-| `start-step` | — | Beginning of a reasoning step |
-| `text-delta` | `textDelta` | Streamed text chunk |
-| `tool-call` | `toolCallId, toolName, args` | Model invoked a tool |
-| `tool-result` | `toolCallId, toolName, args, result` | Tool execution result |
-| `finish-step` | `finishReason` | Step completed |
-| `error` | `error` | Error during step |
-
-## Browser Demo
-
-Live at **[anentrypoint.github.io/thebird](https://anentrypoint.github.io/thebird/)**
-
-- **Chat tab** — Agentic chat powered by thebird `streamGemini` running in-browser (bundled in `docs/vendor/thebird-browser.js`). Tools: `read_file`, `write_file`, `list_files` (IDB-backed), `run_command`, `read_terminal`, `send_to_terminal`. No proxy server required. Gemini API key stored in localStorage.
-- **Terminal tab** — Browser-native POSIX shell (xstate v5 state machine, V8 eval) backed by IndexedDB filesystem. Built-in commands: `ls`, `cat`, `cd`, `pwd`, `mkdir`, `rm`, `cp`, `mv`, `echo`, `env`, `export`, `node`, `npm install`. Node REPL mode with persistent scope, `require()` from IDB node_modules, `http.createServer` polyfill. No WebContainer or server required.
-- **Preview tab** — iframe served by a service worker reading files from IDB at `/preview/*`. Hot-reloads 5s after any file write.
-
-All JS and CSS dependencies are vendored locally in `docs/vendor/` — no CDN required at runtime.
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thebird",
-  "version": "1.2.101",
+  "version": "1.2.103",
   "description": "Anthropic SDK to Gemini streaming bridge — drop-in proxy that translates Anthropic message format and tool calls to Google Gemini",
   "scripts": {
     "start": "node serve.js"