@pix3/agent-bridge 0.2.0

package/README.md

@@ -0,0 +1,75 @@
+# Pix3AgentBridge
+
+A small **local** service that connects the Pix3 editor's in-editor AI agent to LLM providers a
+browser can't reach on its own — and keeps your API keys on your machine, never in the browser.
+
+It runs on `127.0.0.1` and does two things:
+
+1. **Claude Code (MAX) lane** — serves the agent from a real Claude Agent SDK session using your
+   Claude Code Pro/MAX subscription (`claude login`). No API key, no per-token cost.
+2. **Provider proxy lane** — a credential-injecting reverse proxy for **OpenAI**, the **Anthropic
+   API**, **OpenCode Zen**, and any **custom OpenAI-compatible** endpoint. The editor authenticates
+   to the bridge with a pairing token; the bridge adds the real provider key and forwards the request
+   to the provider. Your keys live only in `~/.pix3/agent-bridge.json`.
+
+Google Gemini is **not** proxied here — the editor calls it directly (it sends CORS headers), so a
+basic user only needs a Gemini key and no bridge at all. The bridge is the "advanced" path that
+unlocks the other providers.
+
+## Requirements
+
+- Node.js **24+**
+- For the Claude Code lane: a logged-in Claude Code (`claude login`, Pro/MAX)
+
+## Run
+
+```bash
+npx @pix3/agent-bridge
+```
+
+On start it prints a **pairing token**. In the editor: **Settings → AI Agent**, paste the token.
+Providers you've enabled below then appear in the model picker.
+
+Options: `--port <n>` (default 8484), `--origin <url>` (repeatable — extra allowed browser origins).
+
+## Manage providers
+
+```bash
+# Built-in presets — just supply a key:
+npx @pix3/agent-bridge provider add openai        --key sk-...
+npx @pix3/agent-bridge provider add anthropic     --key sk-ant-...
+npx @pix3/agent-bridge provider add opencode-zen  --key ...
+
+# A custom OpenAI-compatible endpoint (arbitrary id + explicit base URL):
+npx @pix3/agent-bridge provider add my-router \
+  --base-url https://openrouter.ai/api/v1 --key sk-or-... --kind openai --label OpenRouter
+
+npx @pix3/agent-bridge provider list
+npx @pix3/agent-bridge provider disable openai
+npx @pix3/agent-bridge provider enable  openai
+npx @pix3/agent-bridge provider set-key openai sk-...
+npx @pix3/agent-bridge provider remove  my-router
+```
+
+`--kind openai` forwards `Authorization: Bearer <key>` (OpenAI Chat Completions, gateways, local
+Ollama/LM Studio). `--kind anthropic` forwards `x-api-key` + `anthropic-version` (native Anthropic
+Messages API). Presets set the right kind for you.
+
+Changes take effect on the editor's next availability probe — no server restart needed for key/enable
+changes (a base-URL/kind change to a provider you're actively using is picked up on reconnect).
+
+## Security
+
+- Binds to `127.0.0.1` only; `Host` must be localhost (blocks DNS-rebinding).
+- Every API call requires the pairing token; browser `Origin` is allowlisted.
+- The proxy's upstream host is fixed per provider (never taken from the request) → no open relay / SSRF.
+- Outbound requests carry only `content-type` + the injected key — the pairing token, cookies and
+  other inbound headers are stripped, so nothing leaks upstream.
+- The Claude Code session runs with zero built-in tools — the model can only call pix3 editor tools,
+  never this machine's shell or filesystem.
+
+## Config file
+
+`~/.pix3/agent-bridge.json` holds the pairing token and the provider table (kind, base URL, key,
+enabled). It is migrated automatically from the old `claude-bridge.json` (the pairing token carries
+over) on first run.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@pix3/agent-bridge",
+  "version": "0.2.0",
+  "description": "Local bridge for the Pix3 editor's in-editor agent: a Claude Agent SDK (Pro/MAX subscription) lane plus a credential-injecting proxy for OpenAI / Anthropic / OpenCode Zen / custom OpenAI-compatible providers. Keys stay on your machine.",
+  "type": "module",
+  "bin": {
+    "pix3-agent-bridge": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "start": "node src/index.ts",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "pix3",
+    "llm",
+    "proxy",
+    "claude",
+    "openai",
+    "agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.211",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "typescript": "~5.8.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,195 @@
+/**
+ * CLI for Pix3AgentBridge. Running the bridge with no subcommand starts the server (see index.ts);
+ * the `provider` subcommands below manage the provider table in `~/.pix3/agent-bridge.json` — adding
+ * a key, enabling/disabling, or removing a provider — without touching a running server (the editor
+ * re-reads availability from `GET /v1/providers` on its next probe).
+ *
+ *   pix3-agent-bridge provider list
+ *   pix3-agent-bridge provider add openai --key sk-...
+ *   pix3-agent-bridge provider add anthropic --key sk-ant-...
+ *   pix3-agent-bridge provider add opencode-zen --key ...
+ *   pix3-agent-bridge provider add my-router --base-url https://openrouter.ai/api/v1 --key ... --kind openai
+ *   pix3-agent-bridge provider enable|disable|remove <id>
+ *   pix3-agent-bridge provider set-key <id> <key>
+ */
+
+import {
+  PROVIDER_PRESETS,
+  RESERVED_PROVIDER_IDS,
+  configPath,
+  loadConfig,
+  saveConfig,
+  type ProviderConfig,
+} from './config.ts';
+
+/** Parse `--flag value` / `--flag=value` pairs, returning [positional[], flags]. */
+const parseArgs = (args: string[]): { positional: string[]; flags: Record<string, string> } => {
+  const positional: string[] = [];
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq >= 0) {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      } else {
+        flags[arg.slice(2)] = args[i + 1] ?? '';
+        i += 1;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
+};
+
+const maskKey = (key: string): string =>
+  key.length <= 8 ? (key ? '••••' : '(none)') : `${key.slice(0, 4)}…${key.slice(-4)}`;
+
+const printList = (providers: Record<string, ProviderConfig>): void => {
+  const ids = Object.keys(providers);
+  if (ids.length === 0) {
+    console.log('No providers configured. Add one, e.g.:  pix3-agent-bridge provider add openai --key sk-...');
+    console.log(`\nBuilt-in presets: ${Object.keys(PROVIDER_PRESETS).join(', ')}`);
+    return;
+  }
+  console.log(`Providers (from ${configPath()}):\n`);
+  for (const id of ids) {
+    const p = providers[id];
+    const state = p.enabled ? 'enabled' : 'disabled';
+    const key = p.apiKey ? maskKey(p.apiKey) : '(no key — add one with `provider set-key`)';
+    console.log(`  ${id}`);
+    console.log(`    kind:    ${p.kind}`);
+    console.log(`    label:   ${p.label}`);
+    console.log(`    baseUrl: ${p.baseUrl}`);
+    console.log(`    key:     ${key}`);
+    console.log(`    status:  ${state}`);
+    console.log('');
+  }
+};
+
+const usage = (): void => {
+  console.log(
+    [
+      'Usage:',
+      '  pix3-agent-bridge                         start the bridge server',
+      '  pix3-agent-bridge provider list',
+      '  pix3-agent-bridge provider add <id> [--key <k>] [--base-url <url>] [--kind openai|anthropic] [--label <l>]',
+      '  pix3-agent-bridge provider set-key <id> <key>',
+      '  pix3-agent-bridge provider enable <id>',
+      '  pix3-agent-bridge provider disable <id>',
+      '  pix3-agent-bridge provider remove <id>',
+      '',
+      `Built-in presets (add with just --key): ${Object.keys(PROVIDER_PRESETS).join(', ')}`,
+    ].join('\n')
+  );
+};
+
+const addProvider = (
+  config: ReturnType<typeof loadConfig>,
+  id: string,
+  flags: Record<string, string>
+): void => {
+  if ((RESERVED_PROVIDER_IDS as readonly string[]).includes(id)) {
+    console.error(
+      `Provider id "${id}" is reserved by the bridge and cannot be added. Pick a different id.`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const preset = PROVIDER_PRESETS[id];
+  const baseUrl = (flags['base-url'] ?? preset?.baseUrl ?? '').replace(/\/$/, '');
+  if (!baseUrl) {
+    console.error(
+      `Provider "${id}" is not a built-in preset, so it needs an explicit --base-url ` +
+        `(e.g. --base-url https://openrouter.ai/api/v1).`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const kindFlag = flags.kind === 'anthropic' ? 'anthropic' : flags.kind === 'openai' ? 'openai' : undefined;
+  const existing = config.providers[id];
+  config.providers[id] = {
+    kind: kindFlag ?? preset?.kind ?? existing?.kind ?? 'openai',
+    label: flags.label ?? preset?.label ?? existing?.label ?? id,
+    baseUrl,
+    apiKey: flags.key ?? existing?.apiKey ?? '',
+    enabled: true,
+    builtin: preset?.builtin ?? existing?.builtin ?? false,
+  };
+  saveConfig(config);
+  console.log(`Provider "${id}" added/updated and enabled.`);
+  if (!config.providers[id].apiKey) {
+    console.log('  Note: no API key set yet — add one with `provider set-key ' + id + ' <key>`.');
+  }
+};
+
+/** Run a `provider …` subcommand. Returns true if it was handled (so the server should not start). */
+export const runProviderCommand = (args: string[]): void => {
+  const { positional, flags } = parseArgs(args);
+  const [sub, id] = positional;
+  const config = loadConfig();
+
+  switch (sub) {
+    case undefined:
+    case 'list':
+      printList(config.providers);
+      return;
+    case 'add':
+      if (!id) {
+        console.error('Usage: provider add <id> [--key <k>] [--base-url <url>] [--kind openai|anthropic]');
+        process.exitCode = 1;
+        return;
+      }
+      addProvider(config, id, flags);
+      return;
+    case 'set-key': {
+      const key = positional[2];
+      if (!id || !key) {
+        console.error('Usage: provider set-key <id> <key>');
+        process.exitCode = 1;
+        return;
+      }
+      const provider = config.providers[id];
+      if (!provider) {
+        console.error(`No such provider "${id}". Add it first with \`provider add ${id}\`.`);
+        process.exitCode = 1;
+        return;
+      }
+      provider.apiKey = key;
+      saveConfig(config);
+      console.log(`Key updated for "${id}".`);
+      return;
+    }
+    case 'enable':
+    case 'disable': {
+      const provider = id ? config.providers[id] : undefined;
+      if (!provider) {
+        console.error(`No such provider "${id ?? ''}".`);
+        process.exitCode = 1;
+        return;
+      }
+      provider.enabled = sub === 'enable';
+      saveConfig(config);
+      console.log(`Provider "${id}" ${provider.enabled ? 'enabled' : 'disabled'}.`);
+      return;
+    }
+    case 'remove': {
+      if (!id || !config.providers[id]) {
+        console.error(`No such provider "${id ?? ''}".`);
+        process.exitCode = 1;
+        return;
+      }
+      delete config.providers[id];
+      saveConfig(config);
+      console.log(`Provider "${id}" removed.`);
+      return;
+    }
+    default:
+      console.error(`Unknown provider subcommand: ${sub}\n`);
+      usage();
+      process.exitCode = 1;
+  }
+};
+
+export { usage };

package/src/config.ts

@@ -0,0 +1,179 @@
+/**
+ * Persistent configuration for Pix3AgentBridge, stored in `~/.pix3/agent-bridge.json`.
+ *
+ * Beyond the pairing token / port / origins the bridge always had, this now holds the **provider
+ * table**: for each metered LLM provider (OpenAI, Anthropic API, OpenCode Zen, or a user-defined
+ * OpenAI-compatible endpoint) the upstream base URL, the API key, and an enabled flag. Keys live
+ * ONLY here on the user's machine — the editor never receives them; it authenticates to the bridge
+ * with the pairing token and the bridge injects the real key when forwarding upstream.
+ *
+ * The provider table is managed through the CLI (`pix3-agent-bridge provider add|remove|enable|…`),
+ * never by hand-editing (though the file is plain JSON if you must).
+ */
+
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Provider ids the bridge reserves for its own intrinsic lanes (e.g. the Agent-SDK lane exposed as
+ * `claude-bridge` in discovery). The CLI rejects adding a provider under one of these so `GET
+ * /v1/providers` can never emit duplicate ids.
+ */
+export const RESERVED_PROVIDER_IDS = ['claude-bridge'] as const;
+
+/** Upstream auth scheme: how the bridge presents the stored key to the provider. */
+export type ProviderKind = 'openai' | 'anthropic';
+
+export interface ProviderConfig {
+  /**
+   * `openai` → forward `Authorization: Bearer <key>` (OpenAI Chat Completions, OpenCode Zen, most
+   * gateways, local Ollama/LM Studio). `anthropic` → forward `x-api-key: <key>` + `anthropic-version`
+   * (native Anthropic Messages API).
+   */
+  kind: ProviderKind;
+  /** Human label shown in the editor picker and `provider list`. */
+  label: string;
+  /** Upstream base URL INCLUDING the version segment, e.g. `https://api.openai.com/v1`. */
+  baseUrl: string;
+  /** Provider API key. Empty string = not yet configured (provider stays effectively unusable). */
+  apiKey: string;
+  /** When false the provider is hidden from discovery and its proxy route 404s. */
+  enabled: boolean;
+  /** True for the shipped presets (openai/anthropic/opencode-zen/cerebras); false for user-added. */
+  builtin?: boolean;
+}
+
+export interface BridgeConfig {
+  token: string;
+  port: number;
+  origins: string[];
+  providers: Record<string, ProviderConfig>;
+}
+
+/**
+ * Shipped presets: `provider add <id> --key <k>` for one of these fills in kind/label/baseUrl so the
+ * common providers are one command away. A custom OpenAI-compatible endpoint is added with an
+ * arbitrary id plus an explicit `--base-url`.
+ */
+export const PROVIDER_PRESETS: Record<string, Omit<ProviderConfig, 'apiKey' | 'enabled'>> = {
+  openai: {
+    kind: 'openai',
+    label: 'OpenAI',
+    baseUrl: 'https://api.openai.com/v1',
+    builtin: true,
+  },
+  anthropic: {
+    kind: 'anthropic',
+    label: 'Anthropic (Claude)',
+    baseUrl: 'https://api.anthropic.com/v1',
+    builtin: true,
+  },
+  'opencode-zen': {
+    kind: 'openai',
+    label: 'OpenCode Zen',
+    baseUrl: 'https://opencode.ai/zen/v1',
+    builtin: true,
+  },
+  cerebras: {
+    kind: 'openai',
+    label: 'Cerebras',
+    baseUrl: 'https://api.cerebras.ai/v1',
+    builtin: true,
+  },
+};
+
+export const DEFAULT_PORT = 8484;
+
+export const DEFAULT_ORIGINS = [
+  'https://editor.pix3.dev',
+  'https://cloud.pix3.dev',
+  'http://localhost:8123',
+  'http://127.0.0.1:8123',
+];
+
+const CONFIG_DIR = path.join(os.homedir(), '.pix3');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'agent-bridge.json');
+/** Pre-rename config file. Read once to carry the existing pairing token forward on first run. */
+const LEGACY_CONFIG_PATH = path.join(CONFIG_DIR, 'claude-bridge.json');
+
+export const configPath = (): string => CONFIG_PATH;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const parseProviders = (raw: unknown): Record<string, ProviderConfig> => {
+  if (!isRecord(raw)) return {};
+  const providers: Record<string, ProviderConfig> = {};
+  for (const [id, value] of Object.entries(raw)) {
+    if (!isRecord(value)) continue;
+    const kind = value.kind === 'anthropic' ? 'anthropic' : 'openai';
+    if (typeof value.baseUrl !== 'string' || !value.baseUrl) continue;
+    providers[id] = {
+      kind,
+      label: typeof value.label === 'string' && value.label ? value.label : id,
+      baseUrl: value.baseUrl.replace(/\/$/, ''),
+      apiKey: typeof value.apiKey === 'string' ? value.apiKey : '',
+      enabled: value.enabled !== false,
+      builtin: value.builtin === true,
+    };
+  }
+  return providers;
+};
+
+const readLegacyToken = (): string | null => {
+  try {
+    const legacy = JSON.parse(fs.readFileSync(LEGACY_CONFIG_PATH, 'utf8')) as unknown;
+    if (isRecord(legacy) && typeof legacy.token === 'string' && legacy.token.length >= 16) {
+      return legacy.token;
+    }
+  } catch {
+    /* no legacy file */
+  }
+  return null;
+};
+
+/** Load config, creating the file (and a fresh pairing token) on first run. */
+export const loadConfig = (): BridgeConfig => {
+  let stored: Partial<BridgeConfig> = {};
+  let existed = false;
+  try {
+    stored = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')) as Partial<BridgeConfig>;
+    existed = true;
+  } catch {
+    /* first run */
+  }
+
+  const config: BridgeConfig = {
+    token:
+      typeof stored.token === 'string' && stored.token.length >= 16
+        ? stored.token
+        : (readLegacyToken() ?? randomBytes(24).toString('base64url')),
+    port: typeof stored.port === 'number' ? stored.port : DEFAULT_PORT,
+    origins: [
+      ...DEFAULT_ORIGINS,
+      ...(Array.isArray(stored.origins) ? stored.origins.filter(o => typeof o === 'string') : []),
+    ],
+    providers: parseProviders(stored.providers),
+  };
+
+  // Persist on first run (or after a legacy-token migration) so the token is stable across restarts.
+  if (!existed || !stored.token) {
+    saveConfig(config);
+  }
+  return config;
+};
+
+/** Persist only the durable fields (token, port, custom origins, providers) — never the merged defaults. */
+export const saveConfig = (config: BridgeConfig): void => {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  const customOrigins = config.origins.filter(o => !DEFAULT_ORIGINS.includes(o));
+  const persisted = {
+    token: config.token,
+    ...(config.port !== DEFAULT_PORT ? { port: config.port } : {}),
+    ...(customOrigins.length > 0 ? { origins: customOrigins } : {}),
+    providers: config.providers,
+  };
+  fs.writeFileSync(CONFIG_PATH, `${JSON.stringify(persisted, null, 2)}\n`, 'utf8');
+};