cc-x10ded 3.0.17 → 3.0.18

package/PLUGINS.md

@@ -0,0 +1,173 @@
+# ccx Plugin System
+
+Extend ccx with custom model providers.
+
+## Overview
+
+The plugin system allows you to add any OpenAI-compatible API as a provider in ccx. Plugins are discovered from `~/.config/claude-glm/plugins/` and automatically loaded at runtime.
+
+## Quick Start
+
+### 1. Create Plugin Directory
+
+```bash
+mkdir -p ~/.config/claude-glm/plugins/my-provider
+```
+
+### 2. Create Plugin Manifest
+
+Create `plugin.json` in your plugin directory:
+
+```json
+{
+  "id": "my-provider",
+  "name": "My Custom Provider",
+  "version": "1.0.0",
+  "description": "A custom model provider",
+  "entry": "./dist/index.js"
+}
+```
+
+### 3. Write Plugin Implementation
+
+Create `index.ts` with your plugin code (see Example below).
+
+### 4. Build Plugin
+
+```bash
+bun build ./index.ts --outdir ./dist --target bun
+```
+
+### 5. Verify Installation
+
+```bash
+ccx models
+```
+
+Your provider should now appear in the list.
+
+## Plugin API
+
+### ProviderPlugin Interface
+
+```typescript
+import type { ProviderPlugin } from "@ccx/plugin-types";
+
+export default {
+  id: "my-provider",
+  name: "My Provider",
+  version: "1.0.0",
+  description: "Description of your provider",
+  models: [
+    { id: "model-1", name: "Model 1", contextWindow: 128000 },
+    { id: "model-2", name: "Model 2", contextWindow: 64000, default: true }
+  ],
+  createClient(config) {
+    return new MyProviderClient(config);
+  }
+} satisfies ProviderPlugin;
+```
+
+### ProviderClient Interface
+
+Your client must implement:
+
+```typescript
+interface ProviderClient {
+  readonly provider: string;
+
+  // Stream completions (required)
+  streamComplete(request: AnthropicRequest): AsyncGenerator<SSEMessage>;
+
+  // Get model info (optional)
+  getModelInfo(): ModelInfo | undefined;
+
+  // Health check (optional)
+  healthCheck(): Promise<HealthStatus>;
+}
+```
+
+### SSE Message Format
+
+Messages must be in Anthropic's SSE format:
+
+```typescript
+interface SSEMessage {
+  type: string;  // "message_start", "content_block_delta", "message_delta", "message_stop"
+  data: {
+    type?: string;
+    index?: number;
+    delta?: { type: "text_delta"; text: string };
+    stop_reason?: string;
+    usage?: { input_tokens: number; output_tokens: number };
+  };
+}
+```
+
+## Example: Ollama Plugin
+
+See `examples/plugins/ollama/` for a complete working example.
+
+## Type Definitions
+
+Install the official type definitions:
+
+```bash
+bun add -D @ccx/plugin-types
+```
+
+## Configuration
+
+Plugins can read configuration from the main config file:
+
+```json
+{
+  "plugins": {
+    "my-provider": {
+      "apiKey": "your-api-key",
+      "baseUrl": "https://api.example.com/v1",
+      "extra": {
+        "customOption": true
+      }
+    }
+  }
+}
+```
+
+## Best Practices
+
+1. **Handle errors gracefully** - Return meaningful error messages
+2. **Implement health checks** - Helps with `ccx doctor` diagnostics
+3. **Support streaming** - Users expect real-time responses
+4. **Respect rate limits** - Implement backoff on 429 errors
+5. **Use environment variables** - Allow API key via env vars
+
+## Publishing
+
+Want to share your plugin?
+
+1. Create a GitHub repository with your plugin code
+2. Add installation instructions to your README
+3. Submit a PR to add your plugin to the examples directory
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+Check `ccx doctor` for plugin errors. Common issues:
+- Missing `plugin.json`
+- Entry file not found
+- TypeScript compilation errors
+
+### Model Not Found
+
+Ensure your model's `id` matches what users will type:
+- `ccx --model=my-provider:model-1`
+
+### API Errors
+
+Implement proper error handling in your plugin to surface meaningful errors to users.
+
+## API Reference
+
+See [@ccx/plugin-types](https://www.npmjs.com/package/@ccx/plugin-types) for complete type definitions.

package/examples/plugins/ollama/README.md

@@ -0,0 +1,67 @@
+# Ollama Plugin for ccx
+
+This example plugin demonstrates how to integrate local Ollama models with ccx.
+
+## Installation
+
+```bash
+# 1. Ensure Ollama is running (default: http://localhost:11434)
+ollama serve
+
+# 2. Pull a model
+ollama pull llama3.1
+
+# 3. Create plugin directory
+mkdir -p ~/.config/claude-glm/plugins/ollama
+
+# 4. Copy plugin files
+cp plugin.json ~/.config/claude-glm/plugins/ollama/
+cp dist/index.js ~/.config/claude-glm/plugins/ollama/
+
+# 5. Verify installation
+ccx models
+```
+
+## Building
+
+```bash
+# From the examples/plugins/ollama directory:
+bun build ./index.ts --outdir ./dist --target bun
+```
+
+## Configuration
+
+No API key required for local Ollama. The plugin connects to `http://localhost:11434` by default.
+
+You can override the base URL by adding to your config:
+
+```json
+{
+  "plugins": {
+    "ollama": {
+      "baseUrl": "http://ollama:11434"
+    }
+  }
+}
+```
+
+## Supported Models
+
+- Llama 3.1 8B (131K context)
+- Qwen 2.5 72B (131K context)
+- Mistral 7B (32K context)
+- CodeLlama 7B (16K context)
+- DeepSeek Coder 6.7B (16K context)
+
+## Adding Custom Models
+
+Edit `index.ts` to add more models:
+
+```typescript
+const MODELS: ModelInfo[] = [
+  { id: "your-model", name: "Your Model Name", contextWindow: 32768 },
+  // Add more models...
+];
+```
+
+Then rebuild and reinstall.

package/examples/plugins/ollama/index.ts

@@ -0,0 +1,138 @@
+import type {
+  ProviderPlugin,
+  ProviderClient,
+  PluginConfig,
+  ModelInfo,
+  HealthStatus,
+  SSEMessage,
+  AnthropicRequest
+} from "../../../packages/plugin-types/index";
+
+const MODELS: ModelInfo[] = [
+  { id: "llama3.1", name: "Llama 3.1 8B", contextWindow: 131072 },
+  { id: "qwen2.5", name: "Qwen 2.5 72B", contextWindow: 131072 },
+  { id: "mistral", name: "Mistral 7B", contextWindow: 32768 },
+  { id: "codellama", name: "CodeLlama 7B", contextWindow: 16384 },
+  { id: "deepseek-coder", name: "DeepSeek Coder 6.7B", contextWindow: 16384 }
+];
+
+export default {
+  id: "ollama",
+  name: "Ollama (Local)",
+  version: "1.0.0",
+  description: "Run local Ollama models with Claude Code",
+  models: MODELS,
+
+  createClient(config: PluginConfig): ProviderClient {
+    return new OllamaClient(config);
+  }
+} satisfies ProviderPlugin;
+
+class OllamaClient implements ProviderClient {
+  readonly provider = "ollama";
+  private baseUrl: string;
+
+  constructor(config: PluginConfig) {
+    this.baseUrl = config.baseUrl || "http://localhost:11434";
+  }
+
+  async *streamComplete(request: AnthropicRequest): AsyncGenerator<SSEMessage> {
+    const prompt = this.buildPrompt(request);
+
+    const response = await fetch(`${this.baseUrl}/api/generate`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: request.model,
+        prompt,
+        stream: true,
+        options: {
+          temperature: request.temperature ?? 0.7,
+          num_predict: request.max_tokens
+        }
+      })
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`Ollama error: ${response.status} ${errorText}`);
+    }
+
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error("No response body from Ollama");
+
+    const decoder = new TextDecoder();
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      const chunk = decoder.decode(value);
+      const lines = chunk.split("\n");
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+
+        try {
+          const data = JSON.parse(line);
+
+          if (data.response) {
+            yield {
+              type: "content_block_delta",
+              data: { text: data.response }
+            };
+          }
+
+          if (data.done) {
+            yield {
+              type: "message_delta",
+              data: { stop_reason: "end_turn" }
+            };
+            yield {
+              type: "message_stop",
+              data: {}
+            };
+            break;
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  }
+
+  getModelInfo(): ModelInfo | undefined {
+    return MODELS.find(m => m.id === "llama3.1");
+  }
+
+  async healthCheck(): Promise<HealthStatus> {
+    try {
+      const start = Date.now();
+      const response = await fetch(`${this.baseUrl}/api/tags`);
+      if (!response.ok) {
+        return { healthy: false, error: `HTTP ${response.status}` };
+      }
+      return { healthy: true, latencyMs: Date.now() - start };
+    } catch (error) {
+      return { healthy: false, error: (error as Error).message };
+    }
+  }
+
+  private buildPrompt(request: AnthropicRequest): string {
+    const parts: string[] = [];
+
+    if (request.system) {
+      parts.push(`<system>${request.system}</system>`);
+    }
+
+    for (const message of request.messages) {
+      const role = message.role === "assistant" ? "assistant" : "user";
+      const content = typeof message.content === "string"
+        ? message.content
+        : message.content.map(c => c.type === "text" ? c.text : "").join("");
+      parts.push(`<${role}>${content}</${role}>`);
+    }
+
+    return parts.join("\n");
+  }
+}

package/examples/plugins/ollama/plugin.json

@@ -0,0 +1,7 @@
+{
+  "id": "ollama",
+  "name": "Ollama (Local)",
+  "version": "1.0.0",
+  "description": "Use local Ollama models with Claude Code",
+  "entry": "./dist/index.js"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-x10ded",
-  "version": "3.0.17",
+  "version": "3.0.18",
   "description": "Extend Claude Code with custom OpenAI-compatible model providers",
   "repository": {
     "type": "git",

package/packages/plugin-types/index.ts

@@ -0,0 +1,60 @@
+export interface ProviderPlugin {
+  readonly id: string;
+  readonly name: string;
+  readonly version: string;
+  readonly description?: string;
+  readonly models: ModelInfo[];
+
+  createClient(config: PluginConfig): ProviderClient;
+}
+
+export interface ModelInfo {
+  readonly id: string;
+  readonly name: string;
+  readonly contextWindow?: number;
+  readonly maxOutputTokens?: number;
+  readonly capabilities?: readonly ("text" | "vision" | "tools")[];
+  readonly default?: boolean;
+}
+
+export interface ProviderClient {
+  readonly provider: string;
+
+  streamComplete(request: AnthropicRequest): AsyncGenerator<SSEMessage>;
+
+  getModelInfo(): ModelInfo | undefined;
+
+  healthCheck(): Promise<HealthStatus>;
+}
+
+export interface PluginConfig {
+  readonly apiKey?: string;
+  readonly baseUrl: string;
+  readonly extra?: Record<string, unknown>;
+}
+
+export interface HealthStatus {
+  readonly healthy: boolean;
+  readonly latencyMs?: number;
+  readonly error?: string;
+}
+
+export interface SSEMessage {
+  type: string;
+  data: unknown;
+}
+
+export interface AnthropicRequest {
+  model: string;
+  messages: AnthropicMessage[];
+  max_tokens: number;
+  temperature?: number;
+  system?: string;
+  tools?: unknown[];
+  stream?: boolean;
+}
+
+export interface AnthropicMessage {
+  role: "user" | "assistant" | "system";
+  content: string | Array<{ type: "text"; text: string } | { type: "tool_result"; content: string | unknown }>;
+}

package/packages/plugin-types/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@ccx/plugin-types",
+  "version": "1.0.0",
+  "description": "TypeScript types for ccx plugins",
+  "main": "index.ts",
+  "types": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": ["ccx", "claude", "plugin", "types"],
+  "author": "",
+  "license": "MIT"
+}

package/src/commands/doctor.ts

@@ -1,6 +1,9 @@
 import { intro, outro, spinner } from "@clack/prompts";
 import { ShellIntegrator } from "../core/shell";
 import { ConfigManager } from "../core/config";
+import { telemetry } from "../core/telemetry";
+import { circuitBreaker } from "../core/circuit-breaker";
+import { pluginManager } from "../core/plugins";
 import * as pc from "picocolors";
 import { existsSync } from "fs";
 import { join } from "path";
@@ -30,7 +33,9 @@ export async function doctorCommand() {
 
   if (foundOld.length > 0) {
     issues.push("❌ Old ccx binaries found that may shadow the new one:");
-    foundOld.forEach(p => issues.push(`   ${p}`));
+    for (const p of foundOld) {
+      issues.push(`   ${p}`);
+    }
     issues.push("   👉 Run 'ccx update' to remove them automatically");
   } else {
     checks.push("✅ No conflicting binaries");
@@ -58,7 +63,7 @@ export async function doctorCommand() {
   if (!config.zaiApiKey && !config.minimaxApiKey && Object.keys(config.providers).length === 0) {
     issues.push("❌ No API keys configured. Run 'ccx setup'.");
   } else {
-    const keys = [];
+    const keys: string[] = [];
     if (config.zaiApiKey) keys.push("Z.AI");
     if (config.minimaxApiKey) keys.push("Minimax");
     if (config.providers.openai?.apiKey) keys.push("OpenAI");
@@ -91,7 +96,6 @@ export async function doctorCommand() {
     if (profile && existsSync(profile)) {
       const content = await Bun.file(profile).text();
       if (content.includes("claude-glm-wrapper")) {
-        // Check if using old bunx-based aliases
         if (content.includes("bunx cc-x10ded")) {
           warnings.push("⚠️  Old bunx-based aliases detected");
           warnings.push("   👉 Run 'ccx update' to migrate to faster direct aliases");
@@ -105,18 +109,90 @@ export async function doctorCommand() {
   }
   s.stop("Shell check complete");
 
+  // 6. Telemetry (Local)
+  s.start("Checking telemetry...");
+  const sessionDuration = telemetry.getSessionDuration();
+  const requestCount = telemetry.getRequestCount();
+  const providerStats = telemetry.getProviderStats();
+  const errors = telemetry.getErrors();
+  const fallbacks = telemetry.getFallbacks();
+
+  console.log("\n" + pc.bold("Telemetry (this session):"));
+  console.log(`  Session: ${Math.round(sessionDuration / 1000)}s | Requests: ${requestCount}`);
+
+  if (Object.keys(providerStats).length > 0) {
+    console.log("\n  Provider Usage:");
+    for (const [provider, stats] of Object.entries(providerStats)) {
+      const statusIcon = stats.errors > 0 ? "🔴" : "🟢";
+      console.log(`  ${statusIcon} ${provider}: ${stats.count} requests (avg ${stats.avgLatency}ms)${stats.errors > 0 ? `, ${stats.errors} errors` : ""}`);
+    }
+  }
+
+  if (errors.length > 0) {
+    console.log("\n  Errors:");
+    for (const error of errors) {
+      console.log(`    ${error.provider}: ${error.error} (${error.count})`);
+    }
+  }
+
+  if (fallbacks.length > 0) {
+    console.log("\n  Fallbacks:");
+    for (const fallback of fallbacks) {
+      console.log(`    ${fallback.fromProvider} → ${fallback.toProvider} (${fallback.reason})`);
+    }
+  }
+
+  if (requestCount === 0) {
+    console.log("  No requests yet in this session.");
+  }
+  s.stop("Telemetry check complete");
+
+  // 7. Circuit Breaker Status
+  s.start("Checking circuit breaker...");
+  const circuitStates = circuitBreaker.getStates();
+  if (circuitStates.length > 0) {
+    console.log("\n" + pc.bold("Circuit Breaker Status:"));
+    for (const state of circuitStates) {
+      const icon = state.state === "closed" ? "🟢" : state.state === "half-open" ? "🟡" : "🔴";
+      console.log(`  ${icon} ${state.provider}: ${state.state} (${state.failures} failures)`);
+    }
+  } else {
+    console.log("  No circuit breaker activity yet.");
+  }
+  s.stop("Circuit breaker check complete");
+
+  // 8. Plugins
+  s.start("Checking plugins...");
+  const pluginCount = pluginManager.getPluginCount();
+  if (pluginCount > 0) {
+    const plugins = pluginManager.getPlugins();
+    console.log(`\n  Installed Plugins: ${pluginCount}`);
+    for (const plugin of plugins) {
+      console.log(`    - ${plugin.name} v${plugin.version}`);
+    }
+  } else {
+    console.log("  No plugins installed.");
+  }
+  s.stop("Plugin check complete");
+
   // Report
   console.log("\n" + pc.bold("Diagnostic Report:"));
-  checks.forEach(c => console.log(c));
+  for (const c of checks) {
+    console.log(c);
+  }
 
   if (warnings.length > 0) {
     console.log("");
-    warnings.forEach(w => console.log(pc.yellow(w)));
+    for (const w of warnings) {
+      console.log(pc.yellow(w));
+    }
   }
 
   if (issues.length > 0) {
     console.log("");
-    issues.forEach(i => console.log(pc.red(i)));
+    for (const i of issues) {
+      console.log(pc.red(i));
+    }
     outro(pc.red("Issues found. Please resolve them above."));
     process.exit(1);
   } else if (warnings.length > 0) {

package/src/commands/models.ts

@@ -0,0 +1,71 @@
+import { providerRegistry } from "../core/registry";
+import { pluginManager } from "../core/plugins";
+import { createLogger } from "../core/logger";
+
+const logger = createLogger();
+
+export async function modelsCommand(): Promise<void> {
+  console.log("\n");
+
+  const providers = providerRegistry.listProviders();
+  const plugins = pluginManager.getPlugins();
+
+  const allModels = providerRegistry.getAllModels();
+
+  const maxProviderWidth = Math.max(
+    ...providers.map(p => p.name.length),
+    ...plugins.map(p => p.name.length)
+  );
+  const maxModelWidth = Math.max(
+    ...allModels.map(m => `${m.provider.id}:${m.model.id}`.length),
+    30
+  );
+
+  console.log("╔" + "═".repeat(maxProviderWidth + maxModelWidth + 7) + "╗");
+  console.log("║" + " ".repeat(Math.floor((maxProviderWidth + maxModelWidth + 7 - 26) / 2)) + "ccx Available Models" + " ".repeat(Math.ceil((maxProviderWidth + maxModelWidth + 7 - 26) / 2)) + "║");
+  console.log("╠" + "═".repeat(maxProviderWidth + maxModelWidth + 7) + "╣");
+
+  for (const provider of providers) {
+    const statusIcon = provider.isNative ? "🔵" : "🟢";
+    const keyHint = provider.isNative ? "[Native - No proxy needed]" : `[Requires: ${provider.requiresKey.split(".").pop()?.replace("ApiKey", "_KEY") || "key"}]`;
+
+    console.log("║");
+    console.log(`║  ${statusIcon} ${provider.name.padEnd(maxProviderWidth)} ${keyHint}`);
+
+    for (const model of provider.models) {
+      const defaultMark = model.default ? " (default)" : "";
+      const modelLine = `  ├── ${model.id}${defaultMark}`;
+      console.log(`║  ${modelLine.padEnd(maxProviderWidth + maxModelWidth + 3)}║`);
+    }
+  }
+
+  console.log("║");
+  console.log("╠" + "═".repeat(maxProviderWidth + maxModelWidth + 7) + "╣");
+
+  if (plugins.length > 0) {
+    console.log("║");
+    console.log("║  Installed Plugins (" + plugins.length + ")");
+
+    for (const plugin of plugins) {
+      console.log(`║  ├── ${plugin.name} v${plugin.version}`);
+      for (const model of plugin.models) {
+        const modelLine = `  │   ├── ${model.id}`;
+        console.log(`║  ${modelLine.padEnd(maxProviderWidth + maxModelWidth + 3)}║`);
+      }
+    }
+  } else {
+    console.log("║");
+    console.log("║  Plugins: 0 installed");
+    console.log("║  To add a plugin, create: ~/.config/claude-glm/plugins/<name>/");
+  }
+
+  console.log("║");
+  console.log("╚" + "═".repeat(maxProviderWidth + maxModelWidth + 7) + "╝");
+  console.log("\n");
+  console.log("Usage:");
+  console.log("  ccx                    # Interactive selection");
+  console.log("  ccx --model=glm-4.7    # Use specific model");
+  console.log("  ccx --list             # Show this list");
+  console.log("  ccx setup              # Configure API keys");
+  console.log("\n");
+}