@g3nomaly/g3n-mods 0.1.7 → 0.1.8

package/mods/agent-adventure/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/mods/agent-adventure/hooks/register.tsx

@@ -0,0 +1,465 @@
+// packages/g3n-mods/mods/agent-adventure/hooks/register.tsx
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Hero, Run, UnitView, World } from '../types'
+import { CLASSES, CLASS_IDS, REGIONS, SKILLS } from './content'
+import { agentRequest, chooseRoute, christen, defaultRoute, hash, hpShare, join, learn, leave, newWorld, partyIds, step, toView } from './engine'
+import type { Ask } from './engine'
+import { RANK_SCALE, SPRITE_COLUMNS, SPRITE_ROWS, eliteTint, spriteSvg } from './sprite'
+
+const PANE = 'agent-adventure'
+const TITLE = 'Agent Adventure'
+/** The tool agents may call to name their hero, set its motto or say how they feel about another hero. */
+const TOOL = 'hero'
+const TOOL_NAME = `mcp__agent-adventure__${TOOL}`
+
+const world = atom({ plugin: 'agent-adventure', key: 'world' } as const, null)
+
+/** Milliseconds per game tick: one action of a small fight. */
+const TICK_MS = 1000
+/** With nobody working, the tavern moves only every this many ticks. */
+const TAVERN_EVERY = 4
+const DEFAULT_MODEL = 'haiku'
+const MODEL_TIMEOUT_MS = 15_000
+
+/** Store keys: one per hero, the run in progress, and the counters. */
+const HERO_PREFIX = 'hero:'
+const RUN_KEY = 'run'
+const META_KEY = 'meta'
+
+/** Prop the mods viewer adds to every pane it draws; the Claude Code extension draws on the `vscode` surface too, without it. */
+const VIEWER_PROP = 'g3nViewer'
+
+/** Glyph of each stop in the run's path, for surfaces without the mod's view. */
+const STOP_GLYPHS = { fight: '⚔', elite: '★', fork: '⑂', camp: '⛺', boss: '☠' } as const
+
+/**
+ * Tells whether the mods viewer asked for this drawing, rather than the Claude Code extension on the same surface.
+ *
+ * @param props - The `Pane` props of the `ui.render` argument.
+ * @returns `true` when the viewer's prop is set.
+ */
+function isViewer(props: object): boolean {
+  return (props as Readonly<Record<string, unknown>>)[VIEWER_PROP] === true
+}
+
+/** JSON last written per store key, so a tick writes only what changed. */
+const saved = new Map<string, string>()
+
+/**
+ * Writes to the store each hero, the run and the counters that changed since the last write.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param w - The world after a change.
+ */
+async function persist($: EngineInterface, w: World): Promise<void> {
+  const writes: Array<[string, unknown]> = []
+  for (const hero of w.heroes) writes.push([`${HERO_PREFIX}${hero.id}`, hero])
+  writes.push([RUN_KEY, w.run], [META_KEY, { runs: w.runs, threat: Math.round(w.threat * 1000) / 1000, isCalm: w.isCalm }])
+  for (const [key, value] of writes) {
+    const json = JSON.stringify(value)
+    if (saved.get(key) === json) continue
+    saved.set(key, json)
+    await $.store.set(key, value).catch(() => saved.delete(key))
+  }
+}
+
+/**
+ * Reads the guild, the run and the counters back from the store into a fresh world.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @returns The world as the last session left it, or an empty one.
+ */
+async function load($: EngineInterface): Promise<World> {
+  const keys = await $.store.keys().catch(() => [] as string[])
+  const heroes: Hero[] = []
+  for (const key of keys.filter(one => one.startsWith(HERO_PREFIX))) {
+    const value = await $.store.get(key)
+    if (isHero(value)) {
+      heroes.push(value)
+      saved.set(key, JSON.stringify(value))
+    }
+  }
+  const run = await $.store.get(RUN_KEY)
+  const meta = await $.store.get(META_KEY)
+  const counters = typeof meta === 'object' && meta !== null ? (meta as { runs?: unknown; threat?: unknown; isCalm?: unknown }) : {}
+  const now = await $.clock.now()
+  const w = newWorld(
+    heroes.sort((a, b) => a.createdAt - b.createdAt),
+    isRun(run) ? run : null,
+    hash(String(now)),
+    typeof counters.runs === 'number' ? counters.runs : 0,
+    typeof counters.threat === 'number' ? counters.threat : 1,
+  )
+  w.isCalm = counters.isCalm === true
+  return w
+}
+
+/** Tells whether a stored value is a hero this version can play. */
+function isHero(value: unknown): value is Hero {
+  if (typeof value !== 'object' || value === null) return false
+  const hero = value as Partial<Hero>
+  return typeof hero.id === 'string' && typeof hero.name === 'string' && CLASS_IDS.some(cls => cls === hero.cls)
+    && typeof hero.level === 'number' && Array.isArray(hero.skills) && typeof hero.record === 'object'
+}
+
+/** Tells whether a stored value is a run this version can continue. */
+function isRun(value: unknown): value is Run {
+  if (typeof value !== 'object' || value === null) return false
+  const run = value as Partial<Run>
+  return typeof run.region === 'string' && run.region in REGIONS && Array.isArray(run.path) && typeof run.at === 'number'
+}
+
+/**
+ * Applies a rule to the world and settles what follows: the store writes and the decisions it asks for.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param model - Model that makes the game's decisions, or `undefined` for the game's own picks.
+ * @param rule - Pure rule from `engine.ts`; returns the next world and its asks.
+ */
+async function change($: EngineInterface, model: string | undefined, rule: (w: World) => { world: World; asks: Ask[] }): Promise<void> {
+  let asks: Ask[] = []
+  const after = await update($, world, current => {
+    if (current === null) return current
+    const outcome = rule(current)
+    asks = outcome.asks
+    return outcome.world
+  })
+  if (after === null) return
+  await persist($, after)
+  for (const one of asks) $.clock.after(0, () => void decide($, model, one))
+}
+
+/**
+ * Asks the model for one JSON answer, or `undefined` when it gives none in time.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param model - Model alias or id.
+ * @param system - What the model is and the JSON it answers with.
+ * @param prompt - The decision at hand.
+ */
+async function askModel($: EngineInterface, model: string, system: string, prompt: string): Promise<Record<string, unknown> | undefined> {
+  const result = await $.model.complete({ model, system, prompt, maxTokens: 200, timeoutMs: MODEL_TIMEOUT_MS }).catch(() => undefined)
+  if (result === undefined || !result.isAnswered) return undefined
+  const json = /\{[\s\S]*\}/.exec(result.text)?.[0]
+  if (json === undefined) return undefined
+  try {
+    const value: unknown = JSON.parse(json)
+    return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+const GAME = 'You make one small decision in a cozy fantasy idle game that shows AI coding agents as a party of heroes. '
+  + 'It is purely cosmetic. Answer with JSON only, no prose, no code fence.'
+
+/**
+ * @brief Makes a decision the game asked for: the model's pick when a model is set and answers, else the game's own.
+ * Never blocks the game: a fork goes on with its default after `FORK_WAIT` ticks whatever happens here.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param model - Model that makes the decision, or `undefined` for the game's own pick.
+ * @param one - The decision, see `Ask`.
+ */
+async function decide($: EngineInterface, model: string | undefined, one: Ask): Promise<void> {
+  const w = await read($, world)
+  if (w === null) return
+
+  if (one.kind === 'christen') {
+    const counts = CLASS_IDS.map(cls => `${cls} ×${w.heroes.filter(hero => !hero.isRecruit && hero.cls === cls).length}`).join(', ')
+    const hero = w.heroes.find(h => h.id === one.heroId)
+    const answer = model === undefined || hero === undefined ? undefined : await askModel($, model, GAME
+      + ' Sign up a new hero: {"name": "...", "class": "...", "motto": "..."}. The name is one or two words, at most 16'
+      + ` letters, fantasy flavoured, and may nod to the kind of agent it plays. The class is one of ${CLASS_IDS.join(', ')}.`
+      + ' The motto is at most 50 characters, light and friendly.',
+      `This hero turns up for "${hero.calling}" agents${hero.calling === 'main' ? ' (the main assistant)' : ''}. `
+      + `The guild has: ${counts}. Prefer a class the guild lacks. Names taken: ${w.heroes.map(h => h.name).join(', ') || 'none'}.`)
+    await change($, model, current => ({ world: christen(current, one.heroId, answer === undefined ? undefined : { ...answer, cls: answer.class }), asks: [] }))
+    return
+  }
+
+  if (one.kind === 'skill') {
+    const hero = w.heroes.find(h => h.id === one.heroId)
+    const offered = hero?.choice?.map(id => SKILLS[id])
+    if (hero === undefined || offered === undefined || offered.some(skill => skill === undefined)) return
+    const known = hero.skills.map(id => SKILLS[id]?.name ?? id)
+    const answer = model === undefined ? undefined : await askModel($, model, GAME
+      + ' A hero picks one of two skills: {"pick": 1 or 2, "why": "..."}. "why" is at most 60 characters, said by the hero.',
+      `${hero.name}, a level ${hero.level} ${CLASSES[hero.cls].name} (${CLASSES[hero.cls].role}), knows: ${known.join(', ') || 'only its basic attack'}.`
+      + `${known.length >= 3 ? ` Learning one replaces its oldest skill, ${known[0]}.` : ''}`
+      + ` 1) ${offered[0]?.name}: ${offered[0]?.blurb}. 2) ${offered[1]?.name}: ${offered[1]?.blurb}.`)
+    const pick = answer?.pick === 2 || answer?.pick === '2' ? 1 : 0
+    await change($, model, current => ({ world: learn(current, one.heroId, pick, typeof answer?.why === 'string' ? answer.why : undefined), asks: [] }))
+    return
+  }
+
+  if (model === undefined || w.run === null || w.scene.kind !== 'fork') return
+  const run = w.run
+  const party = partyIds(w).map(id => w.heroes.find(hero => hero.id === id)).filter((hero): hero is Hero => hero !== undefined)
+  const answer = await askModel($, model, GAME
+    + ' The party picks a route: {"route": "safe" or "danger", "why": "..."}. "why" is at most 60 characters, said by one hero.',
+    `In the ${REGIONS[run.region].name}, run ${run.number}, the path forks. Safe: a normal fight and a potion. `
+    + 'Dangerous: an elite fight with double XP and a relic. If the whole party falls, everyone loses 5 levels. '
+    + `Party: ${party.map(hero => `${hero.name} (level ${hero.level} ${CLASSES[hero.cls].name}, ${Math.round(100 * hpShare(w, hero.id))}% HP)`).join(', ')}. `
+    + `Potions: ${run.potions}. The cautious pick would be "${defaultRoute(w)}".`)
+  const route = answer?.route === 'danger' || answer?.route === 'safe' ? answer.route : undefined
+  if (route === undefined) return
+  await change($, model, current => ({ world: chooseRoute(current, one.forkId, route, typeof answer?.why === 'string' ? answer.why : undefined), asks: [] }))
+}
+
+/**
+ * Carries out an action the mod's view sent: `calm` toggles calmer animations.
+ *
+ * @param $ - Engine handle the action came through.
+ * @param value - The action as the view sent it, JSON of `{ name, arg }`.
+ */
+async function act($: EngineInterface, value: string): Promise<void> {
+  let action: { name?: unknown }
+  try {
+    action = JSON.parse(value) as { name?: unknown }
+  } catch {
+    return
+  }
+  if (action.name !== 'calm') return
+  const after = await update($, world, w => (w === null ? w : { ...w, isCalm: !w.isCalm }))
+  if (after !== null) await persist($, after)
+}
+
+let idleTicks = 0
+let isTicking = false
+
+/**
+ * Advances the game one tick. With nobody working, the tavern moves only every `TAVERN_EVERY` ticks.
+ *
+ * @param $ - Engine handle the clock callback received.
+ * @param model - Model that makes the game's decisions, or `undefined` for the game's own picks.
+ */
+async function tick($: EngineInterface, model: string | undefined): Promise<void> {
+  if (isTicking) return
+  const current = await read($, world)
+  if (current === null) return
+  const isIdle = current.scene.kind === 'tavern' && current.bindings.length === 0
+  idleTicks = isIdle ? idleTicks + 1 : 0
+  if (isIdle && idleTicks % TAVERN_EVERY !== 0) return
+  isTicking = true
+  try {
+    await change($, model, step)
+  } finally {
+    isTicking = false
+  }
+}
+
+/**
+ * Puts an agent's hero in the party. Joining twice is harmless, so a subagent may arrive by `turn.start` and by
+ * `SubagentStart` alike.
+ *
+ * @param $ - Engine handle the hook received, see `EngineInterface`.
+ * @param model - Model that christens a new recruit, or `undefined` for the game's own picks.
+ * @param agent - `main`, or the subagent's id.
+ * @param calling - `main`, or the subagent's type.
+ */
+async function arrive($: EngineInterface, model: string | undefined, agent: string, calling: string): Promise<void> {
+  const now = await $.clock.now()
+  await change($, model, w => join(w, agent, calling, now))
+}
+
+/** Fills `share` of a text bar `cells` wide. */
+function bar(share: number, cells: number): [string, string] {
+  const filled = Math.round(Math.max(0, Math.min(1, share)) * cells)
+  return ['█'.repeat(filled), '░'.repeat(cells - filled)]
+}
+
+/** HP bar color by how full it is. */
+function hpColor(share: number): string {
+  return share > 0.5 ? '#3fa66b' : share > 0.25 ? '#e0a030' : '#e05a4f'
+}
+
+/**
+ * Registers the adventure: its pane and command, the agents' lifecycle hooks that fill the party, the game's tick,
+ * and the tool agents may call for their own hero.
+ *
+ * @param on - Hook registration function the engine passes in.
+ * @param options - Plugin options: `showInClaudeCode` opens the pane in the chat at session start; `model` makes the
+ *   game's small decisions, `off` for the game's own picks.
+ */
+export const register: Register = (on, options) => {
+  const model = typeof options.model !== 'string' || options.model.trim() === '' ? DEFAULT_MODEL
+    : options.model.trim().toLowerCase() === 'off' ? undefined : options.model.trim()
+
+  on('session.start', async ($, e, next) => {
+    await $.command.register({ name: 'agent-adventure', description: 'Watch your agents adventure as a party of heroes' })
+    await $.tool.register({
+      name: TOOL,
+      description: 'Optional and purely cosmetic: your hero in Agent Adventure, a spectator game the user watches while '
+        + 'agents work. Never needed for any task, and it changes nothing outside the game. Set your hero\'s `name` '
+        + '(2 to 16 letters), its `motto` (at most 60 characters), or a `feeling` toward another hero by name, from -2 '
+        + '(rival) to 2 (friend). Call it with no input to see your hero.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', maxLength: 16 },
+          motto: { type: 'string', maxLength: 60 },
+          feeling: {
+            type: 'object',
+            properties: { toward: { type: 'string' }, value: { type: 'integer', minimum: -2, maximum: 2 } },
+            required: ['toward', 'value'],
+          },
+        },
+      },
+      isDeferred: true,
+    }).catch(() => undefined)
+
+    // A hot reload keeps the session's world; a new session reads the guild back from the store.
+    if ((await read($, world)) === null) {
+      const loaded = await load($)
+      await update($, world, current => current ?? loaded)
+    }
+    const w = await read($, world)
+    if (w !== null) {
+      for (const hero of w.heroes) {
+        if (hero.isRecruit) $.clock.after(0, () => void decide($, undefined, { kind: 'christen', heroId: hero.id }))
+        else if (hero.choice !== undefined) $.clock.after(0, () => void decide($, model, { kind: 'skill', heroId: hero.id }))
+      }
+    }
+    $.clock.every(TICK_MS, () => void tick($, model))
+    if (options.showInClaudeCode === true) void $.ui.open({ id: PANE, title: TITLE })
+    return next(e)
+  })
+
+  on('command.run', { command: 'agent-adventure' }, async $ => {
+    await $.ui.open({ id: PANE, title: TITLE })
+    return { text: 'Agent Adventure is open. Each running agent fights as a hero; with none running, they rest in the tavern.' }
+  })
+
+  // Engines before 2.1.300 send `turn.start` without `agentId`: there a subagent arrives by `SubagentStart` alone.
+  on('turn.start', async ($, e, next) => {
+    const result = await next(e)
+    const agentId = (e as { agentId?: string }).agentId
+    if (agentId === undefined) await arrive($, model, 'main', 'main')
+    else {
+      const info = (await $.agent.list().catch(() => [])).find(one => one.id === agentId)
+      await arrive($, model, agentId, info?.type ?? 'agent')
+    }
+    return result
+  }).catch(($, e, next) => next(e))
+
+  on('classic.SubagentStart', async ($, e, next) => {
+    await arrive($, model, e.agent_id, e.agent_type)
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  on('classic.SubagentStop', async ($, e, next) => {
+    await change($, model, w => ({ world: leave(w, e.agent_id), asks: [] }))
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  on('turn.complete', async ($, e, next) => {
+    const result = await next(e)
+    await change($, model, w => ({ world: leave(w, e.agentId ?? 'main'), asks: [] }))
+    return result
+  }).catch(($, e, next) => next(e))
+
+  on('tool.call', { tool: TOOL_NAME }, async ($, e) => {
+    const input = e as unknown as { agentId?: string; name?: unknown; motto?: unknown; feeling?: unknown }
+    let text = 'The game is not running in this session.'
+    await change($, model, w => {
+      const answer = agentRequest(w, input.agentId ?? 'main', input)
+      text = answer.text
+      return { world: answer.world, asks: [] }
+    })
+    return { result: text }
+  })
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    const w = await read($, world)
+    if (w === null) return <Text dimColor>The guild is opening its doors…</Text>
+    const data = toView(w)
+
+    // The viewer draws the game with the mod's own view: hand it the data.
+    if (e.surface === 'vscode' && isViewer(e.props)) {
+      const { Input } = $.ui.resolve(e)
+      return (
+        <Box key="g3n-view:agent-adventure">
+          <Text>{JSON.stringify(data)}</Text>
+          <Input key="g3n-act:agent-adventure" onSubmit={value => act($, value)} />
+        </Box>
+      )
+    }
+
+    // Elsewhere, the engine's elements: the scene, the path, both sides with their HP, and the last lines of the log.
+    // Sprites are SVG everywhere but the terminal.
+    const isTerminal = e.surface === 'terminal'
+    const isTavern = data.scene === 'tavern'
+
+    const sprite = (u: UnitView) => {
+      if (isTerminal) return ''
+      const { Svg } = $.ui.resolve(e)
+      const pixel = Math.round(3 * RANK_SCALE[u.rank])
+      const tint = eliteTint(u.rank)
+      const markup = spriteSvg(u.look, { flip: false, pixel, isDown: u.isDown, ...(tint === undefined ? {} : { tint }) })
+      return <Svg source={markup} alt={u.name} width={SPRITE_COLUMNS * pixel} height={SPRITE_ROWS * pixel} />
+    }
+
+    const unitRow = (u: UnitView) => {
+      const share = u.maxHp > 0 ? u.hp / u.maxHp : 0
+      const [full, empty] = bar(share, 10)
+      const isRecruit = u.look === 'recruit'
+      return (
+        <Box key={`unit:${u.id}`} flexDirection="row" columnGap={1} alignItems="center">
+          {sprite(u)}
+          <Box flexDirection="column">
+            <Text bold={u.rank === 'boss'} dimColor={u.isDown} wrap="truncate-end">
+              {u.name}<Text dimColor> {isRecruit ? u.title : `Lv ${u.level}${u.title === '' ? '' : ` ${u.title}`}`}</Text>
+            </Text>
+            {isRecruit ? '' : (
+              <Text>
+                <Text color={hpColor(share)}>{full}</Text><Text color="#3a3f4b">{empty}</Text>
+                <Text dimColor> {u.isDown ? 'down' : `${u.hp}/${u.maxHp}`}{u.tags.length > 0 ? ` · ${u.tags.join(', ')}` : ''}</Text>
+              </Text>
+            )}
+          </Box>
+        </Box>
+      )
+    }
+
+    const path = data.stops.map((stop, i) => (
+      <Text key={`stop:${i}`} color={stop.state === 'here' ? '#f2c14e' : undefined} dimColor={stop.state === 'done'}>{STOP_GLYPHS[stop.kind]}</Text>
+    ))
+
+    const loot = [
+      data.potions > 0 ? `🧪 ${data.potions}` : '',
+      ...data.relics.map(relic => relic.icon),
+    ].filter(Boolean).join(' ')
+
+    return (
+      <Box flexDirection="column" gap={1}>
+        <Box flexDirection="row" justifyContent="space-between">
+          <Text bold>{data.caption}</Text>
+          <Text dimColor>{isTavern ? `${data.roster.length} heroes · ${data.trophies} trophies` : `Run ${data.runNumber} · threat ${data.threat}%`}</Text>
+        </Box>
+        {!isTavern && data.stops.length > 0 && (
+          <Box flexDirection="row" columnGap={1}>
+            {path}
+            {loot === '' ? '' : <Text dimColor>  {loot}</Text>}
+          </Box>
+        )}
+        <Box flexDirection="row" columnGap={4} flexWrap="wrap">
+          <Box flexDirection="column" rowGap={isTerminal ? 0 : 0.5}>
+            {data.heroes.length === 0 ? <Text dimColor>No heroes yet.</Text> : data.heroes.map(unitRow)}
+          </Box>
+          {data.enemies.length > 0 && <Box flexDirection="column" rowGap={isTerminal ? 0 : 0.5}>{data.enemies.map(unitRow)}</Box>}
+        </Box>
+        <Box flexDirection="column">
+          {data.log.slice(-4).map(line => (
+            <Text key={`log:${line.id}`} dimColor={line.tone === 'info'} color={line.tone === 'good' ? '#7cc47f' : line.tone === 'bad' ? '#e06c6c' : line.tone === 'loot' ? '#e5b567' : line.tone === 'level' ? '#b48ead' : undefined} wrap="truncate-end">
+              {line.text}
+            </Text>
+          ))}
+        </Box>
+      </Box>
+    )
+  })
+}