agent-procedures 0.3.1 → 0.4.1

package/README.md

@@ -18,9 +18,10 @@ You don't run either of these manually. You just use your agent.
 
 ## Status & Harnesses
 
-Early. Reflex is built to plug into different agent platforms (harnesses). Right now, **Claude Code is the only one built** and is the default.
+Early. Reflex plugs into agent platforms through thin harness adapters.
 
-I set the engine up so Cursor and others can plug in later, but the adapters for those don't exist yet.
+- **Claude Code** — default (`npx agent-procedures init`)
+- **Cursor** — `npx agent-procedures init --harness cursor`
 
 ## Install
 
@@ -28,12 +29,14 @@ Run this in the repo you want Reflex in:
 
 ```bash
 npx agent-procedures init
+# or
+npx agent-procedures init --harness cursor
 ```
 
-By default this installs the Claude Code harness. If you were using a different one later, you'd run `npx agent-procedures init --harness cursor`. 
-
 Installing the package on its own won't do anything. You need `init`. It creates the folders, copies the runtime in, and adds a hook so your agent knows to call it.
 
+For Cursor, init writes `.cursor/hooks.json` and a shim under `.cursor/hooks/`. The hook command uses the absolute path to the `node` that ran init, because Cursor's hook shell often doesn't see nvm on `PATH`.
+
 ## API key (for the background groomer)
 
 Because the groomer uses an LLM to review procedures, it needs a cheap model key. 
@@ -63,7 +66,7 @@ The key gets checked before it's saved, so a typo fails right away instead of a
 
 The hot path only appends to `pending.jsonl`. A background groomer renames that buffer to `processing.jsonl`, reviews it, and merges keepers into `procedures.jsonl`. Recall reads all three, so memory works before grooming finishes.
 
-Init ignores everything under `.reflex/` except `config.json`, `procedures.jsonl`, `runs.jsonl`, and `runtime.js`. **Commit those four files**, plus `.claude/settings.json` (the hook wiring), so anyone who clones the repo gets the same memory. If you upgrade the package, run `init` again. That overwrites `runtime.js`.
+Init ignores everything under `.reflex/` except `config.json`, `procedures.jsonl`, `runs.jsonl`, and `runtime.js`. **Commit those four files**, plus the harness wiring (`.claude/settings.json` for Claude Code, or `.cursor/hooks.json` for Cursor), so anyone who clones the repo gets the same memory. If you upgrade the package, run `init` again. That overwrites `runtime.js`.
 
 ## Secrets
 

package/bin/cli.js

@@ -8,7 +8,7 @@ if (!command || command === "--help" || command === "-h") {
   console.log(`agent-procedures — procedural memory for coding agents (Reflex)
 
 Usage:
-  npx agent-procedures init [--harness claude]   Create .reflex/ and wire hooks
+  npx agent-procedures init [--harness claude|cursor]   Create .reflex/ and wire hooks
   npx agent-procedures auth login                Store an API key for the background groomer
   npx agent-procedures auth status               Show which provider/key the groomer will use
 `);

package/dist/runtime.js

@@ -1,8 +1,8 @@
-// Generated by agent-procedures@0.3.1. Do not edit.
+// Generated by agent-procedures@0.4.1. Do not edit.
 // To upgrade: npx agent-procedures init
 
 // lib/main.js
-import path5 from "node:path";
+import path6 from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -391,13 +391,15 @@ function recall(prompt, procs) {
   let text = formatSteps(best.steps, best.requires_env);
   const alt = procs.find((e) => e.parent_id === best.id && e.type === "alt" && e.enabled !== false);
   if (alt) text += "\n\nAlternative path that worked:\n" + formatSteps(alt.steps, alt.requires_env);
+  const label = best.trigger || "procedure";
   return {
     node: best,
     text: `Reflex memory found a procedure for this task:
 
 ${text}
 
-Follow these steps instead of figuring it out from scratch.`
+Follow these steps instead of figuring it out from scratch.`,
+    notice: `Reflex recalled: "${label}"`
   };
 }
 
@@ -420,9 +422,9 @@ function onPrompt(evt, reflexDir) {
     ...sanitized.unsafe ? { contains_unresolvable_secret: true } : {}
   });
   const hit = recall(sanitized.text, readAllProcedures(reflexDir));
-  if (!hit) return { context: null };
+  if (!hit) return { context: null, notice: null };
   appendTrace(reflexDir, sessionId, promptId, { t: "Recall", hit: hit.node.id });
-  return { context: hit.text };
+  return { context: hit.text, notice: hit.notice };
 }
 function onTool(evt, reflexDir) {
   const sanitized = evt.tool === "Bash" || evt.tool === "bash" ? sanitizeCommand(evt.target) : sanitizeText(evt.target);
@@ -882,14 +884,100 @@ var claude_default = {
   render(evt, result2) {
     if (evt.type !== "prompt") return "";
     if (!result2.context) return "{}";
-    return JSON.stringify({
+    const out = {
       hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: result2.context }
-    });
+    };
+    if (result2.notice) out.systemMessage = result2.notice;
+    return JSON.stringify(out);
+  }
+};
+
+// lib/harnesses/cursor.js
+import fs5 from "node:fs";
+import path5 from "node:path";
+var EVENTS2 = ["beforeSubmitPrompt", "postToolUse", "postToolUseFailure", "stop"];
+function toolTarget(tool, input) {
+  if (!input || typeof input !== "object") return typeof input === "string" ? input : "";
+  if (tool === "Shell" || tool === "Bash" || tool === "bash") return input.command || "";
+  return input.target || input.file_path || input.path || "";
+}
+function normalizeToolName(tool) {
+  if (tool === "Shell") return "Bash";
+  return tool || "";
+}
+var cursor_default = {
+  id: "cursor",
+  /** Where the generated hook shim goes, relative to the repo root. */
+  hookFile: ".cursor/hooks/reflex.mjs",
+  /** Merge our hooks into .cursor/hooks.json without touching anything else. */
+  register(cwd) {
+    const settingsPath = path5.join(cwd, ".cursor", "hooks.json");
+    let settings = {};
+    if (fs5.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs5.readFileSync(settingsPath, "utf8"));
+      } catch (e) {
+        console.warn("Failed to parse existing .cursor/hooks.json, overwriting...");
+      }
+    }
+    settings.version = settings.version || 1;
+    settings.hooks = settings.hooks || {};
+    const node = process.execPath;
+    for (const event of EVENTS2) {
+      if (!Array.isArray(settings.hooks[event])) settings.hooks[event] = [];
+      const command = `"${node}" ${this.hookFile} ${event}`;
+      const wired = settings.hooks[event].some((h) => h && h.command === command);
+      if (!wired) settings.hooks[event].push({ command });
+    }
+    fs5.mkdirSync(path5.dirname(settingsPath), { recursive: true });
+    fs5.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  },
+  /** Cursor's stdin payload → normalized engine event, or null to ignore. */
+  normalize(eventName, payload) {
+    const name = payload.hook_event_name || eventName;
+    const sessionId = payload.conversation_id || payload.session_id;
+    const promptId = payload.generation_id || payload.prompt_id;
+    const base = { sessionId, promptId };
+    if (name === "beforeSubmitPrompt") {
+      return { type: "prompt", ...base, prompt: payload.prompt || "" };
+    }
+    if (name === "postToolUse" || name === "postToolUseFailure") {
+      const rawTool = payload.tool_name || "";
+      const tool = normalizeToolName(rawTool);
+      const input = payload.tool_input || {};
+      return {
+        type: "tool",
+        ...base,
+        tool,
+        target: toolTarget(rawTool, input),
+        ok: name === "postToolUse"
+      };
+    }
+    if (name === "stop") {
+      return {
+        type: "stop",
+        ...base,
+        interrupted: payload.status === "aborted",
+        busy: false
+      };
+    }
+    return null;
+  },
+  /** Engine result → what to print on stdout for Cursor. */
+  render(evt, result2) {
+    if (evt.type !== "prompt") return "";
+    const out = { continue: true };
+    if (result2.context) {
+      out.additional_context = result2.notice ? `${result2.notice}
+
+${result2.context}` : result2.context;
+    }
+    return JSON.stringify(out);
   }
 };
 
 // lib/harnesses/index.js
-var HARNESSES = { claude: claude_default };
+var HARNESSES = { claude: claude_default, cursor: cursor_default };
 var DEFAULT_HARNESS = "claude";
 function getHarness(id = DEFAULT_HARNESS) {
   const h = HARNESSES[id];
@@ -900,7 +988,7 @@ function getHarness(id = DEFAULT_HARNESS) {
 }
 
 // lib/main.js
-var REFLEX_DIR = path5.dirname(fileURLToPath(import.meta.url));
+var REFLEX_DIR = path6.dirname(fileURLToPath(import.meta.url));
 function readStdin() {
   return new Promise((resolve) => {
     let data = "";

package/lib/engine.js

@@ -18,8 +18,9 @@ import { recall } from "./recall.js";
  *   { type: "tool",   sessionId, promptId, tool, target, ok }
  *   { type: "stop",   sessionId, promptId, interrupted, busy }
  *
- * Returns { context: string | null }. `context` is text the harness should
- * inject into the agent's next turn, if it knows how.
+ * Returns { context: string | null, notice?: string | null }.
+ * `context` is text the harness should inject into the agent's next turn.
+ * `notice` is a short user-visible line; the harness maps it if the host supports it.
  */
 export function handleEvent(evt, reflexDir, deps = {}) {
   if (!evt || !evt.sessionId || !evt.promptId) return { context: null };
@@ -45,10 +46,10 @@ function onPrompt(evt, reflexDir) {
   });
 
   const hit = recall(sanitized.text, readAllProcedures(reflexDir));
-  if (!hit) return { context: null };
+  if (!hit) return { context: null, notice: null };
 
   appendTrace(reflexDir, sessionId, promptId, { t: "Recall", hit: hit.node.id });
-  return { context: hit.text };
+  return { context: hit.text, notice: hit.notice };
 }
 
 // --- tool: trace ----------------------------------------------------------

package/lib/harnesses/claude.js

@@ -70,8 +70,11 @@ export default {
   render(evt, result) {
     if (evt.type !== "prompt") return "";
     if (!result.context) return "{}";
-    return JSON.stringify({
+    const out = {
       hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: result.context },
-    });
+    };
+    // Top-level systemMessage is shown to the user; not model context.
+    if (result.notice) out.systemMessage = result.notice;
+    return JSON.stringify(out);
   },
 };

package/lib/harnesses/cursor.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Cursor adapter. Everything Cursor-specific lives here.
+// Docs: https://cursor.com/docs/hooks
+// beforeSubmitPrompt → additional_context is undocumented but verified on Cursor 3.22.x.
+
+const EVENTS = ["beforeSubmitPrompt", "postToolUse", "postToolUseFailure", "stop"];
+
+function toolTarget(tool, input) {
+  if (!input || typeof input !== "object") return typeof input === "string" ? input : "";
+  if (tool === "Shell" || tool === "Bash" || tool === "bash") return input.command || "";
+  return input.target || input.file_path || input.path || "";
+}
+
+/** Cursor Shell → engine Bash so command sanitization still applies. */
+function normalizeToolName(tool) {
+  if (tool === "Shell") return "Bash";
+  return tool || "";
+}
+
+export default {
+  id: "cursor",
+
+  /** Where the generated hook shim goes, relative to the repo root. */
+  hookFile: ".cursor/hooks/reflex.mjs",
+
+  /** Merge our hooks into .cursor/hooks.json without touching anything else. */
+  register(cwd) {
+    const settingsPath = path.join(cwd, ".cursor", "hooks.json");
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+      try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+      } catch (e) {
+        console.warn("Failed to parse existing .cursor/hooks.json, overwriting...");
+      }
+    }
+    settings.version = settings.version || 1;
+    settings.hooks = settings.hooks || {};
+
+    // Cursor's hook shell often lacks nvm on PATH; bake the node that ran init.
+    const node = process.execPath;
+
+    for (const event of EVENTS) {
+      if (!Array.isArray(settings.hooks[event])) settings.hooks[event] = [];
+      const command = `"${node}" ${this.hookFile} ${event}`;
+      const wired = settings.hooks[event].some((h) => h && h.command === command);
+      if (!wired) settings.hooks[event].push({ command });
+    }
+
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  },
+
+  /** Cursor's stdin payload → normalized engine event, or null to ignore. */
+  normalize(eventName, payload) {
+    const name = payload.hook_event_name || eventName;
+    const sessionId = payload.conversation_id || payload.session_id;
+    const promptId = payload.generation_id || payload.prompt_id;
+    const base = { sessionId, promptId };
+
+    if (name === "beforeSubmitPrompt") {
+      return { type: "prompt", ...base, prompt: payload.prompt || "" };
+    }
+    if (name === "postToolUse" || name === "postToolUseFailure") {
+      const rawTool = payload.tool_name || "";
+      const tool = normalizeToolName(rawTool);
+      const input = payload.tool_input || {};
+      return {
+        type: "tool",
+        ...base,
+        tool,
+        target: toolTarget(rawTool, input),
+        ok: name === "postToolUse",
+      };
+    }
+    if (name === "stop") {
+      return {
+        type: "stop",
+        ...base,
+        interrupted: payload.status === "aborted",
+        busy: false,
+      };
+    }
+    return null;
+  },
+
+  /** Engine result → what to print on stdout for Cursor. */
+  render(evt, result) {
+    if (evt.type !== "prompt") return "";
+    const out = { continue: true };
+    if (result.context) {
+      // No Claude-style systemMessage on continue:true; put the notice in model context.
+      out.additional_context = result.notice
+        ? `${result.notice}\n\n${result.context}`
+        : result.context;
+    }
+    return JSON.stringify(out);
+  },
+};

package/lib/harnesses/index.js

@@ -1,8 +1,9 @@
 import claude from "./claude.js";
+import cursor from "./cursor.js";
 
 // To add a harness: write lib/harnesses/<id>.js with the same shape as claude.js
 // (id, hookFile, register, normalize, render) and list it here.
-export const HARNESSES = { claude };
+export const HARNESSES = { claude, cursor };
 
 export const DEFAULT_HARNESS = "claude";
 

package/lib/recall.js

@@ -77,7 +77,7 @@ function formatSteps(steps, requiresEnv = []) {
 
 /**
  * Best-scoring root procedure for this prompt, or null.
- * Returns { node, text } ready to inject.
+ * Returns { node, text, notice } — text for the agent, notice for the harness UI.
  */
 export function recall(prompt, procs) {
   if (!prompt) return null;
@@ -101,8 +101,10 @@ export function recall(prompt, procs) {
   const alt = procs.find((e) => e.parent_id === best.id && e.type === "alt" && e.enabled !== false);
   if (alt) text += "\n\nAlternative path that worked:\n" + formatSteps(alt.steps, alt.requires_env);
 
+  const label = best.trigger || "procedure";
   return {
     node: best,
     text: `Reflex memory found a procedure for this task:\n\n${text}\n\nFollow these steps instead of figuring it out from scratch.`,
+    notice: `Reflex recalled: "${label}"`,
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-procedures",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Procedural memory for coding agents",
   "type": "module",
   "bin": {