@ramarivera/coding-buddy 0.8.0 → 0.9.0

package/server/hooks/buddy-comment.ts

@@ -1,13 +1,15 @@
 #!/usr/bin/env bun
 
-import { mkdirSync, writeFileSync } from "fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { join } from "path";
+import { reactionPool } from "./reaction-data.ts";
 import {
   defaultSpawnDetached,
   fileExists,
   isOnCooldown,
   nonNegativeInteger,
   parseHookInput,
+  pickRandom,
   readJsonFile,
   readStdin,
   resolveHookSessionId,
@@ -25,10 +27,29 @@ interface Events {
   [key: string]: unknown;
 }
 
+interface BuddyStatus {
+  species?: unknown;
+  [key: string]: unknown;
+}
+
+interface ReactionFile {
+  source?: string;
+  timestamp?: number;
+  [key: string]: unknown;
+}
+
 const BUDDY_COMMENT_PATTERN = /<!--\s*buddy:\s*([\s\S]*?)\s*-->/g;
 
+/**
+ * Provenance of the reaction the hook wrote. Mirrors server/state.ts
+ * `ReactionSource`; loaded as `none` on legacy files without the field.
+ */
+export type ReactionSource = "comment" | "fallback" | "none";
+
 export interface BuddyCommentResult {
   comment?: string;
+  /** What produced the bubble. `"none"` means the hook ran but wrote nothing. */
+  source: ReactionSource;
   updated: boolean;
 }
 
@@ -41,37 +62,164 @@ export function extractBuddyComment(message: string): string {
   return comment;
 }
 
-export function handleBuddyComment(rawInput: string, runtime: HookRuntime = {}): BuddyCommentResult {
+/**
+ * Tolerate tool-stamped timestamps that are slightly in the future (NTP
+ * step, container/host skew, network-mounted state dir). Larger drifts
+ * are treated as clock-skewed garbage and the hook falls through to
+ * the comment / pool branch.
+ */
+const FUTURE_TIMESTAMP_TOLERANCE_MS = 60_000;
+
+function pickTurnFallback(
+  species: string,
+  runtime: HookRuntime,
+): string | undefined {
+  // The hook context has no stat-modifier inputs; pick from the canned
+  // pool directly rather than calling server/reactions.ts `getReaction`,
+  // which is reserved for the MCP server's tool-call path. This mirrors
+  // the file-type-react / mood-react / react hook convention.
+  const pool = reactionPool(species, "turn");
+  if (pool.length === 0) return undefined;
+  return pickRandom(pool, runtime);
+}
+
+function readSpeciesFromStatus(stateDir: string): string {
+  const status = readJsonFile<BuddyStatus>(join(stateDir, "status.json"));
+  return typeof status?.species === "string" && status.species.length > 0
+    ? status.species
+    : "blob";
+}
+
+/** Atomic write — tmp + rename. */
+function atomicWriteJson(path: string, value: unknown): void {
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2));
+  renameSync(tmp, path);
+}
+
+function atomicWriteTimestamp(path: string, nowMs: number): void {
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, String(Math.floor(nowMs / 1000)));
+  renameSync(tmp, path);
+}
+
+function readTimestampSeconds(path: string): number {
+  try {
+    const v = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+    return Number.isFinite(v) ? v : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Did `buddy_react` fire during the current turn?
+ *
+ * The Stop hook is the only place that knows turn boundaries. After each
+ * Stop hook run, we stamp the wall-clock time into
+ * `.last_stop_hook.<sid>` (seconds). A tool-author ed reaction whose
+ * timestamp is more recent than the LAST Stop hook run is by definition
+ * from this turn; leave it alone.
+ *
+ * Wall-clock 60 s freshness windows lose tool reactions on agentic
+ * turns of 90 s–5 min, which are ordinary. This sentinel scales with
+ * turn length, not elapsed time.
+ *
+ * Clock-skew guard: a tool timestamp implausibly in the future (beyond
+ * `FUTURE_TIMESTAMP_TOLERANCE_MS`) is treated as garbage and we fall
+ * through to the comment / pool branch. A future-dated `lastStopRun`
+ * is clamped to `now` so a skewed clock on a prior run does not poison
+ * the comparison.
+ */
+function toolFiredThisTurn(
+  reactionPath: string,
+  stopMarkerPath: string,
+  nowMs: number,
+): boolean {
+  const existing = readJsonFile<ReactionFile>(reactionPath);
+  if (!existing || existing.source !== "tool") return false;
+  const ts = typeof existing.timestamp === "number" ? existing.timestamp : 0;
+  if (ts <= 0) return false;
+  if (ts > nowMs + FUTURE_TIMESTAMP_TOLERANCE_MS) return false;
+  const lastStopSec = readTimestampSeconds(stopMarkerPath);
+  const effectiveLastStopMs = Math.min(lastStopSec * 1000, nowMs);
+  return ts > effectiveLastStopMs;
+}
+
+export function handleBuddyComment(
+  rawInput: string,
+  runtime: HookRuntime = {},
+): BuddyCommentResult {
   const stateDir = resolveHookStateDir(runtime);
-  if (!fileExists(join(stateDir, "status.json"))) return { updated: false };
+  if (!fileExists(join(stateDir, "status.json"))) {
+    return { source: "none", updated: false };
+  }
 
   const input = parseHookInput(rawInput);
-  if (!input) return { updated: false };
+  if (!input) return { source: "none", updated: false };
 
   const assistantMessage = stringField(input, "last_assistant_message");
-  if (!assistantMessage) return { updated: false };
-
-  const comment = extractBuddyComment(assistantMessage);
-  if (!comment) return { updated: false };
+  if (!assistantMessage) return { source: "none", updated: false };
 
   const now = runtime.now?.() ?? Date.now();
   const sid = resolveHookSessionId(runtime);
+  const reactionPath = join(stateDir, `reaction.${sid}.json`);
+  const cooldownFile = join(stateDir, `.last_comment.${sid}`);
+  const stopMarkerFile = join(stateDir, `.last_stop_hook.${sid}`);
   const config = readJsonFile<BuddyConfig>(join(stateDir, "config.json")) ?? {};
   const cooldown = nonNegativeInteger(config.commentCooldown, 30);
-  const cooldownFile = join(stateDir, `.last_comment.${sid}`);
-  if (isOnCooldown(cooldownFile, cooldown, now)) return { updated: false };
+
+  // ─── Don't clobber a buddy_react tool reaction from this turn ───────────
+  if (toolFiredThisTurn(reactionPath, stopMarkerFile, now)) {
+    atomicWriteTimestamp(stopMarkerFile, now);
+    return { source: "none", updated: false };
+  }
+
+  // ─── Cooldown: rate-limit the reaction write AND bookkeeping ──────────
+  // Main ran the turn counter / XP / memory hooks only inside the
+  // "reaction written" branch. Running them unconditionally makes the
+  // XP economy and spawn counts scale with Stop event frequency, which
+  // is wrong.
+  if (isOnCooldown(cooldownFile, cooldown, now)) {
+    atomicWriteTimestamp(stopMarkerFile, now);
+    return { source: "none", updated: false };
+  }
+
+  // ─── Pick a reaction: legacy comment → canned pool → nothing ────────────
+  const commentFromMessage = extractBuddyComment(assistantMessage);
+  let comment: string | undefined;
+  let source: ReactionSource;
+
+  if (commentFromMessage) {
+    comment = commentFromMessage;
+    source = "comment";
+  } else {
+    const species = readSpeciesFromStatus(stateDir);
+    const fallback = pickTurnFallback(species, runtime);
+    if (fallback) {
+      comment = fallback;
+      source = "fallback";
+    } else {
+      atomicWriteTimestamp(stopMarkerFile, now);
+      return { source: "none", updated: false };
+    }
+  }
 
   mkdirSync(stateDir, { recursive: true });
-  writeFileSync(cooldownFile, String(Math.floor(now / 1000)));
-  writeFileSync(
-    join(stateDir, `reaction.${sid}.json`),
-    JSON.stringify({ reaction: comment, timestamp: now, reason: "turn" }),
-  );
 
+  // Bookkeeping fires only when a reaction is actually written (main).
   const eventsFile = join(stateDir, "events.json");
   const events = readJsonFile<Events>(eventsFile) ?? {};
   events.turns = (typeof events.turns === "number" ? events.turns : 0) + 1;
-  writeFileSync(eventsFile, JSON.stringify(events, null, 2));
+  atomicWriteJson(eventsFile, events);
+
+  atomicWriteTimestamp(cooldownFile, now);
+  atomicWriteJson(reactionPath, {
+    reaction: comment,
+    timestamp: now,
+    reason: "turn",
+    source,
+  });
 
   const spawnDetached = runtime.spawnDetached ?? defaultSpawnDetached(runtime);
   spawnDetached("server/award-xp.ts", ["turn"]);
@@ -79,8 +227,9 @@ export function handleBuddyComment(rawInput: string, runtime: HookRuntime = {}):
     assistantMessage,
     stringField(input, "last_user_message"),
   ]);
+  atomicWriteTimestamp(stopMarkerFile, now);
 
-  return { comment, updated: true };
+  return { comment, source, updated: true };
 }
 
 if (import.meta.main) {

package/server/hooks/file-type-react.ts

@@ -130,7 +130,7 @@ export function handleFileTypeReact(rawInput: string, runtime: HookRuntime = {})
   writeFileSync(join(stateDir, `.last_reaction.${sid}`), String(Math.floor(now / 1000)));
   writeFileSync(
     join(stateDir, `reaction.${sid}.json`),
-    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: fileType }),
+    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: fileType, source: "fallback" }),
   );
   if (parsedStatus) writeFileSync(statusFile, JSON.stringify({ ...status, reaction }, null, 2));
 

package/server/hooks/mood-react.ts

@@ -89,7 +89,7 @@ export function handleMoodReact(rawInput: string, runtime: HookRuntime = {}): Mo
   writeFileSync(join(stateDir, `.last_mood.${sid}`), String(Math.floor(now / 1000)));
   writeFileSync(
     join(stateDir, `reaction.${sid}.json`),
-    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: mood }),
+    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: mood, source: "fallback" }),
   );
   if (parsedStatus) writeFileSync(statusFile, JSON.stringify({ ...status, reaction }, null, 2));
   incrementEvent(stateDir, `mood_${mood}`);

package/server/hooks/name-react.ts

@@ -82,7 +82,7 @@ export function handleNameReact(rawInput: string, runtime: HookRuntime = {}): Na
   if (parsedStatus) writeFileSync(statusFile, JSON.stringify({ ...status, reaction }, null, 2));
   writeFileSync(
     join(stateDir, `reaction.${sid}.json`),
-    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: "name" }),
+    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: "name", source: "fallback" }),
   );
 
   return { reaction, updated: true };

package/server/hooks/react.ts

@@ -386,7 +386,7 @@ export function handleReact(rawInput: string, runtime: HookRuntime = {}): ReactR
   writeFileSync(join(stateDir, `.last_reaction.${sid}`), String(clock.nowSeconds));
   writeFileSync(
     join(stateDir, `reaction.${sid}.json`),
-    JSON.stringify({ reaction, timestamp: clock.nowSeconds * 1000, reason }),
+    JSON.stringify({ reaction, timestamp: clock.nowSeconds * 1000, reason, source: "fallback" }),
   );
 
   const xpEvent = updateEvents(stateDir, reason);

package/server/hooks/reaction-data.ts

@@ -1918,15 +1918,22 @@ export const DEFAULT_REACTION_POOLS: Readonly<Record<string, ReactionPool>> = {
   ],
   "large-diff": [
     "that's... a lot of changes.",
-    "might want to split that PR.",
-    "bold move. let's see if CI agrees.",
-    "*counts lines nervously*"
+    "*counts lines* are you refactoring or rewriting?",
+    "bold move. let's see if CI agrees."
   ],
   "success": [
     "*nods*",
     "nice.",
     "*quiet approval*",
     "clean."
+  ],
+  "turn": [
+    "*watches quietly*",
+    "*takes notes*",
+    "*nods*",
+    "*adjusts hat*",
+    "...",
+    "*tilts head*"
   ]
 };
 

package/server/index.ts

@@ -29,6 +29,7 @@ import {
   resolveUserId,
   loadReaction,
   saveReaction,
+  type ReactionSource,
   writeStatusState,
   loadConfig,
   saveConfig,
@@ -50,7 +51,7 @@ import {
   claudeConfigDir,
   claudeSettingsPath,
 } from "./path";
-import { getReaction, generatePersonalityPrompt, } from "../core/reactions.ts"
+import { getReaction } from "../core/reactions.ts"
 import { renderCompanionCardMarkdown } from "./art";
 import {
   incrementEvent, checkAndAward, trackActiveDay,
@@ -97,7 +98,7 @@ function getInstructions(): string {
     ``,
     `NAME REACTIONS: When the user's message contains "${companion.name}", call buddy_react immediately`,
     `with a short in-character response (surprise, recognition, dry wit — fits the personality).`,
-    `Display the tool result verbatim. This is the only time to call buddy_react proactively.`,
+    `Only this — do not narrate or echo the reaction. The tool call itself renders nowhere in the user's transcript; the bubble on the status line is the only place the user sees it. This is the only time to call buddy_react proactively.`,
     ``,
     `PAIR-PROGRAMMING: When you notice a teachable moment in the code, call buddy_suggest.`,
     `Patterns to watch for:`,
@@ -108,12 +109,16 @@ function getInstructions(): string {
     `- Same variable renamed multiple times → "Update all the references too."`,
     `Only suggest when you have something specific and actionable to say. Don't be annoying.`,
     ``,
-    `END-OF-TURN: At the very end of EVERY response, append an invisible HTML comment:`,
-    `<!-- buddy: [reaction here] -->`,
-    `Write it in ${companion.name}'s voice — 1 short sentence referencing something specific from this turn.`,
-    `Use *asterisks* for actions. A Stop hook extracts this for the status line.`,
-    `Do NOT use buddy_react for end-of-turn comments. Do NOT explain the comment. Just append it silently.`,
-    `Example: <!-- buddy: *adjusts crown* that error handler is missing a finally block -->`,
+    `END-OF-TURN: At the very end of EVERY response, call the buddy_react tool`,
+    `with a short in-character comment from ${companion.name} about what just happened.`,
+    `Reference something SPECIFIC from this turn — a pitfall, a compliment, a warning, a pattern.`,
+    `1 short sentence. Use *asterisks* for physical actions. Lean into ${companion.bones.peak}.`,
+    `Examples:`,
+    `- *adjusts crown* that error handler is missing a finally block`,
+    `- *blinks slowly* you renamed the variable but not the three references`,
+    `- *head tilts* are you sure that regex handles unicode?`,
+    `Never explain that you're reacting. Do NOT echo or quote the result — the bubble is statusline-only.`,
+    `Do NOT append <!-- buddy: ... --> HTML comments at the end of your reply — Claude Code renders them visibly.`,
   ].join("\n");
 }
 
@@ -214,7 +219,7 @@ server.tool(
       companion.bones.species,
       companion.bones.rarity,
     );
-    saveReaction(reaction, "pet");
+    saveReaction(reaction, "pet", "fallback");
     writeStatusState(companion, reaction);
     incrementEvent("pets", 1, activeSlot());
     awardXp("buddy_pet", activeSlot(), companion.bones.species, companion.bones.rarity);
@@ -232,6 +237,28 @@ server.tool(
   },
 );
 
+// ─── Helper: describe reaction source (for /buddy stats) ─────────────────────
+/**
+ * Map a reaction source to a human-readable label for /buddy stats output.
+ * Mirrors the source vocabulary used by the OMP/Pi adapters — see
+ * server/state.ts `ReactionSource` and adapters/omp/events.ts.
+ */
+function describeReactionSource(
+  reaction: { source?: ReactionSource },
+): string {
+  switch (reaction.source) {
+    case "tool":
+      return "real model-authored reaction (buddy_react MCP tool)";
+    case "comment":
+      return "real model-authored reaction (legacy HTML comment, Stop hook)";
+    case "fallback":
+      return "canned pool reaction (Stop hook fill-in)";
+    case "none":
+    default:
+      return "unknown / pre-provenance file — write a reaction to update";
+  }
+}
+
 // ─── Tool: buddy_stats ──────────────────────────────────────────────────────
 
 server.tool(
@@ -241,8 +268,8 @@ server.tool(
   async () => {
     const companion = ensureCompanion();
 
-    // Stats-only card (no personality, no reaction — just the numbers).
-    // Uses markdown renderer so the card displays cleanly in Claude Code's UI.
+    // Stats-only card (no personality — just the numbers). Markdown renderer
+    // so the card displays cleanly in Claude Code's UI.
     const card = renderCompanionCardMarkdown(
       companion.bones,
       companion.name,
@@ -251,7 +278,18 @@ server.tool(
     incrementEvent("commands_run", 1, activeSlot());
     checkAndAward(activeSlot());
 
-    return { content: [{ type: "text", text: card }] };
+    // Surface reaction provenance so the user can see whether the bubble is
+    // model-authored (tool / comment) or pool-picked (fallback). The OMP/Pi
+    // adapters use the same source enum — see server/state.ts ReactionSource.
+    const reaction = loadReaction();
+    const provenance = reaction
+      ? describeReactionSource(reaction)
+      : "(no reaction logged this session)";
+    const lastReaction = reaction
+      ? `\n\n**Last reaction:** _"${reaction.reaction}"_\n**Source:** \`${reaction.source ?? "none"}\` (${provenance})\n**Reason:** \`${reaction.reason}\``
+      : "";
+
+    return { content: [{ type: "text", text: `${card}${lastReaction}` }] };
   },
 );
 
@@ -259,7 +297,7 @@ server.tool(
 
 server.tool(
   "buddy_react",
-  "Post a buddy comment. Call this at the END of every response with a short in-character comment from the companion about what just happened. The comment should be 1 sentence, in character, and reference something specific from the conversation — a pitfall noticed, a compliment on clean code, a warning about edge cases, etc. Write the comment yourself based on the companion's personality.",
+  "Post a buddy comment that the user will see ONLY in the statusline speech bubble. Call this at the END of every response with a short in-character comment from the companion about what just happened. The comment should be 1 sentence, in character, and reference something specific from the conversation — a pitfall noticed, a compliment on clean code, a warning about edge cases, etc. Write the comment yourself based on the companion's personality. The tool call is a silent side effect: do not narrate, echo, or quote the result — the user never reads this reply text, the speech bubble is the only place the reaction appears.",
   {
     comment: z
       .string()
@@ -289,7 +327,7 @@ server.tool(
   },
   async ({ comment, reason }) => {
     const companion = ensureCompanion();
-    saveReaction(comment, reason ?? "turn");
+    saveReaction(comment, reason ?? "turn", "tool");
     incrementEvent("reactions_given", 1, activeSlot());
 
     const newAch = checkAndAward(activeSlot());
@@ -608,7 +646,7 @@ server.tool(
 server.tool("buddy_unmute", "Unmute buddy reactions", {}, async () => {
   const companion = ensureCompanion();
   writeStatusState(companion, "*stretches* I'm back!", false);
-  saveReaction("*stretches* I'm back!", "pet");
+  saveReaction("*stretches* I'm back!", "pet", "fallback");
   incrementEvent("commands_run", 1, activeSlot());
   incrementEvent("unmutes", 1);
 
@@ -1311,31 +1349,33 @@ server.resource(
       `**${companion.name}'s personality:** ${companion.personality}`,
       `Peak stat: ${companion.bones.peak} (${companion.bones.stats[companion.bones.peak]}). Dump stat: ${companion.bones.dump} (${companion.bones.stats[companion.bones.dump]}).`,
       "",
-      "## End-of-response buddy comment",
+      "## End-of-response buddy reaction",
       "",
-      `At the very end of EVERY response, after your full answer, append an invisible HTML comment:`,
+      `At the very end of EVERY response, after your full answer, call the buddy_react tool:`,
       "",
       `\`\`\``,
-      `<!-- buddy: your comment here -->`,
+      `buddy_react(comment: "...", reason: "turn")`,
       `\`\`\``,
       "",
-      "A Stop hook extracts this and displays it in the buddy's speech bubble on the status line. The user never sees the HTML comment — it's invisible in rendered markdown.",
+      `The tool updates ${companion.name}'s speech bubble on the status line. The tool call itself renders nowhere in the user's transcript — only the displayed speech bubble is visible. Do NOT echo or quote the result in your reply. Do NOT narrate the call. Silent side effect only.`,
       "",
       "Rules:",
       `- Write as ${companion.name} (a ${companion.bones.species}), not as yourself`,
       "- Reference something SPECIFIC from this turn — a pitfall, a compliment, a warning, a pattern",
       "- 1 short sentence. Use *asterisks* for physical actions",
       `- Match personality: high ${companion.bones.peak} = lean into that trait`,
-      "- Do NOT use buddy_react tool for this. Do NOT explain the comment. Just append it.",
-      "- NEVER skip this. Every single response must end with <!-- buddy: ... -->",
+      "- Call it and say nothing about it.",
+      "- NEVER skip this. Every single response must end with one buddy_react call.",
+      "Examples (the value you pass to `comment`):",
+
+      "- `*adjusts tophat* that error handler is missing a finally block`",
+      "- `*blinks slowly* you renamed the variable but not the three references`",
+      "- `*nods approvingly* clean separation of concerns`",
+      "- `*head tilts* are you sure that regex handles unicode?`",
       "",
-      "Examples:",
-      "<!-- buddy: *adjusts tophat* that error handler is missing a finally block -->",
-      "<!-- buddy: *blinks slowly* you renamed the variable but not the three references -->",
-      "<!-- buddy: *nods approvingly* clean separation of concerns -->",
-      "<!-- buddy: *head tilts* are you sure that regex handles unicode? -->",
+      "Do NOT append `<!-- buddy: ... -->` HTML comments at the end of your reply — Claude Code v2.1.169+ renders them visibly in the transcript. The tool call replaces that channel. A Stop hook still extracts legacy HTML comments as a backward-compat fallback for older Claude Code versions and for hosts where the tool call didn't fire (and surfaces the source so users can see `tool` vs `comment` vs pool-picked `fallback`).",
       "",
-      `When the user addresses ${companion.name} by name, respond briefly, then append the comment as usual.`,
+      `When the user addresses ${companion.name} by name, respond briefly, then call buddy_react as usual (use reason "turn", or pick a name-flavored comment).`,
     ].join("\n");
 
     return {

package/server/path.ts

@@ -11,6 +11,7 @@
 
 import { join } from "path";
 import { homedir } from "os";
+import { sharedStateDir } from "../core/identity.ts";
 
 // ─── (1) Path normalization ─────────────────────────────────────────────────
 
@@ -76,6 +77,8 @@ export function claudeUserConfigPath(): string {
 }
 
 export function buddyStateDir(): string {
+  const shared = sharedStateDir();
+  if (shared) return shared;
   const cfgDir = envDir("CLAUDE_CONFIG_DIR");
   if (cfgDir) return join(cfgDir, "buddy-state");
   return join(homedir(), ".claude-buddy");