lynkr 4.2.0 → 4.2.1

package/LYNKR-TUI-PLAN.md

@@ -0,0 +1,984 @@
+# Lynkr TUI Implementation Plan
+
+> Fork OpenCode + OpenTUI to build a companion TUI for Lynkr
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Architecture Mapping](#part-1-architecture-mapping)
+3. [API to Component Mapping](#part-2-lynkr-api--tui-component-mapping)
+4. [TUI Component Architecture](#part-3-tui-component-architecture)
+5. [Communication Protocol](#part-4-communication-protocol)
+6. [Implementation Phases](#part-5-implementation-phases)
+7. [File-by-File Checklist](#part-6-file-by-file-implementation-checklist)
+8. [Summary & Next Steps](#summary)
+
+---
+
+## Executive Summary
+
+**Goal:** Fork OpenCode and OpenTUI to create `lynkr-tui` - a terminal user interface companion for Lynkr proxy server.
+
+**Key Technologies:**
+- **OpenTUI** - TypeScript/Zig TUI framework (`@opentui/core`, `@opentui/react`, `@opentui/solid`)
+- **OpenCode** - Reference TUI implementation to fork and adapt
+- **Lynkr** - Backend proxy server (existing)
+
+**Why Fork OpenCode?**
+- Client/server architecture already decoupled
+- Polished TUI built by terminal experts
+- OpenTUI framework is modern and performant
+- MIT licensed, allowing modification
+
+---
+
+## Part 1: Architecture Mapping
+
+### 1.1 Lynkr Backend ↔ OpenCode Backend Comparison
+
+| Aspect | Lynkr | OpenCode | Mapping Strategy |
+|--------|-------|----------|------------------|
+| **API Format** | Anthropic (`/v1/messages`) + OpenAI (`/v1/chat/completions`) | Custom protocol | TUI calls Lynkr's existing endpoints |
+| **Streaming** | SSE (Server-Sent Events) | Unknown (likely SSE/WebSocket) | Use Lynkr's SSE format directly |
+| **Session Management** | `x-session-id` header, SQLite persistence | Built-in session tracking | Map session IDs between systems |
+| **Tool System** | Anthropic tool format, smart selection | Custom tools | Passthrough to Lynkr's tool execution |
+| **Memory** | SQLite FTS5, surprise-based extraction | Unknown | Expose Lynkr memory via new API |
+| **Providers** | 9+ providers with smart routing | Claude, OpenAI, Google, local | Leverage Lynkr's routing |
+| **Agents** | Executor + parallel coordinator | build/plan/general agents | Map agent modes to Lynkr config |
+
+### 1.2 OpenTUI Package Structure → Lynkr TUI
+
+```
+OpenTUI Packages:
+├── @opentui/core     → Use directly (rendering primitives)
+├── @opentui/react    → Use directly (React reconciler)
+└── @opentui/solid    → Optional (if prefer SolidJS)
+
+OpenCode Packages (to fork):
+├── packages/tui/     → Fork and adapt for Lynkr
+├── packages/core/    → Replace with Lynkr client
+└── packages/shared/  → Adapt types for Lynkr
+```
+
+---
+
+## Part 2: Lynkr API → TUI Component Mapping
+
+### 2.1 Core API Endpoints → Components
+
+| Lynkr Endpoint | Method | TUI Component | Purpose |
+|----------------|--------|---------------|---------|
+| `/v1/messages` | POST (SSE) | `<ChatView>` | Main conversation, streaming |
+| `/v1/messages/count_tokens` | POST | `<TokenCounter>` | Pre-send token estimation |
+| `/v1/models` | GET | `<ModelSelector>` | Provider/model selection |
+| `/health/live` | GET | `<StatusIndicator>` | Connection status |
+| `/health/ready` | GET | `<ProviderStatus>` | Deep health with provider check |
+| `/api/sessions/:id/tokens` | GET | `<TokenDashboard>` | Session token usage |
+| `/api/tokens/stats` | GET | `<CostAnalytics>` | Global cost tracking |
+| `/v1/agents` | GET | `<AgentSelector>` | List available agents |
+| `/v1/agents/stats` | GET | `<AgentStats>` | Agent performance metrics |
+| `/v1/agents/:id/transcript` | GET | `<AgentTranscript>` | Agent execution history |
+| `/metrics` | GET | `<MetricsDashboard>` | Prometheus metrics view |
+
+### 2.2 New API Endpoints Required for TUI
+
+| New Endpoint | Method | Purpose | Implementation |
+|--------------|--------|---------|----------------|
+| `/v1/memory/search` | POST | Search memories for inspector | Wrap `memory/search.js` |
+| `/v1/memory/list` | GET | List recent memories | Wrap `memory/store.js` |
+| `/v1/memory/:id` | GET/DELETE | Memory CRUD | Wrap store operations |
+| `/v1/providers/status` | GET | All provider health | Aggregate health checks |
+| `/v1/config` | GET | Runtime configuration | Expose safe config values |
+| `/ws/session/:id` | WebSocket | Real-time bidirectional | New implementation |
+
+### 2.3 Lynkr SSE Events → TUI State Updates
+
+```
+Lynkr SSE Event Stream:
+┌─────────────────────────────────────────────────────────────┐
+│ event: message_start                                        │
+│ data: {"type":"message_start","message":{...}}             │
+│                         ↓                                   │
+│         TUI: Create message bubble, show typing indicator   │
+├─────────────────────────────────────────────────────────────┤
+│ event: content_block_start                                  │
+│ data: {"type":"content_block_start","index":0,...}         │
+│                         ↓                                   │
+│         TUI: Initialize content block (text/tool_use)       │
+├─────────────────────────────────────────────────────────────┤
+│ event: content_block_delta                                  │
+│ data: {"type":"content_block_delta","delta":{"text":"..."}}│
+│                         ↓                                   │
+│         TUI: Append text to message, re-render              │
+├─────────────────────────────────────────────────────────────┤
+│ event: content_block_stop                                   │
+│ data: {"type":"content_block_stop","index":0}              │
+│                         ↓                                   │
+│         TUI: Finalize block, enable interactions            │
+├─────────────────────────────────────────────────────────────┤
+│ event: message_delta                                        │
+│ data: {"type":"message_delta","usage":{...}}               │
+│                         ↓                                   │
+│         TUI: Update token counter, cost display             │
+├─────────────────────────────────────────────────────────────┤
+│ event: message_stop                                         │
+│ data: {"type":"message_stop"}                              │
+│                         ↓                                   │
+│         TUI: Enable input, update history                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Part 3: TUI Component Architecture
+
+### 3.1 Screen Layout Structure
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ [Lynkr TUI]                                    [●] Provider: Databricks │
+│─────────────────────────────────────────────────────────────────────────│
+│                                                                         │
+│  ┌─ Chat Panel (70%) ─────────────────────┐  ┌─ Side Panel (30%) ────┐ │
+│  │                                         │  │ ┌─ Token Usage ─────┐ │ │
+│  │  [User] How do I implement caching?     │  │ │ In:  ████░ 45k    │ │ │
+│  │                                         │  │ │ Out: ██░░░ 8k     │ │ │
+│  │  [Assistant] I'll help you implement... │  │ │ Cost: $0.42       │ │ │
+│  │  ```typescript                          │  │ └───────────────────┘ │ │
+│  │  const cache = new Map();               │  │ ┌─ Provider Status ─┐ │ │
+│  │  ```                                    │  │ │ ● Databricks  OK  │ │ │
+│  │                                         │  │ │ ● Ollama     OK   │ │ │
+│  │  [Tool: Read] src/cache.ts              │  │ │ ○ Bedrock   STBY  │ │ │
+│  │  ┌────────────────────────────────────┐ │  │ └───────────────────┘ │ │
+│  │  │ 1│ import { LRUCache } from 'lru'; │ │  │ ┌─ Agent Mode ──────┐ │ │
+│  │  │ 2│ export const cache = ...        │ │  │ │ [●] BUILD         │ │ │
+│  │  └────────────────────────────────────┘ │  │ │ [ ] PLAN          │ │ │
+│  │                                         │  │ │ [ ] ANALYZE       │ │ │
+│  │                                         │  │ └───────────────────┘ │ │
+│  └─────────────────────────────────────────┘  │ ┌─ Memory ──────────┐ │ │
+│                                               │ │ 3 relevant        │ │ │
+│  ┌─ Input ────────────────────────────────┐   │ │ memories found    │ │ │
+│  │ > _                                    │   │ │ [View]            │ │ │
+│  │                                [Send]  │   │ └───────────────────┘ │ │
+│  └────────────────────────────────────────┘   └───────────────────────┘ │
+│─────────────────────────────────────────────────────────────────────────│
+│ [Tab] Mode │ [Ctrl+M] Memory │ [Ctrl+P] Providers │ [?] Help │ v1.0.0  │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 Component Hierarchy
+
+```
+<App>
+├── <LynkrProvider>              # Context: connection, config, session
+│   ├── <Layout>
+│   │   ├── <Header>
+│   │   │   ├── <Logo />
+│   │   │   ├── <ConnectionStatus />    # /health/live
+│   │   │   └── <ProviderBadge />       # Current provider
+│   │   │
+│   │   ├── <MainContent>
+│   │   │   ├── <ChatPanel>
+│   │   │   │   ├── <MessageList>
+│   │   │   │   │   ├── <Message role="user" />
+│   │   │   │   │   ├── <Message role="assistant">
+│   │   │   │   │   │   ├── <TextBlock />
+│   │   │   │   │   │   ├── <CodeBlock language="ts" />
+│   │   │   │   │   │   ├── <ToolUseBlock>
+│   │   │   │   │   │   │   ├── <ToolHeader name="Read" />
+│   │   │   │   │   │   │   ├── <ToolInput />
+│   │   │   │   │   │   │   └── <ToolOutput />
+│   │   │   │   │   │   └── </ToolUseBlock>
+│   │   │   │   │   └── </Message>
+│   │   │   │   └── </MessageList>
+│   │   │   │   └── <StreamingIndicator />
+│   │   │   └── </ChatPanel>
+│   │   │   │
+│   │   │   └── <SidePanel>
+│   │   │       ├── <TokenDashboard>     # /api/sessions/:id/tokens
+│   │   │       │   ├── <TokenBar label="Input" />
+│   │   │       │   ├── <TokenBar label="Output" />
+│   │   │       │   ├── <CacheHitRate />
+│   │   │       │   └── <CostDisplay />
+│   │   │       ├── <ProviderStatusPanel>  # /health/ready?deep=true
+│   │   │       │   └── <ProviderRow /> × N
+│   │   │       ├── <AgentModeSelector>    # Lynkr agent modes
+│   │   │       │   ├── <ModeOption mode="build" />
+│   │   │       │   ├── <ModeOption mode="plan" />
+│   │   │       │   └── <ModeOption mode="analyze" />
+│   │   │       └── <MemoryPreview>        # /v1/memory/search
+│   │   │           └── <MemoryItem /> × N
+│   │   │       </SidePanel>
+│   │   │   </MainContent>
+│   │   │
+│   │   ├── <InputArea>
+│   │   │   ├── <TextInput multiline />
+│   │   │   ├── <FileAttachButton />
+│   │   │   └── <SendButton />
+│   │   └── </InputArea>
+│   │   │
+│   │   └── <StatusBar>
+│   │       ├── <KeybindingHints />
+│   │       ├── <SessionInfo />
+│   │       └── <Version />
+│   │   </StatusBar>
+│   └── </Layout>
+│
+├── <ModalManager>               # Overlay modals
+│   ├── <MemoryInspectorModal>   # Full memory browser
+│   ├── <ProviderConfigModal>    # Provider settings
+│   ├── <SettingsModal>          # TUI configuration
+│   └── <HelpModal>              # Keybindings reference
+└── </ModalManager>
+</LynkrProvider>
+</App>
+```
+
+### 3.3 Lynkr-Specific Components (New)
+
+| Component | Lynkr Feature | Data Source |
+|-----------|---------------|-------------|
+| `<TokenDashboard>` | Token optimization tracking | `/api/sessions/:id/tokens` |
+| `<ProviderStatusPanel>` | Multi-provider health | `/health/ready?deep=true` |
+| `<SmartRoutingIndicator>` | Show Ollama↔Cloud routing | Response headers |
+| `<MemoryInspector>` | Browse/search memories | `/v1/memory/search` (new) |
+| `<MemoryInjectionPreview>` | Show injected memories | Response metadata |
+| `<AgentModeSelector>` | Build/Plan/Analyze modes | Config + policy |
+| `<CostAnalytics>` | Cost savings dashboard | `/api/tokens/stats` |
+| `<CircuitBreakerStatus>` | Provider circuit states | `/health/ready` |
+| `<ToolSelectionBadge>` | Smart tool selection mode | Response metadata |
+
+---
+
+## Part 4: Communication Protocol
+
+### 4.1 Lynkr Client Module Structure
+
+```typescript
+// packages/lynkr-client/src/index.ts
+
+export interface LynkrClientConfig {
+  baseUrl: string;              // http://localhost:8081
+  sessionId?: string;           // Persistent session
+  timeout?: number;             // Request timeout
+  retries?: number;             // Retry count
+  onEvent?: (event: LynkrEvent) => void;  // SSE callback
+}
+
+export class LynkrClient {
+  // Core messaging
+  sendMessage(content: string, options?: MessageOptions): AsyncGenerator<StreamEvent>
+  countTokens(messages: Message[]): Promise<TokenCount>
+
+  // Session management
+  getSession(): Promise<Session>
+  getSessionTokens(): Promise<TokenStats>
+
+  // Health & status
+  checkHealth(): Promise<HealthStatus>
+  checkReady(deep?: boolean): Promise<ReadyStatus>
+  getProviderStatus(): Promise<ProviderStatus[]>
+
+  // Memory (requires new endpoints)
+  searchMemories(query: string): Promise<Memory[]>
+  listMemories(options?: ListOptions): Promise<Memory[]>
+  deleteMemory(id: number): Promise<void>
+
+  // Agents
+  listAgents(): Promise<Agent[]>
+  getAgentStats(): Promise<AgentStats>
+  getAgentTranscript(id: string): Promise<Transcript>
+
+  // Models
+  listModels(): Promise<Model[]>
+
+  // Metrics
+  getMetrics(): Promise<PrometheusMetrics>
+  getTokenStats(): Promise<GlobalTokenStats>
+}
+```
+
+### 4.2 SSE Stream Handler
+
+```typescript
+// packages/lynkr-client/src/streaming.ts
+
+export type StreamEvent =
+  | { type: 'message_start'; message: MessageStart }
+  | { type: 'content_block_start'; index: number; content_block: ContentBlock }
+  | { type: 'content_block_delta'; index: number; delta: Delta }
+  | { type: 'content_block_stop'; index: number }
+  | { type: 'message_delta'; delta: MessageDelta; usage: Usage }
+  | { type: 'message_stop' }
+  | { type: 'error'; error: ErrorInfo }
+
+export async function* streamMessages(
+  baseUrl: string,
+  request: MessageRequest,
+  sessionId: string
+): AsyncGenerator<StreamEvent> {
+  const response = await fetch(`${baseUrl}/v1/messages`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-session-id': sessionId,
+      'Accept': 'text/event-stream'
+    },
+    body: JSON.stringify({ ...request, stream: true })
+  });
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split('\n');
+    buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      if (line.startsWith('data: ')) {
+        const data = line.slice(6);
+        if (data === '[DONE]') return;
+        yield JSON.parse(data) as StreamEvent;
+      }
+    }
+  }
+}
+```
+
+### 4.3 State Management (TUI Side)
+
+```typescript
+// packages/tui/src/stores/chat.ts
+
+interface ChatState {
+  messages: Message[];
+  isStreaming: boolean;
+  currentStreamId: string | null;
+
+  // Lynkr-specific
+  tokenUsage: TokenUsage;
+  activeProvider: string;
+  routingDecision: 'ollama' | 'cloud' | null;
+  injectedMemories: Memory[];
+  selectedTools: string[];
+  agentMode: 'build' | 'plan' | 'analyze';
+}
+
+interface Message {
+  id: string;
+  role: 'user' | 'assistant';
+  content: ContentBlock[];
+  timestamp: number;
+
+  // Lynkr metadata
+  provider?: string;
+  modelId?: string;
+  usage?: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+  };
+  toolCalls?: ToolCall[];
+}
+```
+
+### 4.4 Request/Response Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           TUI → LYNKR FLOW                              │
+└─────────────────────────────────────────────────────────────────────────┘
+
+User Input
+    │
+    ▼
+┌─────────────────┐
+│  <InputArea>    │
+│  onSubmit()     │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  chatStore.sendMessage(content)         │
+│  ├─ Set isStreaming = true              │
+│  ├─ Add user message to messages[]      │
+│  └─ Create placeholder assistant msg    │
+└────────┬────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  lynkrClient.sendMessage(content)       │
+│  ├─ POST /v1/messages                   │
+│  ├─ Headers: x-session-id, stream=true  │
+│  └─ Body: { messages, tools?, system? } │
+└────────┬────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  LYNKR BACKEND                          │
+│  ├─ Session middleware (extract/create) │
+│  ├─ Smart tool selection                │
+│  ├─ Memory retrieval & injection        │
+│  ├─ Provider routing (Ollama/Cloud)     │
+│  ├─ Model invocation                    │
+│  └─ SSE stream response                 │
+└────────┬────────────────────────────────┘
+         │
+         ▼ (SSE events)
+┌─────────────────────────────────────────┐
+│  for await (event of stream)            │
+│  ├─ message_start → init metadata       │
+│  ├─ content_block_start → add block     │
+│  ├─ content_block_delta → append text   │
+│  ├─ content_block_stop → finalize       │
+│  ├─ message_delta → update usage        │
+│  └─ message_stop → complete             │
+└────────┬────────────────────────────────┘
+         │
+         ▼
+┌─────────────────────────────────────────┐
+│  chatStore.updateMessage(id, content)   │
+│  ├─ Update assistant message content    │
+│  ├─ Update tokenUsage                   │
+│  ├─ Update provider info                │
+│  └─ Trigger re-render                   │
+└────────┬────────────────────────────────┘
+         │
+         ▼
+┌─────────────────┐
+│  <ChatPanel>    │
+│  re-renders     │
+└─────────────────┘
+```
+
+---
+
+## Part 5: Implementation Phases
+
+### Phase 0: Repository Setup
+
+```bash
+# Step 1: Fork repositories
+gh repo fork anomalyco/opencode --clone=false
+gh repo fork anomalyco/opentui --clone=false
+
+# Step 2: Create lynkr-tui repository
+mkdir lynkr-tui && cd lynkr-tui
+git init
+
+# Step 3: Add OpenCode as upstream (sparse checkout)
+git remote add opencode-upstream https://github.com/anomalyco/opencode.git
+git fetch opencode-upstream
+git checkout -b main
+
+# Step 4: Initialize monorepo
+bun init
+```
+
+**Deliverable:** Empty monorepo with build tooling configured
+
+---
+
+### Phase 1: Core Infrastructure
+
+#### 1.1 Project Structure
+
+```
+lynkr-tui/
+├── packages/
+│   ├── client/                    # @lynkr/client
+│   │   ├── src/
+│   │   │   ├── index.ts           # Main exports
+│   │   │   ├── client.ts          # LynkrClient class
+│   │   │   ├── streaming.ts       # SSE handler
+│   │   │   ├── types.ts           # TypeScript types
+│   │   │   ├── endpoints/
+│   │   │   │   ├── messages.ts    # /v1/messages
+│   │   │   │   ├── health.ts      # /health/*
+│   │   │   │   ├── memory.ts      # /v1/memory/* (new)
+│   │   │   │   ├── agents.ts      # /v1/agents/*
+│   │   │   │   ├── models.ts      # /v1/models
+│   │   │   │   └── tokens.ts      # /api/tokens/*
+│   │   │   └── utils/
+│   │   │       ├── retry.ts
+│   │   │       └── errors.ts
+│   │   ├── package.json
+│   │   └── tsconfig.json
+│   │
+│   ├── tui/                       # @lynkr/tui
+│   │   ├── src/
+│   │   │   ├── index.tsx          # Entry point
+│   │   │   ├── app.tsx            # Root component
+│   │   │   ├── components/        # UI components
+│   │   │   ├── screens/           # Full-screen views
+│   │   │   ├── stores/            # State management
+│   │   │   ├── hooks/             # Custom hooks
+│   │   │   ├── themes/            # Color schemes
+│   │   │   └── utils/             # Helpers
+│   │   ├── package.json
+│   │   └── tsconfig.json
+│   │
+│   └── shared/                    # @lynkr/shared
+│       ├── src/
+│       │   ├── types.ts           # Shared types
+│       │   └── constants.ts       # Shared constants
+│       └── package.json
+│
+├── apps/
+│   └── cli/                       # CLI entry point
+│       ├── src/
+│       │   └── main.ts
+│       └── package.json
+│
+├── turbo.json                     # Turbo config
+├── package.json                   # Root package.json
+├── bun.lockb
+└── tsconfig.base.json
+```
+
+#### 1.2 Lynkr Client Package
+
+**Files to Create:**
+
+| File | Purpose | LOC Est. |
+|------|---------|----------|
+| `client/src/client.ts` | Main LynkrClient class | ~200 |
+| `client/src/streaming.ts` | SSE stream parser | ~100 |
+| `client/src/types.ts` | TypeScript interfaces | ~150 |
+| `client/src/endpoints/messages.ts` | /v1/messages wrapper | ~80 |
+| `client/src/endpoints/health.ts` | Health check wrappers | ~50 |
+| `client/src/endpoints/memory.ts` | Memory API wrappers | ~60 |
+| `client/src/endpoints/tokens.ts` | Token stats wrappers | ~40 |
+
+**Deliverable:** Working `@lynkr/client` package that can connect to Lynkr
+
+---
+
+### Phase 2: Basic TUI Shell
+
+#### 2.1 Fork OpenCode TUI Components
+
+**Components to copy from OpenCode:**
+
+| OpenCode Component | Lynkr Component | Modifications |
+|--------------------|-----------------|---------------|
+| `ChatView` | `<ChatPanel>` | Replace API calls |
+| `MessageList` | `<MessageList>` | Adapt message format |
+| `Message` | `<Message>` | Add Lynkr metadata |
+| `CodeBlock` | `<CodeBlock>` | Keep as-is |
+| `Input` | `<InputArea>` | Minor adaptations |
+| `Layout` | `<Layout>` | Add Lynkr panels |
+
+#### 2.2 Basic Chat Flow
+
+```
+Phase 2 Target:
+┌─────────────────────────────────────────┐
+│ Lynkr TUI v0.1.0                        │
+├─────────────────────────────────────────┤
+│                                         │
+│ [User] Hello                            │
+│                                         │
+│ [Assistant] Hello! How can I help?      │
+│                                         │
+│                                         │
+├─────────────────────────────────────────┤
+│ > _                                     │
+└─────────────────────────────────────────┘
+```
+
+**Deliverable:** Basic chat working with Lynkr streaming
+
+---
+
+### Phase 3: Lynkr-Specific Features
+
+#### 3.1 Token Dashboard
+
+```typescript
+// packages/tui/src/components/TokenDashboard.tsx
+
+import { Box, Text } from '@opentui/react';
+import { useLynkr } from '../hooks/useLynkr';
+
+export function TokenDashboard() {
+  const { tokenStats, isLoading } = useLynkr().useTokenStats();
+
+  return (
+    <Box flexDirection="column" borderStyle="single" padding={1}>
+      <Text bold>Token Usage</Text>
+      <TokenBar
+        label="Input"
+        value={tokenStats.inputTokens}
+        max={100000}
+      />
+      <TokenBar
+        label="Output"
+        value={tokenStats.outputTokens}
+        max={32000}
+      />
+      <TokenBar
+        label="Cache"
+        value={tokenStats.cacheHitRate}
+        max={100}
+        unit="%"
+      />
+      <Text color="green">
+        Cost: ${tokenStats.estimatedCost.toFixed(2)}
+      </Text>
+      <Text color="cyan" dimColor>
+        Savings: {tokenStats.savingsPercent}%
+      </Text>
+    </Box>
+  );
+}
+```
+
+#### 3.2 Provider Status Panel
+
+```typescript
+// packages/tui/src/components/ProviderStatusPanel.tsx
+
+export function ProviderStatusPanel() {
+  const { providers } = useLynkr().useProviderStatus();
+
+  return (
+    <Box flexDirection="column" borderStyle="single" padding={1}>
+      <Text bold>Providers</Text>
+      {providers.map(p => (
+        <Box key={p.name}>
+          <Text color={p.status === 'healthy' ? 'green' : 'red'}>
+            {p.status === 'healthy' ? '●' : '○'}
+          </Text>
+          <Text> {p.name.padEnd(12)}</Text>
+          <Text dimColor>{p.latency}ms</Text>
+          {p.circuitState && (
+            <Text color="yellow"> [{p.circuitState}]</Text>
+          )}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+```
+
+#### 3.3 Memory Inspector Modal
+
+```typescript
+// packages/tui/src/components/MemoryInspector.tsx
+
+export function MemoryInspector() {
+  const [query, setQuery] = useState('');
+  const { memories, search, deleteMemory } = useLynkr().useMemory();
+
+  return (
+    <Box flexDirection="column" width="80%" height="80%">
+      <Box borderStyle="single" padding={1}>
+        <Text bold>Memory Inspector</Text>
+      </Box>
+
+      <Box>
+        <TextInput
+          value={query}
+          onChange={setQuery}
+          placeholder="Search memories..."
+        />
+        <Button onClick={() => search(query)}>Search</Button>
+      </Box>
+
+      <Box flexDirection="column" flexGrow={1} overflow="scroll">
+        {memories.map(m => (
+          <MemoryItem
+            key={m.id}
+            memory={m}
+            onDelete={() => deleteMemory(m.id)}
+          />
+        ))}
+      </Box>
+    </Box>
+  );
+}
+```
+
+#### 3.4 Agent Mode Selector
+
+```typescript
+// packages/tui/src/components/AgentModeSelector.tsx
+
+type AgentMode = 'build' | 'plan' | 'analyze';
+
+const MODES: { mode: AgentMode; label: string; description: string }[] = [
+  { mode: 'build', label: 'BUILD', description: 'Full access' },
+  { mode: 'plan', label: 'PLAN', description: 'Read-only' },
+  { mode: 'analyze', label: 'ANALYZE', description: 'Deep inspection' },
+];
+
+export function AgentModeSelector() {
+  const { agentMode, setAgentMode } = useLynkr();
+
+  return (
+    <Box flexDirection="column" borderStyle="single" padding={1}>
+      <Text bold>Agent Mode</Text>
+      {MODES.map(({ mode, label, description }) => (
+        <Box key={mode}>
+          <Text color={agentMode === mode ? 'green' : 'gray'}>
+            {agentMode === mode ? '[●]' : '[ ]'}
+          </Text>
+          <Text bold={agentMode === mode}> {label}</Text>
+          <Text dimColor> {description}</Text>
+        </Box>
+      ))}
+      <Text dimColor>Press [Tab] to switch</Text>
+    </Box>
+  );
+}
+```
+
+**Deliverable:** All Lynkr-specific components working
+
+---
+
+### Phase 4: Backend Enhancements (Lynkr Side)
+
+#### 4.1 New Endpoints Required
+
+Add to `src/api/router.js`:
+
+```javascript
+// Memory API endpoints
+router.get('/v1/memory', async (req, res) => {
+  const { limit = 50, offset = 0 } = req.query;
+  const memories = await memoryStore.getRecentMemories(req.sessionId, limit, offset);
+  res.json({ memories, total: memories.length });
+});
+
+router.post('/v1/memory/search', async (req, res) => {
+  const { query, limit = 10 } = req.body;
+  const memories = await memoryStore.searchMemories(query, limit);
+  res.json({ memories });
+});
+
+router.delete('/v1/memory/:id', async (req, res) => {
+  await memoryStore.deleteMemory(parseInt(req.params.id));
+  res.json({ success: true });
+});
+
+// Provider status endpoint
+router.get('/v1/providers/status', async (req, res) => {
+  const statuses = await Promise.all([
+    checkDatabricks().catch(e => ({ name: 'databricks', status: 'error', error: e.message })),
+    checkOllama().catch(e => ({ name: 'ollama', status: 'error', error: e.message })),
+    checkOpenRouter().catch(e => ({ name: 'openrouter', status: 'error', error: e.message })),
+    // ... other providers
+  ]);
+  res.json({ providers: statuses });
+});
+
+// Configuration endpoint (safe values only)
+router.get('/v1/config', (req, res) => {
+  res.json({
+    provider: config.modelProvider,
+    memoryEnabled: config.memory.enabled,
+    smartToolSelection: config.tokenOptimization.smartToolSelection.mode,
+    agentsEnabled: config.agents.enabled,
+    // ... other safe config values
+  });
+});
+```
+
+#### 4.2 WebSocket Support (Optional Enhancement)
+
+Add to `src/api/websocket.js`:
+
+```javascript
+import { WebSocketServer } from 'ws';
+
+export function setupWebSocket(server) {
+  const wss = new WebSocketServer({ server, path: '/ws' });
+
+  wss.on('connection', (ws, req) => {
+    const sessionId = new URL(req.url, 'http://localhost').searchParams.get('session');
+
+    ws.on('message', async (data) => {
+      const message = JSON.parse(data);
+
+      switch (message.type) {
+        case 'chat':
+          // Stream response back over WebSocket
+          for await (const event of processMessageStream(message.payload, sessionId)) {
+            ws.send(JSON.stringify(event));
+          }
+          break;
+        case 'cancel':
+          // Cancel current operation
+          break;
+        case 'ping':
+          ws.send(JSON.stringify({ type: 'pong' }));
+          break;
+      }
+    });
+  });
+}
+```
+
+**Deliverable:** Lynkr backend ready to support TUI
+
+---
+
+### Phase 5: Polish & Distribution
+
+#### 5.1 Configuration File
+
+```yaml
+# ~/.config/lynkr-tui/config.yaml
+
+connection:
+  url: http://localhost:8081
+  timeout: 30000
+  retries: 3
+
+ui:
+  theme: dark           # dark | light | nord | dracula
+  layout: split         # split | chat-only | minimal
+  showTokens: true
+  showProviders: true
+  showMemory: true
+
+keybindings:
+  style: vim            # vim | emacs | default
+  custom:
+    toggleMemory: ctrl+m
+    toggleProviders: ctrl+p
+    switchMode: tab
+
+defaults:
+  agentMode: build
+  model: auto           # auto | specific model
+```
+
+#### 5.2 CLI Entry Point
+
+```typescript
+// apps/cli/src/main.ts
+
+#!/usr/bin/env bun
+
+import { program } from 'commander';
+import { render } from '@opentui/react';
+import { App } from '@lynkr/tui';
+import { loadConfig } from './config';
+
+program
+  .name('lynkr-tui')
+  .version('1.0.0')
+  .option('-u, --url <url>', 'Lynkr server URL', 'http://localhost:8081')
+  .option('-s, --session <id>', 'Session ID to resume')
+  .option('-t, --theme <theme>', 'Color theme', 'dark')
+  .option('-c, --config <path>', 'Config file path')
+  .action(async (options) => {
+    const config = await loadConfig(options);
+    render(<App config={config} />);
+  });
+
+program.parse();
+```
+
+#### 5.3 Distribution
+
+| Channel | Implementation |
+|---------|----------------|
+| **npm** | `npm publish` from `apps/cli` |
+| **Homebrew** | Create formula in `homebrew-lynkr-tui` tap |
+| **Binary** | `bun build --compile` for standalone |
+| **Docker** | Dockerfile for containerized usage |
+
+---
+
+## Part 6: File-by-File Implementation Checklist
+
+### 6.1 @lynkr/client Package
+
+| File | Status | Maps To |
+|------|--------|---------|
+| `src/client.ts` | ⬜ New | Main client class |
+| `src/streaming.ts` | ⬜ New | SSE parser for `/v1/messages` |
+| `src/types.ts` | ⬜ New | TypeScript interfaces |
+| `src/endpoints/messages.ts` | ⬜ New | Lynkr `router.js:105` |
+| `src/endpoints/health.ts` | ⬜ New | Lynkr `health.js` |
+| `src/endpoints/memory.ts` | ⬜ New | Lynkr `memory/store.js` |
+| `src/endpoints/agents.ts` | ⬜ New | Lynkr `router.js:405-444` |
+| `src/endpoints/tokens.ts` | ⬜ New | Lynkr `router.js:460-501` |
+| `src/endpoints/models.ts` | ⬜ New | Lynkr `openai-router.js:232` |
+
+### 6.2 @lynkr/tui Package
+
+| File | Status | Source |
+|------|--------|--------|
+| `src/app.tsx` | ⬜ Fork | OpenCode + adapt |
+| `src/components/ChatPanel.tsx` | ⬜ Fork | OpenCode ChatView |
+| `src/components/MessageList.tsx` | ⬜ Fork | OpenCode + adapt |
+| `src/components/Message.tsx` | ⬜ Fork | OpenCode + Lynkr metadata |
+| `src/components/CodeBlock.tsx` | ⬜ Fork | OpenCode (keep) |
+| `src/components/ToolUseBlock.tsx` | ⬜ Fork | OpenCode + adapt |
+| `src/components/InputArea.tsx` | ⬜ Fork | OpenCode + adapt |
+| `src/components/TokenDashboard.tsx` | ⬜ **New** | Lynkr-specific |
+| `src/components/ProviderStatusPanel.tsx` | ⬜ **New** | Lynkr-specific |
+| `src/components/MemoryInspector.tsx` | ⬜ **New** | Lynkr-specific |
+| `src/components/AgentModeSelector.tsx` | ⬜ **New** | Lynkr-specific |
+| `src/components/CostAnalytics.tsx` | ⬜ **New** | Lynkr-specific |
+| `src/stores/chat.ts` | ⬜ Fork | OpenCode + adapt |
+| `src/stores/lynkr.ts` | ⬜ **New** | Lynkr connection state |
+| `src/hooks/useLynkr.ts` | ⬜ **New** | Custom hooks |
+| `src/hooks/useStreaming.ts` | ⬜ **New** | SSE hook |
+
+### 6.3 Lynkr Backend Additions
+
+| File | Status | Purpose |
+|------|--------|---------|
+| `src/api/router.js` | ⬜ Modify | Add memory/config endpoints |
+| `src/api/websocket.js` | ⬜ **New** | WebSocket support |
+| `src/memory/api.js` | ⬜ **New** | Memory API handlers |
+
+---
+
+## Summary
+
+| Phase | Deliverable | Effort Est. |
+|-------|-------------|-------------|
+| **0** | Monorepo setup | 1 day |
+| **1** | @lynkr/client working | 3-4 days |
+| **2** | Basic chat TUI | 4-5 days |
+| **3** | Lynkr features (tokens, providers, memory, modes) | 5-7 days |
+| **4** | Backend enhancements | 2-3 days |
+| **5** | Polish & distribution | 2-3 days |
+
+**Total Estimated Effort:** ~3-4 weeks for full implementation
+
+---
+
+## Next Steps
+
+1. **Fork OpenCode** - `gh repo fork anomalyco/opencode`
+2. **Review OpenTUI docs** - Understand component primitives
+3. **Start with @lynkr/client** - Get streaming working first
+4. **Iterate on TUI** - Build incrementally with Lynkr features
+
+---
+
+## References
+
+- [OpenCode Repository](https://github.com/anomalyco/opencode)
+- [OpenTUI Repository](https://github.com/anomalyco/opentui)
+- [Ink - React for CLI](https://github.com/vadimdemedes/ink)
+- [Building Terminal Interfaces with Node.js](https://blog.openreplay.com/building-terminal-interfaces-nodejs/)
+
+---
+
+*Generated: January 2026*