@pix3/agent-bridge 0.2.0 → 0.2.1

package/dist/wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,38 +1,47 @@
-{
-  "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"
-  }
-}
+{
+  "name": "@pix3/agent-bridge",
+  "version": "0.2.1",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pix3dev/pix3.git",
+    "directory": "tools/pix3-agent-bridge"
+  },
+  "bin": {
+    "pix3-agent-bridge": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node src/index.ts",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "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

@@ -1,195 +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 };
+/**
+ * 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 };