@ory/cursor 0.0.0-bootstrap.0 → 1.0.0

package/README.md

@@ -0,0 +1,181 @@
+# Ory Agent Plugin: Cursor
+
+Security and developer experience for [Cursor](https://cursor.com), powered by [Ory](https://ory.com).
+
+Cursor runs real actions on your machine — editing files, running shell commands, calling APIs. This plugin gives those actions an identity, a permission check, and an audit trail.
+
+One command installs two independent halves:
+
+- **Developer experience** — the Ory `.cursor/rules/*.mdc` guidance rules, the local Ory dev stack, an MCP server, and activity logging. No account, no keys, nothing to configure: it works the moment it's installed.
+- **Ory Agent Security** — browser sign-in, brokered permission checks before tool calls, and the delegation trail. Opt-in connection details from the [Ory Console](https://console.ory.sh) switch it on, and it takes nothing away from the half above. See [Connect to Ory Agent Security](#connect-to-ory-agent-security).
+
+## What you'll need
+
+- [Cursor](https://cursor.com), installed
+- Node.js **22 or newer**
+- [Docker](https://docs.docker.com/get-docker/) — only if you want to run Ory locally
+- macOS or Linux (Windows works via WSL2)
+
+## Get started
+
+Run one command:
+
+```bash
+npx -y -p @ory/cursor ory-cursor install
+```
+
+This merges the Ory entries into `~/.cursor/hooks.json` and `~/.cursor/mcp.json` and writes `~/.cursor/rules/ory-*.mdc` (use `--project` to target `./.cursor` instead). Restart Cursor (or reload the window) to pick up the hooks.
+
+Confirm everything landed with:
+
+```bash
+npx -y -p @ory/cursor ory-cursor status
+```
+
+`status` is your one-stop check: what's configured, who's signed in, which tools are covered by permissions, and recent activity. Until you connect Agent Security, the identity and permission rows say so and name what's missing.
+
+## Rules and commands
+
+Installing the plugin drops the full Ory playbook catalog into Cursor as **`.cursor/rules/*.mdc` guidance rules**, which Cursor applies by relevance — say what you want in plain language and the matching one takes over.
+
+| Rule | What it does for you |
+|---|---|
+| `ory-auth-setup` | Adds a complete auth system to your app — login, registration, recovery, verification, settings — on [Ory Elements](https://github.com/ory/elements) |
+| `ory-login-flow` | Builds just the pages, wired to Ory's self-service flows |
+| `ory-social-login` | "Sign in with…" for Google, GitHub, Apple, Microsoft, Discord, Slack, GitLab, Facebook |
+| `ory-local-dev` | Develops and tests login/permission flows against a local Ory — no project, no account, offline |
+| `ory-permissions-onboarding` | Walks a fresh install from observe mode to enforced per-tool permissions without getting blocked |
+| `ory-build-agent` | Drops `@ory/argus` into an agent *you* own — Claude Agent SDK, OpenAI Agents, Mastra, Vercel AI, LangGraph/PydanticAI |
+| `ory-build-integration` | Wires Ory into your app: Action webhooks, JWT validation at a gateway, live event streams |
+| `ory-contribute-integration` | Authors and submits an integration to the public `ory/integrates` registry |
+| `ory-e2b-sandbox` | Scaffolds an E2B sandbox template that boots with this plugin preinstalled |
+| `ory-temporal-worker` | Scaffolds a Temporal TypeScript worker where every Activity is authenticated, authorized, and audited |
+
+The local stack has its own rules — ask for them by name:
+
+| Command | What it does |
+|---|---|
+| `ory-local-up` | Starts a local Ory (Identities, OAuth2, Permissions) in Docker and seeds a test user — it prints the email + password to sign in with |
+| `ory-local-down` | Stops it, keeping your data volumes |
+| `ory-temporal-up` | Starts a local Temporal dev server for the `ory-temporal-worker` scaffold |
+
+The local stack runs entirely on your laptop: Ory APIs at `http://localhost:4000`, a login UI on `:4455` (not `:3000`, to dodge Next.js port clashes), and the Ory Console on `:4100`.
+
+A built-in **Ory MCP server** rounds it out — Cursor can manage identities, projects, and permissions straight from chat.
+
+So: ask Cursor *"add Ory login to this app"* and it scaffolds the pages, starts a local Ory, and wires them together.
+
+## What you get
+
+Out of the box, every tool Cursor runs produces a privacy-safe structured activity event in the unified local log.
+
+Once you connect to Ory Agent Security, two more things happen automatically:
+
+- **Who's driving.** You sign in once in your browser; Cursor (and any sub-agents it spawns) each get their own identity. No tokens to copy around, and the "who acted on whose behalf" trail stays queryable later.
+- **What it's allowed to do.** Before a tool runs, Ory checks whether it's permitted. It starts in **observe mode** — nothing is blocked, you just *see* what would be — so it never gets in your way on day one.
+
+If Ory is ever unreachable, the plugin gets out of the way and lets Cursor keep working — so it can't lock you out.
+
+### See what's happening
+
+Everything the plugin does is observable out of the box:
+
+- **Activity log.** Privacy-safe activity is always appended to `~/.config/ory-agent-plugins/cursor/ory-agent-debug.log`. View events, decisions, and errors live with:
+
+  ```bash
+  npx -y -p @ory/cursor ory-cursor watch
+  ```
+
+  Set `ORY_AGENT_LOG_FILE` to override the path; set it empty to disable file persistence.
+- **Live debug.** Launch Cursor with `ORY_AGENT_DEBUG=true` to add verbose local diagnostics, including raw shell commands, to the watched log and stderr. Secrets are recursively redacted; pass `watch --json` for NDJSON.
+
+### Ready to enforce?
+
+Once connected, the deny posture lives on the Ory project: when the observe-mode activity looks right, an admin promotes it to **enforce** in the **Ory Console** (Agent Security). Every session reads that posture live, so nothing has to be reinstalled.
+
+```bash
+npx -y -p @ory/cursor ory-cursor permissions   # what the project grants, and the live mode
+```
+
+Then a denied tool is actually blocked (`preToolUse` returns `permission: "deny"`) and Cursor shows why.
+
+## How it maps onto Cursor's hooks
+
+| Cursor hook | What the plugin does |
+|---|---|
+| `sessionStart` | User + agent auth gates, user→agent delegation (never blocks) |
+| `preToolUse` | The permission gate — blocks with `permission: "deny"` in enforce mode |
+| `postToolUse` / `postToolUseFailure` | Record `tool.complete` / `tool.fail` activity |
+| `beforeSubmitPrompt` | Record `user.prompt` activity (never blocks the human) |
+| `subagentStart` / `subagentStop` | Sub-agent DCR identity + delegation activity |
+
+The fine-grained `beforeShellExecution` / `beforeMCPExecution` / `beforeReadFile`
+hooks are **not** registered: `preToolUse` already gates those categories, so
+registering them would only spawn extra hook subprocesses without adding any
+enforcement. (When they do fire, the handler records activity only.)
+
+The `preToolUse` gate is registered fail-closed: if the hook can't produce a verdict, Cursor blocks the tool (exit code 2), so a crashed or timed-out gate can't silently defeat enforce mode. The audit/identity hooks stay fail-open — none of them gate a tool, and session start must never block.
+
+## Connect to Ory Agent Security
+
+Copy the connection details from the [Ory Console](https://console.ory.sh) under **Agent Security**:
+
+| Value | Flag | Environment variable |
+|---|---|---|
+| Project URL | `--project-url` | `ORY_PROJECT_URL` |
+| Agent Security URL | `--agent-security-url` | `ORY_AGENT_SECURITY_URL` |
+| Sign-in client id override (default `ory-agent-security-login`) | `--oauth2-client-id` | `ORY_OAUTH2_CLIENT_ID` |
+
+```bash
+npx -y -p @ory/cursor ory-cursor configure \
+  --project-url https://<slug>.projects.oryapis.com \
+  --agent-security-url https://agents.console.ory.com
+```
+
+`install` accepts the same flags, so you can register the plugin **and** connect in one shot (`install --project-url <URL> --agent-security-url <URL>`). The login client defaults to `ory-agent-security-login`; custom deployments can override it with `--oauth2-client-id`. Existing configurations fall back to the project URL when the Agent Security URL is unset. To turn sign-in and checks back off later, use `configure --disconnect`.
+
+**Ory Network or OEL.** Either works. For an Ory Network project the URL is `https://<slug>.projects.oryapis.com`; for a self-hosted **Ory Enterprise License** deployment, point `--project-url` at that deployment's base URL and use the sign-in client id from its Agent Security configuration. Everything downstream — sign-in, checks, delegation — is identical.
+
+**There is nothing else for you to create.** The sign-in client, the permission model, the per-tool grants and blocks, and the observe/enforce posture are all provisioned in the Console by someone with project access. At runtime the plugin only *reads* permissions — it has no write path into your project, which is why installing it needs no workspace privilege. Each Cursor session registers its own identity automatically on first use.
+
+Sign-in runs at the start of every session and never blocks — a declined, skipped, or timed-out login simply leaves that session without a user identity.
+
+Settings are saved to `~/.config/ory-agent-plugins/config.json` and shared across all your Ory agent plugins; environment variables win when both are set. Running headless with an OAuth2 access token already? Set `ORY_USER_OAUTH2_TOKEN` and the browser step is skipped entirely.
+
+## Commands
+
+```
+ory-cursor install | uninstall        Install (add --project-url to also connect Agent Security) / remove
+ory-cursor status                     Show configuration, identities, permission coverage, recent activity
+ory-cursor permissions <cmd>          status  (read-only; grants + posture live in the Ory Console)
+ory-cursor configure <flags>          Connect a project (--project-url) or --disconnect
+ory-cursor agent <status|unregister>  Manage Cursor's own auto-created identity
+ory-cursor local <up|down|status|…>   Run / manage a local Ory in Docker
+ory-cursor version                    Print plugin, core, and Node versions (--json for machine-readable)
+```
+
+All prefixed with `npx -y -p @ory/cursor`.
+
+## Uninstall
+
+```bash
+npx -y -p @ory/cursor ory-cursor uninstall
+```
+
+Removes only the Ory entries from `hooks.json` / `mcp.json` and the Ory rules, and clears the shared credential store. Because configuration and credentials live in the shared `~/.config/ory-agent-plugins/config.json`, a login performed by any other Ory harness plugin or SDK integration is reused here.
+
+## Troubleshooting
+
+- **Hooks didn't take effect** — restart Cursor or reload the window so it re-reads `hooks.json`.
+- **`local-up` fails** — make sure Docker is running and ports `4000`, `4100`, `4455`, and `16686` are free.
+- **Browser sign-in loops** (after connecting) — reset with `ory-cursor agent unregister` and try again.
+- **Running an older CLI than expected** — `npx -p @ory/cursor` (no version pin) reuses a previously-downloaded copy instead of re-resolving to the latest. The install banner prints the running version; confirm it with `npx -y -p @ory/cursor ory-cursor version`. To force the current release, clear the cache and reinstall: `rm -rf ~/.npm/_npx` then `npx -y -p @ory/cursor ory-cursor install`. Pinning an exact version (`@ory/cursor@<version>`) also bypasses the cached copy.
+
+## Learn more
+
+- [Ory documentation](https://www.ory.com/docs/) · [Ory Console](https://console.ory.sh) · [Ory Elements](https://github.com/ory/elements)
+- [Cursor hooks documentation](https://cursor.com/docs/hooks)
+
+## License
+
+Apache-2.0

package/dist/cli/assets.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Materialize / clean the Ory skill catalog as Cursor **rules**.
+ *
+ * Cursor has no slash-command system and no SKILL.md discovery — the native way
+ * to inject reusable, model-facing guidance is a `.cursor/rules/*.mdc` file:
+ * YAML frontmatter (`description`, `alwaysApply`) followed by a markdown body.
+ * With `alwaysApply: false` + a description, Cursor's agent pulls a rule into
+ * context when the description matches what it's doing ("Agent Requested" rules).
+ *
+ * Both the guide skills and the local-stack commands are rendered from the
+ * shared `@ory/argus` templates and written as rules (commands are wrapped as
+ * skills first, mirroring the Codex/OpenClaw "commands-as-skills" pattern), so
+ * the guidance stays identical across every harness.
+ */
+/**
+ * Write every Ory rule under `<rulesDir>` (e.g. `~/.cursor/rules` or
+ * `<project>/.cursor/rules`). Overwrites existing Ory rules so template
+ * updates take effect; leaves unrelated rules untouched.
+ */
+export declare function installCursorOryRules(rulesDir: string): void;
+/** Remove every Ory rule this plugin installed under `<rulesDir>`. */
+export declare function uninstallCursorOryRules(rulesDir: string): void;

package/dist/cli/assets.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Materialize / clean the Ory skill catalog as Cursor **rules**.
+ *
+ * Cursor has no slash-command system and no SKILL.md discovery — the native way
+ * to inject reusable, model-facing guidance is a `.cursor/rules/*.mdc` file:
+ * YAML frontmatter (`description`, `alwaysApply`) followed by a markdown body.
+ * With `alwaysApply: false` + a description, Cursor's agent pulls a rule into
+ * context when the description matches what it's doing ("Agent Requested" rules).
+ *
+ * Both the guide skills and the local-stack commands are rendered from the
+ * shared `@ory/argus` templates and written as rules (commands are wrapped as
+ * skills first, mirroring the Codex/OpenClaw "commands-as-skills" pattern), so
+ * the guidance stays identical across every harness.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installCursorOryRules = installCursorOryRules;
+exports.uninstallCursorOryRules = uninstallCursorOryRules;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const argus_1 = require("@ory/argus");
+const RENDER_OPTS = {
+    binName: "ory-cursor",
+    packageName: "@ory/cursor",
+};
+/** Escape a value for a single-line YAML frontmatter scalar. */
+function yamlScalar(value) {
+    const needsQuote = /[:#"']/.test(value);
+    return needsQuote ? `"${value.replace(/"/g, '\\"')}"` : value;
+}
+/** Serialize a rendered skill as a Cursor `.mdc` rule. */
+function toMdc(skill) {
+    const body = skill.body.replace(/^\n+/, "").replace(/\s+$/, "");
+    return (`---\n` +
+        `description: ${yamlScalar(skill.description)}\n` +
+        `alwaysApply: false\n` +
+        `---\n\n` +
+        `${body}\n`);
+}
+/** Every Ory rule this plugin materializes (guides + commands-as-skills). */
+function renderRules() {
+    return [
+        ...(0, argus_1.renderOrySkills)("cursor", RENDER_OPTS),
+        ...(0, argus_1.renderOryCommands)("cursor", RENDER_OPTS).map(argus_1.commandToSkill),
+    ];
+}
+/**
+ * Write every Ory rule under `<rulesDir>` (e.g. `~/.cursor/rules` or
+ * `<project>/.cursor/rules`). Overwrites existing Ory rules so template
+ * updates take effect; leaves unrelated rules untouched.
+ */
+function installCursorOryRules(rulesDir) {
+    fs.mkdirSync(rulesDir, { recursive: true });
+    for (const rule of renderRules()) {
+        fs.writeFileSync(path.join(rulesDir, `${rule.name}.mdc`), toMdc(rule));
+    }
+}
+/** Remove every Ory rule this plugin installed under `<rulesDir>`. */
+function uninstallCursorOryRules(rulesDir) {
+    if (!fs.existsSync(rulesDir))
+        return;
+    for (const name of [...argus_1.ORY_SKILL_NAMES, ...argus_1.ORY_COMMAND_SKILL_NAMES]) {
+        const f = path.join(rulesDir, `${name}.mdc`);
+        if (fs.existsSync(f))
+            fs.unlinkSync(f);
+    }
+    try {
+        if (fs.readdirSync(rulesDir).length === 0)
+            fs.rmdirSync(rulesDir);
+    }
+    catch {
+        /* leave the dir if removal fails */
+    }
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Main CLI for @ory/cursor.
+ *
+ * Usage:
+ *   npx -y -p @ory/cursor ory-cursor install [--project]   Install hooks/MCP/rules
+ *   npx -y -p @ory/cursor ory-cursor uninstall [--project] Remove them
+ *   npx -y -p @ory/cursor ory-cursor configure             Set Ory project URL / API key
+ *   npx -y -p @ory/cursor ory-cursor permissions           Show permission mode and per-tool coverage
+ *   npx -y -p @ory/cursor ory-cursor status                Show plugin status
+ *   npx -y -p @ory/cursor ory-cursor local <cmd>           Manage the local Ory stack
+ */
+export {};

package/dist/cli/main.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Main CLI for @ory/cursor.
+ *
+ * Usage:
+ *   npx -y -p @ory/cursor ory-cursor install [--project]   Install hooks/MCP/rules
+ *   npx -y -p @ory/cursor ory-cursor uninstall [--project] Remove them
+ *   npx -y -p @ory/cursor ory-cursor configure             Set Ory project URL / API key
+ *   npx -y -p @ory/cursor ory-cursor permissions           Show permission mode and per-tool coverage
+ *   npx -y -p @ory/cursor ory-cursor status                Show plugin status
+ *   npx -y -p @ory/cursor ory-cursor local <cmd>           Manage the local Ory stack
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const path = __importStar(require("node:path"));
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const argus_1 = require("@ory/argus");
+const setup_js_1 = require("./setup.js");
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+function main() {
+    const [command, ...args] = process.argv.slice(2);
+    // `--help` after a matched subcommand: print usage, do nothing else.
+    // Without this the switch below ignores the flag and `install --help`
+    // performs a real install (#221).
+    if ((0, argus_1.shouldPrintHelp)(command, args))
+        return help();
+    switch (command) {
+        case "install":
+            (0, argus_1.beginDeferNextSteps)();
+            (0, setup_js_1.install)(args);
+            (0, argus_1.runPostInstall)("ory-cursor", "cursor", args).then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "uninstall":
+            (0, setup_js_1.uninstall)(args);
+            (0, argus_1.clearCredentialsForUninstall)({
+                harness: "cursor",
+                purge: args.includes("--purge"),
+            }).then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "configure":
+            (0, argus_1.runConfigureCommand)("ory-cursor", args);
+            break;
+        case "agent":
+            (0, argus_1.runAgentCommand)("ory-cursor", "cursor", args).then((code) => process.exit(code), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "permissions":
+            (0, argus_1.runPermissionsCommand)("ory-cursor", "cursor", args).then((code) => process.exit(code), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "status":
+            status().then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "watch":
+            (0, argus_1.runWatchCommand)("ory-cursor", "cursor", args).then((code) => process.exit(code), (err) => { console.error(err.message ?? err); process.exit(1); });
+            break;
+        case "local":
+            (0, argus_1.runLocalCommand)("ory-cursor", args).catch((err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
+        case "version":
+        case "--version":
+        case "-v":
+            process.exit((0, argus_1.runVersionCommand)("ory-cursor", args, { packageRoot: PACKAGE_ROOT }));
+            break;
+        case "help":
+        case "--help":
+        case "-h":
+        case undefined:
+            help();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            help();
+            process.exit(1);
+    }
+}
+async function status() {
+    await (0, argus_1.runStatusCommand)("ory-cursor", "cursor", {
+        title: "Cursor",
+        printPluginSection: () => {
+            const userHooks = path.join(os.homedir(), ".cursor", "hooks.json");
+            const projectHooks = path.join(process.cwd(), ".cursor", "hooks.json");
+            console.log("Hooks & plugin:");
+            console.log(`  User hooks:    ${fs.existsSync(userHooks) ? userHooks : "(not installed at ~/.cursor)"}`);
+            console.log(`  Project hooks: ${fs.existsSync(projectHooks) ? projectHooks : "(none in this project)"}`);
+            console.log(`  Runtime:       ${(0, argus_1.describeRuntimeHealth)((0, argus_1.checkRuntimeHealth)("cursor"))}`);
+        },
+    });
+}
+function help() {
+    console.log(`
+ory-cursor — Ory plugin for Cursor
+
+Usage:
+  npx -y -p @ory/cursor ory-cursor <command> [options]
+
+Commands:
+  install [--project]   Install Ory hooks, MCP server, and rules into ~/.cursor (or ./.cursor)
+  uninstall [--project] Remove them
+  configure             Set or view Ory project URL and API key
+  agent <cmd>           Manage the agent's OAuth2 (DCR) identity (status, unregister)
+  permissions           Show the live permission mode and per-tool coverage
+  status                Show plugin status and configuration
+  watch [--json] [--lines <count>]
+                        Follow the live activity/debug log
+  version               Show version and the ory-agent-plugins build commit
+  local <cmd>           Manage local Ory dev environment (up, down, status, seed, ...)
+
+Examples:
+  npx -y -p @ory/cursor ory-cursor install
+  npx -y -p @ory/cursor ory-cursor configure --project-url https://your-project.projects.oryapis.com --agent-security-url https://agents.console.ory.com
+  npx -y -p @ory/cursor ory-cursor status
+  npx -y -p @ory/cursor ory-cursor uninstall
+`);
+}
+main();

package/dist/cli/setup.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Install / uninstall the Ory plugin for Cursor.
+ *
+ * Cursor has no plugin marketplace or registration CLI — it discovers hooks
+ * from a `hooks.json`, MCP servers from an `mcp.json`, and guidance from
+ * `.cursor/rules/*.mdc`, in the user-global `~/.cursor/` dir (default) or a
+ * project-local `<cwd>/.cursor/` dir (`--project`). Install merges the Ory
+ * entries into those files non-destructively; uninstall removes only what Ory
+ * added, leaving everything else intact.
+ *
+ * Usage:
+ *   npx -y -p @ory/cursor ory-cursor-setup [--project] [--print]   Install
+ *   npx -y -p @ory/cursor ory-cursor-setup --uninstall [--project] Remove
+ */
+export declare function install(args: string[]): void;
+export declare function uninstall(args: string[]): void;

package/dist/cli/setup.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Install / uninstall the Ory plugin for Cursor.
+ *
+ * Cursor has no plugin marketplace or registration CLI — it discovers hooks
+ * from a `hooks.json`, MCP servers from an `mcp.json`, and guidance from
+ * `.cursor/rules/*.mdc`, in the user-global `~/.cursor/` dir (default) or a
+ * project-local `<cwd>/.cursor/` dir (`--project`). Install merges the Ory
+ * entries into those files non-destructively; uninstall removes only what Ory
+ * added, leaving everything else intact.
+ *
+ * Usage:
+ *   npx -y -p @ory/cursor ory-cursor-setup [--project] [--print]   Install
+ *   npx -y -p @ory/cursor ory-cursor-setup --uninstall [--project] Remove
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.install = install;
+exports.uninstall = uninstall;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const argus_1 = require("@ory/argus");
+const assets_js_1 = require("./assets.js");
+const PACKAGE_ROOT = path.resolve(__dirname, "..", "..");
+const PACKAGE_NAME = "@ory/cursor";
+const MCP_KEY = "ory";
+/** Marker identifying an Ory-owned hooks.json entry (for idempotent merge). */
+/** SessionStart may run the interactive PKCE browser login — generous window.
+ *  Tool-lifecycle hooks only make a permission check. Seconds (Cursor's unit).
+ *  Derived in core so the session-start window cannot drift below the login
+ *  timeout it has to outlast. */
+const SESSION_START_TIMEOUT_SEC = (0, argus_1.sessionStartHookTimeout)("cursor", "seconds");
+const TOOL_HOOK_TIMEOUT_SEC = (0, argus_1.toolHookTimeout)("cursor", "seconds");
+function resolveTarget(args) {
+    const project = args.includes("--project");
+    const baseDir = project
+        ? path.join(process.cwd(), ".cursor")
+        : path.join(os.homedir(), ".cursor");
+    return {
+        baseDir,
+        hooksPath: path.join(baseDir, "hooks.json"),
+        mcpPath: path.join(baseDir, "mcp.json"),
+        rulesDir: path.join(baseDir, "rules"),
+        scope: project ? "project" : "user",
+    };
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(value, null, 2) + "\n");
+}
+/**
+ * Resolve this install's runtime and write its shims.
+ *
+ * Cursor's `preToolUse` gate is registered `failClosed: true` (see
+ * {@link oryHooksBlock}), so a hook that cannot answer blocks every tool. That
+ * makes the shim's runtime-missing path load-bearing: it has to emit an
+ * explicit allow, not just exit 0.
+ */
+function wireCursorRuntime(args) {
+    return (0, argus_1.wireRuntime)({
+        harness: "cursor",
+        packageName: PACKAGE_NAME,
+        packageRoot: PACKAGE_ROOT,
+        installCommand: "npx -y -p @ory/cursor ory-cursor install",
+        args,
+        fallbackStdout: JSON.stringify({ permission: "allow" }),
+    });
+}
+/**
+ * Build the Ory hooks block. Only the load-bearing events are registered:
+ * `preToolUse` is the permission gate; the rest are audit/identity. The
+ * fine-grained shell/MCP/file hooks are intentionally omitted — `preToolUse`
+ * already covers those categories, and registering them would spawn a hook
+ * subprocess per file read / shell line for no added enforcement.
+ *
+ * The `preToolUse` gate is registered `failClosed: true`. Cursor's hook default
+ * is fail-open: a crashed / timed-out / malformed-JSON hook lets the tool
+ * through. For the one hook that makes the permission decision that would
+ * silently defeat `enforce` mode (the whole point of the gate), so we opt it
+ * into fail-closed — if the gate can't produce a verdict, Cursor blocks the
+ * tool. The gate still fails *open* on the paths Ory treats as non-blocking
+ * (network / rate-limit), because those are handled inside the hook, which
+ * exits 0 with an allow verdict; `failClosed` only governs the hook process
+ * itself failing to answer. The audit/identity hooks stay fail-open — none of
+ * them gate a tool, and session start must never block.
+ */
+function oryHooksBlock(command) {
+    const entry = (timeout, failClosed = false) => [
+        failClosed ? { command, timeout, failClosed } : { command, timeout },
+    ];
+    return {
+        sessionStart: entry(SESSION_START_TIMEOUT_SEC),
+        sessionEnd: entry(TOOL_HOOK_TIMEOUT_SEC),
+        preToolUse: entry(TOOL_HOOK_TIMEOUT_SEC, true),
+        postToolUse: entry(TOOL_HOOK_TIMEOUT_SEC),
+        postToolUseFailure: entry(TOOL_HOOK_TIMEOUT_SEC),
+        beforeSubmitPrompt: entry(TOOL_HOOK_TIMEOUT_SEC),
+        subagentStart: entry(TOOL_HOOK_TIMEOUT_SEC),
+        subagentStop: entry(TOOL_HOOK_TIMEOUT_SEC),
+    };
+}
+function isOryEntry(entry) {
+    return (typeof entry === "object" &&
+        entry !== null &&
+        typeof entry.command === "string" &&
+        (0, argus_1.isOryRuntimeCommand)(entry.command));
+}
+/**
+ * Merge the Ory hooks into an existing hooks.json shape, dropping any prior Ory
+ * entries (idempotent re-install) and preserving every non-Ory entry.
+ */
+function mergeHooks(existing, command) {
+    const hooks = existing.hooks ?? {};
+    const merged = {};
+    // Keep every existing event's non-Ory entries.
+    for (const [event, entries] of Object.entries(hooks)) {
+        const kept = Array.isArray(entries) ? entries.filter((e) => !isOryEntry(e)) : [];
+        if (kept.length > 0)
+            merged[event] = kept;
+    }
+    // Add the Ory entries.
+    for (const [event, entries] of Object.entries(oryHooksBlock(command))) {
+        merged[event] = [...(merged[event] ?? []), ...entries];
+    }
+    return { ...existing, version: existing.version ?? 1, hooks: merged };
+}
+function removeOryHooks(existing) {
+    const hooks = existing.hooks ?? {};
+    const cleaned = {};
+    for (const [event, entries] of Object.entries(hooks)) {
+        const kept = Array.isArray(entries) ? entries.filter((e) => !isOryEntry(e)) : [];
+        if (kept.length > 0)
+            cleaned[event] = kept;
+    }
+    return { ...existing, hooks: cleaned };
+}
+function mergeMcp(existing, server) {
+    const servers = existing.mcpServers ?? {};
+    return { ...existing, mcpServers: { ...servers, [MCP_KEY]: server } };
+}
+function removeMcp(existing) {
+    const servers = { ...(existing.mcpServers ?? {}) };
+    delete servers[MCP_KEY];
+    return { ...existing, mcpServers: servers };
+}
+function install(args) {
+    const target = resolveTarget(args);
+    if (args.includes("--print")) {
+        // Nothing is resolved or written on a --print run.
+        console.log(JSON.stringify(mergeHooks(readJson(target.hooksPath), 'node "<runtime shim>"'), null, 2));
+        return;
+    }
+    const runtime = wireCursorRuntime(args);
+    console.log(runtime.target.kind === "linked"
+        ? `Runtime: linked to ${runtime.target.packageDir} (dev)`
+        : `Runtime: ${runtime.target.packageName}@${runtime.target.version} in ${runtime.target.storeDir}`);
+    for (const pruned of runtime.prunedStores) {
+        console.log(`  Removed stale runtime: ${pruned}`);
+    }
+    writeJson(target.hooksPath, mergeHooks(readJson(target.hooksPath), (0, argus_1.requireHookCommand)(runtime)));
+    if (runtime.mcpServer) {
+        writeJson(target.mcpPath, mergeMcp(readJson(target.mcpPath), runtime.mcpServer));
+    }
+    (0, assets_js_1.installCursorOryRules)(target.rulesDir);
+    console.log(`Installed the Ory plugin for Cursor (${target.scope} scope):`);
+    console.log(`  Hooks:  ${target.hooksPath}`);
+    if (runtime.mcpServer) {
+        console.log(`  MCP:    ${target.mcpPath} (mcpServers.${MCP_KEY})`);
+    }
+    console.log(`  Rules:  ${target.rulesDir}/ory-*.mdc`);
+    printNextSteps();
+}
+function uninstall(args) {
+    const target = resolveTarget(args);
+    if (fs.existsSync(target.hooksPath)) {
+        writeJson(target.hooksPath, removeOryHooks(readJson(target.hooksPath)));
+    }
+    if (fs.existsSync(target.mcpPath)) {
+        writeJson(target.mcpPath, removeMcp(readJson(target.mcpPath)));
+    }
+    (0, assets_js_1.uninstallCursorOryRules)(target.rulesDir);
+    (0, argus_1.removeRuntimeWiring)("cursor");
+    for (const pruned of (0, argus_1.pruneRuntimeStores)()) {
+        console.log(`  Removed runtime: ${pruned}`);
+    }
+    console.log(`Removed the Ory plugin for Cursor (${target.scope} scope).`);
+}
+function printNextSteps() {
+    const npx = "npx -y -p @ory/cursor ory-cursor";
+    (0, argus_1.nextStepsSink)(({ configured }) => {
+        console.log("");
+        console.log("Next steps:");
+        console.log("  Restart Cursor (or reload the window) so it picks up the new hooks.");
+        console.log("");
+        if (configured) {
+            if (!(0, argus_1.isSecurityConnected)()) {
+                console.log("  Agent Security not connected: tool activity is recorded locally — no checks, nothing blocked.");
+            }
+            else {
+                console.log("  It starts in observe mode: every tool call is checked, nothing blocked yet.");
+                console.log("  Turn on enforcement:  in the Ory Console (Agent Security)");
+            }
+        }
+        else {
+            console.log("  (Optional) Point at an Ory project — without it, the plugin runs in");
+            console.log("  pass-through mode (rules work, nothing is blocked):");
+            console.log(`     ${npx} configure --project-url https://<slug>.projects.oryapis.com`);
+            console.log("     The broker and login client use production defaults; flags can override them.");
+            console.log("");
+            console.log("  Or spin up the local Ory stack: ask Cursor to run the ory-local-up rule.");
+        }
+        console.log("");
+        console.log(`  See what Ory is doing:  ${npx} status`);
+        console.log("  Stream activity live:   export ORY_AGENT_DEBUG=true");
+        console.log("");
+        console.log(`To uninstall: ${npx} uninstall`);
+    });
+}
+// --- Standalone binary entry point (ory-cursor-setup) ---
+if (require.main === module) {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(`
+ory-cursor-setup — Install or remove the Ory plugin for Cursor
+
+Usage:
+  npx -y -p @ory/cursor ory-cursor-setup [options]
+
+Options:
+  --uninstall    Remove the Ory hooks, MCP server, and rules
+  --project      Target <cwd>/.cursor instead of ~/.cursor
+  --print        Print the merged hooks.json without writing (install only)
+  -h, --help     Show this help
+`);
+        process.exit(0);
+    }
+    if (args.includes("--uninstall")) {
+        uninstall(args);
+        (0, argus_1.clearCredentialsForUninstall)({
+            harness: "cursor",
+            purge: process.argv.includes("--purge"),
+        }).then(() => process.exit(0), (err) => {
+            console.error(err.message ?? err);
+            process.exit(1);
+        });
+    }
+    else {
+        install(args);
+    }
+}

package/dist/handlers.d.ts

@@ -0,0 +1,14 @@
+import { OryAgentClient, ensureUserAuthenticated, ensureAgentIdentity, ensureSubAgentIdentity } from "@ory/argus";
+import type { CursorHookInput, CursorHookOutput } from "./types.js";
+export interface HandleHookEventDeps {
+    /** Test injection point for the user login flow. */
+    userLogin?: typeof ensureUserAuthenticated;
+    /** Test injection point for the agent identity gate. */
+    agentGate?: typeof ensureAgentIdentity;
+    /** Test injection point for the sub-agent identity resolver. */
+    subAgentGate?: typeof ensureSubAgentIdentity;
+}
+/**
+ * Route a Cursor hook event to the appropriate Ory integration.
+ */
+export declare function handleHookEvent(input: CursorHookInput, client: OryAgentClient, deps?: HandleHookEventDeps): Promise<CursorHookOutput>;

package/dist/handlers.js

@@ -0,0 +1,252 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleHookEvent = handleHookEvent;
+const argus_1 = require("@ory/argus");
+const HARNESS = "cursor";
+/**
+ * Cursor doesn't always send `session_id` outside sessionStart — fall back to
+ * the conversation id so activity within one conversation still correlates.
+ *
+ * Returns `undefined` when Cursor sends neither, rather than a placeholder. A
+ * constant here would be read as a real session everywhere downstream: the
+ * derived per-session subject (`Agent:<clientId>|<session>`) would be the same
+ * string for every unidentified run, so a block meant for one of them would hit
+ * all of them, and the delegation graph would collapse them onto one node. No
+ * session is the honest answer, and the identity model handles it through the
+ * reserved sessionless credential slot.
+ */
+function sessionKey(input) {
+    return input.session_id ?? input.conversation_id;
+}
+/**
+ * Route a Cursor hook event to the appropriate Ory integration.
+ */
+async function handleHookEvent(input, client, deps = {}) {
+    const event = input.hook_event_name;
+    client.logger.debug("hook.received", {
+        event,
+        sessionId: sessionKey(input),
+        toolName: input.tool_name,
+    });
+    return (0, argus_1.withHookContext)(client, {
+        sessionId: sessionKey(input),
+    }, async () => {
+        switch (event) {
+            case "sessionStart":
+                return await handleSessionStart(input, client, deps);
+            case "preToolUse":
+                return await handlePreToolUse(input, client);
+            case "postToolUse":
+                return await handlePostToolUse(input, client);
+            case "postToolUseFailure":
+                return await handlePostToolUseFailure(input, client);
+            case "beforeSubmitPrompt":
+                return await handleBeforeSubmitPrompt(input, client);
+            case "subagentStart":
+                return await handleSubagentStart(input, client, deps);
+            case "subagentStop":
+                return await handleSubagentStop(input, client);
+            case "sessionEnd":
+                return await handleSessionEnd(input, client);
+            case "preCompact":
+                return await handleAudit(input, client, "compaction", {
+                    trigger: input.trigger,
+                });
+            // Fine-grained shell / MCP / file hooks surface activity to the user and
+            // are activity-only — `preToolUse` already ran the permission gate for the
+            // corresponding tool category, so gating here would double-count.
+            case "beforeShellExecution":
+            case "afterShellExecution":
+                return await handleAudit(input, client, "user.interaction", {
+                    kind: event,
+                    hasCommand: input.command !== undefined,
+                });
+            case "beforeMCPExecution":
+            case "afterMCPExecution":
+                return await handleAudit(input, client, "user.interaction", {
+                    kind: event,
+                    mcpTool: input.tool_name,
+                });
+            case "beforeReadFile":
+            case "afterFileEdit":
+                return await handleAudit(input, client, "user.interaction", {
+                    kind: event,
+                    hasFilePath: input.file_path !== undefined,
+                });
+            default:
+                client.logger.debug("hook.passthrough", { event });
+                client.logger.activity("hook.passthrough", "skipped", {
+                    attributes: { event },
+                });
+                return {};
+        }
+    });
+}
+// ─── sessionStart ───────────────────────────────────────────────────
+async function handleSessionStart(input, client, deps) {
+    client.logger.info("lifecycle.session_start", {
+        sessionId: sessionKey(input),
+        model: input.model,
+        composerMode: input.composer_mode,
+    });
+    await (0, argus_1.sessionStart)(client, {
+        binName: "ory-cursor",
+        harness: HARNESS,
+        userLogin: deps.userLogin,
+        agentGate: deps.agentGate,
+        activityAttributes: { model: input.model, composerMode: input.composer_mode },
+    });
+    return {};
+}
+// ─── preToolUse — the permission gate ───────────────────────────────
+async function handlePreToolUse(input, client) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.pre_tool_use", {
+        sessionId: sessionKey(input),
+        toolName,
+        toolInput: input.tool_input,
+    });
+    // Only offer a `session:` fallback subject when Cursor actually sent a
+    // session — interpolating an absent one yields the literal
+    // `session:undefined`, a subject that matches nothing yet looks like a real
+    // one in the audit trail.
+    const session = sessionKey(input);
+    const subAgentType = input.subagent_type;
+    const subAgent = subAgentType
+        ? session
+            ? (0, argus_1.loadSubAgentDynamicCredentials)(HARNESS, session, subAgentType)
+            : (0, argus_1.loadSubAgentDynamicCredentials)(HARNESS, subAgentType)
+        : undefined;
+    const result = await (0, argus_1.gate)(client, {
+        harness: HARNESS,
+        toolName,
+        toolArgs: input.tool_input,
+        subjectFallback: session ? `session:${session}` : undefined,
+        principals: subAgent
+            ? {
+                subAgentClientId: subAgent.clientId,
+                subAgentType,
+                perSpawnId: input.subagent_id,
+                sessionId: session,
+            }
+            : undefined,
+    });
+    if (result.blocked) {
+        const reason = result.denialMessage;
+        return { permission: "deny", agent_message: reason, user_message: reason };
+    }
+    return {};
+}
+// ─── postToolUse ────────────────────────────────────────────────────
+async function handlePostToolUse(input, client) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.post_tool_use", {
+        sessionId: sessionKey(input),
+        toolName,
+    });
+    (0, argus_1.complete)(client, {
+        toolName,
+        input: input.tool_input,
+        output: input.tool_output,
+        extraActivityAttributes: {
+            toolUseId: input.tool_use_id,
+            durationMs: input.duration,
+        },
+    });
+    return {};
+}
+// ─── postToolUseFailure ─────────────────────────────────────────────
+async function handlePostToolUseFailure(input, client) {
+    const toolName = input.tool_name ?? "unknown";
+    client.logger.info("lifecycle.post_tool_use_failure", {
+        sessionId: sessionKey(input),
+        toolName,
+        failureType: input.failure_type,
+    });
+    if (input.error_message !== undefined) {
+        client.logger.debug("lifecycle.post_tool_use_failure.error", {
+            error: input.error_message,
+        });
+    }
+    (0, argus_1.fail)(client, {
+        toolName,
+        input: input.tool_input,
+        extraActivityAttributes: {
+            toolUseId: input.tool_use_id,
+            failureType: input.failure_type,
+            hasError: input.error_message !== undefined,
+        },
+    });
+    return {};
+}
+// ─── beforeSubmitPrompt ─────────────────────────────────────────────
+async function handleBeforeSubmitPrompt(input, client) {
+    client.logger.info("lifecycle.before_submit_prompt", {
+        sessionId: sessionKey(input),
+        promptLen: input.prompt?.length,
+    });
+    client.logger.activity("user.prompt", "ok", {
+        attributes: { promptLen: input.prompt?.length },
+    });
+    // Never block the human's prompt — the user is the decision-maker.
+    return { continue: true };
+}
+// ─── subagentStart / subagentStop ───────────────────────────────────
+async function handleSubagentStart(input, client, deps) {
+    const subAgentType = input.subagent_type;
+    client.logger.info("lifecycle.subagent_start", {
+        sessionId: sessionKey(input),
+        subAgentType,
+        subAgentId: input.subagent_id,
+    });
+    client.logger.activity("subagent.start", "ok", {
+        attributes: { subAgentType, subAgentId: input.subagent_id },
+    });
+    if (subAgentType && (0, argus_1.isSecurityConnected)()) {
+        await (0, argus_1.registerSubagent)(client, {
+            harness: HARNESS,
+            subAgentType,
+            perSpawnId: input.subagent_id,
+            subAgentGate: deps.subAgentGate,
+        });
+    }
+    // Subagent creation is never blocked — identity/audit only.
+    return {};
+}
+async function handleSubagentStop(input, client) {
+    client.logger.info("lifecycle.subagent_stop", {
+        sessionId: sessionKey(input),
+        subAgentType: input.subagent_type,
+        status: input.status,
+    });
+    client.logger.activity("subagent.stop", "ok", {
+        attributes: {
+            subAgentType: input.subagent_type,
+            status: input.status,
+            summaryLen: input.summary?.length,
+        },
+    });
+    return {};
+}
+// ─── sessionEnd ─────────────────────────────────────────────────────
+async function handleSessionEnd(input, client) {
+    client.logger.info("lifecycle.session_end", {
+        sessionId: sessionKey(input),
+        reason: input.reason,
+    });
+    client.logger.activity("session.end", "ok", {
+        attributes: { reason: input.reason, durationMs: input.duration_ms },
+    });
+    return {};
+}
+// ─── Generic activity event ─────────────────────────────────────────
+async function handleAudit(input, client, activity, attributes) {
+    client.logger.debug("lifecycle.audit", {
+        sessionId: sessionKey(input),
+        event: input.hook_event_name,
+        activity,
+    });
+    client.logger.activity(activity, "ok", { attributes });
+    return {};
+}
+// ─── Helpers ────────────────────────────────────────────────────────

package/dist/hook.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Cursor hook entry point.
+ * Invoked by Cursor as a subprocess for each hook event.
+ * Input: JSON on stdin. Output: JSON on stdout.
+ * A block is signaled by `permission: "deny"` / `continue: false` in the JSON
+ * output; exit code 2 is honored as an equivalent block signal.
+ */
+export {};

package/dist/hook.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Cursor hook entry point.
+ * Invoked by Cursor as a subprocess for each hook event.
+ * Input: JSON on stdin. Output: JSON on stdout.
+ * A block is signaled by `permission: "deny"` / `continue: false` in the JSON
+ * output; exit code 2 is honored as an equivalent block signal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const argus_1 = require("@ory/argus");
+const handlers_js_1 = require("./handlers.js");
+const EVENT_FLUSH_TIMEOUT_MS = 750;
+let client;
+async function flushEvents() {
+    try {
+        await client?.flushEvents(EVENT_FLUSH_TIMEOUT_MS);
+    }
+    catch {
+        // The hook decision must not depend on activity delivery.
+    }
+}
+/**
+ * Read all of stdin. Resolves on `end`, or after a short idle gap once data has
+ * arrived (some parents don't close stdin promptly).
+ */
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let resolved = false;
+        function done() {
+            if (!resolved) {
+                resolved = true;
+                resolve(Buffer.concat(chunks).toString("utf-8"));
+            }
+        }
+        let idleTimer;
+        process.stdin.on("data", (chunk) => {
+            chunks.push(chunk);
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(done, 100);
+        });
+        process.stdin.on("end", done);
+        process.stdin.on("error", (err) => {
+            if (!resolved) {
+                resolved = true;
+                reject(err);
+            }
+        });
+    });
+}
+async function main() {
+    client = argus_1.OryAgentClient.fromEnv("cursor");
+    const raw = await readStdin();
+    let input;
+    try {
+        input = JSON.parse(raw);
+    }
+    catch {
+        client.logger.error("hook.stdin.parse_failed", { raw: raw.slice(0, 200) });
+        process.exit(0); // Don't block on parse errors
+    }
+    const output = await (0, handlers_js_1.handleHookEvent)(input, client);
+    const blocked = output.permission === "deny" || output.continue === false;
+    if (Object.keys(output).length > 0) {
+        process.stdout.write(JSON.stringify(output));
+    }
+    await flushEvents();
+    process.exit(blocked ? 2 : 0);
+}
+main().catch(async (err) => {
+    process.stderr.write(`[ory-agent] fatal: ${err}\n`);
+    await flushEvents();
+    process.exit(0); // Fail open
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { handleHookEvent } from "./handlers.js";
+export type { CursorHookInput, CursorHookOutput } from "./types.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleHookEvent = void 0;
+var handlers_js_1 = require("./handlers.js");
+Object.defineProperty(exports, "handleHookEvent", { enumerable: true, get: function () { return handlers_js_1.handleHookEvent; } });

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Cursor hook event payload delivered on stdin, and the response written to
+ * stdout.
+ *
+ * Cursor runs each hook as a standalone subprocess: it writes a JSON object to
+ * the hook's stdin and reads a JSON object from stdout. Blocking-capable hooks
+ * (`preToolUse`, `beforeShellExecution`, `beforeMCPExecution`, `beforeReadFile`,
+ * `subagentStart`) honor `permission: "deny"`; `beforeSubmitPrompt` blocks with
+ * `continue: false`. Exit code 2 also blocks. See https://cursor.com/docs/hooks
+ *
+ * Every hook additionally receives a set of base fields (conversation_id,
+ * generation_id, hook_event_name, workspace_roots, …). We model the union of
+ * everything the handler reads; unknown fields are ignored.
+ */
+export interface CursorHookInput {
+    /** Always present — the event that fired (e.g. "preToolUse"). */
+    hook_event_name: string;
+    conversation_id?: string;
+    generation_id?: string;
+    model?: string;
+    cursor_version?: string;
+    workspace_roots?: string[];
+    user_email?: string | null;
+    transcript_path?: string | null;
+    cwd?: string;
+    session_id?: string;
+    is_background_agent?: boolean;
+    composer_mode?: string;
+    /** sessionEnd */
+    reason?: string;
+    duration_ms?: number;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    /** postToolUse — JSON-stringified tool output. */
+    tool_output?: string;
+    tool_use_id?: string;
+    duration?: number;
+    /** postToolUseFailure */
+    error_message?: string;
+    failure_type?: "error" | "timeout" | "permission_denied" | string;
+    command?: string;
+    sandbox?: boolean;
+    output?: string;
+    /** MCP url (remote) — present for MCP hooks. */
+    url?: string;
+    file_path?: string;
+    edits?: Array<{
+        old_string?: string;
+        new_string?: string;
+    }>;
+    prompt?: string;
+    attachments?: Array<{
+        type?: string;
+        file_path?: string;
+    }>;
+    subagent_id?: string;
+    subagent_type?: string;
+    task?: string;
+    parent_conversation_id?: string;
+    tool_call_id?: string;
+    status?: string;
+    summary?: string;
+    trigger?: "auto" | "manual" | string;
+    [key: string]: unknown;
+}
+/**
+ * Cursor hook output written to stdout.
+ *
+ * - `permission: "deny"` on `preToolUse` / `beforeShellExecution` /
+ *   `beforeMCPExecution` / `beforeReadFile` / `subagentStart` blocks the action.
+ *   `agent_message` is surfaced to the model; `user_message` to the human.
+ * - `continue: false` on `beforeSubmitPrompt` blocks the submission.
+ * - Fire-and-forget hooks (sessionStart, post*, after*, stop, …) return `{}`.
+ */
+export interface CursorHookOutput {
+    permission?: "allow" | "deny" | "ask";
+    continue?: boolean;
+    agent_message?: string;
+    user_message?: string;
+    /** preToolUse may rewrite the tool input; unused here. */
+    updated_input?: Record<string, unknown>;
+    [key: string]: unknown;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1 +1,76 @@
-{"name":"@ory/cursor","version":"0.0.0-bootstrap.0","license":"Apache-2.0","description":"Bootstrap package for trusted publishing"}
+{
+  "name": "@ory/cursor",
+  "version": "1.0.0",
+  "description": "Ory plugin for Cursor: scaffolding rules, a local Ory instance, and authentication, authorization, and audit for every tool call",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/ory/ory-agent-plugins/tree/main/packages/cursor",
+  "bugs": {
+    "url": "https://github.com/ory/ory-agent-plugins/issues"
+  },
+  "keywords": [
+    "ory",
+    "cursor",
+    "cursor-editor",
+    "hooks",
+    "plugin",
+    "identity",
+    "authentication",
+    "authorization",
+    "access-control",
+    "permissions",
+    "zanzibar",
+    "oauth2",
+    "audit",
+    "agent",
+    "ai-agent",
+    "agent-security",
+    "guardrails",
+    "mcp",
+    "activity-auditing",
+    "observability"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "provenance": true
+  },
+  "reova": {
+    "enabled": true,
+    "endpoint": "https://telemetry.reo.dev/data"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "ory-cursor": "dist/cli/main.js",
+    "ory-cursor-hook": "dist/hook.js",
+    "ory-cursor-setup": "dist/cli/setup.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "reova": "^0.7.0",
+    "@ory/argus": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.2",
+    "vitest": "4.1.4"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}