engine-internals

Cursor Engine Implementation Details

Agent CLI Invocation

• Binary path: ~/.local/bin/agent (not cursor, nor cursor agent)
• Uses standard child_process.spawn — no PTY (node-pty) needed since CLI version 2026.02+
• Key flags: --output-format stream-json --stream-partial-output --force --trust --sandbox disabled --approve-mcps

stream-json Output Format

Output is clean NDJSON on stdout; stripAnsi() is retained as a safety net but is not expected to be needed.

One JSON object per line, main types:

{ "type": "system", "subtype": "init", "session_id": "xxx", ... }     → Init; does not signal end of conversation
{ "type": "assistant", "message": { "content": [{ "type": "text", "text": "..." }] } }  → Assistant text delta
{ "type": "tool_call", "subtype": "started", "tool_call": { "<XxxToolCall>": { "args": {...} } } }  → Tool call started
{ "type": "tool_call", "subtype": "completed", "tool_call": { "<XxxToolCall>": { "args": {...}, "result": {...} } } }  → Tool call completed
{ "type": "result", "subtype": "success", "is_error": false, "session_id": "xxx", "duration_ms": 1234 }  → Normal end
{ "type": "result", "subtype": "error", "is_error": true, "result": "error msg" }  → Error end

Key Notes

1. tool_call has both started and completed events — started → yield tool_call, completed → yield tool_result; do not treat both as tool_call (would duplicate)
2. tool_call name is not a fixed field — iterate over the tool_call object keys and find the one ending with ToolCall; some tools use function format ({ "name": "...", "arguments": "..." })
3. --stream-partial-output changes assistant event granularity — with it, each assistant event is character-level delta; without it, full paragraphs. Critical: after all deltas for each segment (text between tool calls), Cursor sends one more summary event (content = concatenation of that segment’s deltas). CursorEngine uses accumulated text comparison to detect and skip summary, avoiding duplicate text
4. assistant.message.content is an array — multiple blocks; filter those with type === 'text' and concatenate
5. system event is not a termination signal — do not end the stream on system event
6. session_id appears in both system and result — use the one in result as the final session_id