Skip to content

PRD.md

Latest commit

 

History

History
83 lines (55 loc) · 5.84 KB

PRD.md

File metadata and controls

83 lines (55 loc) · 5.84 KB
Raw

Product Requirements Document (PRD)

Project Name: OpenCode Go Multi-Account Router Plugin Document Version: 1.1 Target Platform: OpenCode CLI (Local Provider Plugin)

1. Overview

The OpenCode Go Multi-Account Router is a native TypeScript provider plugin that manages multiple OpenCode Go API subscriptions. It pools multiple $10/month Go quotas into a single workflow, switching accounts automatically based on limit exhaustion or round-robin strategies. It provides a local Web UI for secure key management and usage tracking, ensuring uninterrupted agentic coding sessions while explicitly preserving OpenCode's native context caching mechanisms.

2. Reference Repositories (clone them to better read the files)

This project blends specific architectural choices and features from two community repositories:

  • ndycode/codex-multi-auth:
    • Adopted: Native TypeScript plugin architecture, multiple switching strategies (limit exhaustion, round-robin), and local Web UI concepts.
    • Discarded: Automated credential scraping/auto-login logic.
  • ArsalanDotMe/switchboard-go:
    • Adopted: The proxy-style concept of trapping API limit errors to trigger a failover.
    • Discarded: SMTP email alerting and headless-only configuration.
  • https://github.com/junhoyeo/tokscale
    • just for the token usage

3. Core Features & Requirements

3.1. Dynamic Switching Strategies

The router must support multiple selectable strategies for handling outgoing API requests:

  • Exhaustion Failover (Fallback Mode): Routes all traffic through Account A. If Account A returns a limit-exhausted error (402 Payment Required / 429 Too Many Requests), the router places Account A on "cooldown" (e.g., 5 hours) and seamlessly reroutes the request to Account B without crashing the user's CLI session.
  • Round-Robin (Load Balancing): Cycles through available API keys sequentially on every API call, distributing the token load across all active accounts evenly.

3.2. Proactive Quota Tracking & Circuit Breaker

  • Quota Tracking: Locally track token usage/cost against the known $60 Go limit per key. The plugin should switch accounts gracefully right before hitting the hard limit, rather than waiting for an API error.
  • Circuit Breaker: Monitor the health of each key. If an account returns three consecutive 5xx server errors (indicating OpenCode API load, not an empty wallet), the Circuit Breaker temporarily removes that key from the pool and reroutes traffic to prevent agent latency spikes.

3.3. Cache-Preserving Header Passthrough (Critical Path)

OpenCode relies on specific headers to trigger massive cost discounts for cached contexts ($0.0028/M vs $0.14/M for DeepSeek V4 Flash). The AI agent building this software must explicitly confirm all API calls and headers.

  • Passthrough Requirement: The plugin must intercept, preserve, and forward all caching headers generated by the native OpenCode CLI, specifically: X-Session-Id, prompt_cache_key, and cache_control arrays.
  • Development Instruction: If the intercepted API call already contains caching information from the CLI, the router must pass it through unmodified. If it is missing, the router does nothing (it must not artificially inject false session IDs).
  • Cold Start Warning: If a failover occurs, the new API key will not have the context cached on the server. The plugin must log a warning indicating that the first request on the new key will be a "cache miss."

3.4. Local Web UI Dashboard

A lightweight embedded Node server (e.g., Express or Fastify) serving a local web interface (e.g., http://localhost:XXXX), chose less common and available port.

  • Key Management: Secure form to manually add/remove OpenCode Go API keys.
  • Strategy Selector: Dropdown to instantly change the active routing strategy.
  • Status Ledger: Visual indicator of account health, quota remaining, and cooldown status.
  • Log Viewer: Real-time feed of local logs.

3.5. Secure API Key Storage

  • Keys must not be stored in plain text JSON files. The application must utilize secure local storage (e.g., keytar or OS-equivalent Node library) to interface with the host OS's native secure credential store (macOS Keychain, Windows Credential Manager, or Linux Secret Service API).

3.6. Local Logging

  • Log all routing decisions, exhaustion triggers, cache-miss failovers, and cooldown timers to a local file (e.g., ~/.opencode/router.log). Display these logs in the Web UI.

4. Explicitly Excluded Features

  • No Auto-Login Scripts: The plugin will not scrape the OpenCode website to log in. Users must manually paste their API keys into the Web UI.
  • No Remote Notifications: No SMTP, email alerts, or webhooks. Logging is strictly local.

5. Architecture & Tech Stack

  • Core Plugin: TypeScript / Node.js (conforming to the OpenCode Provider Plugin API).
  • Web Server: Embedded Node server (Express/Fastify).
  • Frontend UI: Vanilla JS/HTML/CSS or a lightweight framework (Preact/Svelte).
  • Security: OS-level credential vault libraries.

6. User Flow

  1. Installation: User installs the plugin via OpenCode CLI.
  2. Initialization: The plugin boots its background Web UI server on an available port.
  3. Configuration: User navigates to the local Web UI, selects "Add Account", and manually pastes their OpenCode Go API keys.
  4. Strategy Selection: User selects "Exhaustion Failover" from the dashboard.
  5. Execution: User runs a standard OpenCode agentic task.
    • The plugin intercepts the request, verifies X-Session-Id caching headers are present, attaches Key A, and forwards it.
    • If Key A fails due to limits, the plugin triggers the Circuit Breaker, retries with Key B, and logs a "cold start cache miss" warning to the local file and Web UI.