@shigureni/minion 0.1.0 → 0.3.0

package/lib/engine/gateway/gateway-server.ts

@@ -0,0 +1,126 @@
+import type { Hono } from "hono"
+import { toError } from "@lib/engine/errors"
+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 type { MinionRandomSource } from "@lib/engine/random/random-source"
+import { buildGatewayRoutes } from "@lib/engine/gateway/gateway-routes"
+import { PetBehaviorEngine } from "@lib/engine/gateway/pet-behavior"
+import { readActiveSessions } from "@lib/engine/gateway/sessions"
+
+const DEFAULT_PORT = 4756
+const DEFAULT_TICK_MS = 250
+
+type Props = {
+  fs: MinionFileSystem
+  process: MinionProcessRunner
+  clock: MinionClock
+  random: MinionRandomSource
+  sessionsDir: string
+  projectsDir: string
+  port?: number
+  tickMs?: number
+}
+
+export type MinionGatewayHandle = {
+  port: number
+  stop(): void
+}
+
+/**
+ * In-process HTTP + WebSocket server that watches the sessions directory and
+ * broadcasts each pet's animation state. `.routes` (the `/sessions` JSON
+ * endpoint) is a plain Hono app testable via `.request()`; `.start()` wraps
+ * it plus the `/ws` upgrade in a real `Bun.serve` — like the IO boundaries
+ * this class composes, that call is a genuine runtime dependency rather than
+ * something behind an interface, so pass `port: 0` to bind an ephemeral port
+ * when a test does need a live server.
+ */
+export class MinionGatewayServer {
+  readonly routes: Hono
+
+  private readonly fs: MinionFileSystem
+  private readonly process: MinionProcessRunner
+  private readonly clock: MinionClock
+  private readonly sessionsDir: string
+  private readonly projectsDir: string
+  private readonly port: number
+  private readonly tickMs: number
+  private readonly engine: PetBehaviorEngine
+
+  constructor(props: Props) {
+    this.fs = props.fs
+    this.process = props.process
+    this.clock = props.clock
+    this.sessionsDir = props.sessionsDir
+    this.projectsDir = props.projectsDir
+    this.port = props.port ?? DEFAULT_PORT
+    this.tickMs = props.tickMs ?? DEFAULT_TICK_MS
+    this.engine = new PetBehaviorEngine({ random: props.random })
+    this.routes = buildGatewayRoutes(this.engine)
+  }
+
+  /** Binds the real server. Returns an Error (instead of throwing) when the port is taken or binding fails. */
+  start(): MinionGatewayHandle | Error {
+    const engine = this.engine
+    const routes = this.routes
+    const clients = new Set<{ send: (data: string) => void }>()
+
+    const broadcast = (): void => {
+      const payload = JSON.stringify({ sessions: engine.snapshot() })
+      for (const ws of clients) ws.send(payload)
+    }
+
+    const tick = (): void => {
+      const now = this.clock.millis()
+      const activeSessions = readActiveSessions({
+        fs: this.fs,
+        process: this.process,
+        clock: this.clock,
+        sessionsDir: this.sessionsDir,
+        projectsDir: this.projectsDir,
+      })
+      if (engine.tick(now, activeSessions)) broadcast()
+    }
+
+    const interval = setInterval(tick, this.tickMs)
+    tick()
+
+    try {
+      const server = Bun.serve({
+        port: this.port,
+        fetch(req, srv) {
+          const url = new URL(req.url)
+          if (url.pathname === "/ws") {
+            if (srv.upgrade(req)) return undefined
+            return new Response("upgrade failed", { status: 400 })
+          }
+          return routes.fetch(req)
+        },
+        websocket: {
+          open(ws) {
+            clients.add(ws)
+            ws.send(JSON.stringify({ sessions: engine.snapshot() }))
+          },
+          close(ws) {
+            clients.delete(ws)
+          },
+          message() {
+            // クライアントからのメッセージは使わない
+          },
+        },
+      })
+
+      return {
+        port: server.port ?? this.port,
+        stop: () => {
+          clearInterval(interval)
+          void server.stop(true)
+        },
+      }
+    } catch (thrown) {
+      clearInterval(interval)
+      return toError(thrown)
+    }
+  }
+}

package/lib/engine/gateway/pet-behavior.ts

@@ -0,0 +1,164 @@
+import type { MinionRandomSource } from "@lib/engine/random/random-source"
+import type { SessionInfo } from "@lib/engine/gateway/sessions"
+
+export const IDLE_CLIP = 0
+
+// Swift側 PetView.clips と同じ並び順・重み(合計100)。座標や速度はSwiftが持つ
+// clip定義とスクリーン形状に依存するため、ここでは「どの行動を・どれだけ続けるか」だけを決める。
+export const ACTIONS: { durationMs: [number, number]; weight: number }[] = [
+  { weight: 14, durationMs: [3000, 6000] }, // 0 待機
+  { weight: 10, durationMs: [3000, 6000] }, // 1 歩く
+  { weight: 28, durationMs: [4000, 7000] }, // 2 走る
+  { weight: 3, durationMs: [1000, 2000] }, // 3 ジャンプ1
+  { weight: 3, durationMs: [1000, 2000] }, // 4 ジャンプ2
+  { weight: 3, durationMs: [1000, 2000] }, // 5 ジャンプ3
+  { weight: 3, durationMs: [1000, 2000] }, // 6 ジャンプ4
+  { weight: 8, durationMs: [4000, 7000] }, // 7 座る1
+  { weight: 8, durationMs: [4000, 7000] }, // 8 座る2
+  { weight: 8, durationMs: [4000, 7000] }, // 9 座る3
+  { weight: 8, durationMs: [4000, 7000] }, // 10 座る4
+  { weight: 2, durationMs: [2000, 3000] }, // 11 食べる1
+  { weight: 2, durationMs: [2000, 3000] }, // 12 食べる2
+]
+
+// 稼働していないセッション用の「静かな」行動だけの部分集合(clipIndexはACTIONS/Swiftの
+// 並びを指す)。移動・ジャンプ・食事は含めず、待機と座り姿勢をゆっくり切り替える。
+export const SLEEPING_ACTIONS: {
+  clipIndex: number
+  durationMs: [number, number]
+  weight: number
+}[] = [
+  { clipIndex: 0, weight: 40, durationMs: [6000, 12000] }, // 待機
+  { clipIndex: 7, weight: 15, durationMs: [6000, 12000] }, // 座る1
+  { clipIndex: 8, weight: 15, durationMs: [6000, 12000] }, // 座る2
+  { clipIndex: 9, weight: 15, durationMs: [6000, 12000] }, // 座る3
+  { clipIndex: 10, weight: 15, durationMs: [6000, 12000] }, // 座る4
+]
+
+export type PetAction = { clipIndex: number; durationMs: number }
+
+export function pickAction(random: MinionRandomSource): PetAction {
+  const roll = random.next() * 100
+  let cumulative = 0
+  let chosen = IDLE_CLIP
+
+  for (let i = 0; i < ACTIONS.length; i++) {
+    const action = ACTIONS[i]
+    if (!action) continue
+    cumulative += action.weight
+    if (roll < cumulative) {
+      chosen = i
+      break
+    }
+  }
+
+  const chosenAction = ACTIONS[chosen]
+  const [min, max] = chosenAction?.durationMs ?? [0, 0]
+  return { clipIndex: chosen, durationMs: min + random.next() * (max - min) }
+}
+
+export function pickSleepingAction(random: MinionRandomSource): PetAction {
+  const roll = random.next() * 100
+  let cumulative = 0
+  let chosen = SLEEPING_ACTIONS[0]
+
+  for (const action of SLEEPING_ACTIONS) {
+    cumulative += action.weight
+    if (roll < cumulative) {
+      chosen = action
+      break
+    }
+  }
+
+  const [min, max] = chosen?.durationMs ?? [0, 0]
+  return {
+    clipIndex: chosen?.clipIndex ?? IDLE_CLIP,
+    durationMs: min + random.next() * (max - min),
+  }
+}
+
+export type PetBehavior = {
+  running: boolean
+  name: string
+  clipIndex: number
+  actionEndsAt: number
+}
+
+export type PetSnapshotEntry = {
+  id: string
+  state: "running" | "sleeping"
+  clipIndex: number
+  name: string
+}
+
+/**
+ * Pure per-session state machine: given the latest active-session snapshot and
+ * the current time, decides each pet's animation clip and how long it plays.
+ * Holds no IO — safe to tick from a test with a fake clock and random source.
+ */
+export class PetBehaviorEngine {
+  private readonly random: MinionRandomSource
+  private readonly behaviors = new Map<string, PetBehavior>()
+
+  constructor(props: { random: MinionRandomSource }) {
+    this.random = props.random
+  }
+
+  /** Advances state given `now` and the latest active sessions. Returns whether anything changed. */
+  tick(now: number, activeSessions: Map<string, SessionInfo>): boolean {
+    let dirty = false
+
+    for (const id of this.behaviors.keys()) {
+      if (!activeSessions.has(id)) {
+        this.behaviors.delete(id)
+        dirty = true
+      }
+    }
+
+    for (const [id, info] of activeSessions) {
+      const existing = this.behaviors.get(id)
+
+      if (!existing) {
+        const action = info.running ? pickAction(this.random) : pickSleepingAction(this.random)
+        this.behaviors.set(id, {
+          running: info.running,
+          name: info.name,
+          clipIndex: action.clipIndex,
+          actionEndsAt: now + action.durationMs,
+        })
+        dirty = true
+        continue
+      }
+
+      if (existing.name !== info.name) {
+        existing.name = info.name
+        dirty = true
+      }
+
+      if (existing.running !== info.running) {
+        existing.running = info.running
+        // 稼働が止まったときも静かな姿勢を選び直す(走りの途中コマで固まらないように)。
+        const action = info.running ? pickAction(this.random) : pickSleepingAction(this.random)
+        existing.clipIndex = action.clipIndex
+        existing.actionEndsAt = now + action.durationMs
+        dirty = true
+      } else if (now >= existing.actionEndsAt) {
+        const action = info.running ? pickAction(this.random) : pickSleepingAction(this.random)
+        if (action.clipIndex !== existing.clipIndex) dirty = true
+        existing.clipIndex = action.clipIndex
+        existing.actionEndsAt = now + action.durationMs
+      }
+    }
+
+    return dirty
+  }
+
+  snapshot(): PetSnapshotEntry[] {
+    return Array.from(this.behaviors.entries()).map(([id, b]) => ({
+      id,
+      state: b.running ? "running" : "sleeping",
+      clipIndex: b.clipIndex,
+      name: b.name,
+    }))
+  }
+}

package/lib/engine/gateway/resolve-daemon-script.ts

@@ -0,0 +1,7 @@
+import { fileURLToPath } from "node:url"
+
+/** Absolute path to the standalone gateway daemon entry, for spawning as a detached process. */
+export function resolveGatewayDaemonScript(): string {
+  // URL.pathname はパスに空白や非ASCII文字があるとパーセントエンコードされたまま壊れる
+  return fileURLToPath(new URL("gateway-daemon.ts", import.meta.url))
+}

package/lib/engine/gateway/sessions.ts

@@ -0,0 +1,127 @@
+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 type { MinionProcessRunner } from "@lib/engine/process/process-runner"
+import type { MinionClock } from "@lib/engine/time/clock"
+
+const DEFAULT_STALE_MS = 8 * 60 * 1000
+const DEFAULT_TRANSCRIPT_ACTIVE_MS = 2 * 60 * 1000
+
+// One `~/.claude/sessions/*.json` file. `sessionId` and `pid` are required to
+// identify the session at all; everything else degrades gracefully (`.catch()`)
+// since these files are written by Claude Code, not by us. `status` stays
+// `undefined` when absent — claude-desktop sessions never write it, and
+// "no status" (fall back to transcript activity) must stay distinguishable
+// from "status: idle".
+const sessionFileSchema = z.looseObject({
+  sessionId: z.string(),
+  pid: z.number(),
+  status: z.string().optional().catch(undefined),
+  name: z.string().catch(""),
+  cwd: z.string().optional().catch(undefined),
+  updatedAt: z.number().optional().catch(undefined),
+  statusUpdatedAt: z.number().optional().catch(undefined),
+  startedAt: z.number().optional().catch(undefined),
+})
+
+export type SessionInfo = {
+  running: boolean
+  name: string
+  /** The session's working directory, when Claude Code recorded one — used to count distinct projects worked in. */
+  cwd?: string
+}
+
+type Props = {
+  fs: MinionFileSystem
+  process: MinionProcessRunner
+  clock: MinionClock
+  sessionsDir: string
+  /** Claude Code's transcript root (`~/.claude/projects`) — the busy signal for sessions whose file has no `status`. */
+  projectsDir: string
+  /** How long a dead session's last-known status is trusted before it's dropped. Defaults to 8 minutes. */
+  staleMs?: number
+  /** How recent a transcript write counts as "busy" for statusless sessions. Defaults to 2 minutes. */
+  transcriptActiveMs?: number
+}
+
+/**
+ * Reads every `~/.claude/sessions/*.json` file and resolves each into a
+ * running/idle verdict. updatedAt only changes when status flips, so a
+ * session that's been busy for a long time can't be judged by elapsed time
+ * alone — while its process is alive we trust `status` directly, and only
+ * fall back to the `staleMs` grace period once the process has died.
+ *
+ * claude-desktop sessions write their file once at startup and never include
+ * `status` at all, so for those the transcript file's mtime is the busy
+ * signal instead: the transcript is appended to continuously while Claude
+ * works, so a write within `transcriptActiveMs` means the session is running.
+ *
+ * An unreadable directory reads as "no sessions", and a file that's missing,
+ * mid-write, or shaped wrong is skipped — session files churn constantly and
+ * none of that is an error worth surfacing.
+ */
+export function readActiveSessions(props: Props): Map<string, SessionInfo> {
+  const staleMs = props.staleMs ?? DEFAULT_STALE_MS
+
+  const entries = props.fs.readdirSync(props.sessionsDir)
+  if (entries instanceof Error) return new Map()
+
+  const now = props.clock.millis()
+  const result = new Map<string, SessionInfo>()
+
+  for (const file of entries.filter((f) => f.endsWith(".json"))) {
+    const content = props.fs.readFileSync(join(props.sessionsDir, file))
+    if (content instanceof Error) continue
+
+    const json = safeJsonParse(content)
+    if (json instanceof Error) continue
+
+    const parsed = sessionFileSchema.safeParse(json)
+    if (!parsed.success) continue
+    const session = parsed.data
+
+    const alive = props.process.isAlive(session.pid)
+    if (!alive) {
+      const updatedAt = session.updatedAt ?? session.statusUpdatedAt ?? session.startedAt
+      if (updatedAt === undefined || now - updatedAt > staleMs) continue
+    }
+
+    const busy =
+      session.status !== undefined
+        ? session.status === "busy"
+        : isTranscriptActive({
+            fs: props.fs,
+            projectsDir: props.projectsDir,
+            cwd: session.cwd,
+            sessionId: session.sessionId,
+            now,
+            activeMs: props.transcriptActiveMs ?? DEFAULT_TRANSCRIPT_ACTIVE_MS,
+          })
+
+    result.set(session.sessionId, {
+      running: alive && busy,
+      name: session.name,
+      cwd: session.cwd,
+    })
+  }
+
+  return result
+}
+
+// Claude Code stores each transcript at
+// `<projectsDir>/<cwd with "/" and "." flattened to "-">/<sessionId>.jsonl`.
+function isTranscriptActive(props: {
+  fs: MinionFileSystem
+  projectsDir: string
+  cwd: string | undefined
+  sessionId: string
+  now: number
+  activeMs: number
+}): boolean {
+  if (props.cwd === undefined) return false
+  const projectDir = props.cwd.replace(/[/\\.:]/g, "-")
+  const stat = props.fs.statSync(join(props.projectsDir, projectDir, `${props.sessionId}.jsonl`))
+  if (stat instanceof Error) return false
+  return props.now - stat.mtimeMs <= props.activeMs
+}

package/lib/engine/process/memory-process-runner.ts

@@ -0,0 +1,67 @@
+import { MinionProcessRunner, type RunOptions } from "@lib/engine/process/process-runner"
+
+export type MemoryProcessCall =
+  | { kind: "runInherit"; command: string[]; options: RunOptions }
+  | { kind: "spawnDetached"; command: string[]; options: RunOptions }
+  | { kind: "kill"; pid: number; signal: string }
+
+export type MemoryRunInheritHandler = (
+  command: string[],
+) => number | Error | Promise<number | Error>
+export type MemorySpawnDetachedHandler = (command: string[]) => number | Error
+export type MemoryIsAliveHandler = (pid: number) => boolean
+
+/** Records every call and lets tests stub exit codes, spawned pids, and liveness. */
+export class MemoryMinionProcessRunner extends MinionProcessRunner {
+  readonly calls: MemoryProcessCall[] = []
+  readonly killed: { pid: number; signal: string }[] = []
+
+  private nextPid = 1000
+  private runInheritHandler: MemoryRunInheritHandler = () => 0
+  private spawnDetachedHandler: MemorySpawnDetachedHandler = () => {
+    this.nextPid += 1
+    return this.nextPid
+  }
+  private isAliveHandler: MemoryIsAliveHandler = () => false
+
+  onRunInherit(handler: MemoryRunInheritHandler): this {
+    this.runInheritHandler = handler
+    return this
+  }
+
+  onSpawnDetached(handler: MemorySpawnDetachedHandler): this {
+    this.spawnDetachedHandler = handler
+    return this
+  }
+
+  onIsAlive(handler: MemoryIsAliveHandler): this {
+    this.isAliveHandler = handler
+    return this
+  }
+
+  /** Convenience for tests that only care that a set of pids is "alive". */
+  setAlivePids(pids: Iterable<number>): this {
+    const alive = new Set(pids)
+    this.isAliveHandler = (pid) => alive.has(pid)
+    return this
+  }
+
+  async runInherit(command: string[], options: RunOptions = {}): Promise<number | Error> {
+    this.calls.push({ kind: "runInherit", command, options })
+    return await this.runInheritHandler(command)
+  }
+
+  spawnDetached(command: string[], options: RunOptions = {}): number | Error {
+    this.calls.push({ kind: "spawnDetached", command, options })
+    return this.spawnDetachedHandler(command)
+  }
+
+  kill(pid: number, signal: string = "SIGTERM"): void {
+    this.calls.push({ kind: "kill", pid, signal })
+    this.killed.push({ pid, signal })
+  }
+
+  isAlive(pid: number): boolean {
+    return this.isAliveHandler(pid)
+  }
+}

package/lib/engine/process/node-process-runner.ts

@@ -0,0 +1,51 @@
+import { toError } from "@lib/engine/errors"
+import { MinionProcessRunner, type RunOptions } from "@lib/engine/process/process-runner"
+
+export class NodeMinionProcessRunner extends MinionProcessRunner {
+  async runInherit(command: string[], options: RunOptions = {}): Promise<number | Error> {
+    try {
+      const [cmd, ...args] = command
+      const proc = Bun.spawn([cmd ?? "", ...args], {
+        cwd: options.cwd,
+        stdout: "inherit",
+        stderr: "inherit",
+      })
+      return await proc.exited
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+
+  spawnDetached(command: string[], options: RunOptions = {}): number | Error {
+    try {
+      const [cmd, ...args] = command
+      const proc = Bun.spawn([cmd ?? "", ...args], {
+        cwd: options.cwd,
+        stdout: "ignore",
+        stderr: "ignore",
+        stdin: "ignore",
+      })
+      proc.unref()
+      return proc.pid
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+
+  kill(pid: number, signal: string = "SIGTERM"): void {
+    try {
+      process.kill(pid, signal)
+    } catch {
+      // already dead — nothing to do
+    }
+  }
+
+  isAlive(pid: number): boolean {
+    try {
+      process.kill(pid, 0)
+      return true
+    } catch {
+      return false
+    }
+  }
+}

package/lib/engine/process/process-runner.ts

@@ -0,0 +1,21 @@
+export type RunOptions = {
+  cwd?: string
+}
+
+/**
+ * Process boundary covering foreground builds, detached background spawns,
+ * and liveness checks. Default is NodeMinionProcessRunner (Bun.spawn);
+ * MemoryMinionProcessRunner records calls and lets tests stub responses.
+ *
+ * Fallible operations return `T | Error` (e.g. the executable doesn't exist)
+ * instead of throwing — implementations must catch their runtime's exceptions
+ * at this boundary.
+ */
+export abstract class MinionProcessRunner {
+  /** Run a command to completion, inheriting stdio. Resolves to its exit code. */
+  abstract runInherit(command: string[], options?: RunOptions): Promise<number | Error>
+  /** Spawn a detached background process (keeps running after the parent exits). Returns its pid. */
+  abstract spawnDetached(command: string[], options?: RunOptions): number | Error
+  abstract kill(pid: number, signal?: string): void
+  abstract isAlive(pid: number): boolean
+}

package/lib/engine/random/memory-random-source.ts

@@ -0,0 +1,22 @@
+import { MinionRandomSource } from "@lib/engine/random/random-source"
+
+type Props = {
+  /** Values replayed in order, then repeated from the start once exhausted. Defaults to always `0`. */
+  values?: number[]
+}
+
+export class MemoryMinionRandomSource extends MinionRandomSource {
+  private readonly values: number[]
+  private index = 0
+
+  constructor(props: Props = {}) {
+    super()
+    this.values = props.values && props.values.length > 0 ? props.values : [0]
+  }
+
+  next(): number {
+    const value = this.values[this.index % this.values.length] ?? 0
+    this.index += 1
+    return value
+  }
+}

package/lib/engine/random/node-random-source.ts

@@ -0,0 +1,7 @@
+import { MinionRandomSource } from "@lib/engine/random/random-source"
+
+export class NodeMinionRandomSource extends MinionRandomSource {
+  next(): number {
+    return Math.random()
+  }
+}

package/lib/engine/random/random-source.ts

@@ -0,0 +1,9 @@
+/**
+ * Randomness boundary used by the pet behavior picker. Default NodeMinionRandomSource
+ * wraps `Math.random()`; MemoryMinionRandomSource replays a fixed sequence of values
+ * for deterministic action-selection tests.
+ */
+export abstract class MinionRandomSource {
+  /** A pseudo-random number in [0, 1), same contract as `Math.random()`. */
+  abstract next(): number
+}

package/lib/engine/stats/date-window.ts

@@ -0,0 +1,31 @@
+const MS_PER_DAY = 24 * 60 * 60 * 1000
+
+/** Parses a "YYYY-MM-DD" string as a UTC-midnight instant. */
+function parseIsoDate(dateIso: string): number {
+  const [y, m, d] = dateIso.split("-").map(Number)
+  return Date.UTC(y ?? 1970, (m ?? 1) - 1, d ?? 1)
+}
+
+/** The `days` calendar dates ending on (and including) `todayIso`, in "YYYY-MM-DD" form, most-recent first. */
+export function recentDates(todayIso: string, days: number): string[] {
+  const base = parseIsoDate(todayIso)
+  const dates: string[] = []
+  for (let i = 0; i < days; i++) {
+    dates.push(new Date(base - i * MS_PER_DAY).toISOString().slice(0, 10))
+  }
+  return dates
+}
+
+/** Sums a date-keyed map over the `days` calendar dates ending on `todayIso` (a rolling window, e.g. "this week" = 7). */
+export function sumRecentDays(
+  byDate: Record<string, number>,
+  todayIso: string,
+  days: number,
+): number {
+  return recentDates(todayIso, days).reduce((sum, date) => sum + (byDate[date] ?? 0), 0)
+}
+
+/** Whether `nextIso` is exactly the calendar day after `previousIso`. */
+export function isNextDay(previousIso: string, nextIso: string): boolean {
+  return parseIsoDate(nextIso) - parseIsoDate(previousIso) === MS_PER_DAY
+}