opencode-usage-limit 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-usage-limit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# opencode-usage-limit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+OpenCode 플러그인 — **오늘 남은 사용량 한도**를 사이드바 최하단 게이지로 표시하고, 429 rate limit을 실측 추적합니다.
+
+```
+⚡ 오늘 남음 1.16M (38%) · 10h 11m 리셋
+[████░░░░░░] 사용 1.8M · 86 req
+⛔ 429 쿨다운 38m            (429 발생 시에만)
+```
+
+- 바의 채워진 부분 = **남은 비율** (사용할수록 줄어드는 연료게이지)
+- 50% 이하 노랑, 20% 이하 빨강 + 자동 toast 경고
+- 매일 자정(타임존 설정 가능) 리셋
+- 429 감지 시 provider별 쿨다운 표시 (NVIDIA NIM 40분 리필, opencode Zen 무료 모델 3분, 기타 5분)
+- `/usage` 슬래시 커맨드: 오늘 상세 / 모델별 Top 5 / 429 통계 대시보드
+
+## 설치
+
+### 방법 1 — opencode 자동 설치 (백그라운드 수집기)
+
+`~/.config/opencode/opencode.jsonc`의 `plugin` 배열에 패키지 이름 추가:
+
+```jsonc
+{
+  "plugin": ["opencode-usage-limit"]
+}
+```
+
+opencode 시작 시 npm에서 자동 설치되어 429 수집기가 로드됩니다.
+
+### 방법 2 — TUI 게이지 설치
+
+터미널에서 한 번 실행:
+
+```bash
+npx opencode-usage-limit
+```
+
+설치 CLI가 TUI 플러그인을 `~/.config/opencode/tui-plugins/`에 복사하고 `tui.json`에 등록합니다.
+
+**두 단계 모두 필요합니다** (백그라운드 수집기 + TUI 게이지). 설치 후 opencode를 재시작하세요.
+
+### 제거
+
+```bash
+npx opencode-usage-limit --remove
+```
+
+설치 스크립트는 재실행해도 안전합니다 (idempotent).
+
+## 설정 (`~/.config/opencode/usage-tracker.json`)
+
+| 키 | 기본값 | 설명 |
+|---|---|---|
+| `dailyLimit` | `3000000` | 일일 순토큰 한도. `0`이면 남은 한도 대신 사용량만 표시 |
+| `plan` | `"free"` | `"go"` / `"go-plus"` 지정 시 OpenCode Go 달러 한도 게이지로 전환 (5시간 = 월 한도 20%, 월간 = 100%, 공식 단가표 내장) |
+| `cacheWeights` | `{"read": 0.1, "write": 0.25}` | 순토큰 = `input + output + cacheRead×0.1 + cacheWrite×0.25` |
+| `resetTimezone` | `"Asia/Seoul"` | 일일 리셋 자정 기준 시간대 |
+| `pollSeconds` | `30` | 집계 갱신 주기 |
+| `rateLimitPatterns` | (기본 제공) | 429 감지용 에러 문자열 패턴 |
+
+설치 시 기존 설정 파일이 있으면 덮어쓰지 않습니다.
+
+## 동작 방식
+
+- opencode의 로컬 DB(`opencode.db`, `part` 테이블의 step-finish 파트)를 **읽기 전용**으로 집계 — 별도 기록 없이 설치 즉시 오늘 사용량이 표시됩니다
+- `message.part.updated` 이벤트 + 주기적 폴링으로 실시간 갱신
+- 백그라운드 수집기(`index.js`)가 429 에러를 감지해 `~/.config/opencode/usage-tracker/rate-limits.json`에 기록하면 TUI가 표시합니다
+
+## 구성 요소
+
+| 파일 | 설치 위치 | 역할 |
+|---|---|---|
+| `index.js` | npm 플러그인 (opencode가 자동 설치) | 백그라운드 429 수집기 |
+| `tui/usage-tracker.js` | `~/.config/opencode/tui-plugins/usage-tracker.js` | TUI 게이지 + `/usage` 대시보드 |
+| `config-default.json` | `~/.config/opencode/usage-tracker.json` | 기본 설정 (설치 시 기존 파일이 없을 때만 생성) |
+
+## 유의사항
+
+- opencode.db는 기기별 로컬입니다. 여러 기기가 같은 계정을 써도 각 기기 사용량만 집계되며, 각 기기에 설치하면 각자 표시됩니다. 서버 측 전체 사용량은 [opencode.ai/console](https://opencode.ai/console)에서 확인하세요.
+- 다른 플러그인이 `sidebar_footer` 슬롯(단일 승자)을 사용 중이면 게이지가 대신 표시될 수 있습니다. 기존 footer 플러그인은 `sidebar_content`(append 방식) 슬롯으로 옮기면 공존합니다.
+
+## 요구 사항
+
+- [opencode](https://opencode.ai)
+- node 18 이상 (설치 CLI용)
+
+## License
+
+MIT

package/bin/opencode-usage-limit.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// opencode-usage-limit 설치 CLI
+// 사용:
+//   node install.mjs          (설치 — 소스 디렉토리에서 직접 실행)
+//   npx opencode-usage-limit  (npm 설치 후)
+//   node install.mjs --remove (제거)
+//
+// 설치 내용:
+//   1. 백그라운드 수집기(index.js) → ~/.config/opencode/plugins/usage-tracker-collector.js 복사 + opencode.jsonc 등록
+//   2. TUI 플러그인(tui/usage-tracker.js) → ~/.config/opencode/tui-plugins/usage-tracker.js 복사 + tui.json 등록
+//   3. 기본 설정(config-default.json) → ~/.config/opencode/usage-tracker.json (기존 파일이 있으면 유지)
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, rmSync } from "node:fs"
+import path from "node:path"
+import { homedir } from "node:os"
+
+const remove = process.argv.includes("--remove")
+const SRC = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..")
+const CONFIG_DIR = process.env.OPENCODE_CONFIG_DIR || path.join(homedir(), ".config/opencode")
+
+const COLLECTOR_SRC = path.join(SRC, "index.js")
+const TUI_SRC = path.join(SRC, "tui", "usage-tracker.js")
+const CONFIG_SRC = path.join(SRC, "config-default.json")
+
+const COLLECTOR_DST = path.join(CONFIG_DIR, "plugins/usage-tracker-collector.js")
+const TUI_DST = path.join(CONFIG_DIR, "tui-plugins/usage-tracker.js")
+const CONFIG_DST = path.join(CONFIG_DIR, "usage-tracker.json")
+
+const COLLECTOR_REF = "./plugins/usage-tracker-collector.js"
+const TUI_REF = "./tui-plugins/usage-tracker.js"
+const STATE_DIR = path.join(CONFIG_DIR, "usage-tracker")
+
+function parseJsonc(text) {
+  const attempts = [
+    () => JSON.parse(text),
+    () => JSON.parse(text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:"'\\])\/\/.*$/gm, "$1")),
+  ]
+  for (const attempt of attempts) {
+    try {
+      return attempt()
+    } catch {}
+  }
+  return null
+}
+
+function updateConfig(fileName, ref) {
+  const filePath = path.join(CONFIG_DIR, fileName)
+  if (remove) {
+    if (!existsSync(filePath)) return true
+    const parsed = parseJsonc(readFileSync(filePath, "utf8"))
+    if (!parsed || !Array.isArray(parsed.plugin)) return true
+    const next = parsed.plugin.filter((item) => item !== ref)
+    if (next.length !== parsed.plugin.length) {
+      parsed.plugin = next
+      writeFileSync(filePath, JSON.stringify(parsed, null, 2) + "\n")
+      console.log(`[usage-limit] ${fileName} 등록 해제: ${ref}`)
+    }
+    return true
+  }
+
+  if (!existsSync(filePath)) {
+    const minimal = fileName === "tui.json"
+      ? { $schema: "https://opencode.ai/tui.json", plugin: [ref] }
+      : { plugin: [ref] }
+    writeFileSync(filePath, JSON.stringify(minimal, null, 2) + "\n")
+    console.log(`[usage-limit] ${filePath} 생성 및 등록`)
+    return true
+  }
+
+  const parsed = parseJsonc(readFileSync(filePath, "utf8"))
+  if (!parsed) {
+    console.error(`[usage-limit] ${fileName} 파싱 실패. 수동 등록 필요:`)
+    console.error(`  "${ref}" 를 "plugin" 배열에 추가하세요.`)
+    return false
+  }
+  const plugins = Array.isArray(parsed.plugin) ? parsed.plugin : []
+  if (plugins.includes(ref)) {
+    console.log(`[usage-limit] ${fileName}: 이미 등록됨`)
+    return true
+  }
+  parsed.plugin = [...plugins, ref]
+  writeFileSync(filePath, JSON.stringify(parsed, null, 2) + "\n")
+  console.log(`[usage-limit] ${fileName} 등록: ${ref}`)
+  return true
+}
+
+if (remove) {
+  rmSync(COLLECTOR_DST, { force: true })
+  rmSync(TUI_DST, { force: true })
+  rmSync(STATE_DIR, { recursive: true, force: true })
+  const okMain = updateConfig("opencode.jsonc", COLLECTOR_REF)
+  const okTui = updateConfig("tui.json", TUI_REF)
+  console.log(`[usage-limit] 제거 완료 (설정 파일 ${CONFIG_DST}은 유지됩니다).`)
+  process.exit(okMain && okTui ? 0 : 1)
+}
+
+if (!existsSync(COLLECTOR_SRC) || !existsSync(TUI_SRC)) {
+  console.error("[usage-limit] 오류: 패키지 파일이 없습니다. 저장소가 온전한지 확인하세요.")
+  process.exit(1)
+}
+
+mkdirSync(path.dirname(COLLECTOR_DST), { recursive: true })
+mkdirSync(path.dirname(TUI_DST), { recursive: true })
+copyFileSync(COLLECTOR_SRC, COLLECTOR_DST)
+copyFileSync(TUI_SRC, TUI_DST)
+console.log(`[usage-limit] 수집기 설치: ${COLLECTOR_DST}`)
+console.log(`[usage-limit] TUI 플러그인 설치: ${TUI_DST}`)
+
+if (!existsSync(CONFIG_DST)) {
+  copyFileSync(CONFIG_SRC, CONFIG_DST)
+  console.log(`[usage-limit] 설정 생성: ${CONFIG_DST} (dailyLimit 편집 가능)`)
+} else {
+  console.log(`[usage-limit] 기존 설정 유지: ${CONFIG_DST}`)
+}
+
+const okMain = updateConfig("opencode.jsonc", COLLECTOR_REF)
+const okTui = updateConfig("tui.json", TUI_REF)
+if (okMain && okTui) {
+  console.log("[usage-limit] 설치 완료. opencode를 재시작하세요.")
+}
+process.exit(okMain && okTui ? 0 : 1)

package/config-default.json

@@ -0,0 +1,21 @@
+{
+  "$comment": "opencode usage-tracker 설정. dailyLimit: 일일 순토큰 한도 (0 = 미지정, 남은 한도 대신 사용량만 표시). plan: free(기본) | go | go-plus",
+  "enabled": true,
+  "plan": "free",
+  "dailyLimit": 3000000,
+  "warnThresholds": [0.8, 0.95],
+  "cacheWeights": { "read": 0.1, "write": 0.25 },
+  "resetTimezone": "Asia/Seoul",
+  "pollSeconds": 30,
+  "historyDays": 2,
+  "rateLimitPatterns": [
+    "rate increased too quickly",
+    "scale requests more smoothly",
+    "ensure system stability",
+    "rate limit",
+    "rate_limit",
+    "too many requests",
+    "quota exceeded",
+    "usage exceeded"
+  ]
+}

package/index.js

@@ -0,0 +1,120 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { homedir } from "node:os"
+import path from "node:path"
+
+const CONFIG_PATH = path.join(homedir(), ".config/opencode/usage-tracker.json")
+const STATE_DIR = path.join(homedir(), ".config/opencode/usage-tracker")
+const STATE_PATH = path.join(STATE_DIR, "rate-limits.json")
+
+const DEFAULT_PATTERNS = [
+  "rate increased too quickly",
+  "scale requests more smoothly",
+  "ensure system stability",
+  "rate limit",
+  "rate_limit",
+  "too many requests",
+  "quota exceeded",
+  "usage exceeded",
+]
+
+function loadJson(file, fallback) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"))
+  } catch {
+    return fallback
+  }
+}
+
+function saveState(state) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true })
+    writeFileSync(STATE_PATH, JSON.stringify(state, null, 2))
+  } catch {}
+}
+
+function errorText(properties) {
+  const seen = new Set()
+  const parts = []
+  function visit(value, depth) {
+    if (value == null || depth > 5 || seen.has(value)) return
+    if (typeof value === "string") {
+      parts.push(value)
+      return
+    }
+    if (typeof value !== "object") return
+    seen.add(value)
+    for (const key of [
+      "message",
+      "error",
+      "title",
+      "data",
+      "name",
+      "statusCode",
+      "status_code",
+      "responseBody",
+      "body",
+      "metadata",
+      "url",
+      "cause",
+      "detail",
+      "details",
+    ]) {
+      if (key in value) visit(value[key], depth + 1)
+    }
+  }
+  visit(properties, 0)
+  return parts.join(" ")
+}
+
+const ZEN_SIGNATURES = ["rate increased too quickly", "scale requests more smoothly", "ensure system stability"]
+
+function cooldownMinutesFor(text, config) {
+  const t = text.toLowerCase()
+  if (
+    t.includes("nvidia") ||
+    t.includes("integrate.api.nvidia.com") ||
+    t.includes("nvapi") ||
+    (/nim\b/.test(t) && t.includes("too many requests"))
+  ) {
+    return config?.nim?.refillMinutes ?? 40
+  }
+  if (ZEN_SIGNATURES.some((s) => t.includes(s))) {
+    return config?.zen?.cooldownMinutes ?? 3
+  }
+  return config?.other?.cooldownMinutes ?? 5
+}
+
+export const UsageTrackerCollector = async () => {
+  const config = loadJson(CONFIG_PATH, {})
+  if (config?.enabled === false) return {}
+  const patterns = (config?.rateLimitPatterns ?? DEFAULT_PATTERNS).map((p) => p.toLowerCase())
+
+  return {
+    event: async ({ event }) => {
+      if (!event?.type || !event.type.includes("error")) return
+      const text = errorText(event.properties ?? {})
+      if (!text) return
+      const lower = text.toLowerCase()
+      if (!patterns.some((p) => lower.includes(p))) return
+
+      const now = Date.now()
+      const cooldownMin = cooldownMinutesFor(text, config)
+      const sessionID = event.properties?.sessionID ?? ""
+      const state = loadJson(STATE_PATH, {})
+      const key = sessionID || "global"
+      const prev = state[key] ?? {}
+      state[key] = {
+        lastSeen: now,
+        count: (prev.count ?? 0) + 1,
+        cooldownUntil: now + cooldownMin * 60_000,
+        cooldownMinutes: cooldownMin,
+        sessionID,
+        snippet: text.slice(0, 300),
+      }
+      state.lastEventAt = now
+      saveState(state)
+    },
+  }
+}
+
+export default UsageTrackerCollector

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "opencode-usage-limit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "OpenCode plugin that shows today's remaining usage limit as a sidebar gauge, tracks 429 rate limits, and provides a /usage dashboard",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "opencode-usage-limit": "bin/opencode-usage-limit.mjs"
+  },
+  "files": [
+    "index.js",
+    "tui/usage-tracker.js",
+    "config-default.json",
+    "bin/opencode-usage-limit.mjs"
+  ],
+  "keywords": [
+    "opencode",
+    "plugin",
+    "usage",
+    "limit",
+    "rate-limit",
+    "gauge",
+    "tui"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/tui/usage-tracker.js

@@ -0,0 +1,629 @@
+import { createSignal } from "solid-js"
+import { jsx } from "@opentui/solid/jsx-runtime"
+import { Database } from "bun:sqlite"
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import path from "node:path"
+
+const HOME = homedir()
+const CONFIG_PATH = path.join(HOME, ".config/opencode/usage-tracker.json")
+const RATE_LIMIT_STATE_PATH = path.join(HOME, ".config/opencode/usage-tracker/rate-limits.json")
+
+const DEFAULT_CONFIG = {
+  enabled: true,
+  plan: "free",
+  dailyLimit: 0,
+  warnThresholds: [0.8, 0.95],
+  cacheWeights: { read: 0.1, write: 0.25 },
+  resetTimezone: "Asia/Seoul",
+  pollSeconds: 30,
+  historyDays: 2,
+}
+
+// OpenCode Go 요금표 (USD per 1M tokens): [input, output, cacheRead, cacheWrite, monthlyLimit]
+const GO_PRICING = {
+  "glm-5.3-flash": [0.15, 0.5, 0.03, 0, 60],
+  "glm-5.3": [1.4, 4.4, 0.26, 0, 15],
+  "glm-5.2": [1.4, 4.4, 0.26, 0, 60],
+  "kimi-k3": [3.0, 15.0, 0.3, 0, 15],
+  "kimi-k2.7-code": [0.95, 4.0, 0.19, 0, 60],
+  "longcat-2.0": [0.3, 1.2, 0.006, 0, 60],
+  "step-5-preview": [1.0, 2.7, 0.1, 0, 15],
+  "mimo-v2.6-flash": [0.14, 0.28, 0.0028, 0, 60],
+  "mimo-v2.6-pro": [0.435, 0.87, 0.003625, 0, 15],
+  "mimo-v2.5": [0.14, 0.28, 0.0028, 0, 60],
+  "mimo-v2.5-pro": [0.435, 0.87, 0.003625, 0, 15],
+  "minimax-m3.1-flash": [0.15, 0.6, 0.015, 0, 20],
+  "minimax-m3": [0.3, 1.2, 0.06, 0, 60],
+  "muse-spark-1.3-contributor": [0.1, 0.2, 0.002, 0, 60],
+  "muse-spark-1.2-contributor": [0.1, 0.2, 0.002, 0, 60],
+  "qwen3.8-max": [2.0, 6.0, 0.25, 2.5, 15],
+  "qwen3.8-flash": [0.15, 0.47, 0.016, 0.2, 30],
+  "qwen3.7-plus": [0.4, 1.6, 0.04, 0.5, 60],
+  "deepseek-v4.1-flash": [0.15, 0.6, 0.003, 0, 80],
+  "deepseek-v4-pro": [0.66, 1.98, 0.022, 0, 15],
+  "hy4-preview": [0.834, 2.501, 0.042, 0, 30],
+  "hy3": [0.14, 0.58, 0.035, 0, 60],
+  "grok-4.7": [2.0, 6.0, 0.5, 0, 15],
+  "gpt-6-luna": [0.1, 0.5, 0.01, 0.125, 15],
+  "gpt-5.6-luna": [0.2, 1.2, 0.02, 0.25, 15],
+  "claude-haiku-5-5": [0.1, 0.5, 0.01, 0.125, 15],
+  "gemini-4-argon-contributor": [4.0, 20.0, 0.2, 0, 60],
+}
+
+const GO_PLUS_PRICING = {
+  "glm-5.3-flash": [0.15, 0.5, 0.03, 0, 180],
+  "glm-5.3": [1.4, 4.4, 0.26, 0, 120],
+  "glm-5.2": [1.4, 4.4, 0.26, 0, 180],
+  "kimi-k3": [3.0, 15.0, 0.3, 0, 60],
+  "kimi-k2.7-code": [0.95, 4.0, 0.19, 0, 180],
+  "longcat-2.0": [0.3, 1.2, 0.006, 0, 240],
+  "step-5-preview": [1.0, 2.7, 0.1, 0, 60],
+  "mimo-v2.6-flash": [0.14, 0.28, 0.0028, 0, 120],
+  "mimo-v2.6-pro": [0.435, 0.87, 0.003625, 0, 60],
+  "mimo-v2.5": [0.14, 0.28, 0.0028, 0, 120],
+  "mimo-v2.5-pro": [0.435, 0.87, 0.003625, 0, 60],
+  "minimax-m3.1-flash": [0.15, 0.6, 0.015, 0, 80],
+  "minimax-m3": [0.3, 1.2, 0.06, 0, 180],
+  "muse-spark-1.3-contributor": [0.1, 0.2, 0.002, 0, 120],
+  "muse-spark-1.2-contributor": [0.1, 0.2, 0.002, 0, 120],
+  "qwen3.8-max": [2.0, 6.0, 0.25, 2.5, 60],
+  "qwen3.8-flash": [0.15, 0.47, 0.016, 0.2, 90],
+  "qwen3.7-plus": [0.4, 1.6, 0.04, 0.5, 180],
+  "deepseek-v4.1-flash": [0.15, 0.6, 0.003, 0, 160],
+  "deepseek-v4-pro": [0.66, 1.98, 0.022, 0, 60],
+  "hy4-preview": [0.834, 2.501, 0.042, 0, 120],
+  "hy3": [0.14, 0.58, 0.035, 0, 240],
+  "grok-4.7": [2.0, 6.0, 0.5, 0, 60],
+  "gpt-6-luna": [0.1, 0.5, 0.01, 0.125, 60],
+  "gpt-5.6-luna": [0.2, 1.2, 0.02, 0.25, 60],
+  "claude-haiku-5-5": [0.1, 0.5, 0.01, 0.125, 60],
+  "gemini-4-argon-contributor": [4.0, 20.0, 0.2, 0, 240],
+}
+
+function loadJson(file, fallback) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"))
+  } catch {
+    return fallback
+  }
+}
+
+function findDatabasePath() {
+  const xdg = process.env.XDG_DATA_HOME
+  const candidates = [
+    xdg ? path.join(xdg, "opencode", "opencode.db") : null,
+    path.join(HOME, ".local/share/opencode/opencode.db"),
+    path.join(HOME, ".opencode/opencode.db"),
+  ].filter(Boolean)
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+function tzOffsetMinutes(tz, ts) {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+  })
+  const parts = dtf.formatToParts(new Date(ts)).reduce((acc, p) => {
+    acc[p.type] = p.value
+    return acc
+  }, {})
+  const asUTC = Date.UTC(
+    Number(parts.year),
+    Number(parts.month) - 1,
+    Number(parts.day),
+    Number(parts.hour) % 24,
+    Number(parts.minute),
+    Number(parts.second),
+  )
+  return Math.round((asUTC - ts) / 60000)
+}
+
+function startOfDay(ts, tz) {
+  const dtf = new Intl.DateTimeFormat("en-CA", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  })
+  const [y, m, d] = dtf.format(new Date(ts)).split("-").map(Number)
+  const noonUTC = Date.UTC(y, m - 1, d, 12)
+  const offset = tzOffsetMinutes(tz, noonUTC)
+  return Date.UTC(y, m - 1, d) - offset * 60000
+}
+
+function startOfMonth(ts, tz) {
+  const dtf = new Intl.DateTimeFormat("en-CA", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+  })
+  const [y, m] = dtf.format(new Date(ts)).split("-").map(Number)
+  const noonUTC = Date.UTC(y, m - 1, 1, 12)
+  const offset = tzOffsetMinutes(tz, noonUTC)
+  return Date.UTC(y, m - 1, 1) - offset * 60000
+}
+
+function fmtTokens(n) {
+  if (n >= 1e9) return (n / 1e9).toFixed(1) + "B"
+  if (n >= 1e6) return (n / 1e6).toFixed(1) + "M"
+  if (n >= 1e3) return (n / 1e3).toFixed(1) + "k"
+  return String(Math.round(n))
+}
+
+function fmtUSD(n) {
+  if (n < 0.005) return "$0"
+  return "$" + n.toFixed(n < 10 ? 2 : 1)
+}
+
+function fmtDuration(ms) {
+  const totalMin = Math.max(0, Math.round(ms / 60000))
+  const h = Math.floor(totalMin / 60)
+  const m = totalMin % 60
+  if (h > 0) return `${h}h ${m}m`
+  if (m > 0) return `${m}m`
+  return "곧"
+}
+
+function bar(remainRatio, width = 10) {
+  const clamped = Math.max(0, Math.min(1, remainRatio))
+  const filled = Math.round(clamped * width)
+  return "[" + "█".repeat(filled) + "░".repeat(width - filled) + "]"
+}
+
+export default {
+  id: "usage-tracker",
+  tui: async (api) => {
+    const config = { ...DEFAULT_CONFIG, ...loadJson(CONFIG_PATH, {}) }
+    if (config.enabled === false) return
+    const cacheWeights = { ...DEFAULT_CONFIG.cacheWeights, ...config.cacheWeights }
+    const tz = config.resetTimezone || "Asia/Seoul"
+    const dailyLimit = Number(config.dailyLimit) > 0 ? Number(config.dailyLimit) : 0
+    const goPlan = config.plan === "go" ? GO_PRICING : config.plan === "go-plus" ? GO_PLUS_PRICING : null
+
+    const [revision, setRevision] = createSignal(0)
+    const [dashVisible, setDashVisible] = createSignal(false)
+    const bump = () => setRevision((r) => r + 1)
+
+    let db = null
+    let dbError = ""
+    let modelMap = new Map()
+    let records = []
+    let lastLoadedTs = 0
+    let lastToastKey = ""
+    let pendingSessionIds = new Set()
+
+    const openDb = () => {
+      if (db) return true
+      const dbPath = findDatabasePath()
+      if (!dbPath) {
+        dbError = "opencode.db를 찾을 수 없음"
+        return false
+      }
+      try {
+        db = new Database(dbPath, { readonly: true })
+        return true
+      } catch (error) {
+        dbError = "DB 열기 실패: " + (error instanceof Error ? error.message : String(error))
+        return false
+      }
+    }
+
+    const ensureModels = (sessionIds) => {
+      if (!sessionIds.length) return
+      try {
+        const placeholders = sessionIds.map(() => "?").join(",")
+        const rows = db
+          .prepare(`SELECT id, model FROM session WHERE id IN (${placeholders})`)
+          .all(...sessionIds)
+        for (const row of rows) {
+          try {
+            const model = JSON.parse(row.model || "{}")
+            modelMap.set(row.id, {
+              providerID: model.providerID ?? "",
+              modelID: model.id ?? "",
+            })
+          } catch {}
+        }
+        for (const sid of sessionIds) {
+          if (!modelMap.has(sid)) pendingSessionIds.add(sid)
+        }
+      } catch {}
+    }
+
+    const loadRecords = (sinceTs) => {
+      if (!openDb()) return
+      const now = Date.now()
+      try {
+        const rows = db
+          .prepare(
+            "SELECT session_id, time_created, data FROM part WHERE time_created >= ? AND data LIKE '%\"type\":\"step-finish\"%' ORDER BY time_created ASC",
+          )
+          .all(sinceTs)
+        const newSessions = new Set()
+        let maxTs = sinceTs
+        for (const row of rows) {
+          let parsed
+          try {
+            parsed = JSON.parse(row.data)
+          } catch {
+            continue
+          }
+          if (parsed?.type !== "step-finish" || !parsed?.tokens) continue
+          records.push({
+            ts: row.time_created,
+            sid: row.session_id,
+            input: parsed.tokens.input ?? 0,
+            output: parsed.tokens.output ?? 0,
+            cacheRead: parsed.tokens.cache?.read ?? 0,
+            cacheWrite: parsed.tokens.cache?.write ?? 0,
+          })
+          if (row.time_created > maxTs) maxTs = row.time_created
+          if (!modelMap.has(row.session_id)) newSessions.add(row.session_id)
+        }
+        ensureModels([...newSessions, ...pendingSessionIds])
+        pendingSessionIds = new Set(
+          [...pendingSessionIds].filter((sid) => !modelMap.has(sid)),
+        )
+        lastLoadedTs = Math.max(lastLoadedTs, maxTs, now - 1000)
+      } catch (error) {
+        dbError = "조회 실패: " + (error instanceof Error ? error.message : String(error))
+      }
+    }
+
+    const refresh = () => {
+      const historyMs = (config.historyDays || 2) * 86400000
+      loadRecords(lastLoadedTs || Date.now() - historyMs)
+      bump()
+    }
+
+    const netTokens = (r) =>
+      r.input +
+      r.output +
+      r.cacheRead * (cacheWeights.read ?? 0.1) +
+      r.cacheWrite * (cacheWeights.write ?? 0.25)
+
+    const todayAggregate = () => {
+      const todayStart = startOfDay(Date.now(), tz)
+      const agg = { requests: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0, net: 0 }
+      for (const r of records) {
+        if (r.ts < todayStart) continue
+        agg.requests += 1
+        agg.input += r.input
+        agg.output += r.output
+        agg.cacheRead += r.cacheRead
+        agg.cacheWrite += r.cacheWrite
+        agg.net += netTokens(r)
+      }
+      return agg
+    }
+
+    const goUsage = (from) => {
+      let cost = 0
+      let limit = 0
+      const seen = new Set()
+      for (const r of records) {
+        if (r.ts < from) continue
+        const model = modelMap.get(r.sid)
+        if (!model || model.providerID !== "opencode-go") continue
+        const price = goPlan[model.modelID]
+        if (!price) continue
+        cost +=
+          (r.input / 1e6) * price[0] +
+          (r.output / 1e6) * price[1] +
+          (r.cacheRead / 1e6) * price[2] +
+          (r.cacheWrite / 1e6) * price[3]
+        if (!seen.has(model.modelID)) {
+          seen.add(model.modelID)
+          limit = Math.max(limit, price[4])
+        }
+      }
+      return { cost, limit }
+    }
+
+    const topModelsToday = (limit = 5) => {
+      const todayStart = startOfDay(Date.now(), tz)
+      const stats = new Map()
+      for (const r of records) {
+        if (r.ts < todayStart) continue
+        const model = modelMap.get(r.sid) ?? { providerID: "?", modelID: "?" }
+        const key = model.modelID || "?"
+        const entry = stats.get(key) ?? { net: 0, requests: 0 }
+        entry.net += netTokens(r)
+        entry.requests += 1
+        stats.set(key, entry)
+      }
+      return [...stats.entries()]
+        .sort((a, b) => b[1].net - a[1].net)
+        .slice(0, limit)
+    }
+
+    const activeCooldowns = () => {
+      const state = loadJson(RATE_LIMIT_STATE_PATH, {})
+      const now = Date.now()
+      const out = []
+      for (const [key, entry] of Object.entries(state)) {
+        if (key === "lastEventAt" || !entry?.cooldownUntil) continue
+        if (entry.cooldownUntil <= now) continue
+        out.push({
+          key,
+          minutesLeft: entry.cooldownUntil - now,
+          count: entry.count ?? 1,
+        })
+      }
+      return out.sort((a, b) => b.minutesLeft - a.minutesLeft)
+    }
+
+    const recentRateLimits = (windowMs = 3600000) => {
+      const state = loadJson(RATE_LIMIT_STATE_PATH, {})
+      const now = Date.now()
+      let count = 0
+      for (const [key, entry] of Object.entries(state)) {
+        if (key === "lastEventAt" || !entry?.lastSeen) continue
+        if (now - entry.lastSeen <= windowMs) count += 1
+      }
+      return count
+    }
+
+    const maybeWarn = (message, key) => {
+      if (lastToastKey === key) return
+      lastToastKey = key
+      api.ui.toast({ variant: "warn", message, duration: 6000 })
+    }
+
+    const remainColor = (remainRatio, theme) => {
+      if (remainRatio <= 0.2) return theme.error ?? theme.accent
+      if (remainRatio <= 0.5) return theme.accent
+      return theme.text
+    }
+
+    const footerLines = (theme) => {
+      const now = Date.now()
+      const todayStart = startOfDay(now, tz)
+      const today = todayAggregate()
+      const resetIn = todayStart + 86400000 - now
+      const lines = []
+
+      if (goPlan) {
+        const fiveHour = goUsage(now - 5 * 3600000)
+        const month = goUsage(startOfMonth(now, tz))
+        if (fiveHour.limit > 0) {
+          const cap = fiveHour.limit * 0.2
+          const remain = Math.max(0, cap - fiveHour.cost)
+          const remainRatio = cap > 0 ? remain / cap : 0
+          lines.push(
+            jsx("text", {
+              fg: remainColor(remainRatio, theme),
+              children: `⚡ 5h 남음 ${fmtUSD(remain)} (${Math.round(remainRatio * 100)}%)`,
+            }),
+          )
+          lines.push(
+            jsx("text", {
+              fg: theme.textMuted,
+              children: `${bar(remainRatio)} 월 남음 ${fmtUSD(Math.max(0, month.limit - month.cost))}`,
+            }),
+          )
+          if (remainRatio <= 0.2) {
+            maybeWarn(
+              `5시간 윈도우 한도 임박: 남음 ${fmtUSD(remain)} / ${fmtUSD(cap)}`,
+              "go5h-" + Math.round(remainRatio * 20),
+            )
+          }
+        }
+      } else if (dailyLimit > 0) {
+        const remain = Math.max(0, dailyLimit - today.net)
+        const remainRatio = dailyLimit > 0 ? remain / dailyLimit : 0
+        lines.push(
+          jsx("text", {
+            fg: remainColor(remainRatio, theme),
+            children: `⚡ 오늘 남음 ${fmtTokens(remain)} (${Math.round(remainRatio * 100)}%) · ${fmtDuration(resetIn)} 리셋`,
+          }),
+        )
+        lines.push(
+          jsx("text", {
+            fg: theme.textMuted,
+            children: `${bar(remainRatio)} 사용 ${fmtTokens(today.net)} · ${today.requests} req`,
+          }),
+        )
+        if (remainRatio <= 0.05) {
+          maybeWarn(
+            `일일 한도 소진 임박: ${fmtTokens(remain)} 남음 (사용 ${fmtTokens(today.net)}/${fmtTokens(dailyLimit)})`,
+            "daily-" + Math.round(remainRatio * 20),
+          )
+        }
+      } else {
+        lines.push(
+          jsx("text", {
+            fg: theme.textMuted,
+            children: `⚡ 오늘 ${fmtTokens(today.net)} 순토큰 · ${today.requests} req`,
+          }),
+        )
+        lines.push(
+          jsx("text", {
+            fg: theme.textMuted,
+            children: `리셋 ${fmtDuration(resetIn)} · usage-tracker.json에 dailyLimit 설정 시 남은 한도 표시`,
+          }),
+        )
+      }
+
+      const cooldowns = activeCooldowns()
+      if (cooldowns.length > 0) {
+        lines.push(
+          jsx("text", {
+            fg: theme.error ?? theme.accent,
+            children: `⛔ 429 쿨다운 ${fmtDuration(cooldowns[0].minutesLeft)} · /usage로 상세`,
+          }),
+        )
+      }
+      return lines
+    }
+
+    const dashboardLines = (theme) => {
+      const now = Date.now()
+      const today = todayAggregate()
+      const resetIn = startOfDay(now, tz) + 86400000 - now
+      const lines = []
+
+      lines.push(jsx("text", { fg: theme.accent, children: "─── 오늘 사용량 ───" }))
+      lines.push(
+        jsx("text", {
+          fg: theme.text,
+          children: `순 ${fmtTokens(today.net)} · ${today.requests} req · 리셋 ${fmtDuration(resetIn)}`,
+        }),
+      )
+      lines.push(
+        jsx("text", {
+          fg: theme.textMuted,
+          children: `입력 ${fmtTokens(today.input)} · 출력 ${fmtTokens(today.output)} · 캐시 읽기 ${fmtTokens(today.cacheRead)}`,
+        }),
+      )
+      if (!goPlan && dailyLimit > 0) {
+        const remain = Math.max(0, dailyLimit - today.net)
+        lines.push(
+          jsx("text", {
+            fg: remainColor(dailyLimit > 0 ? remain / dailyLimit : 0, theme),
+            children: `남은 한도 ${fmtTokens(remain)} / ${fmtTokens(dailyLimit)}`,
+          }),
+        )
+      }
+
+      lines.push(jsx("text", { fg: theme.accent, children: "─── 모델별 오늘 ───" }))
+      const models = topModelsToday()
+      if (models.length === 0) {
+        lines.push(jsx("text", { fg: theme.textMuted, children: "기록 없음" }))
+      }
+      for (const [name, stat] of models) {
+        lines.push(
+          jsx("text", {
+            fg: theme.textMuted,
+            children: `${name.slice(0, 24).padEnd(24)} ${fmtTokens(stat.net).padStart(7)} · ${stat.requests} req`,
+          }),
+        )
+      }
+
+      lines.push(jsx("text", { fg: theme.accent, children: "─── 429 rate limit ───" }))
+      const cooldowns = activeCooldowns()
+      lines.push(
+        jsx("text", {
+          fg: theme.textMuted,
+          children: `최근 1시간 ${recentRateLimits()}회 · 진행 중 쿨다운 ${cooldowns.length}건`,
+        }),
+      )
+      for (const c of cooldowns.slice(0, 3)) {
+        lines.push(
+          jsx("text", {
+            fg: theme.error ?? theme.accent,
+            children: `쿨다운 ${fmtDuration(c.minutesLeft)} · ${c.count}회 누적`,
+          }),
+        )
+      }
+      return lines
+    }
+
+    api.slots.register({
+      slots: {
+        sidebar_footer: (context, props) =>
+          jsx("box", {
+            flexDirection: "column",
+            paddingLeft: 1,
+            paddingRight: 1,
+            children: () => {
+              revision()
+              const theme = context.theme.current
+              if (!props?.session_id) return null
+              try {
+                if (dbError && !db) {
+                  return [
+                    jsx("text", { fg: theme.error ?? theme.accent, children: `⚡ usage-tracker: ${dbError}` }),
+                  ]
+                }
+                const lines = footerLines(theme)
+                if (dashVisible()) lines.push(...dashboardLines(theme))
+                return lines
+              } catch (error) {
+                return [
+                  jsx("text", {
+                    fg: theme.error ?? theme.accent,
+                    children: "usage-tracker 렌더 오류: " + (error instanceof Error ? error.message : String(error)),
+                  }),
+                ]
+              }
+            },
+          }),
+      },
+    })
+
+    let refreshTimer = null
+    const unsubscribers = []
+
+    refresh()
+
+    const pollMs = Math.max(5, config.pollSeconds || 30) * 1000
+    refreshTimer = setInterval(() => refresh(), pollMs)
+
+    const partUnsub = api.event.on("message.part.updated", (event) => {
+      const part = event?.properties?.part
+      if (part?.type === "step-finish") refresh()
+    })
+    if (partUnsub) unsubscribers.push(partUnsub)
+
+    const errorUnsub = api.event.on("session.error", () => {
+      const state = loadJson(RATE_LIMIT_STATE_PATH, {})
+      if (state?.lastEventAt && Date.now() - state.lastEventAt < 10000) {
+        refresh()
+      }
+    })
+    if (errorUnsub) unsubscribers.push(errorUnsub)
+
+    const statusUnsub = api.event.on("session.status", (event) => {
+      if (event?.properties?.status?.type === "idle") refresh()
+    })
+    if (statusUnsub) unsubscribers.push(statusUnsub)
+
+    api.keymap.registerLayer({
+      priority: 900,
+      commands: [
+        {
+          name: "usage-tracker.toggle",
+          title: "Toggle usage dashboard",
+          desc: "오늘 사용량/남은 한도/429 쿨다운 대시보드 표시",
+          category: "Session",
+          namespace: "palette",
+          slashName: "usage",
+          run: () => {
+            const next = !dashVisible()
+            setDashVisible(next)
+            if (next) refresh()
+            api.ui.toast({
+              variant: next ? "success" : "info",
+              message: next ? "사용량 대시보드를 열었습니다." : "사용량 대시보드를 닫았습니다.",
+              duration: 2000,
+            })
+          },
+        },
+      ],
+      bindings: [],
+    })
+
+    api.lifecycle.onDispose(() => {
+      if (refreshTimer) clearInterval(refreshTimer)
+      for (const unsub of unsubscribers) {
+        try {
+          unsub()
+        } catch {}
+      }
+      try {
+        db?.close()
+      } catch {}
+    })
+  },
+}