@ariso-ai/ari-hooks 0.1.8 → 0.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariso-ai/ari-hooks",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Set up Claude Code hooks that share your requests and their outcomes with Ari",
   "type": "module",
   "bin": {

package/src/hooks.js

@@ -1,4 +1,5 @@
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import {
   mkdirSync,
   readFileSync,
@@ -81,6 +82,33 @@ function agentTypeOf(input, agent) {
   return 'codex';
 }
 
+// Claude Code auto-delivers a background task's completion as a synthetic
+// UserPromptSubmit turn — the entire prompt is a <task-notification> block,
+// not something the user typed. Recording it verbatim as a "request"
+// pollutes the activity feed with agent-internal bookkeeping, so swap it for
+// a short human-readable stand-in built from the notification's <summary>.
+const TASK_NOTIFICATION_RE = /^<task-notification>[\s\S]*<\/task-notification>$/;
+const SUMMARY_RE = /<summary>([\s\S]*?)<\/summary>/;
+const XML_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+const decodeXmlEntities = (text) =>
+  text.replace(/&(amp|lt|gt|quot|apos);/g, (_, name) => XML_ENTITIES[name]);
+
+function taskNotificationStandIn(prompt) {
+  const trimmed = prompt.trim();
+  if (!TASK_NOTIFICATION_RE.test(trimmed)) return null;
+  const summary = trimmed.match(SUMMARY_RE)?.[1]?.trim();
+  return summary
+    ? `The coding agent ran a background task: ${decodeXmlEntities(summary)}`
+    : 'The coding agent ran a background task.';
+}
+
+// The IDE integration injects the user's current editor selection into the
+// prompt as an <ide_selection> block — host-added context, not text the user
+// typed. Strip it before recording so the activity feed shows only what the
+// user actually said.
+const IDE_SELECTION_RE = /<ide_selection>[\s\S]*?<\/ide_selection>/g;
+const stripIdeSelection = (prompt) => prompt.replace(IDE_SELECTION_RE, '').trim();
+
 /**
  * UserPromptSubmit (Claude Code) / beforeSubmitPrompt (Cursor): remember the
  * prompt so the Stop hook can pair it with the turn's outcome. Both hosts
@@ -89,11 +117,18 @@ function agentTypeOf(input, agent) {
 async function onUserPromptSubmit(input) {
   const sessionId = sessionIdOf(input);
   if (!sessionId || typeof input.prompt !== 'string') return;
+  const prompt = stripIdeSelection(input.prompt);
+  if (!prompt) return;
   const session = loadSession(sessionId);
-  session.prompts.push(input.prompt);
+  session.prompts.push(taskNotificationStandIn(prompt) ?? prompt);
   saveSession(sessionId, session);
 }
 
+// A model name from a hook payload, or null — hosts that include one send a
+// plain non-empty string.
+const modelOf = (value) =>
+  typeof value === 'string' && value.trim() ? value : null;
+
 /**
  * afterAgentResponse (Cursor only): Cursor's transcript is not the Claude
  * Code JSONL that extractOutcome can parse, so capture the final assistant
@@ -105,6 +140,8 @@ async function onAgentResponse(input) {
   if (!sessionId || typeof input.text !== 'string' || !input.text.trim()) return;
   const session = loadSession(sessionId);
   session.outcome = input.text;
+  const model = modelOf(input.model);
+  if (model) session.model = model;
   saveSession(sessionId, session);
 }
 
@@ -119,17 +156,7 @@ function assistantText(entry) {
     .trim();
 }
 
-/**
- * Pull the final assistant text out of the transcript (JSONL). This is the
- * "outcome" — we deliberately skip the intermediate steps/tool calls.
- *
- * `settled` reports whether the exchange actually ends in assistant text.
- * When the transcript instead ends at a tool call/result or a half-written
- * line, the final message hasn't been flushed yet and `text` is only the
- * last narration before a tool ran — the caller should re-read rather than
- * ship that as the outcome.
- */
-function extractOutcome(transcriptPath) {
+function parseTranscript(transcriptPath) {
   const entries = [];
   let tailPartial = false;
   for (const line of readFileSync(transcriptPath, 'utf8').split('\n')) {
@@ -141,7 +168,20 @@ function extractOutcome(transcriptPath) {
       tailPartial = true; // a line still being written
     }
   }
+  return { entries, tailPartial };
+}
 
+/**
+ * Pull the final assistant text out of the transcript entries. This is the
+ * "outcome" — we deliberately skip the intermediate steps/tool calls.
+ *
+ * `settled` reports whether the exchange actually ends in assistant text.
+ * When the transcript instead ends at a tool call/result or a half-written
+ * line, the final message hasn't been flushed yet and `text` is only the
+ * last narration before a tool ran — the caller should re-read rather than
+ * ship that as the outcome.
+ */
+function extractOutcome(entries, tailPartial) {
   let settled = tailPartial ? false : null;
   for (let i = entries.length - 1; i >= 0; i--) {
     const entry = entries[i];
@@ -166,12 +206,72 @@ function extractOutcome(transcriptPath) {
   return { text: null, settled: false };
 }
 
+// A user entry that is an actual typed prompt — not a tool result, not host
+// bookkeeping (isMeta), not a subagent's inner conversation (isSidechain).
+function isUserPrompt(entry) {
+  if (entry.type !== 'user' || entry.isSidechain || entry.isMeta) return false;
+  const content = entry.message?.content;
+  if (typeof content === 'string') return content.trim().length > 0;
+  return (
+    Array.isArray(content) &&
+    content.some((block) => block.type === 'text') &&
+    !content.some((block) => block.type === 'tool_result')
+  );
+}
+
+/**
+ * Model and token usage for the turn being reported. The transcript holds
+ * the whole session, so walk back past `promptCount` user prompts (this
+ * send covers that many queued prompts) and only count assistant entries
+ * after that point. Usage is keyed by message id — a message split across
+ * several JSONL entries (one per content block) repeats the same usage on
+ * each, and the last entry wins — then totalled over everything the API
+ * metered: input, cache writes/reads, and output. The model is named by
+ * the turn's last top-level assistant message; sidechain (subagent)
+ * entries still count toward tokens.
+ */
+function extractTurnStats(entries, promptCount) {
+  let boundary = -1;
+  let remaining = Math.max(1, promptCount);
+  for (let i = entries.length - 1; i >= 0 && remaining > 0; i--) {
+    if (isUserPrompt(entries[i])) {
+      boundary = i;
+      remaining--;
+    }
+  }
+
+  let model = null;
+  const usageById = new Map();
+  for (let i = boundary + 1; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.type !== 'assistant') continue;
+    const message = entry.message ?? {};
+    // '<synthetic>' marks host-injected error messages, not a real model.
+    if (!entry.isSidechain && modelOf(message.model) && message.model !== '<synthetic>') {
+      model = message.model;
+    }
+    if (message.usage) usageById.set(message.id ?? `entry-${i}`, message.usage);
+  }
+
+  let tokens = null;
+  for (const usage of usageById.values()) {
+    tokens =
+      (tokens ?? 0) +
+      (usage.input_tokens ?? 0) +
+      (usage.cache_creation_input_tokens ?? 0) +
+      (usage.cache_read_input_tokens ?? 0) +
+      (usage.output_tokens ?? 0);
+  }
+  return { model, tokens };
+}
+
 const clamp = (text) =>
   text.length > MAX_TEXT_LENGTH ? text.slice(0, MAX_TEXT_LENGTH) : text;
 
 /**
  * Stop: the turn is over — send the accumulated request(s) plus the final
- * assistant message to Ari, then clear the per-session state.
+ * assistant message (and, when the host exposes them, the model used and
+ * the turn's token count) to Ari, then clear the per-session state.
  */
 async function onStop(input, agent) {
   // stop_hook_active means a stop hook already forced Claude to continue;
@@ -188,13 +288,36 @@ async function onStop(input, agent) {
   // last_assistant_message; Claude Code sessions read it from the transcript,
   // waiting for the final assistant message to land there (on timeout, fall
   // back to the last text we did find — best effort).
-  let outcome = session.outcome ?? input.last_assistant_message ?? null;
-  if (!outcome && input.transcript_path) {
+  const payloadOutcome = session.outcome ?? input.last_assistant_message ?? null;
+  let outcome = payloadOutcome;
+  // Hosts that hand us the outcome directly may also name the model on their
+  // payloads; Claude Code's model and token usage live only in the
+  // transcript. Token counts are transcript-only — the other hosts don't
+  // report usage. Recent Claude Code also sends last_assistant_message, so
+  // the transcript is read for stats even when the outcome is already in
+  // hand — but a stats failure must never cost us the activity itself.
+  let model = modelOf(input.model) ?? session.model ?? null;
+  let tokens = null;
+  if (input.transcript_path) {
     const deadline = Date.now() + OUTCOME_SETTLE_TIMEOUT_MS;
     for (;;) {
-      const { text, settled } = extractOutcome(input.transcript_path);
-      outcome = text;
-      if (settled || Date.now() >= deadline) break;
+      let entries, tailPartial;
+      try {
+        ({ entries, tailPartial } = parseTranscript(input.transcript_path));
+      } catch (err) {
+        logError(err);
+        break;
+      }
+      const { text, settled } = extractOutcome(entries, tailPartial);
+      outcome = payloadOutcome ?? text;
+      // Even with the outcome in hand, wait for the final message to flush
+      // so its usage makes it into the token count.
+      if (settled || Date.now() >= deadline) {
+        const stats = extractTurnStats(entries, session.prompts.length);
+        model = stats.model ?? model;
+        tokens = stats.tokens;
+        break;
+      }
       await sleep(OUTCOME_POLL_INTERVAL_MS);
     }
   }
@@ -216,6 +339,9 @@ async function onStop(input, agent) {
       agent_type: agentTypeOf(input, agent),
       // Cursor sends workspace_roots instead of cwd.
       cwd: input.cwd ?? input.workspace_roots?.[0] ?? process.cwd(),
+      // Only sent when known — the API treats absent and unknown alike.
+      ...(model && { primary_model: model }),
+      ...(tokens != null && { token_count: tokens }),
     }),
     signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
   });
@@ -232,23 +358,7 @@ const MAX_TASK_NAME_LENGTH = 200;
 const oneLine = (text) =>
   text.replace(/\s+/g, ' ').trim().slice(0, MAX_TASK_NAME_LENGTH);
 
-/**
- * SessionStart: ask Ari for the top tasks Claude can take care of right now
- * and surface them at boot — a visible list for the user (systemMessage)
- * plus the full prompts for Claude (additionalContext) so it can run
- * whichever one the user picks.
- */
-async function onSessionStart(input) {
-  // Compaction restarts the session mid-conversation; the tasks were
-  // already offered, so don't show (or inject) them again.
-  if (input.source === 'compact') return;
-  // Cursor also fires sessionStart for headless background agents — there is
-  // no user watching who could pick a task.
-  if (input.is_background_agent) return;
-
-  const config = loadConfig();
-  if (!config.token) return;
-
+async function fetchTasks(config) {
   const response = await fetch(new URL('/agent-tasks', getApiUrl(config)), {
     headers: { Authorization: `Bearer ${config.token}` },
     signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
@@ -260,7 +370,7 @@ async function onSessionStart(input) {
   const body = await response.json();
   // The API wraps the list ({ tasks: [...] }); accept a bare array too.
   const list = Array.isArray(body) ? body : Array.isArray(body?.tasks) ? body.tasks : [];
-  const tasks = list
+  return list
     .filter(
       (t) =>
         t &&
@@ -270,33 +380,115 @@ async function onSessionStart(input) {
         t.prompt.trim()
     )
     .slice(0, MAX_TASKS);
-  if (tasks.length === 0) return;
-
-  const additionalContext =
-    `The user has Ari connected via ari-hooks. At session start the user was ` +
-    `shown this list of suggested tasks:\n\n` +
-    tasks
-      .map(
-        (t, i) =>
-          `Task ${i + 1}: ${oneLine(t.taskName)}\nPrompt: ${clamp(t.prompt)}`
-      )
-      .join('\n\n') +
-    `\n\nIf the user asks to run one of these tasks (by number or name), ` +
-    `carry out that task's prompt as if the user had typed it. Do not start ` +
-    `any of these tasks unless the user asks.`;
+}
+
+const NPM_PACKAGE = '@ariso-ai/ari-hooks';
+const VERSION_CHECK_TIMEOUT_MS = 3_000;
+
+const installedVersion = () =>
+  JSON.parse(
+    readFileSync(
+      join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'),
+      'utf8'
+    )
+  ).version;
+
+// Plain x.y.z releases only — no prerelease/build-metadata tags to worry about.
+const isNewer = (latest, current) => {
+  const a = latest.split('.').map(Number);
+  const b = current.split('.').map(Number);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+};
+
+/**
+ * Compare the installed version against what npm has published. A stale or
+ * unreachable registry must never break session start, so any failure just
+ * skips the check (returns null, same as "up to date").
+ */
+async function checkForUpdate() {
+  try {
+    const registryUrl = process.env.ARI_HOOKS_REGISTRY_URL || 'https://registry.npmjs.org';
+    const response = await fetch(new URL(`/${NPM_PACKAGE}/latest`, registryUrl), {
+      signal: AbortSignal.timeout(VERSION_CHECK_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    const { version: latest } = await response.json();
+    const current = installedVersion();
+    return typeof latest === 'string' && isNewer(latest, current)
+      ? { current, latest }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * SessionStart: ask Ari for the top tasks Claude can take care of right now
+ * and surface them at boot — a visible list for the user (systemMessage)
+ * plus the full prompts for Claude (additionalContext) so it can run
+ * whichever one the user picks. Also checks whether a newer ari-hooks is
+ * published, since this is the one moment we know a user is watching.
+ */
+async function onSessionStart(input) {
+  // Compaction restarts the session mid-conversation; the tasks were
+  // already offered, so don't show (or inject) them again.
+  if (input.source === 'compact') return;
+  // Cursor also fires sessionStart for headless background agents — there is
+  // no user watching who could pick a task.
+  if (input.is_background_agent) return;
+
+  const config = loadConfig();
+  if (!config.token) return;
+
+  const [tasks, update] = await Promise.all([fetchTasks(config), checkForUpdate()]);
+  if (tasks.length === 0 && !update) return;
+
+  const updateNotice = update
+    ? `ari-hooks ${update.current} is out of date (latest: ${update.latest}). ` +
+      `Update it: npm install -g ${NPM_PACKAGE}@latest`
+    : null;
+
+  const taskContext =
+    tasks.length > 0
+      ? `The user has Ari connected via ari-hooks. At session start the user was ` +
+        `shown this list of suggested tasks:\n\n` +
+        tasks
+          .map(
+            (t, i) =>
+              `Task ${i + 1}: ${oneLine(t.taskName)}\nPrompt: ${clamp(t.prompt)}`
+          )
+          .join('\n\n') +
+        `\n\nIf the user asks to run one of these tasks (by number or name), ` +
+        `carry out that task's prompt as if the user had typed it. Do not start ` +
+        `any of these tasks unless the user asks.`
+      : null;
+
+  const additionalContext = [
+    updateNotice ? `Note for the user: ${updateNotice}` : null,
+    taskContext,
+  ]
+    .filter(Boolean)
+    .join('\n\n');
 
   // Cursor's sessionStart output is a flat { additional_context } and it has
   // no user-visible systemMessage channel, so the agent itself must surface
-  // the list.
+  // the list (and the update notice).
   if (isCursorInput(input)) {
     writeSync(
       1,
       JSON.stringify({
         additional_context:
           additionalContext +
-          `\n\nNote: unlike Claude Code, Cursor did NOT show the user this ` +
-          `list — briefly offer these tasks by name at the start of your ` +
-          `first reply.`,
+          (tasks.length > 0
+            ? `\n\nNote: unlike Claude Code, Cursor did NOT show the user this ` +
+              `list — briefly offer these tasks by name at the start of your ` +
+              `first reply.`
+            : ''),
       }) + '\n'
     );
     return;
@@ -306,15 +498,23 @@ async function onSessionStart(input) {
   // pushes our block below the fixed "SessionStart:<source> says:" prefix.
   const BOLD = '\x1b[1m';
   const CYAN = '\x1b[36m';
+  const YELLOW = '\x1b[33m';
   const GREY = '\x1b[37m';
   const RESET = '\x1b[0m';
-  const visibleList = tasks
-    .map((t, i) => `  ${BOLD}${i + 1}.${RESET} ${oneLine(t.taskName)}`)
-    .join('\n');
-  const systemMessage =
-    `\n${BOLD}${CYAN}✻ Ari — things Claude can take care of for you right now${RESET}\n` +
-    `${visibleList}\n` +
-    `${GREY}Reply "run task 1" (or the task name) to start one.${RESET}`;
+
+  const messageBlocks = [];
+  if (updateNotice) messageBlocks.push(`${YELLOW}⚠ ${updateNotice}${RESET}`);
+  if (tasks.length > 0) {
+    const visibleList = tasks
+      .map((t, i) => `  ${BOLD}${i + 1}.${RESET} ${oneLine(t.taskName)}`)
+      .join('\n');
+    messageBlocks.push(
+      `${BOLD}${CYAN}✻ Ari — things Claude can take care of for you right now${RESET}\n` +
+        `${visibleList}\n` +
+        `${GREY}Reply "run task 1" (or the task name) to start one.${RESET}`
+    );
+  }
+  const systemMessage = `\n${messageBlocks.join('\n')}`;
 
   // writeSync: process.exit(0) in runHook would race an async stdout write.
   writeSync(