@g3nomaly/g3n-mods 0.0.0-stage → 0.1.1

package/mods/tool-timeline/hooks/register.tsx

@@ -0,0 +1,311 @@
+// packages/g3n-mods/mods/tool-timeline/hooks/register.tsx
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { CallStatus, TimelineCall } from '../types'
+
+const PANE = 'tool-timeline'
+const TITLE = 'Tool timeline'
+const calls = atom({ plugin: 'tool-timeline', key: 'calls' } as const, [])
+
+/** Calls kept in state; older ones fall off. */
+const KEEP = 100
+
+/** Approximate pixel width of one cell of the editor's code font. */
+const CELL_PX = 7
+
+const TRACK = '#2b3240'
+const ERROR = '#e06c6c'
+const DIM = '#8a8f98'
+
+/** Badge color per tool family. */
+const TOOL_COLORS: ReadonlyArray<[RegExp, string]> = [
+  [/^Bash$|^PowerShell$/, '#e5b567'],
+  [/^Read$/, '#5b8def'],
+  [/^(Edit|Write|NotebookEdit)$/, '#7cc47f'],
+  [/^(Grep|Glob|LS)$/, '#9b87f5'],
+  [/^Web/, '#5fb3c4'],
+  [/^(Agent|Task)$/, '#f09bb5'],
+]
+
+/** Input fields that say most about a call, tried in order. */
+const LABEL_FIELDS = ['command', 'file_path', 'notebook_path', 'pattern', 'url', 'query', 'description', 'skill', 'prompt'] as const
+
+/** Finds the badge color of a tool, or the dim color for a tool outside every family. */
+function colorOf(tool: string): string {
+  return TOOL_COLORS.find(([match]) => match.test(tool))?.[1] ?? DIM
+}
+
+/** Picks the one-character badge a tool shows: `$` for shell tools, else its first letter. */
+function badgeOf(tool: string): string {
+  if (tool === 'Bash' || tool === 'PowerShell') return '$'
+  return tool.replace(/^mcp__[^_]+__/, '').charAt(0).toUpperCase()
+}
+
+/**
+ * @brief Shortens a call's input to the text the pane shows: a command, a file's name, a pattern, or the first text field.
+ *
+ * @param input - Arguments of the tool call.
+ * @returns The label, with whitespace collapsed to single spaces.
+ */
+export function labelOf(input: Record<string, unknown>): string {
+  for (const field of LABEL_FIELDS) {
+    const value = input[field]
+    if (typeof value !== 'string' || value.length === 0) continue
+    const text = field === 'file_path' || field === 'notebook_path' ? value.split('/').pop() ?? value : value
+    return text.replace(/\s+/g, ' ').trim()
+  }
+  const first = Object.values(input).find((value): value is string => typeof value === 'string')
+  return first?.replace(/\s+/g, ' ').trim() ?? ''
+}
+
+/**
+ * @brief Joins the text of a tool result's content, which is a string or a list of text blocks.
+ *
+ * @param content - Result content: a string, or a list of blocks with a `text` field.
+ * @returns The text, one block per line.
+ */
+function resultText(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  return content
+    .map(block => (typeof block === 'object' && block !== null && 'text' in block && typeof block.text === 'string' ? block.text : ''))
+    .join('\n')
+}
+
+/** Checks whether an error text reads as a refusal: a hook's deny, the permission dialog's no, a blocked call. */
+function isRefusal(text: string): boolean {
+  return /\bdenied\b|\bblocked\b|doesn't want to proceed|was rejected|permission/i.test(text)
+}
+
+/** Formats a duration in milliseconds as seconds, with one decimal below ten seconds. */
+function seconds(ms: number): string {
+  return ms >= 10_000 ? `${Math.round(ms / 1000)}s` : `${(ms / 1000).toFixed(1)}s`
+}
+
+/** Shortens a call's note for the callout, e.g. `use the trash` for delete-guard's deny. */
+function shortNote(note: string | undefined): string {
+  if (note === undefined) return ''
+  if (/trash/i.test(note)) return 'use the trash'
+  const text = note.replace(/^[\w-]+:\s*/, '')
+  return text.length > 40 ? `${text.slice(0, 39)}…` : text
+}
+
+/**
+ * @brief Adds a call or changes the one with its id; the list stays in start order and capped.
+ *
+ * @param $ - Engine handle the calls state is updated through.
+ * @param id - Tool use id of the call.
+ * @param patch - Builds the call's next value from its stored value, or from `undefined` when the call is new.
+ */
+async function patchCall($: EngineInterface, id: string, patch: (call: TimelineCall | undefined) => TimelineCall): Promise<void> {
+  await update($, calls, list => {
+    const index = list.findIndex(call => call.id === id)
+    if (index === -1) return [...list, patch(undefined)].slice(-KEEP)
+    return list.map((call, i) => (i === index ? patch(call) : call))
+  })
+}
+
+/**
+ * @brief Ends a call with its status, keeping the first ending it got.
+ *
+ * @param $ - Engine handle the calls state is updated through.
+ * @param id - Tool use id of the call.
+ * @param status - Status the call ends with.
+ * @param note - Text shown with the status, such as a refusal reason.
+ */
+async function settleCall($: EngineInterface, id: string, status: CallStatus, note?: string): Promise<void> {
+  const endedAt = await $.clock.now()
+  await patchCall($, id, call =>
+    call === undefined
+      ? { id, tool: 'tool', label: '', status, startedAt: endedAt, endedAt, note }
+      : call.endedAt !== undefined ? call : { ...call, status, endedAt, note },
+  )
+}
+
+/**
+ * @brief Redraws the pane while a call runs, so its bar and time move.
+ *
+ * @param $ - Engine handle the pane is redrawn through.
+ */
+async function tick($: EngineInterface): Promise<void> {
+  const list = await read($, calls)
+  if (list.some(call => call.status === 'running')) $.ui.invalidate('ui.render')
+}
+
+/**
+ * @brief Finds the call that replaced a denied call: the next call of the same tool.
+ *
+ * @param list - Calls in start order.
+ * @param index - Position of the denied call in `list`.
+ * @returns The replacing call, or `undefined` when none follows.
+ */
+function replacementOf(list: readonly TimelineCall[], index: number): TimelineCall | undefined {
+  const denied = list[index]
+  return denied === undefined ? undefined : list.slice(index + 1).find(call => call.tool === denied.tool)
+}
+
+/**
+ * @brief Builds the SVG of a track with a bar filled to `fill` pixels.
+ *
+ * @param width - Width of the track in pixels.
+ * @param fill - Filled length in pixels, clamped to the width.
+ * @param color - Fill color.
+ * @returns The SVG markup.
+ */
+function barSvg(width: number, fill: number, color: string): string {
+  const w = Math.max(0, Math.min(width, fill))
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="8" viewBox="0 0 ${width} 8"><rect width="${width}" height="8" rx="2" fill="${TRACK}"/><rect width="${w.toFixed(1)}" height="8" rx="2" fill="${color}"/></svg>`
+}
+
+/**
+ * @brief Subscribes the timeline's handlers to the engine's events, its command and its pane.
+ *
+ * @param on - Subscribes a handler to one engine event, optionally filtered.
+ */
+export const register: Register = on => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({ name: 'tool-timeline', description: 'Show or hide the tool call timeline' })
+    void $.ui.open({ id: PANE, title: TITLE })
+    $.clock.every(1000, () => void tick($))
+    return next(e)
+  })
+
+  on('command.run', { command: 'tool-timeline' }, async $ => {
+    if ((await $.ui.panes()).some(pane => pane.id === PANE)) {
+      await $.ui.close({ id: PANE })
+      return { text: 'Tool timeline hidden.' }
+    }
+    await $.ui.open({ id: PANE, title: TITLE })
+    return { text: 'Tool timeline shown.' }
+  })
+
+  on('tool.call', async ($, e, next) => {
+    const startedAt = await $.clock.now()
+    const label = labelOf(e as unknown as Record<string, unknown>)
+    await patchCall($, e.tool_use_id, call => ({
+      ...call,
+      id: e.tool_use_id,
+      tool: e.tool,
+      label,
+      status: 'running',
+      startedAt,
+      agentId: e.agentId,
+    }))
+
+    const ran = await next(e)
+    if ('deny' in ran) await settleCall($, e.tool_use_id, 'denied', ran.deny)
+    else if (ran.isError === true) await settleCall($, e.tool_use_id, isRefusal(ran.text ?? '') ? 'denied' : 'error', ran.text)
+    else await settleCall($, e.tool_use_id, 'ok')
+    return ran
+  }).catch(($, e, next) => next(e))
+
+  on('session.append', async ($, e, next) => {
+    const stored = await next(e)
+    if (e.door === 'response') {
+      const now = await $.clock.now()
+      for (const block of e.message.content) {
+        if (block.type !== 'tool_use' || typeof block.id !== 'string' || typeof block.name !== 'string') continue
+        const input = typeof block.input === 'object' && block.input !== null ? (block.input as Record<string, unknown>) : {}
+        const id = block.id
+        const tool = block.name
+        await patchCall($, id, call => call ?? { id, tool, label: labelOf(input), status: 'queued', startedAt: now, agentId: e.agentId })
+      }
+    }
+    if (e.door === 'tool-result') {
+      for (const block of e.message.content) {
+        if (block.type !== 'tool_result' || typeof block.tool_use_id !== 'string') continue
+        const list = await read($, calls)
+        const call = list.find(one => one.id === block.tool_use_id)
+        if (call?.status === 'queued') {
+          const text = resultText(block.content)
+          await settleCall($, block.tool_use_id, block.is_error === true ? 'denied' : 'ok', text)
+        }
+      }
+    }
+    return stored
+  }).catch(($, e, next) => next(e))
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e)
+    const list = await read($, calls)
+    if (list.length === 0) return <Text dimColor>No tool calls yet.</Text>
+
+    const now = await $.clock.now()
+    const room = Math.max(4, (e.viewport?.rows ?? 30) - 6)
+    const shown = list.slice(-room)
+    /** Length of a call so far, or up to its end when it has one. */
+    const durationOf = (call: TimelineCall): number => (call.endedAt ?? now) - call.startedAt
+    const longest = Math.max(1, ...shown.map(durationOf))
+    const total = list.reduce((sum, call) => sum + (call.status === 'denied' ? 0 : durationOf(call)), 0)
+    const barCells = Math.max(8, Math.floor(e.props.bodyColumns * 0.3))
+    const labelCells = Math.max(12, e.props.bodyColumns - barCells - 12)
+
+    /** Draws the bar showing a call's share of the longest call's time. */
+    const bar = (call: TimelineCall) => {
+      const color = call.status === 'error' ? ERROR : call.status === 'ok' && /^Bash$/.test(call.tool) ? '#5fae6e' : colorOf(call.tool)
+      const share = call.status === 'denied' ? 0.04 : Math.max(0.03, durationOf(call) / longest)
+      if (e.surface === 'terminal') {
+        const filled = Math.max(1, Math.round(share * barCells))
+        return (
+          <Text>
+            <Text color={color}>{'▬'.repeat(filled)}</Text>
+            <Text color={TRACK}>{'▬'.repeat(barCells - filled)}</Text>
+          </Text>
+        )
+      }
+      const { Svg } = $.ui.resolve(e)
+      const width = barCells * CELL_PX
+      return <Svg source={barSvg(width, share * width, color)} alt={`${call.tool} ${seconds(durationOf(call))}`} width={width} height={8} />
+    }
+
+    /** Renders a call's status at the end of its row: its time, `denied`, `queued` or a mark for an error. */
+    const outcome = (call: TimelineCall) => {
+      switch (call.status) {
+        case 'denied': return <Text color={ERROR}>denied</Text>
+        case 'error': return <Text color={ERROR}>{seconds(durationOf(call))} ✗</Text>
+        case 'ok': return <Text dimColor>{seconds(durationOf(call))}</Text>
+        case 'running': return <Text color="#e5b567">{seconds(durationOf(call))}…</Text>
+        case 'queued': return <Text dimColor>queued</Text>
+      }
+    }
+
+    const rows = shown.map((call, index) => {
+      const replacement = call.status === 'denied' ? replacementOf(shown, index) : undefined
+      return (
+        <Box flexDirection="column">
+          <Box flexDirection="row" columnGap={1}>
+            <Text bold color="#1b1f27" backgroundColor={colorOf(call.tool)}> {badgeOf(call.tool)} </Text>
+            <Box width={labelCells}>
+              <Text wrap="truncate-end" strikethrough={call.status === 'denied'} color={call.status === 'denied' ? ERROR : undefined}>
+                {call.agentId === undefined ? '' : '↳ '}{call.tool} <Text dimColor>{call.label}</Text>
+              </Text>
+            </Box>
+            {bar(call)}
+            <Box width={8} justifyContent="flex-end">{outcome(call)}</Box>
+          </Box>
+          {call.status === 'denied' && (
+            <Box borderStyle="round" borderColor="#7a3b3b" paddingX={1} flexDirection="row" justifyContent="space-between">
+              <Text wrap="truncate-end">
+                <Text color={ERROR}>⊘ </Text>
+                <Text strikethrough dimColor>{call.label}</Text>
+                {replacement === undefined ? '' : <Text> → <Text color="#7cc47f">{replacement.label}</Text></Text>}
+              </Text>
+              <Text color={ERROR}>denied{call.note === undefined ? '' : ` · ${shortNote(call.note)}`}</Text>
+            </Box>
+          )}
+        </Box>
+      )
+    })
+
+    return (
+      <Box flexDirection="column" gap={0}>
+        <Box flexDirection="row" justifyContent="space-between" marginBottom={1}>
+          <Text bold>Tool timeline</Text>
+          <Text dimColor>{list.length} call{list.length === 1 ? '' : 's'} · {seconds(total)}</Text>
+        </Box>
+        {rows}
+      </Box>
+    )
+  })
+}

package/mods/tool-timeline/types/index.d.ts

@@ -0,0 +1,25 @@
+// packages/g3n-mods/mods/tool-timeline/types/index.d.ts
+
+/** How a call ended: still waiting or running, done, failed, or refused before it ran. */
+export type CallStatus = 'queued' | 'running' | 'ok' | 'error' | 'denied'
+
+/** One tool call on the timeline; times are milliseconds since the epoch. */
+export type TimelineCall = {
+  id: string
+  tool: string
+  /** Short form of the call's input, e.g. `rm -rf dist` or `package.json` */
+  label: string
+  status: CallStatus
+  startedAt: number
+  endedAt?: number
+  /** Why it was denied or failed, as the deny or error text said */
+  note?: string
+  /** Set on calls a subagent made */
+  agentId?: string
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'tool-timeline': { calls: TimelineCall[] }
+  }
+}

package/mods/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "types": [],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "jsx": "react",
+    "jsxFactory": "h",
+    "jsxFragmentFactory": "Fragment"
+  },
+  "include": ["../types/claude-code.d.ts", "*/hooks", "*/types"]
+}

package/mods/you-should-know/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "you-should-know",
+  "version": "0.1.0",
+  "description": "A card under long replies that flags their key point: a headline and one supporting line.",
+  "author": {
+    "name": "g3ntrovert"
+  },
+  "types": "./types/index.d.ts",
+  "userConfig": {
+    "minChars": {
+      "type": "number",
+      "title": "Minimum reply length",
+      "default": 1500,
+      "description": "Replies shorter than this many characters get no card"
+    },
+    "model": {
+      "type": "string",
+      "title": "Model",
+      "default": "haiku",
+      "description": "Model that picks the key point"
+    }
+  }
+}

package/mods/you-should-know/hooks/hooks.json

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

package/mods/you-should-know/hooks/register.tsx

@@ -0,0 +1,116 @@
+// packages/g3n-mods/mods/you-should-know/hooks/register.tsx
+import { atom, read, update } from 'claude-code'
+import type { EngineInterface, Register } from 'claude-code'
+
+import type { Card } from '../types'
+
+const cards = atom({ plugin: 'you-should-know', key: 'cards' } as const, [])
+
+const DEFAULT_MIN_CHARS = 1500
+const DEFAULT_MODEL = 'haiku'
+const TAIL = 200
+const KEEP = 20
+/** Most of a reply sent to the model; the end of a reply carries its conclusion. */
+const MAX_PROMPT_CHARS = 40_000
+
+const SYSTEM = [
+  'You read one reply that an AI coding assistant wrote to its user, and pick the single point the user must not miss:',
+  'a cost, a risk, a decision they have to make, a breaking change, or a surprising fact.',
+  'Answer with JSON only, no prose and no code fence: {"headline": "...", "detail": "..."}.',
+  'The headline is a plain statement of at most 70 characters. The detail is one supporting line of at most 120 characters.',
+  'Use the reply\'s own facts and numbers. If nothing in the reply stands out, answer {"skip": true}.',
+].join(' ')
+
+const BULB_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="#3d3424"/><path d="M20 11a6 6 0 0 0-3.6 10.8c.8.6 1.1 1.3 1.1 2.2v1h5v-1c0-.9.3-1.6 1.1-2.2A6 6 0 0 0 20 11z" fill="none" stroke="#e5b567" stroke-width="1.6"/><path d="M17.5 28h5M18.3 30.5h3.4" stroke="#e5b567" stroke-width="1.6" stroke-linecap="round"/></svg>'
+
+/** Collapses every run of whitespace to one space and trims both ends. */
+function normalize(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+/**
+ * @brief Reads the model's answer into a card's headline and detail.
+ *
+ * @param text - Raw answer from the model.
+ * @returns The headline and detail, or `undefined` for a skip or anything malformed.
+ */
+export function parseCard(text: string): Omit<Card, 'tail'> | undefined {
+  const json = /\{[\s\S]*\}/.exec(text)?.[0]
+  if (json === undefined) return undefined
+  let value: unknown
+  try {
+    value = JSON.parse(json)
+  } catch {
+    return undefined
+  }
+  if (typeof value !== 'object' || value === null || !('headline' in value) || !('detail' in value)) return undefined
+  const { headline, detail } = value
+  if (typeof headline !== 'string' || typeof detail !== 'string' || headline.trim().length === 0) return undefined
+  return { headline: headline.trim().slice(0, 90), detail: detail.trim().slice(0, 160) }
+}
+
+/**
+ * @brief Asks the model for the reply's key point and keeps the card when there is one.
+ *
+ * @param $ - Engine handle the model call and the cards state go through.
+ * @param answer - Full text of the assistant's reply.
+ * @param model - Model that reads the reply.
+ */
+async function extract($: EngineInterface, answer: string, model: string): Promise<void> {
+  const result = await $.model.complete({ model, system: SYSTEM, prompt: answer.slice(-MAX_PROMPT_CHARS), maxTokens: 300 })
+  if (!result.isAnswered) return
+  const card = parseCard(result.text)
+  if (card === undefined) return
+  const tail = normalize(answer).slice(-TAIL)
+  await update($, cards, list => [...list.filter(one => one.tail !== tail), { tail, ...card }].slice(-KEEP))
+}
+
+/**
+ * @brief Subscribes the card handlers to the engine's events and renders the card.
+ *
+ * @param on - Subscribes a handler to one engine event.
+ * @param options - Plugin options: `minChars` sets the shortest reply read, `model` the model that reads it.
+ */
+export const register: Register = (on, options) => {
+  const minChars = Number(options.minChars ?? DEFAULT_MIN_CHARS)
+  const model = typeof options.model === 'string' && options.model.length > 0 ? options.model : DEFAULT_MODEL
+
+  on('turn.complete', async ($, e, next) => {
+    const result = await next(e)
+    if (e.agentId === undefined && e.reason === 'answer' && e.answer.length >= minChars) {
+      const answer = e.answer
+      $.clock.after(0, () => void extract($, answer, model))
+    }
+    return result
+  }).catch(($, e, next) => next(e))
+
+  on('ui.render', { component: 'AssistantMessage' }, async ($, e, next) => {
+    if (e.props.isSummary === true) return next(e)
+    const text = normalize(e.props.text)
+    if (text.length < 20) return next(e)
+    const card = (await read($, cards)).find(one => one.tail.endsWith(text.slice(-TAIL)))
+    if (card === undefined) return next(e)
+
+    const { Box, Text } = $.ui.resolve(e)
+    const icon = e.surface === 'terminal'
+      ? <Text color="#e5b567">💡</Text>
+      : (() => {
+          const { Svg } = $.ui.resolve(e)
+          return <Svg source={BULB_SVG} alt="key point" width={40} height={40} />
+        })()
+
+    return (
+      <Box flexDirection="column" gap={1}>
+        {await next(e)}
+        <Box borderStyle="round" borderColor="#3a3f4b" paddingX={2} paddingY={1} flexDirection="row" columnGap={2} alignItems="center">
+          {icon}
+          <Box flexDirection="column">
+            <Text bold color="#e5b567">YOU SHOULD KNOW</Text>
+            <Text bold>{card.headline}</Text>
+            <Text dimColor>{card.detail}</Text>
+          </Box>
+        </Box>
+      </Box>
+    )
+  })
+}

package/mods/you-should-know/types/index.d.ts

@@ -0,0 +1,15 @@
+// packages/g3n-mods/mods/you-should-know/types/index.d.ts
+
+/** The key point of one long reply, keyed by the reply's last characters so its message can find it. */
+export type Card = {
+  /** The reply's last 200 characters, whitespace collapsed */
+  tail: string
+  headline: string
+  detail: string
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    'you-should-know': { cards: Card[] }
+  }
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@g3nomaly/g3n-mods",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The g3n Claude Code mods: panes, status lines, commands and hooks, installed with @g3nomaly/mods.",
+  "type": "module",
+  "files": [
+    ".claude-plugin",
+    "mods"
+  ],
+  "scripts": {
+    "build": "bun run build:marketplace",
+    "typecheck": "tsc --noEmit && tsc --noEmit --project mods/tsconfig.json",
+    "validate": "bun scripts/validate.ts",
+    "build:marketplace": "bun scripts/build-marketplace.ts",
+    "types": "bun scripts/sync-types.ts"
+  },
+  "devDependencies": {
+    "@g3nomaly/core": "^0.3.1",
+    "@types/bun": "^1.4.0",
+    "typescript": "~7.0.2",
+    "zod": "^4.4.3"
+  },
+  "license": "Elastic-2.0",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.