better-codex 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# better-codex
+
+Consumer-friendly launcher for the Codex Hub web UI.
+
+## Install
+
+```bash
+npm i -g better-codex
+```
+
+Requires Bun: https://bun.sh
+
+## Run
+
+```bash
+better-codex
+```
+
+`better-codex web` works too (same command).
+
+Options:
+- `--root PATH` set the repo root (defaults to current dir or parent lookup).
+- `--host 127.0.0.1` host for backend + UI.
+- `--backend-port 7711` backend port.
+- `--web-port 5173` UI port.
+- `--open` open the UI in your browser after startup.

package/apps/backend/README.md

@@ -0,0 +1,46 @@
+# codex-backend
+
+Local backend that supervises multiple `codex app-server` processes and exposes a
+WebSocket bridge for the web UI.
+
+## Setup
+
+1. Install dependencies
+   ```bash
+   bun install
+   ```
+2. Run the server
+   ```bash
+   bun run dev
+   ```
+
+## Protocol types
+
+Generate TypeScript bindings from the installed Codex CLI:
+
+```bash
+bun run generate:protocol
+```
+
+## Environment variables
+
+- `CODEX_HUB_HOST` (default: `127.0.0.1`)
+- `CODEX_HUB_PORT` (default: `7711`)
+- `CODEX_HUB_TOKEN` (default: auto-generated at boot)
+- `CODEX_HUB_DATA_DIR` (default: `~/.codex-hub`)
+- `CODEX_HUB_PROFILES_DIR` (default: `~/.codex/profiles`)
+- `CODEX_HUB_DEFAULT_CODEX_HOME` (default: `~/.codex`)
+- `CODEX_BIN` (default: `codex`)
+- `CODEX_FLAGS` (space-delimited)
+- `CODEX_FLAGS_JSON` (JSON array, preferred)
+- `CODEX_APP_SERVER_FLAGS`
+- `CODEX_APP_SERVER_FLAGS_JSON`
+
+## Endpoints
+
+- `GET /health`
+- `GET /profiles`
+- `POST /profiles`
+- `POST /profiles/:profileId/start`
+- `POST /profiles/:profileId/stop`
+- `WS /ws?token=...`

package/apps/backend/bun.lock

@@ -0,0 +1,64 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "codex-backend",
+      "dependencies": {
+        "@elysiajs/cors": "^1.4.1",
+        "elysia": "1",
+      },
+      "devDependencies": {
+        "@types/bun": "1",
+        "typescript": "5",
+      },
+    },
+  },
+  "packages": {
+    "@borewit/text-codec": ["@borewit/text-codec@0.2.1", "", {}, "sha512-k7vvKPbf7J2fZ5klGRD9AeKfUvojuZIQ3BT5u7Jfv+puwXkUBUT5PVyMDfJZpy30CBDXGMgw7fguK/lpOMBvgw=="],
+
+    "@elysiajs/cors": ["@elysiajs/cors@1.4.1", "", { "peerDependencies": { "elysia": ">= 1.4.0" } }, "sha512-lQfad+F3r4mNwsxRKbXyJB8Jg43oAOXjRwn7sKUL6bcOW3KjUqUimTS+woNpO97efpzjtDE0tEjGk9DTw8lqTQ=="],
+
+    "@sinclair/typebox": ["@sinclair/typebox@0.34.46", "", {}, "sha512-kiW7CtS/NkdvTUjkjUJo7d5JsFfbJ14YjdhDk9KoEgK6nFjKNXZPrX0jfLA8ZlET4cFLHxOZ/0vFKOP+bOxIOQ=="],
+
+    "@tokenizer/inflate": ["@tokenizer/inflate@0.4.1", "", { "dependencies": { "debug": "^4.4.3", "token-types": "^6.1.1" } }, "sha512-2mAv+8pkG6GIZiF1kNg1jAjh27IDxEPKwdGul3snfztFerfPGI1LjDezZp3i7BElXompqEtPmoPx6c2wgtWsOA=="],
+
+    "@tokenizer/token": ["@tokenizer/token@0.3.0", "", {}, "sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A=="],
+
+    "@types/bun": ["@types/bun@1.3.5", "", { "dependencies": { "bun-types": "1.3.5" } }, "sha512-RnygCqNrd3srIPEWBd5LFeUYG7plCoH2Yw9WaZGyNmdTEei+gWaHqydbaIRkIkcbXwhBT94q78QljxN0Sk838w=="],
+
+    "@types/node": ["@types/node@25.0.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA=="],
+
+    "bun-types": ["bun-types@1.3.5", "", { "dependencies": { "@types/node": "*" } }, "sha512-inmAYe2PFLs0SUbFOWSVD24sg1jFlMPxOjOSSCYqUgn4Hsc3rDc7dFvfVYjFPNHtov6kgUeulV4SxbuIV/stPw=="],
+
+    "cookie": ["cookie@1.1.1", "", {}, "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ=="],
+
+    "debug": ["debug@4.4.3", "", { "dependencies": { "ms": "^2.1.3" } }, "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA=="],
+
+    "elysia": ["elysia@1.4.19", "", { "dependencies": { "cookie": "^1.1.1", "exact-mirror": "0.2.5", "fast-decode-uri-component": "^1.0.1", "memoirist": "^0.4.0" }, "peerDependencies": { "@sinclair/typebox": ">= 0.34.0 < 1", "@types/bun": ">= 1.2.0", "file-type": ">= 20.0.0", "openapi-types": ">= 12.0.0", "typescript": ">= 5.0.0" }, "optionalPeers": ["@types/bun", "typescript"] }, "sha512-DZb9y8FnWyX5IuqY44SvqAV0DjJ15NeCWHrLdgXrKgTPDPsl3VNwWHqrEr9bmnOCpg1vh6QUvAX/tcxNj88jLA=="],
+
+    "exact-mirror": ["exact-mirror@0.2.5", "", { "peerDependencies": { "@sinclair/typebox": "^0.34.15" }, "optionalPeers": ["@sinclair/typebox"] }, "sha512-u8Wu2lO8nio5lKSJubOydsdNtQmH8ENba5m0nbQYmTvsjksXKYIS1nSShdDlO8Uem+kbo+N6eD5I03cpZ+QsRQ=="],
+
+    "fast-decode-uri-component": ["fast-decode-uri-component@1.0.1", "", {}, "sha512-WKgKWg5eUxvRZGwW8FvfbaH7AXSh2cL+3j5fMGzUMCxWBJ3dV3a7Wz8y2f/uQ0e3B6WmodD3oS54jTQ9HVTIIg=="],
+
+    "file-type": ["file-type@21.2.0", "", { "dependencies": { "@tokenizer/inflate": "^0.4.1", "strtok3": "^10.3.4", "token-types": "^6.1.1", "uint8array-extras": "^1.4.0" } }, "sha512-vCYBgFOrJQLoTzDyAXAL/RFfKnXXpUYt4+tipVy26nJJhT7ftgGETf2tAQF59EEL61i3MrorV/PG6tf7LJK7eg=="],
+
+    "ieee754": ["ieee754@1.2.1", "", {}, "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA=="],
+
+    "memoirist": ["memoirist@0.4.0", "", {}, "sha512-zxTgA0mSYELa66DimuNQDvyLq36AwDlTuVRbnQtB+VuTcKWm5Qc4z3WkSpgsFWHNhexqkIooqpv4hdcqrX5Nmg=="],
+
+    "ms": ["ms@2.1.3", "", {}, "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA=="],
+
+    "openapi-types": ["openapi-types@12.1.3", "", {}, "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw=="],
+
+    "strtok3": ["strtok3@10.3.4", "", { "dependencies": { "@tokenizer/token": "^0.3.0" } }, "sha512-KIy5nylvC5le1OdaaoCJ07L+8iQzJHGH6pWDuzS+d07Cu7n1MZ2x26P8ZKIWfbK02+XIL8Mp4RkWeqdUCrDMfg=="],
+
+    "token-types": ["token-types@6.1.2", "", { "dependencies": { "@borewit/text-codec": "^0.2.1", "@tokenizer/token": "^0.3.0", "ieee754": "^1.2.1" } }, "sha512-dRXchy+C0IgK8WPC6xvCHFRIWYUbqqdEIKPaKo/AcTUNzwLTK6AH7RjdLWsEZcAN/TBdtfUw3PYEgPr5VPr6ww=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "uint8array-extras": ["uint8array-extras@1.5.0", "", {}, "sha512-rvKSBiC5zqCCiDZ9kAOszZcDvdAHwwIKJG33Ykj43OKcWsnmcBRL09YTU4nOeHZ8Y2a7l1MgTd08SBe9A8Qj6A=="],
+
+    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
+  }
+}

package/apps/backend/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "codex-backend",
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/server.ts",
+    "generate:protocol": "bun scripts/generate-protocol.ts",
+    "start": "bun src/server.ts",
+    "typecheck": "tsc"
+  },
+  "devDependencies": {
+    "@types/bun": "1",
+    "typescript": "5"
+  },
+  "dependencies": {
+    "@elysiajs/cors": "^1.4.1",
+    "elysia": "1"
+  }
+}

package/apps/backend/scripts/generate-protocol.ts

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process'
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { loadConfig } from '../src/config'
+
+const config = loadConfig()
+const outDir = join(process.cwd(), 'src', 'protocol')
+
+await mkdir(outDir, { recursive: true })
+
+const args = [
+  ...config.codexArgs,
+  'app-server',
+  'generate-ts',
+  '--out',
+  outDir,
+]
+
+const child = spawn(config.codexBin, args, {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+  },
+})
+
+const exitCode = await new Promise<number>((resolve) => {
+  child.on('exit', (code) => resolve(code ?? 1))
+})
+
+if (exitCode !== 0) {
+  process.exit(exitCode)
+}

package/apps/backend/src/analytics/service.ts

@@ -0,0 +1,219 @@
+import { AnalyticsStore, type AnalyticsEvent, deriveDateKey } from './store'
+
+type RpcEvent = {
+  profileId: string
+  method: string
+  params?: unknown
+}
+
+type RpcRequest = {
+  profileId: string
+  method: string
+  params?: unknown
+}
+
+type RpcResponse = {
+  profileId: string
+  method?: string
+  result?: unknown
+  error?: string
+}
+
+type ServerRequest = {
+  profileId: string
+  id: number
+  method: string
+  params?: unknown
+}
+
+type ApprovalDecision = {
+  decision?: string
+  acceptSettings?: { forSession?: boolean }
+}
+
+const now = () => Date.now()
+
+export class AnalyticsService {
+  private readonly store: AnalyticsStore
+  private readonly pendingApprovals = new Map<number, { type: string }>()
+
+  constructor(store: AnalyticsStore) {
+    this.store = store
+  }
+
+  init(): void {
+    this.store.init()
+  }
+
+  getDailySeries(metric: string, profileId?: string, model?: string, days = 365) {
+    return this.store.getDailySeries(metric, profileId, model, days)
+  }
+
+  trackRpcEvent(event: RpcEvent): void {
+    const timestamp = now()
+    const base: AnalyticsEvent = {
+      occurredAt: timestamp,
+      dateKey: deriveDateKey(timestamp),
+      profileId: event.profileId,
+      eventType: `rpc.event:${event.method}`,
+      payload: event.params,
+    }
+    this.store.recordEvent(base)
+
+    if (event.method === 'thread/started' && event.params && typeof event.params === 'object') {
+      const { thread } = event.params as { thread?: { id?: string; modelProvider?: string; cwd?: string; createdAt?: number } }
+      if (thread?.id) {
+        this.store.upsertThreadMeta(thread.id, event.profileId, thread.modelProvider, thread.cwd, thread.createdAt ? thread.createdAt * 1000 : undefined)
+        this.store.incrementDaily('threads_started', event.profileId, thread.modelProvider, timestamp)
+      }
+    }
+
+    if (event.method === 'turn/started' && event.params && typeof event.params === 'object') {
+      const { threadId, turn } = event.params as { threadId?: string; turn?: { id?: string } }
+      if (threadId && turn?.id) {
+        this.store.upsertTurnMeta(turn.id, threadId, event.profileId, undefined, timestamp)
+        this.store.incrementDaily('turns_started', event.profileId, undefined, timestamp)
+      }
+    }
+
+    if (event.method === 'turn/completed' && event.params && typeof event.params === 'object') {
+      const { threadId, turn } = event.params as { threadId?: string; turn?: { id?: string; status?: string } }
+      if (threadId && turn?.id) {
+        this.store.upsertTurnMeta(turn.id, threadId, event.profileId, undefined, undefined, timestamp, turn.status)
+        this.store.incrementDaily('turns_completed', event.profileId, undefined, timestamp)
+        if (turn.status) {
+          this.store.incrementDaily(`turns_${turn.status}`, event.profileId, undefined, timestamp)
+        }
+      }
+    }
+
+    if (event.method === 'item/started' && event.params && typeof event.params === 'object') {
+      const { item } = event.params as { item?: { type?: string; id?: string } }
+      const itemType = item?.type
+      if (itemType) {
+        this.store.incrementDaily(`items_${itemType}`, event.profileId, undefined, timestamp)
+      }
+    }
+
+    if (event.method === 'item/completed' && event.params && typeof event.params === 'object') {
+      const { item } = event.params as { item?: { type?: string; id?: string } }
+      const itemType = item?.type
+      if (itemType) {
+        this.store.incrementDaily(`items_completed_${itemType}`, event.profileId, undefined, timestamp)
+      }
+    }
+
+    if (event.method === 'thread/tokenUsage/updated' && event.params && typeof event.params === 'object') {
+      const { threadId } = event.params as { threadId?: string }
+      if (threadId) {
+        this.store.recordTokenUsage(event.profileId, threadId, event.params, timestamp)
+      }
+    }
+  }
+
+  trackRpcRequest(request: RpcRequest): void {
+    const timestamp = now()
+    const base: AnalyticsEvent = {
+      occurredAt: timestamp,
+      dateKey: deriveDateKey(timestamp),
+      profileId: request.profileId,
+      eventType: `rpc.request:${request.method}`,
+      payload: request.params,
+    }
+    this.store.recordEvent(base)
+
+    if (request.method === 'turn/start') {
+      const params = (request.params ?? {}) as { model?: string; threadId?: string }
+      if (params.threadId && params.model) {
+        this.store.upsertThreadMeta(params.threadId, request.profileId, params.model)
+      }
+    }
+
+    if (request.method === 'command/exec') {
+      this.store.incrementDaily('command_exec', request.profileId, undefined, timestamp)
+    }
+
+    if (request.method === 'review/start') {
+      this.store.incrementDaily('reviews_started', request.profileId, undefined, timestamp)
+    }
+
+    if (request.method === 'account/login/start') {
+      const params = (request.params ?? {}) as { type?: string }
+      if (params.type) {
+        this.store.incrementDaily(`login_started_${params.type}`, request.profileId, undefined, timestamp)
+      }
+    }
+  }
+
+  trackRpcResponse(response: RpcResponse): void {
+    const timestamp = now()
+    const base: AnalyticsEvent = {
+      occurredAt: timestamp,
+      dateKey: deriveDateKey(timestamp),
+      profileId: response.profileId,
+      eventType: `rpc.response:${response.method ?? 'unknown'}`,
+      status: response.error ? 'error' : 'ok',
+      payload: response.error ?? response.result,
+    }
+    this.store.recordEvent(base)
+
+    if (response.method === 'thread/start' && response.result && typeof response.result === 'object') {
+      const { thread } = response.result as { thread?: { id?: string; modelProvider?: string; cwd?: string; createdAt?: number } }
+      if (thread?.id) {
+        this.store.upsertThreadMeta(thread.id, response.profileId, thread.modelProvider, thread.cwd, thread.createdAt ? thread.createdAt * 1000 : undefined)
+      }
+    }
+
+    if (response.method === 'thread/resume' && response.result && typeof response.result === 'object') {
+      const result = response.result as { thread?: { id?: string; modelProvider?: string; cwd?: string } }
+      if (result.thread?.id) {
+        this.store.upsertThreadMeta(result.thread.id, response.profileId, result.thread.modelProvider, result.thread.cwd)
+      }
+    }
+  }
+
+  trackServerRequest(request: ServerRequest): void {
+    const timestamp = now()
+    const base: AnalyticsEvent = {
+      occurredAt: timestamp,
+      dateKey: deriveDateKey(timestamp),
+      profileId: request.profileId,
+      eventType: `rpc.serverRequest:${request.method}`,
+      payload: request.params,
+    }
+    this.store.recordEvent(base)
+
+    if (request.method === 'item/commandExecution/requestApproval') {
+      this.pendingApprovals.set(request.id, { type: 'command' })
+      this.store.recordApprovalRequest(request.id, request.profileId, 'command', (request.params as { threadId?: string; itemId?: string })?.threadId, (request.params as { itemId?: string })?.itemId)
+      this.store.incrementDaily('approvals_requested_command', request.profileId, undefined, timestamp)
+    }
+
+    if (request.method === 'item/fileChange/requestApproval') {
+      this.pendingApprovals.set(request.id, { type: 'file' })
+      this.store.recordApprovalRequest(request.id, request.profileId, 'file', (request.params as { threadId?: string; itemId?: string })?.threadId, (request.params as { itemId?: string })?.itemId)
+      this.store.incrementDaily('approvals_requested_file', request.profileId, undefined, timestamp)
+    }
+  }
+
+  trackApprovalDecision(profileId: string, requestId: number, result?: unknown, error?: { message: string } | null): void {
+    const timestamp = now()
+    const decisionPayload = result as ApprovalDecision | undefined
+    const decision = error ? 'error' : decisionPayload?.decision ?? 'unknown'
+
+    this.store.recordEvent({
+      occurredAt: timestamp,
+      dateKey: deriveDateKey(timestamp),
+      profileId,
+      eventType: 'approval.decision',
+      status: decision,
+      payload: result ?? error,
+    })
+
+    if (this.pendingApprovals.has(requestId)) {
+      this.pendingApprovals.delete(requestId)
+      this.store.recordApprovalDecision(requestId, decision)
+      this.store.incrementDaily(`approvals_${decision}`, profileId, undefined, timestamp)
+    }
+  }
+}

package/apps/backend/src/analytics/store.ts

@@ -0,0 +1,284 @@
+import { Database } from 'bun:sqlite'
+
+export type AnalyticsEvent = {
+  occurredAt: number
+  dateKey: string
+  profileId: string
+  eventType: string
+  threadId?: string
+  turnId?: string
+  itemId?: string
+  model?: string
+  status?: string
+  payload?: unknown
+}
+
+const toDateKey = (timestampMs: number): string => {
+  const date = new Date(timestampMs)
+  const year = date.getUTCFullYear()
+  const month = String(date.getUTCMonth() + 1).padStart(2, '0')
+  const day = String(date.getUTCDate()).padStart(2, '0')
+  return `${year}-${month}-${day}`
+}
+
+export class AnalyticsStore {
+  private readonly db: Database
+
+  constructor(private readonly dbPath: string) {
+    this.db = new Database(dbPath)
+  }
+
+  init(): void {
+    this.db.exec(`
+      pragma journal_mode = wal;
+      create table if not exists analytics_events (
+        id integer primary key autoincrement,
+        occurred_at integer not null,
+        date_key text not null,
+        profile_id text not null,
+        thread_id text,
+        turn_id text,
+        item_id text,
+        model text,
+        event_type text not null,
+        status text,
+        payload text
+      );
+      create index if not exists analytics_events_date on analytics_events(date_key);
+      create index if not exists analytics_events_profile on analytics_events(profile_id);
+      create index if not exists analytics_events_thread on analytics_events(thread_id);
+      create index if not exists analytics_events_type on analytics_events(event_type);
+
+      create table if not exists analytics_daily (
+        date_key text not null,
+        metric text not null,
+        profile_id text not null,
+        model text,
+        count integer not null default 0,
+        primary key (date_key, metric, profile_id, model)
+      );
+
+      create table if not exists analytics_thread_meta (
+        thread_id text primary key,
+        profile_id text not null,
+        model text,
+        cwd text,
+        created_at integer
+      );
+
+      create table if not exists analytics_turn_meta (
+        turn_id text primary key,
+        thread_id text not null,
+        profile_id text not null,
+        model text,
+        started_at integer,
+        completed_at integer,
+        status text
+      );
+
+      create table if not exists analytics_token_usage (
+        id integer primary key autoincrement,
+        occurred_at integer not null,
+        date_key text not null,
+        profile_id text not null,
+        thread_id text not null,
+        payload text
+      );
+
+      create table if not exists analytics_approvals (
+        request_id integer primary key,
+        profile_id text not null,
+        thread_id text,
+        item_id text,
+        approval_type text not null,
+        requested_at integer not null,
+        decision text,
+        decided_at integer
+      );
+    `)
+  }
+
+  recordEvent(event: AnalyticsEvent): void {
+    const payload = event.payload ? safeStringify(event.payload) : null
+    this.db
+      .prepare(
+        `insert into analytics_events
+          (occurred_at, date_key, profile_id, thread_id, turn_id, item_id, model, event_type, status, payload)
+        values
+          ($occurred_at, $date_key, $profile_id, $thread_id, $turn_id, $item_id, $model, $event_type, $status, $payload)
+        `
+      )
+      .run({
+        $occurred_at: event.occurredAt,
+        $date_key: event.dateKey,
+        $profile_id: event.profileId,
+        $thread_id: event.threadId ?? null,
+        $turn_id: event.turnId ?? null,
+        $item_id: event.itemId ?? null,
+        $model: event.model ?? null,
+        $event_type: event.eventType,
+        $status: event.status ?? null,
+        $payload: payload,
+      })
+  }
+
+  incrementDaily(metric: string, profileId: string, model?: string, occurredAt = Date.now()): void {
+    const dateKey = toDateKey(occurredAt)
+    this.db
+      .prepare(
+        `insert into analytics_daily (date_key, metric, profile_id, model, count)
+         values ($date_key, $metric, $profile_id, $model, 0)
+         on conflict(date_key, metric, profile_id, model) do nothing
+        `
+      )
+      .run({
+        $date_key: dateKey,
+        $metric: metric,
+        $profile_id: profileId,
+        $model: model ?? null,
+      })
+
+    this.db
+      .prepare(
+        `update analytics_daily
+         set count = count + 1
+         where date_key = $date_key and metric = $metric and profile_id = $profile_id and model is $model
+        `
+      )
+      .run({
+        $date_key: dateKey,
+        $metric: metric,
+        $profile_id: profileId,
+        $model: model ?? null,
+      })
+  }
+
+  upsertThreadMeta(threadId: string, profileId: string, model?: string, cwd?: string, createdAt?: number): void {
+    this.db
+      .prepare(
+        `insert into analytics_thread_meta (thread_id, profile_id, model, cwd, created_at)
+         values ($thread_id, $profile_id, $model, $cwd, $created_at)
+         on conflict(thread_id) do update set
+           profile_id = excluded.profile_id,
+           model = coalesce(excluded.model, analytics_thread_meta.model),
+           cwd = coalesce(excluded.cwd, analytics_thread_meta.cwd),
+           created_at = coalesce(excluded.created_at, analytics_thread_meta.created_at)
+        `
+      )
+      .run({
+        $thread_id: threadId,
+        $profile_id: profileId,
+        $model: model ?? null,
+        $cwd: cwd ?? null,
+        $created_at: createdAt ?? null,
+      })
+  }
+
+  upsertTurnMeta(turnId: string, threadId: string, profileId: string, model?: string, startedAt?: number, completedAt?: number, status?: string): void {
+    this.db
+      .prepare(
+        `insert into analytics_turn_meta (turn_id, thread_id, profile_id, model, started_at, completed_at, status)
+         values ($turn_id, $thread_id, $profile_id, $model, $started_at, $completed_at, $status)
+         on conflict(turn_id) do update set
+           model = coalesce(excluded.model, analytics_turn_meta.model),
+           started_at = coalesce(excluded.started_at, analytics_turn_meta.started_at),
+           completed_at = coalesce(excluded.completed_at, analytics_turn_meta.completed_at),
+           status = coalesce(excluded.status, analytics_turn_meta.status)
+        `
+      )
+      .run({
+        $turn_id: turnId,
+        $thread_id: threadId,
+        $profile_id: profileId,
+        $model: model ?? null,
+        $started_at: startedAt ?? null,
+        $completed_at: completedAt ?? null,
+        $status: status ?? null,
+      })
+  }
+
+  recordTokenUsage(profileId: string, threadId: string, payload: unknown, occurredAt = Date.now()): void {
+    this.db
+      .prepare(
+        `insert into analytics_token_usage (occurred_at, date_key, profile_id, thread_id, payload)
+         values ($occurred_at, $date_key, $profile_id, $thread_id, $payload)
+        `
+      )
+      .run({
+        $occurred_at: occurredAt,
+        $date_key: toDateKey(occurredAt),
+        $profile_id: profileId,
+        $thread_id: threadId,
+        $payload: safeStringify(payload),
+      })
+  }
+
+  recordApprovalRequest(requestId: number, profileId: string, approvalType: string, threadId?: string, itemId?: string): void {
+    this.db
+      .prepare(
+        `insert into analytics_approvals (request_id, profile_id, thread_id, item_id, approval_type, requested_at)
+         values ($request_id, $profile_id, $thread_id, $item_id, $approval_type, $requested_at)
+         on conflict(request_id) do nothing
+        `
+      )
+      .run({
+        $request_id: requestId,
+        $profile_id: profileId,
+        $thread_id: threadId ?? null,
+        $item_id: itemId ?? null,
+        $approval_type: approvalType,
+        $requested_at: Date.now(),
+      })
+  }
+
+  recordApprovalDecision(requestId: number, decision: string): void {
+    this.db
+      .prepare(
+        `update analytics_approvals
+         set decision = $decision, decided_at = $decided_at
+         where request_id = $request_id
+        `
+      )
+      .run({
+        $decision: decision,
+        $decided_at: Date.now(),
+        $request_id: requestId,
+      })
+  }
+
+  getDailySeries(metric: string, profileId?: string, model?: string, days = 365): Array<{ date: string; count: number }> {
+    const cutoff = new Date()
+    cutoff.setUTCDate(cutoff.getUTCDate() - days + 1)
+    const cutoffKey = toDateKey(cutoff.getTime())
+
+    const rows = this.db
+      .prepare(
+        `select date_key as date, count
+         from analytics_daily
+         where metric = $metric
+           and date_key >= $cutoff
+           and ($profile_id is null or profile_id = $profile_id)
+           and ($model is null or model = $model)
+         order by date_key asc
+        `
+      )
+      .all({
+        $metric: metric,
+        $cutoff: cutoffKey,
+        $profile_id: profileId ?? null,
+        $model: model ?? null,
+      }) as Array<{ date: string; count: number }>
+
+    return rows
+  }
+}
+
+const safeStringify = (value: unknown): string => {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}
+
+export const deriveDateKey = toDateKey