@shigureni/minion 0.1.0 → 0.3.0

package/lib/engine/stats/session-stats-tracker.ts

@@ -0,0 +1,125 @@
+import { z } from "zod"
+import type { MinionFileSystem } from "@lib/engine/fs/file-system"
+import { JsonFileStore } from "@lib/engine/fs/json-file-store"
+import type { SessionInfo } from "@lib/engine/gateway/sessions"
+import { isNextDay } from "@lib/engine/stats/date-window"
+
+/**
+ * Per-field `.catch()` defaults double as the schema-evolution backfill: a
+ * file written by an older version of this tracker (missing a field, e.g.
+ * `seenProjects` was added later) reads back with that field defaulted
+ * instead of the whole file being discarded.
+ */
+const schema = z.object({
+  totalSessionsSeen: z.number().catch(0),
+  maxConcurrentSessions: z.number().catch(0),
+  /** Bounded, most-recent-first log of distinct session ids, used only to dedup lifetime counting across restarts. */
+  seenSessionIds: z.array(z.string()).catch([]),
+  /** Bounded log of distinct working directories seen, used only to dedup `uniqueProjectsSeen` across restarts. */
+  seenProjects: z.array(z.string()).catch([]),
+  currentStreakDays: z.number().catch(0),
+  longestStreakDays: z.number().catch(0),
+  /** "YYYY-MM-DD" (UTC) of the last `record()` call that saw at least one active session. */
+  lastActiveDate: z.string().nullable().catch(null),
+})
+
+type SessionStatsData = z.infer<typeof schema>
+
+const EMPTY: SessionStatsData = {
+  totalSessionsSeen: 0,
+  maxConcurrentSessions: 0,
+  seenSessionIds: [],
+  seenProjects: [],
+  currentStreakDays: 0,
+  longestStreakDays: 0,
+  lastActiveDate: null,
+}
+
+// Bounds the dedup logs' size; an id/project aged out here can be recounted
+// as "new" if it somehow reappears, which only over-counts figures that are
+// already just fun numbers, not something that needs to be exact.
+const MAX_SEEN_IDS = 5000
+const MAX_SEEN_PROJECTS = 2000
+
+export type SessionStatsSummary = {
+  totalSessionsSeen: number
+  currentConcurrentSessions: number
+  maxConcurrentSessions: number
+  uniqueProjectsSeen: number
+  currentStreakDays: number
+  longestStreakDays: number
+}
+
+/**
+ * Tracks lifetime distinct session/project counts, the concurrency
+ * high-water-mark, and a day-streak of "was any session active that day",
+ * all persisted across gateway restarts.
+ */
+export class SessionStatsTracker {
+  private readonly store: JsonFileStore<SessionStatsData>
+
+  constructor(props: { fs: MinionFileSystem; path: string }) {
+    this.store = new JsonFileStore({ fs: props.fs, path: props.path, schema, defaultValue: EMPTY })
+  }
+
+  /** Records the latest active-session snapshot (at `now`) and returns the updated summary, or the write failure. */
+  record(activeSessions: Map<string, SessionInfo>, now: Date): SessionStatsSummary | Error {
+    const data = this.store.read()
+    const seenIds = new Set(data.seenSessionIds)
+    const seenProjects = new Set(data.seenProjects)
+
+    for (const info of activeSessions.values()) {
+      if (info.cwd) seenProjects.add(info.cwd)
+    }
+
+    for (const id of activeSessions.keys()) {
+      if (seenIds.has(id)) continue
+      seenIds.add(id)
+      data.totalSessionsSeen += 1
+    }
+
+    data.seenSessionIds = Array.from(seenIds).slice(-MAX_SEEN_IDS)
+    data.seenProjects = Array.from(seenProjects).slice(-MAX_SEEN_PROJECTS)
+    data.maxConcurrentSessions = Math.max(data.maxConcurrentSessions, activeSessions.size)
+
+    if (activeSessions.size > 0) {
+      this.recordActiveDay(data, now.toISOString().slice(0, 10))
+    }
+
+    const writeError = this.store.write(data)
+    if (writeError) return writeError
+
+    return {
+      totalSessionsSeen: data.totalSessionsSeen,
+      currentConcurrentSessions: activeSessions.size,
+      maxConcurrentSessions: data.maxConcurrentSessions,
+      uniqueProjectsSeen: data.seenProjects.length,
+      currentStreakDays: data.currentStreakDays,
+      longestStreakDays: data.longestStreakDays,
+    }
+  }
+
+  /** Persisted totals without recording a new sample; `currentConcurrentSessions` is always 0 here since no live sessions were read. */
+  summary(): SessionStatsSummary {
+    const data = this.store.read()
+    return {
+      totalSessionsSeen: data.totalSessionsSeen,
+      currentConcurrentSessions: 0,
+      maxConcurrentSessions: data.maxConcurrentSessions,
+      uniqueProjectsSeen: data.seenProjects.length,
+      currentStreakDays: data.currentStreakDays,
+      longestStreakDays: data.longestStreakDays,
+    }
+  }
+
+  private recordActiveDay(data: SessionStatsData, today: string): void {
+    if (data.lastActiveDate === today) return // already recorded today
+
+    data.currentStreakDays =
+      data.lastActiveDate !== null && isNextDay(data.lastActiveDate, today)
+        ? data.currentStreakDays + 1
+        : 1
+    data.longestStreakDays = Math.max(data.longestStreakDays, data.currentStreakDays)
+    data.lastActiveDate = today
+  }
+}

package/lib/engine/stats/stats-collector.ts

@@ -0,0 +1,100 @@
+import type { MinionFileSystem } from "@lib/engine/fs/file-system"
+import type { MinionProcessRunner } from "@lib/engine/process/process-runner"
+import type { MinionClock } from "@lib/engine/time/clock"
+import { readActiveSessions } from "@lib/engine/gateway/sessions"
+import type { SessionStatsSummary } from "@lib/engine/stats/session-stats-tracker"
+import { SessionStatsTracker } from "@lib/engine/stats/session-stats-tracker"
+import type { TokenUsageSummary } from "@lib/engine/stats/token-usage-tracker"
+import { TokenUsageTracker } from "@lib/engine/stats/token-usage-tracker"
+import { type StatsSnapshot, timeBucketForHour } from "@lib/engine/stats/stats-snapshot"
+import { sumRecentDays } from "@lib/engine/stats/date-window"
+
+const WEEK_DAYS = 7
+
+type Props = {
+  fs: MinionFileSystem
+  process: MinionProcessRunner
+  clock: MinionClock
+  sessionsDir: string
+  projectsDir: string
+  sessionStats: SessionStatsTracker
+  tokenUsage: TokenUsageTracker
+}
+
+/**
+ * Combines session tracking and token-usage scanning into the single
+ * `StatsSnapshot` that achievement and minion-species conditions evaluate
+ * against.
+ */
+export class MinionStatsCollector {
+  private readonly fs: MinionFileSystem
+  private readonly process: MinionProcessRunner
+  private readonly clock: MinionClock
+  private readonly sessionsDir: string
+  private readonly projectsDir: string
+  private readonly sessionStats: SessionStatsTracker
+  private readonly tokenUsage: TokenUsageTracker
+
+  constructor(props: Props) {
+    this.fs = props.fs
+    this.process = props.process
+    this.clock = props.clock
+    this.sessionsDir = props.sessionsDir
+    this.projectsDir = props.projectsDir
+    this.sessionStats = props.sessionStats
+    this.tokenUsage = props.tokenUsage
+  }
+
+  /**
+   * Reads the current sessions and re-scans token usage, recording both.
+   * Touches disk (transcripts can be large) — call this on a slow cadence,
+   * not on every animation tick. Returns an Error when persisting either
+   * tracker's state fails.
+   */
+  collect(): StatsSnapshot | Error {
+    const activeSessions = readActiveSessions({
+      fs: this.fs,
+      process: this.process,
+      clock: this.clock,
+      sessionsDir: this.sessionsDir,
+      projectsDir: this.projectsDir,
+    })
+    const sessionSummary = this.sessionStats.record(activeSessions, this.clock.now())
+    if (sessionSummary instanceof Error) return sessionSummary
+    const usage = this.tokenUsage.scan()
+    if (usage instanceof Error) return usage
+    return this.buildSnapshot(sessionSummary, usage)
+  }
+
+  /** Cheap read of the last persisted totals, without touching sessions or transcripts. */
+  peek(): StatsSnapshot {
+    const sessionSummary = this.sessionStats.summary()
+    const usage = this.tokenUsage.summary()
+    return this.buildSnapshot(sessionSummary, usage)
+  }
+
+  private buildSnapshot(
+    sessionSummary: SessionStatsSummary,
+    usage: TokenUsageSummary,
+  ): StatsSnapshot {
+    const now = this.clock.now()
+    const hour = now.getHours()
+    // UTC date, matching TokenUsageTracker's transcript-timestamp bucketing.
+    const today = now.toISOString().slice(0, 10)
+
+    return {
+      now,
+      hour,
+      timeBucket: timeBucketForHour(hour),
+      currentConcurrentSessions: sessionSummary.currentConcurrentSessions,
+      maxConcurrentSessions: sessionSummary.maxConcurrentSessions,
+      totalSessionsSeen: sessionSummary.totalSessionsSeen,
+      uniqueProjectsSeen: sessionSummary.uniqueProjectsSeen,
+      currentStreakDays: sessionSummary.currentStreakDays,
+      longestStreakDays: sessionSummary.longestStreakDays,
+      tokensTotal: usage.tokensTotal,
+      tokensToday: usage.tokensByDate[today] ?? 0,
+      tokensThisWeek: sumRecentDays(usage.tokensByDate, today, WEEK_DAYS),
+    }
+  }
+}

package/lib/engine/stats/stats-snapshot.ts

@@ -0,0 +1,31 @@
+export type TimeBucket = "lateNight" | "morning" | "day" | "evening" | "night"
+
+/**
+ * Buckets an hour-of-day (0-23, local time) into one of five time-of-day
+ * windows. Covers every hour exactly once, so `resolveSpecies` always has a
+ * fallback time-of-day species to match against.
+ */
+export function timeBucketForHour(hour: number): TimeBucket {
+  if (hour < 5) return "lateNight" // 0-4
+  if (hour < 10) return "morning" // 5-9
+  if (hour < 17) return "day" // 10-16
+  if (hour < 20) return "evening" // 17-19
+  return "night" // 20-23
+}
+
+export type StatsSnapshot = {
+  now: Date
+  hour: number
+  timeBucket: TimeBucket
+  currentConcurrentSessions: number
+  maxConcurrentSessions: number
+  totalSessionsSeen: number
+  uniqueProjectsSeen: number
+  currentStreakDays: number
+  longestStreakDays: number
+  tokensTotal: number
+  /** Tokens consumed on `now`'s (UTC) calendar date. */
+  tokensToday: number
+  /** Rolling 7-day sum ending on `now`'s (UTC) calendar date. */
+  tokensThisWeek: number
+}

package/lib/engine/stats/token-usage-tracker.ts

@@ -0,0 +1,170 @@
+import { join } from "node:path"
+import { z } from "zod"
+import { safeJsonParse } from "@lib/engine/errors"
+import type { MinionFileSystem } from "@lib/engine/fs/file-system"
+import { JsonFileStore } from "@lib/engine/fs/json-file-store"
+import type { MinionClock } from "@lib/engine/time/clock"
+
+const scanDataSchema = z.object({
+  tokensTotal: z.number().catch(0),
+  tokensByDate: z.record(z.string(), z.number()).catch({}),
+  files: z
+    .record(z.string(), z.object({ mtimeMs: z.number(), linesConsumed: z.number() }))
+    .catch({}),
+})
+
+type UsageScanData = z.infer<typeof scanDataSchema>
+
+const EMPTY: UsageScanData = { tokensTotal: 0, tokensByDate: {}, files: {} }
+
+// Bounds tokensByDate's growth; only the running total needs to survive
+// forever, per-day figures beyond ~4 months aren't queried by anything here.
+const MAX_TRACKED_DATES = 120
+
+// Backfill cutoff: an unseen transcript whose mtime is older than this is
+// skipped without being read. The rolling figures (today / this week) only
+// need the trailing 7 days, so the first-ever scan parses the active week
+// instead of the full history — lifetime totals just accrue from that point
+// on. Must stay >= the WEEK_DAYS window in stats-collector.ts. A dormant
+// file that gets appended later turns recent again and is then counted whole,
+// history included — a harmless one-time bump.
+const BACKFILL_WINDOW_MS = 7 * 24 * 60 * 60 * 1000
+
+export type TokenUsageSummary = {
+  tokensTotal: number
+  tokensByDate: Record<string, number>
+}
+
+type Props = {
+  fs: MinionFileSystem
+  clock: MinionClock
+  path: string
+  /** Claude Code's transcript root, e.g. `~/.claude/projects`. */
+  projectsDir: string
+}
+
+/**
+ * Incrementally sums token usage out of Claude Code's transcript files
+ * (`<projectsDir>/**\/*.jsonl`, one JSON object per line). Tracks each
+ * file's mtime and how many lines were already counted, so a scan only
+ * re-reads files that changed since the last scan, and only parses newly
+ * appended lines within those — this keeps repeated scans cheap even though
+ * the underlying transcripts only grow over time.
+ */
+export class TokenUsageTracker {
+  private readonly fs: MinionFileSystem
+  private readonly clock: MinionClock
+  private readonly projectsDir: string
+  private readonly store: JsonFileStore<UsageScanData>
+
+  constructor(props: Props) {
+    this.fs = props.fs
+    this.clock = props.clock
+    this.projectsDir = props.projectsDir
+    this.store = new JsonFileStore({
+      fs: props.fs,
+      path: props.path,
+      schema: scanDataSchema,
+      defaultValue: EMPTY,
+    })
+  }
+
+  /**
+   * Re-scans changed transcript files and persists the updated totals.
+   * Touches disk — call on a slow cadence. An unreadable transcript dir/file
+   * is skipped (transcripts come and go); only a failure to persist the
+   * scan state itself returns an Error.
+   */
+  scan(): TokenUsageSummary | Error {
+    const data = this.store.read()
+
+    const entries = this.fs.readdirRecursiveSync(this.projectsDir)
+    if (entries instanceof Error) return toSummary(data)
+
+    for (const relativeFile of entries.filter((f) => f.endsWith(".jsonl"))) {
+      this.scanFile(join(this.projectsDir, relativeFile), data)
+    }
+
+    pruneOldDates(data.tokensByDate)
+    const writeError = this.store.write(data)
+    if (writeError) return writeError
+    return toSummary(data)
+  }
+
+  /** Persisted totals without touching the transcript files. */
+  summary(): TokenUsageSummary {
+    return toSummary(this.store.read())
+  }
+
+  private scanFile(path: string, data: UsageScanData): void {
+    const stat = this.fs.statSync(path)
+    if (stat instanceof Error) return
+
+    const known = data.files[path]
+    if (known && known.mtimeMs === stat.mtimeMs) return // unchanged since the last scan
+    if (!known && this.clock.millis() - stat.mtimeMs > BACKFILL_WINDOW_MS) return // old history — not worth reading
+
+    const content = this.fs.readFileSync(path)
+    if (content instanceof Error) return
+
+    // Filter blank lines (notably the trailing "" from a file that ends in
+    // "\n", which every appended JSONL record does) before indexing — a raw
+    // split() index would double-count that trailing blank as "consumed" and
+    // then permanently skip the next real line once the file grows again.
+    const lines = content.split("\n").filter((line) => line.length > 0)
+    const startIndex = known?.linesConsumed ?? 0
+
+    for (let i = startIndex; i < lines.length; i++) {
+      addLineUsage(lines[i] as string, data)
+    }
+
+    data.files[path] = { mtimeMs: stat.mtimeMs, linesConsumed: lines.length }
+  }
+}
+
+// Hand-rolled shape checks, not zod: this runs per transcript line, and a
+// first-ever scan chews through hundreds of thousands of lines — zod here
+// roughly doubles the post-JSON.parse cost for no safety gain over these
+// typeof guards (a wrong-shaped line just contributes 0 tokens either way).
+function addLineUsage(line: string, data: UsageScanData): void {
+  const parsed = safeJsonParse(line)
+  if (parsed instanceof Error) return
+  if (typeof parsed !== "object" || parsed === null) return
+
+  const usage = (parsed as { message?: { usage?: Record<string, unknown> } }).message?.usage
+  if (!usage || typeof usage !== "object") return
+
+  const tokens =
+    numberOr0(usage.input_tokens) +
+    numberOr0(usage.output_tokens) +
+    numberOr0(usage.cache_creation_input_tokens) +
+    numberOr0(usage.cache_read_input_tokens)
+  if (tokens <= 0) return
+
+  data.tokensTotal += tokens
+
+  // Bucketed by the transcript line's own (UTC) timestamp date, matching the
+  // UTC day boundary MinionStatsCollector uses for "today" — the two must
+  // agree, even though it means the day rolls over at UTC midnight rather
+  // than the user's local midnight.
+  const timestamp = (parsed as { timestamp?: unknown }).timestamp
+  const date = typeof timestamp === "string" ? timestamp.slice(0, 10) : undefined
+  if (date) data.tokensByDate[date] = (data.tokensByDate[date] ?? 0) + tokens
+}
+
+function numberOr0(value: unknown): number {
+  return typeof value === "number" ? value : 0
+}
+
+function pruneOldDates(tokensByDate: Record<string, number>): void {
+  const dates = Object.keys(tokensByDate).sort()
+  const excess = dates.length - MAX_TRACKED_DATES
+  for (let i = 0; i < excess; i++) {
+    const date = dates[i]
+    if (date) delete tokensByDate[date]
+  }
+}
+
+function toSummary(data: UsageScanData): TokenUsageSummary {
+  return { tokensTotal: data.tokensTotal, tokensByDate: { ...data.tokensByDate } }
+}

package/lib/engine/time/clock.ts

@@ -0,0 +1,11 @@
+/**
+ * Time boundary. Default NodeMinionClock returns `new Date()`; MemoryMinionClock
+ * is settable and `advance(ms)`-able for deterministic session-staleness / tick tests.
+ */
+export abstract class MinionClock {
+  abstract now(): Date
+
+  millis(): number {
+    return this.now().getTime()
+  }
+}

package/lib/engine/time/memory-clock.ts

@@ -0,0 +1,26 @@
+import { MinionClock } from "@lib/engine/time/clock"
+
+type Props = {
+  start?: Date
+}
+
+export class MemoryMinionClock extends MinionClock {
+  private current: Date
+
+  constructor(props: Props = {}) {
+    super()
+    this.current = props.start ?? new Date(0)
+  }
+
+  now(): Date {
+    return new Date(this.current.getTime())
+  }
+
+  set(date: Date): void {
+    this.current = date
+  }
+
+  advance(ms: number): void {
+    this.current = new Date(this.current.getTime() + ms)
+  }
+}

package/lib/engine/time/node-clock.ts

@@ -0,0 +1,7 @@
+import { MinionClock } from "@lib/engine/time/clock"
+
+export class NodeMinionClock extends MinionClock {
+  now(): Date {
+    return new Date()
+  }
+}

package/lib/index.ts

@@ -0,0 +1,65 @@
+// Public API surface for the @shigureni/minion package.
+//
+// This is the programmable counterpart to the `minion` CLI — the CLI (cli/)
+// is a thin Hono-routed consumer of the same `Minion` facade exported here.
+//
+//   import { Minion } from "@shigureni/minion"
+//
+//   const minion = new Minion()
+//   const result = await minion.app.start() // { kind: "started", pid: 123 } など
+//   console.log(minion.app.status().app.running)
+//
+// Pass `Minion.inMemory()` to get a fully sandboxed instance (no real disk,
+// processes, or wall-clock time) for tests or ad-hoc experiments.
+
+// Facade
+export * from "@lib/minion"
+
+// Error-as-value helpers — fallible operations return `T | Error`, never throw
+export * from "@lib/engine/errors"
+
+// App — build/start/kill/status for the Swift app + gateway daemon
+export * from "@lib/engine/app/app-paths"
+export * from "@lib/engine/app/app-runner"
+export * from "@lib/engine/app/source-hash"
+
+// Config — flat string-keyed `config.json` store
+export * from "@lib/engine/config/config-store"
+
+// Gateway — session watching + pet behavior + the in-process HTTP/WS server
+export * from "@lib/engine/gateway/sessions"
+export * from "@lib/engine/gateway/pet-behavior"
+export * from "@lib/engine/gateway/gateway-routes"
+export * from "@lib/engine/gateway/gateway-server"
+export * from "@lib/engine/gateway/resolve-daemon-script"
+
+// Stats — session/token tracking feeding achievement + minion-species conditions
+export * from "@lib/engine/stats/stats-snapshot"
+export * from "@lib/engine/stats/session-stats-tracker"
+export * from "@lib/engine/stats/token-usage-tracker"
+export * from "@lib/engine/stats/stats-collector"
+
+// Collection — the minion dex: rarity-tiered species + achievements, unlocked over time
+export * from "@lib/engine/collection/moon"
+export * from "@lib/engine/collection/species"
+export * from "@lib/engine/collection/achievements"
+export * from "@lib/engine/collection/collection-store"
+export * from "@lib/engine/collection/collection-tracker"
+
+// IO boundaries (abstract + Node / Memory implementations)
+export * from "@lib/engine/fs/file-system"
+export * from "@lib/engine/fs/node-file-system"
+export * from "@lib/engine/fs/memory-file-system"
+export * from "@lib/engine/fs/json-file-store"
+
+export * from "@lib/engine/process/process-runner"
+export * from "@lib/engine/process/node-process-runner"
+export * from "@lib/engine/process/memory-process-runner"
+
+export * from "@lib/engine/time/clock"
+export * from "@lib/engine/time/node-clock"
+export * from "@lib/engine/time/memory-clock"
+
+export * from "@lib/engine/random/random-source"
+export * from "@lib/engine/random/node-random-source"
+export * from "@lib/engine/random/memory-random-source"