@tetrixdev/ai-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tetrixdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @tetrixdev/ai-bridge
+
+A local CLI bridge that connects your AI command-line tools (Codex, Claude, Gemini) to web applications via WebSocket. The bridge runs on your machine, receives AI requests from a server, pipes them through your locally installed CLI tools, and streams normalized responses back -- letting web apps use your own AI subscriptions without touching your credentials.
+
+## Quick Start
+
+The **connection token** is generated from the web application that uses the AI Bridge server package (for example, `php artisan ai-bridge:token` for Laravel apps). The **server URL** is the WebSocket server address provided by that application (typically `wss://your-app.com/api/ai-bridge/ws`).
+
+```bash
+npx @tetrixdev/ai-bridge --server wss://your-app.com/api/ai-bridge/ws --token YOUR_CONNECTION_TOKEN
+```
+
+Or using environment variables:
+
+```bash
+export AI_BRIDGE_SERVER=wss://your-app.com/api/ai-bridge/ws
+export AI_BRIDGE_TOKEN=YOUR_CONNECTION_TOKEN
+npx @tetrixdev/ai-bridge
+```
+
+## Options
+
+| Flag | Environment Variable | Description |
+|------|---------------------|-------------|
+| `--server <url>` | `AI_BRIDGE_SERVER` | WebSocket server URL (`wss://...`) |
+| `--token <token>` | `AI_BRIDGE_TOKEN` | Connection token from the web app |
+| `--test` | | Test mode -- responds with mock data instead of calling real CLIs |
+| `--debug` | | Enable verbose debug logging |
+
+## Supported Providers
+
+| Provider | CLI Binary | Session Resume | Streaming | Thinking | Server Tools |
+|----------|-----------|----------------|-----------|----------|--------------|
+| **Codex** (OpenAI) | `codex` | Yes | NDJSON | Yes | Yes |
+| **Claude** (Anthropic) | `claude` | Yes | NDJSON | Yes | Yes |
+| **Gemini** (Google) | `gemini` | Yes | NDJSON | Partial | Yes |
+
+The bridge auto-detects which CLIs are installed on startup.
+
+**Server-defined tools** registered by the web application are exposed to every provider as Bash wrapper scripts placed on the CLI's `PATH`; the CLI invokes them as ordinary shell commands and the bridge routes the call back through the WebSocket. For Codex, the bridge runs `codex exec` with a workspace-write sandbox and network access enabled so the wrapper scripts can reach the bridge — this is handled automatically when tools are present.
+
+## Test Mode
+
+Use `--test` to verify your WebSocket connection and protocol behaviour without needing a real CLI installed. Note that `--server` and `--token` are still required in test mode — the WebSocket connection to the server is what test mode exercises.
+
+```bash
+npx @tetrixdev/ai-bridge --server wss://your-app.com/api/ai-bridge/ws --token TOKEN --test
+```
+
+In test mode, AI requests receive mock streaming responses (thinking block + text block + done event) that exercise the full protocol.
+
+## Troubleshooting
+
+**Get detailed diagnostics with `--debug`**
+For detailed diagnostic output, add `--debug` to the command. This logs each WebSocket message, provider command, and session operation, which is the fastest way to pin down a confusing error before filing a support request.
+
+**"Authentication token is required" / "Server URL is required"**
+The token is generated by your web application (e.g. `php artisan ai-bridge:token` for Laravel apps). The server URL is the WebSocket endpoint exposed by that application (typically `wss://your-app.com/api/ai-bridge/ws`). See your application's documentation for the exact values.
+
+**"Connection rejected: invalid or expired token"**
+Your token has expired or was revoked. Generate a new one from your web application's admin interface and restart the bridge.
+
+**"No AI CLI tools detected"**
+Install one or more supported CLIs:
+- Codex: https://github.com/openai/codex
+- Claude: https://claude.ai/download
+- Gemini: https://github.com/google-gemini/gemini-cli
+
+**"Authentication required — run \`<provider\> auth login\`"**
+Your AI CLI's authentication session has expired. Run the indicated login command (e.g. `claude auth login`) and then restart the bridge.
+
+**Where are sessions stored?**
+Session mappings are persisted to `~/.ai-bridge/sessions.json` so conversations can be resumed across bridge restarts. You can delete this file to clear all sessions.
+
+## Protocol
+
+See [PROTOCOL.md](./PROTOCOL.md) for the full wire format specification.
+
+## License
+
+MIT