@doguyilmaz/konvoy 0.1.1

package/src/dashboard/page.ts

@@ -0,0 +1,211 @@
+import type { Database } from 'bun:sqlite'
+import {
+  turnsPerDay,
+  turnsPerDayByAgent,
+  usageAcrossSessions,
+  usageByAgentModel,
+  usageForSession,
+} from '../store/queries'
+import type { Config } from '../config/schema'
+import { estimateAgentUsd } from '../pricing'
+import { spend } from '../format'
+
+export interface DashboardData {
+  title: string
+  asOf: string
+  agents: {
+    agent: string
+    turns: number
+    inputTokens: number
+    outputTokens: number
+    spend: string
+    estimateUsd: number | null
+  }[]
+  days: { day: string; count: number }[]
+  byAgentDay: { agent: string; day: string; count: number }[]
+  totals: { turns: number; inputTokens: number; outputTokens: number }
+}
+
+// collect is a pure read of the same tables `konvoy usage --chart` reads, through the same
+// queries — a parallel query here is exactly how the two views would start disagreeing
+export function collect(db: Database, cfg: Config, sessionId?: string): DashboardData {
+  const rows = sessionId ? usageForSession(db, sessionId) : usageAcrossSessions(db)
+  const modelRows = usageByAgentModel(db, sessionId)
+
+  const agents = rows.map((r) => ({
+    agent: r.agent,
+    turns: r.turns,
+    inputTokens: r.inputTokens,
+    outputTokens: r.outputTokens,
+    spend: spend(r),
+    estimateUsd: estimateAgentUsd(r.agent, modelRows, cfg.pricing),
+  }))
+
+  const totals = rows.reduce(
+    (acc, r) => ({
+      turns: acc.turns + r.turns,
+      inputTokens: acc.inputTokens + r.inputTokens,
+      outputTokens: acc.outputTokens + r.outputTokens,
+    }),
+    { turns: 0, inputTokens: 0, outputTokens: 0 },
+  )
+
+  return {
+    title: '',
+    asOf: cfg.pricing.asOf,
+    agents,
+    days: turnsPerDay(db, sessionId),
+    byAgentDay: turnsPerDayByAgent(db, sessionId),
+    totals,
+  }
+}
+
+function escape(text: string): string {
+  return text.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!)
+}
+
+// every day between the first and last, inclusive — gaps filled with zero downstream — so
+// bars line up between agents the same way the terminal's sparklines line up columns
+function expandDays(start: string, end: string): string[] {
+  const days: string[] = []
+  for (
+    const cursor = new Date(`${start}T00:00:00Z`);
+    cursor <= new Date(`${end}T00:00:00Z`);
+    cursor.setUTCDate(cursor.getUTCDate() + 1)
+  ) {
+    days.push(cursor.toISOString().slice(0, 10))
+  }
+  return days
+}
+
+function usdCell(a: DashboardData['agents'][number]): string {
+  if (a.estimateUsd === null) return '-'
+  return a.spend.startsWith('$') ? `$${a.estimateUsd.toFixed(2)}` : `$${a.estimateUsd.toFixed(3)}`
+}
+
+function totalsBarsSvg(days: { day: string; count: number }[]): string {
+  if (days.length === 0) return '<p class="empty">no turns recorded yet</p>'
+  const range = expandDays(days[0]!.day, days[days.length - 1]!.day)
+  const counts = new Map(days.map((d) => [d.day, d.count]))
+  const values = range.map((d) => counts.get(d) ?? 0)
+  const max = Math.max(...values, 1)
+
+  const barW = 14
+  const gap = 4
+  const height = 84
+  const floor = height - 14
+  const width = range.length * (barW + gap)
+
+  const bars = values
+    .map((v, i) => {
+      const h = v > 0 ? Math.max(1, Math.round((v / max) * (floor - 4))) : 0
+      const x = i * (barW + gap)
+      const y = floor - h
+      return `<rect x="${x}" y="${y}" width="${barW}" height="${h}" rx="2"></rect><text x="${x + barW / 2}" y="${height - 2}" text-anchor="middle">${escape(range[i]!.slice(5))}</text>`
+    })
+    .join('')
+
+  return `<svg viewBox="0 0 ${width} ${height}" width="${width}" height="${height}" role="img" aria-label="turns per day">${bars}</svg>`
+}
+
+function agentBarsSvg(rows: { agent: string; day: string; count: number }[]): string {
+  if (rows.length === 0) return '<p class="empty">no turns recorded yet</p>'
+
+  const sortedDays = [...new Set(rows.map((r) => r.day))].sort()
+  const range = expandDays(sortedDays[0]!, sortedDays[sortedDays.length - 1]!)
+
+  const byAgent = new Map<string, Map<string, number>>()
+  for (const r of rows) {
+    if (!byAgent.has(r.agent)) byAgent.set(r.agent, new Map())
+    byAgent.get(r.agent)!.set(r.day, r.count)
+  }
+
+  const series = [...byAgent.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([agent, dayCounts]) => ({ agent, values: range.map((d) => dayCounts.get(d) ?? 0) }))
+
+  // one shared max across every agent — a per-row scale would draw a quiet agent's two
+  // turns at a busy agent's height, hiding exactly the comparison this chart is for
+  const sharedMax = Math.max(...series.flatMap((s) => s.values), 1)
+
+  const barW = 10
+  const gap = 3
+  const rowHeight = 34
+  const width = range.length * (barW + gap)
+
+  const rowsHtml = series
+    .map(({ agent, values }) => {
+      const bars = values
+        .map((v, i) => {
+          const h = v > 0 ? Math.max(1, Math.round((v / sharedMax) * (rowHeight - 2))) : 0
+          const x = i * (barW + gap)
+          const y = rowHeight - h
+          return `<rect x="${x}" y="${y}" width="${barW}" height="${h}"></rect>`
+        })
+        .join('')
+      return `<div class="agent-row" data-agent="${escape(agent)}"><span class="agent-label">${escape(agent)}</span><svg viewBox="0 0 ${width} ${rowHeight}" width="${width}" height="${rowHeight}" role="img" aria-label="turns per day for ${escape(agent)}">${bars}</svg></div>`
+    })
+    .join('')
+
+  return `<div class="agent-bars">${rowsHtml}</div>`
+}
+
+const STYLE = `
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.5 -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; margin: 2rem; max-width: 860px; }
+  h1 { font-size: 1.25rem; margin-bottom: 0.25rem; }
+  .totals { color: #666; margin-top: 0; }
+  table { border-collapse: collapse; width: 100%; margin: 1rem 0; }
+  th, td { text-align: left; padding: 0.35rem 0.75rem 0.35rem 0; border-bottom: 1px solid #8883; }
+  h2 { font-size: 1rem; margin-top: 2rem; }
+  svg rect { fill: currentColor; opacity: 0.75; }
+  svg text { font-size: 8px; fill: currentColor; opacity: 0.6; }
+  .agent-row { display: flex; align-items: center; gap: 0.75rem; margin: 0.4rem 0; }
+  .agent-label { width: 5rem; flex: none; }
+  .empty, .note { color: #888; }
+`
+
+export function renderPage(data: DashboardData): string {
+  const title = escape(data.title)
+
+  const agentRows = data.agents
+    .map(
+      (a) => `<tr>
+        <td>${escape(a.agent)}</td>
+        <td>${a.turns}</td>
+        <td>${a.inputTokens}</td>
+        <td>${a.outputTokens}</td>
+        <td>${escape(a.spend)}</td>
+        <td>${usdCell(a)}</td>
+      </tr>`,
+    )
+    .join('')
+
+  const anyPriced = data.agents.some((a) => a.estimateUsd !== null)
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>konvoy dashboard — ${title}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<h1>${title}</h1>
+<p class="totals">${data.totals.turns} turns · ${data.totals.inputTokens} in · ${data.totals.outputTokens} out</p>
+
+<table>
+<thead><tr><th>AGENT</th><th>TURNS</th><th>IN</th><th>OUT</th><th>SPEND</th><th>~USD</th></tr></thead>
+<tbody>${agentRows}</tbody>
+</table>
+${anyPriced ? `<p class="note">~USD is estimated from rates configured as of ${escape(data.asOf || 'an unspecified date')}</p>` : ''}
+
+<h2>turns per day</h2>
+${totalsBarsSvg(data.days)}
+
+<h2>turns per day by agent</h2>
+${agentBarsSvg(data.byAgentDay)}
+</body>
+</html>`
+}

package/src/format.ts

@@ -0,0 +1,98 @@
+import type { AgentId } from './types'
+import type { UsageRow } from './store/queries'
+import { estimateAgentUsd, isPricingConfigured, type ModelUsage, type Pricing } from './pricing'
+
+export interface RosterRow {
+  agent: AgentId
+  status: string
+  model: string
+  effort: string
+  foreignId: string | null
+  turns: number
+  costUsd: number
+  credits: number
+}
+
+function table(header: string[], rows: string[][]): string {
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)))
+  const line = (cells: string[]) => cells.map((c, i) => c.padEnd(widths[i]!)).join('  ').trimEnd()
+  return [line(header), ...rows.map(line)].join('\n') + '\n'
+}
+
+export function formatRoster(rows: RosterRow[]): string {
+  return table(
+    ['AGENT', 'STATUS', 'MODEL', 'EFFORT', 'SESSION', 'TURNS', 'COST'],
+    rows.map((r) => [r.agent, r.status, r.model || '-', r.effort, r.foreignId ?? '-', String(r.turns), cost(r)]),
+  )
+}
+
+function cost(r: RosterRow): string {
+  if (r.costUsd > 0) return `$${r.costUsd.toFixed(2)}`
+  if (r.credits > 0) return `${r.credits.toFixed(3)} cr`
+  return '-'
+}
+
+// exported so the dashboard renders the same string the terminal does, rather than
+// reimplementing the credits-before-dollars rule and risking the two drifting apart
+export function spend(row: UsageRow): string {
+  // credits win when both are non-zero: they're what the agent actually charged, and the
+  // cost estimator derives its dollar figure from credits the same way — the two must
+  // never disagree about which number is the real one for a given row.
+  if (row.credits > 0) return `${row.credits.toFixed(3)} cr`
+  if (row.costUsd > 0) return `$${row.costUsd.toFixed(2)}`
+  return '-'
+}
+
+function usdCell(row: UsageRow, modelRows: ModelUsage[], pricing: Pricing): string {
+  const est = estimateAgentUsd(row.agent, modelRows, pricing)
+  if (est === null) return '-'
+  // an already-real dollar figure keeps money's usual 2 decimals; a credit- or token-derived
+  // estimate gets the extra precision those small figures are shown with, or it rounds to nothing
+  return row.costUsd > 0 ? `$${est.toFixed(2)}` : `$${est.toFixed(3)}`
+}
+
+export function formatUsage(rows: UsageRow[], pricing?: Pricing, modelRows: ModelUsage[] = []): string {
+  const showUsd = pricing !== undefined && isPricingConfigured(pricing)
+  const header = ['AGENT', 'TURNS', 'IN', 'OUT', 'SPEND', ...(showUsd ? ['~USD'] : []), 'GATE']
+  return table(
+    header,
+    rows.map((r) => [
+      r.agent,
+      String(r.turns),
+      String(r.inputTokens),
+      String(r.outputTokens),
+      spend(r),
+      ...(showUsd ? [usdCell(r, modelRows, pricing!)] : []),
+      r.gateKnown > 0 ? `${r.gatePassed}/${r.gateKnown}` : '-',
+    ]),
+  )
+}
+
+export function duplicateModels(rows: RosterRow[]): string[] {
+  const counts = new Map<string, number>()
+  for (const r of rows) {
+    if (!r.model) continue
+    counts.set(r.model, (counts.get(r.model) ?? 0) + 1)
+  }
+  return [...counts.entries()].filter(([, n]) => n > 1).map(([model]) => model)
+}
+
+export interface AgentStatusRow {
+  agent: AgentId
+  installed: boolean
+  version: string | null
+  authed: boolean | null
+  detail?: string
+}
+
+export function formatVersions(rows: AgentStatusRow[]): string {
+  return table(
+    ['AGENT', 'VERSION', 'AUTH', 'DETAIL'],
+    rows.map((r) => [
+      r.agent,
+      r.installed ? (r.version ?? 'unknown') : 'not installed',
+      r.authed === null ? 'unknown' : r.authed ? 'ok' : 'login required',
+      r.detail ?? '',
+    ]),
+  )
+}

package/src/paths.ts

@@ -0,0 +1,33 @@
+export function join(...parts: string[]): string {
+  const absolute = parts[0]?.startsWith('/') ?? false
+  const segments: string[] = []
+  for (const part of parts) {
+    for (const segment of part.split('/')) {
+      if (segment === '' || segment === '.') continue
+      if (segment === '..') {
+        segments.pop()
+        continue
+      }
+      segments.push(segment)
+    }
+  }
+  return (absolute ? '/' : '') + segments.join('/')
+}
+
+export function dirname(p: string): string {
+  const cut = p.lastIndexOf('/')
+  if (cut < 0) return '.'
+  if (cut === 0) return '/'
+  return p.slice(0, cut)
+}
+
+export function home(): string {
+  const h = Bun.env.HOME
+  if (!h) throw new Error('HOME is not set')
+  return h
+}
+
+export const configDir = (): string => join(home(), '.config', 'konvoy')
+const dataDir = (): string => join(home(), '.local', 'share', 'konvoy')
+export const dbPath = (): string => join(dataDir(), 'konvoy.db')
+export const sessionDir = (cwd: string, slug: string): string => join(cwd, '.konvoy', slug)

package/src/pricing.ts

@@ -0,0 +1,86 @@
+import type { AgentId } from './types'
+import type { Config } from './config/schema'
+
+export type Pricing = Config['pricing']
+
+export interface Priced {
+  agent: AgentId
+  model: string | null
+  inputTokens: number
+  outputTokens: number
+  credits: number
+}
+
+export function estimateUsd(row: Priced, pricing: Pricing): number | null {
+  // An agent bills one way or the other, never both. Kiro reports token counts alongside the
+  // credits it actually charges, so pricing its model as well would double the row.
+  if (row.credits > 0) {
+    const rate = pricing.credits[row.agent]
+    return rate ? row.credits * rate.usdPerCredit : null
+  }
+
+  if (row.model) {
+    const rate = pricing.models[row.model]
+    if (rate) {
+      // inputTokens is the whole context sent, cache reads included, and those bill at a
+      // tenth of this rate — so a cache-heavy turn estimates high. Only turns whose CLI
+      // reported no cost of its own reach here, which today is never claude's.
+      return (row.inputTokens / 1_000_000) * rate.inputPerMTok +
+        (row.outputTokens / 1_000_000) * rate.outputPerMTok
+    }
+  }
+
+  return null
+}
+
+// pricing defaults to empty, so an unconfigured user must never see a ~USD column of dashes —
+// the column exists only once there's at least one rate to estimate from
+export function isPricingConfigured(pricing: Pricing): boolean {
+  return Object.keys(pricing.models).length > 0 || Object.keys(pricing.credits).length > 0
+}
+
+export interface ModelUsage {
+  agent: AgentId
+  model: string | null
+  inputTokens: number
+  outputTokens: number
+  costUsd: number
+  credits: number
+}
+
+// Summed per model, never priced once on the aggregate: a session that ran half its turns on
+// an expensive model and half on a cheap one must not be priced as though it used either one
+// throughout — that's the whole reason `model` lives on the turn instead of the binding.
+export function estimateAgentUsd(agent: AgentId, rows: ModelUsage[], pricing: Pricing): number | null {
+  const mine = rows.filter((r) => r.agent === agent)
+  // An agent bills one way or the other. Kiro charges credits and reports token counts beside
+  // them for information; codex and opencode report only tokens. Deciding per agent rather than
+  // per row is what keeps a kiro turn that charged no credits from reading as unpriceable, and
+  // a codex turn with real tokens and no model from reading as free.
+  const billsInCredits = mine.some((r) => r.credits > 0)
+
+  let total = 0
+  for (const row of mine) {
+    if (row.costUsd > 0) {
+      total += row.costUsd
+      continue
+    }
+
+    if (billsInCredits) {
+      if (row.credits === 0) continue
+      const rate = pricing.credits[agent]
+      if (!rate) return null
+      total += row.credits * rate.usdPerCredit
+      continue
+    }
+
+    if (row.inputTokens === 0 && row.outputTokens === 0) continue
+    const est = estimateUsd(
+      { agent, model: row.model, inputTokens: row.inputTokens, outputTokens: row.outputTokens, credits: row.credits },
+      pricing,
+    )
+    if (est === null) return null
+    total += est
+  }
+  return total
+}

package/src/store/db.ts

@@ -0,0 +1,78 @@
+import { Database } from 'bun:sqlite'
+import { dirname } from '../paths'
+
+const MIGRATIONS: string[] = [
+  `CREATE TABLE session (
+     id TEXT PRIMARY KEY, slug TEXT NOT NULL UNIQUE, goal TEXT NOT NULL,
+     cwd TEXT NOT NULL, lead TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'active',
+     created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL,
+     updated_seq INTEGER NOT NULL DEFAULT 0);
+   CREATE TABLE binding (
+     session_id TEXT NOT NULL, agent TEXT NOT NULL, foreign_id TEXT,
+     model TEXT, effort TEXT NOT NULL, permission TEXT NOT NULL,
+     status TEXT NOT NULL, turns INTEGER NOT NULL DEFAULT 0,
+     cost_usd REAL NOT NULL DEFAULT 0, credits REAL NOT NULL DEFAULT 0, last_seen INTEGER,
+     PRIMARY KEY (session_id, agent));
+   CREATE TABLE turn (
+     id TEXT PRIMARY KEY, session_id TEXT NOT NULL, agent TEXT NOT NULL,
+     prompt TEXT NOT NULL, final TEXT NOT NULL, cost_usd REAL NOT NULL DEFAULT 0,
+     credits REAL NOT NULL DEFAULT 0, input_tokens INTEGER NOT NULL DEFAULT 0,
+     output_tokens INTEGER NOT NULL DEFAULT 0, kind TEXT, gate_passed INTEGER,
+     exit_code INTEGER NOT NULL, error TEXT, error_kind TEXT,
+     started_at INTEGER NOT NULL, ended_at INTEGER NOT NULL);
+   CREATE INDEX turn_kind_agent ON turn(kind, agent);
+   CREATE TABLE lock (
+     session_id TEXT PRIMARY KEY, owner TEXT NOT NULL, pid INTEGER NOT NULL,
+     acquired_at INTEGER NOT NULL);
+   CREATE TABLE event (
+     turn_id TEXT NOT NULL, seq INTEGER NOT NULL, type TEXT NOT NULL,
+     payload TEXT NOT NULL, ts INTEGER NOT NULL, PRIMARY KEY (turn_id, seq));`,
+  `ALTER TABLE turn ADD COLUMN parent_turn_id TEXT;
+   ALTER TABLE turn ADD COLUMN model TEXT;`,
+  `CREATE INDEX turn_session_id ON turn(session_id);
+   CREATE INDEX session_cwd_status ON session(cwd, status);`,
+]
+
+export function openDb(path: string): Database {
+  if (path !== ':memory:') {
+    const dir = dirname(path)
+    Bun.spawnSync(['mkdir', '-p', dir])
+  }
+  let db: Database
+  try {
+    db = new Database(path, { create: true, strict: true })
+    if (path !== ':memory:') {
+      // konvoy runs concurrently by design — a nested konvoy inside an agent, a dashboard beside
+      // a send. Set before anything that takes a lock: switching a fresh file to WAL needs an
+      // exclusive one, and without the timeout the losers of that first statement throw
+      db.exec('PRAGMA busy_timeout = 5000')
+      // the journal-mode switch needs an exclusive lock and SQLite does not run the busy handler
+      // for it, so with several openers racing the losers get SQLITE_BUSY on this one statement.
+      // The mode is persistent in the file: the winner's switch holds for everyone, a loser moves on.
+      try {
+        db.exec('PRAGMA journal_mode = WAL')
+      } catch {
+        // another opener is switching it right now
+      }
+    }
+    // one transaction for every pending migration: a loser of the open race re-reads
+    // user_version under the write lock and finds nothing left to do, and a process that dies
+    // mid-migration leaves no half-applied schema behind
+    db.exec('BEGIN IMMEDIATE')
+    try {
+      const current = (db.query('PRAGMA user_version').get() as { user_version: number }).user_version
+      for (let v = current; v < MIGRATIONS.length; v++) {
+        db.exec(MIGRATIONS[v]!)
+        db.exec(`PRAGMA user_version = ${v + 1}`)
+      }
+      db.exec('COMMIT')
+    } catch (error) {
+      db.exec('ROLLBACK')
+      throw error
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    throw new Error(`cannot open konvoy database at ${path}: ${message}`)
+  }
+  return db
+}