@g3nomaly/g3n-mods 0.1.4 → 0.1.6

package/mods/custom-crab-agents/hooks/register.tsx

@@ -2,7 +2,9 @@
 import { atom, read, update } from 'claude-code'
 import type { EngineInterface, Register, RenderElement } from 'claude-code'
 
-import type { Crab, CrabSteps, PlannedItem } from '../types'
+import type { Crab, CrabSteps, CrabsViewData, PlannedItem, Role } from '../types'
+import { PALETTE, PIXEL, SPRITE_COLUMNS, SPRITE_ROWS, crabSvg, phaseOf } from './sprite'
+import type { Pose } from './sprite'
 
 /** The agents-panel mod's pane, which this mod depends on and draws its crabs into. */
 const PANEL = 'agents-panel'
@@ -13,40 +15,45 @@ const ADDON_KEY = 'addon:'
 const crabs = atom({ plugin: 'custom-crab-agents', key: 'crabs' } as const, [])
 const planned = atom({ plugin: 'custom-crab-agents', key: 'planned' } as const, [])
 const contextWindow = atom({ plugin: 'custom-crab-agents', key: 'window' } as const, 1_000_000)
+const chats = atom({ plugin: 'custom-crab-agents', key: 'chats' } as const, [])
+
+/** Pane id prefix of a subagent's chat; the viewer opens a pane whose id starts with `tab-` in a tab of its own. */
+const CHAT_PREFIX = 'tab-chat-'
+
+/** Most of a subagent's conversation entries a chat draws, newest kept. */
+const CHAT_ROWS = 300
 
 const KEEP = 30
-const PIXEL = 4
-
-/** Effort level → tier name, color and hat. */
-const TIERS: Readonly<Record<string, { name: string; color: string; hat: keyof typeof HATS }>> = {
-  low: { name: 'light', color: '#3fa66b', hat: 'cap' },
-  medium: { name: 'medium', color: '#4c8bf5', hat: 'sailor' },
-  high: { name: 'careful', color: '#e0a030', hat: 'hardhat' },
-  xhigh: { name: 'heavy', color: '#e05a4f', hat: 'beanie' },
-  max: { name: 'heavy', color: '#e05a4f', hat: 'beanie' },
+
+/** Effort level → tier name and the color of the crab's bar. */
+const TIERS: Readonly<Record<string, { name: string; color: string }>> = {
+  low: { name: 'light', color: '#3fa66b' },
+  medium: { name: 'medium', color: '#4c8bf5' },
+  high: { name: 'careful', color: '#e0a030' },
+  xhigh: { name: 'heavy', color: '#e05a4f' },
+  max: { name: 'heavy', color: '#e05a4f' },
 }
-const DEFAULT_TIER = { name: 'medium', color: '#4c8bf5', hat: 'sailor' as const }
-
-/** Sprite rows, 12 pixels wide; each letter is a palette color, `.` is empty. */
-const BODY = [
-  '...k....k...',
-  'C..b....b..C',
-  'CC.bbbbbb.CC',
-  '.CbbbbbbbbC.',
-  '..bbbbbbbb..',
-  '..bbbbbbbb..',
-  '..b.b..b.b..',
-  '.b..b..b..b.',
+const DEFAULT_TIER = { name: 'medium', color: '#4c8bf5' }
+
+/** Words in an agent's title or type that give its role, tried in order; the first match wins. */
+const ROLE_RULES: ReadonlyArray<[Role, RegExp]> = [
+  ['review', /review|audit|inspect|critic|check/i],
+  ['test', /test|\bqa\b|verif/i],
+  ['design', /design|artist|\bart\b|style|graphic|visual|\bui\b/i],
+  ['explore', /explor|research|search|scout|find/i],
+  ['plan', /plan|architect|\bspec/i],
+  ['build', /build|implement|\bcode|\bfix|refactor|general-purpose/i],
 ]
-const HATS = {
-  cap: ['...gggg.....', '..gggggg....', '..ggggggggg.'],
-  sailor: ['...wwwwww...', '..wwwwwwww..', '..uuuuuuuu..'],
-  hardhat: ['....yyyy....', '...yyyyyy...', '.yyyyyyyyyy.'],
-  beanie: ['.....t......', '...nnnnnn...', '..nnnnnnnn..'],
-} as const
-const PALETTE: Readonly<Record<string, string>> = {
-  b: '#e07a5f', C: '#c8553d', k: '#1e1e1e',
-  g: '#3fa66b', w: '#f0f0f0', u: '#4c8bf5', y: '#f2c14e', t: '#e8e8e8', n: '#7a4a2a',
+
+/** What each role is called on its crab, and the emoji it gets in the terminal. */
+const ROLES: Readonly<Record<Role, { name: string; emoji: string }>> = {
+  review: { name: 'reviewer', emoji: '🔍' },
+  test: { name: 'tester', emoji: '🔧' },
+  design: { name: 'designer', emoji: '🎩' },
+  explore: { name: 'explorer', emoji: '🧭' },
+  plan: { name: 'planner', emoji: '📜' },
+  build: { name: 'builder', emoji: '🔨' },
+  other: { name: 'helper', emoji: '' },
 }
 
 /** Price per million tokens: input, output, cache read, cache write. First match wins. */
@@ -60,6 +67,21 @@ const PRICES: ReadonlyArray<[RegExp, [number, number, number, number]]> = [
   [/haiku/, [1, 5, 0.1, 1.25]],
 ]
 
+/**
+ * Finds an agent's role from its title, then its subagent type.
+ *
+ * @param title - What the agent was started to do, e.g. `review: read mod files`.
+ * @param subagentType - Its subagent type, e.g. `Explore`.
+ * @returns The first role whose words match, or `other`.
+ */
+export function roleOf(title: string, subagentType: string): Role {
+  for (const text of [title, subagentType]) {
+    const found = ROLE_RULES.find(([, words]) => words.test(text))
+    if (found !== undefined) return found[0]
+  }
+  return 'other'
+}
+
 /**
  * Looks up the tier of an effort level, falling back to the default tier.
  *
@@ -127,28 +149,6 @@ function minutes(ms: number): string {
   return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`
 }
 
-/**
- * Draws the crab as one SVG: hat rows for the tier on top of the body; a planned crab is drawn grey.
- *
- * @param hat - Hat to draw, a key of `HATS`.
- * @param isPlanned - Whether the crab is planned work, not a running or finished subagent.
- * @returns The SVG markup as a string.
- */
-function crabSvg(hat: keyof typeof HATS, isPlanned: boolean): string {
-  const rows = [...HATS[hat], ...BODY]
-  const rects: string[] = []
-  rows.forEach((row, y) => {
-    for (let x = 0; x < row.length; x++) {
-      const color = PALETTE[row.charAt(x)]
-      if (color !== undefined) rects.push(`<rect x="${x * PIXEL}" y="${y * PIXEL}" width="${PIXEL}" height="${PIXEL}" fill="${color}"/>`)
-    }
-  })
-  const width = 12 * PIXEL
-  const height = rows.length * PIXEL
-  const filter = isPlanned ? ' opacity="0.45" style="filter:grayscale(1)"' : ''
-  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"${filter}>${rects.join('')}</svg>`
-}
-
 /**
  * Draws a progress bar as one SVG, filled to `share` of its width.
  *
@@ -350,7 +350,103 @@ async function readWindow($: EngineInterface): Promise<void> {
 }
 
 /**
- * Registers this mod's session, tool, subagent and turn hooks, and its section of the agents panel.
+ * @brief Works out what a crab's card says: its tier and role, how full its bar is, its step line and its stats.
+ *
+ * @param crab - Crab to describe, see `Crab`.
+ * @param window - The session's context window, in tokens.
+ * @param now - Current time, the end of a crab still running.
+ * @returns The card's facts.
+ */
+function factsOf(crab: Crab, window: number, now: number) {
+  const tier = tierOf(crab.effort)
+  const role = roleOf(crab.title, crab.subagentType)
+  const elapsed = crab.durationMs ?? now - crab.startedAt
+  const tokens = crab.tokens ?? 0
+  const share = crab.steps.total > 0 ? crab.steps.done / crab.steps.total : crab.status === 'running' ? 0.08 + Math.min(0.8, crab.requests / 40) : 1
+  const stepLine = crab.steps.total > 0
+    ? `${crab.steps.done}/${crab.steps.total}${crab.steps.current === undefined ? '' : ` · ${crab.steps.current}`}`
+    : crab.status === 'running' ? `step ${crab.requests}` : `${crab.requests} step${crab.requests === 1 ? '' : 's'}`
+  const stats = [
+    tokens > 0 ? `ctx ${Math.max(1, Math.round((tokens / window) * 100))}%` : '',
+    tokens > 0 ? formatTokens(tokens) : '',
+    crab.costUsd === undefined ? '' : `≈$${crab.costUsd.toFixed(2)}`,
+    minutes(elapsed),
+  ].filter(part => part.length > 0).join(' · ')
+  return { tier, role, share, stepLine, stats }
+}
+
+/**
+ * Carries out an action the crabs' view sent: `openChat` with a crab's id.
+ *
+ * @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; arg?: unknown }
+  try {
+    action = JSON.parse(value) as { name?: unknown; arg?: unknown }
+  } catch {
+    return
+  }
+  const arg = typeof action.arg === 'object' && action.arg !== null ? (action.arg as Record<string, unknown>) : {}
+  if (action.name === 'openChat' && typeof arg.id === 'string') await openChat($, arg.id)
+}
+
+/**
+ * Opens a crab's conversation as a pane of its own, which the viewer shows in a tab of its own.
+ *
+ * @param $ - Engine handle the press came through.
+ * @param crabId - `id` of the crab whose agent to show.
+ */
+async function openChat($: EngineInterface, crabId: string): Promise<void> {
+  const crab = (await read($, crabs)).find(one => one.id === crabId)
+  if (crab?.agentId === undefined) {
+    $.ui.toast('This agent has no conversation yet; try again once it has started.')
+    return
+  }
+  const agentId = crab.agentId
+  const id = `${CHAT_PREFIX}${agentId.replace(/[^A-Za-z0-9_-]/g, '')}`.slice(0, 64)
+  await update($, chats, list => [...list.filter(chat => chat.id !== id), { id, agentId, title: crab.title }])
+  await $.ui.open({ id, title: `Chat · ${crab.title}`, focus: true })
+}
+
+/**
+ * Sends a message typed in a chat to its agent, which resumes a finished one.
+ *
+ * @param $ - Engine handle the submit came through.
+ * @param agentId - Agent the chat shows.
+ * @param text - What the person typed.
+ */
+async function sendToAgent($: EngineInterface, agentId: string, text: string): Promise<void> {
+  const message = text.trim()
+  if (message === '') return
+  const sent = await $.session.send({ to: { agentId }, text: message }).catch((error: unknown) => ({ isDelivered: false as const, reason: String(error) }))
+  if (!sent.isDelivered) {
+    $.ui.toast(`Not delivered: ${sent.reason ?? 'the agent could not be reached'}`)
+    return
+  }
+  await patchCrab($, crab => crab.agentId === agentId, crab => ({ ...crab, status: 'running', durationMs: undefined }))
+  $.ui.invalidate('ui.render')
+}
+
+/**
+ * Shortens a tool call to the text its one line in a chat shows: a command, a file's name, a pattern.
+ *
+ * @param input - Arguments of the tool call.
+ * @returns The label with whitespace collapsed, at most 200 characters.
+ */
+function toolLabel(input: Record<string, unknown>): string {
+  for (const key of ['command', 'file_path', 'pattern', 'url', 'query', 'description', 'prompt']) {
+    const value = input[key]
+    if (typeof value !== 'string' || value === '') continue
+    const text = key === 'file_path' ? value.split('/').pop() ?? value : value
+    return text.replace(/\s+/g, ' ').trim().slice(0, 200)
+  }
+  return ''
+}
+
+/**
+ * Registers this mod's session, tool, subagent and turn hooks, its section of the agents panel, and the agents' chats.
  *
  * @param on - Hook registration function the engine passes in.
  */
@@ -406,10 +502,85 @@ export const register: Register = on => {
     return result
   }).catch(($, e, next) => next(e))
 
+  // Forgets a chat once its pane is closed.
+  on('ui.close', async ($, e, next) => {
+    if (e.id.startsWith(CHAT_PREFIX)) await update($, chats, list => list.filter(chat => chat.id !== e.id))
+    return next(e)
+  }).catch(($, e, next) => next(e))
+
+  // A subagent's chat: its whole conversation, each tool call on one line, and a box to message it.
+  on('ui.render', { component: 'Pane' }, async ($, e, next) => {
+    const chat = (await read($, chats)).find(one => one.id === e.requestId)
+    if (chat === undefined) return next(e)
+    const { Box, Text, Markdown } = $.ui.resolve(e)
+    const crab = (await read($, crabs)).find(one => one.agentId === chat.agentId)
+    const found = await $.session.messages({ agentId: chat.agentId })
+    const role = roleOf(chat.title, crab?.subagentType ?? '')
+    const status = crab === undefined ? '' : crab.status === 'running' ? '● running' : crab.status === 'failed' ? '✗ failed' : '✓ finished'
+
+    const header = (
+      <Box flexDirection="row" columnGap={1}>
+        <Text bold wrap="truncate-end">{chat.title}</Text>
+        <Text dimColor wrap="truncate-end">{ROLES[role].name}{crab === undefined ? '' : ` · ${modelName(crab.model)} · ${status}`}</Text>
+      </Box>
+    )
+    if ('deny' in found) return <Box flexDirection="column" gap={1}>{header}<Text dimColor>{found.deny}</Text></Box>
+
+    const rows = found.slice(-CHAT_ROWS).flatMap((message, index) => {
+      const parts = []
+      if (message.role === 'user' && message.text.trim() !== '') {
+        parts.push(
+          <Box key={`m${index}`} borderStyle="round" borderColor="#3a3f4b" backgroundColor="#24272e" paddingX={1} marginTop={1}>
+            <Text wrap="wrap">{message.text}</Text>
+          </Box>,
+        )
+      }
+      if (message.role === 'assistant' && message.text.trim() !== '') {
+        parts.push(<Box key={`m${index}`} marginTop={1}><Markdown text={message.text} /></Box>)
+      }
+      message.toolUses.forEach((use, n) => {
+        parts.push(
+          <Box key={`t${index}:${n}`} flexDirection="row" columnGap={1}>
+            <Text color={use.isError === true ? '#e06c6c' : '#7cc47f'}>⏺</Text>
+            <Text wrap="truncate-end">{use.tool} <Text dimColor>{toolLabel(use.input)}</Text></Text>
+          </Box>,
+        )
+      })
+      return parts
+    })
+
+    const working = crab?.status === 'running'
+      ? <Box marginTop={1}><Text color="#d97757">✻ Working… <Text dimColor>{crab.steps.current ?? `step ${crab.requests}`}</Text></Text></Box>
+      : ''
+
+    const input = e.surface === 'mobile'
+      ? ''
+      : (() => {
+          const { Input } = $.ui.resolve(e)
+          return (
+            <Input
+              key="send"
+              placeholder={crab?.status === 'running' ? `Message ${chat.title}… it reads it after its current step` : `Reply to ${chat.title}…`}
+              submitLabel="Send"
+              onSubmit={value => sendToAgent($, chat.agentId, value)}
+            />
+          )
+        })()
+
+    return (
+      <Box flexDirection="column">
+        {header}
+        {rows.length === 0 ? <Text dimColor>Nothing in this conversation yet.</Text> : rows}
+        {working}
+        <Box marginTop={1}>{input}</Box>
+      </Box>
+    )
+  })
+
   // Draws into the agents panel: under the panel's tree when the panel's hook lies beneath this one, or alone with an
   // `addon:` key that the panel's hook picks up when it lies above. Either way the crabs end up under the agents.
   on('ui.render', { component: 'Pane', requestId: PANEL }, async ($, e, next) => {
-    const { Box, Text } = $.ui.resolve(e)
+    const { Box, Text, Button } = $.ui.resolve(e)
     const below: RenderElement | undefined = await next(e).catch(() => undefined)
     const panel = below !== undefined && holdsKey(below, PANEL_KEY) ? below : undefined
     /** Puts the crabs' section under the panel's tree, when it was drawn beneath. */
@@ -419,6 +590,40 @@ export const register: Register = on => {
     const plan = await read($, planned)
     const window = await read($, contextWindow)
     const now = await $.clock.now()
+
+    // The viewer draws the crabs with the mod's own view: hand it the cards as data, inside the key the panel looks for.
+    if (e.surface === 'vscode') {
+      const { Input } = $.ui.resolve(e)
+      const data: CrabsViewData = {
+        crabs: list.map(crab => {
+          const facts = factsOf(crab, window, now)
+          return {
+            id: crab.id,
+            title: crab.title,
+            role: facts.role,
+            roleName: ROLES[facts.role].name,
+            color: facts.tier.color,
+            model: modelName(crab.model),
+            ...(crab.effort === undefined ? {} : { effort: crab.effort }),
+            status: crab.status,
+            stepLine: facts.stepLine,
+            stats: facts.stats,
+            share: facts.share,
+            phase: phaseOf(crab.id),
+          }
+        }),
+        planned: plan.map(item => ({ index: item.index, content: item.content, after: item.after, role: roleOf(item.content, '') })),
+      }
+      return joined(
+        <Box key={`${ADDON_KEY}crabs`}>
+          <Box key="g3n-view:custom-crab-agents">
+            <Text>{JSON.stringify(data)}</Text>
+            <Input key="g3n-act:custom-crab-agents" onSubmit={value => act($, value)} />
+          </Box>
+        </Box>,
+      )
+    }
+
     if (list.length === 0 && plan.length === 0) {
       return joined(<Box key={`${ADDON_KEY}crabs`}><Text dimColor>No subagents yet. Each one shows up here as a crab.</Text></Box>)
     }
@@ -427,14 +632,15 @@ export const register: Register = on => {
     /**
      * Draws a crab sprite: an emoji in the terminal, an SVG elsewhere.
      *
-     * @param hat - Hat to draw, a key of `HATS`.
-     * @param isPlanned - Whether the crab is planned work.
+     * @param role - Role whose hat and item to draw.
+     * @param pose - Walking while the agent runs, standing once done, grey while planned.
+     * @param id - The crab's id, which offsets its animations from its neighbours'.
      * @returns The sprite element.
      */
-    const sprite = (hat: keyof typeof HATS, isPlanned: boolean) => {
-      if (e.surface === 'terminal') return <Text color={isPlanned ? '#6b7280' : PALETTE.b}>🦀</Text>
+    const sprite = (role: Role, pose: Pose, id: string) => {
+      if (e.surface === 'terminal') return <Text color={pose === 'planned' ? '#6b7280' : PALETTE.b}>{ROLES[role].emoji}🦀</Text>
       const { Svg } = $.ui.resolve(e)
-      return <Svg source={crabSvg(hat, isPlanned)} alt="crab" width={12 * PIXEL} height={11 * PIXEL} />
+      return <Svg source={crabSvg(role, pose, phaseOf(id))} alt={`${ROLES[role].name} crab`} width={SPRITE_COLUMNS * PIXEL} height={SPRITE_ROWS * PIXEL} />
     }
     /**
      * Draws a progress bar for a crab.
@@ -460,32 +666,29 @@ export const register: Register = on => {
      * @returns The card element.
      */
     const card = (crab: Crab) => {
-      const tier = tierOf(crab.effort)
-      const elapsed = crab.durationMs ?? now - crab.startedAt
-      const tokens = crab.tokens ?? 0
-      const share = crab.steps.total > 0 ? crab.steps.done / crab.steps.total : crab.status === 'running' ? 0.08 + Math.min(0.8, crab.requests / 40) : 1
-      const stepLine = crab.steps.total > 0
-        ? `${crab.steps.done}/${crab.steps.total}${crab.steps.current === undefined ? '' : ` · ${crab.steps.current}`}`
-        : crab.status === 'running' ? `step ${crab.requests}` : `${crab.requests} step${crab.requests === 1 ? '' : 's'}`
-      const stats = [
-        tokens > 0 ? `ctx ${Math.max(1, Math.round((tokens / window) * 100))}%` : '',
-        tokens > 0 ? formatTokens(tokens) : '',
-        crab.costUsd === undefined ? '' : `≈$${crab.costUsd.toFixed(2)}`,
-        minutes(elapsed),
-      ].filter(part => part.length > 0).join(' · ')
+      const { tier, role, share, stepLine, stats } = factsOf(crab, window, now)
       const mark = crab.status === 'running' ? <Text color="#2f6b4a">●</Text>
         : crab.status === 'failed' ? <Text color="#e06c6c">✗</Text>
         : <Text color="#7cc47f">✓</Text>
+      // The whole card opens the agent's chat: a Button holds only text, so a plain one covers the card. The terminal,
+      // where a cover would hide the card, gets a line of its own instead.
+      const opener = e.surface === 'terminal'
+        ? <Button key={`chat:${crab.id}`} label="open chat" onPress={() => openChat($, crab.id)} />
+        : (
+            <Box position="absolute" top={0} left={0} right={0} bottom={0}>
+              <Button key={`chat:${crab.id}`} plain label="Open chat ↗" onPress={() => openChat($, crab.id)} />
+            </Box>
+          )
       return (
-        <Box flexDirection="row" columnGap={2} paddingY={1}>
-          {sprite(tier.hat, false)}
+        <Box key={`crab:${crab.id}`} flexDirection="row" columnGap={2} paddingY={1} paddingX={1}>
+          {sprite(role, crab.status === 'running' ? 'running' : 'idle', crab.id)}
           <Box flexDirection="column" flexGrow={1}>
             <Box flexDirection="row" justifyContent="space-between">
               <Text bold wrap="truncate-end">{crab.title}</Text>
               {mark}
             </Box>
             <Text>
-              <Text color={tier.color}>{tier.name}</Text>
+              <Text color={tier.color}>{ROLES[role].name}</Text>
               <Text dimColor> {modelName(crab.model)}{crab.effort === undefined ? '' : ` · ${crab.effort}`}</Text>
             </Text>
             <Box flexDirection="row" justifyContent="space-between">
@@ -493,7 +696,9 @@ export const register: Register = on => {
               <Text dimColor>{stats}</Text>
             </Box>
             {progress(share, tier.color)}
+            {e.surface === 'terminal' ? opener : ''}
           </Box>
+          {e.surface === 'terminal' ? '' : opener}
         </Box>
       )
     }
@@ -510,7 +715,7 @@ export const register: Register = on => {
         {plan.length > 0 && <Text dimColor>Planned · {plan.length}</Text>}
         {plan.map(item => (
           <Box flexDirection="row" columnGap={2} paddingY={1}>
-            {sprite('beanie', true)}
+            {sprite(roleOf(item.content, ''), 'planned', String(item.index))}
             <Box flexDirection="column" flexGrow={1}>
               <Box flexDirection="row" justifyContent="space-between">
                 <Text bold dimColor wrap="truncate-end">{item.index}. {item.content}</Text>

package/mods/custom-crab-agents/hooks/sprite.ts

@@ -0,0 +1,131 @@
+// packages/g3n-mods/mods/custom-crab-agents/hooks/sprite.ts
+import type { Role } from '../types'
+
+/**
+ * The crab sprite, shared by the hooks module, which draws it as an Svg on surfaces without the mod's view, and by
+ * the view in `view/view.ts`. Plain data and string building only, so both can import it.
+ */
+
+/** Size of one sprite pixel, in CSS pixels. */
+export const PIXEL = 4
+
+/**
+ * The body: Claude's mascot as the Claude Code logo draws it, 16 pixels wide. A wide body, two dark eye slits,
+ * arms out to both sides, four short legs. Each letter is a palette color, `.` is empty.
+ */
+export const BODY = [
+  '..bbbbbbbbbbbb..',
+  '..bbkbbbbbbkbb..',
+  '..bbkbbbbbbkbb..',
+  'CCbbbbbbbbbbbbCC',
+  '..bbbbbbbbbbbb..',
+  '...b.b....b.b...',
+  '...b.b....b.b...',
+]
+
+/** Each role's hat, four rows over the body, 12 pixels wide and centred on it: an inspector's deerstalker, a work helmet, a top hat, and so on. */
+export const HATS: Readonly<Record<Role, readonly string[]>> = {
+  review: ['............', '....hhhh....', '...hHhHhh...', '.hhhhhhhhhh.'],
+  test: ['.....aa.....', '...yyyyyy...', '..yyyyyyyy..', '.yyyyyyyyyy.'],
+  design: ['...tttttt...', '...tttttt...', '...vvvvvv...', '.tttttttttt.'],
+  explore: ['............', '....pppp....', '...pppppp...', '.pppppppppp.'],
+  plan: ['............', '.mmmmmmmmmmq', '...mmmmmm..q', '...mmmmmm...'],
+  build: ['............', '...gggg.....', '..gggggg....', '..ggggggggg.'],
+  other: ['............', '...wwwwww...', '..wwwwwwww..', '..uuuuuuuu..'],
+}
+
+/** What each role holds in its right arm, four pixels wide beside the body, by sprite row; the arm is on row 7. */
+export const PROPS: Readonly<Record<Role, Readonly<Record<number, string>>>> = {
+  review: { 3: '.oo.', 4: 'oLLo', 5: 'oLLo', 6: '.oo.', 7: 's...' },
+  test: { 3: '.w.w', 4: '.www', 5: '..w.', 6: '.w..', 7: 'w...' },
+  design: { 2: '...P', 3: '..P.', 4: '..f.', 5: '.s..', 6: '.s..', 7: 's...' },
+  explore: { 2: '.rrr', 3: '.rrr', 4: '.s..', 5: '.s..', 6: '.s..', 7: 'ss..' },
+  plan: { 5: 'eee.', 6: 'eEe.', 7: 'eee.' },
+  build: { 3: 'mmm.', 4: 'mmm.', 5: '.s..', 6: '.s..', 7: 's...' },
+  other: {},
+}
+
+/** Size of the whole sprite in pixels: the 16-pixel body and the 4-pixel item it holds, under a 4-row hat. */
+export const SPRITE_COLUMNS = 20
+export const SPRITE_ROWS = 11
+
+export const PALETTE: Readonly<Record<string, string>> = {
+  b: '#d97757', C: '#c8613f', k: '#1e1e1e',
+  g: '#3fa66b', w: '#f0f0f0', u: '#4c8bf5', y: '#f2c14e', a: '#fff3b0',
+  h: '#8b6b3e', H: '#c9a46a', t: '#22252b', v: '#9b59d0', p: '#d8c38f',
+  m: '#2f3542', q: '#f2c14e', o: '#c9d1d9', L: '#9fd3e6', s: '#7a4a2a',
+  P: '#4c8bf5', f: '#c9d1d9', r: '#e05a4f', e: '#efe6c8', E: '#b8a77a',
+}
+
+/** The sprite rows of the legs, below the hat and the body above them, and the second leg pose of a walking crab. */
+const LEG_ROWS = [9, 10]
+const STEP_LEGS = '..b...b..b...b..'
+
+/** The sprite cells of the eyes, as column and row, which close for a moment when the crab blinks. */
+const EYES: ReadonlyArray<[number, number]> = [[4, 5], [4, 6], [11, 5], [11, 6]]
+
+/** How a crab is drawn: walking while its agent runs, standing and blinking once done, grey while only planned. */
+export type Pose = 'running' | 'idle' | 'planned'
+
+/**
+ * Turns an id into a start offset for the crab's animations, so crabs side by side do not move in step.
+ *
+ * @param id - The crab's id, e.g. its Agent call's tool_use_id.
+ * @returns An offset in seconds, from 0 up to 4.
+ */
+export function phaseOf(id: string): number {
+  let hash = 0
+  for (let i = 0; i < id.length; i++) hash = (hash * 31 + id.charCodeAt(i)) >>> 0
+  return (hash % 4000) / 1000
+}
+
+/**
+ * Draws pixels as SVG rects, one per colored cell.
+ *
+ * @param rows - Sprite rows; each letter is a `PALETTE` color, `.` is empty.
+ * @param only - The row numbers to draw; all when absent.
+ * @returns The rects as markup.
+ */
+function pixels(rows: readonly string[], only?: readonly number[]): string {
+  const rects: string[] = []
+  rows.forEach((row, y) => {
+    if (only !== undefined && !only.includes(y)) return
+    for (let x = 0; x < row.length; x++) {
+      const color = PALETTE[row.charAt(x)]
+      if (color !== undefined) rects.push(`<rect x="${x * PIXEL}" y="${y * PIXEL}" width="${PIXEL}" height="${PIXEL}" fill="${color}"/>`)
+    }
+  })
+  return rects.join('')
+}
+
+/**
+ * @brief Draws the crab as one SVG: its role's hat over the body and the item it holds. A running crab bobs and walks,
+ * every crab but a planned one blinks now and then, and a planned crab is drawn grey and still.
+ *
+ * The motion is the SVG's own animation (SMIL), so it needs nothing from the surface drawing it.
+ *
+ * @param role - Role whose hat and item to draw.
+ * @param pose - Walking, standing or planned.
+ * @param phase - Seconds into its animations the crab starts, see `phaseOf`.
+ * @returns The SVG markup as a string.
+ */
+export function crabSvg(role: Role, pose: Pose, phase = 0): string {
+  const rows = [...HATS[role].map(row => `..${row}..`), ...BODY].map((row, y) => row + (PROPS[role][y] ?? '....'))
+  const width = SPRITE_COLUMNS * PIXEL
+  const height = SPRITE_ROWS * PIXEL
+  // crispEdges keeps the pixels sharp, with no seams between them, while the crab bobs.
+  const open = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" shape-rendering="crispEdges"`
+  if (pose === 'planned') return `${open} opacity="0.45" style="filter:grayscale(1)">${pixels(rows)}</svg>`
+
+  const begin = `begin="-${phase.toFixed(2)}s"`
+  const above = rows.map((_, y) => y).filter(y => !LEG_ROWS.includes(y))
+  const eyelids = EYES.map(([x, y]) => `<rect x="${x * PIXEL}" y="${y * PIXEL}" width="${PIXEL}" height="${PIXEL}" fill="${PALETTE.b}"/>`).join('')
+  const blink = `<g opacity="0">${eyelids}<animate attributeName="opacity" values="0;1;0" keyTimes="0;0.94;0.97" calcMode="discrete" dur="${pose === 'running' ? 3.2 : 4.6}s" repeatCount="indefinite" ${begin}/></g>`
+  if (pose === 'idle') return `${open}>${pixels(rows)}${blink}</svg>`
+
+  // Running: the body bobs half a pixel and the legs swap between two poses, as a walk.
+  const stepped = rows.map((row, y) => (LEG_ROWS.includes(y) ? STEP_LEGS + row.slice(STEP_LEGS.length) : row))
+  const swap = (from: number) => `<animate attributeName="opacity" values="${from};${1 - from}" calcMode="discrete" dur="0.5s" repeatCount="indefinite" ${begin}/>`
+  const bob = `<animateTransform attributeName="transform" type="translate" values="0 0;0 -2;0 0" dur="0.5s" repeatCount="indefinite" ${begin}/>`
+  return `${open}><g>${pixels(rows, above)}${blink}${bob}</g><g>${pixels(rows, LEG_ROWS)}${swap(1)}</g><g opacity="0">${pixels(stepped, LEG_ROWS)}${swap(0)}</g></svg>`
+}

package/mods/custom-crab-agents/types/index.d.ts

@@ -38,8 +38,54 @@ export type PlannedItem = {
   after: number[]
 }
 
+/** What an agent does, read from its title or type; it picks the crab's hat and the item it holds. */
+export type Role = 'review' | 'test' | 'design' | 'explore' | 'plan' | 'build' | 'other'
+
+/** A subagent's conversation opened as a pane of its own. */
+export type ChatPane = {
+  /** Pane id, `tab-chat-` and the agent's id */
+  id: string
+  agentId: string
+  title: string
+}
+
+/** One crab as the view draws it. */
+export type CrabView = {
+  id: string
+  title: string
+  role: Role
+  roleName: string
+  /** The bar's color, from the effort tier */
+  color: string
+  model: string
+  effort?: string
+  status: 'running' | 'finished' | 'failed'
+  /** e.g. `3/5 · Writing hero copy`, or `step 4` */
+  stepLine: string
+  /** e.g. `ctx 4% · 38k · ≈$0.05 · 0:26` */
+  stats: string
+  /** Filled part of the bar, from 0 to 1 */
+  share: number
+  /** Seconds into its animations the crab starts, so neighbours do not move in step */
+  phase: number
+}
+
+/** One planned item as the view draws it: a grey crab. */
+export type PlannedView = {
+  index: number
+  content: string
+  after: number[]
+  role: Role
+}
+
+/** What the crabs' view gets. */
+export type CrabsViewData = {
+  crabs: CrabView[]
+  planned: PlannedView[]
+}
+
 declare module 'claude-code' {
   interface PluginState {
-    'custom-crab-agents': { crabs: Crab[]; planned: PlannedItem[]; window: number }
+    'custom-crab-agents': { crabs: Crab[]; planned: PlannedItem[]; window: number; chats: ChatPane[] }
   }
 }