@raindrop-ai/cursor-agent-sdk

Raindrop instrumentation for the Cursor Agent SDK.

Installation

pnpm add @raindrop-ai/cursor-agent-sdk @cursor/sdk

Quick start

import * as cursor from "@cursor/sdk";
import { createRaindropCursorAgentSDK, eventMetadata } from "@raindrop-ai/cursor-agent-sdk";

const raindrop = createRaindropCursorAgentSDK({
  writeKey: process.env.RAINDROP_WRITE_KEY,
  context: { userId: "user-123", eventName: "cursor_agent_run" },
});
const wrapped = raindrop.wrap(cursor);

const agent = await wrapped.Agent.create({
  model: { id: "composer-1" },
});
const run = await agent.send("Summarize the repository");

for await (const message of run.stream()) {
  console.log(message);
}

// Metadata can be constructed for a wrap context and reused per request.
const metadata = eventMetadata({ userId: "user-456", convoId: "conversation-1" });
const otherWrapped = raindrop.wrap(cursor, { context: metadata });

await raindrop.flush();

The wrapper preserves Cursor return values, streams, and thrown errors. It records one Raindrop AI event per run and a trace tree containing thinking and tool-call spans.

Captured data

Captured runs include the prompt, assistant output, model id, status, errors, and Cursor token usage. Cursor tool_call and thinking messages become child trace spans. Runs can be consumed through stream(), wait(), or conversation(); a run is finalized only once.

Options

writeKey is optional. Without it, shipping is disabled and the wrapped Cursor SDK remains usable. endpoint, projectId, localWorkshopUrl, events, traces, a default context, and a default tools catalog are supported. Set RAINDROP_AI_DEBUG=1 or the relevant debug option to log telemetry failures.

Identity and routing metadata are supplied through wrap(..., { context }). The eventMetadata() helper provides a typed metadata object for that context. The Cursor SDK's actual method signatures do not provide a trailing metadata parameter, so this integration does not alter Cursor method arguments.

wrap(..., { tools }) overrides the tool catalog recorded as ai.prompt.tools on every model span. Use when the integration cannot see the tools the model was given. A tools array on createRaindropCursorAgentSDK(...) is the default for every wrap() call; the wrap() option replaces it entirely.

Tool catalog capture (ai.prompt.tools)

The Cursor SDK streams messages, never the request it sends to the model, so this integration cannot observe the tool catalog and records nothing by default (the attribute stays absent, meaning "unknown"). The tools override is recorded verbatim on the cursor.agent.run span, which is the span carrying the prompt (traceloop.entity.input) and ai.model.id; child tool_call / thinking spans never carry it. tools: [] records an explicitly empty catalog. Declarations may use any shape @raindrop-ai/core recognizes ({ name, description?, parameters }, { type: "function", name, inputSchema }, OpenAI/Anthropic wrappers, ...).

Limitations

• Concurrent runs should use separate wrapped contexts when each run needs distinct identity metadata.
• The Cursor SDK requires Node.js >=22.13.
• Cloud responses may omit usage, model, or message content; those fields are omitted gracefully.

Testing

pnpm --filter @raindrop-ai/cursor-agent-sdk test

Application Git identity

Set appGit on createRaindropCursorAgentSDK to override commitSha, commitDirty, and optional ordinary branch, or pass false to opt out. Cursor can operate against remote workspaces, so the revision is unknown by default: ambient deploy/CI and observer working-directory metadata are ignored. Local Git discovery requires an explicit sourceDirectory (or RAINDROP_GIT_SOURCE_DIRECTORY); explicit RAINDROP_COMMIT_SHA values are honored. Automatic branch discovery requires detectBranch: true.