149 lines
7.5 KiB
Markdown
149 lines
7.5 KiB
Markdown
---
|
|
status: draft
|
|
created: 2026-08-20
|
|
owner: cfl12
|
|
---
|
|
|
|
# Cursor Subagent Metadata
|
|
|
|
## Why
|
|
|
|
When Cursor's agent dispatches a subagent, the only thing a Kandev user sees is a
|
|
generic `Task: Subagent task` card with no prompt, no model, and no identity. All
|
|
the useful detail (what the subagent was asked to do, which model runs it, its
|
|
agent id, whether it runs in the background) is delivered by Cursor over a
|
|
non-standard agent-to-client request, `cursor/task`, which Kandev currently
|
|
rejects. The subagent's work is therefore opaque, and a backgrounded subagent
|
|
looks identical to one that already finished.
|
|
|
|
## What
|
|
|
|
- A Cursor subagent card SHALL show the subagent's description, prompt, model,
|
|
and (for background subagents) a background indicator, sourced from the
|
|
`cursor/task` request Cursor emits alongside the standard `tool_call`.
|
|
- The rich metadata is correlated to the standard subagent `tool_call` by the
|
|
shared `toolCallId` Cursor puts in both, so the existing subagent card is
|
|
enriched in place rather than a second card appearing.
|
|
- `cursor/task` MUST NOT cause a JSON-RPC error back to Cursor. Kandev accepts
|
|
the request and returns an empty success result.
|
|
- A `cursor/task` that arrives with no matching subagent `tool_call` (or before
|
|
it) is retained and applied when the matching `tool_call` appears; a stored
|
|
correlation that is never matched is bounded and dropped when the session ends.
|
|
- Cursor reports background dispatch two ways that both map to the payload's
|
|
existing async concept: `cursor/task.model` ending in `-fast` is informational
|
|
only, while the completion `tool_call_update.rawOutput.isBackground == true`
|
|
marks the subagent as background. A background Cursor subagent renders the same
|
|
"background" affordance Claude's async subagents use.
|
|
- No behavior changes for any non-Cursor agent, and no change to how Cursor's
|
|
ordinary (non-subagent) tool calls render.
|
|
|
|
## Data model
|
|
|
|
No new persistent tables. The existing in-message
|
|
`streams.SubagentTaskPayload`
|
|
(`apps/backend/internal/agentctl/types/streams/tool_payload.go`) is the store;
|
|
its `Description`, `Prompt`, `SubagentType`, `Model`, `AgentID`, `DurationMs`,
|
|
and `IsAsync` fields already exist and already serialize to the frontend
|
|
`SubagentTaskPayload` (`apps/web/components/task/chat/types.ts`). This feature
|
|
populates the Cursor-shaped subset that is currently dropped; it adds no new
|
|
payload field unless correlation requires transient adapter-side state (a
|
|
per-session `map[toolCallId]cursorTask`, not persisted).
|
|
|
|
## API surface
|
|
|
|
`cursor/task` is an inbound agent-to-client JSON-RPC **request** (it carries an
|
|
`id`, so a response is required). Kandev is the ACP client. The method name does
|
|
not start with `_`, so the stock SDK extension hook
|
|
(`ExtensionMethodHandler`, only invoked for `_`-prefixed methods in
|
|
`kdlbs/acp-go-sdk` `extensions.go`) does not reach it, and the generated
|
|
`ClientSideConnection.handle` switch returns `-32601`.
|
|
|
|
Observed request params (wire capture, `composer-2.5`):
|
|
|
|
```text
|
|
cursor/task (request, has id)
|
|
agentId string e.g. "eaa12f70-...-60506ebd5c78"
|
|
description string e.g. "Summarize src JS files"
|
|
durationMs number launch duration, not the subagent's run time
|
|
model string e.g. "composer-2.5-fast"
|
|
prompt string the full subagent prompt
|
|
subagentType object e.g. {"custom":{"unspecified":{}}} — opaque, not a string
|
|
toolCallId string correlates to the standard tool_call, e.g. "tool_2494c23d-..."
|
|
```
|
|
|
|
Response: an empty JSON object result (no error).
|
|
|
|
The correlated standard frames (unchanged path): the `tool_call` carries
|
|
`rawInput:{"_toolName":"task"}` and title `Task: Subagent task`; the completion
|
|
`tool_call_update` carries `rawOutput:{"durationMs":N,"isBackground":true|false}`.
|
|
|
|
## Failure modes
|
|
|
|
- **Unknown/extra fields in `cursor/task`:** parsed defensively over untyped
|
|
maps; missing fields stay zero-valued and the card degrades to whatever is
|
|
present. Never errors the request.
|
|
- **`subagentType` is an object, not a string:** it is not coerced into the
|
|
string `SubagentType` field; it is ignored unless a stable string label can be
|
|
derived. A malformed value never blocks the rest of the metadata.
|
|
- **Ordering (request before or after the `tool_call`):** correlation by
|
|
`toolCallId` is order-independent; whichever arrives second applies the merge.
|
|
- **No matching `tool_call` ever arrives:** the stored `cursor/task` is bounded
|
|
per session and discarded at session teardown; it never leaks across sessions.
|
|
- **A field already set by the standard frame is not blanked** by a later empty
|
|
Cursor value (mirrors `applySubagentResult`'s fill-if-present rule).
|
|
|
|
## Persistence guarantees
|
|
|
|
Captured metadata lives on the message payload and persists with the transcript
|
|
exactly as today. The transient `toolCallId -> cursorTask` correlation map is
|
|
in-memory adapter state and does NOT survive a restart; a subagent whose
|
|
`cursor/task` was seen only before a restart keeps whatever was already merged
|
|
onto its stored payload.
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** Cursor emits a subagent `tool_call` and a matching `cursor/task`
|
|
request, **WHEN** both are processed, **THEN** the subagent card shows the
|
|
Cursor description, prompt, and model, and Kandev returns a success (not
|
|
`-32601`) for `cursor/task`.
|
|
- **GIVEN** a `cursor/task` arrives before its `tool_call`, **WHEN** the
|
|
`tool_call` later arrives, **THEN** the card is enriched with the earlier
|
|
metadata.
|
|
- **GIVEN** the completion `tool_call_update.rawOutput.isBackground` is `true`,
|
|
**WHEN** the card renders, **THEN** it shows the background affordance.
|
|
- **GIVEN** `isBackground` is `false` or absent, **WHEN** the card renders,
|
|
**THEN** no background affordance shows.
|
|
- **GIVEN** a `cursor/task` with a missing `model` and a present `prompt`,
|
|
**WHEN** the card renders, **THEN** the prompt shows and no empty model chip
|
|
appears.
|
|
- **GIVEN** any non-Cursor agent's subagent, **WHEN** it is processed, **THEN**
|
|
its rendering is byte-identical to before this feature.
|
|
- **GIVEN** a `cursor/task` that never matches a `tool_call`, **WHEN** the
|
|
session ends, **THEN** the stored correlation is dropped and no card appears.
|
|
|
|
## Out of scope
|
|
|
|
- Fetching or resuming a **parked background subagent's result** by `agentId`.
|
|
A wire capture proved Cursor never pushes the async result back over the ACP
|
|
session (125s linger, zero post-`end_turn` frames); retrieval would need a new
|
|
follow-up-prompt flow and is a separate feature.
|
|
- Result-text capture for Cursor. Unlike Claude, Cursor's completion frame
|
|
carries only `durationMs`/`isBackground`, no result content; this remains as
|
|
noted out of scope in
|
|
[subagent-observability](../ui/subagent-observability.md).
|
|
- Interpreting Cursor's `subagentType` object taxonomy.
|
|
- Any change to `active_subagent_count`, liveness, or the board chip
|
|
([background-work-liveness](../platform/background-work-liveness.md)).
|
|
|
|
## Notes
|
|
|
|
- Wire evidence and the SDK dispatch analysis are recorded against task
|
|
`hey-a-user-reported` (`acpdbg --linger`, `composer-2.5`). The `cursor/task`
|
|
params and the `tool_call`/`tool_call_update` shapes above are from
|
|
`acp-debug/cursor-acp-linger-20260820-145213.jsonl`.
|
|
- Decision: [ADR-2026-08-20-acp-client-non-underscore-extension-methods](../../decisions/2026-08-20-acp-client-non-underscore-extension-methods.md)
|
|
resolves how `cursor/task` is accepted: the `kdlbs/acp-go-sdk` fork routes any
|
|
unrecognized inbound client method to the client's `ExtensionMethodHandler`,
|
|
and Kandev's `Client` returns success only for methods it recognizes
|
|
(`cursor/task`) and `NewMethodNotFound` otherwise.
|