The best way to control Claude Code, Codex and more from any computer or phone

main
ts 1,167 lines 44.5 KB
Raw
1 import type { AgentMessage, InteractionUpdate, RunResult, SteerAckOutcome } from "@cursor/sdk";
2 import * as ProviderEventLoggers from "@t3tools/provider-core/server/ProviderEventLoggers";
3 import { AgentScope } from "@t3tools/shared/AgentScope";
4 import * as HostProcess from "@t3tools/shared/HostProcess";
5 import * as Cause from "effect/Cause";
6 import * as Deferred from "effect/Deferred";
7 import * as Duration from "effect/Duration";
8 import * as Effect from "effect/Effect";
9 import * as Exit from "effect/Exit";
10 import * as Fiber from "effect/Fiber";
11 import * as Layer from "effect/Layer";
12 import * as Option from "effect/Option";
13 import * as ChildProcess from "effect/process/ChildProcess";
14 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
15 import * as Queue from "effect/Queue";
16 import * as Ref from "effect/Ref";
17 import * as Scope from "effect/Scope";
18 import * as Semaphore from "effect/Semaphore";
19 import * as Stream from "effect/Stream";
20
21 import * as CursorAgentSdk from "./CursorAgentSdk.ts";
22 import {
23 type CursorWorkerMessage,
24 type CursorWorkerRequest,
25 type CursorWorkerResponsePayload,
26 type SerializedRunResult,
27 type SerializedRunnerFailure,
28 decodeWorkerFrame,
29 deserializeRunResult,
30 deserializeWorkerError,
31 encodeWorkerFrame,
32 } from "./CursorAgentSdkWorkerProtocol.ts";
33
34 const WORKER_CLOSE_TIMEOUT = Duration.seconds(3);
35 const WORKER_EXIT_TIMEOUT = Duration.seconds(2);
36 const MAX_STDERR_CHARS = 8_192;
37
38 export interface CursorSdkWorkerLaunch {
39 readonly command: string;
40 readonly args: ReadonlyArray<string>;
41 readonly env?: NodeJS.ProcessEnv | undefined;
42 readonly registerProcess?: ((pid: number) => () => void) | undefined;
43 }
44
45 type RunQueueItem =
46 | { readonly _tag: "delta"; readonly update: InteractionUpdate }
47 | { readonly _tag: "done"; readonly ok: true; readonly result: RunResult }
48 | {
49 readonly _tag: "done";
50 readonly ok: false;
51 readonly error: CursorAgentSdk.CursorAgentSdkRunnerError;
52 };
53
54 interface ActiveWorkerRun {
55 readonly sessionId: number;
56 readonly queue: Queue.Queue<RunQueueItem>;
57 readonly waitDeferred: Deferred.Deferred<RunResult, CursorAgentSdk.CursorAgentSdkRunnerError>;
58 doneEnqueued: boolean;
59 }
60
61 function toRunnerError(method: string, cause: unknown): CursorAgentSdk.CursorAgentSdkRunnerError {
62 return CursorAgentSdk.isCursorAgentSdkRunnerError(cause)
63 ? cause
64 : new CursorAgentSdk.CursorAgentSdkRunnerError({ method, cause });
65 }
66
67 function fromSerializedFailure(
68 failure: SerializedRunnerFailure,
69 ): CursorAgentSdk.CursorAgentSdkRunnerError {
70 return new CursorAgentSdk.CursorAgentSdkRunnerError({
71 method: failure.method,
72 cause: deserializeWorkerError(failure.cause),
73 });
74 }
75
76 function workerExitError(method: string, exitCode: number | undefined, stderr: string) {
77 const trimmedStderr = stderr.trim();
78 const detail = `Cursor SDK worker exited unexpectedly${exitCode === undefined ? "" : ` (code ${exitCode})`}.`;
79 return new CursorAgentSdk.CursorAgentSdkRunnerError({
80 method,
81 cause: new Error(
82 detail,
83 trimmedStderr.length > 0 ? { cause: new Error(trimmedStderr) } : undefined,
84 ),
85 });
86 }
87
88 interface SpawnedCursorWorker {
89 readonly scope: Scope.Scope;
90 /** Routes worker-side protocol logs to the session that produced them. */
91 readonly protocolLoggers: Map<string, CursorAgentSdk.CursorAgentSdkProtocolLogger>;
92 readonly sessionProtocolLoggers: Map<number, CursorAgentSdk.CursorAgentSdkProtocolLogger>;
93 readonly nextId: () => number;
94 readonly requestWithId: (
95 id: number,
96 frame: CursorWorkerRequest,
97 method: string,
98 callbacks?: {
99 readonly onTransmitting?: () => void;
100 readonly onWorkerRejected?: () => void;
101 },
102 ) => Effect.Effect<CursorWorkerResponsePayload, CursorAgentSdk.CursorAgentSdkRunnerError>;
103 readonly request: (
104 build: (id: number) => CursorWorkerRequest,
105 method: string,
106 ) => Effect.Effect<CursorWorkerResponsePayload, CursorAgentSdk.CursorAgentSdkRunnerError>;
107 readonly registerRun: (sessionId: number, sendId: number) => Effect.Effect<ActiveWorkerRun>;
108 readonly unregisterRun: (sendId: number) => Effect.Effect<void>;
109 readonly failSessionRuns: (sessionId: number) => Effect.Effect<void>;
110 readonly setBackgroundShellListener: (
111 sessionId: number,
112 listener: (event: CursorAgentSdk.CursorBackgroundShellEvent) => Effect.Effect<void>,
113 ) => Effect.Effect<void>;
114 readonly drainBackgroundShellStops: (sessionId: number) => Effect.Effect<void>;
115 readonly closeBackgroundShellSession: (sessionId: number) => void;
116 readonly isAlive: () => boolean;
117 readonly close: (graceful: boolean) => Effect.Effect<void>;
118 }
119
120 export const makeCursorAgentSdkProcessRunner = Effect.fn("makeCursorAgentSdkProcessRunner")(
121 function* (options: {
122 readonly resolveLaunch: Effect.Effect<CursorSdkWorkerLaunch>;
123 readonly protocolLoggerFor: (
124 input: CursorAgentSdk.CursorAgentSdkOpenInput,
125 ) => CursorAgentSdk.CursorAgentSdkProtocolLogger | undefined;
126 readonly onWorkerTerminated?: (exitCode: number | undefined) => void;
127 }) {
128 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
129 const agentScope = yield* AgentScope;
130 const hostEnvironment = yield* HostProcess.Environment;
131 const runnerContext = yield* Effect.context<never>();
132 const activeCleanups = new Set<Effect.Effect<void>>();
133
134 yield* Effect.addFinalizer(() =>
135 Effect.forEach(Array.from(activeCleanups), (cleanup) => cleanup.pipe(Effect.ignore), {
136 concurrency: "unbounded",
137 discard: true,
138 }),
139 );
140
141 const spawnWorker = Effect.fn("CursorAgentSdkProcessRunner.spawnWorker")(
142 function* (): Effect.fn.Return<
143 SpawnedCursorWorker,
144 CursorAgentSdk.CursorAgentSdkRunnerError
145 > {
146 const workerScope = yield* Scope.make();
147 let activeCleanup: Effect.Effect<void> = Scope.close(workerScope, Exit.void).pipe(
148 Effect.ignore,
149 );
150 activeCleanups.add(activeCleanup);
151
152 const teardownScope = () =>
153 Scope.close(workerScope, Exit.void).pipe(
154 Effect.ignore,
155 Effect.ensuring(
156 Effect.sync(() => {
157 activeCleanups.delete(activeCleanup);
158 }),
159 ),
160 );
161
162 const launch = yield* options.resolveLaunch.pipe(
163 Effect.onError(() => teardownScope()),
164 Effect.mapError((cause) => toRunnerError("worker.launch", cause)),
165 );
166 const env: NodeJS.ProcessEnv = {
167 ...hostEnvironment,
168 ...launch.env,
169 ELECTRON_RUN_AS_NODE: "1",
170 };
171 const wrapped = yield* agentScope.wrap({
172 command: launch.command,
173 args: launch.args,
174 name: "cursor-sdk",
175 env,
176 shared: true,
177 });
178
179 const handle = yield* Scope.provide(
180 Effect.acquireRelease(
181 spawner.spawn(
182 ChildProcess.make(wrapped.command, wrapped.args, {
183 stdin: { stream: "pipe", endOnDone: false },
184 stdout: "pipe",
185 stderr: "pipe",
186 env,
187 killSignal: "SIGTERM",
188 forceKillAfter: WORKER_EXIT_TIMEOUT,
189 }),
190 ),
191 (child) =>
192 child
193 .kill()
194 .pipe(
195 Effect.ignore,
196 Effect.andThen(
197 wrapped.unit === undefined ? Effect.void : agentScope.stop(wrapped.unit),
198 ),
199 ),
200 ),
201 workerScope,
202 ).pipe(
203 Effect.onError(() => teardownScope()),
204 Effect.mapError((cause) => toRunnerError("worker.spawn", cause)),
205 );
206
207 if (launch.registerProcess !== undefined) {
208 const unregister = yield* Effect.try({
209 try: () => launch.registerProcess!(handle.pid),
210 catch: (cause) => toRunnerError("worker.register", cause),
211 }).pipe(Effect.onError(() => teardownScope()));
212 yield* Scope.addFinalizer(workerScope, Effect.sync(unregister));
213 }
214
215 const writeMutex = yield* Semaphore.make(1);
216 const closed = yield* Ref.make(false);
217 const protocolLoggers = new Map<string, CursorAgentSdk.CursorAgentSdkProtocolLogger>();
218 const sessionProtocolLoggers = new Map<
219 number,
220 CursorAgentSdk.CursorAgentSdkProtocolLogger
221 >();
222 const closedDone = yield* Deferred.make<void>();
223 const stdoutDone = yield* Deferred.make<void>();
224 const stderrDone = yield* Deferred.make<void>();
225 let nextRequestId = 0;
226 let stderrTail = "";
227 let closing = false;
228 let terminated: { readonly exitCode: number | undefined } | undefined;
229 let deadTeardownScheduled = false;
230
231 const pendingRequests = new Map<
232 number,
233 {
234 readonly method: string;
235 readonly deferred: Deferred.Deferred<
236 CursorWorkerResponsePayload,
237 CursorAgentSdk.CursorAgentSdkRunnerError
238 >;
239 readonly onWorkerRejected?: (() => void) | undefined;
240 }
241 >();
242 const activeRuns = new Map<number, ActiveWorkerRun>();
243 const backgroundShellSessions = new Map<
244 number,
245 {
246 listener: (event: CursorAgentSdk.CursorBackgroundShellEvent) => Effect.Effect<void>;
247 readonly queue: Queue.Queue<CursorAgentSdk.CursorBackgroundShellEvent | null>;
248 closed: boolean;
249 }
250 >();
251 const activeBackgroundShells = new Map<
252 string,
253 {
254 readonly sessionId: number;
255 readonly id: string;
256 readonly pid: number | undefined;
257 readonly command: string;
258 }
259 >();
260 const pendingShellStops = new Map<string, Fiber.Fiber<void, never>>();
261
262 const hasDrainingRuns = () => {
263 for (const run of activeRuns.values()) {
264 if (run.doneEnqueued) return true;
265 }
266 return false;
267 };
268
269 // Untraced: internal shutdown helper already covered by the enclosing operation span.
270 const failAllPending = Effect.fnUntraced(function* (
271 exitCode: number | undefined,
272 forceActiveRuns: boolean,
273 ) {
274 const wasTerminated = terminated !== undefined;
275 if (!wasTerminated) {
276 terminated = { exitCode };
277 }
278 const pending = Array.from(pendingRequests.entries());
279 pendingRequests.clear();
280 for (const [, entry] of pending) {
281 yield* Deferred.fail(
282 entry.deferred,
283 workerExitError(entry.method, exitCode, stderrTail),
284 );
285 }
286 for (const run of activeRuns.values()) {
287 const error = workerExitError("run.wait", exitCode, stderrTail);
288 if (!run.doneEnqueued) {
289 run.doneEnqueued = true;
290 Queue.offerUnsafe(run.queue, { _tag: "done", ok: false, error });
291 yield* Deferred.fail(run.waitDeferred, error);
292 } else if (forceActiveRuns) {
293 // Forced teardown interrupts the FIFO consumer, so settle waiters directly.
294 yield* Deferred.fail(run.waitDeferred, error);
295 }
296 }
297 // Background shells live in the worker's process tree, so a dead worker ends them too.
298 for (const [key, shell] of activeBackgroundShells) {
299 activeBackgroundShells.delete(key);
300 const sessionState = backgroundShellSessions.get(shell.sessionId);
301 if (sessionState !== undefined && !sessionState.closed) {
302 Queue.offerUnsafe(sessionState.queue, {
303 type: "ended",
304 id: shell.id,
305 pid: shell.pid,
306 command: shell.command,
307 stopped: true,
308 exitCode: undefined,
309 outputPath: undefined,
310 });
311 }
312 }
313 for (const sessionState of backgroundShellSessions.values()) {
314 if (!sessionState.closed) {
315 sessionState.closed = true;
316 Queue.offerUnsafe(sessionState.queue, null);
317 }
318 }
319 if (!wasTerminated && options.onWorkerTerminated !== undefined) {
320 const notify = options.onWorkerTerminated;
321 yield* Effect.try({
322 try: () => notify(exitCode),
323 catch: () => undefined,
324 }).pipe(Effect.ignore);
325 }
326 if (!forceActiveRuns && !deadTeardownScheduled && !hasDrainingRuns()) {
327 deadTeardownScheduled = true;
328 // Reap the dead worker's scope immediately instead of waiting for old sessions to idle out.
329 yield* Effect.forkDetach(close(false).pipe(Effect.ignore));
330 }
331 });
332
333 const handleLine = (line: string): Effect.Effect<void> => {
334 if (line.trim().length === 0) return Effect.void;
335 let parsed: CursorWorkerMessage;
336 try {
337 parsed = decodeWorkerFrame(line) as CursorWorkerMessage;
338 } catch {
339 return Effect.void;
340 }
341 switch (parsed.type) {
342 case "response": {
343 const entry = pendingRequests.get(parsed.id);
344 if (entry === undefined) return Effect.void;
345 pendingRequests.delete(parsed.id);
346 if (parsed.ok) {
347 return Deferred.succeed(entry.deferred, parsed.result).pipe(Effect.asVoid);
348 }
349 entry.onWorkerRejected?.();
350 return Deferred.fail(entry.deferred, fromSerializedFailure(parsed.error)).pipe(
351 Effect.asVoid,
352 );
353 }
354 case "delta": {
355 const run = activeRuns.get(parsed.sendId);
356 if (run !== undefined && !run.doneEnqueued) {
357 Queue.offerUnsafe(run.queue, { _tag: "delta", update: parsed.update });
358 }
359 return Effect.void;
360 }
361 case "runDone": {
362 const run = activeRuns.get(parsed.sendId);
363 if (run !== undefined && !run.doneEnqueued) {
364 run.doneEnqueued = true;
365 Queue.offerUnsafe(
366 run.queue,
367 parsed.ok
368 ? { _tag: "done", ok: true, result: deserializeRunResult(parsed.result) }
369 : { _tag: "done", ok: false, error: fromSerializedFailure(parsed.error) },
370 );
371 }
372 return Effect.void;
373 }
374 case "protocolLog": {
375 const logger =
376 (parsed.sessionId === undefined
377 ? undefined
378 : sessionProtocolLoggers.get(parsed.sessionId)) ??
379 protocolLoggers.get(parsed.providerSessionId);
380 return logger === undefined ? Effect.void : logger(parsed.event).pipe(Effect.ignore);
381 }
382 case "backgroundShell": {
383 const sessionState = backgroundShellSessions.get(parsed.sessionId);
384 if (sessionState === undefined || sessionState.closed) return Effect.void;
385 const key = `${parsed.sessionId}:${parsed.event.id}`;
386 if (parsed.event.type === "started") {
387 const { id, pid, command } = parsed.event;
388 activeBackgroundShells.set(key, {
389 sessionId: parsed.sessionId,
390 id,
391 pid,
392 command,
393 });
394 const stop = () => {
395 const stopFiber = Effect.runForkWith(runnerContext)(
396 request(
397 (reqId) => ({
398 id: reqId,
399 type: "stopBackgroundShell",
400 sessionId: parsed.sessionId,
401 shellId: id,
402 }),
403 "shell.stop",
404 ).pipe(
405 Effect.ignore,
406 Effect.ensuring(
407 Effect.sync(() => {
408 if (pendingShellStops.get(key) === stopFiber) {
409 pendingShellStops.delete(key);
410 }
411 }),
412 ),
413 ),
414 );
415 pendingShellStops.set(key, stopFiber);
416 };
417 Queue.offerUnsafe(sessionState.queue, {
418 type: "started",
419 id,
420 pid,
421 command,
422 stop,
423 });
424 return Effect.void;
425 }
426 activeBackgroundShells.delete(key);
427 Queue.offerUnsafe(sessionState.queue, {
428 type: "ended",
429 id: parsed.event.id,
430 pid: parsed.event.pid,
431 command: parsed.event.command,
432 stopped: parsed.event.stopped,
433 exitCode: parsed.event.exitCode,
434 outputPath: parsed.event.outputPath,
435 });
436 return Effect.void;
437 }
438 }
439 };
440
441 yield* handle.stderr.pipe(
442 Stream.decodeText(),
443 Stream.runForEach((chunk) =>
444 Effect.sync(() => {
445 stderrTail += chunk;
446 if (stderrTail.length > MAX_STDERR_CHARS) {
447 stderrTail = stderrTail.slice(-MAX_STDERR_CHARS);
448 }
449 }),
450 ),
451 Effect.ignore,
452 Effect.ensuring(Deferred.succeed(stderrDone, undefined).pipe(Effect.asVoid)),
453 Effect.forkIn(workerScope),
454 );
455
456 yield* handle.stdout.pipe(
457 Stream.decodeText(),
458 Stream.splitLines,
459 Stream.runForEach(handleLine),
460 Effect.ignore,
461 Effect.ensuring(
462 Deferred.succeed(stdoutDone, undefined).pipe(
463 Effect.andThen(
464 Effect.suspend(() => {
465 if (terminated !== undefined) return Effect.void;
466 return handle.exitCode.pipe(
467 Effect.map((code) => Number(code)),
468 Effect.timeoutOption(Duration.millis(250)),
469 Effect.orElseSucceed(() => Option.none<number>()),
470 Effect.flatMap((exitCode) =>
471 Deferred.await(stderrDone).pipe(
472 Effect.timeoutOption(Duration.millis(500)),
473 Effect.andThen(failAllPending(Option.getOrUndefined(exitCode), false)),
474 ),
475 ),
476 );
477 }),
478 ),
479 ),
480 ),
481 Effect.forkIn(workerScope),
482 );
483
484 yield* handle.exitCode.pipe(
485 Effect.map((code) => Number(code)),
486 Effect.orElseSucceed(() => undefined),
487 Effect.flatMap((exitCode) =>
488 // Drain buffered stdout replies and stderr tail before failing remaining requests.
489 Effect.all([Deferred.await(stdoutDone), Deferred.await(stderrDone)], {
490 concurrency: "unbounded",
491 discard: true,
492 }).pipe(
493 Effect.timeoutOption(Duration.millis(500)),
494 Effect.andThen(failAllPending(exitCode, false)),
495 ),
496 ),
497 Effect.forkIn(workerScope),
498 );
499
500 const writeFrame = (
501 frame: CursorWorkerRequest,
502 method: string,
503 onTransmitting?: () => void,
504 ) =>
505 writeMutex.withPermits(1)(
506 Effect.suspend(() => {
507 if (terminated !== undefined) {
508 return Effect.fail(workerExitError(method, terminated.exitCode, stderrTail));
509 }
510 onTransmitting?.();
511 return Stream.run(
512 Stream.encodeText(Stream.make(encodeWorkerFrame(frame))),
513 handle.stdin,
514 ).pipe(Effect.mapError((cause) => toRunnerError(method, cause)));
515 }),
516 );
517
518 // Untraced: callers own the enclosing RPC operation span.
519 const requestWithId = Effect.fnUntraced(function* (
520 id: number,
521 frame: CursorWorkerRequest,
522 method: string,
523 callbacks?: {
524 readonly onTransmitting?: () => void;
525 readonly onWorkerRejected?: () => void;
526 },
527 ) {
528 if (terminated !== undefined) {
529 return yield* workerExitError(method, terminated.exitCode, stderrTail);
530 }
531 const deferred = yield* Deferred.make<
532 CursorWorkerResponsePayload,
533 CursorAgentSdk.CursorAgentSdkRunnerError
534 >();
535 pendingRequests.set(id, {
536 method,
537 deferred,
538 ...(callbacks?.onWorkerRejected === undefined
539 ? {}
540 : { onWorkerRejected: callbacks.onWorkerRejected }),
541 });
542 return yield* writeFrame(frame, method, callbacks?.onTransmitting).pipe(
543 Effect.andThen(Deferred.await(deferred)),
544 Effect.onInterrupt(() =>
545 Effect.sync(() => {
546 pendingRequests.delete(id);
547 }),
548 ),
549 Effect.onError(() =>
550 Effect.sync(() => {
551 pendingRequests.delete(id);
552 }),
553 ),
554 );
555 });
556
557 const nextId = () => ++nextRequestId;
558
559 const request = (
560 build: (id: number) => CursorWorkerRequest,
561 method: string,
562 ): Effect.Effect<CursorWorkerResponsePayload, CursorAgentSdk.CursorAgentSdkRunnerError> =>
563 Effect.suspend(() => {
564 const id = nextId();
565 return requestWithId(id, build(id), method);
566 });
567
568 // Untraced: called from close/finalizer boundaries that already hold a span.
569 const close: (graceful: boolean) => Effect.Effect<void> = Effect.fnUntraced(function* (
570 graceful: boolean,
571 ) {
572 closing = true;
573 if (yield* Ref.getAndSet(closed, true)) {
574 return yield* Deferred.await(closedDone);
575 }
576 const gracefulShutdown =
577 graceful && terminated === undefined
578 ? request((id) => ({ id, type: "close" }), "agent.close").pipe(
579 Effect.timeoutOption(WORKER_CLOSE_TIMEOUT),
580 Effect.ignore,
581 Effect.andThen(
582 handle.exitCode.pipe(Effect.timeoutOption(WORKER_EXIT_TIMEOUT), Effect.ignore),
583 ),
584 )
585 : Effect.void;
586 yield* gracefulShutdown.pipe(
587 Effect.ensuring(
588 failAllPending(terminated?.exitCode, true).pipe(
589 Effect.andThen(Effect.suspend(teardownScope)),
590 Effect.ensuring(Deferred.succeed(closedDone, undefined).pipe(Effect.asVoid)),
591 ),
592 ),
593 );
594 });
595
596 // Replace the raw scope closer with forced worker teardown so runner shutdown settles runs.
597 activeCleanups.delete(activeCleanup);
598 activeCleanup = close(false);
599 activeCleanups.add(activeCleanup);
600
601 // Untraced: per-send registration inside CursorAgentSdkSession.send.
602 const registerRun = Effect.fnUntraced(function* (sessionId: number, sendId: number) {
603 const queue = yield* Queue.unbounded<RunQueueItem>();
604 const waitDeferred = yield* Deferred.make<
605 RunResult,
606 CursorAgentSdk.CursorAgentSdkRunnerError
607 >();
608 const state: ActiveWorkerRun = { sessionId, queue, waitDeferred, doneEnqueued: false };
609 activeRuns.set(sendId, state);
610 return state;
611 });
612
613 // Untraced: settles only runs belonging to a closed session without disturbing peers.
614 const failSessionRuns = Effect.fnUntraced(function* (sessionId: number) {
615 const error = new CursorAgentSdk.CursorAgentSdkRunnerError({
616 method: "run.wait",
617 cause: new Error("Cursor SDK session was closed."),
618 });
619 for (const run of activeRuns.values()) {
620 if (run.sessionId !== sessionId) continue;
621 if (!run.doneEnqueued) {
622 run.doneEnqueued = true;
623 Queue.offerUnsafe(run.queue, { _tag: "done", ok: false, error });
624 yield* Deferred.fail(run.waitDeferred, error);
625 }
626 }
627 });
628
629 return {
630 scope: workerScope,
631 protocolLoggers,
632 sessionProtocolLoggers,
633 nextId,
634 requestWithId,
635 request,
636 registerRun,
637 unregisterRun: (sendId) =>
638 Effect.suspend(() => {
639 activeRuns.delete(sendId);
640 if (terminated !== undefined && !deadTeardownScheduled && !hasDrainingRuns()) {
641 deadTeardownScheduled = true;
642 return Effect.forkDetach(close(false).pipe(Effect.ignore)).pipe(Effect.asVoid);
643 }
644 return Effect.void;
645 }),
646 failSessionRuns,
647 // Untraced: called inside session.send which already carries a span.
648 setBackgroundShellListener: Effect.fnUntraced(function* (
649 sessionId: number,
650 listener: (event: CursorAgentSdk.CursorBackgroundShellEvent) => Effect.Effect<void>,
651 ) {
652 const existing = backgroundShellSessions.get(sessionId);
653 if (existing !== undefined && !existing.closed) {
654 existing.listener = listener;
655 return;
656 }
657 const queue =
658 yield* Queue.unbounded<CursorAgentSdk.CursorBackgroundShellEvent | null>();
659 const state = { listener, queue, closed: false };
660 backgroundShellSessions.set(sessionId, state);
661 // Detached from workerScope so synthesized ended events finish draining on worker crash.
662 yield* Effect.forkDetach(
663 Effect.gen(function* () {
664 while (true) {
665 const event = yield* Queue.take(queue);
666 if (event === null) return;
667 yield* state.listener(event).pipe(Effect.ignore);
668 }
669 }),
670 );
671 }),
672 drainBackgroundShellStops: (sessionId) =>
673 Effect.suspend(() => {
674 const prefix = `${sessionId}:`;
675 const fibers: Array<Fiber.Fiber<void, never>> = [];
676 for (const [key, fiber] of pendingShellStops) {
677 if (key.startsWith(prefix)) fibers.push(fiber);
678 }
679 if (fibers.length === 0) return Effect.void;
680 return Effect.forEach(fibers, (fiber) => Fiber.await(fiber), {
681 concurrency: "unbounded",
682 discard: true,
683 }).pipe(Effect.timeoutOption(WORKER_CLOSE_TIMEOUT), Effect.asVoid);
684 }),
685 closeBackgroundShellSession: (sessionId) => {
686 const prefix = `${sessionId}:`;
687 for (const key of activeBackgroundShells.keys()) {
688 if (key.startsWith(prefix)) activeBackgroundShells.delete(key);
689 }
690 const state = backgroundShellSessions.get(sessionId);
691 if (state !== undefined) {
692 backgroundShellSessions.delete(sessionId);
693 if (!state.closed) {
694 state.closed = true;
695 Queue.offerUnsafe(state.queue, null);
696 }
697 }
698 },
699 isAlive: () => terminated === undefined && !closing,
700 close,
701 };
702 },
703 );
704
705 // Every session and text generation shares one worker: a process per session duplicates the
706 // SDK's ~250 MB baseline and pages the host under concurrent threads. Idle, the worker exits.
707 interface WorkerLease {
708 readonly worker: SpawnedCursorWorker;
709 users: number;
710 }
711 let shared: WorkerLease | undefined;
712 const sharedLock = yield* Semaphore.make(1);
713 const acquireWorker = sharedLock.withPermits(1)(
714 Effect.suspend(() => {
715 if (shared !== undefined && shared.worker.isAlive()) {
716 shared.users += 1;
717 return Effect.succeed(shared);
718 }
719 return spawnWorker().pipe(
720 Effect.map((worker) => {
721 const lease: WorkerLease = { worker, users: 1 };
722 shared = lease;
723 return lease;
724 }),
725 );
726 }),
727 );
728 const releaseWorker = (lease: WorkerLease) =>
729 sharedLock
730 .withPermits(1)(
731 Effect.sync(() => {
732 lease.users -= 1;
733 if (lease.users > 0) return false;
734 if (shared === lease) shared = undefined;
735 return true;
736 }),
737 )
738 .pipe(
739 Effect.flatMap((shouldClose) => (shouldClose ? lease.worker.close(true) : Effect.void)),
740 );
741
742 return CursorAgentSdk.CursorAgentSdkRunner.of({
743 open: Effect.fn("CursorAgentSdkProcessRunner.open")(function* (input) {
744 const protocolLogger = options.protocolLoggerFor(input);
745 const log = (event: CursorAgentSdk.CursorAgentSdkProtocolLogEvent) =>
746 protocolLogger === undefined ? Effect.void : protocolLogger(event);
747
748 yield* log({
749 direction: "outgoing",
750 stage: "decoded",
751 payload: {
752 type: "agent.open",
753 operation: input.operation,
754 ...(input.agentId === undefined ? {} : { agentId: input.agentId }),
755 options: CursorAgentSdk.loggedCursorAgentOptions(input.options),
756 },
757 });
758
759 const lease = yield* acquireWorker;
760 const { worker } = lease;
761 const sessionId = worker.nextId();
762 if (protocolLogger !== undefined) {
763 worker.protocolLoggers.set(input.providerSessionId, protocolLogger);
764 worker.sessionProtocolLoggers.set(sessionId, protocolLogger);
765 }
766 let openTransmitted = false;
767 let openRejected = false;
768 let opened = false;
769 let sessionClosed = false;
770 let handedOff = false;
771 const forgetLogger = Effect.sync(() => {
772 worker.closeBackgroundShellSession(sessionId);
773 worker.sessionProtocolLoggers.delete(sessionId);
774 if (worker.protocolLoggers.get(input.providerSessionId) === protocolLogger) {
775 worker.protocolLoggers.delete(input.providerSessionId);
776 }
777 });
778 const closeWorkerSession = Effect.suspend(() => {
779 sessionClosed = true;
780 return worker
781 .drainBackgroundShellStops(sessionId)
782 .pipe(
783 Effect.andThen(
784 worker.request((id) => ({ id, type: "closeSession", sessionId }), "agent.close"),
785 ),
786 Effect.timeoutOption(WORKER_CLOSE_TIMEOUT),
787 Effect.ignore,
788 Effect.ensuring(worker.failSessionRuns(sessionId)),
789 );
790 });
791 const release = (closeInWorker: boolean) =>
792 (closeInWorker ? closeWorkerSession : Effect.void).pipe(
793 Effect.ensuring(forgetLogger),
794 Effect.ensuring(releaseWorker(lease)),
795 );
796 return yield* Effect.gen(function* () {
797 const openedAgent = (yield* worker.requestWithId(
798 sessionId,
799 {
800 id: sessionId,
801 type: "open",
802 operation: input.operation,
803 ...(input.agentId === undefined ? {} : { agentId: input.agentId }),
804 ...(input.storeCwd === undefined ? {} : { storeCwd: input.storeCwd }),
805 options: input.options,
806 threadId: input.threadId,
807 providerSessionId: input.providerSessionId,
808 },
809 `agent.${input.operation}`,
810 {
811 onTransmitting: () => {
812 openTransmitted = true;
813 },
814 onWorkerRejected: () => {
815 openRejected = true;
816 },
817 },
818 )) as { readonly agentId: string };
819 opened = true;
820
821 const agentId = openedAgent.agentId;
822 yield* log({
823 direction: "incoming",
824 stage: "decoded",
825 payload: {
826 type: "agent.opened",
827 agentId,
828 },
829 });
830
831 const closeSession = yield* Effect.cached(
832 log({
833 direction: "outgoing",
834 stage: "decoded",
835 payload: {
836 type: "agent.close",
837 agentId,
838 },
839 }).pipe(Effect.andThen(release(true))),
840 );
841
842 const session = {
843 agentId,
844 send: Effect.fn("CursorAgentSdkSession.send")(function* (sendInput) {
845 const loggedOptions = CursorAgentSdk.loggedCursorSendOptions(sendInput.options);
846 yield* sendInput.resume === true
847 ? log({
848 direction: "outgoing",
849 stage: "decoded",
850 payload: { type: "run.resume", options: loggedOptions },
851 })
852 : log({
853 direction: "outgoing",
854 stage: "decoded",
855 payload: {
856 type: "run.start",
857 message: sendInput.message,
858 options: loggedOptions,
859 },
860 });
861
862 const sendId = worker.nextId();
863 if (sendInput.onBackgroundShell !== undefined) {
864 yield* worker.setBackgroundShellListener(sessionId, sendInput.onBackgroundShell);
865 }
866 const runState = yield* worker.registerRun(sessionId, sendId);
867 let transmitted = false;
868 let acknowledged = false;
869 let rejectedByWorker = false;
870 let runHandedOff = false;
871 return yield* Effect.gen(function* () {
872 const started = (yield* worker.requestWithId(
873 sendId,
874 {
875 id: sendId,
876 type: "send",
877 sessionId,
878 message: sendInput.message,
879 ...(sendInput.options === undefined ? {} : { options: sendInput.options }),
880 ...(sendInput.summarize === undefined
881 ? {}
882 : { summarize: sendInput.summarize }),
883 ...(sendInput.resume === undefined ? {} : { resume: sendInput.resume }),
884 ...(sendInput.onBackgroundShell === undefined
885 ? {}
886 : { listenBackgroundShells: true }),
887 },
888 sendInput.resume === true ? "run.resume" : "run.start",
889 {
890 onTransmitting: () => {
891 transmitted = true;
892 },
893 onWorkerRejected: () => {
894 rejectedByWorker = true;
895 },
896 },
897 )) as { readonly runId: string; readonly agentId: string };
898 acknowledged = true;
899
900 const { runId } = started;
901 yield* log({
902 direction: "incoming",
903 stage: "decoded",
904 payload: {
905 type: "run.started",
906 runId,
907 agentId: started.agentId,
908 },
909 });
910
911 // Consume deltas and terminal completion sequentially from one FIFO queue so every
912 // preceding onDelta finishes before run.wait resolves, matching the in-process runner.
913 yield* Effect.gen(function* () {
914 let callbackFailure: { readonly cause: unknown } | undefined;
915 while (true) {
916 const item = yield* Queue.take(runState.queue);
917 if (item._tag === "delta") {
918 if (callbackFailure !== undefined) continue;
919 const deltaExit = yield* Effect.exit(
920 log({
921 direction: "incoming",
922 stage: "decoded",
923 payload: {
924 type: "interaction.update",
925 runId,
926 update: item.update,
927 },
928 }).pipe(Effect.andThen(sendInput.onDelta?.(item.update) ?? Effect.void)),
929 );
930 if (Exit.isFailure(deltaExit)) {
931 callbackFailure = { cause: Cause.squash(deltaExit.cause) };
932 }
933 continue;
934 }
935 if (!item.ok) {
936 yield* Deferred.fail(runState.waitDeferred, item.error);
937 return;
938 }
939 if (callbackFailure !== undefined) {
940 yield* Deferred.fail(
941 runState.waitDeferred,
942 toRunnerError("run.wait", callbackFailure.cause),
943 );
944 return;
945 }
946 yield* log({
947 direction: "incoming",
948 stage: "decoded",
949 payload: {
950 type: "run.completed",
951 result: item.result,
952 },
953 });
954 yield* Deferred.succeed(runState.waitDeferred, item.result);
955 return;
956 }
957 }).pipe(Effect.ensuring(worker.unregisterRun(sendId)), Effect.forkIn(worker.scope));
958
959 const run = {
960 runId,
961 agentId: started.agentId,
962 wait: Deferred.await(runState.waitDeferred),
963 steer: Effect.fn("CursorAgentSdkRun.steer")((text: string) =>
964 log({
965 direction: "outgoing",
966 stage: "decoded",
967 payload: {
968 type: "run.steer",
969 runId,
970 text,
971 },
972 }).pipe(
973 Effect.andThen(
974 worker.request(
975 (id) => ({ id, type: "steer", sendId, text }),
976 "run.steer",
977 ) as Effect.Effect<
978 SteerAckOutcome,
979 CursorAgentSdk.CursorAgentSdkRunnerError
980 >,
981 ),
982 Effect.tap((outcome) =>
983 log({
984 direction: "incoming",
985 stage: "decoded",
986 payload: {
987 type: "run.steered",
988 runId,
989 outcome,
990 },
991 }),
992 ),
993 ),
994 ),
995 cancel: log({
996 direction: "outgoing",
997 stage: "decoded",
998 payload: {
999 type: "run.cancel",
1000 runId,
1001 },
1002 }).pipe(
1003 Effect.andThen(
1004 worker.request((id) => ({ id, type: "cancel", sendId }), "run.cancel"),
1005 ),
1006 Effect.asVoid,
1007 ),
1008 } satisfies CursorAgentSdk.CursorAgentSdkRun;
1009 runHandedOff = true;
1010 return run;
1011 }).pipe(
1012 Effect.ensuring(
1013 Effect.suspend(() => {
1014 if (runHandedOff) return Effect.void;
1015 const stopRun = acknowledged
1016 ? worker
1017 .request((id) => ({ id, type: "cancel", sendId }), "run.cancel")
1018 .pipe(
1019 Effect.timeoutOption(WORKER_CLOSE_TIMEOUT),
1020 // Other threads share the worker; closing this agent stops the run.
1021 Effect.flatMap(
1022 Option.match({
1023 onNone: () => closeWorkerSession,
1024 onSome: () => Effect.void,
1025 }),
1026 ),
1027 Effect.catch(() => closeWorkerSession),
1028 )
1029 : transmitted && !rejectedByWorker
1030 ? // A send interrupted after hitting stdin may still start in the worker.
1031 closeWorkerSession
1032 : Effect.void;
1033 return stopRun.pipe(Effect.ensuring(worker.unregisterRun(sendId)));
1034 }),
1035 ),
1036 );
1037 }),
1038 listMessages: log({
1039 direction: "outgoing",
1040 stage: "decoded",
1041 payload: {
1042 type: "agent.messages.list",
1043 agentId,
1044 },
1045 }).pipe(
1046 Effect.andThen(
1047 worker.request(
1048 (id) => ({ id, type: "listMessages", sessionId }),
1049 "agent.messages.list",
1050 ) as Effect.Effect<
1051 ReadonlyArray<AgentMessage>,
1052 CursorAgentSdk.CursorAgentSdkRunnerError
1053 >,
1054 ),
1055 Effect.tap((messages) =>
1056 log({
1057 direction: "incoming",
1058 stage: "decoded",
1059 payload: {
1060 type: "agent.messages",
1061 agentId,
1062 messages,
1063 },
1064 }),
1065 ),
1066 ),
1067 readContextUsage: worker
1068 .request(
1069 (id) => ({ id, type: "readContextUsage", sessionId }),
1070 "agent.checkpoint.load",
1071 )
1072 .pipe(
1073 Effect.map((result) =>
1074 result === null ? undefined : (result as CursorAgentSdk.CursorContextUsage),
1075 ),
1076 ),
1077 runCheckpointed: (runId) =>
1078 worker
1079 .request(
1080 (id) => ({
1081 id,
1082 type: "runCheckpointed",
1083 sessionId,
1084 ...(runId === undefined ? {} : { runId }),
1085 }),
1086 "agent.run.get",
1087 )
1088 .pipe(Effect.map((result) => result === true)),
1089 rewindAfterRun: (runId) =>
1090 log({
1091 direction: "outgoing",
1092 stage: "decoded",
1093 payload: { type: "agent.rewind", agentId, afterRunId: runId },
1094 }).pipe(
1095 Effect.andThen(
1096 worker.request(
1097 (id) => ({ id, type: "rewindAfterRun", sessionId, runId }),
1098 "agent.rewind",
1099 ),
1100 ),
1101 Effect.asVoid,
1102 ),
1103 isAlive: () => !sessionClosed && worker.isAlive(),
1104 close: closeSession,
1105 } satisfies CursorAgentSdk.CursorAgentSdkSession;
1106 handedOff = true;
1107 return session;
1108 }).pipe(
1109 Effect.ensuring(
1110 Effect.suspend(() =>
1111 handedOff ? Effect.void : release(opened || (openTransmitted && !openRejected)),
1112 ),
1113 ),
1114 );
1115 }),
1116 textGenerate: Effect.fn("CursorAgentSdkProcessRunner.textGenerate")(function* (input) {
1117 const lease = yield* acquireWorker;
1118 const { worker } = lease;
1119 const textGenerateId = worker.nextId();
1120 return yield* worker
1121 .requestWithId(
1122 textGenerateId,
1123 {
1124 id: textGenerateId,
1125 type: "textGenerate",
1126 prompt: input.prompt,
1127 apiKey: input.apiKey,
1128 model: input.model,
1129 cwd: input.cwd,
1130 stateRoot: input.stateRoot,
1131 },
1132 "textGenerate",
1133 )
1134 .pipe(
1135 Effect.map((result) => deserializeRunResult(result as SerializedRunResult)),
1136 Effect.onInterrupt(() =>
1137 worker
1138 .request(
1139 (id) => ({ id, type: "cancelTextGenerate", textGenerateId }),
1140 "textGenerate",
1141 )
1142 .pipe(Effect.timeoutOption(WORKER_CLOSE_TIMEOUT), Effect.ignore),
1143 ),
1144 Effect.ensuring(releaseWorker(lease)),
1145 );
1146 }),
1147 assertComplete: Effect.void,
1148 });
1149 },
1150 );
1151
1152 export const layer = (resolveLaunch: Effect.Effect<CursorSdkWorkerLaunch>) =>
1153 Layer.effect(
1154 CursorAgentSdk.CursorAgentSdkRunner,
1155 Effect.gen(function* () {
1156 const { native: nativeEventLogger } = yield* ProviderEventLoggers.ProviderEventLoggers;
1157 return yield* makeCursorAgentSdkProcessRunner({
1158 resolveLaunch,
1159 protocolLoggerFor: (input) =>
1160 CursorAgentSdk.makeCursorAgentSdkProtocolLogger({
1161 nativeEventLogger,
1162 threadId: input.threadId,
1163 providerSessionId: input.providerSessionId,
1164 }),
1165 });
1166 }),
1167 );