cursor-acp-enriched

Recovers missing tool call arguments from Cursor's ACP (Agent Client Protocol) events by reading the local SQLite store.db.

The problem

Cursor's ACP stream emits tool_call notifications with an empty rawInput field — you can see that a tool was called but not what arguments it received (which file was read, which command was run, etc.).

Cursor does write the full tool call data — including arguments — to a local SQLite database. Recent Cursor builds use a flat layout:

~/.cursor/acp-sessions/<sessionId>/store.db

Older sessions still live under the legacy hashed layout, which this package also resolves transparently:

~/.cursor/chats/<hash>/<sessionId>/store.db

This package reads whichever database is present for a given session and recovers the missing arguments, using the toolCallId as the join key between ACP events and store.db blobs.

Installation

npm install cursor-acp-enriched

Quick start

import { CursorToolEnricher } from 'cursor-acp-enriched';

// sessionId comes from the ACP session notification
const enricher = new CursorToolEnricher(sessionId);

// toolCallId comes from the ACP tool_call event
const result = await enricher.enrich(toolCallId);

if (result) {
  console.log(result.toolName); // e.g. "Read"
  console.log(result.args); // e.g. { path: "/foo/bar.ts" }
  console.log(result.result); // e.g. "export default function main() {}"
  console.log(result.richResult); // structured data from Cursor (see below)
}

// With a polling timeout (retries until blob appears or timeout expires)
const result = await enricher.enrich(toolCallId, { timeoutMs: 2000 });

// Limit result length (default is 50 000 characters)
const result = await enricher.enrich(toolCallId, { maxResultLength: 5000 });

API reference

new CursorToolEnricher(sessionId, options?)

Creates an enricher for the given Cursor session.

Option	Type	Default	Description
cursorDir	string	~/.cursor	Override the Cursor data directory
defaultTimeoutMs	number	1000	Default retry window for enrich()

enricher.enrich(toolCallId, options?)

Looks up the tool call in store.db. Returns EnrichedToolCall | null.

If the blob isn't found immediately and timeoutMs > 0, retries with exponential backoff (50ms → 100ms → 200ms…) until the timeout is reached. Useful when the blob may not be written yet.

Option	Type	Default	Description
timeoutMs	number		Overrides defaultTimeoutMs for this call
maxResultLength	number	50_000	Truncates the recovered result to this many chars

enricher.close()

Clears the cached store.db path. The next enrich() call will re-discover it.

findSessionStorePath(sessionId, options?)

Low-level helper. Scans ~/.cursor/chats/*/ for a subdirectory matching sessionId and returns the full path to store.db. Throws SessionNotFoundError if not found.

Types

interface EnrichedToolCall {
  toolCallId: string;
  toolName: string;
  args: Record<string, unknown>;
  result: string | null; // tool output; null when no tool-result blob was found
  richResult: Record<string, unknown> | null; // structured data from highLevelToolCallResult; null when absent
}

richResult — structured tool output

Cursor's store.db stores a providerOptions.cursor.highLevelToolCallResult field on tool-role blobs containing rich structured data that goes beyond the plain-text result. The enricher extracts this as richResult.

Examples of what each tool provides:

Tool	richResult contains
Grep / Glob	workspaceResults — file paths and matching lines
WebSearch	references — URLs, titles, and content chunks
StrReplace	diffString — before/after diff
Write	diffString — full file diff
Task	conversationSteps — subagent conversation activity
Shell	exit code and full output (when Cursor includes it)

richResult is null when the tool blob has no highLevelToolCallResult (e.g. older Cursor versions, or tools that don't provide it).

const result = await enricher.enrich(toolCallId);
if (result?.richResult) {
  // Grep example
  const workspaceResults = result.richResult.workspaceResults;

  // WebSearch example
  const references = result.richResult.references;

  // StrReplace/Write example
  const diff = result.richResult.diffString;
}

How it works

1. Path discovery — scans ~/.cursor/chats/<hash>/<sessionId>/store.db to find the database for the session
2. Blob correlation — opens the database read-only in WAL mode, iterates all rows in the blobs table; finds the type === "tool-call" entry for the given toolCallId (for args), the paired type === "tool-result" entry (for output), and the providerOptions.cursor.highLevelToolCallResult field (for structured rich data)
3. Retry — if the blob isn't present yet (Cursor may not have flushed it), polls with exponential backoff up to the configured timeout

Limitations

• macOS and Linux only (no Windows support in v1)
• Depends on Cursor's internal store.db schema, which may change across Cursor versions
• Read-only: does not write to or modify the database

License

MIT