agent-procedures 0.3.2 → 0.4.2

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,9 @@ 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`, `package.json`, `procedures.jsonl`, `runs.jsonl`, and `runtime.js`. **Commit those five files**, plus the harness wiring (`.claude/settings.json` for Claude Code, and/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`.
+
+You can wire both harnesses in one repo if you use Claude Code and Cursor. Cursor may also load Claude’s hooks via third-party compatibility — if you see double hook runs, turn that off in Cursor settings and keep `.cursor/hooks.json` for Cursor / `.claude/settings.json` for Claude Code.
 
 ## 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.2. Do not edit.
+// Generated by agent-procedures@0.4.2. 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";
 
@@ -892,8 +892,92 @@ var claude_default = {
   }
 };
 
+// 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];
@@ -904,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/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/init.js

@@ -42,6 +42,7 @@ function ensureGitignore(cwd) {
     "# Reflex: ignore runtime state; commit only the shared allowlist",
     ".reflex/*",
     "!.reflex/config.json",
+    "!.reflex/package.json",
     "!.reflex/procedures.jsonl",
     "!.reflex/runs.jsonl",
     "!.reflex/runtime.js",
@@ -77,6 +78,12 @@ function installRuntime(reflexDir) {
     throw new Error("Missing dist/runtime.js. Run `npm run build` in the agent-procedures repo first.");
   }
   fs.copyFileSync(RUNTIME_SRC, path.join(reflexDir, "runtime.js"));
+  // Host apps are often "type":"commonjs". Without this, Node treats runtime.js as
+  // CJS and the .mjs shim's `import { run }` crashes before any event is handled.
+  writeAlways(
+    path.join(reflexDir, "package.json"),
+    `${JSON.stringify({ type: "module", private: true }, null, 2)}\n`,
+  );
   const engineDir = path.join(reflexDir, "engine");
   if (fs.existsSync(engineDir)) fs.rmSync(engineDir, { recursive: true, force: true });
   return "updated";

package/package.json

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