@g3nomaly/g3n-mods 0.1.6 → 0.1.8

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

@@ -2,84 +2,204 @@
 import { atom, read, update } from 'claude-code'
 import type { EngineInterface, Register } from 'claude-code'
 
-import type { Card } from '../types'
+import type { Card, Point, PointKind } from '../types'
 
-const cards = atom({ plugin: 'you-should-know', key: 'cards' } as const, [])
+const notes = atom({ plugin: 'you-should-know', key: 'notes' } as const, [])
 
-const DEFAULT_MIN_CHARS = 1500
+const DEFAULT_MIN_CHARS = 800
 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
+/** Most questions a card lists, and the longest one kept whole. */
+const MAX_QUESTIONS = 3
+const MAX_QUESTION_CHARS = 220
+/** Most changes, conclusions and facts the model adds to a card. */
+const MAX_MODEL_POINTS = 3
+/** Most of the user's request sent beside the reply. */
+const MAX_REQUEST_CHARS = 4000
+/** Kinds the model may tag a point with, in the order a card lists them; questions come from the reply itself. */
+const MODEL_KINDS: readonly PointKind[] = ['change', 'conclusion', 'fact']
+
+/**
+ * Each tag's look: its name, its color, the dark tint of its round icon, and the icon's mark, drawn in a 40 by 40 box
+ * in `currentColor`, which `iconSvg` fills with the tag's color.
+ * `badge` is the mark's character for the terminal, which draws no SVG.
+ */
+const TAGS: Readonly<Record<PointKind, { badge: string; name: string; color: string; tint: string; mark: string }>> = {
+  question: {
+    badge: '?', name: 'Question', color: '#e5b567', tint: '#3d3424',
+    mark: '<path d="M15.5 15.5a4.5 4.5 0 1 1 6.3 4.1c-1.2.6-1.8 1.5-1.8 2.8v1" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round"/><circle cx="20" cy="28.5" r="1.6" fill="currentColor"/>',
+  },
+  change: {
+    badge: '±', name: 'Change', color: '#b48ead', tint: '#36293a',
+    mark: '<path d="M13 27l1.6-5.2 9.2-9.2 3.6 3.6-9.2 9.2z" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linejoin="round"/>',
+  },
+  conclusion: {
+    badge: '✓', name: 'Conclusion', color: '#7cc47f', tint: '#26392a',
+    mark: '<path d="M13.5 20.5l4.5 4.5 8.5-9.5" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>',
+  },
+  fact: {
+    badge: 'i', name: 'Fact', color: '#5b8def', tint: '#232e45',
+    mark: '<circle cx="20" cy="13.5" r="1.8" fill="currentColor"/><path d="M20 18.5v9.5" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round"/>',
+  },
+}
+
+/** Text color on a badge, the card's own dark. */
+const CARD = '#1b1f27'
+
+/** Width of the longest tag name, so the points' text starts level. */
+const NAME_CELLS = Math.max(...Object.values(TAGS).map(tag => tag.name.length))
+
+/**
+ * Spacing of the card per surface. The terminal counts whole cells; the Claude Code extension turns a number into CSS
+ * (`ch` across, `lh` down) and takes fractions, so there the card gets room inside its border and between its lines.
+ */
+const SPACING = {
+  terminal: { paddingX: 1, paddingY: 0, rowGap: 0 },
+  other: { paddingX: 1.5, paddingY: 0.6, rowGap: 0.35 },
+} as const
+
+/** Size of a tag's round icon, in pixels. */
+const ICON_PX = 18
+
+/**
+ * Draws a tag's round icon: its tint filling the circle and its mark in the tag's color.
+ *
+ * @param kind - The tag, see `TAGS`.
+ * @returns The SVG markup as a string.
+ */
+function iconSvg(kind: PointKind): string {
+  const tag = TAGS[kind]
+  const mark = tag.mark.replaceAll('currentColor', tag.color)
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${ICON_PX}" height="${ICON_PX}" viewBox="0 0 40 40"><circle cx="20" cy="20" r="20" fill="${tag.tint}"/>${mark}</svg>`
+}
+
 
 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}.',
+  'You read the request a user gave an AI coding assistant and the reply it wrote, and pick at most three points that',
+  'tell the user what happened about their request.',
+  'Tag each one: "change" for something the reply did, such as a file, feature, element or setting it added, removed',
+  'or changed; "conclusion" for its direct answer to what the user asked; "fact" only for a cost, a breaking change',
+  'or a decision the user must make. Prefer changes when the reply did work, and list the biggest first.',
+  'Never pick caveats, limitations, what was not checked or tested, how to try it out, or anything the user did not ask about.',
+  'A line saying something was not verified, could not be checked or may need fixing later is a caveat: leave it out.',
+  'Fewer points beat a weak one; an empty list is fine.',
+  'Leave out the questions the reply asks; they are shown elsewhere.',
+  'Write a change as what was done, starting with the verb: "Removed the bulb icon", "Added a round icon per tag".',
+  'Answer with JSON only, no prose and no code fence: {"points": [{"kind": "change", "text": "..."}]}.',
+  'Each text is one plain line of at most 100 characters, in the reply\'s own facts and numbers.',
+  'If nothing in the reply answers the request, answer {"points": []}.',
 ].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.
+ * @brief Finds the questions a reply asks, in its own words: the sentences of its prose that end in a question mark.
+ *
+ * Code blocks and inline code holding a `?` are left out, and so is a `?` inside a word or URL, such as `?page=2`.
+ * List markers, heading marks and bold or italic marks are taken off.
+ *
+ * @param text - Full text of the reply.
+ * @returns Up to `MAX_QUESTIONS` questions, in order, each cut to `MAX_QUESTION_CHARS`.
+ */
+export function extractQuestions(text: string): string[] {
+  const prose = text
+    .replace(/```[\s\S]*?```/g, '\n')
+    .replace(/`([^`\n]*)`/g, (_, code: string) => (code.includes('?') ? ' ' : code))
+  const questions: string[] = []
+  for (const rawLine of prose.split('\n')) {
+    const line = rawLine.replace(/^\s*(?:[-*+]|\d+\.|#+|>)\s+/, '').replace(/\*\*|__/g, '')
+    for (const match of line.matchAll(/[^.!?]*\?(?=[\s)"'*_]|$)/g)) {
+      const question = normalize(match[0])
+      if (question.length >= 8 && !questions.includes(question)) questions.push(question.slice(0, MAX_QUESTION_CHARS))
+    }
+  }
+  return questions.slice(0, MAX_QUESTIONS)
+}
+
+/**
+ * @brief Reads the model's answer into tagged points.
  *
  * @param text - Raw answer from the model.
- * @returns The headline and detail, or `undefined` for a skip or anything malformed.
+ * @returns The changes, conclusions and facts, at most `MAX_MODEL_POINTS`; empty for a skip or anything malformed.
  */
-export function parseCard(text: string): Omit<Card, 'tail'> | undefined {
+export function parseModelPoints(text: string): Point[] {
   const json = /\{[\s\S]*\}/.exec(text)?.[0]
-  if (json === undefined) return undefined
+  if (json === undefined) return []
   let value: unknown
   try {
     value = JSON.parse(json)
   } catch {
-    return undefined
+    return []
+  }
+  if (typeof value !== 'object' || value === null || !('points' in value) || !Array.isArray(value.points)) return []
+  const points: Point[] = []
+  for (const item of value.points as unknown[]) {
+    if (typeof item !== 'object' || item === null || !('kind' in item) || !('text' in item)) continue
+    const { kind, text: line } = item
+    const tagged = MODEL_KINDS.find(one => one === kind)
+    if (tagged === undefined || typeof line !== 'string' || line.trim() === '') continue
+    points.push({ kind: tagged, text: line.trim().slice(0, 140) })
   }
-  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) }
+  return points.slice(0, MAX_MODEL_POINTS)
 }
 
 /**
- * @brief Asks the model for the reply's key point and keeps the card when there is one.
+ * @brief Builds a reply's card: its questions, then the model's changes, conclusions and facts when the reply is long
+ * enough.
  *
- * @param $ - Engine handle the model call and the cards state go through.
+ * @param $ - Engine handle the model call and the notes state go through.
+ * @param request - The user's text the reply answers; empty for a turn started without one.
  * @param answer - Full text of the assistant's reply.
- * @param model - Model that reads the reply.
+ * @param model - Model that reads the reply, or `undefined` to skip the call for a short 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
+async function buildCard($: EngineInterface, request: string, answer: string, model: string | undefined): Promise<void> {
+  const questions: Point[] = extractQuestions(answer).map(text => ({ kind: 'question', text }))
+  let found: Point[] = []
+  if (model !== undefined) {
+    const asked = request.trim() === '' ? '(no typed request; the reply continues earlier work)' : request.slice(0, MAX_REQUEST_CHARS)
+    const prompt = `The user asked:\n${asked}\n\nThe reply:\n${answer.slice(-MAX_PROMPT_CHARS)}`
+    const result = await $.model.complete({ model, system: SYSTEM, prompt, maxTokens: 400 })
+    if (result.isAnswered) found = parseModelPoints(result.text)
+  }
+  const points = [...questions, ...MODEL_KINDS.flatMap(kind => found.filter(point => point.kind === kind))]
+  if (points.length === 0) return
   const tail = normalize(answer).slice(-TAIL)
-  await update($, cards, list => [...list.filter(one => one.tail !== tail), { tail, ...card }].slice(-KEEP))
+  await update($, notes, list => [...list.filter(one => one.tail !== tail), { tail, points }].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.
+ * @param options - Plugin options: `minChars` sets the shortest reply the model reads for conclusions and facts,
+ *   `model` the model that reads it. A reply that asks a question gets a card at any length.
  */
 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
 
+  /** The user's text of each running turn, by turn id, so the model reads a reply beside the request it answers. */
+  const requests = new Map<string, string>()
+
+  on('turn.start', async ($, e, next) => {
+    requests.set(e.turnId, e.text)
+    return next(e)
+  })
+
   on('turn.complete', async ($, e, next) => {
     const result = await next(e)
-    if (e.agentId === undefined && e.reason === 'answer' && e.answer.length >= minChars) {
+    const request = requests.get(e.turnId) ?? ''
+    requests.delete(e.turnId)
+    if (e.agentId === undefined && e.reason === 'answer') {
       const answer = e.answer
-      $.clock.after(0, () => void extract($, answer, model))
+      const isLong = answer.length >= minChars
+      if (isLong || extractQuestions(answer).length > 0) $.clock.after(0, () => void buildCard($, request, answer, isLong ? model : undefined))
     }
     return result
   }).catch(($, e, next) => next(e))
@@ -88,27 +208,35 @@ export const register: Register = (on, options) => {
     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)))
+    const card: Card | undefined = (await read($, notes)).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} />
-        })()
+    const space = e.surface === 'terminal' ? SPACING.terminal : SPACING.other
+    /** A tag's round icon; the terminal, which draws no SVG, gets its mark's character on its color. */
+    const icon = (kind: PointKind) => {
+      if (e.surface === 'terminal') return <Text bold color={CARD} backgroundColor={TAGS[kind].color}>{` ${TAGS[kind].badge} `}</Text>
+      const { Svg } = $.ui.resolve(e)
+      return <Svg source={iconSvg(kind)} alt={TAGS[kind].name} width={ICON_PX} height={ICON_PX} />
+    }
 
+    // One line per point, each led by its tag's icon and name; only the tags the reply has show. Rows say `nowrap`: the
+    // Claude Code extension wraps a row by default, which would drop a long point under its icon. The point's text
+    // wraps inside its own column instead.
     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 borderStyle="round" borderColor="#3a3f4b" paddingX={space.paddingX} paddingY={space.paddingY} flexDirection="column" rowGap={space.rowGap}>
+            {card.points.map(point => {
+              const tag = TAGS[point.kind]
+              return (
+                <Box flexDirection="row" flexWrap="nowrap" columnGap={1} alignItems="flex-start">
+                  <Box flexShrink={0}>{icon(point.kind)}</Box>
+                  <Box width={NAME_CELLS} flexShrink={0}><Text color={tag.color}>{tag.name}</Text></Box>
+                  <Box flexGrow={1} flexShrink={1} minWidth={0}><Text>{point.text}</Text></Box>
+                </Box>
+              )
+            })}
         </Box>
       </Box>
     )

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

@@ -1,15 +1,24 @@
 // 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. */
+/** What a point is: a question the reply asks the user, a change it made, its answer to the request, or a fact they must act on. */
+export type PointKind = 'question' | 'change' | 'conclusion' | 'fact'
+
+/** One tagged line of a card. */
+export type Point = {
+  kind: PointKind
+  /** For a question, the reply's own words; else one plain line */
+  text: string
+}
+
+/** The points of one reply, keyed by the reply's last characters so its message can find them. */
 export type Card = {
   /** The reply's last 200 characters, whitespace collapsed */
   tail: string
-  headline: string
-  detail: string
+  points: Point[]
 }
 
 declare module 'claude-code' {
   interface PluginState {
-    'you-should-know': { cards: Card[] }
+    'you-should-know': { notes: Card[] }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g3nomaly/g3n-mods",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "The g3n Claude Code mods: panes, status lines, commands and hooks, installed with @g3nomaly/mods.",
   "type": "module",
   "files": [
@@ -11,6 +11,7 @@
     "build": "bun run build:marketplace",
     "typecheck": "tsc --noEmit && tsc --noEmit --project mods/tsconfig.json && tsc --noEmit --project mods/tsconfig.view.json",
     "validate": "bun scripts/validate.ts",
+    "test": "bun test tests",
     "build:marketplace": "bun scripts/build-marketplace.ts",
     "types": "bun scripts/sync-types.ts"
   },