mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/031-cost-tracking.rispec.md

@@ -0,0 +1,243 @@
+# RISE-031: Cost Tracking
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/031-cost-tracking.rispec.md
+
+## Creative Intent
+
+mia-code tracks every token consumed and every dollar spent in real time, per message, per session, per agent, and per provider. Developers see costs accumulate as they work — not as a surprise on their monthly bill. The system calculates costs using the model registry's pricing data, stores them alongside message metadata, warns when budgets are approached, and suggests optimizations. Cost visibility transforms LLM usage from an opaque expense into a manageable engineering resource with clear per-task attribution.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Token consumption is invisible — developers have no idea how many tokens a session uses
+- Cost is discovered only when checking the provider's billing dashboard, often days later
+- There is no per-session, per-agent, or per-message cost attribution
+- No mechanism to set spending limits or receive budget warnings
+- Cache tokens (reads and writes) are not tracked separately despite different pricing
+- Sub-agents may consume disproportionate tokens with no visibility into the breakdown
+- Developers cannot compare the cost efficiency of different models for the same task
+
+**Desired State:**
+- Every message records input tokens, output tokens, cache read tokens, and cache write tokens
+- Cost is calculated in real time using pricing from the model registry (RISE-030)
+- Running cost is displayed per message and accumulated per session
+- Cost breakdowns are available per agent, per model, and per provider
+- Configurable cost alerts warn when session or daily spend exceeds thresholds
+- Cost optimization suggestions identify savings opportunities
+- Historical cost data is available via the `/costs` command
+
+## Desired Outcome Definition
+
+A developer starts a coding session. Each assistant message displays its cost: "$0.03 (1.2K in / 0.8K out)." The session status bar shows a running total: "$0.47 session total." When the total crosses $2.00, a yellow warning appears: "⚠ Session cost: $2.07 — approaching $3.00 limit." At session end, a summary shows cost per agent: main agent $1.80, explore agent $0.27. A suggestion notes: "Switching explore tasks to claude-haiku would save ~60%."
+
+## Natural Language Functional Description
+
+### Token Tracking Schema
+
+Each message records token consumption in its metadata:
+
+```typescript
+interface TokenUsage {
+  inputTokens: number;           // tokens in the request (prompt + context)
+  outputTokens: number;          // tokens in the response
+  cacheReadTokens: number;       // tokens served from provider cache
+  cacheWriteTokens: number;      // tokens written to provider cache
+  totalTokens: number;           // inputTokens + outputTokens
+}
+
+interface CostMetadata {
+  usage: TokenUsage;
+  model: string;                 // model ID used for this message
+  providerId: string;            // provider that served the request
+  cost: CostBreakdown;
+  timestamp: number;             // Unix timestamp ms
+}
+
+interface CostBreakdown {
+  inputCost: number;             // USD: inputTokens * inputRate
+  outputCost: number;            // USD: outputTokens * outputRate
+  cacheReadCost: number;         // USD: cacheReadTokens * cacheReadRate
+  cacheWriteCost: number;        // USD: cacheWriteTokens * cacheWriteRate
+  totalCost: number;             // sum of all cost components
+}
+```
+
+### Cost Calculation
+
+Cost is computed using pricing from the model registry (RISE-030):
+
+```typescript
+function calculateCost(usage: TokenUsage, pricing: ModelPricing): CostBreakdown {
+  const inputCost = (usage.inputTokens / 1_000_000) * pricing.inputPerMToken;
+  const outputCost = (usage.outputTokens / 1_000_000) * pricing.outputPerMToken;
+  const cacheReadCost = (usage.cacheReadTokens / 1_000_000) * (pricing.cacheReadPerMToken ?? 0);
+  const cacheWriteCost = (usage.cacheWriteTokens / 1_000_000) * (pricing.cacheWritePerMToken ?? 0);
+
+  return {
+    inputCost,
+    outputCost,
+    cacheReadCost,
+    cacheWriteCost,
+    totalCost: inputCost + outputCost + cacheReadCost + cacheWriteCost,
+  };
+}
+```
+
+For models without pricing data (custom/local models), cost is recorded as $0.00 with a note that pricing is unavailable.
+
+### Real-Time Cost Display
+
+Costs are displayed at multiple granularities:
+
+**Per-message cost** — shown after each assistant response:
+```
+Assistant: [response text...]
+  ── claude-sonnet-4-20250514 · 1,247 in · 832 out · $0.031 ──
+```
+
+**Session running total** — updated in the status bar after each message:
+```
+Session: 12 messages · 45.2K tokens · $1.47
+```
+
+**Streaming cost** — during generation, MetadataDelta events (RISE-027) update the cost counter in real time. The developer sees cost climbing as the response generates.
+
+### Session Cost Summary
+
+At session end or via `/costs session`, a comprehensive breakdown is displayed:
+
+```
+Session Cost Summary
+────────────────────
+Total Cost:     $2.34
+Total Tokens:   78,432 (62,100 in / 16,332 out)
+Duration:       47 minutes
+Messages:       24
+
+By Agent:
+  main (claude-sonnet-4-20250514):     $1.89  (80.8%)
+  explore (claude-haiku-3.5):          $0.31  (13.2%)
+  compaction (claude-haiku-3.5):       $0.14   (6.0%)
+
+By Cost Type:
+  Input:       $0.93  (39.7%)
+  Output:      $1.22  (52.1%)
+  Cache Read:  $0.08   (3.4%)
+  Cache Write: $0.11   (4.7%)
+```
+
+### Cost Alerts
+
+Configurable thresholds trigger warnings:
+
+```json
+{
+  "costs": {
+    "sessionWarningUsd": 3.00,
+    "sessionLimitUsd": 10.00,
+    "dailyWarningUsd": 20.00,
+    "dailyLimitUsd": 50.00
+  }
+}
+```
+
+**Warning behavior:**
+- At warning threshold: yellow notification — "⚠ Session cost: $3.12 — approaching $10.00 limit"
+- At limit threshold: red notification — "🛑 Session cost limit reached ($10.00). Continue? [y/N]"
+- Daily limits aggregate across all sessions in a calendar day
+- Limits are soft by default — the developer can override and continue
+
+### Cost Optimization Suggestions
+
+After each session, the system analyzes usage patterns and suggests savings:
+
+```typescript
+interface CostOptimization {
+  suggestion: string;
+  estimatedSavings: number;      // USD saved per session
+  savingsPercent: number;
+  affectedAgent?: string;
+  currentModel: string;
+  suggestedModel: string;
+}
+```
+
+Example suggestions:
+- "Explore agent used 12,400 tokens on claude-sonnet-4-20250514 ($0.31). Switching to claude-haiku ($0.05) would save ~84%."
+- "Compaction used 8,200 output tokens. Enabling cache write would save ~40% on subsequent compactions."
+- "3 messages exceeded 4K output tokens. Setting maxTokens: 4096 would cap output costs."
+
+### The `/costs` Command
+
+```
+/costs                    Show current session costs
+/costs session            Detailed session breakdown
+/costs daily              Today's total across all sessions
+/costs weekly             This week's cost report
+/costs model <id>         Costs for a specific model
+/costs provider <id>      Costs for a specific provider
+```
+
+**Daily/weekly reports** aggregate from stored session metadata:
+
+```
+Daily Cost Report — 2025-02-17
+──────────────────────────────
+Sessions: 5
+Total Cost: $8.72
+
+By Model:
+  claude-sonnet-4-20250514:  $6.14  (4 sessions)
+  claude-haiku-3.5:          $1.23  (5 sessions)
+  gpt-4o:                    $1.35  (1 session)
+```
+
+### Cost Storage
+
+Cost data is persisted in message metadata (RISE-026) and aggregated in session metadata (RISE-018):
+
+```typescript
+// In MessageMetadata (RISE-026)
+interface MessageMetadata {
+  model?: string;
+  input_tokens?: number;
+  output_tokens?: number;
+  cached_tokens?: number;
+  cost?: number;                 // total cost in USD
+  cost_breakdown?: CostBreakdown;
+}
+
+// Session-level aggregation
+interface SessionCostSummary {
+  totalCost: number;
+  totalTokens: number;
+  byAgent: Record<string, number>;
+  byModel: Record<string, number>;
+  byProvider: Record<string, number>;
+}
+```
+
+## Supporting Structures
+
+- **Model Registry (RISE-030)** provides per-model pricing data for cost calculations
+- **Message Parts Model (RISE-026)** stores cost metadata alongside message content
+- **Streaming Message Deltas (RISE-027)** emits MetadataDelta events for real-time cost display
+- **Session Persistence (RISE-018)** stores session-level cost aggregations
+- **Multi-Agent System (RISE-009)** enables per-agent cost attribution
+- **Structured Logging (RISE-007)** logs cost events for historical analysis
+- **Named Error System (RISE-006)** provides CostLimitExceededError, PricingUnavailableError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Budget-Conscious Development:**
+A freelance developer sets a $5.00 daily limit. During the day, they see running costs on every message. At $4.20, a yellow warning appears. They switch their explore agent from Claude Sonnet to Haiku for the remaining tasks. They finish the day at $4.85 — under budget, fully aware of every dollar spent.
+
+**Scenario 2 — Team Cost Attribution:**
+A team uses mia-code on a shared Anthropic API key. Weekly cost reports show per-developer breakdown (via session metadata). The team lead notices one developer's sessions average $15/day while others average $3. Investigation reveals they're using the main agent for explore tasks. A quick config change to use Haiku for exploration cuts their cost by 70%.
+
+**Scenario 3 — Model Comparison:**
+A developer runs the same refactoring task with three different models. Cost tracking shows: Claude Sonnet ($0.45, 12 min), GPT-4o ($0.38, 8 min), Gemini 2.5 ($0.22, 15 min). Quality was comparable across all three. They switch their default to Gemini for routine tasks — a data-driven decision enabled by per-session cost tracking.
+
+**Scenario 4 — Cache Optimization:**
+Cost breakdown reveals that 60% of input tokens are repeated context (system prompts, file contents). The developer enables cache write for their system prompt. Next session's cost breakdown shows cache read tokens replacing input tokens — a 40% input cost reduction. The optimization is visible in the numbers, not theoretical.

package/rispecs/borrowed_from_opencode/032-provider-transform-pipeline.rispec.md

@@ -0,0 +1,282 @@
+# RISE-032: Provider Transform Pipeline
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/032-provider-transform-pipeline.rispec.md
+
+## Creative Intent
+
+mia-code insulates its core logic from the chaotic diversity of LLM provider APIs through a structured request/response transformation pipeline. Anthropic uses a `system` parameter and content blocks; OpenAI uses a `system` role message and inline tool calls; Google Gemini uses `systemInstruction` and `functionCall` parts. The transform pipeline normalizes these differences so that mia-code's agent loop, tool system, and session management operate on a single internal format — never touching provider-specific structures. Adding a new provider means writing a pair of transformers, not modifying core logic.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- mia-code shells out to CLI binaries, so format differences are hidden behind each binary's argument parsing
+- But this also means mia-code has no control over how messages, tools, or system prompts are formatted
+- There is no internal canonical message format — messages are text strings shaped for the target CLI
+- Each provider integration duplicates format logic: how to pass system prompts, tools, images
+- Error responses from different providers have completely different structures and error codes
+- Streaming chunk formats vary between providers — SSE events, JSON lines, protobuf
+- Image content is encoded differently: base64 inline, URL references, multipart form data
+
+**Desired State:**
+- mia-code has a well-defined internal message format that all core logic operates on
+- A transform pipeline converts between internal format and each provider's API format
+- Request transforms: internal → provider-specific request body
+- Response transforms: provider-specific response → internal format
+- Streaming transforms: provider-specific chunks → normalized Delta events (RISE-027)
+- Error transforms: provider-specific errors → Named Error System errors (RISE-006)
+- Each provider registers its transformer pair — no core logic changes needed
+
+## Desired Outcome Definition
+
+A developer's prompt flows through the pipeline: mia-code constructs an internal `ChatRequest` with messages, tools, and a system prompt. The Anthropic transformer converts it — moving the system prompt to the `system` parameter, reformatting tool definitions to Anthropic's schema, converting image parts to base64 content blocks. The response arrives in Anthropic's format; the reverse transformer normalizes it back to internal `AssistantMessage` with typed parts. If the developer switches to OpenAI, a different transformer pair handles the conversion — but the agent loop, tool executor, and session manager see identical structures.
+
+## Natural Language Functional Description
+
+### Internal Message Format
+
+The canonical internal format that all mia-code core logic operates on:
+
+```typescript
+interface InternalChatRequest {
+  messages: InternalMessage[];
+  systemPrompt?: string;
+  tools?: InternalToolDefinition[];
+  model: string;
+  options: {
+    temperature?: number;
+    maxTokens?: number;
+    stopSequences?: string[];
+    responseFormat?: "text" | "json";
+    stream: boolean;
+  };
+}
+
+interface InternalMessage {
+  role: "user" | "assistant";
+  parts: InternalPart[];         // uses RISE-026 part types
+}
+
+interface InternalToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;  // JSON Schema
+}
+```
+
+### Transform Pipeline Architecture
+
+The pipeline has three stages for requests and three for responses:
+
+```
+Request Flow:
+  InternalChatRequest
+    → [Pre-Transform Hooks]
+    → [Provider Request Transformer]
+    → Provider-specific API request body
+
+Response Flow:
+  Provider-specific API response
+    → [Provider Response Transformer]
+    → [Post-Transform Hooks]
+    → InternalAssistantMessage
+
+Streaming Flow:
+  Provider-specific stream chunk
+    → [Provider Stream Transformer]
+    → Normalized Delta event (RISE-027)
+```
+
+### Transformer Interface
+
+Each provider registers a transformer implementing:
+
+```typescript
+interface ProviderTransformer {
+  providerId: string;
+
+  // Request direction: internal → provider
+  transformRequest(request: InternalChatRequest): ProviderRequest;
+
+  // Response direction: provider → internal
+  transformResponse(response: ProviderResponse): InternalAssistantMessage;
+
+  // Streaming: provider chunk → normalized delta
+  transformStreamChunk(chunk: ProviderStreamChunk): Delta[];
+
+  // Errors: provider error → named error
+  transformError(error: ProviderError): MiaCodeError;
+}
+```
+
+### System Prompt Handling
+
+System prompts are handled differently by each provider:
+
+| Provider | System Prompt Location |
+|---|---|
+| Anthropic | Top-level `system` parameter (string or content blocks) |
+| OpenAI | First message with `role: "system"` |
+| Google Gemini | `systemInstruction` field in request body |
+| Mistral | First message with `role: "system"` |
+| Cohere | `preamble` field |
+
+The request transformer moves the internal `systemPrompt` string to the correct location:
+
+```typescript
+// Anthropic transformer
+transformRequest(request: InternalChatRequest): AnthropicRequest {
+  return {
+    model: request.model,
+    system: request.systemPrompt,  // top-level parameter
+    messages: request.messages.map(m => this.transformMessage(m)),
+    tools: request.tools?.map(t => this.transformTool(t)),
+    max_tokens: request.options.maxTokens ?? 8192,
+  };
+}
+
+// OpenAI transformer
+transformRequest(request: InternalChatRequest): OpenAIRequest {
+  const messages = [];
+  if (request.systemPrompt) {
+    messages.push({ role: "system", content: request.systemPrompt });
+  }
+  messages.push(...request.messages.map(m => this.transformMessage(m)));
+  return {
+    model: request.model,
+    messages,
+    tools: request.tools?.map(t => this.transformTool(t)),
+    max_tokens: request.options.maxTokens,
+  };
+}
+```
+
+### Tool Call Format Normalization
+
+Tool definitions and tool calls vary significantly:
+
+**Anthropic format:**
+```json
+{ "name": "edit_file", "input": { "path": "src/app.ts", "content": "..." } }
+```
+
+**OpenAI format:**
+```json
+{ "id": "call_abc", "type": "function", "function": { "name": "edit_file", "arguments": "{\"path\":\"src/app.ts\"}" } }
+```
+
+**Gemini format:**
+```json
+{ "functionCall": { "name": "edit_file", "args": { "path": "src/app.ts" } } }
+```
+
+The response transformer normalizes all of these to the internal `ToolCallPart` (RISE-026):
+```typescript
+{ type: "tool_call", tool_call_id: "...", tool_name: "edit_file", arguments: { path: "src/app.ts" } }
+```
+
+### Image Content Transformation
+
+Image encoding varies by provider:
+
+| Provider | Image Format |
+|---|---|
+| Anthropic | `{ type: "image", source: { type: "base64", media_type, data } }` |
+| OpenAI | `{ type: "image_url", image_url: { url: "data:image/png;base64,..." } }` |
+| Gemini | `{ inlineData: { mimeType, data } }` |
+
+The request transformer converts internal `ImagePart` to provider-specific encoding:
+
+```typescript
+// Internal ImagePart → Anthropic content block
+transformImagePart(part: ImagePart): AnthropicContentBlock {
+  return {
+    type: "image",
+    source: { type: "base64", media_type: part.mime_type, data: part.data },
+  };
+}
+
+// Internal ImagePart → OpenAI content part
+transformImagePart(part: ImagePart): OpenAIContentPart {
+  return {
+    type: "image_url",
+    image_url: { url: `data:${part.mime_type};base64,${part.data}` },
+  };
+}
+```
+
+### Streaming Chunk Normalization
+
+Each provider emits streaming chunks in different formats:
+
+- **Anthropic:** `content_block_start`, `content_block_delta`, `message_delta` events
+- **OpenAI:** `chat.completion.chunk` with `choices[0].delta`
+- **Gemini:** `generateContent` response chunks with `candidates[0].content`
+
+The stream transformer converts each provider's chunk format into the normalized Delta types defined in RISE-027 (TextDelta, ToolCallStart, ToolCallDelta, etc.).
+
+### Error Response Mapping
+
+Provider error responses are mapped to the Named Error System (RISE-006):
+
+| Provider Error | Internal Error |
+|---|---|
+| Anthropic `overloaded_error` | `ProviderOverloadedError` |
+| OpenAI `rate_limit_exceeded` | `RateLimitError` |
+| Gemini `RESOURCE_EXHAUSTED` | `RateLimitError` |
+| Anthropic `authentication_error` | `AuthenticationError` |
+| OpenAI `invalid_api_key` | `AuthenticationError` |
+| Any `context_length_exceeded` | `ContextOverflowError` |
+| Any HTTP 500/502/503 | `ProviderServerError` |
+
+```typescript
+transformError(error: ProviderError): MiaCodeError {
+  if (error.status === 429 || error.code === "rate_limit_exceeded") {
+    return new RateLimitError(this.providerId, {
+      retryAfter: error.headers?.["retry-after"],
+    });
+  }
+  // ... other mappings
+}
+```
+
+### Custom Transform Hooks
+
+Providers can register pre- and post-transform hooks for cross-cutting concerns:
+
+```typescript
+interface TransformHook {
+  name: string;
+  phase: "pre-request" | "post-response";
+  execute(data: unknown): unknown;
+}
+```
+
+Use cases for hooks:
+- **Prompt caching:** inject cache control headers for Anthropic's prompt caching
+- **Content filtering:** strip or flag sensitive content before sending to certain providers
+- **Logging:** capture raw request/response for debugging without polluting transformer logic
+- **Metrics:** record transform latency and payload sizes
+
+## Supporting Structures
+
+- **Multi-Provider Architecture (RISE-028)** routes requests to the correct provider and transformer pair
+- **Provider SDK Abstraction (RISE-033)** sends the transformed request and receives the raw response
+- **Message Parts Model (RISE-026)** defines the internal part types the pipeline normalizes to/from
+- **Streaming Message Deltas (RISE-027)** defines the Delta types the stream transformer produces
+- **Named Error System (RISE-006)** provides the error types that provider errors are mapped to
+- **Zod Schema Validation (RISE-005)** validates transformer output against internal schemas
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Transparent Provider Switch:**
+A developer switches from Anthropic to OpenAI mid-project. The agent loop, tool executor, and session manager are entirely unaware — they continue operating on internal message formats. Only the transformer pair changes. The developer's tools, system prompts, and conversation history work identically because the pipeline handles all format differences.
+
+**Scenario 2 — New Provider in an Afternoon:**
+A developer wants to add support for a new provider (Fireworks AI) that uses an OpenAI-compatible API. They extend the OpenAI transformer, override the endpoint URL, and adjust one tool call format field. No changes to mia-code's core logic, agent system, or tool infrastructure. The new provider is usable within hours.
+
+**Scenario 3 — Image Context Across Providers:**
+A developer pastes a screenshot. The internal `ImagePart` is created once. When sent to Anthropic, the transformer wraps it in a `source.base64` content block. If the fallback triggers and it goes to OpenAI instead, the transformer creates a `data:` URL. The developer doesn't know or care — their screenshot just works with any provider.
+
+**Scenario 4 — Error Normalization:**
+Anthropic returns an `overloaded_error` with a custom JSON body. OpenAI returns a `429` with a `retry-after` header. Gemini returns a `RESOURCE_EXHAUSTED` gRPC status. The pipeline normalizes all three to a `RateLimitError` with a consistent interface. The retry logic handles one error type, not three provider-specific ones.