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

main
ts 474 lines 16.6 KB
Raw
1 // Pi frames are LF-delimited with trailing CR stripped; readline also splits U+2028/U+2029 and corrupts them.
2 import * as Clock from "effect/Clock";
3 import * as Deferred from "effect/Deferred";
4 import * as Duration from "effect/Duration";
5 import * as Effect from "effect/Effect";
6 import * as Option from "effect/Option";
7 import * as Predicate from "effect/Predicate";
8 import * as Queue from "effect/Queue";
9 import * as Scope from "effect/Scope";
10 import * as Schema from "effect/Schema";
11 import * as Stream from "effect/Stream";
12 import * as ChildProcess from "effect/process/ChildProcess";
13 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
14 import * as HostProcess from "@t3tools/shared/HostProcess";
15 import { resolveSpawnCommand } from "@t3tools/shared/shell";
16 import {
17 MAX_TOOL_OUTPUT_IMAGES,
18 MAX_TOOL_OUTPUT_IMAGE_BASE64_LENGTH,
19 } from "@t3tools/shared/toolOutput";
20
21 import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
22
23 export class PiRpcError extends Schema.TaggedError<PiRpcError>()("PiRpcError", {
24 operation: Schema.String,
25 detail: Schema.optional(Schema.String),
26 cause: Schema.optional(Schema.Defect()),
27 }) {
28 override get message(): string {
29 return `Pi RPC ${this.operation} failed${this.detail === undefined ? "" : `: ${this.detail}`}.`;
30 }
31 }
32
33 export class PiRpcTimeoutError extends Schema.TaggedError<PiRpcTimeoutError>()(
34 "PiRpcTimeoutError",
35 {
36 operation: Schema.String,
37 timeoutMs: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER })),
38 },
39 ) {
40 override get message(): string {
41 return `Pi RPC ${this.operation} failed: timed out after ${this.timeoutMs}ms.`;
42 }
43 }
44
45 export type PiRpcRecord = Record<string, unknown>;
46
47 export function piRecordField(input: unknown, key: string): unknown {
48 return Predicate.isObject(input) ? input[key] : undefined;
49 }
50
51 export function piRecordString(input: unknown, key: string): string | undefined {
52 const value = piRecordField(input, key);
53 return Predicate.isString(value) ? value : undefined;
54 }
55
56 export function piRecordNumber(input: unknown, key: string): number | undefined {
57 const value = piRecordField(input, key);
58 return Predicate.isNumber(value) && Number.isFinite(value) ? value : undefined;
59 }
60
61 // Pi provider names and model ids may both contain "/", so a slug only splits
62 // reliably through the `{provider, id}` pairs `get_available_models` reported.
63 export function findReportedPiModel(
64 slug: string,
65 reportedModels: unknown,
66 ): { provider: string; modelId: string } | undefined {
67 if (!Array.isArray(reportedModels)) return undefined;
68 for (const model of reportedModels) {
69 const provider = piRecordString(model, "provider");
70 const modelId = piRecordString(model, "id");
71 if (provider !== undefined && modelId !== undefined && `${provider}/${modelId}` === slug)
72 return { provider, modelId };
73 }
74 return undefined;
75 }
76
77 export function resolvePiModelSlug(
78 slug: string,
79 reportedModels: unknown,
80 ): { provider: string; modelId: string } | null {
81 const reported = findReportedPiModel(slug, reportedModels);
82 if (reported !== undefined) return reported;
83 const separator = slug.indexOf("/");
84 if (separator <= 0 || separator === slug.length - 1) return null;
85 return { provider: slug.slice(0, separator), modelId: slug.slice(separator + 1) };
86 }
87
88 export interface PiRpcSpawnOptions {
89 readonly command: string;
90 readonly args: ReadonlyArray<string>;
91 readonly cwd: string | undefined;
92 readonly env: NodeJS.ProcessEnv;
93 }
94
95 export interface PiRpcConnection {
96 readonly send: (record: PiRpcRecord) => Effect.Effect<void, PiRpcError>;
97 readonly request: (
98 record: PiRpcRecord,
99 timeoutMs?: number,
100 ) => Effect.Effect<unknown, PiRpcError | PiRpcTimeoutError>;
101 readonly events: Queue.Queue<PiRpcRecord, PiRpcError>;
102 readonly exited: Effect.Effect<number, PiRpcError>;
103 readonly terminate: Effect.Effect<void>;
104 }
105
106 const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
107 const TERMINATION_GRACE = Duration.seconds(1);
108 const TERMINATION_POLL_INTERVAL = Duration.millis(20);
109
110 interface PendingPiRequest {
111 readonly deferred: Deferred.Deferred<unknown, PiRpcError>;
112 }
113
114 // MCP duplicates images in model content and CallToolResult; budget both plus bounded overhead.
115 const MAX_PI_RECORD_CHARS =
116 2 * MAX_TOOL_OUTPUT_IMAGES * MAX_TOOL_OUTPUT_IMAGE_BASE64_LENGTH + 8 * 1024 * 1024;
117
118 function makeJsonlFramer() {
119 let buffer = "";
120 let dropping = false;
121 return (chunk: string) => {
122 const lines: string[] = [];
123 const droppedLengths: number[] = [];
124 let start = 0;
125 while (start < chunk.length) {
126 const newline = chunk.indexOf("\n", start);
127 const end = newline < 0 ? chunk.length : newline;
128 if (!dropping) {
129 if (buffer.length + end - start > MAX_PI_RECORD_CHARS) {
130 droppedLengths.push(buffer.length + end - start);
131 buffer = "";
132 dropping = true;
133 } else {
134 buffer += chunk.slice(start, end);
135 }
136 }
137 if (newline < 0) break;
138 if (!dropping && buffer.length > 0) {
139 lines.push(buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer);
140 }
141 buffer = "";
142 dropping = false;
143 start = newline + 1;
144 }
145 return { lines, droppedLengths };
146 };
147 }
148
149 // Report the observed length before LF arrives; an unterminated response can time out first.
150 const logDroppedPiRecords = (droppedLengths: ReadonlyArray<number>) =>
151 Effect.forEach(
152 droppedLengths,
153 (recordLength) =>
154 Effect.logWarning("Dropping oversized pi stdout record.", {
155 recordLength,
156 maxRecordLength: MAX_PI_RECORD_CHARS,
157 }),
158 { discard: true },
159 );
160
161 const UnknownFromJsonString = Schema.fromJsonString(Schema.Unknown);
162 const decodeJsonLine = Schema.decodeSync(UnknownFromJsonString);
163 const encodeJsonLine = Schema.encodeSync(UnknownFromJsonString);
164
165 const PI_ERROR_DETAIL_MAX_CHARS = 200;
166
167 function summarizePiError(error: unknown): string {
168 const text = typeof error === "string" ? error : JSON.stringify(error);
169 if (text === undefined) return "unknown error";
170 return text.length > PI_ERROR_DETAIL_MAX_CHARS
171 ? `${text.slice(0, PI_ERROR_DETAIL_MAX_CHARS)}…`
172 : text;
173 }
174
175 // Pi 0.84+ may exit 1 during import without any protocol output.
176 function describePiStdoutClosure(exitCode: number | undefined): string {
177 if (exitCode === undefined || !Number.isFinite(exitCode)) {
178 return "pi process closed stdout";
179 }
180 return `pi process exited with code ${exitCode}`;
181 }
182
183 function parsePiRecord(line: string): PiRpcRecord | undefined {
184 try {
185 const parsed: unknown = decodeJsonLine(line);
186 return Predicate.isObject(parsed) ? parsed : undefined;
187 } catch {
188 return undefined;
189 }
190 }
191
192 /**
193 * `hasExited` is consulted before each signal. Once the original child is
194 * gone its pid/pgid can be recycled by the OS, so escalating blindly could
195 * deliver SIGKILL to an unrelated process.
196 */
197 const terminatePiProcess = Effect.fn("PiRpc.terminatePiProcess")(function* (
198 kill: (signal: NodeJS.Signals) => boolean,
199 hasExited: () => boolean,
200 groupGone: () => boolean,
201 ) {
202 if (hasExited()) return;
203 if (!kill("SIGTERM")) return;
204 yield* Effect.sleep(TERMINATION_POLL_INTERVAL).pipe(
205 Effect.repeat({ until: groupGone }),
206 Effect.timeoutOption(TERMINATION_GRACE),
207 );
208 if (hasExited()) return;
209 kill("SIGKILL");
210 });
211
212 export const makePiRpcConnection = Effect.fnUntraced(function* (options: PiRpcSpawnOptions) {
213 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
214 const platform = yield* HostProcess.Platform;
215 const scope = yield* Effect.scope;
216
217 const spawnCommand = yield* resolveSpawnCommand(options.command, [...options.args], {
218 env: options.env,
219 }).pipe(Effect.mapError((cause) => new PiRpcError({ operation: "spawn", cause })));
220 const child = yield* spawner
221 .spawn(
222 ChildProcess.make(spawnCommand.command, spawnCommand.args, {
223 ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
224 env: options.env,
225 extendEnv: false,
226 shell: spawnCommand.shell,
227 detached: platform !== "win32",
228 // On stdin EOF Pi quits without its SIGTERM handler, so the later SIGTERM kills it mid-cleanup.
229 stdin: { stream: "pipe", endOnDone: false },
230 }),
231 )
232 .pipe(Effect.mapError((cause) => new PiRpcError({ operation: "spawn", cause })));
233
234 let childExited = false;
235 let diagnosingStdoutClose = false;
236
237 const killProcessGroup = (signal: NodeJS.Signals): boolean => {
238 try {
239 if (platform === "win32") {
240 process.kill(Number(child.pid), signal);
241 } else {
242 signalProcessGroup(Number(child.pid), signal);
243 }
244 return true;
245 } catch {
246 return false;
247 }
248 };
249
250 const hasExited = (): boolean => {
251 if (childExited) return true;
252 try {
253 if (platform === "win32") process.kill(Number(child.pid), 0);
254 else signalProcessGroup(Number(child.pid), 0);
255 return false;
256 } catch {
257 return true;
258 }
259 };
260
261 // EPERM means a group member is still alive, so only ESRCH ends the SIGTERM grace early.
262 const processGroupGone = (): boolean => {
263 try {
264 signalProcessGroup(Number(child.pid), 0);
265 return false;
266 } catch (cause) {
267 return (cause as NodeJS.ErrnoException | undefined)?.code === "ESRCH";
268 }
269 };
270
271 // Windows process.kill leaves extension children and pipes alive; taskkill /T reaps the tree.
272 const terminateWindowsTree = Effect.gen(function* () {
273 if (hasExited()) return;
274 const taskkill = yield* spawner.spawn(
275 ChildProcess.make("taskkill", ["/PID", String(child.pid), "/T", "/F"]),
276 );
277 yield* taskkill.exitCode;
278 }).pipe(Effect.scoped, Effect.ignore);
279
280 const terminateProcess =
281 platform === "win32"
282 ? terminateWindowsTree
283 : terminatePiProcess(killProcessGroup, hasExited, processGroupGone);
284
285 // Register teardown immediately after spawn so interrupted setup cannot leak a detached process.
286 yield* Scope.addFinalizer(scope, terminateProcess.pipe(Effect.ignore, Effect.uninterruptible));
287
288 const pendingRequests = new Map<string, PendingPiRequest>();
289 const events = yield* Queue.unbounded<PiRpcRecord, PiRpcError>();
290 const outgoing = yield* Queue.unbounded<Uint8Array, PiRpcError>();
291 const transportDown = yield* Deferred.make<never, PiRpcError>();
292 const exitDeferred = yield* Deferred.make<number, PiRpcError>();
293 let nextRequestId = 0;
294
295 const failTransport = Effect.fn("PiRpc.failTransport")(function* (error: PiRpcError) {
296 const claimed = yield* Deferred.fail(transportDown, error);
297 if (!claimed) return;
298 for (const [key, pending] of pendingRequests) {
299 pendingRequests.delete(key);
300 yield* Deferred.fail(pending.deferred, error);
301 }
302 yield* Queue.fail(outgoing, error);
303 yield* Queue.fail(events, error);
304 });
305
306 const routeRecord =
307 /* Protocol records and writes include streaming deltas; avoid a span per record. */
308 Effect.fnUntraced(function* (record: PiRpcRecord) {
309 if (record["type"] === "response" && typeof record["id"] === "string") {
310 const pending = pendingRequests.get(record["id"]);
311 if (pending !== undefined) {
312 pendingRequests.delete(record["id"]);
313 if (record["success"] === true) {
314 yield* Deferred.succeed(pending.deferred, record["data"]);
315 } else {
316 yield* Deferred.fail(
317 pending.deferred,
318 new PiRpcError({
319 operation: String(record["command"] ?? "request"),
320 detail: summarizePiError(record["error"]),
321 ...(record["error"] === undefined ? {} : { cause: record["error"] }),
322 }),
323 );
324 }
325 return;
326 }
327 }
328 yield* Queue.offer(events, record);
329 });
330
331 // Watch exit before reading stdout so immediate crashes populate exitDeferred for diagnosis.
332 yield* child.exitCode.pipe(
333 Effect.matchEffect({
334 onFailure: (cause) =>
335 Deferred.fail(exitDeferred, new PiRpcError({ operation: "exit", cause })),
336 onSuccess: (code) =>
337 Effect.suspend(() => {
338 childExited = true;
339 return Deferred.succeed(exitDeferred, Number(code));
340 }),
341 }),
342 Effect.forkIn(scope),
343 );
344
345 yield* Effect.gen(function* () {
346 const frame = makeJsonlFramer();
347 yield* child.stdout.pipe(
348 Stream.decodeText(),
349 Stream.runForEach((chunk) =>
350 Effect.gen(function* () {
351 const { lines, droppedLengths } = frame(chunk);
352 yield* logDroppedPiRecords(droppedLengths);
353 for (const line of lines) {
354 const record = parsePiRecord(line);
355 if (record === undefined) {
356 yield* Effect.logDebug("Dropping non-JSON pi stdout line.", {
357 lineLength: line.length,
358 });
359 continue;
360 }
361 yield* routeRecord(record);
362 }
363 }),
364 ),
365 );
366 const flushed = frame("\n");
367 yield* logDroppedPiRecords(flushed.droppedLengths);
368 for (const line of flushed.lines) {
369 const trailing = parsePiRecord(line);
370 if (trailing !== undefined) yield* routeRecord(trailing);
371 }
372 }).pipe(
373 Effect.matchCauseEffect({
374 onFailure: (cause) => failTransport(new PiRpcError({ operation: "read", cause })),
375 // The enclosing operation owns the span for this inline handler.
376 onSuccess: Effect.fnUntraced(function* () {
377 // Claim stdout-close diagnosis before waiting so broken stdin cannot replace the exit error.
378 diagnosingStdoutClose = true;
379 const polled = yield* Deferred.poll(exitDeferred);
380 const maybeExitCode = Option.isSome(polled)
381 ? yield* polled.value.pipe(
382 Effect.asSome,
383 Effect.orElseSucceed(() => Option.none<number>()),
384 )
385 : yield* Deferred.await(exitDeferred).pipe(
386 Effect.timeoutOption(Duration.millis(250)),
387 // Stdout-close waits need wall time; TestClock would strand Stop-with-restart without an exit.
388 Effect.provideService(Clock.Clock, Clock.Clock.defaultValue()),
389 Effect.orElseSucceed(() => Option.none<number>()),
390 );
391 return yield* failTransport(
392 new PiRpcError({
393 operation: "read",
394 detail: describePiStdoutClosure(
395 Option.isSome(maybeExitCode) ? maybeExitCode.value : undefined,
396 ),
397 }),
398 );
399 }),
400 }),
401 Effect.forkIn(scope),
402 );
403
404 yield* child.stderr.pipe(
405 Stream.decodeText(),
406 Stream.runForEach((chunk) =>
407 chunk.trim().length === 0
408 ? Effect.void
409 : // Log stderr length only; unbounded text may contain credentials or prompts.
410 Effect.logDebug("pi stderr", { stderrLength: chunk.length }),
411 ),
412 Effect.ignore,
413 Effect.forkIn(scope),
414 );
415
416 // Start the reader first so stdout-close diagnosis can win over broken-pipe stdin.
417 yield* Stream.fromQueue(outgoing).pipe(
418 Stream.run(child.stdin),
419 Effect.catchCause((cause) =>
420 diagnosingStdoutClose
421 ? Effect.void
422 : failTransport(new PiRpcError({ operation: "write", cause })),
423 ),
424 Effect.forkIn(scope),
425 );
426
427 const send =
428 /* Protocol records and writes include streaming deltas; avoid a span per record. */
429 Effect.fnUntraced(function* (record: PiRpcRecord): Effect.fn.Return<void, PiRpcError> {
430 const accepted = yield* Queue.offer(
431 outgoing,
432 new TextEncoder().encode(`${encodeJsonLine(record)}\n`),
433 );
434 if (!accepted) {
435 return yield* Deferred.await(transportDown);
436 }
437 });
438
439 const request = Effect.fn("PiRpc.request")(function* (
440 record: PiRpcRecord,
441 timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
442 ): Effect.fn.Return<unknown, PiRpcError | PiRpcTimeoutError> {
443 const id = `t3-${nextRequestId++}`;
444 const deferred = yield* Deferred.make<unknown, PiRpcError>();
445 pendingRequests.set(id, { deferred });
446 yield* send({ ...record, id }).pipe(
447 Effect.tapError(() => Effect.sync(() => pendingRequests.delete(id))),
448 );
449 return yield* Effect.raceFirst(Deferred.await(deferred), Deferred.await(transportDown)).pipe(
450 Effect.timeoutOrElse({
451 duration: Duration.millis(timeoutMs),
452 orElse: () =>
453 Effect.fail(
454 new PiRpcTimeoutError({
455 operation: String(record["type"] ?? "request"),
456 timeoutMs,
457 }),
458 ),
459 }),
460 Effect.onInterrupt(() => Effect.sync(() => pendingRequests.delete(id))),
461 Effect.onError(() => Effect.sync(() => pendingRequests.delete(id))),
462 );
463 });
464
465 return {
466 send,
467 request,
468 events,
469 exited: Deferred.await(exitDeferred),
470 terminate: failTransport(
471 new PiRpcError({ operation: "terminate", detail: "pi process was stopped" }),
472 ).pipe(Effect.andThen(terminateProcess), Effect.ignore, Effect.uninterruptible),
473 } satisfies PiRpcConnection;
474 });