@pyrokine/mcp-ssh 2.4.0 → 2.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -6,8 +6,14 @@ export declare const DEFAULT_OPERATION_READ_BYTES: number;
6
6
  export declare const HARD_OPERATION_READ_BYTES: number;
7
7
  export declare const DEFAULT_OPERATION_RETENTION_MS: number;
8
8
  export declare const MAX_OPERATION_RETENTION_MS: number;
9
+ export declare const DEFAULT_OPERATION_START_TIMEOUT_MS = 30000;
10
+ export declare const MAX_OPERATION_START_TIMEOUT_MS = 600000;
11
+ export declare class OperationStartError extends Error {
12
+ readonly details: Record<string, unknown>;
13
+ constructor(message: string, details: Record<string, unknown>);
14
+ }
9
15
  export interface OperationDependencies {
10
- openStream(alias: string, command: string, marker: string, options: OperationStartOptions): Promise<ClientChannel>;
16
+ openStream(alias: string, command: string, marker: string, options: OperationStartOptions, adopt: (stream: ClientChannel) => void): Promise<void>;
11
17
  cancelRemote(alias: string, pid: number, marker: string, processGroup: boolean, options: OperationStartOptions): Promise<{
12
18
  success: boolean;
13
19
  error?: string;
@@ -17,6 +23,7 @@ export declare class OperationManager {
17
23
  private readonly dependencies;
18
24
  private readonly now;
19
25
  private readonly operations;
26
+ private readonly pendingStarts;
20
27
  private readonly sweeper;
21
28
  constructor(dependencies: OperationDependencies, now?: () => number);
22
29
  start(alias: string, command: string, options?: OperationStartOptions): Promise<OperationInfo>;
@@ -36,17 +43,17 @@ export declare class OperationManager {
36
43
  private finishStreamError;
37
44
  private finishStreamClose;
38
45
  private consumeMarker;
46
+ private failMarker;
47
+ private flushMarkerBuffer;
48
+ private appendStderr;
39
49
  private appendOutput;
40
50
  private finish;
41
51
  private info;
52
+ private clearPendingStart;
42
53
  private requireOperation;
43
54
  private normalizeMaxOutputBytes;
44
55
  private normalizeReadBytes;
45
56
  private normalizeRetentionMs;
57
+ private normalizeStartTimeoutMs;
46
58
  private normalizeOffset;
47
- private ensureUtf8Boundary;
48
- private utf8SafeEnd;
49
- private trimIncompleteUtf8Sequence;
50
- private utf8SequenceLength;
51
- private isUtf8ContinuationByte;
52
59
  }
@@ -1,16 +1,28 @@
1
1
  import { randomBytes, randomUUID } from 'node:crypto';
2
+ import { ensureUtf8Boundary, utf8SafeEnd } from './utf8.js';
2
3
  export const DEFAULT_OPERATION_MAX_OUTPUT_BYTES = 1024 * 1024;
3
4
  export const HARD_OPERATION_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
4
5
  export const DEFAULT_OPERATION_READ_BYTES = 64 * 1024;
5
6
  export const HARD_OPERATION_READ_BYTES = 1024 * 1024;
6
7
  export const DEFAULT_OPERATION_RETENTION_MS = 60 * 60_000;
7
8
  export const MAX_OPERATION_RETENTION_MS = 24 * 60 * 60_000;
9
+ export const DEFAULT_OPERATION_START_TIMEOUT_MS = 30_000;
10
+ export const MAX_OPERATION_START_TIMEOUT_MS = 600_000;
11
+ export class OperationStartError extends Error {
12
+ details;
13
+ constructor(message, details) {
14
+ super(message);
15
+ this.details = details;
16
+ this.name = 'OperationStartError';
17
+ }
18
+ }
8
19
  const MARKER_PREFIX = '__MCP_SSH_OPERATION__';
9
20
  const MARKER_LINE_LIMIT = 512;
10
21
  export class OperationManager {
11
22
  dependencies;
12
23
  now;
13
24
  operations = new Map();
25
+ pendingStarts = new Map();
14
26
  sweeper;
15
27
  constructor(dependencies, now = Date.now) {
16
28
  this.dependencies = dependencies;
@@ -19,11 +31,20 @@ export class OperationManager {
19
31
  this.sweeper.unref?.();
20
32
  }
21
33
  async start(alias, command, options = {}) {
34
+ const pendingOperationId = this.pendingStarts.get(alias);
35
+ if (pendingOperationId) {
36
+ throw new OperationStartError(`Alias '${alias}' already has an operation start awaiting SSH channel setup`, {
37
+ alias,
38
+ operationId: pendingOperationId,
39
+ retryable: true,
40
+ suggestion: '等待当前 operation start 完成,或断开该 alias 以释放未完成的 SSH channel request',
41
+ });
42
+ }
22
43
  const operationId = `op_${randomUUID()}`;
23
44
  const marker = randomBytes(32).toString('hex');
24
45
  const maxOutputBytes = this.normalizeMaxOutputBytes(options.maxOutputBytes);
25
46
  const retentionMs = this.normalizeRetentionMs(options.retentionMs);
26
- const stream = await this.dependencies.openStream(alias, command, marker, options);
47
+ const startTimeoutMs = this.normalizeStartTimeoutMs(options.startTimeoutMs);
27
48
  const record = {
28
49
  operationId,
29
50
  alias,
@@ -50,11 +71,75 @@ export class OperationManager {
50
71
  stderrTruncated: false,
51
72
  maxOutputBytes,
52
73
  markerBuffer: Buffer.alloc(0),
53
- stream,
54
- options: { ...options, maxOutputBytes, retentionMs },
74
+ options: { ...options, maxOutputBytes, retentionMs, startTimeoutMs },
55
75
  };
56
76
  this.operations.set(operationId, record);
57
- this.attachStream(record);
77
+ this.pendingStarts.set(alias, operationId);
78
+ const opening = this.dependencies.openStream(alias, command, marker, record.options, (stream) => {
79
+ if (record.stream) {
80
+ stream.destroy();
81
+ throw new Error('Operation stream was adopted more than once');
82
+ }
83
+ if (record.finishedAt !== null) {
84
+ stream.destroy();
85
+ throw new Error('Operation stream arrived after operation start finished');
86
+ }
87
+ record.stream = stream;
88
+ this.attachStream(record, stream);
89
+ });
90
+ void opening.then(() => this.clearPendingStart(alias, operationId), () => this.clearPendingStart(alias, operationId));
91
+ let timer;
92
+ try {
93
+ await Promise.race([
94
+ opening,
95
+ new Promise((_resolve, reject) => {
96
+ timer = setTimeout(() => {
97
+ reject(new OperationStartError(`Operation start timed out after ${startTimeoutMs}ms`, {
98
+ alias,
99
+ operationId,
100
+ startTimeoutMs,
101
+ status: 'unknown',
102
+ retryable: false,
103
+ suggestion: 'SSH channel request 状态无法确认;使用 ssh_operation_status 查询记录,' +
104
+ '必要时用 ssh_disconnect 释放底层 pending channel',
105
+ }));
106
+ }, startTimeoutMs);
107
+ }),
108
+ ]);
109
+ }
110
+ catch (error) {
111
+ if (record.finishedAt === null) {
112
+ record.status = error instanceof OperationStartError ? 'unknown' : 'failed';
113
+ record.error = error instanceof Error ? error.message : String(error);
114
+ this.finish(record);
115
+ }
116
+ record.stream?.destroy();
117
+ if (error instanceof OperationStartError) {
118
+ throw error;
119
+ }
120
+ throw new OperationStartError(record.error ?? 'Operation start failed', {
121
+ alias,
122
+ operationId,
123
+ status: record.status,
124
+ retryable: false,
125
+ });
126
+ }
127
+ finally {
128
+ if (timer) {
129
+ clearTimeout(timer);
130
+ }
131
+ }
132
+ if (!record.stream) {
133
+ record.status = 'failed';
134
+ record.error = 'Operation stream was not adopted';
135
+ this.finish(record);
136
+ throw new OperationStartError(record.error, {
137
+ alias,
138
+ operationId,
139
+ status: record.status,
140
+ retryable: false,
141
+ });
142
+ }
58
143
  return this.info(record);
59
144
  }
60
145
  status(operationId) {
@@ -65,21 +150,25 @@ export class OperationManager {
65
150
  const maxReadBytes = this.normalizeReadBytes(options.maxBytes);
66
151
  const stdoutOffset = this.normalizeOffset(options.stdoutOffset, record.stdout.length, 'stdoutOffset');
67
152
  const stderrOffset = this.normalizeOffset(options.stderrOffset, record.stderr.length, 'stderrOffset');
68
- this.ensureUtf8Boundary(record.stdout, stdoutOffset, 'stdoutOffset');
69
- this.ensureUtf8Boundary(record.stderr, stderrOffset, 'stderrOffset');
70
- const stdoutEnd = this.utf8SafeEnd(record.stdout, stdoutOffset, Math.min(record.stdout.length, stdoutOffset + maxReadBytes), 'stdout');
153
+ ensureUtf8Boundary(record.stdout, stdoutOffset, 'stdoutOffset');
154
+ ensureUtf8Boundary(record.stderr, stderrOffset, 'stderrOffset');
155
+ const stdoutRequestedEnd = Math.min(record.stdout.length, stdoutOffset + maxReadBytes);
156
+ const stdoutEnd = utf8SafeEnd(record.stdout, stdoutOffset, stdoutRequestedEnd, 'stdout');
71
157
  const stdout = record.stdout.subarray(stdoutOffset, stdoutEnd);
158
+ const nextStdoutOffset = record.stdoutTruncated && stdoutRequestedEnd === record.stdout.length ? stdoutRequestedEnd : stdoutEnd;
72
159
  const remaining = maxReadBytes - stdout.length;
73
- const stderrEnd = this.utf8SafeEnd(record.stderr, stderrOffset, Math.min(record.stderr.length, stderrOffset + remaining), 'stderr');
160
+ const stderrRequestedEnd = Math.min(record.stderr.length, stderrOffset + remaining);
161
+ const stderrEnd = utf8SafeEnd(record.stderr, stderrOffset, stderrRequestedEnd, 'stderr');
74
162
  const stderr = record.stderr.subarray(stderrOffset, stderrEnd);
163
+ const nextStderrOffset = record.stderrTruncated && stderrRequestedEnd === record.stderr.length ? stderrRequestedEnd : stderrEnd;
75
164
  return {
76
165
  ...this.info(record),
77
166
  stdout: stdout.toString('utf8'),
78
167
  stderr: stderr.toString('utf8'),
79
168
  stdoutOffset,
80
169
  stderrOffset,
81
- nextStdoutOffset: stdoutEnd,
82
- nextStderrOffset: stderrEnd,
170
+ nextStdoutOffset,
171
+ nextStderrOffset,
83
172
  readBytes: stdout.length + stderr.length,
84
173
  maxReadBytes,
85
174
  };
@@ -143,6 +232,7 @@ export class OperationManager {
143
232
  .map((record) => this.info(record));
144
233
  }
145
234
  markAliasDisconnected(alias) {
235
+ this.pendingStarts.delete(alias);
146
236
  for (const record of this.operations.values()) {
147
237
  if (record.alias === alias && (record.status === 'starting' || record.status === 'running')) {
148
238
  record.status = 'unknown';
@@ -162,22 +252,22 @@ export class OperationManager {
162
252
  close() {
163
253
  clearInterval(this.sweeper);
164
254
  }
165
- attachStream(record) {
166
- record.stream.on('data', (data) => {
255
+ attachStream(record, stream) {
256
+ stream.on('data', (data) => {
167
257
  record.stdoutBytes += data.length;
168
258
  this.appendOutput(record, 'stdout', data);
169
259
  });
170
- record.stream.stderr.on('data', (data) => {
260
+ stream.stderr.on('data', (data) => {
171
261
  this.consumeMarker(record, data);
172
262
  });
173
- record.stream.on('error', (error) => {
263
+ stream.on('error', (error) => {
174
264
  if (record.cancelInFlight) {
175
265
  record.pendingTermination ??= { type: 'error', error };
176
266
  return;
177
267
  }
178
268
  this.finishStreamError(record, error);
179
269
  });
180
- record.stream.on('close', (code, signal) => {
270
+ stream.on('close', (code, signal) => {
181
271
  const close = { type: 'close', code, signal: signal ?? null };
182
272
  if (record.cancelInFlight) {
183
273
  record.pendingTermination ??= close;
@@ -202,6 +292,7 @@ export class OperationManager {
202
292
  if (record.status === 'unknown' || record.finishedAt !== null) {
203
293
  return;
204
294
  }
295
+ this.flushMarkerBuffer(record);
205
296
  record.status = 'failed';
206
297
  record.error = error.message;
207
298
  this.finish(record);
@@ -212,12 +303,13 @@ export class OperationManager {
212
303
  }
213
304
  record.exitCode = code;
214
305
  record.signal = signal;
306
+ this.flushMarkerBuffer(record);
215
307
  if (record.cancelRequested) {
216
308
  record.status = 'cancelled';
217
309
  }
218
310
  else if (!record.markerVerified) {
219
311
  record.status = 'failed';
220
- record.error = 'Remote operation exited before its marker was verified';
312
+ record.error ??= 'Remote operation exited before its marker was verified';
221
313
  }
222
314
  else {
223
315
  record.status = code === 0 ? 'completed' : 'failed';
@@ -225,49 +317,94 @@ export class OperationManager {
225
317
  this.finish(record);
226
318
  }
227
319
  consumeMarker(record, data) {
228
- if (record.markerVerified) {
229
- record.stderrBytes += data.length;
230
- this.appendOutput(record, 'stderr', data);
320
+ if (record.markerVerified || record.status !== 'starting') {
321
+ this.appendStderr(record, data);
231
322
  return;
232
323
  }
324
+ const markerPrefix = Buffer.from(MARKER_PREFIX);
233
325
  record.markerBuffer = Buffer.concat([record.markerBuffer, data]);
234
- const newline = record.markerBuffer.indexOf(0x0a);
235
- if (newline < 0) {
236
- if (record.markerBuffer.length > MARKER_LINE_LIMIT) {
237
- record.status = 'failed';
238
- record.error = 'Remote operation marker exceeded the allowed length';
239
- record.stderrBytes += record.markerBuffer.length;
240
- this.appendOutput(record, 'stderr', record.markerBuffer);
326
+ while (!record.markerVerified) {
327
+ const markerIndex = record.markerBuffer.indexOf(markerPrefix);
328
+ if (markerIndex > 0) {
329
+ this.appendStderr(record, record.markerBuffer.subarray(0, markerIndex));
330
+ record.markerBuffer = record.markerBuffer.subarray(markerIndex);
331
+ continue;
332
+ }
333
+ if (markerIndex < 0) {
334
+ const newline = record.markerBuffer.indexOf(0x0a);
335
+ if (newline >= 0) {
336
+ this.appendStderr(record, record.markerBuffer.subarray(0, newline + 1));
337
+ record.markerBuffer = record.markerBuffer.subarray(newline + 1);
338
+ continue;
339
+ }
340
+ const retainedBytes = Math.min(record.markerBuffer.length, markerPrefix.length - 1);
341
+ const streamedBytes = record.markerBuffer.length - retainedBytes;
342
+ if (streamedBytes > 0) {
343
+ this.appendStderr(record, record.markerBuffer.subarray(0, streamedBytes));
344
+ record.markerBuffer = record.markerBuffer.subarray(streamedBytes);
345
+ }
346
+ return;
347
+ }
348
+ const newline = record.markerBuffer.indexOf(0x0a);
349
+ if (newline < 0) {
350
+ if (record.markerBuffer.length > MARKER_LINE_LIMIT) {
351
+ this.appendStderr(record, record.markerBuffer);
352
+ record.markerBuffer = Buffer.alloc(0);
353
+ this.failMarker(record, 'Remote operation marker exceeded the allowed length');
354
+ }
355
+ return;
356
+ }
357
+ const lineBytes = record.markerBuffer.subarray(0, newline + 1);
358
+ const line = record.markerBuffer.subarray(0, newline).toString('utf8').trim();
359
+ record.markerBuffer = record.markerBuffer.subarray(newline + 1);
360
+ if (newline > MARKER_LINE_LIMIT) {
361
+ this.appendStderr(record, lineBytes);
362
+ this.appendStderr(record, record.markerBuffer);
241
363
  record.markerBuffer = Buffer.alloc(0);
364
+ this.failMarker(record, 'Remote operation marker exceeded the allowed length');
365
+ return;
242
366
  }
243
- return;
244
- }
245
- const line = record.markerBuffer.subarray(0, newline).toString('utf8').trim();
246
- const remainder = record.markerBuffer.subarray(newline + 1);
247
- record.markerBuffer = Buffer.alloc(0);
248
- const expectedPrefix = `${MARKER_PREFIX}:${record.marker}:`;
249
- if (!line.startsWith(expectedPrefix)) {
250
- record.status = 'failed';
251
- record.error = 'Remote operation marker did not match the local operation';
252
- const invalidMarker = Buffer.from(`${line}\n`);
253
- record.stderrBytes += invalidMarker.length + remainder.length;
254
- this.appendOutput(record, 'stderr', invalidMarker);
255
- this.appendOutput(record, 'stderr', remainder);
256
- return;
367
+ const expectedPrefix = `${MARKER_PREFIX}:${record.marker}:`;
368
+ if (!line.startsWith(expectedPrefix)) {
369
+ this.appendStderr(record, lineBytes);
370
+ this.appendStderr(record, record.markerBuffer);
371
+ record.markerBuffer = Buffer.alloc(0);
372
+ this.failMarker(record, 'Remote operation marker did not match the local operation');
373
+ return;
374
+ }
375
+ const metadata = line.slice(expectedPrefix.length).match(/^([1-9]\d*):(0|1)$/);
376
+ const pid = metadata ? Number(metadata[1]) : Number.NaN;
377
+ if (!metadata || !Number.isSafeInteger(pid)) {
378
+ this.appendStderr(record, lineBytes);
379
+ this.appendStderr(record, record.markerBuffer);
380
+ record.markerBuffer = Buffer.alloc(0);
381
+ this.failMarker(record, 'Remote operation marker contained invalid process metadata');
382
+ return;
383
+ }
384
+ record.pid = pid;
385
+ record.processGroup = metadata[2] === '1';
386
+ record.markerVerified = true;
387
+ record.status = 'running';
388
+ this.appendStderr(record, record.markerBuffer);
389
+ record.markerBuffer = Buffer.alloc(0);
257
390
  }
258
- const [pidText, groupText] = line.slice(expectedPrefix.length).split(':');
259
- const pid = Number(pidText);
260
- if (!Number.isSafeInteger(pid) || pid <= 0 || (groupText !== '0' && groupText !== '1')) {
261
- record.status = 'failed';
262
- record.error = 'Remote operation marker contained invalid process metadata';
391
+ }
392
+ failMarker(record, error) {
393
+ record.status = 'failed';
394
+ record.error = error;
395
+ this.finish(record);
396
+ record.stream?.destroy();
397
+ }
398
+ flushMarkerBuffer(record) {
399
+ if (record.markerBuffer.length === 0) {
263
400
  return;
264
401
  }
265
- record.pid = pid;
266
- record.processGroup = groupText === '1';
267
- record.markerVerified = true;
268
- record.status = 'running';
269
- record.stderrBytes += remainder.length;
270
- this.appendOutput(record, 'stderr', remainder);
402
+ this.appendStderr(record, record.markerBuffer);
403
+ record.markerBuffer = Buffer.alloc(0);
404
+ }
405
+ appendStderr(record, data) {
406
+ record.stderrBytes += data.length;
407
+ this.appendOutput(record, 'stderr', data);
271
408
  }
272
409
  appendOutput(record, stream, data) {
273
410
  const storedBytes = record.stdout.length + record.stderr.length;
@@ -315,6 +452,11 @@ export class OperationManager {
315
452
  ...(record.error ? { error: record.error } : {}),
316
453
  };
317
454
  }
455
+ clearPendingStart(alias, operationId) {
456
+ if (this.pendingStarts.get(alias) === operationId) {
457
+ this.pendingStarts.delete(alias);
458
+ }
459
+ }
318
460
  requireOperation(operationId) {
319
461
  this.sweepExpired();
320
462
  const record = this.operations.get(operationId);
@@ -344,6 +486,13 @@ export class OperationManager {
344
486
  }
345
487
  return normalized;
346
488
  }
489
+ normalizeStartTimeoutMs(value) {
490
+ const normalized = value ?? DEFAULT_OPERATION_START_TIMEOUT_MS;
491
+ if (!Number.isSafeInteger(normalized) || normalized <= 0 || normalized > MAX_OPERATION_START_TIMEOUT_MS) {
492
+ throw new Error(`startTimeoutMs must be between 1 and ${MAX_OPERATION_START_TIMEOUT_MS}`);
493
+ }
494
+ return normalized;
495
+ }
347
496
  normalizeOffset(value, length, field) {
348
497
  const normalized = value ?? 0;
349
498
  if (!Number.isSafeInteger(normalized) || normalized < 0 || normalized > length) {
@@ -351,52 +500,4 @@ export class OperationManager {
351
500
  }
352
501
  return normalized;
353
502
  }
354
- ensureUtf8Boundary(buffer, offset, field) {
355
- if (offset < buffer.length && this.isUtf8ContinuationByte(buffer[offset])) {
356
- throw new Error(`${field} must point to a UTF-8 character boundary`);
357
- }
358
- }
359
- utf8SafeEnd(buffer, start, requestedEnd, stream) {
360
- const limitedByMaxBytes = requestedEnd < buffer.length;
361
- let end = requestedEnd;
362
- if (limitedByMaxBytes) {
363
- while (end > start && this.isUtf8ContinuationByte(buffer[end])) {
364
- --end;
365
- }
366
- }
367
- end = this.trimIncompleteUtf8Sequence(buffer, start, end);
368
- if (end === start && requestedEnd > start && limitedByMaxBytes) {
369
- throw new Error(`maxBytes is too small to read the next UTF-8 character from ${stream}`);
370
- }
371
- return end;
372
- }
373
- trimIncompleteUtf8Sequence(buffer, start, end) {
374
- if (end <= start) {
375
- return end;
376
- }
377
- let sequenceStart = end - 1;
378
- while (sequenceStart > start && this.isUtf8ContinuationByte(buffer[sequenceStart])) {
379
- --sequenceStart;
380
- }
381
- const expectedLength = this.utf8SequenceLength(buffer[sequenceStart]);
382
- return sequenceStart + expectedLength > end ? sequenceStart : end;
383
- }
384
- utf8SequenceLength(value) {
385
- if ((value & 0x80) === 0) {
386
- return 1;
387
- }
388
- if ((value & 0xe0) === 0xc0) {
389
- return 2;
390
- }
391
- if ((value & 0xf0) === 0xe0) {
392
- return 3;
393
- }
394
- if ((value & 0xf8) === 0xf0) {
395
- return 4;
396
- }
397
- return 1;
398
- }
399
- isUtf8ContinuationByte(value) {
400
- return (value & 0xc0) === 0x80;
401
- }
402
503
  }
@@ -4,7 +4,7 @@
4
4
  * 负责 PTY 会话的完整生命周期:创建、读写、调整大小、关闭
5
5
  */
6
6
  import type { ClientChannel } from 'ssh2';
7
- import type { PtyOptions, PtySessionInfo } from './types.js';
7
+ import type { PtyCloseResult, PtyOptions, PtySessionInfo, PtyWriteResult } from './types.js';
8
8
  export declare const HARD_PTY_BUFFER_SIZE: number;
9
9
  /** PTY 创建所需的外部依赖 */
10
10
  export interface PtyDependencies {
@@ -20,7 +20,7 @@ export declare class PtyManager {
20
20
  private idleSweeper;
21
21
  constructor();
22
22
  start(deps: PtyDependencies, alias: string, command: string, options?: PtyOptions): Promise<string>;
23
- write(ptyId: string, data: string): boolean;
23
+ write(ptyId: string, data: string): PtyWriteResult;
24
24
  read(ptyId: string, options?: {
25
25
  mode?: 'screen' | 'raw';
26
26
  clear?: boolean;
@@ -37,7 +37,7 @@ export declare class PtyManager {
37
37
  foregroundProcess: string;
38
38
  };
39
39
  resize(ptyId: string, rows: number, cols: number): boolean;
40
- close(ptyId: string): boolean;
40
+ close(ptyId: string): PtyCloseResult;
41
41
  /** 关闭指定 alias 的所有 PTY 会话 */
42
42
  closeByAlias(alias: string): void;
43
43
  list(): PtySessionInfo[];
@@ -19,8 +19,8 @@ export class PtyManager {
19
19
  }
20
20
  async start(deps, alias, command, options = {}) {
21
21
  const ptyId = this.generateId();
22
- const rows = options.rows || 24;
23
- const cols = options.cols || 80;
22
+ const rows = options.rows ?? 24;
23
+ const cols = options.cols ?? 80;
24
24
  const maxBufferSize = this.normalizeBufferSize(options.bufferSize);
25
25
  const stream = await deps.execPty(alias, command, options);
26
26
  // 创建 xterm headless 终端仿真器
@@ -81,11 +81,14 @@ export class PtyManager {
81
81
  throw new Error(`PTY session '${ptyId}' is closed`);
82
82
  }
83
83
  session.lastInputAt = Date.now();
84
- return session.stream.write(data);
84
+ return {
85
+ accepted: true,
86
+ backpressured: !session.stream.write(data),
87
+ };
85
88
  }
86
89
  read(ptyId, options = {}) {
87
90
  const session = this.getSession(ptyId);
88
- const mode = options.mode || 'screen';
91
+ const mode = options.mode ?? 'screen';
89
92
  const clear = options.clear !== false;
90
93
  let data;
91
94
  if (mode === 'screen') {
@@ -126,30 +129,73 @@ export class PtyManager {
126
129
  close(ptyId) {
127
130
  const session = this.sessions.get(ptyId);
128
131
  if (!session) {
129
- return false;
132
+ return {
133
+ success: false,
134
+ ptyId,
135
+ status: 'not_found',
136
+ retryable: false,
137
+ };
130
138
  }
131
- try {
132
- session.stream.close();
133
- }
134
- catch (e) {
135
- console.warn(`PTY ${ptyId} stream close failed:`, e.message);
139
+ if (session.active) {
140
+ try {
141
+ session.stream.close();
142
+ }
143
+ catch (error) {
144
+ return {
145
+ success: false,
146
+ ptyId,
147
+ status: 'failed',
148
+ retryable: true,
149
+ error: error instanceof Error ? error.message : String(error),
150
+ };
151
+ }
136
152
  }
137
153
  try {
138
154
  session.terminal.dispose();
139
155
  }
140
- catch (e) {
141
- console.warn(`PTY ${ptyId} terminal dispose failed:`, e.message);
156
+ catch (error) {
157
+ return {
158
+ success: false,
159
+ ptyId,
160
+ status: session.active ? 'unknown' : 'failed',
161
+ retryable: true,
162
+ error: error instanceof Error ? error.message : String(error),
163
+ };
142
164
  }
143
165
  session.active = false;
144
166
  this.sessions.delete(ptyId);
145
- return true;
167
+ return {
168
+ success: true,
169
+ ptyId,
170
+ status: 'closed',
171
+ retryable: false,
172
+ };
146
173
  }
147
174
  /** 关闭指定 alias 的所有 PTY 会话 */
148
175
  closeByAlias(alias) {
149
176
  for (const [id, session] of this.sessions) {
150
- if (session.alias === alias) {
151
- this.close(id);
177
+ if (session.alias !== alias) {
178
+ continue;
179
+ }
180
+ const result = this.close(id);
181
+ if (result.success) {
182
+ continue;
183
+ }
184
+ try {
185
+ session.stream.destroy();
186
+ }
187
+ catch {
188
+ // SSH 连接已失效,继续释放本地状态
189
+ }
190
+ try {
191
+ session.terminal.dispose();
192
+ }
193
+ catch {
194
+ // SSH 连接已失效,继续释放本地状态
152
195
  }
196
+ session.active = false;
197
+ this.sessions.delete(id);
198
+ console.warn(`PTY ${id} 在 SSH 连接失效时强制清理: ${result.status}`);
153
199
  }
154
200
  }
155
201
  list() {