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

main
ts 533 lines 18.1 KB
Raw
1 import * as Schema from "effect/Schema";
2 import { TrimmedNonEmptyString } from "./baseSchemas.ts";
3 import { ProviderInstanceId } from "./providerInstance.ts";
4
5 export const DEFAULT_TERMINAL_ID = "term-1";
6 export const DEFAULT_MAX_TERMINAL_BUFFER_BYTES = 512 * 1024;
7
8 const historyEncoder = new TextEncoder();
9 // A BOM at a retained chunk boundary is terminal data, not an encoding marker.
10 const historyDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
11
12 // libghostty-vt's parser states, merged where the same input takes them back to ground.
13 export const TERMINAL_SEQUENCE_GROUND = 0;
14 const SEQUENCE_ESCAPE = 1;
15 const SEQUENCE_ESCAPE_INTERMEDIATE = 2;
16 const SEQUENCE_CSI = 3;
17 const SEQUENCE_DCS = 4;
18 const SEQUENCE_SOS_PM_APC = 5;
19 const SEQUENCE_OSC = 6;
20
21 // Bits above the low three hold a high surrogate until its other half arrives.
22 function nextTerminalSequenceState(state: number, unit: number): number {
23 if (unit === 0x1b) return SEQUENCE_ESCAPE;
24 if (state === TERMINAL_SEQUENCE_GROUND || unit === 0x18 || unit === 0x1a) {
25 return TERMINAL_SEQUENCE_GROUND;
26 }
27 let mode = state & 7;
28 if (unit < 0x80) {
29 switch (mode) {
30 case SEQUENCE_ESCAPE:
31 if (unit < 0x20 || unit === 0x7f) return mode;
32 if (unit < 0x30) return SEQUENCE_ESCAPE_INTERMEDIATE;
33 if (unit === 0x5b) return SEQUENCE_CSI;
34 if (unit === 0x5d) return SEQUENCE_OSC;
35 if (unit === 0x50) return SEQUENCE_DCS;
36 return unit === 0x58 || unit === 0x5e || unit === 0x5f
37 ? SEQUENCE_SOS_PM_APC
38 : TERMINAL_SEQUENCE_GROUND;
39 case SEQUENCE_ESCAPE_INTERMEDIATE:
40 return unit >= 0x30 && unit !== 0x7f ? TERMINAL_SEQUENCE_GROUND : mode;
41 case SEQUENCE_CSI:
42 return unit >= 0x40 && unit !== 0x7f ? TERMINAL_SEQUENCE_GROUND : mode;
43 case SEQUENCE_OSC:
44 return unit === 0x07 ? TERMINAL_SEQUENCE_GROUND : mode;
45 default:
46 return mode;
47 }
48 }
49 if (mode === SEQUENCE_OSC) return mode;
50 if (unit >= 0xd800 && unit <= 0xdbff) return mode | (unit << 3);
51 let codePoint = unit;
52 if (unit >= 0xdc00 && unit <= 0xdfff) {
53 if (state < 8) return mode;
54 codePoint = 0x10000 + (((state >> 3) - 0xd800) << 10) + (unit - 0xdc00);
55 }
56 // Outside ground and OSC the parser reads UTF-8 bytes one at a time, so a continuation
57 // byte in 0x80-0x9F acts as a C1 control: most end the sequence, five start another.
58 for (let shift = codePoint > 0xffff ? 12 : codePoint > 0x7ff ? 6 : 0; shift >= 0; shift -= 6) {
59 const byte = 0x80 | ((codePoint >> shift) & 0x3f);
60 if (byte >= 0xa0) continue;
61 if (byte === 0x9d) return SEQUENCE_OSC;
62 if (byte === 0x90) mode = SEQUENCE_DCS;
63 else if (byte === 0x9b) mode = SEQUENCE_CSI;
64 else if (byte === 0x98 || byte >= 0x9e) mode = SEQUENCE_SOS_PM_APC;
65 else return TERMINAL_SEQUENCE_GROUND;
66 }
67 return mode;
68 }
69
70 /** The parser state after `text.slice(start, end)`, for a terminal that entered it in `state`. */
71 export function terminalSequenceStateAfter(
72 state: number,
73 text: string,
74 start = 0,
75 end = text.length,
76 ): number {
77 if (end <= start) return state;
78 // ESC enters the escape state from every state, so only what follows the last one matters.
79 const escape = text.lastIndexOf("\u001b", end - 1);
80 if (escape >= start) {
81 state = SEQUENCE_ESCAPE;
82 start = escape + 1;
83 }
84 for (let index = start; index < end && state !== TERMINAL_SEQUENCE_GROUND; index += 1) {
85 state = nextTerminalSequenceState(state, text.charCodeAt(index));
86 }
87 return state;
88 }
89
90 /** Where in `text` a terminal that entered it in `state` is first back in ground state. */
91 export function terminalSequenceEnd(state: number, text: string): number {
92 let index = 0;
93 while (state !== TERMINAL_SEQUENCE_GROUND && index < text.length) {
94 state = nextTerminalSequenceState(state, text.charCodeAt(index));
95 index += 1;
96 }
97 return index;
98 }
99
100 /**
101 * The final `maxBytes` of UTF-8 a client retains, starting at a code point boundary and
102 * outside any control sequence the cut went through.
103 */
104 export function retainedTerminalHistory(history: string, maxBytes: number): string {
105 if (maxBytes <= 0) {
106 return "";
107 }
108
109 const encoded = historyEncoder.encode(history);
110 if (encoded.byteLength <= maxBytes) {
111 return history;
112 }
113
114 let start = encoded.byteLength - maxBytes;
115 while (start < encoded.length) {
116 const byte = encoded[start];
117 if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {
118 break;
119 }
120 start += 1;
121 }
122
123 const retained = historyDecoder.decode(encoded.subarray(start));
124 const state = terminalSequenceStateAfter(
125 TERMINAL_SEQUENCE_GROUND,
126 history,
127 0,
128 history.length - retained.length,
129 );
130 return retained.slice(terminalSequenceEnd(state, retained));
131 }
132
133 const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
134 const TerminalColsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).check(
135 Schema.isLessThanOrEqualTo(1000),
136 );
137 const TerminalRowsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).check(
138 Schema.isLessThanOrEqualTo(500),
139 );
140 const TerminalIdSchema = TrimmedNonEmptyStringSchema.check(Schema.isMaxLength(128));
141 const TerminalEnvKeySchema = Schema.String.check(
142 Schema.isPattern(/^[A-Za-z_][A-Za-z0-9_]*$/),
143 ).check(Schema.isMaxLength(128));
144 const TerminalEnvValueSchema = Schema.String.check(Schema.isMaxLength(8_192));
145 const TerminalEnvSchema = Schema.Record(TerminalEnvKeySchema, TerminalEnvValueSchema).check(
146 Schema.isMaxProperties(128),
147 );
148
149 export const TerminalThreadInput = Schema.Struct({
150 threadId: TrimmedNonEmptyStringSchema,
151 });
152 export type TerminalThreadInput = typeof TerminalThreadInput.Type;
153
154 // Terminal ids are client-chosen; the server never allocates them.
155 const TerminalSessionInput = Schema.Struct({
156 ...TerminalThreadInput.fields,
157 terminalId: TerminalIdSchema,
158 });
159 export type TerminalSessionInput = Schema.Codec.Encoded<typeof TerminalSessionInput>;
160
161 export const TerminalOpenInput = Schema.Struct({
162 ...TerminalSessionInput.fields,
163 cwd: TrimmedNonEmptyStringSchema,
164 worktreePath: Schema.optional(Schema.NullOr(TrimmedNonEmptyStringSchema)),
165 cols: Schema.optional(TerminalColsSchema),
166 rows: Schema.optional(TerminalRowsSchema),
167 env: Schema.optional(TerminalEnvSchema),
168 providerInstanceId: Schema.optional(ProviderInstanceId),
169 stopOnSettle: Schema.optional(Schema.Boolean),
170 });
171 export type TerminalOpenInput = typeof TerminalOpenInput.Type;
172
173 export const TerminalAttachInput = Schema.Struct({
174 ...TerminalSessionInput.fields,
175 cwd: Schema.optional(TrimmedNonEmptyStringSchema),
176 worktreePath: Schema.optional(Schema.NullOr(TrimmedNonEmptyStringSchema)),
177 cols: Schema.optional(TerminalColsSchema),
178 rows: Schema.optional(TerminalRowsSchema),
179 env: Schema.optional(TerminalEnvSchema),
180 providerInstanceId: Schema.optional(ProviderInstanceId),
181 stopOnSettle: Schema.optional(Schema.Boolean),
182 restartIfNotRunning: Schema.optional(Schema.Boolean),
183 // Resubscriptions preserve stopped terminals; unknown IDs recover after a server restart.
184 resume: Schema.optional(Schema.Boolean),
185 // Snapshots carry only the history a client this bounded keeps; older servers ignore it.
186 maxHistoryBytes: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
187 });
188 export type TerminalAttachInput = typeof TerminalAttachInput.Type;
189
190 export const TerminalObserveInput = TerminalSessionInput;
191 export type TerminalObserveInput = Schema.Codec.Encoded<typeof TerminalObserveInput>;
192
193 /** Longest `data` one `terminal.write` carries, in UTF-16 code units. */
194 export const TERMINAL_WRITE_MAX_LENGTH = 65_536;
195
196 export const TerminalWriteInput = Schema.Struct({
197 ...TerminalSessionInput.fields,
198 data: Schema.String.check(Schema.isNonEmpty()).check(
199 Schema.isMaxLength(TERMINAL_WRITE_MAX_LENGTH),
200 ),
201 // `data` holds one byte per UTF-16 code unit; older servers write it as UTF-8 text.
202 binary: Schema.optionalKey(Schema.Boolean),
203 // A renderer's answer to a terminal query (DA, DSR, DECRQM). Every attached renderer
204 // answers, so the server passes on one viewer's replies; older servers ignore it.
205 reply: Schema.optionalKey(Schema.Boolean),
206 });
207 export type TerminalWriteInput = Schema.Codec.Encoded<typeof TerminalWriteInput>;
208
209 /** Splits input into writes that fit `TerminalWriteInput`, never between a surrogate pair. */
210 export function chunkTerminalWrite(data: string): ReadonlyArray<string> {
211 const chunks: string[] = [];
212 let start = 0;
213 while (start < data.length) {
214 let end = Math.min(start + TERMINAL_WRITE_MAX_LENGTH, data.length);
215 const last = data.charCodeAt(end - 1);
216 if (end < data.length && last >= 0xd800 && last <= 0xdbff) {
217 end -= 1;
218 }
219 chunks.push(data.slice(start, end));
220 start = end;
221 }
222 return chunks;
223 }
224
225 export const TerminalResizeInput = Schema.Struct({
226 ...TerminalSessionInput.fields,
227 cols: TerminalColsSchema,
228 rows: TerminalRowsSchema,
229 });
230 export type TerminalResizeInput = Schema.Codec.Encoded<typeof TerminalResizeInput>;
231
232 export const TerminalClearInput = TerminalSessionInput;
233 export type TerminalClearInput = Schema.Codec.Encoded<typeof TerminalClearInput>;
234
235 export const TerminalCloseInput = Schema.Struct({
236 ...TerminalThreadInput.fields,
237 terminalId: Schema.optional(TerminalIdSchema),
238 deleteHistory: Schema.optional(Schema.Boolean),
239 });
240 export type TerminalCloseInput = typeof TerminalCloseInput.Type;
241
242 export const TerminalSessionStatus = Schema.Literals(["starting", "running", "exited", "error"]);
243 export type TerminalSessionStatus = typeof TerminalSessionStatus.Type;
244
245 export const TerminalSessionSnapshot = Schema.Struct({
246 threadId: Schema.String.check(Schema.isNonEmpty()),
247 terminalId: Schema.String.check(Schema.isNonEmpty()),
248 cwd: Schema.String.check(Schema.isNonEmpty()),
249 worktreePath: Schema.NullOr(TrimmedNonEmptyStringSchema),
250 status: TerminalSessionStatus,
251 pid: Schema.NullOr(Schema.Int.check(Schema.isGreaterThan(0))),
252 history: Schema.String,
253 exitCode: Schema.NullOr(Schema.Int),
254 exitSignal: Schema.NullOr(Schema.Int),
255 label: Schema.String.check(Schema.isMaxLength(128)),
256 updatedAt: Schema.String,
257 sequence: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
258 // The PTY grid every renderer of this terminal should draw; absent from older servers.
259 cols: Schema.optional(TerminalColsSchema),
260 rows: Schema.optional(TerminalRowsSchema),
261 // Why the shell failed to start, kept so later attachments can show it.
262 error: Schema.optional(Schema.String.check(Schema.isNonEmpty())),
263 });
264 export type TerminalSessionSnapshot = typeof TerminalSessionSnapshot.Type;
265
266 export const TerminalSummary = Schema.Struct({
267 threadId: Schema.String.check(Schema.isNonEmpty()),
268 terminalId: Schema.String.check(Schema.isNonEmpty()),
269 cwd: Schema.String.check(Schema.isNonEmpty()),
270 worktreePath: Schema.NullOr(TrimmedNonEmptyStringSchema),
271 status: TerminalSessionStatus,
272 pid: Schema.NullOr(Schema.Int.check(Schema.isGreaterThan(0))),
273 exitCode: Schema.NullOr(Schema.Int),
274 exitSignal: Schema.NullOr(Schema.Int),
275 hasRunningSubprocess: Schema.Boolean,
276 label: Schema.String.check(Schema.isMaxLength(128)),
277 updatedAt: Schema.String,
278 });
279 export type TerminalSummary = typeof TerminalSummary.Type;
280
281 const TerminalMetadataSnapshotEvent = Schema.Struct({
282 type: Schema.Literal("snapshot"),
283 terminals: Schema.Array(TerminalSummary),
284 managerId: Schema.optional(Schema.String),
285 });
286
287 const TerminalMetadataUpsertEvent = Schema.Struct({
288 type: Schema.Literal("upsert"),
289 terminal: TerminalSummary,
290 });
291
292 const TerminalMetadataRemoveEvent = Schema.Struct({
293 type: Schema.Literal("remove"),
294 threadId: Schema.String.check(Schema.isNonEmpty()),
295 terminalId: Schema.String.check(Schema.isNonEmpty()),
296 });
297
298 export const TerminalMetadataStreamEvent = Schema.Union([
299 TerminalMetadataSnapshotEvent,
300 TerminalMetadataUpsertEvent,
301 TerminalMetadataRemoveEvent,
302 ]);
303 export type TerminalMetadataStreamEvent = typeof TerminalMetadataStreamEvent.Type;
304
305 const TerminalEventBaseSchema = Schema.Struct({
306 threadId: Schema.String.check(Schema.isNonEmpty()),
307 terminalId: Schema.String.check(Schema.isNonEmpty()),
308 sequence: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
309 });
310
311 const TerminalStartedEvent = Schema.Struct({
312 ...TerminalEventBaseSchema.fields,
313 type: Schema.Literal("started"),
314 snapshot: TerminalSessionSnapshot,
315 });
316
317 const TerminalOutputEvent = Schema.Struct({
318 ...TerminalEventBaseSchema.fields,
319 type: Schema.Literal("output"),
320 data: Schema.String,
321 });
322
323 const TerminalExitedEvent = Schema.Struct({
324 ...TerminalEventBaseSchema.fields,
325 type: Schema.Literal("exited"),
326 exitCode: Schema.NullOr(Schema.Int),
327 exitSignal: Schema.NullOr(Schema.Int),
328 });
329
330 const TerminalClosedEvent = Schema.Struct({
331 ...TerminalEventBaseSchema.fields,
332 type: Schema.Literal("closed"),
333 });
334
335 const TerminalErrorEvent = Schema.Struct({
336 ...TerminalEventBaseSchema.fields,
337 type: Schema.Literal("error"),
338 message: Schema.String.check(Schema.isNonEmpty()),
339 });
340
341 const TerminalClearedEvent = Schema.Struct({
342 ...TerminalEventBaseSchema.fields,
343 type: Schema.Literal("cleared"),
344 });
345
346 const TerminalRestartedEvent = Schema.Struct({
347 ...TerminalEventBaseSchema.fields,
348 type: Schema.Literal("restarted"),
349 snapshot: TerminalSessionSnapshot,
350 });
351
352 const TerminalActivityEvent = Schema.Struct({
353 ...TerminalEventBaseSchema.fields,
354 type: Schema.Literal("activity"),
355 hasRunningSubprocess: Schema.Boolean,
356 label: Schema.String.check(Schema.isMaxLength(128)),
357 // Shared PTY grid changes ride on activity because older clients reject unknown event types.
358 cols: Schema.optional(TerminalColsSchema),
359 rows: Schema.optional(TerminalRowsSchema),
360 });
361
362 export const TerminalEvent = Schema.Union([
363 TerminalStartedEvent,
364 TerminalOutputEvent,
365 TerminalExitedEvent,
366 TerminalClosedEvent,
367 TerminalErrorEvent,
368 TerminalClearedEvent,
369 TerminalRestartedEvent,
370 TerminalActivityEvent,
371 ]);
372 export type TerminalEvent = typeof TerminalEvent.Type;
373
374 const TerminalAttachSnapshotEvent = Schema.Struct({
375 type: Schema.Literal("snapshot"),
376 snapshot: TerminalSessionSnapshot,
377 });
378
379 export const TerminalAttachStreamEvent = Schema.Union([
380 TerminalAttachSnapshotEvent,
381 TerminalOutputEvent,
382 TerminalExitedEvent,
383 TerminalClosedEvent,
384 TerminalErrorEvent,
385 TerminalClearedEvent,
386 TerminalRestartedEvent,
387 TerminalActivityEvent,
388 ]);
389 export type TerminalAttachStreamEvent = typeof TerminalAttachStreamEvent.Type;
390
391 export class TerminalCwdNotFoundError extends Schema.TaggedError<TerminalCwdNotFoundError>()(
392 "TerminalCwdNotFoundError",
393 {
394 cwd: Schema.String,
395 },
396 ) {
397 override get message() {
398 return `Terminal folder does not exist: ${this.cwd}. Restore the folder at this path before retrying.`;
399 }
400 }
401
402 export class TerminalCwdNotDirectoryError extends Schema.TaggedError<TerminalCwdNotDirectoryError>()(
403 "TerminalCwdNotDirectoryError",
404 {
405 cwd: Schema.String,
406 },
407 ) {
408 override get message() {
409 return `Terminal cwd is not a directory: ${this.cwd}`;
410 }
411 }
412
413 export class TerminalCwdStatError extends Schema.TaggedError<TerminalCwdStatError>()(
414 "TerminalCwdStatError",
415 {
416 cwd: Schema.String,
417 cause: Schema.Defect(),
418 },
419 ) {
420 override get message() {
421 return `Failed to access terminal cwd: ${this.cwd}`;
422 }
423 }
424
425 export const TerminalCwdError = Schema.Union([
426 TerminalCwdNotFoundError,
427 TerminalCwdNotDirectoryError,
428 TerminalCwdStatError,
429 ]);
430 export type TerminalCwdError = typeof TerminalCwdError.Type;
431
432 export class TerminalHistoryError extends Schema.TaggedError<TerminalHistoryError>()(
433 "TerminalHistoryError",
434 {
435 operation: Schema.Literals(["read", "truncate", "migrate"]),
436 threadId: Schema.String,
437 terminalId: Schema.String,
438 cause: Schema.optional(Schema.Defect()),
439 },
440 ) {
441 override get message() {
442 return `Failed to ${this.operation} terminal history for thread: ${this.threadId}, terminal: ${this.terminalId}`;
443 }
444 }
445
446 export class TerminalSessionLookupError extends Schema.TaggedError<TerminalSessionLookupError>()(
447 "TerminalSessionLookupError",
448 {
449 threadId: Schema.String,
450 terminalId: Schema.String,
451 },
452 ) {
453 override get message() {
454 return `Unknown terminal thread: ${this.threadId}, terminal: ${this.terminalId}`;
455 }
456 }
457
458 export class TerminalProviderInstanceNotFoundError extends Schema.TaggedError<TerminalProviderInstanceNotFoundError>()(
459 "TerminalProviderInstanceNotFoundError",
460 {
461 providerInstanceId: ProviderInstanceId,
462 },
463 ) {
464 override get message() {
465 return `Provider instance is not available: ${this.providerInstanceId}`;
466 }
467 }
468
469 export class TerminalProviderEnvironmentError extends Schema.TaggedError<TerminalProviderEnvironmentError>()(
470 "TerminalProviderEnvironmentError",
471 {
472 providerInstanceId: ProviderInstanceId,
473 cause: Schema.Defect(),
474 },
475 ) {
476 override get message() {
477 return `Could not prepare the terminal environment for provider instance: ${this.providerInstanceId}`;
478 }
479 }
480
481 export class TerminalNotRunningError extends Schema.TaggedError<TerminalNotRunningError>()(
482 "TerminalNotRunningError",
483 {
484 threadId: Schema.String,
485 terminalId: Schema.String,
486 },
487 ) {
488 override get message() {
489 return `Terminal is not running for thread: ${this.threadId}, terminal: ${this.terminalId}`;
490 }
491 }
492
493 export class TerminalWriteError extends Schema.TaggedError<TerminalWriteError>()(
494 "TerminalWriteError",
495 {
496 threadId: Schema.String,
497 terminalId: Schema.String,
498 terminalPid: Schema.Number,
499 cause: Schema.Defect(),
500 },
501 ) {
502 override get message() {
503 return `Failed to write to terminal for thread: ${this.threadId}, terminal: ${this.terminalId}, PID: ${this.terminalPid}`;
504 }
505 }
506
507 export class TerminalResizeError extends Schema.TaggedError<TerminalResizeError>()(
508 "TerminalResizeError",
509 {
510 threadId: Schema.String,
511 terminalId: Schema.String,
512 terminalPid: Schema.Number,
513 cols: TerminalColsSchema,
514 rows: TerminalRowsSchema,
515 cause: Schema.Defect(),
516 },
517 ) {
518 override get message() {
519 return `Failed to resize terminal for thread: ${this.threadId}, terminal: ${this.terminalId}, PID: ${this.terminalPid} to ${this.cols}x${this.rows}`;
520 }
521 }
522
523 export const TerminalError = Schema.Union([
524 TerminalCwdError,
525 TerminalHistoryError,
526 TerminalSessionLookupError,
527 TerminalProviderInstanceNotFoundError,
528 TerminalProviderEnvironmentError,
529 TerminalNotRunningError,
530 TerminalWriteError,
531 TerminalResizeError,
532 ]);
533 export type TerminalError = typeof TerminalError.Type;