Commit afad39d125a319e5fa22e15bbc8615b3a6267aa4 | the-knife

author	Julius Marminge <julius0216@outlook.com> 2026-02-28 18:26:13-08:00
committer	Julius Marminge <jmarminge@gmail.com> 2026-03-05 23:00:41-08:00
log	afad39d125a319e5fa22e15bbc8615b3a6267aa4
tree	f3c649bd5f2415bb47e7208b2e77941611341b88
parent	f97916f371ab2480a47f62efa17d42c64a253501

Revise Cursor provider plan for ACP JSON-RPC integration

- Switch plan from `agent -p` stream-json to `agent acp` JSON-RPC transport
- Document ACP session, permission, event-mapping, and interrupt/recovery behavior
- Update implementation phases, tests, and delivery checklist for ACP-first design

1 files changed, 227 insertions(+), 210 deletions(-)

.plans
- 18-cursor-agent-provider.md

.plans/18-cursor-agent-provider.md+227-210

...	...	@@ -1,248 +1,260 @@
1		# Plan: Cursor CLI (`agent`) Provider Integration
	1	# Plan: Cursor ACP (`agent acp`) Provider Integration
2	2
3	3	## Goal
4	4
5		Add Cursor as a first-class provider in T3 Code using Cursor CLI stream JSON mode (`agent -p --output-format stream-json`), with robust session lifecycle handling and canonical `ProviderRuntimeEvent` projection.
	5	Add Cursor as a first-class provider in T3 Code using ACP (`agent acp`) over JSON-RPC 2.0 stdio, with robust session lifecycle handling and canonical `ProviderRuntimeEvent` projection.
6	6
7	7	---
8	8
9		## 1) Exploration Findings (from live CLI runs)
	9	## 1) Exploration Findings (from live ACP probes)
10	10
11		### 1.1 Core invocation shape
	11	### 1.1 Core invocation and transport
12	12
13	13	1. Binary is `agent` on PATH (`2026.02.27-e7d2ef6` observed).
14		2. Non-interactive streaming mode:
15		- `agent -p --trust --output-format stream-json --stream-partial-output ...`
16		3. Session continuity:
17		- `agent create-chat` returns a chat UUID.
18		- `--resume <chatId>` and `--continue` preserve history.
19		- Stream `session_id` equals chat UUID.
20
21		### 1.2 Stream JSON event families observed
22
23		1. `system/init`
24		2. `user`
25		3. `thinking/delta`, `thinking/completed`
26		4. `assistant` (partial and final)
27		5. `tool_call/started`, `tool_call/completed`
28		6. `result/success` (`is_error: false` in all successful process exits)
29		7. Previously observed under load/rate-limit:
30		- `connection/reconnecting`, `connection/reconnected`
31		- `retry/starting`, `retry/resuming`
32		- followed by non-JSON terminal line `v: [resource_exhausted] Error` and process exit code `1`
33
34		### 1.3 Tool call variants observed
35
36		1. `shellToolCall`
37		2. `readToolCall`
38		3. `editToolCall`
39		4. `grepToolCall`
40		5. `globToolCall`
41
42		Tool completion outcomes observed:
43
44		1. `result.success`
45		2. `result.failure` (non-zero exit, stderr)
46		3. `result.rejected` (permission denied by Cursor approval layer)
47
48		### 1.4 Critical protocol quirks
49
50		1. `tool_call.call_id` contains embedded newline characters (must sanitize for IDs).
51		2. Startup failures are plain text, not JSON:
52		- invalid model -> plain error + exit `1`
53		- invalid API key -> plain warning + exit `1`
54		3. `result.subtype` can be `success` even when tool calls failed/rejected inside the turn.
55		4. Running multiple `agent` commands concurrently can race on `~/.cursor/cli-config.json` writes (`ENOENT rename ...cli-config.json.tmp` observed).
56
57		Fixtures recorded in repo:
58
59		1. `.tmp/cursor-observations/*.ndjson`
60		2. `.tmp/cursor-observations/startup-invalid-*.txt`
	14	2. ACP server command is `agent acp`.
	15	3. Transport is newline-delimited JSON-RPC 2.0 over stdio.
	16	4. Messages:
	17	- client -> server: requests and responses to server-initiated requests
	18	- server -> client: responses, notifications (`session/update`), and server requests (`session/request_permission`)
	19
	20	### 1.2 Handshake and session calls observed
	21
	22	1. `initialize` returns:
	23	- `protocolVersion`
	24	- `agentCapabilities` (`loadSession`, `mcpCapabilities`, `promptCapabilities`)
	25	- `authMethods` (includes `cursor_login`)
	26	2. `authenticate { methodId: "cursor_login" }` returns `{}` when logged in.
	27	3. `session/new` returns:
	28	- `sessionId`
	29	- `modes` (`agent`, `plan`, `ask`)
	30	4. `session/load` works and requires `sessionId`, `cwd`, `mcpServers`.
	31	5. `session/prompt` returns terminal response `{ stopReason: "end_turn" \| "cancelled" }`.
	32
	33	Important sequence note:
	34	1. ACP currently allows `session/new` even without explicit `initialize`/`authenticate` when local auth already exists.
	35	2. For adapter consistency and forward compatibility, we should still send `initialize` and `authenticate` during startup.
	36
	37	### 1.3 `session/update` event families observed
	38
	39	Observed `params.update.sessionUpdate` values:
	40
	41	1. `available_commands_update`
	42	2. `agent_thought_chunk`
	43	3. `agent_message_chunk`
	44	4. `tool_call`
	45	5. `tool_call_update`
	46
	47	Observed payload behavior:
	48
	49	1. `agent_*_chunk` provides `content: { type: "text", text: string }`.
	50	2. `tool_call` may be emitted multiple times for same `toolCallId`:
	51	- initial generic form (`title: "Terminal"`, `rawInput: {}`)
	52	- enriched form (`title: "\`pwd\`"`, `rawInput: { command: "pwd" }`)
	53	3. `tool_call_update` statuses observed:
	54	- `in_progress`
	55	- `completed`
	56	4. `tool_call_update` on completion may include `rawOutput`:
	57	- terminal: `{ exitCode, stdout, stderr }`
	58	- search/find: `{ totalFiles, truncated }`
	59
	60	### 1.4 Permission flow observed
	61
	62	1. ACP server sends `session/request_permission` (JSON-RPC request with `id`).
	63	2. Request shape includes:
	64	- `params.sessionId`
	65	- `params.toolCall`
	66	- `params.options` (`allow-once`, `allow-always`, `reject-once`)
	67	3. Client must respond on same `id` with:
	68	- `{ outcome: { outcome: "selected", optionId: "<one-option-id>" } }`
	69	4. Reject path still results in tool lifecycle completion events (`tool_call_update status: completed`), typically without `rawOutput`.
	70
	71	### 1.5 Error and capability quirks
	72
	73	1. `session/cancel` currently returns:
	74	- JSON-RPC error `-32601` Method not found
	75	2. Error shape examples:
	76	- unknown auth method: `-32602`
	77	- `session/load` missing/invalid params: `-32602`
	78	- `session/prompt` unknown session: `-32603` with details
	79	3. Parallel prompts on same session are effectively single-flight:
	80	- second prompt can cause first to complete with `stopReason: "cancelled"`.
	81	4. `session/new` accepts a `model` field (no explicit echo in response).
	82
	83	Probe artifacts:
	84	1. `.tmp/acp-probe/*/transcript.ndjson`
	85	2. `.tmp/acp-probe/*/summary.json`
	86	3. `scripts/cursor-acp-probe.mjs`
61	87
62	88	---
63	89
64	90	## 2) Integration Constraints for T3
65	91
66		1. T3 requires adapter contract support for:
	92	1. T3 adapter contract still requires:
67	93	- `startSession`, `sendTurn`, `interruptTurn`, `respondToRequest`, `readThread`, `rollbackThread`, `stopSession`, `listSessions`, `hasSession`, `stopAll`, `streamEvents`.
68		2. Orchestration depends on canonical runtime events (`ProviderRuntimeEvent`) only.
69		3. Current `ProviderCommandReactor` ignores `thread.turn-start-requested.payload.provider` and prefers existing provider/session; this must be fixed for reliable provider selection (including Cursor).
70		4. Cursor CLI currently has no external approval callback API; approvals are internal to CLI behavior.
	94	2. Orchestration consumes canonical `ProviderRuntimeEvent` only.
	95	3. `ProviderCommandReactor` provider precedence fix remains required (respect explicit provider on turn start).
	96	4. ACP now supports external permission decisions, so Cursor can participate in T3 approval UX via adapter-managed request/response plumbing.
71	97
72	98	---
73	99
74	100	## 3) Proposed Architecture
75	101
76		## 3.1 New server components
	102	### 3.1 New server components
77	103
78		1. `apps/server/src/provider/Services/CursorAdapter.ts` (service contract/tag only for DI parity)
79		2. `apps/server/src/provider/Layers/CursorAdapter.ts` (single implementation unit; owns Cursor process lifecycle + stream parsing + runtime projection)
80		3. No separate `cursorCliManager.ts` abstraction in v1.
	104	1. `apps/server/src/provider/Services/CursorAdapter.ts` (service contract/tag + ACP event schemas).
	105	2. `apps/server/src/provider/Layers/CursorAdapter.ts` (single implementation unit; owns ACP process lifecycle, JSON-RPC routing, runtime projection).
	106	3. No manager indirection; keep logic in layer implementation.
81	107
82	108	### 3.2 Session model
83	109
84		1. T3 `ProviderSessionId` = synthetic UUID managed by adapter (stable for T3 APIs).
85		2. Cursor chat UUID stored as:
86		- `ProviderSession.resumeCursor = { chatId: string }`
87		- `ProviderSession.threadId = ProviderThreadId(chatId)` for adapter contract compatibility.
88		3. Adapter keeps runtime map:
89		- `sessionId -> { chatId, cwd, model, activeChildProcess?, activeTurnId?, turnLog }`
	110	1. One long-lived ACP child process per T3 Cursor provider session.
	111	2. Track:
	112	- `providerSessionId` (T3 synthetic ID)
	113	- `acpSessionId` (from `session/new` or restored via `session/load`)
	114	- `cwd`, `model`, in-flight turn state
	115	- pending permission requests by JSON-RPC request id
	116	3. Resume support:
	117	- persist `acpSessionId` in provider resume metadata and call `session/load` on reattach.
90	118
91	119	### 3.3 Command strategy
92	120
93	121	1. `startSession`:
94		- call `agent create-chat` unless `resumeCursor.chatId` exists.
95		- validate provider is `cursor` when provided.
	122	- spawn `agent acp`
	123	- `initialize`
	124	- `authenticate(cursor_login)` (best-effort, typed failure handling)
	125	- `session/new` or `session/load`
96	126	2. `sendTurn`:
97		- spawn `agent -p --trust --output-format stream-json --stream-partial-output --resume <chatId>`.
98		- add `--model` when provided.
99		- map runtime mode:
100		- `approvalPolicy = never` -> include `--force`
101		- otherwise omit `--force` (commands may be rejected by CLI).
102		- use `--workspace <cwd>` when available.
	127	- send `session/prompt { sessionId, prompt: [...] }`
	128	- consume streaming `session/update` notifications until terminal prompt response
103	129	3. `interruptTurn`:
104		- terminate active child process for session (`SIGINT` then hard kill fallback).
	130	- no native `session/cancel` today; implement fallback:
	131	- terminate ACP process + restart + `session/load` for subsequent turns
	132	- mark in-flight turn as interrupted/failed in canonical events
	133	4. `respondToRequest`:
	134	- map T3 approval decision -> ACP `optionId`
	135	- reply to exact JSON-RPC request id from `session/request_permission`
105	136
106	137	### 3.4 Effect-first implementation style (required)
107	138
108		1. Keep adapter logic inside `CursorAdapterLive` layer constructor (no manager indirection).
109		2. Use Effect process primitives first:
110		- `ChildProcessSpawner` + `ChildProcess.make` from `effect/unstable/process` for `agent` execution.
111		3. Use Effect concurrency/state primitives:
112		- `Queue` for adapter event queue, `Stream.fromQueue` for `streamEvents`
113		- `Ref` / `Ref.Synchronized` for session maps and active-turn process handles
114		- `Effect.scoped` + `Effect.forkScoped` for worker fibers and cleanup
115		4. Use Effect stream parsing path for stdout/stderr:
116		- decode bytes -> line buffer -> JSON parse -> typed projection
117		- keep non-JSON lines on a fallback branch that emits `runtime.error`
118		5. Keep errors in typed adapter error algebra (`ProviderAdapter*Error`) via `Effect.mapError` boundaries, not ad-hoc exceptions.
	139	1. Keep logic inside `CursorAdapterLive`.
	140	2. Use Effect primitives:
	141	- `Queue` + `Stream.fromQueue` for event fan-out
	142	- `Ref` / `Ref.Synchronized` for session/process/request state
	143	- scoped fibers for stdout/stderr read loops
	144	3. Typed JSON decode at boundary:
	145	- request/response envelopes
	146	- `session/update` union schema
	147	- permission-request schema
	148	4. Keep adapter errors in typed error algebra with explicit mapping at process/protocol boundaries.
119	149
120	150	---
121	151
122		## 4) Canonical Event Mapping Plan
123
124		For each parsed NDJSON line, emit zero or more `ProviderRuntimeEvent`s:
125
126		1. `system/init`
127		- emit `session.started` (once per adapter session lifecycle)
128		- emit `thread.started` if thread not yet emitted
129		2. `assistant` partial chunks
130		- emit `message.delta` with stable per-turn synthetic `itemId`
131		3. final `assistant` message
132		- emit `message.completed`
133		4. `tool_call/started`
134		- emit `tool.started`
135		- map kind:
136		- shell -> `command`
137		- edit -> `file-change`
138		- read/grep/glob -> `other`
139		5. `tool_call/completed`
140		- emit `tool.completed`
141		- include summary detail from nested payload (`command`, `path`, stderr fragment, rejection reason)
142		6. `thinking/*`
143		- initial version: ignore for canonical events (optional later: map to `tool.*` “Thinking”)
144		7. `result/success`
145		- emit `turn.completed` with `status: completed` unless unrecoverable parse/process error already set failure
146		8. non-JSON stdout/stderr protocol line
	152	## 4) Canonical Event Mapping Plan (ACP -> ProviderRuntimeEvent)
	153
	154	1. `session/update: agent_message_chunk`
	155	- emit `message.delta` for assistant stream
	156	2. prompt terminal response (`session/prompt` result `stopReason: end_turn`)
	157	- emit `message.completed` + `turn.completed`
	158	3. `session/update: agent_thought_chunk`
	159	- initial mapping: emit thinking activity (or ignore if we keep current canonical surface minimal)
	160	4. `session/update: tool_call`
	161	- first-seen `toolCallId` emits `tool.started`
	162	- subsequent `tool_call` for same ID treated as metadata update (no duplicate started event)
	163	5. `session/update: tool_call_update`
	164	- `in_progress`: optional progress activity
	165	- `completed`: emit `tool.completed` with summarized `rawOutput` when present
	166	6. `session/request_permission`
	167	- emit `approval.requested` with mapped options
	168	- when client decision sent, emit `approval.resolved`
	169	7. protocol/process error
147	170	- emit `runtime.error`
148		- emit `turn.completed` with `status: failed`
149		9. `connection/` + `retry/` (when present)
150		- emit `tool.started/completed` with `toolKind: other`, title like “Connection retry”
151		- if final failure follows, also emit `runtime.error`
	171	- fail active turn/session as appropriate
152	172
153	173	Synthetic IDs:
154
155		1. `turnId`: adapter-generated UUID per `sendTurn`.
156		2. `itemId`: `${turnId}:assistant` for assistant stream; `${turnId}:${sanitizedCallId}` for tool calls.
157		3. `call_id` sanitization: replace whitespace (including newline) with `_`.
	174	1. `turnId`: T3-generated UUID per `sendTurn`.
	175	2. `itemId`:
	176	- assistant stream: `${turnId}:assistant`
	177	- tools: `${turnId}:${toolCallId}`
158	178
159	179	---
160	180
161		## 5) Approval and Checkpoint Behavior (explicit limitations)
	181	## 5) Approval, Resume, and Rollback Behavior
162	182
163	183	### 5.1 Approvals
164	184
165		1. Cursor CLI approval is internal; adapter cannot accept/reject mid-turn via `respondToRequest`.
166		2. Plan for v1:
167		- `respondToRequest` returns `ProviderAdapterRequestError` (“Cursor CLI does not expose external approval response API”).
168		- approval-required runtime uses no `--force`, so dangerous commands become `tool_call.result.rejected`.
169		3. Future:
170		- if Cursor exposes approval RPC/hooks, implement `approval.requested` + `approval.resolved` fully.
	185	1. Cursor ACP permission requests are externally controllable; implement full `respondToRequest` path in v1.
	186	2. Decision mapping:
	187	- allow once -> `allow-once`
	188	- allow always -> `allow-always`
	189	- reject -> `reject-once`
	190
	191	### 5.2 Resume
171	192
172		### 5.2 Rollback / thread read
	193	1. `session/load` is available and should be first-class for adapter restart/reconnect.
	194	2. Must send required params: `sessionId`, `cwd`, `mcpServers`.
173	195
174		1. Cursor CLI has no observed equivalent to `thread/read` or `thread/rollback`.
	196	### 5.3 Rollback / thread read
	197
	198	1. ACP currently has no observed rollback API.
175	199	2. Plan for v1:
176		- `readThread` returns adapter-maintained in-memory turn snapshot.
177		- `rollbackThread` returns `ProviderAdapterRequestError` unsupported.
	200	- `readThread`: adapter-maintained snapshot projection
	201	- `rollbackThread`: explicit unsupported error
178	202	3. Product guard:
179		- disable checkpoint revert for Cursor threads until rollback is implemented.
	203	- disable checkpoint revert for Cursor threads in UI until rollback exists.
180	204
181	205	---
182	206
183	207	## 6) Required Contract and Runtime Changes
184	208
185		## 6.1 Contracts
186
187		1. `packages/contracts/src/orchestration.ts`
188		- add `cursor` to `ProviderKind`.
189		2. `packages/contracts/src/provider.ts`
190		- add `CursorProviderStartOptions` under `providerOptions.cursor`:
191		- `binaryPath?`
192		- `apiKey?` (optional; default login auth)
193		- `trust?` (default true for headless)
194		3. `packages/contracts/src/model.ts`
195		- add `cursor` provider model options baseline.
196		- initial set should mirror observed supported IDs that are stable enough for UX.
197		4. Update related contract tests.
198
199		## 6.2 Server orchestration and registry
200
201		1. Add `CursorAdapter` to provider registry and server layer wiring.
202		2. Update provider-kind decoding in:
203		- `apps/server/src/provider/Layers/ProviderSessionDirectory.ts`
204		- persistence schemas that currently literal-match provider kinds.
205		3. Fix provider selection in `ProviderCommandReactor`:
206		- honor `thread.turn-start-requested.payload.provider` as highest precedence.
207		- fallback to existing session provider, then default.
208
209		## 6.3 Web
210
211		1. Enable Cursor in provider selector (`apps/web/src/session-logic.ts`).
212		2. Add Cursor label/icon treatment.
213		3. Add optional Cursor settings fields if using per-user overrides (binary path/api key).
214		4. Ensure thread/provider display and legacy mapping code handles `cursor`.
	209	### 6.1 Contracts
	210
	211	1. Add `cursor` to `ProviderKind`.
	212	2. Add Cursor provider start options (`providerOptions.cursor`), ACP-oriented:
	213	- optional `binaryPath`
	214	- optional auth/mode knobs if needed later
	215	3. Extend model options for Cursor list and traits mapping.
	216	4. Add schemas for ACP-native event union in Cursor adapter service file.
	217
	218	### 6.2 Server orchestration and registry
	219
	220	1. Register `CursorAdapter` in provider registry and server layer wiring.
	221	2. Update provider-kind persistence decoding for `cursor`.
	222	3. Fix `ProviderCommandReactor` precedence to honor explicit provider in turn-start command.
	223
	224	### 6.3 Web
	225
	226	1. Cursor in provider picker and model picker (already partially done).
	227	2. Trait controls map to concrete Cursor model identifiers.
	228	3. Surface unsupported rollback behavior in UX.
215	229
216	230	---
217	231
218	232	## 7) Implementation Phases
219	233
220		### Phase A: Protocol-safe adapter skeleton
	234	### Phase A: ACP process and protocol skeleton
221	235
222		1. Implement `CursorAdapter` service/layer with all runtime logic in `CursorAdapterLive` (no CLI manager), plus session map + event queue.
223		2. Implement robust NDJSON parser with:
224		- line buffering
225		- tolerant non-JSON handling
226		- explicit process-exit mapping.
227		3. Wire into registry and server layers.
	236	1. Implement ACP process lifecycle in `CursorAdapterLive`.
	237	2. Implement JSON-RPC request/response multiplexer.
	238	3. Implement `initialize`/`authenticate`/`session/new\|load` flow.
	239	4. Wire `streamEvents` from ACP notifications.
228	240
229		### Phase B: Event projection completeness
	241	### Phase B: Runtime projection and approvals
230	242
231		1. Map assistant/tool/result events to canonical runtime events.
232		2. Add synthetic ID strategy and item lifecycle consistency.
233		3. Add runtime error and retry handling.
	243	1. Map `session/update` variants to canonical runtime events.
	244	2. Implement permission-request bridging to `respondToRequest`.
	245	3. Implement dedupe for repeated `tool_call` on same `toolCallId`.
234	246
235		### Phase C: Provider selection and UX
	247	### Phase C: Turn control and interruption
236	248
237		1. Fix `ProviderCommandReactor` provider precedence.
238		2. Enable Cursor provider in web UI.
239		3. Add Cursor model defaults/options.
	249	1. Implement single in-flight prompt protection per session.
	250	2. Implement interruption fallback (process restart + reload) because `session/cancel` unavailable.
	251	3. Ensure clean state recovery on ACP process crash.
240	252
241		### Phase D: Safeguards and unsupported surfaces
	253	### Phase D: Orchestration + UX polish
242	254
243		1. Explicit unsupported errors for `respondToRequest` and `rollbackThread` (v1).
244		2. Guard checkpoint-revert path for Cursor threads.
245		3. Document limitations in UI/help text.
	255	1. Provider routing precedence fix.
	256	2. Cursor-specific UX notes for unsupported rollback.
	257	3. End-to-end smoke and event log validation.
246	258
247	259	---
248	260
...	...	@@ -252,59 +264,64 @@ Follow project rule: backend external-service integrations tested via layered fa
252	264
253	265	### 8.1 Unit tests (`CursorAdapter`)
254	266
255		1. stream JSON parse and mapping:
256		- assistant partial/final
257		- each tool type
258		- shell success/failure/rejected
259		- non-JSON line failure
260		2. process lifecycle:
261		- start/send/interrupt/stop
262		- stale session errors
263		3. ID sanitization:
264		- `call_id` with newline.
	267	1. JSON-RPC envelope parsing:
	268	- response matching by id
	269	- server request handling (`session/request_permission`)
	270	- notification decode (`session/update`)
	271	2. Event projection:
	272	- `agent_message_chunk` / `agent_thought_chunk`
	273	- `tool_call` + `tool_call_update` dedupe/lifecycle
	274	- permission request -> approval events
	275	3. Error mapping:
	276	- unknown session
	277	- method-not-found (`session/cancel`)
	278	- invalid params
265	279
266	280	### 8.2 Provider service/routing tests
267	281
268	282	1. Registry resolves `cursor`.
269		2. Session directory persistence reads/writes `cursor` provider.
270		3. ProviderService fan-out/order with Cursor events.
	283	2. Session directory persistence reads/writes `cursor`.
	284	3. ProviderService fan-out ordering with Cursor ACP events.
271	285
272	286	### 8.3 Orchestration tests
273	287
274	288	1. `thread.turn.start` with `provider: cursor` routes to Cursor adapter.
275		2. checkpoint revert on Cursor thread returns controlled failure activity.
276		3. approval response command on Cursor session surfaces “unsupported approval API”.
	289	2. approval response command maps to ACP permission response.
	290	3. checkpoint revert on Cursor thread returns controlled unsupported failure.
277	291
278		### 8.4 Smoke/integration harness
	292	### 8.4 Optional live smoke
279	293
280		1. Optional local smoke behind env flag (`CURSOR_SMOKE=1`) to run real `agent`:
281		- create session
282		- send simple turn
283		- verify message delta/completion + turn completion.
	294	1. Env-gated ACP smoke:
	295	- start session
	296	- run prompt
	297	- observe deltas + completion
	298	- exercise permission request path with one tool call
284	299
285	300	---
286	301
287	302	## 9) Operational Notes
288	303
289		1. Do not run concurrent `agent` processes per workspace by default; serialize per adapter session to avoid config races.
290		2. Keep native event NDJSON logs for Cursor similar to Codex adapter logs.
291		3. Treat startup plain-text failures as process-level errors and surface full message.
	304	1. Keep one in-flight turn per ACP session.
	305	2. Keep per-session ACP process logs/NDJSON artifacts for debugging.
	306	3. Treat `session/cancel` as unsupported until Cursor ships it; avoid relying on it.
	307	4. Preserve resume metadata (`acpSessionId`) for crash recovery.
292	308
293	309	---
294	310
295	311	## 10) Open Questions
296	312
297		1. Should Cursor provider expose full model list dynamically (`agent --list-models`) or use curated static list in contracts?
298		2. Should T3 keep strict approval UX parity with Codex, or accept Cursor’s current non-interactive approval limitation in v1?
299		3. Is checkpoint revert required for initial Cursor release, or can it ship as explicitly unsupported?
	313	1. Should we call `authenticate` always, or only after auth-required errors?
	314	2. Should model selection be passed at `session/new` only, or can/should we support model switching mid-session if ACP adds API?
	315	3. For interruption UX, do we expose “hard interrupt” semantics (process restart) explicitly?
300	316
301	317	---
302	318
303	319	## 11) Delivery Checklist
304	320
305		1. Contracts updated (`ProviderKind`, provider start options, models).
306		2. Cursor adapter + layer implemented and registered.
307		3. Provider selection precedence fixed in `ProviderCommandReactor`.
308		4. Cursor enabled in web provider picker.
309		5. Tests added for adapter mapping, routing, and orchestration behavior.
310		6. Lint + test suite green.
	321	1. Plan/documentation switched from headless `agent -p` to ACP `agent acp`.
	322	2. Contracts updated (`ProviderKind`, Cursor options, model/trait mapping).
	323	3. Cursor ACP adapter layer implemented and registered.
	324	4. Provider precedence fixed in orchestration router.
	325	5. Approval response path wired through ACP permission requests.
	326	6. Tests added for protocol decode, projection, approval flow, and routing.
	327	7. Lint + tests green.