opencode-morph-rotation 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rnbsov
+
+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,84 @@
+# opencode-morph-rotation
+
+OpenCode plugin for automatic Morph API key rotation with rate-limit handling.
+
+## Features
+
+- 🔄 Automatic key rotation when rate limited
+- 📊 Key health monitoring and status reporting
+- ➕ Add/remove keys at runtime via tools
+- 🛡️ Auto-disable keys after repeated failures
+- 📋 `/morph-quota` slash command for quick status
+
+## Installation
+
+Add to your `opencode.jsonc`:
+
+```jsonc
+{
+  "plugin": [
+    "opencode-morph-rotation@latest"
+  ]
+}
+```
+
+Then restart OpenCode.
+
+## Setup
+
+### 1. Add your keys
+
+Use the `morph_add_key` tool in chat:
+
+> Add my Morph key sk-ABC123... with label "account1"
+
+Or manually create `~/.config/opencode/morph-keys.json`:
+
+```json
+{
+  "keys": [
+    {
+      "key": "sk-YOUR_KEY_1",
+      "label": "account1",
+      "enabled": true,
+      "rateLimitResetTime": 0,
+      "consecutiveFailures": 0,
+      "lastUsed": 0,
+      "addedAt": 1711152000000
+    }
+  ],
+  "strategy": "least-recently-used",
+  "defaultCooldownMs": 60000,
+  "maxConsecutiveFailures": 5
+}
+```
+
+### 2. Remove MORPH_API_KEY from MCP config
+
+Since the plugin injects `MORPH_API_KEY` via `shell.env`, remove any hardcoded key from your MCP server config to avoid conflicts.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `morph_quota` | Show status of all keys |
+| `morph_add_key` | Add a new key for rotation |
+| `morph_remove_key` | Remove a key by label |
+| `morph_mark_rate_limited` | Manually mark a key as rate limited |
+
+## Rotation Strategies
+
+- **least-recently-used** (default): Picks the key used longest ago
+- **round-robin**: Cycles through keys in order
+- **sticky**: Stays on current key until it fails
+
+## How It Works
+
+1. Plugin loads on OpenCode start
+2. Before each shell/tool execution, `shell.env` hook picks the best available key
+3. When a key hits rate limit (429), use `morph_mark_rate_limited` to rotate
+4. Disabled keys re-enable after cooldown period
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,25 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "opencode-morph-rotation",
+      "dependencies": {
+        "@opencode-ai/plugin": "^1.3.0",
+        "zod": "^3.24.0",
+      },
+      "peerDependencies": {
+        "@opencode-ai/plugin": ">=0.15.30",
+      },
+    },
+  },
+  "packages": {
+    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.3.0", "", { "dependencies": { "@opencode-ai/sdk": "1.3.0", "zod": "4.1.8" } }, "sha512-mR1Kdcpr3Iv+KS7cL2DRFB6QAcSoR6/DojmwuxYF/pMCahMtaCLiqZGQjoSNl12+gQ6RsIJJyUh/jX3JVlOx8A=="],
+
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.3.0", "", {}, "sha512-5WyYEpcV6Zk9otXOMIrvZRbJm1yxt/c8EXSBn1p6Sw1yagz8HRljkoUTJFxzD0x2+/6vAZItr3OrXDZfE+oA2g=="],
+
+    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+
+    "@opencode-ai/plugin/zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
+  }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "opencode-morph-rotation",
+  "version": "0.1.0",
+  "description": "OpenCode plugin for Morph API key rotation with rate limit handling",
+  "main": "src/index.ts",
+  "type": "module",
+  "keywords": ["opencode", "opencode-plugin", "morph", "api-key-rotation", "rate-limit"],
+  "author": "rnbsov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rnbsov/opencode-morph-rotation"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.3.0",
+    "zod": "^3.24.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=0.15.30"
+  }
+}

package/src/config.ts

@@ -0,0 +1,43 @@
+import { join } from 'path';
+import { homedir } from 'os';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import type { MorphKeysConfig } from './types';
+import { DEFAULT_CONFIG } from './types';
+
+const CONFIG_DIR = join(homedir(), '.config', 'opencode');
+const KEYS_FILE = join(CONFIG_DIR, 'morph-keys.json');
+const COMMAND_DIR = join(CONFIG_DIR, 'command');
+const COMMAND_FILE = join(COMMAND_DIR, 'morph-quota.md');
+
+export { CONFIG_DIR, KEYS_FILE, COMMAND_DIR, COMMAND_FILE };
+
+export function loadKeysConfig(): MorphKeysConfig {
+  if (!existsSync(KEYS_FILE)) {
+    return { ...DEFAULT_CONFIG };
+  }
+  try {
+    const raw = readFileSync(KEYS_FILE, 'utf-8');
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULT_CONFIG, ...parsed };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+export function saveKeysConfig(config: MorphKeysConfig): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(KEYS_FILE, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+export function ensureCommandFile(): void {
+  mkdirSync(COMMAND_DIR, { recursive: true });
+  if (!existsSync(COMMAND_FILE)) {
+    const content = `---
+name: morph-quota
+description: Check Morph API key rotation status and quota
+---
+Check the status of all configured Morph API keys, including which are active, rate-limited, or disabled. Shows rotation strategy and key health.
+`;
+    writeFileSync(COMMAND_FILE, content, 'utf-8');
+  }
+}

package/src/index.ts

@@ -0,0 +1,169 @@
+import type { Plugin } from '@opencode-ai/plugin';
+import { tool } from '@opencode-ai/plugin';
+import { z } from 'zod';
+import { KeyManager } from './key-manager';
+import { loadKeysConfig, saveKeysConfig, ensureCommandFile } from './config';
+import { maskKey, formatDuration, keyStatusLine } from './utils';
+
+export const plugin: Plugin = async (ctx) => {
+  const config = loadKeysConfig();
+  const manager = new KeyManager(config);
+
+  // Create /morph-quota command file
+  ensureCommandFile();
+
+  // Save config periodically (on key state changes)
+  const persistConfig = () => {
+    try {
+      saveKeysConfig(manager.getConfig());
+    } catch {
+      // Silent fail on config save
+    }
+  };
+
+  return {
+    'shell.env': async () => {
+      const bestKey = manager.getBestKey();
+      if (bestKey) {
+        return { MORPH_API_KEY: bestKey.key };
+      }
+      // If no keys available, don't override existing env
+      return {};
+    },
+
+    tool: {
+      morph_quota: tool({
+        description:
+          'Show status of all configured Morph API keys including rotation state, rate limits, and health',
+        args: {},
+        execute: async () => {
+          const statuses = manager.getAllStatus();
+          if (statuses.length === 0) {
+            return 'No Morph API keys configured. Use morph_add_key to add keys.';
+          }
+
+          const now = Date.now();
+          const lines: string[] = ['## Morph Key Rotation Status\n'];
+          const cfg = manager.getConfig();
+          lines.push(`Strategy: **${cfg.strategy}**`);
+          lines.push(`Keys: ${statuses.length} total\n`);
+
+          for (const k of statuses) {
+            let status: 'active' | 'rate-limited' | 'disabled' | 'cooldown';
+            let extra = '';
+
+            if (!k.enabled) {
+              status = 'disabled';
+              extra = `(${k.consecutiveFailures} failures)`;
+            } else if (k.rateLimitResetTime > now) {
+              status = 'cooldown';
+              extra = `resets in ${formatDuration(k.rateLimitResetTime - now)}`;
+            } else {
+              status = 'active';
+              if (k.lastUsed > 0) {
+                extra = `last used ${formatDuration(now - k.lastUsed)} ago`;
+              } else {
+                extra = 'never used';
+              }
+            }
+
+            lines.push(keyStatusLine(k.label, maskKey(k.key), status, extra));
+          }
+
+          const bestKey = manager.getBestKey();
+          if (bestKey) {
+            lines.push(`\nCurrent key: **${bestKey.label}** (${maskKey(bestKey.key)})`);
+          } else {
+            lines.push('\n⚠️ No keys currently available! All rate-limited or disabled.');
+          }
+
+          return lines.join('\n');
+        },
+      }),
+
+      morph_add_key: tool({
+        description: 'Add a new Morph API key for rotation',
+        args: {
+          key: z.string().describe('The Morph API key (sk-...)'),
+          label: z.string().describe('Human-readable label for this key (e.g., account name)'),
+        },
+        execute: async (args) => {
+          if (!args.key.startsWith('sk-') && !args.key.startsWith('morph-')) {
+            return 'Invalid key format. Morph keys start with sk- or morph-';
+          }
+          const added = manager.addKey(args.key, args.label);
+          if (!added) {
+            return `Key already exists: ${maskKey(args.key)}`;
+          }
+          persistConfig();
+          return `Added key "${args.label}" (${maskKey(args.key)}). Total keys: ${manager.getAllStatus().length}`;
+        },
+      }),
+
+      morph_remove_key: tool({
+        description: 'Remove a Morph API key from rotation',
+        args: {
+          label: z.string().describe('Label of the key to remove'),
+        },
+        execute: async (args) => {
+          const statuses = manager.getAllStatus();
+          const keyToRemove = statuses.find((k) => k.label === args.label);
+          if (!keyToRemove) {
+            const available = statuses.map((k) => k.label).join(', ');
+            return `Key "${args.label}" not found. Available: ${available}`;
+          }
+          manager.removeKey(keyToRemove.key);
+          persistConfig();
+          return `Removed key "${args.label}". Remaining: ${manager.getAllStatus().length}`;
+        },
+      }),
+
+      morph_mark_rate_limited: tool({
+        description:
+          'Mark a Morph API key as rate limited. Use when you receive a 429 error from Morph API.',
+        args: {
+          label: z
+            .string()
+            .optional()
+            .describe('Label of the key to mark. If omitted, marks the current key.'),
+          cooldown_seconds: z
+            .number()
+            .optional()
+            .describe('Cooldown in seconds. Default: 60'),
+        },
+        execute: async (args) => {
+          let keyToMark: string | undefined;
+
+          if (args.label) {
+            const found = manager.getAllStatus().find((k) => k.label === args.label);
+            keyToMark = found?.key;
+          } else {
+            // Mark the most recently used key (the "current" one)
+            const bestKey = manager.getBestKey();
+            keyToMark = bestKey?.key;
+          }
+
+          if (!keyToMark) {
+            return 'No key found to mark as rate limited.';
+          }
+
+          const cooldownMs = (args.cooldown_seconds ?? 60) * 1000;
+          manager.markRateLimited(keyToMark, cooldownMs);
+          persistConfig();
+
+          const status = manager.getKeyStatus(keyToMark);
+          const nextKey = manager.getBestKey();
+          let msg = `Marked ${maskKey(keyToMark)} as rate limited for ${args.cooldown_seconds ?? 60}s.`;
+          if (nextKey) {
+            msg += ` Rotated to: ${nextKey.label} (${maskKey(nextKey.key)})`;
+          } else {
+            msg += ' ⚠️ No more keys available!';
+          }
+          return msg;
+        },
+      }),
+    },
+  };
+};
+
+export default plugin;

package/src/key-manager.ts

@@ -0,0 +1,107 @@
+import type { MorphKey, MorphKeysConfig } from './types';
+
+export class KeyManager {
+  private config: MorphKeysConfig;
+
+  constructor(config: MorphKeysConfig) {
+    this.config = config;
+  }
+
+  /** Get the best available key based on strategy */
+  getBestKey(): MorphKey | null {
+    const now = Date.now();
+    const available = this.config.keys.filter(
+      (k) => k.enabled && k.rateLimitResetTime < now
+    );
+
+    if (available.length === 0) return null;
+
+    switch (this.config.strategy) {
+      case 'round-robin':
+        return available.sort((a, b) => a.lastUsed - b.lastUsed)[0];
+
+      case 'least-recently-used':
+        return available.sort((a, b) => a.lastUsed - b.lastUsed)[0];
+
+      case 'sticky':
+        return available.sort((a, b) => b.lastUsed - a.lastUsed)[0];
+
+      default:
+        return available[0];
+    }
+  }
+
+  /** Mark a key as rate limited */
+  markRateLimited(apiKey: string, cooldownMs?: number): void {
+    const key = this.findKey(apiKey);
+    if (!key) return;
+    const cooldown = cooldownMs ?? this.config.defaultCooldownMs;
+    key.rateLimitResetTime = Date.now() + cooldown;
+    key.consecutiveFailures++;
+    this.checkDisable(key);
+  }
+
+  /** Mark a key as failed (non-rate-limit failure) */
+  markFailed(apiKey: string): void {
+    const key = this.findKey(apiKey);
+    if (!key) return;
+    key.consecutiveFailures++;
+    this.checkDisable(key);
+  }
+
+  /** Mark a key as successfully used */
+  markSuccess(apiKey: string): void {
+    const key = this.findKey(apiKey);
+    if (!key) return;
+    key.consecutiveFailures = 0;
+    key.lastUsed = Date.now();
+  }
+
+  /** Get status of a specific key */
+  getKeyStatus(apiKey: string): MorphKey | undefined {
+    return this.findKey(apiKey);
+  }
+
+  /** Get all key statuses */
+  getAllStatus(): MorphKey[] {
+    return [...this.config.keys];
+  }
+
+  /** Add a new key */
+  addKey(apiKey: string, label: string): boolean {
+    if (this.findKey(apiKey)) return false;
+    this.config.keys.push({
+      key: apiKey,
+      label,
+      enabled: true,
+      rateLimitResetTime: 0,
+      consecutiveFailures: 0,
+      lastUsed: 0,
+      addedAt: Date.now(),
+    });
+    return true;
+  }
+
+  /** Remove a key */
+  removeKey(apiKey: string): boolean {
+    const idx = this.config.keys.findIndex((k) => k.key === apiKey);
+    if (idx === -1) return false;
+    this.config.keys.splice(idx, 1);
+    return true;
+  }
+
+  /** Get the underlying config for saving */
+  getConfig(): MorphKeysConfig {
+    return this.config;
+  }
+
+  private findKey(apiKey: string): MorphKey | undefined {
+    return this.config.keys.find((k) => k.key === apiKey);
+  }
+
+  private checkDisable(key: MorphKey): void {
+    if (key.consecutiveFailures >= this.config.maxConsecutiveFailures) {
+      key.enabled = false;
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,33 @@
+export interface MorphKey {
+  /** The API key string (sk-...) */
+  key: string;
+  /** Human-readable label for this key */
+  label: string;
+  /** Whether this key is enabled for rotation */
+  enabled: boolean;
+  /** Timestamp when rate limit resets (0 = not rate limited) */
+  rateLimitResetTime: number;
+  /** Number of consecutive failures */
+  consecutiveFailures: number;
+  /** Timestamp of last successful use */
+  lastUsed: number;
+  /** Timestamp when key was added */
+  addedAt: number;
+}
+
+export interface MorphKeysConfig {
+  keys: MorphKey[];
+  /** Rotation strategy: 'round-robin' | 'least-recently-used' | 'sticky' */
+  strategy: 'round-robin' | 'least-recently-used' | 'sticky';
+  /** Default cooldown in ms when rate limited without Retry-After header */
+  defaultCooldownMs: number;
+  /** Max consecutive failures before disabling a key */
+  maxConsecutiveFailures: number;
+}
+
+export const DEFAULT_CONFIG: MorphKeysConfig = {
+  keys: [],
+  strategy: 'least-recently-used',
+  defaultCooldownMs: 60_000,
+  maxConsecutiveFailures: 5,
+};

package/src/utils.ts

@@ -0,0 +1,37 @@
+export function maskKey(key: string): string {
+  if (key.length <= 8) return '****';
+  return key.slice(0, 6) + '...' + key.slice(-4);
+}
+
+export function formatDuration(ms: number): string {
+  if (ms <= 0) return 'now';
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ${minutes % 60}m`;
+}
+
+export function progressBar(current: number, max: number, width = 20): string {
+  const ratio = Math.min(current / max, 1);
+  const filled = Math.round(ratio * width);
+  const empty = width - filled;
+  return `[${'█'.repeat(filled)}${'░'.repeat(empty)}] ${Math.round(ratio * 100)}%`;
+}
+
+export function keyStatusLine(
+  label: string,
+  maskedKey: string,
+  status: 'active' | 'rate-limited' | 'disabled' | 'cooldown',
+  extra?: string
+): string {
+  const icons: Record<string, string> = {
+    active: '🟢',
+    'rate-limited': '🟡',
+    disabled: '🔴',
+    cooldown: '⏳',
+  };
+  const icon = icons[status] || '⚪';
+  return `${icon} ${label} (${maskedKey}) — ${status}${extra ? ` ${extra}` : ''}`;
+}

package/tests/key-manager.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeEach } from 'bun:test';
+import { KeyManager } from '../src/key-manager';
+import type { MorphKeysConfig, MorphKey } from '../src/types';
+import { DEFAULT_CONFIG } from '../src/types';
+
+function makeKey(label: string, key = `sk-${label}`): MorphKey {
+  return {
+    key,
+    label,
+    enabled: true,
+    rateLimitResetTime: 0,
+    consecutiveFailures: 0,
+    lastUsed: 0,
+    addedAt: Date.now(),
+  };
+}
+
+describe('KeyManager', () => {
+  let manager: KeyManager;
+
+  beforeEach(() => {
+    const config: MorphKeysConfig = {
+      ...DEFAULT_CONFIG,
+      keys: [makeKey('key1'), makeKey('key2'), makeKey('key3')],
+    };
+    manager = new KeyManager(config);
+  });
+
+  it('should return a key when keys are available', () => {
+    const key = manager.getBestKey();
+    expect(key).not.toBeNull();
+    expect(key!.key).toStartWith('sk-');
+  });
+
+  it('should skip rate-limited keys', () => {
+    manager.markRateLimited('sk-key1', 60_000);
+    const key = manager.getBestKey();
+    expect(key).not.toBeNull();
+    expect(key!.key).not.toBe('sk-key1');
+  });
+
+  it('should return null when all keys are rate-limited', () => {
+    manager.markRateLimited('sk-key1', 60_000);
+    manager.markRateLimited('sk-key2', 60_000);
+    manager.markRateLimited('sk-key3', 60_000);
+    const key = manager.getBestKey();
+    expect(key).toBeNull();
+  });
+
+  it('should disable key after max consecutive failures', () => {
+    for (let i = 0; i < 5; i++) {
+      manager.markFailed('sk-key1');
+    }
+    const status = manager.getKeyStatus('sk-key1');
+    expect(status?.enabled).toBe(false);
+  });
+
+  it('should reset failure count on success', () => {
+    manager.markFailed('sk-key1');
+    manager.markFailed('sk-key1');
+    manager.markSuccess('sk-key1');
+    const status = manager.getKeyStatus('sk-key1');
+    expect(status?.consecutiveFailures).toBe(0);
+  });
+
+  it('should use least-recently-used strategy', () => {
+    // Use key1, then key2
+    manager.markSuccess('sk-key1');
+    manager.markSuccess('sk-key2');
+    // Next key should be key3 (never used)
+    const key = manager.getBestKey();
+    expect(key!.key).toBe('sk-key3');
+  });
+
+  it('should return all keys status', () => {
+    const statuses = manager.getAllStatus();
+    expect(statuses).toHaveLength(3);
+  });
+
+  it('should add a new key', () => {
+    manager.addKey('sk-new', 'new-key');
+    const statuses = manager.getAllStatus();
+    expect(statuses).toHaveLength(4);
+  });
+
+  it('should not add duplicate key', () => {
+    const added = manager.addKey('sk-key1', 'duplicate');
+    expect(added).toBe(false);
+  });
+
+  it('should remove a key', () => {
+    const removed = manager.removeKey('sk-key1');
+    expect(removed).toBe(true);
+    expect(manager.getAllStatus()).toHaveLength(2);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "declaration": true,
+    "sourceMap": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}