pi-wechat-session-hub 0.1.0

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.
Files changed (51) hide show
  1. package/LICENSE +661 -0
  2. package/README.md +365 -0
  3. package/docs/decisions/0001-ilink-context-token-queue.md +41 -0
  4. package/docs/handoff-next-session.md +134 -0
  5. package/docs/implementation-spec.md +147 -0
  6. package/extensions/wechat-session-hub.ts +589 -0
  7. package/package.json +67 -0
  8. package/scripts/pi-rpc-smoke.mjs +150 -0
  9. package/scripts/probe-wt-capability.mjs +27 -0
  10. package/scripts/start-ui-worker.ps1 +37 -0
  11. package/src/commands/ilink-qr-login-component.ts +148 -0
  12. package/src/commands/project-command-parser.ts +108 -0
  13. package/src/commands/tokenizer.ts +71 -0
  14. package/src/commands/wechat-manager-command-parser.ts +143 -0
  15. package/src/config/defaults.ts +30 -0
  16. package/src/config/paths.ts +56 -0
  17. package/src/config/store.ts +311 -0
  18. package/src/config/types.ts +33 -0
  19. package/src/config/validation.ts +221 -0
  20. package/src/gateway/channel-types.ts +47 -0
  21. package/src/gateway/command-parser.ts +291 -0
  22. package/src/gateway/command-router.ts +1449 -0
  23. package/src/gateway/credential-store.ts +611 -0
  24. package/src/gateway/durable-message-queue.ts +1043 -0
  25. package/src/gateway/gateway-control-ipc.ts +687 -0
  26. package/src/gateway/gateway-runtime.ts +726 -0
  27. package/src/gateway/ui-worker-extension-bridge.ts +1070 -0
  28. package/src/gateway/ui-worker-ipc.ts +1483 -0
  29. package/src/gateway/ui-worker-types.ts +50 -0
  30. package/src/gateway/wechat-ilink/api-client.ts +390 -0
  31. package/src/gateway/wechat-ilink/channel-adapter.ts +320 -0
  32. package/src/gateway/wechat-ilink/cursor-store.ts +134 -0
  33. package/src/gateway/wechat-ilink/qr-login.ts +612 -0
  34. package/src/gateway/wechat-ilink/typing-indicator.ts +133 -0
  35. package/src/gateway/windows-terminal-launcher.ts +247 -0
  36. package/src/projects/project-service.ts +483 -0
  37. package/src/registry/gateway-lease.ts +348 -0
  38. package/src/registry/manager-registry.ts +466 -0
  39. package/src/registry/types.ts +61 -0
  40. package/src/runtime/background-pi-worker.ts +309 -0
  41. package/src/runtime/background-worker-manager.ts +594 -0
  42. package/src/runtime/gateway-daemon.ts +281 -0
  43. package/src/runtime/gateway-lifecycle-operation.ts +308 -0
  44. package/src/runtime/gateway-service-controller.ts +339 -0
  45. package/src/runtime/gateway-worker-manager.ts +181 -0
  46. package/src/runtime/pi-cli.ts +56 -0
  47. package/src/runtime/pi-rpc-client.ts +427 -0
  48. package/src/runtime/ui-worker-manager.ts +1186 -0
  49. package/src/runtime/windows-logon-task-manager.ts +212 -0
  50. package/src/system/process-liveness.ts +88 -0
  51. package/tsconfig.json +19 -0
@@ -0,0 +1,594 @@
1
+ import { resolve } from "node:path";
2
+ import { stat } from "node:fs/promises";
3
+ import { BackgroundPiWorker } from "./background-pi-worker.ts";
4
+ import type { PiCliInvocation } from "./pi-cli.ts";
5
+ import { ManagerRegistry } from "../registry/manager-registry.ts";
6
+ import type {
7
+ SessionIndexRecord,
8
+ WorkerInstanceRecord,
9
+ WorkerState,
10
+ } from "../registry/types.ts";
11
+ import { ProjectService } from "../projects/project-service.ts";
12
+
13
+ export type BackgroundWorkerManagerErrorCode =
14
+ | "max_background_workers"
15
+ | "session_not_found"
16
+ | "session_not_saved"
17
+ | "session_owned_by_other_process"
18
+ | "worker_not_found"
19
+ | "worker_stop_failed";
20
+
21
+ /**
22
+ * 表示后台 worker 管理请求无法安全完成。
23
+ */
24
+ export class BackgroundWorkerManagerError extends Error {
25
+ /**
26
+ * 创建后台 worker 管理错误。
27
+ *
28
+ * @param code 稳定错误代码。
29
+ * @param message 面向用户的中文说明。
30
+ */
31
+ constructor(
32
+ readonly code: BackgroundWorkerManagerErrorCode,
33
+ message: string,
34
+ ) {
35
+ super(message);
36
+ this.name = "BackgroundWorkerManagerError";
37
+ }
38
+ }
39
+
40
+ export interface BackgroundWorkerManagerOptions {
41
+ projectService: ProjectService;
42
+ registry: ManagerRegistry;
43
+ invocation: PiCliInvocation;
44
+ maxBackgroundWorkers?: number;
45
+ sessionDirectory?: string;
46
+ env?: NodeJS.ProcessEnv;
47
+ disableDiscoveredResources?: boolean;
48
+ }
49
+
50
+ /**
51
+ * 负责后台 Pi worker 创建、恢复、消息投递和优雅停止。
52
+ */
53
+ export class BackgroundWorkerManager {
54
+ private readonly projectService: ProjectService;
55
+ private readonly registry: ManagerRegistry;
56
+ private readonly invocation: PiCliInvocation;
57
+ private readonly maxBackgroundWorkers: number;
58
+ private readonly sessionDirectory?: string;
59
+ private readonly env?: NodeJS.ProcessEnv;
60
+ private readonly disableDiscoveredResources: boolean;
61
+ private readonly workers = new Map<string, BackgroundPiWorker>();
62
+ private readonly stoppingSessions = new Set<string>();
63
+ private startQueue: Promise<void> = Promise.resolve();
64
+ private readonly sessionQueues = new Map<string, Promise<void>>();
65
+
66
+ /**
67
+ * 创建后台 worker 管理器。
68
+ *
69
+ * @param options 项目服务、registry、Pi CLI 和 worker 限额。
70
+ */
71
+ constructor(options: BackgroundWorkerManagerOptions) {
72
+ this.projectService = options.projectService;
73
+ this.registry = options.registry;
74
+ this.invocation = options.invocation;
75
+ this.maxBackgroundWorkers = options.maxBackgroundWorkers ?? 4;
76
+ this.sessionDirectory = options.sessionDirectory;
77
+ this.env = options.env;
78
+ this.disableDiscoveredResources = options.disableDiscoveredResources ?? false;
79
+ }
80
+
81
+ /**
82
+ * 让 Pi CLI 自己创建新的后台 session。
83
+ *
84
+ * @param projectAlias 已登记项目 alias。
85
+ * @param name 可选 session 显示名称。
86
+ * @returns 已启动 worker 的 session 索引记录。
87
+ * @throws {BackgroundWorkerManagerError} worker 数量达到上限时抛出。
88
+ */
89
+ async startNew(projectAlias: string, name?: string): Promise<SessionIndexRecord> {
90
+ return this.withStartQueue(async () => {
91
+ const project = await this.projectService.resolve(projectAlias);
92
+ const snapshot = await this.registry.readSnapshot();
93
+ const activeBackgroundCount = Object.values(snapshot.instances).filter((instance) =>
94
+ instance.mode === "background" && instance.state !== "stale" && instance.state !== "stopping",
95
+ ).length;
96
+ if (activeBackgroundCount >= this.maxBackgroundWorkers) {
97
+ throw new BackgroundWorkerManagerError(
98
+ "max_background_workers",
99
+ `后台 worker 数量已达到上限 ${this.maxBackgroundWorkers}。`,
100
+ );
101
+ }
102
+
103
+ const worker = await BackgroundPiWorker.start({
104
+ invocation: this.invocation,
105
+ cwd: project.path,
106
+ name,
107
+ sessionDirectory: this.sessionDirectory,
108
+ env: this.env,
109
+ disableDiscoveredResources: this.disableDiscoveredResources,
110
+ });
111
+ const session: SessionIndexRecord = {
112
+ sessionId: worker.info.sessionId,
113
+ sessionFile: worker.info.sessionFile,
114
+ cwd: project.path,
115
+ projectAlias,
116
+ ...(worker.info.name ? { name: worker.info.name } : name ? { name } : {}),
117
+ mode: "background",
118
+ state: await isPersistedSessionFile(worker.info.sessionFile) ? "active" : "pending",
119
+ lastActivityAt: new Date().toISOString(),
120
+ };
121
+
122
+ try {
123
+ await this.registerWorker(worker, session);
124
+ } catch (error) {
125
+ await worker.shutdown().catch(() => undefined);
126
+ throw error;
127
+ }
128
+ return session;
129
+ });
130
+ }
131
+
132
+ /**
133
+ * 恢复 registry 中已保存且没有活跃 owner 的 session。
134
+ *
135
+ * @param sessionId Pi session ID。
136
+ * @returns 恢复后的 session 索引记录。
137
+ * @throws {BackgroundWorkerManagerError} session 不存在或已有其他 owner 时抛出。
138
+ */
139
+ async resume(sessionId: string, mode: "background" | "ui" = "background"): Promise<SessionIndexRecord> {
140
+ return this.withStartQueue(() => this.withSessionQueue(sessionId, async () => {
141
+ const existingWorker = this.workers.get(sessionId);
142
+ if (existingWorker && existingWorker.state !== "stale") {
143
+ return this.findSession(sessionId);
144
+ }
145
+ if (existingWorker?.state === "stale") {
146
+ this.workers.delete(sessionId);
147
+ await this.registry.removeInstance(existingWorker.info.instanceId);
148
+ const staleSession = await this.findSession(sessionId);
149
+ await this.registry.upsertSession({
150
+ ...staleSession,
151
+ mode,
152
+ state: await isPersistedSessionFile(staleSession.sessionFile) ? "saved" : "pending",
153
+ });
154
+ }
155
+ const snapshot = await this.registry.readSnapshot();
156
+ const session = snapshot.sessions[sessionId];
157
+ if (!session) {
158
+ throw new BackgroundWorkerManagerError(
159
+ "session_not_found",
160
+ `未找到 session: ${sessionId}。`,
161
+ );
162
+ }
163
+ const activeOwner = Object.values(snapshot.instances).find((instance) =>
164
+ instance.sessionId === sessionId && instance.state !== "stale" && instance.state !== "stopping",
165
+ );
166
+ if (activeOwner || session.state === "active") {
167
+ throw new BackgroundWorkerManagerError(
168
+ "session_owned_by_other_process",
169
+ activeOwner
170
+ ? `session 已由另一个 Pi runtime 持有 (${activeOwner.mode}, PID ${activeOwner.pid}), 拒绝双开。`
171
+ : `session ${sessionId} 在 registry 中仍标记为 active, owner 状态未核实, 拒绝恢复。`,
172
+ );
173
+ }
174
+ if (!(await isPersistedSessionFile(session.sessionFile))) {
175
+ throw new BackgroundWorkerManagerError(
176
+ "session_not_saved",
177
+ `session ${sessionId} 尚无 Pi session JSONL 文件; 先向活跃 worker 发送一条消息后才能恢复。`,
178
+ );
179
+ }
180
+ const project = await this.projectService.resolveSession(session.projectAlias, session.cwd);
181
+ const worker = await BackgroundPiWorker.start({
182
+ invocation: this.invocation,
183
+ cwd: project.path,
184
+ sessionFile: session.sessionFile,
185
+ name: session.name,
186
+ sessionDirectory: this.sessionDirectory,
187
+ env: this.env,
188
+ disableDiscoveredResources: this.disableDiscoveredResources,
189
+ });
190
+ if (
191
+ worker.info.sessionId !== sessionId ||
192
+ !samePath(worker.info.sessionFile, session.sessionFile)
193
+ ) {
194
+ await worker.shutdown().catch(() => undefined);
195
+ throw new BackgroundWorkerManagerError(
196
+ "session_not_found",
197
+ "Pi 恢复后返回了不同的 sessionId, 已停止新 worker。",
198
+ );
199
+ }
200
+
201
+ const resumed: SessionIndexRecord = {
202
+ ...session,
203
+ sessionFile: worker.info.sessionFile,
204
+ cwd: project.path,
205
+ mode,
206
+ state: "active",
207
+ lastActivityAt: new Date().toISOString(),
208
+ };
209
+ try {
210
+ await this.registerWorker(worker, resumed);
211
+ } catch (error) {
212
+ await worker.shutdown().catch(() => undefined);
213
+ throw error;
214
+ }
215
+ return resumed;
216
+ }));
217
+ }
218
+
219
+ /**
220
+ * 向活跃后台 session 发送消息并等待 Pi 最终文本。
221
+ *
222
+ * @param sessionId Pi session ID。
223
+ * @param message 用户消息正文。
224
+ * @returns Pi 最终 assistant 文本。
225
+ * @throws {BackgroundWorkerManagerError} session 没有本 manager 的活跃 worker 时抛出。
226
+ */
227
+ async prompt(sessionId: string, message: string): Promise<string> {
228
+ return this.withSessionQueue(sessionId, async () => {
229
+ const worker = this.workers.get(sessionId);
230
+ if (!worker) {
231
+ throw new BackgroundWorkerManagerError(
232
+ "worker_not_found",
233
+ `session ${sessionId} 没有由当前 Gateway 管理的后台 worker。`,
234
+ );
235
+ }
236
+ try {
237
+ const text = await worker.prompt(message);
238
+ const session = await this.findSession(sessionId);
239
+ await this.registry.upsertSession({
240
+ ...session,
241
+ state: await isPersistedSessionFile(session.sessionFile) ? "active" : "pending",
242
+ lastActivityAt: new Date().toISOString(),
243
+ });
244
+ if (worker.state !== "stale") {
245
+ await this.updateWorkerState(worker);
246
+ }
247
+ await this.registry.appendEvent("worker.turn_settled", {
248
+ sessionId,
249
+ instanceId: worker.info.instanceId,
250
+ });
251
+ return text;
252
+ } catch (error) {
253
+ const session = await this.findSession(sessionId);
254
+ await this.registry.upsertSession({
255
+ ...session,
256
+ state: await isPersistedSessionFile(session.sessionFile) ? "active" : "pending",
257
+ lastActivityAt: new Date().toISOString(),
258
+ });
259
+ if (worker.state !== "stale") {
260
+ await this.updateWorkerState(worker);
261
+ }
262
+ await this.registry.appendEvent("worker.turn_failed", {
263
+ sessionId,
264
+ instanceId: worker.info.instanceId,
265
+ errorType: error instanceof Error ? error.name : "UnknownError",
266
+ });
267
+ throw error;
268
+ }
269
+ });
270
+ }
271
+
272
+ /**
273
+ * 优雅停止后台 worker, 保留 Pi session 文件与索引。
274
+ *
275
+ * @param sessionId Pi session ID。
276
+ * @param abortRunning 是否明确允许中止当前 turn。
277
+ * @returns 无返回值。
278
+ * @throws {BackgroundWorkerManagerError} session 没有由当前 manager 管理的 worker 时抛出。
279
+ */
280
+ async stop(sessionId: string, abortRunning = false): Promise<void> {
281
+ const runningWorker = this.workers.get(sessionId);
282
+ if (abortRunning && runningWorker?.state === "running") {
283
+ this.stoppingSessions.add(sessionId);
284
+ try {
285
+ await runningWorker.shutdown({ abortRunning: true });
286
+ } catch (error) {
287
+ this.stoppingSessions.delete(sessionId);
288
+ throw error;
289
+ }
290
+ }
291
+
292
+ return this.withSessionQueue(sessionId, async () => {
293
+ const worker = this.workers.get(sessionId);
294
+ if (!worker) {
295
+ throw new BackgroundWorkerManagerError(
296
+ "worker_not_found",
297
+ `session ${sessionId} 没有由当前 Gateway 管理的后台 worker。`,
298
+ );
299
+ }
300
+ this.stoppingSessions.add(sessionId);
301
+ try {
302
+ if (worker.state !== "stale") {
303
+ await worker.shutdown({ abortRunning });
304
+ }
305
+ this.workers.delete(sessionId);
306
+ await this.registry.removeInstance(worker.info.instanceId);
307
+ const session = await this.findSession(sessionId);
308
+ await this.registry.upsertSession({
309
+ ...session,
310
+ state: await isPersistedSessionFile(session.sessionFile) ? "saved" : "pending",
311
+ lastActivityAt: new Date().toISOString(),
312
+ });
313
+ await this.registry.appendEvent("worker.stopped", {
314
+ sessionId,
315
+ instanceId: worker.info.instanceId,
316
+ });
317
+ } finally {
318
+ this.stoppingSessions.delete(sessionId);
319
+ }
320
+ });
321
+ }
322
+
323
+ /**
324
+ * 优雅停止本管理器启动或恢复的全部后台 worker。
325
+ *
326
+ * @returns 无返回值。
327
+ * @throws {BackgroundWorkerManagerError} 任一 worker 未能安全停止时抛出。
328
+ */
329
+ async stopAll(): Promise<void> {
330
+ const outcomes = await Promise.allSettled(
331
+ [...this.workers.keys()].map((sessionId) => this.stop(sessionId)),
332
+ );
333
+ if (outcomes.some((outcome) => outcome.status === "rejected")) {
334
+ throw new BackgroundWorkerManagerError(
335
+ "worker_stop_failed",
336
+ "至少一个后台 Pi worker 未能优雅停止; Gateway 租约将保留, 请检查后重试。",
337
+ );
338
+ }
339
+ }
340
+
341
+ /**
342
+ * 检查当前进程是否持有该 session 的可用后台 worker。
343
+ *
344
+ * @param sessionId Pi session ID。
345
+ * @returns worker 已启动且未 stale 时返回 true。
346
+ */
347
+ hasWorker(sessionId: string): boolean {
348
+ const worker = this.workers.get(sessionId);
349
+ return Boolean(worker && worker.state !== "stale" && worker.state !== "stopping");
350
+ }
351
+
352
+ /**
353
+ * 列出 registry 中保存的所有 session。
354
+ *
355
+ * @returns 按最近活动时间倒序排列的 session。
356
+ */
357
+ async listSessions(): Promise<SessionIndexRecord[]> {
358
+ const snapshot = await this.registry.readSnapshot();
359
+ return Object.values(snapshot.sessions).sort((left, right) =>
360
+ right.lastActivityAt.localeCompare(left.lastActivityAt),
361
+ );
362
+ }
363
+
364
+ /**
365
+ * 注册已启动 worker, session 和审计事件。
366
+ *
367
+ * @param worker Pi RPC worker。
368
+ * @param session session 索引记录。
369
+ * @returns 无返回值。
370
+ */
371
+ private async registerWorker(
372
+ worker: BackgroundPiWorker,
373
+ session: SessionIndexRecord,
374
+ ): Promise<void> {
375
+ const instance = this.toInstanceRecord(worker, session);
376
+ try {
377
+ if (worker.state === "stale") {
378
+ throw new BackgroundWorkerManagerError(
379
+ "worker_not_found",
380
+ "Pi RPC worker 在 registry 注册前已退出。",
381
+ );
382
+ }
383
+ const current = await this.registry.readSnapshot();
384
+ const competingOwner = Object.values(current.instances).find((candidate) =>
385
+ candidate.sessionId === session.sessionId &&
386
+ candidate.instanceId !== instance.instanceId &&
387
+ candidate.state !== "stale" &&
388
+ candidate.state !== "stopping",
389
+ );
390
+ if (competingOwner) {
391
+ throw new BackgroundWorkerManagerError(
392
+ "session_owned_by_other_process",
393
+ `session ${session.sessionId} 已由 PID ${competingOwner.pid} 持有, 拒绝双 writer。`,
394
+ );
395
+ }
396
+ await this.registry.upsertInstance(instance);
397
+ await this.registry.upsertSession(session);
398
+ await this.registry.appendEvent("worker.started", {
399
+ sessionId: session.sessionId,
400
+ instanceId: instance.instanceId,
401
+ projectAlias: session.projectAlias,
402
+ mode: "background",
403
+ pid: instance.pid,
404
+ });
405
+ this.workers.set(session.sessionId, worker);
406
+ worker.on("state_change", (state: WorkerState) => {
407
+ void this.handleWorkerStateChange(worker, state).catch(() => undefined);
408
+ });
409
+ } catch (error) {
410
+ await this.registry.removeInstance(instance.instanceId).catch(() => undefined);
411
+ await this.registry.upsertSession({
412
+ ...session,
413
+ state: await isPersistedSessionFile(session.sessionFile) ? "saved" : "pending",
414
+ }).catch(() => undefined);
415
+ throw error;
416
+ }
417
+ }
418
+
419
+ /**
420
+ * 将 worker 信息规范化为 registry instance 记录。
421
+ *
422
+ * @param worker Pi RPC worker。
423
+ * @param session 对应 session 索引。
424
+ * @returns worker instance 记录。
425
+ */
426
+ private toInstanceRecord(
427
+ worker: BackgroundPiWorker,
428
+ session: SessionIndexRecord,
429
+ ): WorkerInstanceRecord {
430
+ return {
431
+ instanceId: worker.info.instanceId,
432
+ pid: worker.info.pid,
433
+ processBirthId: worker.info.processBirthId,
434
+ sessionId: worker.info.sessionId,
435
+ sessionFile: worker.info.sessionFile,
436
+ cwd: session.cwd,
437
+ projectAlias: session.projectAlias,
438
+ mode: "background",
439
+ state: worker.state,
440
+ heartbeatAt: new Date().toISOString(),
441
+ };
442
+ }
443
+
444
+ /**
445
+ * 从 registry 读取 session 索引记录。
446
+ *
447
+ * @param sessionId Pi session ID。
448
+ * @returns session 索引记录。
449
+ * @throws {BackgroundWorkerManagerError} session 不存在时抛出。
450
+ */
451
+ private async findSession(sessionId: string): Promise<SessionIndexRecord> {
452
+ const snapshot = await this.registry.readSnapshot();
453
+ const session = snapshot.sessions[sessionId];
454
+ if (!session) {
455
+ throw new BackgroundWorkerManagerError(
456
+ "session_not_found",
457
+ `未找到 session: ${sessionId}。`,
458
+ );
459
+ }
460
+ return session;
461
+ }
462
+
463
+ /**
464
+ * 将 worker 当前状态写回 instance registry。
465
+ *
466
+ * @param worker Pi RPC worker。
467
+ * @returns 无返回值。
468
+ */
469
+ private async updateWorkerState(worker: BackgroundPiWorker): Promise<void> {
470
+ const session = await this.findSession(worker.info.sessionId);
471
+ await this.registry.upsertInstance(this.toInstanceRecord(worker, session));
472
+ }
473
+
474
+ /**
475
+ * 处理 worker 状态变化; 意外退出后保留已持久化 session。
476
+ *
477
+ * @param worker 发生状态变化的 Pi worker。
478
+ * @param state 新状态。
479
+ * @returns 无返回值。
480
+ */
481
+ private async handleWorkerStateChange(
482
+ worker: BackgroundPiWorker,
483
+ state: WorkerState,
484
+ ): Promise<void> {
485
+ const sessionId = worker.info.sessionId;
486
+ if (this.workers.get(sessionId) !== worker || this.stoppingSessions.has(sessionId)) {
487
+ return;
488
+ }
489
+ if (state !== "stale") {
490
+ await this.updateWorkerState(worker);
491
+ return;
492
+ }
493
+ this.workers.delete(sessionId);
494
+ await this.registry.removeInstance(worker.info.instanceId);
495
+ const session = await this.findSession(sessionId);
496
+ await this.registry.upsertSession({
497
+ ...session,
498
+ state: await isPersistedSessionFile(session.sessionFile) ? "saved" : "pending",
499
+ lastActivityAt: new Date().toISOString(),
500
+ });
501
+ await this.registry.appendEvent("worker.exited", {
502
+ sessionId,
503
+ instanceId: worker.info.instanceId,
504
+ });
505
+ }
506
+
507
+ /**
508
+ * 串行执行 session 内的消息、恢复和停止操作。
509
+ *
510
+ * @param sessionId Pi session ID。
511
+ * @param operation 需要串行执行的操作。
512
+ * @returns 操作结果。
513
+ */
514
+ private async withSessionQueue<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
515
+ const previous = this.sessionQueues.get(sessionId) ?? Promise.resolve();
516
+ let release = (): void => undefined;
517
+ const gate = new Promise<void>((resolveGate) => {
518
+ release = resolveGate;
519
+ });
520
+ const queued = previous.then(() => gate);
521
+ this.sessionQueues.set(sessionId, queued);
522
+ await previous;
523
+ try {
524
+ return await operation();
525
+ } finally {
526
+ release();
527
+ if (this.sessionQueues.get(sessionId) === queued) {
528
+ this.sessionQueues.delete(sessionId);
529
+ }
530
+ }
531
+ }
532
+
533
+ /**
534
+ * 串行执行 startNew 操作, 避免并发创建绕过 worker 限额。
535
+ *
536
+ * @param operation 创建操作。
537
+ * @returns 创建结果。
538
+ */
539
+ private async withStartQueue<T>(operation: () => Promise<T>): Promise<T> {
540
+ const previous = this.startQueue;
541
+ let release = (): void => undefined;
542
+ this.startQueue = new Promise<void>((resolveQueue) => {
543
+ release = resolveQueue;
544
+ });
545
+ await previous;
546
+ try {
547
+ return await operation();
548
+ } finally {
549
+ release();
550
+ }
551
+ }
552
+ }
553
+
554
+ /**
555
+ * 判断两个 session 文件路径是否指向同一位置。
556
+ *
557
+ * @param left Pi 返回的路径。
558
+ * @param right registry 保存的路径。
559
+ * @returns 路径一致时返回 true。
560
+ */
561
+ function samePath(left: string, right: string): boolean {
562
+ const resolvedLeft = resolve(left);
563
+ const resolvedRight = resolve(right);
564
+ return process.platform === "win32"
565
+ ? resolvedLeft.toLowerCase() === resolvedRight.toLowerCase()
566
+ : resolvedLeft === resolvedRight;
567
+ }
568
+
569
+ /**
570
+ * 判断 Pi session JSONL 是否已由 Pi 持久化。
571
+ *
572
+ * @param sessionFile Pi 返回的 session 文件路径。
573
+ * @returns 文件存在且为普通文件时返回 true。
574
+ */
575
+ async function isPersistedSessionFile(sessionFile: string): Promise<boolean> {
576
+ try {
577
+ return (await stat(sessionFile)).isFile();
578
+ } catch (error) {
579
+ if (isNodeError(error) && error.code === "ENOENT") {
580
+ return false;
581
+ }
582
+ throw error;
583
+ }
584
+ }
585
+
586
+ /**
587
+ * 判断值是否为 Node.js 文件系统错误。
588
+ *
589
+ * @param error 待检查值。
590
+ * @returns 值带有 Node.js 错误代码时返回 true。
591
+ */
592
+ function isNodeError(error: unknown): error is NodeJS.ErrnoException {
593
+ return error instanceof Error && "code" in error;
594
+ }