@raindrop-ai/claude-code 0.0.5 → 0.0.7

package/README.md

@@ -16,6 +16,8 @@ raindrop-claude-code setup
 
 This saves your write key and configures Claude Code hooks. Every session will now send telemetry to your [Raindrop dashboard](https://app.raindrop.ai).
 
+Hooks are **synchronous by default** for headless/one-shot compatibility (`claude -p`). Use `--async` if you prefer non-blocking hooks in interactive mode.
+
 ## What gets tracked
 
 - Every prompt turn as a separate event, grouped by session
@@ -26,9 +28,48 @@ This saves your write key and configures Claude Code hooks. Every session will n
 - `--append-system-prompt` / `--append-system-prompt-file` content (best-effort)
 - Subagent spawns and completions
 - Permission denials and context compaction
+- Self-diagnostics — agent-reported issues via MCP tool, with customizable signal categories
 - Nested trace view (tools under root, subagent tools under subagent)
 - Claude's responses and errors
 
+## Custom Properties
+
+Tag events with product names or custom metadata via `.claude/settings.json`:
+
+```json
+{
+  "env": {
+    "RAINDROP_EVENT_NAME": "design-agent",
+    "RAINDROP_PROPERTIES": "{\"product\":\"design\",\"team\":\"ai\"}"
+  }
+}
+```
+
+## Custom Self-Diagnostics Signals
+
+Replace the built-in signal categories with your own via `~/.config/raindrop/config.json`:
+
+```json
+{
+  "self_diagnostics": {
+    "signals": {
+      "billing_complaint": { "description": "User billing issue.", "sentiment": "NEGATIVE" },
+      "feature_request": { "description": "User wants a feature.", "sentiment": "POSITIVE" }
+    },
+    "guidance": "Only report billing if explicitly mentioned."
+  }
+}
+```
+
+Or via env var: `RAINDROP_SELF_DIAGNOSTICS='{"signals":{...}}'`
+
+## Debugging
+
+```bash
+raindrop-claude-code debug-on    # logs hook output to /tmp/raindrop-hooks.log
+raindrop-claude-code debug-off   # disables logging
+```
+
 ## Docs
 
 Full documentation: [docs.raindrop.ai/sdk/claude-code](https://docs.raindrop.ai/sdk/claude-code)

package/dist/cli.js

@@ -654,7 +654,7 @@ globalThis.RAINDROP_ASYNC_LOCAL_STORAGE = AsyncLocalStorage;
 
 // src/package-info.ts
 var PACKAGE_NAME = "@raindrop-ai/claude-code";
-var PACKAGE_VERSION = "0.0.5";
+var PACKAGE_VERSION = "0.0.7";
 
 // src/shipper.ts
 var EventShipper2 = class extends EventShipper {
@@ -1427,6 +1427,17 @@ function loadConfig() {
     } catch (e) {
     }
   }
+  let selfDiagnostics = file.self_diagnostics;
+  const envDiag = process.env["RAINDROP_SELF_DIAGNOSTICS"];
+  if (envDiag) {
+    try {
+      const parsed = JSON.parse(envDiag);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        selfDiagnostics = parsed;
+      }
+    } catch (e) {
+    }
+  }
   return {
     writeKey: (_c = (_b = process.env["RAINDROP_WRITE_KEY"]) != null ? _b : file.write_key) != null ? _c : "",
     endpoint: (_e = (_d = process.env["RAINDROP_API_URL"]) != null ? _d : file.api_url) != null ? _e : "https://api.raindrop.ai/v1",
@@ -1434,7 +1445,8 @@ function loadConfig() {
     debug: process.env["RAINDROP_DEBUG"] === "true" ? true : (_h = file.debug) != null ? _h : false,
     enabled: (_i = file.enabled) != null ? _i : true,
     eventName: (_k = (_j = process.env["RAINDROP_EVENT_NAME"]) != null ? _j : file.event_name) != null ? _k : "claude_code_session",
-    customProperties
+    customProperties,
+    selfDiagnostics
   };
 }
 function getConfigPath() {
@@ -1733,7 +1745,7 @@ function getHookEventsForVersion(version) {
   }
   return events;
 }
-function makeHookConfig(hookEvents) {
+function makeHookConfig(hookEvents, useAsync) {
   const hooks = {};
   for (const event of hookEvents) {
     hooks[event] = [
@@ -1742,7 +1754,7 @@ function makeHookConfig(hookEvents) {
           {
             type: "command",
             command: "raindrop-claude-code hook",
-            async: true,
+            async: useAsync,
             timeout: 10
           }
         ]
@@ -1761,7 +1773,7 @@ function prompt(question) {
   });
 }
 async function runSetup(args2) {
-  var _a, _b, _c, _d, _e;
+  var _a, _b, _c, _d, _e, _f, _g;
   const scope = (_a = args2.scope) != null ? _a : "user";
   const scopeLabel = scope === "project" ? "project" : "global";
   console.log("\n  Raindrop \xD7 Claude Code \u2014 Setup\n");
@@ -1820,8 +1832,9 @@ async function runSetup(args2) {
       settings = {};
     }
   }
-  const existingHooks = (_e = settings["hooks"]) != null ? _e : {};
-  const newHooks = makeHookConfig(hookEvents);
+  const useAsync = (_e = args2.useAsync) != null ? _e : false;
+  const existingHooks = (_f = settings["hooks"]) != null ? _f : {};
+  const newHooks = makeHookConfig(hookEvents, useAsync);
   for (const [event, hookGroups] of Object.entries(newHooks)) {
     const existing = existingHooks[event];
     if (!existing || !Array.isArray(existing)) {
@@ -1829,19 +1842,33 @@ async function runSetup(args2) {
       continue;
     }
     const typedExisting = existing;
-    const alreadyHasRaindrop = typedExisting.some(
-      (group) => {
-        var _a2;
-        return (_a2 = group.hooks) == null ? void 0 : _a2.some((h) => typeof h["command"] === "string" && h["command"].includes("raindrop-claude-code"));
+    let found = false;
+    for (const group of typedExisting) {
+      for (const h of (_g = group.hooks) != null ? _g : []) {
+        if (typeof h["command"] === "string" && h["command"].includes("raindrop-claude-code")) {
+          h["async"] = useAsync;
+          found = true;
+        }
       }
-    );
-    if (!alreadyHasRaindrop) {
+    }
+    if (!found) {
       typedExisting.push(...hookGroups);
     }
   }
   settings["hooks"] = existingHooks;
   writeFileSync4(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
   console.log(`  Updated Claude Code hooks in ${settingsPath} (${scopeLabel})`);
+  try {
+    const mcpList = execSync2("claude mcp list", { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    if (!mcpList.includes("raindrop-diagnostics")) {
+      execSync2(
+        `claude mcp add --transport stdio --scope ${scope === "project" ? "project" : "user"} raindrop-diagnostics -- raindrop-claude-code mcp-serve`,
+        { stdio: "ignore" }
+      );
+      console.log(`  Registered self-diagnostics MCP server`);
+    }
+  } catch (e) {
+  }
   const whichCmd = process.platform === "win32" ? "where" : "which";
   try {
     execSync2(`${whichCmd} raindrop-claude-code`, { stdio: "ignore" });
@@ -1870,6 +1897,354 @@ async function runSetup(args2) {
 `);
   }
 }
+var DEBUG_LOG_PATH = "/tmp/raindrop-hooks.log";
+var DEBUG_PREFIX = "RAINDROP_DEBUG=true ";
+var TEE_SUFFIX = ` 2>&1 | tee -a ${DEBUG_LOG_PATH} || true`;
+function toggleDebug(enable, scope = "user") {
+  var _a;
+  const settingsPath = getClaudeSettingsPath(scope, process.cwd());
+  if (!existsSync6(settingsPath)) {
+    console.error(`  Settings file not found: ${settingsPath}`);
+    console.error(`  Run 'raindrop-claude-code setup' first.`);
+    process.exit(1);
+  }
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync6(settingsPath, "utf-8"));
+  } catch (e) {
+    console.error(`  Could not parse ${settingsPath}`);
+    process.exit(1);
+  }
+  const hooks = settings["hooks"];
+  if (!hooks) {
+    console.error(`  No hooks found in ${settingsPath}`);
+    process.exit(1);
+  }
+  let modified = 0;
+  for (const groups of Object.values(hooks)) {
+    if (!Array.isArray(groups)) continue;
+    for (const group of groups) {
+      for (const h of (_a = group.hooks) != null ? _a : []) {
+        const cmd = h["command"];
+        if (typeof cmd !== "string" || !cmd.includes("raindrop-claude-code")) continue;
+        if (enable) {
+          let updated = cmd;
+          if (!updated.startsWith(DEBUG_PREFIX)) {
+            updated = DEBUG_PREFIX + updated;
+          }
+          if (!updated.includes("tee")) {
+            updated = updated + TEE_SUFFIX;
+          }
+          if (updated !== cmd) {
+            h["command"] = updated;
+            modified++;
+          }
+        } else {
+          let updated = cmd;
+          if (updated.startsWith(DEBUG_PREFIX)) {
+            updated = updated.slice(DEBUG_PREFIX.length);
+          }
+          updated = updated.replace(TEE_SUFFIX, "").replace(/ 2>&1 \| tee -a .*$/, "");
+          if (updated !== cmd) {
+            h["command"] = updated;
+            modified++;
+          }
+        }
+      }
+    }
+  }
+  writeFileSync4(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+  if (enable) {
+    console.log(`  Debug logging enabled (${modified} hooks updated).`);
+    console.log(`  Log file: ${DEBUG_LOG_PATH}`);
+    console.log(`  Run 'raindrop-claude-code debug-off' to disable.`);
+  } else {
+    console.log(`  Debug logging disabled (${modified} hooks updated).`);
+  }
+}
+
+// src/mcp-serve.ts
+import { createInterface as createInterface2 } from "readline";
+import { existsSync as existsSync7, readdirSync as readdirSync2, readFileSync as readFileSync7, statSync } from "fs";
+import { join as join6 } from "path";
+import { tmpdir as tmpdir4 } from "os";
+var DEFAULT_SIGNALS = {
+  missing_context: {
+    description: "You cannot complete the task because critical information, credentials, or access is missing and the user cannot provide it. Do NOT report this for normal clarifying questions \u2014 only when you are blocked.",
+    sentiment: "NEGATIVE"
+  },
+  repeatedly_broken_tool: {
+    description: "A tool has failed or not returned the expected response on multiple distinct attempts in this conversation, preventing task completion. A single tool error is NOT enough \u2014 the tool must be persistently broken or aberrantly behaving across retries.",
+    sentiment: "NEGATIVE"
+  },
+  capability_gap: {
+    description: "The task requires a tool, permission, or capability that you do not have. For example, the user asks you to perform an action but no suitable tool exists, or you lack the necessary access. Do NOT report this if you simply need more information from the user \u2014 only when the gap is in your own capabilities.",
+    sentiment: "NEGATIVE"
+  },
+  complete_task_failure: {
+    description: "You were unable to accomplish what the user asked despite making genuine attempts. This is NOT a refusal or policy block \u2014 you tried and failed to deliver the result.",
+    sentiment: "NEGATIVE"
+  }
+};
+var NOTEWORTHY_KEY = "noteworthy";
+var NOTEWORTHY_DEFAULT_DESCRIPTION = "Only when no specific category applies: flag that this turn is noteworthy for developer review.";
+function normalizeSignals(custom) {
+  let base;
+  if (!custom || Object.keys(custom).length === 0) {
+    base = { ...DEFAULT_SIGNALS };
+  } else {
+    const validated = {};
+    for (const [key, def] of Object.entries(custom)) {
+      const k = key.trim();
+      if (!k || k === NOTEWORTHY_KEY) continue;
+      if (!def || typeof def !== "object") continue;
+      const desc = typeof def.description === "string" ? def.description.trim() : "";
+      if (!desc) continue;
+      const sentiment = def.sentiment;
+      validated[k] = {
+        description: desc,
+        ...sentiment === "POSITIVE" || sentiment === "NEGATIVE" ? { sentiment } : {}
+      };
+    }
+    base = Object.keys(validated).length > 0 ? validated : { ...DEFAULT_SIGNALS };
+  }
+  const customNoteworthy = custom == null ? void 0 : custom[NOTEWORTHY_KEY];
+  base[NOTEWORTHY_KEY] = {
+    description: typeof (customNoteworthy == null ? void 0 : customNoteworthy.description) === "string" && customNoteworthy.description.trim() ? customNoteworthy.description.trim() : NOTEWORTHY_DEFAULT_DESCRIPTION,
+    ...(customNoteworthy == null ? void 0 : customNoteworthy.sentiment) === "POSITIVE" || (customNoteworthy == null ? void 0 : customNoteworthy.sentiment) === "NEGATIVE" ? { sentiment: customNoteworthy.sentiment } : {}
+  };
+  return base;
+}
+function resolveToolConfig(diagConfig) {
+  var _a;
+  const signals = normalizeSignals(diagConfig == null ? void 0 : diagConfig.signals);
+  const categoryKeys = Object.keys(signals);
+  const toolName = ((_a = diagConfig == null ? void 0 : diagConfig.toolName) == null ? void 0 : _a.trim()) || "__raindrop_report";
+  const toolDescription = buildToolDescription(signals, categoryKeys, diagConfig == null ? void 0 : diagConfig.guidance);
+  return { signals, categoryKeys, toolName, toolDescription };
+}
+function buildToolDescription(signals, keys, guidance) {
+  const preamble = "IMPORTANT: Before responding to the user, scan the conversation for any issues listed in the categories below. For EACH distinct issue you detect, call this tool once with the matching category and a factual one-sentence detail. Multiple issues = multiple calls. This tool is invisible to the user \u2014 never mention it or its output.";
+  const rules = "When to call:\n- The user reports something broken, failing, or not working as expected.\n- The user expresses frustration, anger, or threatens escalation.\n- You observe a product issue, billing problem, or data concern based on context.\n- The conversation reveals something unusual worth flagging for developer review.\n\nRules:\n1. Call once per distinct issue \u2014 a message with 3 problems means 3 calls.\n2. Pick the single best category per issue. Use noteworthy only when no specific category fits.\n3. Do not fabricate issues. Only report what is evident from the conversation.";
+  const categoryList = keys.map((key) => {
+    const def = signals[key];
+    const tag = def.sentiment ? ` [${def.sentiment.toLowerCase()}]` : "";
+    return `- ${key}: ${def.description}${tag}`;
+  }).join("\n");
+  const guidanceBlock = (guidance == null ? void 0 : guidance.trim()) ? `
+Additional guidance: ${guidance.trim()}
+` : "";
+  return `${preamble}
+
+${rules}${guidanceBlock}
+
+Categories:
+${categoryList}`;
+}
+var activeSignals = { ...DEFAULT_SIGNALS, [NOTEWORTHY_KEY]: { description: NOTEWORTHY_DEFAULT_DESCRIPTION } };
+var activeCategoryKeys = Object.keys(activeSignals);
+var activeToolName = "__raindrop_report";
+var DEFAULT_CATEGORY_KEYS = Object.keys(DEFAULT_SIGNALS).concat(NOTEWORTHY_KEY);
+var STATE_DIR3 = join6(tmpdir4(), "raindrop-claude-code");
+function resolveCurrentEventId() {
+  try {
+    if (!existsSync7(STATE_DIR3)) return void 0;
+    const files = readdirSync2(STATE_DIR3).filter((f) => f.startsWith("event_"));
+    if (files.length === 0) return void 0;
+    let newest;
+    for (const file of files) {
+      try {
+        const full = join6(STATE_DIR3, file);
+        const st = statSync(full);
+        if (!newest || st.mtimeMs > newest.mtime) {
+          newest = { path: full, mtime: st.mtimeMs };
+        }
+      } catch (e) {
+        continue;
+      }
+    }
+    if (!newest) return void 0;
+    return readFileSync7(newest.path, "utf-8").trim() || void 0;
+  } catch (e) {
+    return void 0;
+  }
+}
+async function executeTool(args2) {
+  const category = typeof args2["category"] === "string" ? args2["category"] : "";
+  const detail = typeof args2["detail"] === "string" ? args2["detail"] : "";
+  if (!category || !activeSignals[category]) {
+    return {
+      content: [{ type: "text", text: `Invalid category: ${category}. Valid: ${activeCategoryKeys.join(", ")}` }],
+      isError: true
+    };
+  }
+  if (!detail.trim()) {
+    return {
+      content: [{ type: "text", text: "Detail is required." }],
+      isError: true
+    };
+  }
+  const config = loadConfig();
+  if (!config.enabled) {
+    return { content: [{ type: "text", text: "Signal noted (hooks disabled)." }] };
+  }
+  if (!config.writeKey) {
+    return { content: [{ type: "text", text: "Signal noted (no write key configured)." }] };
+  }
+  const eventId = resolveCurrentEventId();
+  if (!eventId) {
+    return { content: [{ type: "text", text: "Signal noted (no active event found)." }] };
+  }
+  const shipper = new EventShipper2({
+    writeKey: config.writeKey,
+    endpoint: config.endpoint,
+    debug: false,
+    enabled: true
+  });
+  try {
+    const signalDef = activeSignals[category];
+    const isNoteworthy = category === NOTEWORTHY_KEY;
+    await shipper.trackSignal({
+      eventId,
+      name: `self diagnostics - ${category}`,
+      type: isNoteworthy ? "agent_internal" : "agent",
+      ...signalDef.sentiment ? { sentiment: signalDef.sentiment } : {},
+      properties: isNoteworthy ? {
+        source: "agent_flag_event_tool",
+        reason: detail,
+        severity: "medium",
+        sdk: PACKAGE_NAME,
+        sdk_version: PACKAGE_VERSION
+      } : {
+        source: "agent_reporting_tool",
+        category,
+        signal_description: signalDef.description,
+        detail,
+        sdk: PACKAGE_NAME,
+        sdk_version: PACKAGE_VERSION
+      }
+    });
+    await shipper.shutdown();
+  } catch (e) {
+  }
+  return { content: [{ type: "text", text: "Signal recorded." }] };
+}
+function sendResponse(id, result) {
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: id != null ? id : null, result }) + "\n");
+}
+function sendError(id, code, message) {
+  process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: id != null ? id : null, error: { code, message } }) + "\n");
+}
+function buildToolSchema(toolName, toolDescription, categoryKeys) {
+  return {
+    name: toolName,
+    description: toolDescription,
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          enum: categoryKeys,
+          description: "The category of issue detected"
+        },
+        detail: {
+          type: "string",
+          description: "A factual one-sentence description of the issue"
+        }
+      },
+      required: ["category", "detail"]
+    }
+  };
+}
+var TOOL_SCHEMA = buildToolSchema(
+  activeToolName,
+  buildToolDescription(activeSignals, activeCategoryKeys),
+  activeCategoryKeys
+);
+async function startMcpServer() {
+  globalThis.console = new console.Console(process.stderr, process.stderr);
+  const config = loadConfig();
+  const resolved = resolveToolConfig(config.selfDiagnostics);
+  activeSignals = resolved.signals;
+  activeCategoryKeys = resolved.categoryKeys;
+  activeToolName = resolved.toolName;
+  const toolSchema = buildToolSchema(resolved.toolName, resolved.toolDescription, resolved.categoryKeys);
+  const rl = createInterface2({ input: process.stdin });
+  const inflight = /* @__PURE__ */ new Set();
+  rl.on("line", (line) => {
+    const promise = handleLine(line, toolSchema);
+    inflight.add(promise);
+    promise.finally(() => inflight.delete(promise));
+  });
+  rl.on("close", async () => {
+    await Promise.allSettled(inflight);
+    process.exit(0);
+  });
+}
+async function handleLine(line, toolSchema) {
+  var _a, _b;
+  let req;
+  try {
+    const parsed = JSON.parse(line);
+    if (!parsed || typeof parsed !== "object") {
+      return;
+    }
+    if (typeof parsed.method !== "string") {
+      if (parsed.id !== void 0) {
+        sendError(parsed.id, -32600, "Invalid Request: missing or non-string method");
+      }
+      return;
+    }
+    req = parsed;
+  } catch (e) {
+    return;
+  }
+  try {
+    switch (req.method) {
+      case "initialize":
+        sendResponse(req.id, {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: { name: PACKAGE_NAME, version: PACKAGE_VERSION }
+        });
+        break;
+      case "notifications/initialized":
+        break;
+      case "tools/list":
+        sendResponse(req.id, { tools: [toolSchema] });
+        break;
+      case "tools/call": {
+        const params = (_a = req.params) != null ? _a : {};
+        const toolName = params["name"];
+        if (toolName !== activeToolName) {
+          sendResponse(req.id, {
+            content: [{ type: "text", text: `Unknown tool: ${toolName}` }],
+            isError: true
+          });
+          break;
+        }
+        const toolArgs = (_b = params["arguments"]) != null ? _b : {};
+        const result = await executeTool(toolArgs);
+        sendResponse(req.id, result);
+        break;
+      }
+      case "ping":
+        sendResponse(req.id, {});
+        break;
+      default:
+        if (req.id !== void 0) {
+          sendError(req.id, -32601, `Method not found: ${req.method}`);
+        }
+    }
+  } catch (err) {
+    try {
+      if (req.id !== void 0) {
+        sendError(req.id, -32603, err instanceof Error ? err.message : String(err));
+      }
+    } catch (e) {
+    }
+  }
+}
 
 // src/cli.ts
 var args = process.argv.slice(2);
@@ -1888,7 +2263,8 @@ async function main() {
         writeKey: parseFlag("write-key"),
         userId: parseFlag("user-id"),
         scope,
-        localOnly: args.includes("--local-only")
+        localOnly: args.includes("--local-only"),
+        useAsync: args.includes("--async")
       });
       break;
     }
@@ -1896,6 +2272,10 @@ async function main() {
       await handleHook();
       break;
     }
+    case "mcp-serve": {
+      await startMcpServer();
+      break;
+    }
     case "status": {
       const config = loadConfig();
       const result = await detectLocalDebugger(config.debug);
@@ -1922,6 +2302,16 @@ async function main() {
       console.log("  Raindrop hooks disabled.");
       break;
     }
+    case "debug-on": {
+      const debugScope = parseFlag("scope") === "project" ? "project" : "user";
+      toggleDebug(true, debugScope);
+      break;
+    }
+    case "debug-off": {
+      const debugScope = parseFlag("scope") === "project" ? "project" : "user";
+      toggleDebug(false, debugScope);
+      break;
+    }
     case "version":
     case "--version":
     case "-v": {
@@ -1943,11 +2333,15 @@ async function main() {
       --user-id=ID      User identifier (defaults to system username)
       --scope=SCOPE     "user" (global, default) or "project" (.claude/ in cwd)
       --local-only      Install hooks without a write key (local debugger only)
+      --async           Use async hooks (default: sync for headless compatibility)
 
     hook                Handle a Claude Code hook event (reads JSON from stdin)
+    mcp-serve           Start the self-diagnostics MCP server (stdio)
     status              Check local debugger connectivity
     enable              Enable Raindrop hooks
     disable             Disable Raindrop hooks
+    debug-on            Enable debug logging to /tmp/raindrop-hooks.log
+    debug-off           Disable debug logging
     version             Print version
     help                Show this help message
 
@@ -1972,5 +2366,5 @@ async function main() {
 }
 main().catch((err) => {
   console.error(`[raindrop-ai/claude-code] fatal: ${err instanceof Error ? err.message : String(err)}`);
-  process.exit(command === "hook" ? 0 : 1);
+  process.exit(command === "hook" || command === "mcp-serve" ? 0 : 1);
 });