@xhulz/nina 0.33.0 → 0.35.0

package/src/transcripts.mjs

@@ -632,7 +632,7 @@ async function attachAgentDetail(projectDir, dispatches) {
       if (
         run.agent_read_bytes === size &&
         !('resumes' in run) &&
-        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'effort' in r && 'turns' in r)
+        [...records, ...later].every((r) => settled(r) && 'round' in r && 'lessons_read' in r && 'tokens' in r && 'files_touched' in r && 'effort' in r && 'turns' in r && 'prompt_chars' in r)
       ) {
         continue;
       }
@@ -662,6 +662,8 @@ async function attachAgentDetail(projectDir, dispatches) {
         written: new Set(),
         /** The tool calls the round made, by id: over its turns, how many calls each turn sent at once. */
         calls: new Set(),
+        /** How long the prompt that opened the round was, in characters; never the prompt. */
+        promptChars: null,
       });
       const rounds = [fresh()];
       const roundOf = roundsOf();
@@ -681,6 +683,14 @@ async function attachAgentDetail(projectDir, dispatches) {
           }
         }
         const round = rounds[n - 1];
+        if (round.promptChars === null && line.includes('"type":"user"')) {
+          try {
+            const said = promptOf(JSON.parse(line), n);
+            if (said !== null) round.promptChars = said.length;
+          } catch {
+            // A torn line is not the prompt.
+          }
+        }
         const hasSkill = line.includes('"Skill"');
         const hasHandback = line.includes('SubagentHandback');
         for (const m of line.matchAll(/"type":"tool_use","id":"([^"]+)"/g)) round.calls.add(m[1]);
@@ -770,6 +780,7 @@ async function attachAgentDetail(projectDir, dispatches) {
           record.tool_calls = round.calls.size;
           record.context_start = shape.start;
           record.context_peak = shape.peak;
+          record.prompt_chars = round.promptChars;
           record.usage_model = spent.model;
           record.effort = spent.effort;
           record.files_touched = round.written.size;
@@ -802,6 +813,21 @@ async function attachAgentDetail(projectDir, dispatches) {
   }
 }
 
+/**
+ * What a round was told, from one transcript row, or null when the row is not it. The dispatch's prompt
+ * opens the first round; a later round opens with the message that resumed the run, which Claude Code
+ * marks as meta, while a meta row in the first round is a reminder. The snapshot measures it and the
+ * Langfuse export sends it, so both read it here.
+ *
+ * @param {object} row - A parsed transcript row.
+ * @param {number} round - The round the row is in, from 1.
+ * @returns {string|null}
+ */
+export function promptOf(row, round) {
+  const content = row?.message?.content;
+  return row?.type === 'user' && (round > 1 || !row.isMeta) && typeof content === 'string' ? content : null;
+}
+
 /**
  * How a round spent its context: how many turns it took, and how large the context each turn re-read was
  * when the round began and at its largest. Every turn is billed the whole context again, so a round that

package/src/vocabulary.mjs

@@ -16,6 +16,17 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+/**
+ * A vocabulary name: capitals, digits and `_`, from a letter — `{{S3_BUCKET}}` as much as `{{OWNER}}`. Every
+ * reader of a placeholder reads it with this one grammar. Compose took any name the profile declared while
+ * `check`, `init` and `upgrade` looked only for capitals and `_`, so `{{S3_BUCKET}}` was reported as declared
+ * and referenced by nothing, and deleting it on that advice composed the placeholder raw, with nobody saying so.
+ */
+export const NAME = /^[A-Z][A-Z0-9_]*$/;
+
+/** A placeholder in a text, its name captured. */
+export const PLACEHOLDER = /\{\{([A-Z][A-Z0-9_]*)\}\}/g;
+
 /**
  * The defaults a layer root supplies, name → value. Anything that is not a string under an
  * upper-case name is ignored rather than trusted: a default reaches every project that pins it.
@@ -26,7 +37,7 @@ import { join } from 'node:path';
 export function defaultVocabulary(layerRoot) {
   try {
     const parsed = JSON.parse(readFileSync(join(layerRoot, 'core', 'vocabulary.json'), 'utf8'));
-    return Object.fromEntries(Object.entries(parsed).filter(([name, value]) => /^[A-Z_]+$/.test(name) && typeof value === 'string'));
+    return Object.fromEntries(Object.entries(parsed).filter(([name, value]) => NAME.test(name) && typeof value === 'string'));
   } catch {
     return {};
   }

package/src/wiring.mjs

@@ -205,21 +205,77 @@ function groupsFor(hooks, event) {
   return Array.isArray(hooks[event]) ? hooks[event] : null;
 }
 
+/** Whether one hook command runs a hook's script, recognised by what it runs, not by its exact text. */
+function runsCommand(x, h) {
+  const cmd = String(x?.command ?? '');
+  return cmd.includes(h.script) && (!h.mode || cmd.includes(h.mode));
+}
+
+/** Whether a settings group runs a hook's script. */
+function runs(g, h) {
+  return Boolean(g) && typeof g === 'object' && Array.isArray(g.hooks) && g.hooks.some((x) => runsCommand(x, h));
+}
+
+/** A matcher that reaches every tool: none, empty, or `*`. */
+const everyTool = (m) => m === undefined || m === null || m === '' || m === '*';
+
+/** A matcher this can read and rewrite: every tool, or a list of exact names. A regular expression is its owner's. */
+const plainMatcher = (m) => everyTool(m) || (typeof m === 'string' && /^[A-Za-z0-9_|]+$/.test(m));
+
+/** Whether two matchers reach a tool in common — unknown for a regular expression, taken as no. */
+function overlaps(a, b) {
+  if (everyTool(a) || everyTool(b)) return true;
+  if (!plainMatcher(a) || !plainMatcher(b)) return false;
+  const names = new Set(a.split('|'));
+  return b.split('|').some((n) => names.has(n));
+}
+
+/** Whether two of these groups run on a tool they share, so the hook runs once per group there. */
+const doubled = (groups) => groups.some((g, i) => groups.slice(i + 1).some((other) => overlaps(g.matcher, other.matcher)));
+
 /**
  * Whether settings already run a hook. Recognised by what the command runs, not by its exact text —
  * a project may have written its own — and by a matcher that reaches every tool the hook needs.
  */
 function covered(hooks, h) {
-  const groups = groupsFor(hooks, h.event) ?? [];
   const need = h.matcher ? h.matcher.split('|') : [];
-  return groups.some((g) => {
-    if (!g || typeof g !== 'object') return false;
-    if (!need.every((tool) => matcherReaches(g.matcher, tool))) return false;
-    return Array.isArray(g.hooks) && g.hooks.some((x) => {
-      const cmd = String(x?.command ?? '');
-      return cmd.includes(h.script) && (!h.mode || cmd.includes(h.mode));
-    });
-  });
+  return (groupsFor(hooks, h.event) ?? []).some((g) => runs(g, h) && need.every((tool) => matcherReaches(g.matcher, tool)));
+}
+
+/**
+ * The hooks a project runs, from both settings files merged by event — Claude Code runs both, so a hook
+ * kept in the local file counts. Every reader asks this one: `wire` used to read the shared file alone,
+ * and appended a second copy of each hook a project kept in its local file, which then ran twice.
+ *
+ * @param {string} target - The project directory.
+ * @param {(event: string) => boolean} [wanted] - Events whose malformed lists are worth a problem.
+ * @returns {Promise<{merged: Record<string, object[]>, problems: string[]}>} Each merged group says `from` which file.
+ */
+async function projectHooks(target, wanted = () => false) {
+  const merged = {};
+  const problems = [];
+  for (const rel of SETTINGS_FILES) {
+    const path = join(target, rel);
+    if (!existsSync(path)) continue;
+    let settings;
+    try {
+      settings = JSON.parse(await readFile(path, 'utf8'));
+    } catch (error) {
+      problems.push(`${rel} is not valid JSON — ${error.message}`);
+      continue;
+    }
+    const shape = settings?.hooks;
+    if (shape === undefined || shape === null) continue;
+    if (typeof shape !== 'object' || Array.isArray(shape)) {
+      problems.push(`${rel} has a "hooks" that is not an object of event lists — no hook in it can run`);
+      continue;
+    }
+    for (const [event, groups] of Object.entries(shape)) {
+      if (Array.isArray(groups)) (merged[event] ??= []).push(...groups.map((g) => (g && typeof g === 'object' ? { ...g, from: rel } : g)));
+      else if (wanted(event)) problems.push(`${rel}'s hooks.${event} is not a list — no hook in it can run`);
+    }
+  }
+  return { merged, problems };
 }
 
 /** The command settings run for a hook, when they run one — the selftest runs it the same way. */
@@ -299,29 +355,16 @@ export async function missingWiring(target, shipped) {
   }
   const wanted = HOOKS.filter((h) => shipped.has(h.script));
   if (wanted.length === 0) return out;
-  const merged = {};
-  for (const rel of SETTINGS_FILES) {
-    const path = join(target, rel);
-    if (!existsSync(path)) continue;
-    let settings;
-    try {
-      settings = JSON.parse(await readFile(path, 'utf8'));
-    } catch (error) {
-      out.push(`${rel} is not valid JSON — ${error.message}`);
-      continue;
-    }
-    const shape = settings?.hooks;
-    if (shape === undefined || shape === null) continue;
-    if (typeof shape !== 'object' || Array.isArray(shape)) {
-      out.push(`${rel} has a "hooks" that is not an object of event lists — no hook in it can run`);
-      continue;
-    }
-    for (const [event, groups] of Object.entries(shape)) {
-      if (Array.isArray(groups)) (merged[event] ??= []).push(...groups);
-      else if (wanted.some((h) => h.event === event)) out.push(`${rel}'s hooks.${event} is not a list — no hook in it can run`);
-    }
-  }
+  const { merged, problems } = await projectHooks(target, (event) => wanted.some((h) => h.event === event));
+  out.push(...problems);
   for (const h of wanted) {
+    const running = (merged[h.event] ?? []).filter((g) => runs(g, h));
+    if (doubled(running)) {
+      out.push(
+        `${running.length} ${h.event} groups run \`${h.script}${h.mode ? ` ${h.mode}` : ''}\` for tools they share, so it runs once per group there — ` +
+          '`nina wire --apply` makes them one',
+      );
+    }
     if (covered(merged, h)) continue;
     out.push(
       `.claude/settings.json has no ${h.event} hook${h.matcher ? ` for ${h.matcher}` : ''} running \`${h.script}${h.mode ? ` ${h.mode}` : ''}\` — without it ${h.why}`,
@@ -359,13 +402,9 @@ export async function staleHooks(target, shipped) {
  * @returns {Promise<string|null>} Null when nothing is missing.
  */
 export async function missingFragment(target, shipped) {
-  let settings = null;
-  try {
-    settings = JSON.parse(await readFile(join(target, '.claude', 'settings.json'), 'utf8'));
-  } catch {
-    // Absent or unreadable: everything is missing, and `missingWiring` says which.
-  }
-  const lacking = HOOKS.filter((h) => shipped.has(h.script) && !covered(settings?.hooks, h));
+  // Absent or unreadable files hold nothing: everything they would have held is missing, and `missingWiring` says why.
+  const { merged } = await projectHooks(target);
+  const lacking = HOOKS.filter((h) => shipped.has(h.script) && !covered(merged, h));
   return lacking.length === 0 ? null : JSON.stringify({ hooks: settingsHooks(lacking) }, null, 2);
 }
 
@@ -405,10 +444,36 @@ export async function applyWiring(target, shipped, { settings: editSettings = tr
     if (readable) {
       const hooks = settings.hooks ?? {};
       const added = [];
+      const { merged } = await projectHooks(target);
       for (const h of HOOKS.filter((h) => shipped.has(h.script))) {
-        if (covered(hooks, h)) continue;
-        (hooks[h.event] ??= []).push(group(h));
-        added.push(`${h.event}${h.matcher ? ` (${h.matcher})` : ''} → ${h.script}${h.mode ? ` ${h.mode}` : ''}`);
+        const running = (merged[h.event] ?? []).filter((g) => runs(g, h));
+        if (covered(merged, h) && !doubled(running)) continue;
+        const named = `${h.event}${h.matcher ? ` (${h.matcher})` : ''} → ${h.script}${h.mode ? ` ${h.mode}` : ''}`;
+        if (running.length === 0) {
+          (hooks[h.event] ??= []).push(group(h));
+          added.push(named);
+          continue;
+        }
+        // The groups that already run the script become one that reaches every tool it needs. A second group
+        // beside a narrower one — or two left as they were — runs it on the tools they share once per group, and
+        // the gate counts each of those events twice. A group in the local file, or one matched by a regular
+        // expression, is its owner's to change: said, and not doubled.
+        const foreign = running.find((g) => g.from !== '.claude/settings.json' || !plainMatcher(g.matcher));
+        if (foreign) {
+          problems.push(
+            `${foreign.from} runs ${h.script} for "${foreign.matcher ?? ''}" — make every group that runs it there one, reaching ${h.matcher ?? 'every tool'}; ` +
+              'another group beside it would run it twice',
+          );
+          continue;
+        }
+        const mine = (hooks[h.event] ?? []).filter((g) => runs(g, h));
+        const keep = mine.find((g) => everyTool(g.matcher)) ?? mine[0];
+        if (!everyTool(keep.matcher)) {
+          keep.matcher = [...new Set([...mine.flatMap((g) => g.matcher.split('|')), ...(h.matcher ? h.matcher.split('|') : [])])].join('|');
+        }
+        for (const g of mine) if (g !== keep) g.hooks = g.hooks.filter((x) => !runsCommand(x, h));
+        hooks[h.event] = hooks[h.event].filter((g) => !Array.isArray(g?.hooks) || g.hooks.length > 0);
+        added.push(`${named} (${mine.length > 1 ? `${mine.length} groups made one, ` : ''}reaching ${everyTool(keep.matcher) ? 'every tool' : keep.matcher})`);
       }
       // An old command, exactly as it was written, learns to say when its script cannot start, and how to
       // install NINA as it is installed now.