@onmars/lunar-core 0.1.0

package/src/lib/session-tracker.ts

@@ -0,0 +1,222 @@
+/**
+ * Session Tracker — Accumulates usage metrics per session.
+ *
+ * Fed by AgentEvent 'done' events from the Router. Tracks:
+ * - Cumulative token counts (input, output, cache read, cache write)
+ * - Message count and turn count
+ * - Session start time and duration
+ * - Last known model and context usage
+ * - Cost estimate (via model-catalog pricing)
+ *
+ * All data comes from the stream-json output that Claude Code CLI
+ * already provides — no internal APIs or OAuth tokens needed.
+ */
+
+import type { AgentUsage } from '../types/agent'
+import { calculateCost, getContextWindowSize, getModelDisplayName } from './model-catalog'
+
+export interface SessionUsage {
+  /** Total input tokens across all queries */
+  inputTokens: number
+  /** Total output tokens across all queries */
+  outputTokens: number
+  /** Total cache read tokens */
+  cacheReadTokens: number
+  /** Total cache write tokens */
+  cacheWriteTokens: number
+  /** Number of agent queries completed */
+  queryCount: number
+  /** Number of user messages processed */
+  messageCount: number
+  /** Last known model ID */
+  model?: string
+  /** Context tokens from the last API call (actual context window usage) */
+  lastContextTokens: number
+  /** Session start timestamp (ms) */
+  startedAt: number
+  /** Total API duration across all queries (ms) */
+  totalApiDurationMs: number
+}
+
+export interface SessionStatus {
+  /** Session key */
+  sessionKey: string
+  /** Usage data */
+  usage: SessionUsage
+  /** Human-readable model name */
+  modelDisplayName: string
+  /** Context window max for current model */
+  contextWindowSize: number
+  /** Context usage percentage (0-100) */
+  contextUsedPercent: number
+  /** Estimated cost in USD */
+  estimatedCostUsd: number
+  /** Session age in human-readable format */
+  sessionAge: string
+  /** Session age in ms */
+  sessionAgeMs: number
+}
+
+/**
+ * Tracks usage metrics per session. In-memory — resets on restart.
+ * Designed to be lightweight: one Map, no async, no external deps.
+ */
+export class SessionTracker {
+  private sessions = new Map<string, SessionUsage>()
+
+  /**
+   * Record a completed agent query for a session.
+   * Called by Router when it receives an AgentEvent of type 'done'.
+   */
+  recordQuery(sessionKey: string, usage: AgentUsage): void {
+    let session = this.sessions.get(sessionKey)
+    if (!session) {
+      session = {
+        inputTokens: 0,
+        outputTokens: 0,
+        cacheReadTokens: 0,
+        cacheWriteTokens: 0,
+        queryCount: 0,
+        messageCount: 0,
+        model: undefined,
+        lastContextTokens: 0,
+        startedAt: Date.now(),
+        totalApiDurationMs: 0,
+      }
+      this.sessions.set(sessionKey, session)
+    }
+
+    session.inputTokens += usage.inputTokens
+    session.outputTokens += usage.outputTokens
+    session.cacheReadTokens += usage.cacheReadTokens ?? 0
+    session.cacheWriteTokens += usage.cacheWriteTokens ?? 0
+    session.queryCount += 1
+    // contextTokens = last API call's real context window usage
+    // Falls back to input + cache if not provided
+    session.lastContextTokens =
+      usage.contextTokens ??
+      usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0)
+    session.totalApiDurationMs += usage.durationMs
+
+    if (usage.model) {
+      session.model = usage.model
+    }
+  }
+
+  /**
+   * Record that a user message was processed (called per incoming message).
+   */
+  recordMessage(sessionKey: string): void {
+    const session = this.sessions.get(sessionKey)
+    if (session) {
+      session.messageCount += 1
+    }
+  }
+
+  /**
+   * Get full status for a session.
+   */
+  getStatus(sessionKey: string): SessionStatus | null {
+    const usage = this.sessions.get(sessionKey)
+    if (!usage) return null
+
+    const model = usage.model ?? 'unknown'
+    const contextWindowSize = getContextWindowSize(model)
+
+    // Context percentage from last API call's actual context window usage
+    const contextUsedPercent =
+      contextWindowSize > 0 ? Math.min(100, (usage.lastContextTokens / contextWindowSize) * 100) : 0
+
+    const estimatedCostUsd = calculateCost(model, {
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      cacheReadTokens: usage.cacheReadTokens,
+      cacheWriteTokens: usage.cacheWriteTokens,
+    })
+
+    const ageMs = Date.now() - usage.startedAt
+
+    return {
+      sessionKey,
+      usage,
+      modelDisplayName: getModelDisplayName(model),
+      contextWindowSize,
+      contextUsedPercent,
+      estimatedCostUsd,
+      sessionAge: formatDuration(ageMs),
+      sessionAgeMs: ageMs,
+    }
+  }
+
+  /**
+   * Get raw usage for a session.
+   */
+  getUsage(sessionKey: string): SessionUsage | undefined {
+    return this.sessions.get(sessionKey)
+  }
+
+  /**
+   * Get all tracked sessions.
+   */
+  listSessions(): string[] {
+    return [...this.sessions.keys()]
+  }
+
+  /**
+   * Clear tracking for a session (e.g., on session close).
+   */
+  clear(sessionKey: string): void {
+    this.sessions.delete(sessionKey)
+  }
+
+  /**
+   * Clear all sessions.
+   */
+  clearAll(): void {
+    this.sessions.clear()
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────
+
+/**
+ * Format milliseconds to human-readable duration.
+ * e.g., 7_380_000 → "2h 3m"
+ */
+export function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000)
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+
+  if (hours > 0) {
+    const remainingMinutes = minutes % 60
+    return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`
+  }
+  if (minutes > 0) {
+    const remainingSeconds = seconds % 60
+    return remainingSeconds > 0 ? `${minutes}m ${remainingSeconds}s` : `${minutes}m`
+  }
+  return `${seconds}s`
+}
+
+/**
+ * Format token count with K/M suffixes.
+ * e.g., 12450 → "12.4K", 1500000 → "1.5M", 850 → "850"
+ */
+export function formatTokens(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`
+  if (tokens >= 10_000) return `${(tokens / 1_000).toFixed(0)}K`
+  if (tokens >= 1_000) return `${(tokens / 1_000).toFixed(1)}K`
+  return String(tokens)
+}
+
+/**
+ * Build a progress bar string.
+ * e.g., buildProgressBar(42, 10) → "████░░░░░░"
+ */
+export function buildProgressBar(percent: number, width = 10): string {
+  const clamped = Math.max(0, Math.min(100, percent))
+  const filled = Math.round((clamped / 100) * width)
+  const empty = width - filled
+  return '█'.repeat(filled) + '░'.repeat(empty)
+}

package/src/lib/session.ts

@@ -0,0 +1,158 @@
+import { Database } from 'bun:sqlite'
+import { existsSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { log } from './logger'
+
+export interface Session {
+  /** Channel + chat composite key */
+  key: string
+  /** Agent session ID (for resumption) */
+  agentSessionId: string
+  /** Last activity timestamp */
+  lastActive: number
+  /** Optional metadata */
+  metadata?: string
+}
+
+export class SessionStore {
+  private db: Database
+
+  constructor(dbPath: string) {
+    // Ensure directory exists
+    const dir = dirname(dbPath)
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+    }
+
+    this.db = new Database(dbPath, { create: true })
+    this.db.exec('PRAGMA journal_mode = WAL')
+    this.db.exec('PRAGMA busy_timeout = 5000')
+    this.migrate()
+    log.debug({ path: dbPath }, 'Session store initialized')
+  }
+
+  private migrate(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        key TEXT PRIMARY KEY,
+        agent_session_id TEXT NOT NULL,
+        last_active INTEGER NOT NULL DEFAULT (unixepoch()),
+        metadata TEXT
+      );
+
+      CREATE TABLE IF NOT EXISTS jobs (
+        id TEXT PRIMARY KEY,
+        name TEXT,
+        schedule TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        enabled INTEGER NOT NULL DEFAULT 1,
+        last_run INTEGER,
+        next_run INTEGER,
+        created_at INTEGER NOT NULL DEFAULT (unixepoch())
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_sessions_active ON sessions(last_active);
+      CREATE INDEX IF NOT EXISTS idx_jobs_next ON jobs(next_run) WHERE enabled = 1;
+    `)
+  }
+
+  /** Get or create a session for a channel/chat key */
+  get(key: string): Session | null {
+    const row = this.db
+      .query('SELECT key, agent_session_id, last_active, metadata FROM sessions WHERE key = ?')
+      .get(key) as {
+      key: string
+      agent_session_id: string
+      last_active: number
+      metadata: string | null
+    } | null
+
+    if (!row) return null
+    return {
+      key: row.key,
+      agentSessionId: row.agent_session_id,
+      lastActive: row.last_active,
+      metadata: row.metadata ?? undefined,
+    }
+  }
+
+  /** Upsert a session */
+  set(key: string, agentSessionId: string, metadata?: string): void {
+    this.db
+      .query(
+        `INSERT INTO sessions (key, agent_session_id, last_active, metadata)
+         VALUES (?, ?, unixepoch(), ?)
+         ON CONFLICT(key) DO UPDATE SET
+           agent_session_id = excluded.agent_session_id,
+           last_active = unixepoch(),
+           metadata = excluded.metadata`,
+      )
+      .run(key, agentSessionId, metadata ?? null)
+  }
+
+  /** Touch session (update last_active) */
+  touch(key: string): void {
+    this.db.query('UPDATE sessions SET last_active = unixepoch() WHERE key = ?').run(key)
+  }
+
+  /** Delete a session */
+  delete(key: string): void {
+    this.db.query('DELETE FROM sessions WHERE key = ?').run(key)
+  }
+
+  /** List all sessions, optionally filtered by recency */
+  list(maxAgeSeconds?: number): Session[] {
+    let query = 'SELECT key, agent_session_id, last_active, metadata FROM sessions'
+    const params: number[] = []
+
+    if (maxAgeSeconds) {
+      query += ' WHERE last_active > unixepoch() - ?'
+      params.push(maxAgeSeconds)
+    }
+
+    query += ' ORDER BY last_active DESC'
+
+    const rows = this.db.query(query).all(...params) as Array<{
+      key: string
+      agent_session_id: string
+      last_active: number
+      metadata: string | null
+    }>
+
+    return rows.map((row) => ({
+      key: row.key,
+      agentSessionId: row.agent_session_id,
+      lastActive: row.last_active,
+      metadata: row.metadata ?? undefined,
+    }))
+  }
+
+  /** Update only metadata for an existing session (or create placeholder if none exists) */
+  updateMetadata(key: string, metadata: string): void {
+    this.db
+      .query(
+        `INSERT INTO sessions (key, agent_session_id, last_active, metadata)
+         VALUES (?, '', unixepoch(), ?)
+         ON CONFLICT(key) DO UPDATE SET
+           metadata = excluded.metadata,
+           last_active = unixepoch()`,
+      )
+      .run(key, metadata)
+  }
+
+  /** Get parsed metadata for a session */
+  getMetadata(key: string): Record<string, unknown> | null {
+    const session = this.get(key)
+    if (!session?.metadata) return null
+    try {
+      return JSON.parse(session.metadata) as Record<string, unknown>
+    } catch {
+      return null
+    }
+  }
+
+  /** Close the database */
+  close(): void {
+    this.db.close()
+  }
+}

package/src/lib/skill-loader.ts

@@ -0,0 +1,166 @@
+/**
+ * SkillLoader — Discovers and indexes skills from the workspace filesystem.
+ *
+ * Skills are directories containing a SKILL.md file with YAML frontmatter.
+ * The loader scans configured paths, extracts metadata, and builds a
+ * compact manifest for injection into the agent's system prompt.
+ *
+ * Design: filesystem IS the database. No SQLite, no cache invalidation.
+ * Skills are scanned once at startup and cached in memory.
+ */
+
+import { readdir } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { log } from './logger'
+
+export interface SkillMeta {
+  name: string
+  description: string
+  path: string
+}
+
+export class SkillLoader {
+  private skills: SkillMeta[] = []
+
+  public get size(): number {
+    return this.skills.length
+  }
+
+  public getSkills(): SkillMeta[] {
+    return [...this.skills]
+  }
+
+  public getManifest(allowlist?: string[]): string {
+    const skills = allowlist ? this.skills.filter((s) => allowlist.includes(s.name)) : this.skills
+
+    if (skills.length === 0) return ''
+
+    let manifest = '## Skills\n\nAvailable in your workspace. Read the SKILL.md before using.\n\n'
+
+    for (const skill of skills) {
+      // Find relative path to workspace if possible
+      let displayPath = skill.path
+      const workspaceIndex = skill.path.indexOf('/workspace/')
+      if (workspaceIndex !== -1) {
+        displayPath = skill.path.slice(workspaceIndex + 11)
+      } else {
+        const skillsIndex = skill.path.indexOf('skills/')
+        if (skillsIndex !== -1) {
+          displayPath = skill.path.slice(skillsIndex)
+        }
+      }
+
+      manifest += `- **${skill.name}** — ${skill.description} → \`${displayPath}\`\n`
+    }
+
+    manifest += '\nRead the relevant SKILL.md before executing specialized tasks.\n'
+
+    return manifest
+  }
+
+  public async scan(dirs: string[]): Promise<void> {
+    const foundSkills: SkillMeta[] = []
+
+    for (const dir of dirs) {
+      try {
+        const entries = await readdir(dir, { withFileTypes: true })
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            const skillPath = join(dir, entry.name, 'SKILL.md')
+            const file = Bun.file(skillPath)
+            if (await file.exists()) {
+              const content = await file.text()
+              const meta = this.parseFrontmatter(content, skillPath)
+              if (meta) {
+                foundSkills.push(meta)
+              } else {
+                log.warn(
+                  { path: skillPath },
+                  'Skipped SKILL.md due to missing or invalid frontmatter',
+                )
+              }
+            }
+          }
+        }
+      } catch (err: any) {
+        if (err.code !== 'ENOENT') {
+          log.warn({ err: err.message, dir }, 'Failed to scan directory for skills')
+        }
+      }
+    }
+
+    // Sort by name for deterministic output
+    foundSkills.sort((a, b) => a.name.localeCompare(b.name))
+    this.skills = foundSkills
+  }
+
+  private parseFrontmatter(content: string, filePath: string): SkillMeta | null {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+    if (!match) return null
+
+    const yaml = match[1]
+    const lines = yaml.split(/\r?\n/)
+    let name = ''
+    let description = ''
+
+    let inMultilineDesc = false
+    let currentDesc = ''
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      if (!line.trim() && !inMultilineDesc) continue
+
+      if (!inMultilineDesc && line.includes(':')) {
+        const colonIndex = line.indexOf(':')
+        const key = line.slice(0, colonIndex).trim()
+        const value = line.slice(colonIndex + 1).trim()
+
+        if (key === 'name') {
+          name = this.stripQuotes(value)
+        } else if (key === 'description') {
+          if (
+            value === '' ||
+            value.startsWith('"') ||
+            (value.startsWith("'") && !value.endsWith('"') && !value.endsWith("'"))
+          ) {
+            inMultilineDesc = true
+            currentDesc = this.stripQuotes(value)
+          } else {
+            description = this.stripQuotes(value)
+          }
+        }
+      } else if (inMultilineDesc) {
+        if (line.includes(':') && !line.startsWith(' ')) {
+          inMultilineDesc = false
+          description = this.stripQuotes(currentDesc)
+          i-- // Re-process this line
+        } else {
+          currentDesc += (currentDesc ? ' ' : '') + line.trim()
+          if (currentDesc.endsWith('"') || currentDesc.endsWith("'")) {
+            inMultilineDesc = false
+            description = this.stripQuotes(currentDesc)
+          }
+        }
+      }
+    }
+
+    if (inMultilineDesc && !description) {
+      description = this.stripQuotes(currentDesc)
+    }
+
+    if (!name || !description) return null
+
+    return { name, description, path: resolve(filePath) }
+  }
+
+  private stripQuotes(val: string): string {
+    const result = val.trim()
+    if (result.startsWith('"') && result.endsWith('"')) {
+      return result.slice(1, -1)
+    }
+    if (result.startsWith("'") && result.endsWith("'")) {
+      return result.slice(1, -1)
+    }
+    return result
+  }
+}

package/src/lib/usage-api.ts

@@ -0,0 +1,145 @@
+/**
+ * Usage API — Fetch account-level usage/quota from Anthropic.
+ *
+ * Reads the OAuth token from Claude Code's credentials file
+ * (~/.claude/.credentials.json) and calls the usage endpoint.
+ *
+ * Returns 5-hour and 7-day rolling window usage vs limits.
+ * This is the same data that Claude Code's /usage command shows.
+ *
+ * NOTE: This directly calls Anthropic's API with the stored OAuth token.
+ * It's a pragmatic solution — same auth that Claude Code uses internally.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+import { log } from './logger'
+
+const USAGE_API_URL = 'https://api.anthropic.com/api/oauth/usage'
+
+export interface UsageWindow {
+  /** Tokens used in this window */
+  used: number
+  /** Token limit for this window */
+  limit: number
+  /** Percentage used (0-100) */
+  percent: number
+  /** When the window resets (ISO string, if available) */
+  resetsAt?: string
+}
+
+export interface AccountUsage {
+  /** 5-hour rolling window */
+  fiveHour: UsageWindow | null
+  /** 7-day rolling window */
+  sevenDay: UsageWindow | null
+  /** When the data was fetched */
+  fetchedAt: number
+}
+
+/**
+ * Read the OAuth token from Claude Code's credentials file.
+ *
+ * Looks in:
+ * 1. CLAUDE_CODE_OAUTH_TOKEN env var
+ * 2. ~/.claude/.credentials.json
+ */
+export function readOAuthToken(): string | null {
+  // 1. Environment variable (takes precedence)
+  const envToken = process.env.CLAUDE_CODE_OAUTH_TOKEN
+  if (envToken) return envToken
+
+  // 2. Credentials file
+  const credPath = resolve(homedir(), '.claude', '.credentials.json')
+  if (!existsSync(credPath)) {
+    log.debug({ path: credPath }, 'Claude credentials file not found')
+    return null
+  }
+
+  try {
+    const raw = readFileSync(credPath, 'utf-8')
+    const creds = JSON.parse(raw)
+
+    // The file typically has { accessToken, refreshToken, expiresAt }
+    const token = creds.claudeAiOauth?.accessToken ?? creds.accessToken ?? creds.access_token
+    if (!token) {
+      log.debug('No access token found in credentials file')
+      return null
+    }
+
+    return token
+  } catch (err) {
+    log.warn({ err }, 'Failed to read Claude credentials')
+    return null
+  }
+}
+
+/**
+ * Parse a raw usage window object into a typed UsageWindow.
+ * Returns null if input is not a valid object.
+ */
+export function parseWindow(raw: unknown): UsageWindow | null {
+  if (!raw || typeof raw !== 'object') return null
+  const w = raw as Record<string, unknown>
+  const used = typeof w.used === 'number' ? w.used : 0
+  const limit = typeof w.limit === 'number' ? w.limit : 0
+  return {
+    used,
+    limit,
+    percent: limit > 0 ? Math.round((used / limit) * 100) : 0,
+    resetsAt: typeof w.resetsAt === 'string' ? w.resetsAt : undefined,
+  }
+}
+
+/**
+ * Fetch account usage from Anthropic's OAuth usage API.
+ *
+ * Returns null if:
+ * - No OAuth token found
+ * - API call fails
+ * - Not an OAuth/subscription user (API key users don't have this)
+ */
+export async function fetchAccountUsage(): Promise<AccountUsage | null> {
+  const token = readOAuthToken()
+  if (!token) return null
+
+  try {
+    const response = await fetch(USAGE_API_URL, {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${token}`,
+        'anthropic-beta': 'oauth-2025-04-20',
+        'User-Agent': 'lunar/1.0',
+      },
+    })
+
+    if (!response.ok) {
+      log.debug(
+        { status: response.status, statusText: response.statusText },
+        'Usage API returned non-OK',
+      )
+      return null
+    }
+
+    const data = (await response.json()) as Record<string, unknown>
+
+    return {
+      fiveHour: parseWindow(data.five_hour),
+      sevenDay: parseWindow(data.seven_day),
+      fetchedAt: Date.now(),
+    }
+  } catch (err) {
+    log.debug({ err }, 'Failed to fetch account usage')
+    return null
+  }
+}
+
+/**
+ * Check if OAuth credentials are available.
+ */
+export function hasOAuthCredentials(): boolean {
+  return readOAuthToken() !== null
+}