kentutai 1.5.0 → 1.7.0

package/.dockerignore

@@ -0,0 +1,32 @@
+# VCS
+.git
+**/.git
+
+# Editor
+.vscode
+**/.vscode
+
+# Dependencies and build output
+node_modules
+.next
+out
+build
+dist
+coverage
+
+# Runtime data and logs
+data
+logs
+
+# Local env files (inject at runtime via --env-file or -e)
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Debug logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*

package/.env.example

@@ -0,0 +1,38 @@
+# KentutAI environment contract
+# This file reflects actual runtime usage in the current codebase.
+
+# Required
+JWT_SECRET=change-me-to-a-long-random-secret
+INITIAL_PASSWORD=change-me
+DATA_DIR=/var/lib/kentutai
+
+# Recommended runtime variables
+PORT=20123
+NODE_ENV=production
+
+# Recommended security and ops variables
+API_KEY_SECRET=endpoint-proxy-api-key-secret
+MACHINE_ID_SALT=endpoint-proxy-salt
+ENABLE_REQUEST_LOGS=false
+OBSERVABILITY_ENABLED=true
+AUTH_COOKIE_SECURE=false
+REQUIRE_API_KEY=false
+
+# Cloud sync variables
+# Must point to this running instance so internal sync jobs can call /api/sync/cloud.
+# Server-side preferred variables:
+BASE_URL=http://localhost:20123
+CLOUD_URL=https://kentutai.com
+# Backward-compatible/public variables:
+NEXT_PUBLIC_BASE_URL=http://localhost:20123
+NEXT_PUBLIC_CLOUD_URL=https://kentutai.com
+
+# Optional outbound proxy variables for upstream provider calls
+# Lowercase variants are also supported: http_proxy, https_proxy, all_proxy, no_proxy
+# HTTP_PROXY=http://127.0.0.1:7890
+# HTTPS_PROXY=http://127.0.0.1:7890
+# ALL_PROXY=socks5://127.0.0.1:7890
+# NO_PROXY=localhost,127.0.0.1
+
+# Currently unused by application runtime (kept as reference)
+# INSTANCE_NAME=kentutai

package/.github/dependabot.yml

@@ -0,0 +1,2 @@
+version: 2
+updates: []

package/.github/workflows/docker-publish.yml

@@ -0,0 +1,60 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+env:
+  GHCR_IMAGE: ghcr.io/${{ github.repository }}
+  DOCKERHUB_IMAGE: decolua/9router
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.GHCR_IMAGE }}
+            ${{ env.DOCKERHUB_IMAGE }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=registry,ref=${{ env.GHCR_IMAGE }}:buildcache
+          cache-to: type=registry,ref=${{ env.GHCR_IMAGE }}:buildcache,mode=max
+          platforms: linux/amd64,linux/arm64
+          provenance: false
+          sbom: false

package/.github/workflows/gitbook-pages.yml

@@ -0,0 +1,50 @@
+name: Deploy GitBook to 9router.github.io
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - "gitbook/**"
+      - ".github/workflows/gitbook-pages.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: gitbook-pages
+  cancel-in-progress: true
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: gitbook
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+
+      - name: Install deps
+        run: npm install --no-audit --no-fund
+
+      - name: Build static export
+        run: npm run build
+        env:
+          NODE_ENV: production
+          NEXT_PUBLIC_BASE_PATH: ""
+
+      - name: Add .nojekyll
+        run: touch out/.nojekyll
+
+      - name: Deploy to 9router.github.io
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          deploy_key: ${{ secrets.GH_PAGES_DEPLOY_KEY }}
+          external_repository: 9router/9router.github.io
+          publish_branch: main
+          publish_dir: gitbook/out
+          force_orphan: true
+          user_name: github-actions[bot]
+          user_email: github-actions[bot]@users.noreply.github.com
+          commit_message: "deploy: ${{ github.sha }}"

package/.omo/boulder.json

@@ -0,0 +1,15 @@
+{
+    "total_tasks":  9,
+    "session_ids":  [
+                        "opencode:ses_1822a56a4ffeNWTVDWlc5C2b2b"
+                    ],
+    "started_at":  "2026-05-31T12:58:52.851Z",
+    "plan_name":  "unified-access-management",
+    "active_plan":  "D:\\opencode\\Kentut-Router\\.omo\\plans\\unified-access-management.md",
+    "pending_tasks":  [
+
+                      ],
+    "status":  "completed",
+    "completed_tasks":  9,
+    "ended_at":  "2026-05-31T20:53:28.617Z"
+}

package/.omo/evidence/task-1-data-flow-investigation.txt

@@ -0,0 +1,254 @@
+================================================================================
+TASK 1: DATA FLOW INVESTIGATION — Usage Monitoring System
+Date: 2026-05-30
+================================================================================
+
+## EXECUTIVE SUMMARY
+
+The usage monitoring system has TWO separate tables serving different purposes:
+- `usageHistory` — legacy ops monitoring (provider-level, connection-based)
+- `usage_records` — new billing system (user-level, API-key-based)
+
+ROOT CAUSE: The write paths and read paths are split across these two tables,
+causing the dashboard to show empty data depending on which tab/view is used.
+
+================================================================================
+## TABLE 1: `usageHistory` (Legacy Ops Monitoring)
+================================================================================
+
+### Schema (src/lib/db/schema.js:180-201)
+  - id: INTEGER PRIMARY KEY AUTOINCREMENT
+  - timestamp, provider, model, connectionId, apiKey, endpoint
+  - promptTokens, completionTokens, cost, status
+  - tokens (JSON), meta (JSON)
+
+### Purpose
+  Provider-level request logging for ops monitoring. Tracks every proxied
+  LLM request with provider, model, connection, and token counts.
+
+### WRITE PATH
+  Written by: `saveRequestUsage()` in `src/lib/db/repos/usageRepo.js:243-287`
+
+  Callers:
+  1. `open-sse/utils/usageTracking.js:345` — `logUsage()` function
+     → Called from `open-sse/utils/stream.js:289,359` (SSE proxy handler)
+     → This is the MAIN write path for all proxied LLM requests
+
+  2. `open-sse/handlers/chatCore/requestDetail.js:93` — `saveUsageStats()` function
+     → Called from chat core request handler
+
+### READ PATH
+  Read by functions in `src/lib/db/repos/usageRepo.js`:
+  - `getUsageStats()` (line 319) — reads usageHistory + usageDaily
+  - `getChartData()` (line 620) — reads usageHistory + usageDaily
+  - `getRecentLogs()` (line 701) — reads usageHistory
+  - `getUsageHistory()` (line 289) — reads usageHistory
+
+  Also read by `src/lib/db/repos/rateLimitRepo.js`:
+  - `getMonthlyTokens()` (line 54) — reads usageHistory for rate limit checks
+  - `getMonthlyCost()` (line 68) — reads usageHistory for credit checks
+  - Rate limit RTPM/RTPD checks in `rateLimitMiddleware.js:78,97`
+
+================================================================================
+## TABLE 2: `usage_records` (New Billing System)
+================================================================================
+
+### Schema (migration 004 + schema.js:226-246)
+  - id: TEXT PRIMARY KEY (UUID)
+  - userId, apiKeyId, model
+  - inputTokens, outputTokens, totalTokens
+  - cost, creditUsed, status, errorMessage, endpoint, timestamp
+
+### Purpose
+  User-level billing records. Tracks usage per user/API-key for billing,
+  rate limiting, and per-user usage dashboards.
+
+### WRITE PATH
+  Written by: `logUsage()` in `src/lib/db/repos/usageRecordsRepo.js:23-48`
+
+  Callers:
+  1. `src/lib/auth/rateLimitMiddleware.js:58-68` — `logUsageAsync()` function
+     → Called from `enforceRateLimits()` (lines 215, 230)
+     → Triggered when API key users make requests through the LLM API gate
+     → Called from `src/dashboardGuard.js:239-240`
+
+### READ PATH
+  Read by functions in `src/lib/db/repos/usageRecordsRepo.js`:
+  - `getUsageByUser()` (line 50) — reads usage_records by userId
+  - `getUsageSummary()` (line 97) — aggregates usage_records by userId
+  - `getUsageByModel()` (line 137) — groups usage_records by model
+  - `getUsageDaily()` (line 173) — groups usage_records by date
+  - `getAllUsersUsage()` (line 211) — aggregates across all users
+
+================================================================================
+## THE DISCONNECT — Root Cause Analysis
+================================================================================
+
+### Problem 1: Dashboard Overview Tab reads from WRONG table for SSE proxy data
+
+  Dashboard "Overview" tab:
+  → `UsageStats` component fetches `/api/usage/stats` + `/api/usage/stream`
+  → These call `getUsageStats()` from `usageRepo.js`
+  → Reads from `usageHistory` table
+  → ✅ CORRECT — SSE proxy writes to `usageHistory` via `saveRequestUsage()`
+
+### Problem 2: Dashboard Table Tab reads from WRONG table for SSE proxy data
+
+  Dashboard "Table" tab:
+  → `UsageTableView` component fetches `/api/usage`
+  → This calls `getUsageByUser()` + `getUsageSummary()` from `usageRecordsRepo.js`
+  → Reads from `usage_records` table
+  → ❌ WRONG — SSE proxy NEVER writes to `usage_records`
+
+  The SSE proxy path writes ONLY to `usageHistory` via `saveRequestUsage()`.
+  The `usage_records` table is ONLY written by `rateLimitMiddleware.js`.
+  So the Table tab shows EMPTY for all SSE proxy requests.
+
+### Problem 3: Export reads from `usage_records` (same issue as Table tab)
+
+  Export:
+  → `/api/usage/export` calls `getUsageByUser()` + `getUsageSummary()` from `usageRecordsRepo.js`
+  → Reads from `usage_records` table
+  → ❌ WRONG — Same disconnect as Table tab
+
+### Problem 4: Rate limit checks read from `usageHistory` but middleware writes to `usage_records`
+
+  Rate limit middleware (`rateLimitMiddleware.js`):
+  → `enforceRateLimits()` writes to `usage_records` via `logUsageAsync()` (line 215)
+  → But `checkRTPM()` reads from `usageHistory` (line 78)
+  → And `checkRTPD()` reads from `usageHistory` (line 97)
+  → And `getMonthlyTokens()` reads from `usageHistory` (rateLimitRepo.js:59)
+  → And `getMonthlyCost()` reads from `usageHistory` (rateLimitRepo.js:73)
+
+  This means rate limiting is based on `usageHistory` data, but the middleware
+  logs to `usage_records`. The rate limiting works ONLY because the SSE proxy
+  also writes to `usageHistory`. If a request only goes through the rate limit
+  middleware (without SSE proxy), its usage is logged to `usage_records` but
+  NOT counted for rate limiting.
+
+### Problem 5: Table name mismatch between schema.js and migration
+
+  - `schema.js` defines table key as `usageRecords` (camelCase)
+  - Migration 004 creates table as `usage_records` (snake_case)
+  - `syncSchemaFromTables()` in migrate.js creates `usageRecords` (from schema key)
+  - `usageRecordsRepo.js` queries `usage_records` (from migration)
+  - This creates TWO tables: `usageRecords` (empty, unused) and `usage_records` (used)
+  - This is a secondary bug but doesn't directly cause the data display issue
+
+================================================================================
+## COMPLETE DATA FLOW DIAGRAM
+================================================================================
+
+  SSE Proxy Request Flow:
+  ┌─────────────────────┐
+  │  Client → SSE Proxy │
+  │  (open-sse/stream.js)│
+  └──────────┬──────────┘
+             │
+             ▼
+  ┌─────────────────────┐
+  │  logUsage()          │
+  │  usageTracking.js    │
+  └──────────┬──────────┘
+             │
+             ▼
+  ┌─────────────────────────┐
+  │  saveRequestUsage()      │
+  │  usageRepo.js:243        │
+  └──────────┬──────────────┘
+             │
+             ▼
+  ┌─────────────────────────┐
+  │  INSERT INTO usageHistory│  ← WRITE PATH
+  │  + usageDaily upsert     │
+  │  + _meta counter         │
+  └─────────────────────────┘
+
+  Rate Limit Middleware Flow:
+  ┌─────────────────────────┐
+  │  API Key Request         │
+  │  (dashboardGuard.js)     │
+  └──────────┬──────────────┘
+             │
+             ▼
+  ┌─────────────────────────┐
+  │  enforceRateLimits()     │
+  │  rateLimitMiddleware.js  │
+  └──────────┬──────────────┘
+             │
+             ▼
+  ┌─────────────────────────┐
+  │  logUsageAsync()         │
+  │  → logUsage() from       │
+  │    usageRecordsRepo.js   │
+  └──────────┬──────────────┘
+             │
+             ▼
+  ┌──────────────────────────┐
+  │  INSERT INTO usage_records│  ← WRITE PATH
+  └──────────────────────────┘
+
+  Dashboard Read Flows:
+  ┌──────────────────────────────────────────────────────────────┐
+  │  Overview Tab                                                  │
+  │  → /api/usage/stats → getUsageStats() → usageHistory ✅       │
+  │  → /api/usage/stream → getUsageStats() → usageHistory ✅      │
+  │  → /api/usage/chart → getChartData() → usageHistory ✅        │
+  ├──────────────────────────────────────────────────────────────┤
+  │  Table Tab                                                     │
+  │  → /api/usage → getUsageByUser() → usage_records ❌ EMPTY     │
+  │  → /api/usage → getUsageSummary() → usage_records ❌ EMPTY    │
+  ├──────────────────────────────────────────────────────────────┤
+  │  Export                                                        │
+  │  → /api/usage/export → getUsageByUser() → usage_records ❌    │
+  │  → /api/usage/export → getUsageSummary() → usage_records ❌   │
+  ├──────────────────────────────────────────────────────────────┤
+  │  Logs Tab                                                      │
+  │  → /api/usage/logs → getRecentLogs() → usageHistory ✅        │
+  ├──────────────────────────────────────────────────────────────┤
+  │  Request Details Tab                                           │
+  │  → /api/usage/request-details → getRequestDetails()            │
+  │    → requestDetails table (separate, not part of disconnect)   │
+  └──────────────────────────────────────────────────────────────┘
+
+================================================================================
+## AFFECTED FEATURES (All 5 reported broken)
+================================================================================
+
+1. DATA NOT SHOWING — Table tab reads from `usage_records` which is empty
+   for SSE proxy requests. Overview tab works (reads from `usageHistory`).
+
+2. CHARTS BROKEN — Charts in Table tab use `records` from `/api/usage`
+   which returns empty from `usage_records`. Overview charts work.
+
+3. CALCULATIONS BROKEN — Summary cards in Table tab use `summary` from
+   `getUsageSummary()` which reads from `usage_records` (empty).
+
+4. ADMIN ACCESS BROKEN — Admin queries (`getAllUsersUsage()`) read from
+   `usage_records` which has no SSE proxy data.
+
+5. EXPORT BROKEN — Export reads from `usage_records` via `getUsageByUser()`
+   and `getUsageSummary()` — both return empty for SSE proxy data.
+
+================================================================================
+## RECOMMENDED FIX APPROACH (for Task 2)
+================================================================================
+
+Option A (Quick fix): Make SSE proxy also write to `usage_records`
+  - Add `logUsage()` call in `usageTracking.js` alongside `saveRequestUsage()`
+  - Requires mapping SSE proxy fields to `usage_records` schema
+  - Requires userId resolution (SSE proxy doesn't have userId context)
+
+Option B (Better fix): Unify read paths to use `usageHistory`
+  - Change `/api/usage` route to read from `usageHistory` via `usageRepo.js`
+  - Change `/api/usage/export` to read from `usageHistory`
+  - Add userId filtering by joining with apiKeys table
+  - This matches the existing data in `usageHistory`
+
+Option C (Best fix): Dual-write from SSE proxy
+  - Keep both tables serving their purposes
+  - Add `logUsage()` call in SSE proxy path for `usage_records`
+  - Ensure both tables get populated for all request types
+  - Most resilient but most complex
+
+================================================================================