131 lines
6.5 KiB
Markdown
131 lines
6.5 KiB
Markdown
---
|
|
spec: docs/specs/agents/requirements/cursor-subagent-metadata.md
|
|
created: 2026-08-20
|
|
status: in_progress
|
|
---
|
|
|
|
# Implementation Plan: Cursor Subagent Metadata
|
|
|
|
## Overview
|
|
|
|
Cursor delivers its subagent's prompt, model, description, and agent id over a
|
|
non-standard agent-to-client request, `cursor/task`, which Kandev currently
|
|
rejects with `-32601`. This plan (1) opens a seam so the ACP client can accept a
|
|
non-`_`-prefixed extension method, (2) parses `cursor/task` and correlates it to
|
|
the standard subagent `tool_call` by `toolCallId`, merging its fields onto the
|
|
existing `SubagentTaskPayload`, and (3) maps Cursor's `isBackground` completion
|
|
flag onto the payload's existing `IsAsync` so the current "background" chip
|
|
renders. The frontend already renders model, prompt (fallback), and the
|
|
background chip, so no frontend change is required for the golden path.
|
|
|
|
---
|
|
|
|
## Resolved decision and implemented seam
|
|
|
|
The upstream ACP client routes inbound client extension handling only for
|
|
method names starting with `_`, so `cursor/task` would fall through to the
|
|
generated `ClientSideConnection.handle` switch and return `-32601`.
|
|
|
|
The implementation that landed widens that seam in the pinned ACP fork instead
|
|
of proxying it in-repo: the fork routes any unrecognized inbound client
|
|
*request* to the client's `ExtensionMethodHandler`, and Kandev keeps the
|
|
client-owned allow/deny policy in
|
|
`apps/backend/internal/agentctl/server/acp/client.go`. The adapter registers a
|
|
`CursorTaskHandler` via `acpclient.WithCursorTaskHandler` and passes the client
|
|
straight to `acp.NewClientSideConnection` (`adapter.go`), so there is no
|
|
repo-local connection proxy. The relaxation is inbound-accept only; the outbound
|
|
`CallExtension`/`NotifyExtension` `_`-prefix contract is unchanged.
|
|
|
|
---
|
|
|
|
## Backend
|
|
|
|
### Area 1 — client extension seam (Task 01)
|
|
Kandev implements `HandleExtensionMethod(ctx, method, params)` on
|
|
`acpclient.Client` (`apps/backend/internal/agentctl/server/acp/client.go`),
|
|
returning an empty result for `cursor/task` and `NewMethodNotFound` otherwise.
|
|
The pinned ACP fork routes any unrecognized inbound client request to that
|
|
handler, so no repo-local connection helper is needed. A `CursorTaskHandler`
|
|
option (mirroring `WithUpdateHandler`) hands the raw params to the adapter.
|
|
|
|
### Area 2 — parse + correlate cursor/task (Task 02)
|
|
New `dialect_cursor.go` in `apps/backend/internal/agentctl/server/adapter/transport/acp/`: parse the `cursor/task` params (`agentId`, `description`, `model`, `prompt`, `toolCallId`; `subagentType` is an object and is ignored) defensively over untyped maps. The adapter keeps a per-session `map[toolCallId]cursorTaskMeta` (bounded, cleared on session teardown). On either the `cursor/task` request or the subagent `tool_call` (whichever is second), merge onto the `SubagentTaskPayload` via the existing fill-if-present rule (extend `applySubagentResult` or a sibling `applyCursorTaskMeta`). Wire the adapter's `CursorTaskHandler` in `adapter.go` next to `enqueueACPUpdate`.
|
|
|
|
### Area 3 — background flag (Task 02, same change)
|
|
Extend `cursorSubagentResult` (`subagent.go:349`) to read `rawOutput.isBackground` and set `res.IsAsync = true` when it is `true`. This reuses `SubagentTaskPayload.IsAsync` and the frontend background chip; no new payload field.
|
|
|
|
---
|
|
|
|
## Frontend
|
|
|
|
> No change required for the golden path. `model` already renders as a chip
|
|
> (`subagent-meta.ts:85`), `is_async` already renders the "background" chip
|
|
> (`subagent-meta.ts:56`), and `prompt` already renders as the card body
|
|
> fallback when there is no `result_text` and no children
|
|
> (`tool-subagent-message.tsx`). The `SubagentTaskPayload` TS type
|
|
> (`apps/web/components/task/chat/types.ts`) already carries every field this
|
|
> feature populates. Confirm in Task 04 (E2E/manual) and only add rendering if a
|
|
> gap is observed.
|
|
|
|
---
|
|
|
|
## Tests
|
|
|
|
- **Extension dispatch (Task 01):** `cursor/task` returns a success result, not
|
|
`-32601`. File: `apps/backend/internal/agentctl/server/acp/client_test.go`
|
|
(table-driven: `cursor/task` → ok; unknown `foo/bar` → method-not-found).
|
|
- **cursor/task parse (Task 02):** parses `agentId`/`description`/`model`/
|
|
`prompt`; ignores object `subagentType`; tolerates missing fields. File:
|
|
`apps/backend/internal/agentctl/server/adapter/transport/acp/dialect_cursor_test.go`.
|
|
- **Correlation both orders (Task 02):** request-before-tool_call and
|
|
tool_call-before-request both merge onto one payload; unmatched entry is
|
|
dropped at teardown. File: `..._cursor_test.go` /
|
|
`subagent_test.go`.
|
|
- **isBackground (Task 02):** completion `rawOutput.isBackground:true` sets
|
|
`IsAsync`; `false`/absent leaves it unset. File: `subagent_test.go`.
|
|
- **No-regression (Task 02/03):** existing subagent tests for Claude/OpenCode/
|
|
Auggie still pass unchanged.
|
|
|
|
---
|
|
|
|
## E2E Tests
|
|
|
|
> No new Playwright spec. `cursor/task` requires a live Cursor login and cannot
|
|
> run in CI. Task 04 is a manual `acpdbg`/live-session verification against a
|
|
> real Cursor subagent, recording the rendered card (prompt, model, background).
|
|
|
|
---
|
|
|
|
## Verification Results
|
|
|
|
- `cd apps/backend && go test ./internal/agentctl/server/acp/... ./internal/agentctl/server/adapter/transport/acp/... ./internal/agentctl/server/utility/...` passed after adding a real wire-path test for inbound `cursor/task` handling.
|
|
- `cd apps && pnpm install --frozen-lockfile` passed in the worktree so focused frontend tests could run.
|
|
- `cd apps && pnpm --filter @kandev/web exec vitest run components/task/chat/messages/subagent-meta.test.ts components/task/chat/messages/tool-subagent-message.test.tsx` passed 41 tests across 2 files.
|
|
- No frontend code change was required: the existing subagent metadata chip/body renderers already display `model`, `is_async`, and `prompt` once the backend populates them.
|
|
- Manual live verification against a real Cursor-authenticated session is still pending (Task 04).
|
|
|
|
---
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
```text
|
|
Wave 1:
|
|
- [x] [task-01-sdk-extension-seam](task-01-sdk-extension-seam.md)
|
|
|
|
Wave 2:
|
|
- [x] [task-02-parse-correlate-cursor-task](task-02-parse-correlate-cursor-task.md)
|
|
|
|
Wave 3 (verification):
|
|
- [x] [task-03-frontend-confirm](task-03-frontend-confirm.md) (parallel-safe with Task 04)
|
|
- [ ] [task-04-manual-live-verify](task-04-manual-live-verify.md)
|
|
```
|
|
|
|
Sequential by default. Task 02 depends on Task 01's `CursorTaskHandler` seam.
|
|
|
|
---
|
|
|
|
## Open Questions
|
|
- None. The one architectural question (Option A vs Option B) is resolved by
|
|
[ADR-2026-08-20-acp-client-non-underscore-extension-methods](../../decisions/2026-08-20-acp-client-non-underscore-extension-methods.md)
|
|
(Option A). Task 01 is unblocked.
|