mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/029-provider-authentication.rispec.md

@@ -0,0 +1,225 @@
+# RISE-029: Provider Authentication
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/029-provider-authentication.rispec.md
+
+## Creative Intent
+
+mia-code manages authentication for every LLM provider through a flexible, secure credential system that supports API keys, OAuth browser flows, and custom enterprise auth plugins. Each provider's credentials are isolated — an expired Anthropic key doesn't prevent OpenAI from working. Developers authenticate once per provider and forget about it; tokens refresh silently, keys are resolved from environment variables or secure storage, and the `/auth` command provides a clear dashboard of what's connected and what needs attention. Authentication becomes invisible infrastructure rather than a recurring friction point.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Authentication is handled implicitly by the CLI binaries (`claude`, `gemini`) through their own auth flows
+- mia-code has no visibility into auth state — if a CLI binary's auth expires, the error surfaces as an opaque shell failure
+- There is no centralized credential store — each CLI binary manages its own tokens independently
+- Adding a new provider means understanding that provider's bespoke auth mechanism
+- No support for enterprise auth patterns (Azure AD, GCP service accounts, AWS IAM roles)
+- Environment variable references are not standardized — some providers use `ANTHROPIC_API_KEY`, others use different conventions
+- There is no way to check auth status across all configured providers at once
+
+**Desired State:**
+- A unified auth system manages credentials for all providers through a common interface
+- Three auth methods are supported: API key, OAuth browser flow, and custom auth plugins
+- API keys support `${ENV_VAR}` substitution or direct string storage
+- OAuth tokens are stored in a credential cache with automatic refresh
+- Auth status is queryable via `/auth` command showing all provider states
+- Per-provider credential isolation ensures one provider's auth failure doesn't cascade
+- Auth plugins allow enterprise teams to inject custom auth logic (Azure AD, SAML, etc.)
+
+## Desired Outcome Definition
+
+A developer sets up mia-code with three providers. For Anthropic, they set `ANTHROPIC_API_KEY` in their shell environment and reference it as `${ANTHROPIC_API_KEY}` in config. For GitHub Copilot, they run `/auth copilot` which opens a browser for OAuth — the token is stored in `~/.mia-code/auth/`. For their enterprise Azure OpenAI, an auth plugin handles Azure AD token acquisition. Running `/auth` shows all three as "✓ authenticated" with token expiry times. Two weeks later, the Copilot token auto-refreshes without intervention.
+
+## Natural Language Functional Description
+
+### Auth Method Interface
+
+Each auth method implements a common contract:
+
+```typescript
+interface AuthMethod {
+  type: "api_key" | "oauth" | "custom";
+  authenticate(provider: string): Promise<AuthCredential>;
+  refresh(credential: AuthCredential): Promise<AuthCredential>;
+  revoke(provider: string): Promise<void>;
+  status(provider: string): AuthStatus;
+}
+
+interface AuthCredential {
+  providerId: string;
+  type: "api_key" | "bearer_token" | "custom";
+  value: string;                 // the credential value
+  expiresAt?: number;            // Unix timestamp ms, undefined = never expires
+  refreshToken?: string;         // for OAuth refresh flow
+  metadata?: Record<string, string>;
+}
+
+interface AuthStatus {
+  providerId: string;
+  authenticated: boolean;
+  method: "api_key" | "oauth" | "custom";
+  expiresAt?: number;
+  lastUsed?: number;
+  error?: string;                // reason for auth failure if any
+}
+```
+
+### API Key Authentication
+
+The simplest and most common auth method:
+
+**Environment variable substitution:**
+```json
+{
+  "provider": {
+    "anthropic": {
+      "apiKey": "${ANTHROPIC_API_KEY}"
+    }
+  }
+}
+```
+
+At initialization, `${ANTHROPIC_API_KEY}` is resolved from `process.env.ANTHROPIC_API_KEY`. If the variable is unset, an `AuthConfigError` is emitted with the variable name and provider.
+
+**Direct string storage:**
+```json
+{
+  "provider": {
+    "groq": {
+      "apiKey": "gsk_abc123..."
+    }
+  }
+}
+```
+
+Direct keys are supported but discouraged in version-controlled config. The system warns if a direct key is detected in a git-tracked `mia-code.json`.
+
+**Key validation:** on first use, the system makes a lightweight API call (e.g. `listModels()`) to verify the key. Invalid keys surface immediately with a clear error rather than failing on the first chat request.
+
+### OAuth Browser Flow
+
+For providers requiring OAuth (GitHub Copilot, Google Vertex, GitLab):
+
+1. **Initiation:** developer runs `/auth copilot` or system detects OAuth-required provider
+2. **Authorization URL:** system generates provider-specific auth URL with required scopes
+3. **Browser redirect:** system opens the URL in the default browser (or displays it for manual copy)
+4. **Callback handling:** a temporary local HTTP server on `localhost:PORT` receives the OAuth callback
+5. **Token exchange:** authorization code is exchanged for access + refresh tokens
+6. **Storage:** tokens stored in `~/.mia-code/auth/{provider_id}.json` with restricted file permissions (0600)
+7. **Confirmation:** system displays "✓ Authenticated with {provider}" and auth status updates
+
+**Token refresh flow:**
+```typescript
+async function ensureValidToken(credential: AuthCredential): Promise<AuthCredential> {
+  if (!credential.expiresAt) return credential;  // no expiry
+  const bufferMs = 5 * 60 * 1000;  // refresh 5 min before expiry
+  if (Date.now() < credential.expiresAt - bufferMs) return credential;
+  // Token is expired or expiring soon — refresh
+  const refreshed = await authMethod.refresh(credential);
+  await credentialStore.save(refreshed);
+  return refreshed;
+}
+```
+
+### Custom Auth Plugins
+
+For enterprise environments with non-standard auth:
+
+```typescript
+interface AuthPlugin {
+  name: string;                  // e.g. "azure-ad", "okta-saml"
+  providerId: string;            // which provider this plugin handles
+  authenticate(): Promise<AuthCredential>;
+  refresh(credential: AuthCredential): Promise<AuthCredential>;
+  interceptHeaders(headers: Record<string, string>): Record<string, string>;
+}
+```
+
+Plugins can:
+- Acquire tokens through Azure AD client credential flow
+- Exchange SAML assertions for bearer tokens
+- Add custom headers (e.g. `X-Organization-Id`, `X-Project-Scope`)
+- Intercept and modify outbound request headers before they reach the provider SDK
+
+Plugins are loaded from `~/.mia-code/auth/plugins/` or specified in config:
+```json
+{
+  "auth": {
+    "plugins": [
+      { "name": "azure-ad", "providerId": "azure", "tenantId": "...", "clientId": "..." }
+    ]
+  }
+}
+```
+
+### Credential Store
+
+Credentials are persisted in `~/.mia-code/auth/`:
+
+```
+~/.mia-code/auth/
+├── anthropic.json       # API key credential
+├── copilot.json         # OAuth tokens (access + refresh)
+├── azure.json           # Custom plugin credential
+└── plugins/
+    └── azure-ad.js      # Custom auth plugin
+```
+
+Each credential file is JSON with restricted permissions. The store provides:
+- `save(credential)` — write credential to disk with 0600 permissions
+- `load(providerId)` — read credential from disk
+- `delete(providerId)` — remove credential file
+- `listAll()` — enumerate all stored credentials with status
+
+### The `/auth` Command
+
+The `/auth` command provides a dashboard of authentication status:
+
+```
+$ /auth
+
+Provider Authentication Status:
+┌────────────┬────────────┬───────────┬─────────────────┐
+│ Provider   │ Method     │ Status    │ Expires         │
+├────────────┼────────────┼───────────┼─────────────────┤
+│ anthropic  │ api_key    │ ✓ valid   │ never           │
+│ openai     │ api_key    │ ✓ valid   │ never           │
+│ copilot    │ oauth      │ ✓ valid   │ in 23 days      │
+│ azure      │ custom     │ ✓ valid   │ in 55 minutes   │
+│ vertex     │ oauth      │ ✗ expired │ 2 days ago      │
+└────────────┴────────────┴───────────┴─────────────────┘
+
+Run /auth <provider> to authenticate or re-authenticate.
+```
+
+### Security Considerations
+
+- API keys in config support `${ENV_VAR}` to avoid committing secrets
+- Direct API keys in git-tracked files trigger a warning
+- OAuth tokens stored with file permissions `0600` (owner read/write only)
+- Refresh tokens are never logged or included in error messages
+- Credential files are excluded from session sharing (RISE-022) and export
+- Auth failures are logged with provider ID and error type but never with credential values
+
+## Supporting Structures
+
+- **Multi-Provider Architecture (RISE-028)** defines the provider configs that reference auth credentials
+- **Provider SDK Abstraction (RISE-033)** uses credentials to authenticate API requests
+- **Named Error System (RISE-006)** provides AuthConfigError, TokenExpiredError, OAuthFlowError, PluginLoadError
+- **Structured Logging (RISE-007)** logs auth events (authenticate, refresh, revoke) without credential values
+- **Instance State Pattern (RISE-003)** manages auth state lifecycle within the application
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Zero-Friction Setup:**
+A developer installs mia-code and sets `ANTHROPIC_API_KEY` in their `.bashrc`. They add `"apiKey": "${ANTHROPIC_API_KEY}"` to config. On first use, mia-code resolves the variable, validates the key with a quick `listModels()` call, and confirms "✓ Anthropic authenticated." The developer never thinks about auth again.
+
+**Scenario 2 — OAuth for Copilot:**
+A developer wants to use GitHub Copilot models. They run `/auth copilot`. A browser window opens to GitHub's OAuth page. They click "Authorize." The browser redirects to `localhost:9876` where mia-code's temporary server captures the code, exchanges it for tokens, and stores them. "✓ Authenticated with GitHub Copilot" appears in the terminal. Twenty-nine days later, the token auto-refreshes during a normal session.
+
+**Scenario 3 — Enterprise Azure AD:**
+A corporate team uses Azure OpenAI with Azure AD authentication. Their platform team provides an auth plugin that acquires tokens via the client credential flow. The plugin is placed in `~/.mia-code/auth/plugins/azure-ad.js`. Config references it with tenant and client IDs. Developers run `/auth azure` once, the plugin acquires a token, and subsequent requests include the Azure AD bearer token automatically. Token refresh happens transparently every hour.
+
+**Scenario 4 — Auth Isolation:**
+A developer's Anthropic API key expires at midnight. Their morning session starts with an `AuthConfigError` for Anthropic. But their OpenAI and Groq providers remain fully functional. They switch to OpenAI for the morning's work, update the Anthropic key at lunch, and `/auth` confirms all three providers are green again. No cascading failure, no lost work.

package/rispecs/borrowed_from_opencode/030-model-registry.rispec.md

@@ -0,0 +1,222 @@
+# RISE-030: Model Registry
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/030-model-registry.rispec.md
+
+## Creative Intent
+
+mia-code maintains a centralized registry of LLM model metadata — context windows, token limits, pricing, and capabilities — powered by the models.dev API and cached locally. Instead of hardcoding model parameters or requiring developers to manually research which model supports vision or function calling, the registry provides a queryable catalog that enables intelligent defaults, cost-aware model selection, and capability-based feature gating. The developer says "I want the cheapest model that can handle images" and the registry answers. Model aliases like "fast," "smart," and "cheap" turn model selection from a research task into a single word.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Model parameters (context window, max tokens) are either hardcoded or unknown
+- There is no pricing data — developers have no visibility into per-token costs
+- Model capabilities are implicit — the system doesn't know if a model supports vision or function calling
+- Adding support for a new model requires code changes to register its parameters
+- Developers must manually research model specifications when choosing between options
+- No mechanism to suggest optimal models based on task requirements
+- Tool availability is static regardless of whether the model can actually use the tools
+
+**Desired State:**
+- A comprehensive model catalog is fetched from models.dev and cached locally
+- Each model entry includes context window, max output tokens, pricing, and capability flags
+- The registry is queryable: "which models support vision?", "what's the cheapest streaming model?"
+- Model aliases ("fast", "smart", "cheap") resolve to optimal models based on current registry data
+- Unknown models are treated as custom with user-provided overrides
+- Tool availability is gated by model capabilities — vision models get image tools, non-streaming models use polling
+- The registry updates automatically with a configurable TTL (default: 24 hours)
+
+## Desired Outcome Definition
+
+A developer configures an agent with model alias "fast." The registry resolves this to the cheapest streaming model currently available — perhaps `llama-3.1-8b` on Groq at $0.05/M tokens. When they switch to "smart," it resolves to `claude-sonnet-4-20250514` with its 200K context window. The developer never looked up a pricing page or a model spec sheet. When a new model is released, the registry picks it up on next refresh — no mia-code update required.
+
+## Natural Language Functional Description
+
+### Model Metadata Schema
+
+Each model in the registry carries:
+
+```typescript
+interface ModelInfo {
+  id: string;                    // e.g. "claude-sonnet-4-20250514", "gpt-4o"
+  name: string;                  // human-readable name
+  providerId: string;            // e.g. "anthropic", "openai"
+  contextWindow: number;         // max input tokens (e.g. 200000)
+  maxOutputTokens: number;       // max output tokens (e.g. 8192)
+  pricing: ModelPricing;
+  capabilities: ModelCapabilities;
+  releaseDate?: string;          // ISO date string
+  deprecationDate?: string;      // ISO date string if sunset planned
+}
+
+interface ModelPricing {
+  inputPerMToken: number;        // USD per million input tokens
+  outputPerMToken: number;       // USD per million output tokens
+  cacheReadPerMToken?: number;   // USD per million cache read tokens
+  cacheWritePerMToken?: number;  // USD per million cache write tokens
+}
+
+interface ModelCapabilities {
+  streaming: boolean;
+  vision: boolean;
+  functionCalling: boolean;
+  jsonMode: boolean;
+  extendedThinking: boolean;
+  codeExecution: boolean;
+  imageGeneration: boolean;
+  embedding: boolean;
+}
+```
+
+### Registry Data Source
+
+The registry fetches model catalogs from the models.dev API:
+
+```typescript
+interface RegistrySource {
+  fetchCatalog(): Promise<ModelInfo[]>;
+  lastFetched: number;           // Unix timestamp of last successful fetch
+  ttl: number;                   // cache TTL in ms (default: 24 * 60 * 60 * 1000)
+}
+```
+
+**Fetch lifecycle:**
+1. On first use (or after TTL expiry), fetch the full catalog from `https://models.dev/api/models`
+2. Parse response into `ModelInfo[]`, normalizing provider-specific fields
+3. Merge with any user-defined custom models from config
+4. Write to local cache at `~/.mia-code/cache/model-registry.json`
+5. Subsequent lookups read from cache until TTL expires
+
+**Offline behavior:** if the API is unreachable, use the cached catalog (even if expired). If no cache exists, fall back to a bundled baseline catalog shipped with mia-code. Log a warning about stale data.
+
+### Model Lookup and Resolution
+
+```typescript
+interface ModelRegistry {
+  getModel(modelId: string): ModelInfo | undefined;
+  getModelsForProvider(providerId: string): ModelInfo[];
+  findModels(filter: ModelFilter): ModelInfo[];
+  resolveAlias(alias: string): ModelInfo;
+  registerCustomModel(model: ModelInfo): void;
+  refresh(): Promise<void>;
+}
+
+interface ModelFilter {
+  providerId?: string;
+  capability?: keyof ModelCapabilities;
+  maxCostPerMToken?: number;     // filter by max input cost
+  minContextWindow?: number;     // filter by min context size
+}
+```
+
+**Resolution flow for a model ID:**
+1. Look up `modelId` in the registry → return `ModelInfo` if found
+2. If not found, check user-configured custom models
+3. If still not found, treat as unknown custom model — use defaults (128K context, no pricing, all capabilities assumed)
+4. Log a warning for unknown models suggesting the developer add metadata
+
+### Model Aliases
+
+Aliases provide semantic model selection:
+
+| Alias | Resolution Strategy |
+|---|---|
+| `fast` | Cheapest streaming-capable model with <2s time-to-first-token |
+| `smart` | Highest-capability model (function calling + vision + extended thinking) |
+| `cheap` | Lowest cost per million tokens (input + output averaged) |
+| `big` | Largest context window available |
+| `local` | Model served by a custom/local provider |
+
+Alias resolution considers only currently configured and authenticated providers. If the developer has only Anthropic configured, "fast" resolves to the cheapest Anthropic model, not an unconfigured Groq model.
+
+Custom aliases can be defined in config:
+```json
+{
+  "modelAliases": {
+    "team-default": "claude-sonnet-4-20250514",
+    "review": "gpt-4o",
+    "draft": "llama-3.1-70b"
+  }
+}
+```
+
+### Capability-Based Feature Gating
+
+Model capabilities influence which tools and features are available:
+
+- **Vision-capable models** (`vision: true`): image tools are enabled — screenshot analysis, diagram reading, image-based context
+- **Non-streaming models** (`streaming: false`): response delivery switches to polling mode instead of SSE deltas
+- **Function-calling models** (`functionCalling: true`): tool use is enabled; without it, tools are described in the system prompt as text instructions
+- **JSON mode models** (`jsonMode: true`): structured output extraction uses native JSON mode
+- **Extended thinking models** (`extendedThinking: true`): thinking budget controls are exposed
+
+```typescript
+function getAvailableTools(model: ModelInfo, allTools: Tool[]): Tool[] {
+  return allTools.filter(tool => {
+    if (tool.requiresVision && !model.capabilities.vision) return false;
+    if (tool.requiresStreaming && !model.capabilities.streaming) return false;
+    return true;
+  });
+}
+```
+
+### Custom Model Registration
+
+For models not in the models.dev catalog (private fine-tunes, self-hosted models):
+
+```json
+{
+  "models": {
+    "my-finetuned-llama": {
+      "providerId": "custom",
+      "contextWindow": 32768,
+      "maxOutputTokens": 4096,
+      "pricing": { "inputPerMToken": 0, "outputPerMToken": 0 },
+      "capabilities": {
+        "streaming": true,
+        "vision": false,
+        "functionCalling": true,
+        "jsonMode": true,
+        "extendedThinking": false,
+        "codeExecution": false,
+        "imageGeneration": false,
+        "embedding": false
+      }
+    }
+  }
+}
+```
+
+### Intelligent Defaults
+
+The registry enables cost-aware suggestions:
+
+- When creating a new agent, suggest the cheapest model meeting the agent's capability requirements
+- When an explore sub-agent is configured with an expensive model, suggest a cheaper alternative
+- When context overflow occurs (RISE-019), suggest a model with a larger context window
+- Present cost comparison: "Using gpt-4o ($2.50/M) — claude-haiku would cost $0.25/M for this task"
+
+## Supporting Structures
+
+- **Multi-Provider Architecture (RISE-028)** uses registry data to map models to providers
+- **Cost Tracking (RISE-031)** uses pricing data from the registry for real-time cost calculation
+- **Agent Definition Config (RISE-010)** references model IDs and aliases resolved by the registry
+- **Provider Transform Pipeline (RISE-032)** uses model capabilities to adjust request formatting
+- **Session Compaction (RISE-019)** consults context window size from registry
+- **Named Error System (RISE-006)** provides ModelNotFoundError, RegistryFetchError, AliasResolutionError
+- **Lazy Initialization (RISE-008)** defers registry fetch until first model lookup
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Automatic Cost Optimization:**
+A developer creates a sub-agent for code exploration. They don't specify a model. The registry's intelligent defaults select `llama-3.1-8b` on Groq — it's fast, cheap ($0.05/M), supports streaming and function calling, and is perfect for explore tasks. The main coding agent stays on Claude. The developer didn't research pricing; the registry made the optimal choice.
+
+**Scenario 2 — New Model Adoption:**
+Anthropic releases Claude 4 Opus. The models.dev API updates within hours. On the developer's next session, the registry refreshes (24h TTL expired), picks up the new model with its context window, pricing, and capabilities. The developer can immediately use it by specifying the model ID — no mia-code update required.
+
+**Scenario 3 — Capability-Gated Tools:**
+A developer switches from Claude (vision-capable) to Mistral (no vision). The registry detects the capability change. Image-related tools (screenshot analysis, image context) are automatically hidden from the tool list. The developer isn't offered tools that would fail. When they switch back to Claude, vision tools reappear.
+
+**Scenario 4 — Team Standardization:**
+A team lead defines custom aliases in the shared `mia-code.json`: `"team-default"` → `claude-sonnet-4-20250514`, `"review"` → `gpt-4o`, `"draft"` → `llama-3.1-70b`. Team members use aliases instead of model IDs. When pricing changes make a different model optimal, the lead updates one alias — every team member gets the change on next session.