@ramarivera/coding-buddy 0.9.4 → 0.9.5

package/server/index.ts

@@ -9,6 +9,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { REACT_REASONS, normalizeReactArgs } from "./react-args.ts";
 import { existsSync } from "fs";
 import { join, resolve, dirname } from "path";
 // The version advertised in the MCP handshake. Imported rather than written
@@ -304,33 +305,33 @@ server.tool(
   {
     comment: z
       .string()
-      .min(1)
-      .max(150)
+      .optional()
       .describe(
-        "The buddy's comment, written in-character (1 short sentence, max 150 chars). Use *asterisks* for actions.",
+        "The buddy's comment, written in-character (1 short sentence, max 150 chars; longer text is shortened). Use *asterisks* for actions. Always send it: a call with no comment returns an error.",
       ),
+    reaction: z
+      .string()
+      .optional()
+      .describe("Deprecated alias for `comment`. Send `comment` instead."),
     reason: z
-      .enum([
-        "error", "test-fail", "large-diff", "turn",
-        "commit", "push", "merge-conflict", "branch", "rebase", "stash", "tag",
-        "late-night", "early-morning", "long-session", "marathon", "friday", "weekend", "monday",
-        "regex-file", "css-file", "sql-file", "docker-file", "ci-file", "lock-file",
-        "env-file", "test-file", "doc-file", "config-file", "binary-file", "gitignore",
-        "makefile", "readme", "package-file", "proto-file",
-        "lint-fail", "type-error", "build-fail", "security-warning", "deprecation",
-        "frustrated", "happy", "stuck", "sarcastic",
-        "many-edits", "delete-file", "large-file", "create-file",
-        "all-green", "deploy", "release", "coverage",
-        "debug-loop", "write-spree", "search-heavy",
-        "recovery-from-error", "recovery-from-test-fail",
-        "recovery-from-build-fail", "recovery-from-merge-conflict",
-      ])
+      .string()
       .optional()
-      .describe("What triggered the reaction"),
+      .describe(
+        `What triggered the reaction. One of: ${REACT_REASONS.join(", ")}. Defaults to "turn"; unknown values are treated as "turn".`,
+      ),
   },
-  async ({ comment, reason }) => {
+  async (raw) => {
+    const { comment, reason } = normalizeReactArgs(raw);
+    if (comment === null) {
+      return {
+        isError: true,
+        content: [
+          { type: "text", text: 'buddy_react needs a non-empty `comment` string, for example {"comment": "*nods* clean diff", "reason": "turn"}.' },
+        ],
+      };
+    }
     const companion = ensureCompanion();
-    saveReaction(comment, reason ?? "turn", "tool");
+    saveReaction(comment, reason, "tool");
     incrementEvent("reactions_given", 1, activeSlot());
 
     const newAch = checkAndAward(activeSlot());

package/server/react-args.ts

@@ -0,0 +1,64 @@
+/**
+ * Argument handling for the buddy_react tool.
+ *
+ * Agents often call buddy_react without having read its schema: the tool is
+ * deferred in Claude Code, so the model guesses argument names. A strict
+ * schema turned those guesses into MCP -32602 errors and agents then reported
+ * the buddy as unavailable. The tool accepts the common guesses instead and
+ * normalizes them here.
+ */
+
+export const REACT_REASONS = [
+  "error", "test-fail", "large-diff", "turn",
+  "commit", "push", "merge-conflict", "branch", "rebase", "stash", "tag",
+  "late-night", "early-morning", "long-session", "marathon", "friday", "weekend", "monday",
+  "regex-file", "css-file", "sql-file", "docker-file", "ci-file", "lock-file",
+  "env-file", "test-file", "doc-file", "config-file", "binary-file", "gitignore",
+  "makefile", "readme", "package-file", "proto-file",
+  "lint-fail", "type-error", "build-fail", "security-warning", "deprecation",
+  "frustrated", "happy", "stuck", "sarcastic",
+  "many-edits", "delete-file", "large-file", "create-file",
+  "all-green", "deploy", "release", "coverage",
+  "debug-loop", "write-spree", "search-heavy",
+  "recovery-from-error", "recovery-from-test-fail",
+  "recovery-from-build-fail", "recovery-from-merge-conflict",
+] as const;
+
+export type ReactReason = (typeof REACT_REASONS)[number];
+
+export const DEFAULT_REACT_REASON: ReactReason = "turn";
+export const MAX_REACT_COMMENT_LENGTH = 150;
+
+export interface RawReactArgs {
+  comment?: string;
+  /** Alias agents guess when they have not loaded the schema. */
+  reaction?: string;
+  reason?: string;
+}
+
+export interface ReactArgs {
+  /** Null when the caller sent no usable comment under any accepted name. */
+  comment: string | null;
+  reason: ReactReason;
+}
+
+function isReactReason(value: string): value is ReactReason {
+  return (REACT_REASONS as readonly string[]).includes(value);
+}
+
+function clampComment(text: string): string {
+  const chars = Array.from(text);
+  if (chars.length <= MAX_REACT_COMMENT_LENGTH) return text;
+  return `${chars.slice(0, MAX_REACT_COMMENT_LENGTH - 1).join("")}…`;
+}
+
+export function normalizeReactArgs(raw: RawReactArgs): ReactArgs {
+  const text = [raw.comment, raw.reaction]
+    .map((value) => (typeof value === "string" ? value.trim() : ""))
+    .find((value) => value.length > 0);
+  const reason = typeof raw.reason === "string" ? raw.reason.trim() : "";
+  return {
+    comment: text ? clampComment(text) : null,
+    reason: isReactReason(reason) ? reason : DEFAULT_REACT_REASON,
+  };
+}

package/skills/buddy/SKILL.md

@@ -74,7 +74,11 @@ Based on `$ARGUMENTS`:
 
 ## CRITICAL OUTPUT RULES
 
-The MCP tools return pre-formatted ASCII art with ANSI colors, box-drawing characters, stat bars, and species art. This is the companion's visual identity.
+Different buddy tools return different shapes of output. The rules below keep the companion's visual identity intact while making sure plain-text replies actually reach the user.
+
+### Visual-card outputs — strict verbatim
+
+These tools return pre-formatted ASCII art with ANSI colors, box-drawing characters, stat bars, and species art: `buddy_show`, `buddy_stats`, `buddy_pet`, `buddy_achievements`, `buddy_summon`, `buddy_pick`. This is the companion's visual identity.
 
 **You MUST output the tool result text EXACTLY as returned — character for character, line for line.** Do NOT:
 
@@ -86,6 +90,20 @@ 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.
 
+### Plain-text outputs — verbatim and visible
+
+These tools return plain text, not ASCII art: `buddy_help`, `buddy_mute`, `buddy_unmute`, `buddy_frequency`, `buddy_style`, `buddy_statusline`, `buddy_list`, `buddy_rename`, `buddy_save`, `buddy_dismiss`, `buddy_set_personality`.
+
+**The visible reply MUST include the tool result text verbatim — every time, on every call, even on repeated calls in the same session.** Treat each invocation as a fresh request from the user, not a "they have seen it before" signal. Tool results are not rendered in the user's transcript; only what you write in your own reply reaches the screen.
+
+You MAY add a one-sentence confirmation before or after if it clarifies what changed, but do NOT paraphrase the text itself.
+
+**Hard floor for the plain-text commands above:** a reply that contains no visible text of its own is broken. A `buddy_react` call is not visible output — it reaches the user only through the statusline bubble — so a turn whose only content is a tool call renders blank. If you have nothing else to say, the tool result text alone is the correct reply.
+
+**Self-check for the plain-text commands above:** does your visible reply contain that command's result text? If not, paste it in. Never paste the result of `buddy_react`. The end-of-turn `buddy_react` call is _additional_, never _instead of_.
+
+### Reactions — statusline only
+
 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