@raindrop-ai/cursor 0.0.1

package/.cursor-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "raindrop",
+  "version": "0.0.1",
+  "description": "Session, tool call, and token tracing for Cursor agents",
+  "author": { "name": "Raindrop AI", "email": "support@raindrop.ai" },
+  "license": "MIT",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "raindrop-diagnostics": {
+      "command": "node",
+      "args": ["${CURSOR_PLUGIN_ROOT}/dist/cli.js", "mcp-serve"]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raindrop AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @raindrop-ai/cursor
+
+Capture Cursor IDE, `cursor-agent` CLI, and Cloud Agent turns in Raindrop using Cursor hooks. No application code changes are required.
+
+## Install
+
+Requires Node.js 20 or later.
+
+```bash
+npm install -g @raindrop-ai/cursor
+raindrop-cursor setup
+export RAINDROP_WRITE_KEY="your-write-key"
+```
+
+Setup merges hooks into `~/.cursor/hooks.json` and adds a self-diagnostics MCP server to `~/.cursor/mcp.json`. Existing hooks and other MCP servers are preserved. Setup asks for a Raindrop write key and an optional project slug; a blank project uses the org default Production project.
+
+For a repository and its Cloud Agents:
+
+```bash
+npx -y @raindrop-ai/cursor setup --scope project
+```
+
+Commit `.cursor/hooks.json` and `.cursor/mcp.json`. Project hooks use `npx -y @raindrop-ai/cursor@<version> hook`, pinned to the CLI version that ran setup; rerunning setup refreshes the pin. The machine needs Node.js, npm, and package registry access. Set `RAINDROP_WRITE_KEY` and `RAINDROP_LOCAL_DEBUGGER=false` in the Cloud Agent's runtime secrets. For a named project, also set `RAINDROP_PROJECT_ID` there. Setup saves your project choice in local shared configuration, which is unavailable on Cloud Agent VMs.
+
+Install in one scope per conversation to avoid duplicate hook deliveries.
+
+## Captured data
+
+Each `generation_id` gets one `ai_generation` event. `beforeSubmitPrompt` opens it, `afterAgentResponse` patches output, and `stop` finalizes it. A turn can also begin from later hooks when lifecycle events are absent.
+
+The integration records:
+
+- Generic tool success and failure spans, using Cursor's duration. Permission denials also produce `ai.permissionDenied`.
+- `ai.thinking` spans.
+- One model span per turn, with input, output, cache-read, and cache-write usage when Cursor provides it.
+- Session usage totals, compaction metadata, and session-end metadata.
+
+`stop` counts are cumulative for the turn. They replace response counts rather than being added again. Missing counts remain absent. Duplicate `stop` hooks do not add another model span or double session totals.
+
+At `sessionEnd`, turns missing a `stop` receive a cancelled model span and a final event patch with their captured usage. This includes earlier unfinished generations. Their usage enters the final session totals once. Already completed turns do not get another model span.
+
+Generic tool hooks avoid double-counting shell, file, and MCP tool operations. Specialized tool hooks and Tab hooks are not installed.
+
+## Configuration
+
+Configuration is shared with the Claude Code integration at `~/.config/raindrop/config.json`.
+
+| Environment variable | Purpose |
+| --- | --- |
+| `RAINDROP_WRITE_KEY` | Raindrop write key |
+| `RAINDROP_API_URL` | Ingest base URL; defaults to `https://api.raindrop.ai/v1` |
+| `RAINDROP_PROJECT_ID` | Project override |
+| `RAINDROP_USER_ID` | User ID fallback; Cursor's `user_email` takes precedence |
+| `RAINDROP_CONVO_ID` | Conversation ID override |
+| `RAINDROP_EVENT_NAME` | Event name; defaults to `ai_generation` |
+| `RAINDROP_PROPERTIES` | JSON object merged with configured custom properties |
+| `RAINDROP_ENABLED` | `false` or `0` disables telemetry |
+| `RAINDROP_DEBUG` | `true` enables debug logging |
+| `RAINDROP_HOOK_FLUSH_DEADLINE_MS` | Whole hook deadline; defaults to 8000 ms |
+| `RAINDROP_LOCAL_DEBUGGER` | Local debugger URL, or `false` to disable discovery |
+| `RAINDROP_SELF_DIAGNOSTICS` | JSON object with optional `signals`, `guidance`, and `toolName` |
+
+```bash
+raindrop-cursor status
+raindrop-cursor disable
+raindrop-cursor enable
+raindrop-cursor debug-on
+raindrop-cursor debug-off
+raindrop-cursor uninstall
+raindrop-cursor uninstall --scope project
+```
+
+Enable, disable, and debug commands update shared Raindrop configuration, including its use by the Claude Code integration.
+
+## Local debugger
+
+Start the Raindrop local debugger on port 5899, or set `RAINDROP_LOCAL_DEBUGGER` to its URL. Hooks probe for it with a short timeout and cache discovery for five seconds. Event patches and OTLP spans appear without a cloud write key. Debugger HTTP requests run with tracing suppressed to prevent recursive instrumentation.
+
+`setup --local-only` skips requiring a write key. It preserves an existing saved write key unless you supply a replacement. To run hooks without cloud delivery, set `RAINDROP_WRITE_KEY` to an empty string in the hook environment; this overrides the saved key.
+
+## Self-diagnostics
+
+`raindrop-cursor mcp-serve` exposes the `__raindrop_report` tool. Its default categories are missing context, repeated tool failures, capability gaps, complete task failure, and noteworthy observations. Signals target the most recently updated Cursor event on that machine. Concurrent conversations can make this fallback ambiguous.
+
+## Cursor plugin
+
+The npm package includes `.cursor-plugin/plugin.json`, `hooks/hooks.json`, `hooks/hook.cjs`, and `.mcp.json`. Each plugin hook is a one-line `node -e` command that runs `hooks/hook.cjs`; the launcher resolves the bundled CLI relative to its own file, skips missing builds, and always exits zero. The package build synchronizes the plugin version with the npm version.
+
+## Limits
+
+Hook commands always exit zero and write no control response to stdout. Slow network requests cannot extend the CLI's whole-invocation deadline. Inputs over 16 MB are dropped; captured text is capped at 1,000,000 characters and serialized span strings at 32,768 characters.
+
+State and debugger discovery cache live in `~/.raindrop-cursor`, with hashed conversation and generation keys and bounded file locking. On POSIX, the directory must belong to the current user with no group or other permissions; files use mode `0600`. Unsafe directories and linked files are rejected on reads. Writes replace files atomically without following existing links. Windows relies on the user's home-directory ACLs. The old shared temporary directory is not read or migrated; restart active Cursor sessions when upgrading.
+
+`sessionEnd` cleans up conversation state. Cloud Agents may omit `sessionStart` and `sessionEnd`; `stop` still finalizes events, but session metadata can be incomplete and state remains until removed. You can remove `~/.raindrop-cursor` when no Cursor sessions are active. No transcript files are parsed.
+
+Cached auto-detection accepts only `http://localhost:5899/v1/`; custom debugger URLs require explicit `RAINDROP_LOCAL_DEBUGGER` configuration. Auto-detection trusts the service listening on that local port. Set `RAINDROP_LOCAL_DEBUGGER=false` on shared hosts where that service cannot be trusted.
+
+## Development
+
+```bash
+pnpm --filter @raindrop-ai/core build
+pnpm --filter @raindrop-ai/cursor build
+pnpm --filter @raindrop-ai/cursor test
+pnpm --filter @raindrop-ai/cursor lint
+```
+
+The conformance driver at `conformance/cursor-driver.mjs` exercises the public mapper and real telemetry transport with synthetic hook payloads. Live Cursor IDE and Cloud Agent validation is separate from these fixtures.
+
+Run it using the [pinned harness instructions](../../conformance/README.md), with `--driver 'node /absolute/path/to/raindrop-js/conformance/cursor-driver.mjs'` and `--failures /absolute/path/to/raindrop-js/conformance/cursor-failures.txt`. The initial fault-lane baseline has 2 passes, 10 expected failures, and 48 unsupported scenarios. [DEV-1661](https://linear.app/raindrop-ai/issue/DEV-1661/cursor-hooks-conformance-gaps-and-live-integration-verification) tracks those gaps, CLI hook availability, subagent token attribution, and CI onboarding.