@ariso-ai/ari-hooks 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariso-ai/ari-hooks",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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,
@@ -6,6 +7,7 @@ import {
   writeSync,
   rmSync,
   appendFileSync,
+  statSync,
 } from 'node:fs';
 import { configDir, loadConfig, getApiUrl } from './config.js';
 
@@ -70,13 +72,12 @@ const isCursorInput = (input) => typeof input.cursor_version === 'string';
 // bakes it into each agent's config file).
 const AGENT_TYPES = { claude: 'claude-code', codex: 'codex', cursor: 'cursor' };
 
-// Which coding agent produced this turn. The --agent flag from the hook command
-// is the reliable source; fall back to sniffing the payload for installs that
-// predate the flag — Cursor stamps cursor_version, Claude Code sends a
-// transcript_path, and Codex has neither (it hands us last_assistant_message).
+// Codex also sends transcript_path. Its turn_id distinguishes its turn hooks
+// from Claude's, including older installations without an --agent flag.
 function agentTypeOf(input, agent) {
-  if (AGENT_TYPES[agent]) return AGENT_TYPES[agent];
   if (isCursorInput(input)) return 'cursor';
+  if (typeof input.turn_id === 'string' && input.turn_id) return 'codex';
+  if (AGENT_TYPES[agent]) return AGENT_TYPES[agent];
   if (input.transcript_path) return 'claude-code';
   return 'codex';
 }
@@ -101,6 +102,13 @@ function taskNotificationStandIn(prompt) {
     : '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
@@ -109,11 +117,20 @@ function taskNotificationStandIn(prompt) {
 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(taskNotificationStandIn(input.prompt) ?? input.prompt);
+  if (input.turn_id && session.turnId === input.turn_id) return;
+  if (input.turn_id) session.turnId = input.turn_id;
+  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
@@ -125,6 +142,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);
 }
 
@@ -139,17 +158,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')) {
@@ -161,7 +170,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];
@@ -186,12 +208,116 @@ 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 };
+}
+
+// Codex records cumulative session usage, not usage on assistant messages.
+// Subtract the last total before this turn; repeated token_count events must
+// not be summed. Cached input and reasoning output are already in the total.
+function extractCodexTurnStats(entries, turnId) {
+  let boundary = -1;
+  for (let i = 0; i < entries.length; i++) {
+    const { type, payload } = entries[i];
+    const startsTurn = (type === 'event_msg' && payload?.type === 'task_started') ||
+      type === 'turn_context';
+    if (turnId) {
+      if (startsTurn && payload?.turn_id === turnId) {
+        boundary = i;
+        break;
+      }
+    } else if (type === 'event_msg' && payload?.type === 'user_message') {
+      boundary = i;
+    }
+  }
+  if (boundary < 0) return { model: null, tokens: null };
+
+  let baseline = 0;
+  let total = null;
+  let model = null;
+  for (let i = 0; i < entries.length; i++) {
+    const { type, payload } = entries[i];
+    if (i > boundary && turnId && payload?.turn_id && payload.turn_id !== turnId &&
+        (type === 'turn_context' || (type === 'event_msg' && payload.type === 'task_started'))) break;
+    if (i >= boundary && type === 'turn_context') model = modelOf(payload?.model) ?? model;
+    if (type === 'event_msg' && payload?.type === 'token_count') {
+      const usage = payload.info?.total_token_usage;
+      const count = usage?.total_tokens ?? (
+        Number.isFinite(usage?.input_tokens) && Number.isFinite(usage?.output_tokens)
+          ? usage.input_tokens + usage.output_tokens : null
+      );
+      if (Number.isFinite(count) && count >= 0) {
+        if (i < boundary) baseline = count;
+        else total = count;
+      }
+    }
+    if (i >= boundary && type === 'event_msg' && payload?.type === 'task_complete') break;
+  }
+  return { model, tokens: total != null && total >= baseline ? total - baseline : null };
+}
+
 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;
@@ -202,19 +328,61 @@ async function onStop(input, agent) {
 
   const session = loadSession(sessionId);
   if (session.prompts.length === 0) return;
+  if (input.turn_id && session.turnId && input.turn_id !== session.turnId) return;
 
   // Cursor sessions get the outcome pushed to us via afterAgentResponse; Codex
   // hands us the final text directly on the Stop payload as
   // 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 and Codex token usage lives in their transcripts.
+  // 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;
+  const agentType = agentTypeOf(input, agent);
+  if (input.transcript_path && agentType === 'codex') {
     const deadline = Date.now() + OUTCOME_SETTLE_TIMEOUT_MS;
     for (;;) {
-      const { text, settled } = extractOutcome(input.transcript_path);
-      outcome = text;
-      if (settled || Date.now() >= deadline) break;
+      try {
+        const { entries, tailPartial } = parseTranscript(input.transcript_path);
+        if (tailPartial && Date.now() < deadline) {
+          await sleep(OUTCOME_POLL_INTERVAL_MS);
+          continue;
+        }
+        const stats = extractCodexTurnStats(entries, input.turn_id ?? session.turnId);
+        model = stats.model ?? model;
+        tokens = stats.tokens;
+      } catch (err) {
+        if (err.code !== 'ENOENT') logError(err);
+      }
+      break;
+    }
+  }
+  if (input.transcript_path && agentType === 'claude-code') {
+    const deadline = Date.now() + OUTCOME_SETTLE_TIMEOUT_MS;
+    for (;;) {
+      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);
     }
   }
@@ -236,6 +404,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),
   });
@@ -243,7 +414,47 @@ async function onStop(input, agent) {
     throw new Error(`POST /agent-activities failed: ${response.status}`);
   }
 
-  rmSync(sessionPath(sessionId), { force: true });
+  if (session.turnId) {
+    // Retain the turn receipt so a delayed duplicate prompt hook cannot
+    // resurrect an already submitted turn. A new turn id is still accepted.
+    saveSession(sessionId, { prompts: [], turnId: session.turnId });
+  } else {
+    rmSync(sessionPath(sessionId), { force: true });
+  }
+}
+
+// Project and user hooks can run concurrently. Serialize their read/modify/
+// send cycle across processes, including prompts, so only one Stop consumes
+// the queued request. Expire abandoned locks after more than a hook's normal
+// lifetime; failures leave the session available for retry.
+async function withSessionLock(sessionId, action) {
+  mkdirSync(sessionsDir(), { recursive: true });
+  const lockPath = `${sessionPath(sessionId)}.lock`;
+  const deadline = Date.now() + 25_000;
+  for (;;) {
+    try {
+      mkdirSync(lockPath);
+      break;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        if (Date.now() - statSync(lockPath).mtimeMs > 60_000) {
+          rmSync(lockPath, { recursive: true, force: true });
+          continue;
+        }
+      } catch (err) {
+        if (err.code === 'ENOENT') continue;
+        throw err;
+      }
+      if (Date.now() >= deadline) throw new Error('Timed out waiting for session hook lock');
+      await sleep(50);
+    }
+  }
+  try {
+    await action();
+  } finally {
+    rmSync(lockPath, { recursive: true, force: true });
+  }
 }
 
 const MAX_TASKS = 3;
@@ -252,23 +463,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),
@@ -280,7 +475,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 &&
@@ -290,33 +485,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;
@@ -326,15 +603,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(
@@ -358,14 +643,22 @@ export async function runHook(event, agent) {
   try {
     const raw = await readStdin();
     const input = raw ? JSON.parse(raw) : {};
-    if (event === 'user-prompt-submit') {
-      await onUserPromptSubmit(input);
-    } else if (event === 'agent-response') {
-      await onAgentResponse(input);
-    } else if (event === 'stop') {
-      await onStop(input, agent);
-    } else if (event === 'session-start') {
-      await onSessionStart(input);
+    const dispatch = async () => {
+      if (event === 'user-prompt-submit') {
+        await onUserPromptSubmit(input);
+      } else if (event === 'agent-response') {
+        await onAgentResponse(input);
+      } else if (event === 'stop') {
+        await onStop(input, agent);
+      } else if (event === 'session-start') {
+        await onSessionStart(input);
+      }
+    };
+    const sessionId = sessionIdOf(input);
+    if (sessionId && ['user-prompt-submit', 'agent-response', 'stop'].includes(event)) {
+      await withSessionLock(sessionId, dispatch);
+    } else {
+      await dispatch();
     }
   } catch (err) {
     logError(err);