ruflo-arena

1import type { Hook, Register } from 'claude-code'
2
3import { answer } from './command'
4import { readOptions } from './options'
5import { newStats, STATUS_PATH, statusText, type Stats } from './status'
6import type { ModOptions } from './options'
7
8type Dollar = Parameters<Hook<'session.start'>>[0]
9
10/** Everything one session of the mod keeps: its settings, counters and the project root. */
11type Session = { readonly opts: ModOptions; readonly stats: Stats; root?: string }
12
13async function flush($: Dollar, s: Session): Promise<void> {
14  if (s.root === undefined) return
15  try {
16    await $.fs.write(`${s.root}/${STATUS_PATH}`, statusText(s.stats, s.opts, await $.clock.now()))
17  } catch {
18    /* the status file is a courtesy */
19  }
20}
21
22/**
23 * Arena as a mod (ADR-445 pattern): `/arena-mod`, and a status file the console reads.
24 * No network, no process: only the hooks API.
25 */
26export const register: Register = (on, options) => {
27  const s: Session = { opts: readOptions(options), stats: newStats() }
28
29  on('session.start', async ($, e, next) => {
30    const result = await next(e)
31    s.root = (await $.session.root()) as string | undefined
32    s.stats.startedMs = await $.clock.now()
33    try {
34      await $.command.register({ name: 'arena-mod', description: 'Arena mod: status, strategies' })
35    } catch {
36      /* a name taken by another plugin must not stop the mod */
37    }
38    await flush($, s)
39    return result
40  })
41
42  /** `/arena-mod` (a markdown command of the plugin cannot be answered by a hook, so the mod owns this name). */
43  on('command.run', { command: 'arena-mod' }, async (_$, e) => ({ text: answer(typeof e.args === 'string' ? e.args : '', { opts: s.opts, stats: s.stats }) }))
44}
45

1import type { ModOptions } from './options'
2import type { Stats } from './status'
3
4/** `/arena-mod` is answered locally and takes no model turn. */
5export type CommandDeps = { readonly opts: ModOptions; readonly stats: Stats }
6
7const HELP = ['/arena-mod status', '/arena-mod strategies'].join('\n')
8
9export function answer(args: string, deps: CommandDeps): string {
10  const [verb = ''] = args.trim().split(/\s+/)
11
12  if (verb === '' || verb === 'help') return HELP
13
14  if (verb === 'status') {
15    return `Arena mod active · no tool is guarded`
16  }
17
18  if (verb === 'strategies') return 'Classic roster: tit-for-tat, always-cooperate, always-defect, grim, pavlov, alternate, random. Run one with /arena run --a <strategy> --b <strategy>, or /arena tournament.'
19
20  return `Unknown: ${verb}\n${HELP}`
21}
22

1import type { PluginOptions } from 'claude-code'
2
3/** The plugin's `userConfig`, validated: a bad value is the default (guard absent). */
4export type ModOptions = {
5  readonly guard: boolean
6}
7
8// BEGIN SHARED FLAG (generated by scripts/sync-mod-screen.mjs; edit plugins/ruflo-agentdb/hooks/options.ts)
9export const flag = (value: unknown, fallback: boolean) =>
10  value === true || value === 'true' || value === 'on' ? true : value === false || value === 'false' || value === 'off' ? false : fallback
11// END SHARED FLAG
12
13export function readOptions(options: PluginOptions | undefined): ModOptions {
14  const o = options ?? {}
15  return {
16    guard: flag(o.guard, false),
17  }
18}
19

1/** Counters the mod keeps for the session and writes to `.claude-flow/arena-mod/status.json` for the console. */
2export type Stats = { calls: number; blocked: number; startedMs: number }
3
4export const newStats = (): Stats => ({ calls: 0, blocked: 0, startedMs: 0 })
5
6export const STATUS_PATH = '.claude-flow/arena-mod/status.json'
7
8/** The file's text; `version` lets the console refuse a shape it does not know. */
9export function statusText(stats: Stats, mode: { guard: boolean }, nowMs: number): string {
10  return `${JSON.stringify({ version: 1, updatedMs: nowMs, mod: 'arena', guard: mode.guard, ...stats }, null, 2)}\n`
11}
12