@ramarivera/coding-buddy 0.7.3 → 0.9.0

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");

package/server/state.ts

@@ -31,6 +31,9 @@ import {
 } from "fs";
 import { join } from "path";
 import type { Companion } from "../core/engine.ts"
+import type * as CoreEngine from "../core/engine.ts";
+import type * as Art from "./art.ts";
+import { configuredSharedUserId } from "../core/identity.ts";
 import {
   buddyStateDir,
   claudeSettingsPath,
@@ -278,32 +281,63 @@ function migrateIfNeeded(): void {
 
 // ─── Reaction state (session-scoped for tmux isolation) ──────────────────────
 
+/**
+ * Where a reaction came from. Proves the bubble content isn't canned when
+ * source === "tool" or "comment"; "fallback" means a hook picked a pool line
+ * because no model-authored text surfaced; "none" is the default for legacy
+ * files written before the field existed.
+ *
+ *   tool      — buddy_react MCP tool call (Claude wrote it; renders nowhere)
+ *   comment   — old `<!-- buddy: ... -->` HTML comment (legacy / older CC)
+ *   fallback  — Stop hook generated it from the canned pool
+ *   none      — unknown / legacy file without a source field
+ */
+export type ReactionSource = "tool" | "comment" | "fallback" | "none";
+
 export interface ReactionState {
   reaction: string;
   timestamp: number;
   reason: string;
+  /** Provenance — see ReactionSource. Defaults to "none" on legacy files. */
+  source?: ReactionSource;
 }
 
 export function loadReaction(): ReactionState | null {
   try {
     const data: ReactionState = JSON.parse(readFileSync(reactionFile(), "utf8"));
     const { reactionTTL } = loadConfig();
-    if (reactionTTL > 0 && Date.now() - data.timestamp > reactionTTL * 1000) return null;
+if (reactionTTL > 0 && Date.now() - data.timestamp > reactionTTL * 1000) {
+  rmSync(reactionFile(), { force: true });
+  return null;
+}
+if (data.source === undefined) data.source = "none";
     return data;
   } catch {
     return null;
   }
 }
 
-export function saveReaction(reaction: string, reason: string): void {
+export function saveReaction(
+  reaction: string,
+  reason: string,
+  source: ReactionSource = "fallback",
+): void {
   mkdirSync(STATE_DIR, { recursive: true });
-  const state: ReactionState = { reaction, timestamp: Date.now(), reason };
-  writeFileSync(reactionFile(), JSON.stringify(state));
+  const state: ReactionState = { reaction, timestamp: Date.now(), reason, source };
+  // Atomic via tmp + rename — torn reads on the reaction file would
+  // make the Stop hook's freshness check see an absent file, pinning
+  // a stale tool reaction into the bubble forever.
+  const target = reactionFile();
+  const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(state));
+  renameSync(tmp, target);
 }
 
 // ─── Identity resolution ─────────────────────────────────────────────────────
 
 export function resolveUserId(): string {
+  const sharedUserId = configuredSharedUserId();
+  if (sharedUserId) return sharedUserId;
   try {
     const claudeJson = JSON.parse(readFileSync(claudeUserConfigPath(), "utf8"));
     return claudeJson.oauthAccount?.accountUuid ?? claudeJson.userID ?? "anon";
@@ -311,9 +345,7 @@ export function resolveUserId(): string {
     return "anon";
   }
 }
-
 // ─── Config persistence (PR #6: tmux popup settings) ─────────────────────────
-
 export interface BuddyConfig {
   commentCooldown: number;
   reactionTTL: number;
@@ -321,10 +353,12 @@ export interface BuddyConfig {
   bubblePosition: "top" | "left";
   showRarity: boolean;
   statusLineEnabled: boolean;
+  statuslineWidthAdjust: number;
   bubbleWidth: number;
   bubbleMargin: number;
   useCombinedStatus: boolean;
   subStatusCommand?: string;
+  subStatusRefreshSeconds: number;
   rainbowColors?: string[];
   theme: "dark" | "light" | "auto";
   moodEnabled: boolean;
@@ -335,14 +369,19 @@ export interface BuddyConfig {
 
 const DEFAULT_CONFIG: BuddyConfig = {
   commentCooldown: 30,
-  reactionTTL: 0,
+  // Long enough that a reaction survives the turn you were reading when it was
+  // written, short enough that yesterday's bubble is never still on screen.
+  // Set to 0 to opt out and keep reactions until they are replaced.
+  reactionTTL: 900,
   bubbleStyle: "classic",
   bubblePosition: "top",
   showRarity: true,
   statusLineEnabled: false,
+  statuslineWidthAdjust: 0,
   bubbleWidth: 28,
   bubbleMargin: 8,
   useCombinedStatus: false,
+  subStatusRefreshSeconds: 15,
   theme: "auto",
   moodEnabled: true,
   memoryEnabled: true,
@@ -358,6 +397,15 @@ export function normalizeConfig(data: unknown): BuddyConfig {
   if (typeof config.subStatusCommand !== "string" || config.subStatusCommand.trim() === "") {
     delete config.subStatusCommand;
   }
+  if (!Number.isInteger(config.subStatusRefreshSeconds) || config.subStatusRefreshSeconds <= 0) {
+    config.subStatusRefreshSeconds = DEFAULT_CONFIG.subStatusRefreshSeconds;
+  }
+  if (!Number.isInteger(config.reactionTTL) || config.reactionTTL < 0) {
+    config.reactionTTL = DEFAULT_CONFIG.reactionTTL;
+  }
+  if (!Number.isInteger(config.statuslineWidthAdjust)) {
+    config.statuslineWidthAdjust = DEFAULT_CONFIG.statuslineWidthAdjust;
+  }
   return config;
 }
 
@@ -407,10 +455,11 @@ export function writeStatusState(
   xp?: number,
 ): void {
   mkdirSync(STATE_DIR, { recursive: true });
-  const { renderFace, RARITY_STARS } =
-    require("../core/engine.ts") as typeof import("../core/engine.ts");
+  const { renderFace, RARITY_STARS, resolveEyeGlyph } =
+    require("../core/engine.ts") as typeof CoreEngine;
   const { getStatusFrames } =
-    require("./art.ts") as typeof import("./art.ts");
+    require("./art.ts") as typeof Art;
+  const safeEye = resolveEyeGlyph(companion.bones.eye);
   const { frames, frameSequence } = getStatusFrames(companion.bones);
   let xpLevel = level ?? 1;
   let xpTotal = xp ?? 0;
@@ -434,8 +483,8 @@ export function writeStatusState(
     species: companion.bones.species,
     rarity: companion.bones.rarity,
     stars: RARITY_STARS[companion.bones.rarity],
-    face: renderFace(companion.bones.species, companion.bones.eye),
-    eye: companion.bones.eye,
+    face: renderFace(companion.bones.species, safeEye),
+    eye: safeEye,
     shiny: companion.bones.shiny,
     hat: companion.bones.hat,
     reaction: "",
@@ -447,14 +496,16 @@ export function writeStatusState(
     xp: xpTotal,
     mood: moodStr,
   };
-  writeFileSync(join(STATE_DIR, "status.json"), JSON.stringify(state));
-  if (reaction) saveReaction(reaction, "mcp");
+  // writeStatusState no longer calls saveReaction implicitly. Callers
+  // that need a reaction file do so explicitly with the correct
+  // `source` tag — the old implicit save had no source argument and
+  // its default later flipped from "tool" to "fallback", either way
+  // overwriting provenance of hatch / pet / unmute writes with whatever
+  // happened to be the default. /buddy stats stopped lying when
+  // this call was removed.
 }
 
-// ─── Claude Code settings.json patching (for buddy_statusline tool) ──────────
-
 export const CLAUDE_SETTINGS_PATH = claudeSettingsPath();
-
 /**
  * Write settings.statusLine pointing to the given buddy-status script.
  * Atomic via tmp + rename. Returns false if settings.json is unreachable.

package/skills/buddy/SKILL.md

@@ -86,7 +86,7 @@ The MCP tools return pre-formatted ASCII art with ANSI colors, box-drawing chara
 
 **Just output the raw text content from the tool result. Nothing else.** The ASCII art IS the response.
 
-If the user mentions the buddy's name in normal conversation, call `buddy_react` with reason "turn" and display the result verbatim.
+If the user mentions the buddy's name in normal conversation, call `buddy_react` with reason "turn". Do NOT echo or quote the tool result — the reaction reaches the user only via the statusline speech bubble.
 
 ## Uninstall Orchestration