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.
- package/LICENSE +661 -0
- package/README.md +365 -0
- package/docs/decisions/0001-ilink-context-token-queue.md +41 -0
- package/docs/handoff-next-session.md +134 -0
- package/docs/implementation-spec.md +147 -0
- package/extensions/wechat-session-hub.ts +589 -0
- package/package.json +67 -0
- package/scripts/pi-rpc-smoke.mjs +150 -0
- package/scripts/probe-wt-capability.mjs +27 -0
- package/scripts/start-ui-worker.ps1 +37 -0
- package/src/commands/ilink-qr-login-component.ts +148 -0
- package/src/commands/project-command-parser.ts +108 -0
- package/src/commands/tokenizer.ts +71 -0
- package/src/commands/wechat-manager-command-parser.ts +143 -0
- package/src/config/defaults.ts +30 -0
- package/src/config/paths.ts +56 -0
- package/src/config/store.ts +311 -0
- package/src/config/types.ts +33 -0
- package/src/config/validation.ts +221 -0
- package/src/gateway/channel-types.ts +47 -0
- package/src/gateway/command-parser.ts +291 -0
- package/src/gateway/command-router.ts +1449 -0
- package/src/gateway/credential-store.ts +611 -0
- package/src/gateway/durable-message-queue.ts +1043 -0
- package/src/gateway/gateway-control-ipc.ts +687 -0
- package/src/gateway/gateway-runtime.ts +726 -0
- package/src/gateway/ui-worker-extension-bridge.ts +1070 -0
- package/src/gateway/ui-worker-ipc.ts +1483 -0
- package/src/gateway/ui-worker-types.ts +50 -0
- package/src/gateway/wechat-ilink/api-client.ts +390 -0
- package/src/gateway/wechat-ilink/channel-adapter.ts +320 -0
- package/src/gateway/wechat-ilink/cursor-store.ts +134 -0
- package/src/gateway/wechat-ilink/qr-login.ts +612 -0
- package/src/gateway/wechat-ilink/typing-indicator.ts +133 -0
- package/src/gateway/windows-terminal-launcher.ts +247 -0
- package/src/projects/project-service.ts +483 -0
- package/src/registry/gateway-lease.ts +348 -0
- package/src/registry/manager-registry.ts +466 -0
- package/src/registry/types.ts +61 -0
- package/src/runtime/background-pi-worker.ts +309 -0
- package/src/runtime/background-worker-manager.ts +594 -0
- package/src/runtime/gateway-daemon.ts +281 -0
- package/src/runtime/gateway-lifecycle-operation.ts +308 -0
- package/src/runtime/gateway-service-controller.ts +339 -0
- package/src/runtime/gateway-worker-manager.ts +181 -0
- package/src/runtime/pi-cli.ts +56 -0
- package/src/runtime/pi-rpc-client.ts +427 -0
- package/src/runtime/ui-worker-manager.ts +1186 -0
- package/src/runtime/windows-logon-task-manager.ts +212 -0
- package/src/system/process-liveness.ts +88 -0
- package/tsconfig.json +19 -0
|
@@ -0,0 +1,726 @@
|
|
|
1
|
+
import { EventEmitter } from "node:events";
|
|
2
|
+
import { stat } from "node:fs/promises";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
4
|
+
import { join, resolve } from "node:path";
|
|
5
|
+
import type { ConfigurationStore } from "../config/store.ts";
|
|
6
|
+
import type { ManagerConfiguration } from "../config/types.ts";
|
|
7
|
+
import { ProjectService } from "../projects/project-service.ts";
|
|
8
|
+
import { GatewayCommandRouter } from "./command-router.ts";
|
|
9
|
+
import { DurableMessageQueue } from "./durable-message-queue.ts";
|
|
10
|
+
import { IlinkCredentialStore } from "./credential-store.ts";
|
|
11
|
+
import { IlinkApiClient } from "./wechat-ilink/api-client.ts";
|
|
12
|
+
import { IlinkChannelAdapter } from "./wechat-ilink/channel-adapter.ts";
|
|
13
|
+
import { IlinkTypingIndicator } from "./wechat-ilink/typing-indicator.ts";
|
|
14
|
+
import { IlinkCursorStore } from "./wechat-ilink/cursor-store.ts";
|
|
15
|
+
import { GatewayLease } from "../registry/gateway-lease.ts";
|
|
16
|
+
import { ManagerRegistry } from "../registry/manager-registry.ts";
|
|
17
|
+
import type { GatewayStatusRecord, RouteRecord, SessionIndexRecord, WorkerInstanceRecord } from "../registry/types.ts";
|
|
18
|
+
import { isProcessAlive } from "../system/process-liveness.ts";
|
|
19
|
+
import { BackgroundWorkerManager } from "../runtime/background-worker-manager.ts";
|
|
20
|
+
import { GatewayWorkerManager } from "../runtime/gateway-worker-manager.ts";
|
|
21
|
+
import { UiWorkerManager } from "../runtime/ui-worker-manager.ts";
|
|
22
|
+
import { resolveCurrentPiCli, type PiCliInvocation } from "../runtime/pi-cli.ts";
|
|
23
|
+
import { UiWorkerIpcServer } from "./ui-worker-ipc.ts";
|
|
24
|
+
import { WindowsTerminalLauncher } from "./windows-terminal-launcher.ts";
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Gateway runtime 在启动、在线、鉴权失效和停止过程中的状态。
|
|
28
|
+
*/
|
|
29
|
+
export type GatewayRuntimeState = "starting" | "online" | "auth_required" | "stopping" | "stopped" | "lease_lost";
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* 表示 Gateway runtime 无法在维持单 writer 与凭证隔离的前提下启动或停止。
|
|
33
|
+
*/
|
|
34
|
+
export class GatewayRuntimeError extends Error {
|
|
35
|
+
/**
|
|
36
|
+
* 创建不包含 token 或消息正文的 Gateway runtime 错误。
|
|
37
|
+
*
|
|
38
|
+
* @param code 稳定错误代码。
|
|
39
|
+
* @param message 可安全显示给用户的中文说明。
|
|
40
|
+
*/
|
|
41
|
+
constructor(
|
|
42
|
+
readonly code:
|
|
43
|
+
| "configuration_incomplete"
|
|
44
|
+
| "live_worker_detected"
|
|
45
|
+
| "worker_capacity"
|
|
46
|
+
| "registry_inconsistent"
|
|
47
|
+
| "worker_shutdown_failed",
|
|
48
|
+
message: string,
|
|
49
|
+
) {
|
|
50
|
+
super(message);
|
|
51
|
+
this.name = "GatewayRuntimeError";
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* 将 Gateway lease、registry、durable queue、background/UI worker 与 iLink poller 组合为显式启停的服务。
|
|
57
|
+
*/
|
|
58
|
+
export class GatewayRuntime extends EventEmitter {
|
|
59
|
+
private heartbeatTimer?: NodeJS.Timeout;
|
|
60
|
+
private stopTask?: Promise<void>;
|
|
61
|
+
private currentState: GatewayRuntimeState = "starting";
|
|
62
|
+
private readonly startedAt = new Date().toISOString();
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* 创建已经取得 Gateway lease 但尚未初始化完成的 runtime。
|
|
66
|
+
*
|
|
67
|
+
* @param options 已验证的运行配置和运行时依赖。
|
|
68
|
+
*/
|
|
69
|
+
private constructor(
|
|
70
|
+
private readonly config: ManagerConfiguration,
|
|
71
|
+
private readonly lease: GatewayLease,
|
|
72
|
+
private readonly registry: ManagerRegistry,
|
|
73
|
+
private readonly queue: DurableMessageQueue,
|
|
74
|
+
private readonly gatewayWorkerManager: GatewayWorkerManager,
|
|
75
|
+
private readonly uiWorkerManager: UiWorkerManager,
|
|
76
|
+
private readonly uiIpcServer: UiWorkerIpcServer,
|
|
77
|
+
private readonly router: GatewayCommandRouter,
|
|
78
|
+
private readonly channel: IlinkChannelAdapter,
|
|
79
|
+
) {
|
|
80
|
+
super();
|
|
81
|
+
this.channel.on("session_expired", () => {
|
|
82
|
+
void this.markAuthRequired();
|
|
83
|
+
});
|
|
84
|
+
this.channel.on("poll_error", (event: { code: string }) => {
|
|
85
|
+
this.emit("poll_error", event);
|
|
86
|
+
});
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* 读取专属凭证、取得单实例租约、恢复安全 session 并启动 iLink poller。
|
|
91
|
+
*
|
|
92
|
+
* @param options Gateway data directory、配置与 Pi worker 运行参数。
|
|
93
|
+
* @returns 已经在线或正在等待 iLink 首次响应的 runtime。
|
|
94
|
+
* @throws {GatewayRuntimeError} allowlist 未配置或旧 worker 仍存活时抛出。
|
|
95
|
+
*/
|
|
96
|
+
static async start(options: {
|
|
97
|
+
dataDirectory: string;
|
|
98
|
+
configStore: ConfigurationStore;
|
|
99
|
+
projectService: ProjectService;
|
|
100
|
+
invocation?: PiCliInvocation;
|
|
101
|
+
extensionPath?: string;
|
|
102
|
+
sessionDirectory?: string;
|
|
103
|
+
env?: NodeJS.ProcessEnv;
|
|
104
|
+
disableDiscoveredResources?: boolean;
|
|
105
|
+
lease?: GatewayLease;
|
|
106
|
+
onControlReady?: (lease: GatewayLease, registry: ManagerRegistry) => Promise<void>;
|
|
107
|
+
fetcher?: typeof fetch;
|
|
108
|
+
uiWorkerLauncher?: Pick<WindowsTerminalLauncher, "launch">;
|
|
109
|
+
uiWorkerCapability?: () => Promise<import("./windows-terminal-launcher.ts").WindowsTerminalCapability>;
|
|
110
|
+
uiIpcEndpoint?: string;
|
|
111
|
+
uiPlatform?: NodeJS.Platform;
|
|
112
|
+
credentialStoreOptions?: ConstructorParameters<typeof IlinkCredentialStore>[2];
|
|
113
|
+
}): Promise<GatewayRuntime> {
|
|
114
|
+
let config: ManagerConfiguration;
|
|
115
|
+
try {
|
|
116
|
+
const snapshot = await options.configStore.load();
|
|
117
|
+
config = snapshot.config;
|
|
118
|
+
if (!config.wechat.authorizedUserId.trim()) {
|
|
119
|
+
throw new GatewayRuntimeError(
|
|
120
|
+
"configuration_incomplete",
|
|
121
|
+
"启动 Gateway 前必须配置唯一授权微信 userId。",
|
|
122
|
+
);
|
|
123
|
+
}
|
|
124
|
+
} catch (error) {
|
|
125
|
+
await options.lease?.release().catch(() => undefined);
|
|
126
|
+
throw error;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
const dataDirectory = resolve(options.dataDirectory);
|
|
130
|
+
if (options.lease && resolve(options.lease.directory) !== dataDirectory) {
|
|
131
|
+
await options.lease.release().catch(() => undefined);
|
|
132
|
+
throw new GatewayRuntimeError(
|
|
133
|
+
"registry_inconsistent",
|
|
134
|
+
"预先取得的 Gateway lease 与 dataDirectory 不匹配。",
|
|
135
|
+
);
|
|
136
|
+
}
|
|
137
|
+
const lease = options.lease ?? await GatewayLease.acquire(dataDirectory);
|
|
138
|
+
let registry: ManagerRegistry | undefined;
|
|
139
|
+
let queue: DurableMessageQueue | undefined;
|
|
140
|
+
let workerManager: BackgroundWorkerManager | undefined;
|
|
141
|
+
let gatewayWorkerManager: GatewayWorkerManager | undefined;
|
|
142
|
+
let uiWorkerManager: UiWorkerManager | undefined;
|
|
143
|
+
let uiIpcServer: UiWorkerIpcServer | undefined;
|
|
144
|
+
let channel: IlinkChannelAdapter | undefined;
|
|
145
|
+
try {
|
|
146
|
+
const credentials = await new IlinkCredentialStore(
|
|
147
|
+
dataDirectory,
|
|
148
|
+
config.wechat.credentialFile,
|
|
149
|
+
options.credentialStoreOptions,
|
|
150
|
+
).load(config.wechat.authorizedUserId);
|
|
151
|
+
registry = new ManagerRegistry(dataDirectory, lease);
|
|
152
|
+
queue = new DurableMessageQueue(dataDirectory, lease);
|
|
153
|
+
const invocation = options.invocation ?? resolveCurrentPiCli();
|
|
154
|
+
workerManager = new BackgroundWorkerManager({
|
|
155
|
+
projectService: options.projectService,
|
|
156
|
+
registry,
|
|
157
|
+
invocation,
|
|
158
|
+
maxBackgroundWorkers: config.runtime.maxBackgroundWorkers,
|
|
159
|
+
sessionDirectory: options.sessionDirectory,
|
|
160
|
+
env: options.env,
|
|
161
|
+
disableDiscoveredResources: options.disableDiscoveredResources,
|
|
162
|
+
});
|
|
163
|
+
uiIpcServer = new UiWorkerIpcServer(dataDirectory, registry, lease, {
|
|
164
|
+
...(options.uiIpcEndpoint ? { endpoint: options.uiIpcEndpoint } : {}),
|
|
165
|
+
});
|
|
166
|
+
uiWorkerManager = new UiWorkerManager({
|
|
167
|
+
managerDirectory: dataDirectory,
|
|
168
|
+
projectService: options.projectService,
|
|
169
|
+
registry,
|
|
170
|
+
ipcServer: uiIpcServer,
|
|
171
|
+
backgroundWorkerManager: workerManager,
|
|
172
|
+
invocation,
|
|
173
|
+
extensionPath: options.extensionPath ?? fileURLToPath(new URL("../../extensions/wechat-session-hub.ts", import.meta.url)),
|
|
174
|
+
staleAfterMs: config.runtime.staleAfterMs,
|
|
175
|
+
registrationTimeoutMs: 60000,
|
|
176
|
+
...(options.uiWorkerLauncher ? { launcher: options.uiWorkerLauncher } : {}),
|
|
177
|
+
...(options.uiWorkerCapability ? { probeCapability: options.uiWorkerCapability } : {}),
|
|
178
|
+
...(options.uiPlatform ? { platform: options.uiPlatform } : {}),
|
|
179
|
+
});
|
|
180
|
+
gatewayWorkerManager = new GatewayWorkerManager(workerManager, uiWorkerManager, registry);
|
|
181
|
+
const api = new IlinkApiClient({
|
|
182
|
+
credentials,
|
|
183
|
+
...(options.fetcher ? { fetcher: options.fetcher } : {}),
|
|
184
|
+
});
|
|
185
|
+
const typingIndicator = new IlinkTypingIndicator(api);
|
|
186
|
+
channel = new IlinkChannelAdapter(
|
|
187
|
+
api,
|
|
188
|
+
new IlinkCursorStore(join(dataDirectory, "ilink-sync.json"), lease),
|
|
189
|
+
{ authorizedUserId: config.wechat.authorizedUserId },
|
|
190
|
+
);
|
|
191
|
+
const router = new GatewayCommandRouter({
|
|
192
|
+
configStore: options.configStore,
|
|
193
|
+
projectService: options.projectService,
|
|
194
|
+
workerManager: gatewayWorkerManager,
|
|
195
|
+
registry,
|
|
196
|
+
queue,
|
|
197
|
+
lease,
|
|
198
|
+
processingIndicator: typingIndicator,
|
|
199
|
+
uiModeCapability: () => uiWorkerManager!.describeUiModeCapability(),
|
|
200
|
+
replySink: (routeId, messageId, reply, replyContext) =>
|
|
201
|
+
channel!.sendReply(routeId, messageId, reply, replyContext),
|
|
202
|
+
});
|
|
203
|
+
const runtime = new GatewayRuntime(
|
|
204
|
+
config,
|
|
205
|
+
lease,
|
|
206
|
+
registry,
|
|
207
|
+
queue,
|
|
208
|
+
gatewayWorkerManager,
|
|
209
|
+
uiWorkerManager,
|
|
210
|
+
uiIpcServer,
|
|
211
|
+
router,
|
|
212
|
+
channel,
|
|
213
|
+
);
|
|
214
|
+
await runtime.initialize(options.onControlReady);
|
|
215
|
+
return runtime;
|
|
216
|
+
} catch (error) {
|
|
217
|
+
let cleanupFailed = false;
|
|
218
|
+
try {
|
|
219
|
+
await channel?.stop();
|
|
220
|
+
} catch {
|
|
221
|
+
cleanupFailed = true;
|
|
222
|
+
}
|
|
223
|
+
try {
|
|
224
|
+
await queue?.waitForIdle();
|
|
225
|
+
} catch {
|
|
226
|
+
cleanupFailed = true;
|
|
227
|
+
}
|
|
228
|
+
try {
|
|
229
|
+
await gatewayWorkerManager?.stopAll();
|
|
230
|
+
} catch {
|
|
231
|
+
cleanupFailed = true;
|
|
232
|
+
}
|
|
233
|
+
try {
|
|
234
|
+
await uiWorkerManager?.detachGateway();
|
|
235
|
+
} catch {
|
|
236
|
+
cleanupFailed = true;
|
|
237
|
+
}
|
|
238
|
+
if (cleanupFailed) {
|
|
239
|
+
if (registry) {
|
|
240
|
+
await registry.setGateway({
|
|
241
|
+
ownerId: lease.ownerId,
|
|
242
|
+
pid: lease.pid,
|
|
243
|
+
processBirthId: lease.processBirthId,
|
|
244
|
+
startedAt: new Date().toISOString(),
|
|
245
|
+
heartbeatAt: new Date().toISOString(),
|
|
246
|
+
state: "stopping",
|
|
247
|
+
}).catch(() => undefined);
|
|
248
|
+
}
|
|
249
|
+
throw new GatewayRuntimeError(
|
|
250
|
+
"worker_shutdown_failed",
|
|
251
|
+
"Gateway 初始化失败且后台资源未能全部停止; 为避免双 writer, manager.lock 已保留。",
|
|
252
|
+
);
|
|
253
|
+
}
|
|
254
|
+
await registry?.setGateway(null).catch(() => undefined);
|
|
255
|
+
await lease.release().catch(() => undefined);
|
|
256
|
+
throw error;
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
/**
|
|
261
|
+
* 获取当前 runtime 生命周期状态。
|
|
262
|
+
*
|
|
263
|
+
* @returns 本进程内的 Gateway 状态。
|
|
264
|
+
*/
|
|
265
|
+
get status(): GatewayRuntimeState {
|
|
266
|
+
return this.currentState;
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* 停止 poller 与后台 Pi worker, detach 可见 UI pipe, 成功后删除 Gateway 状态并释放 lease。
|
|
271
|
+
*
|
|
272
|
+
* 正在执行的模型 turn 会自然结束, 不会被隐式 abort。任一 worker 无法安全停止时保留 lease。
|
|
273
|
+
*
|
|
274
|
+
* @returns 无返回值。
|
|
275
|
+
* @throws {GatewayRuntimeError} worker 未能安全停止时抛出。
|
|
276
|
+
*/
|
|
277
|
+
async stop(): Promise<void> {
|
|
278
|
+
if (this.currentState === "stopped") {
|
|
279
|
+
return;
|
|
280
|
+
}
|
|
281
|
+
if (!this.stopTask) {
|
|
282
|
+
this.stopTask = this.stopInternal();
|
|
283
|
+
}
|
|
284
|
+
try {
|
|
285
|
+
await this.stopTask;
|
|
286
|
+
} finally {
|
|
287
|
+
if (!this.isStopped()) {
|
|
288
|
+
this.stopTask = undefined;
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
/**
|
|
294
|
+
* 判断当前 Gateway 是否已完成停止。
|
|
295
|
+
*
|
|
296
|
+
* @returns 已释放租约且状态记录已清理时返回 true。
|
|
297
|
+
*/
|
|
298
|
+
private isStopped(): boolean {
|
|
299
|
+
return this.currentState === "stopped";
|
|
300
|
+
}
|
|
301
|
+
|
|
302
|
+
/**
|
|
303
|
+
* 持有租约期间定期更新 Gateway 状态并恢复已保存 route。
|
|
304
|
+
*
|
|
305
|
+
* @returns 无返回值。
|
|
306
|
+
*/
|
|
307
|
+
private async initialize(
|
|
308
|
+
onControlReady?: (lease: GatewayLease, registry: ManagerRegistry) => Promise<void>,
|
|
309
|
+
): Promise<void> {
|
|
310
|
+
await this.registry.setGateway(this.toGatewayRecord("starting"));
|
|
311
|
+
await this.uiWorkerManager.listen();
|
|
312
|
+
await onControlReady?.(this.lease, this.registry);
|
|
313
|
+
await this.recoverRoutes();
|
|
314
|
+
await this.channel.start((message) => this.router.acceptInbound(message));
|
|
315
|
+
if (this.currentState === "starting") {
|
|
316
|
+
await this.setState("online");
|
|
317
|
+
}
|
|
318
|
+
this.heartbeatTimer = setInterval(() => {
|
|
319
|
+
void this.refreshHeartbeat();
|
|
320
|
+
}, this.config.runtime.heartbeatIntervalMs);
|
|
321
|
+
this.heartbeatTimer.unref();
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
/**
|
|
325
|
+
* 清理遗留 owner 并恢复可安全重开的 background/UI route。
|
|
326
|
+
*
|
|
327
|
+
* @returns 无返回值。
|
|
328
|
+
* @throws {GatewayRuntimeError} 活跃 owner 或 registry 关系不一致时抛出。
|
|
329
|
+
*/
|
|
330
|
+
private async recoverRoutes(): Promise<void> {
|
|
331
|
+
const initial = await this.registry.readSnapshot();
|
|
332
|
+
for (const session of Object.values(initial.sessions)) {
|
|
333
|
+
if (!isValidSession(session, session.sessionId)) {
|
|
334
|
+
throw new GatewayRuntimeError(
|
|
335
|
+
"registry_inconsistent",
|
|
336
|
+
"session registry 字段不完整或状态不受支持; 保留原始数据并拒绝启动。",
|
|
337
|
+
);
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
const deadInstances: WorkerInstanceRecord[] = [];
|
|
342
|
+
const liveUiInstances: WorkerInstanceRecord[] = [];
|
|
343
|
+
const staleUiInstances: WorkerInstanceRecord[] = [];
|
|
344
|
+
for (const instance of Object.values(initial.instances)) {
|
|
345
|
+
if (!initial.sessions[instance.sessionId]) {
|
|
346
|
+
throw new GatewayRuntimeError(
|
|
347
|
+
"registry_inconsistent",
|
|
348
|
+
`worker ${instance.instanceId} 引用了不存在的 session 索引; 保留 registry 并拒绝启动。`,
|
|
349
|
+
);
|
|
350
|
+
}
|
|
351
|
+
if (!isProcessAlive(instance.pid)) {
|
|
352
|
+
deadInstances.push(instance);
|
|
353
|
+
} else if (instance.mode === "ui" && this.uiWorkerManager.isSupported) {
|
|
354
|
+
if (instance.state === "stale" || instance.state === "stopping") {
|
|
355
|
+
staleUiInstances.push(instance);
|
|
356
|
+
} else {
|
|
357
|
+
liveUiInstances.push(instance);
|
|
358
|
+
}
|
|
359
|
+
} else {
|
|
360
|
+
throw new GatewayRuntimeError(
|
|
361
|
+
"live_worker_detected",
|
|
362
|
+
`发现仍存活的 Pi worker PID ${instance.pid} (session ${instance.sessionId}); 为避免双 writer, Gateway 未启动。`,
|
|
363
|
+
);
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
const reattachResults = await Promise.allSettled(liveUiInstances.map((instance) =>
|
|
367
|
+
this.uiIpcServer.waitForReattach(instance.instanceId, this.config.runtime.staleAfterMs),
|
|
368
|
+
));
|
|
369
|
+
const failedReattach = reattachResults.find((result) => result.status === "rejected");
|
|
370
|
+
if (failedReattach?.status === "rejected") {
|
|
371
|
+
throw failedReattach.reason instanceof Error
|
|
372
|
+
? failedReattach.reason
|
|
373
|
+
: new GatewayRuntimeError("live_worker_detected", "活跃 UI worker 未能安全重连, Gateway 拒绝启动。");
|
|
374
|
+
}
|
|
375
|
+
await Promise.all(deadInstances.map((instance) =>
|
|
376
|
+
this.registry.removeInstance(instance.instanceId),
|
|
377
|
+
));
|
|
378
|
+
|
|
379
|
+
let snapshot = await this.registry.readSnapshot();
|
|
380
|
+
const activeOwnerSessionIds = new Set(
|
|
381
|
+
Object.values(snapshot.instances)
|
|
382
|
+
.filter((instance) => instance.state !== "stale" && instance.state !== "stopping")
|
|
383
|
+
.map((instance) => instance.sessionId),
|
|
384
|
+
);
|
|
385
|
+
const orphanedActiveSessions = Object.values(snapshot.sessions).filter((session) =>
|
|
386
|
+
session.state === "active" && !activeOwnerSessionIds.has(session.sessionId),
|
|
387
|
+
);
|
|
388
|
+
const normalizedSessions = await Promise.all(orphanedActiveSessions.map(async (session) => ({
|
|
389
|
+
...session,
|
|
390
|
+
state: await isPersistedSessionFile(session.sessionFile) ? "saved" as const : "pending" as const,
|
|
391
|
+
})));
|
|
392
|
+
await Promise.all(normalizedSessions.map((session) => this.registry.upsertSession(session)));
|
|
393
|
+
|
|
394
|
+
snapshot = await this.registry.readSnapshot();
|
|
395
|
+
const liveUiSessionIds = new Set(
|
|
396
|
+
Object.values(snapshot.instances)
|
|
397
|
+
.filter((instance) => instance.mode === "ui" && instance.state !== "stale" && instance.state !== "stopping")
|
|
398
|
+
.map((instance) => instance.sessionId),
|
|
399
|
+
);
|
|
400
|
+
const staleUiSessionIds = new Set(staleUiInstances.map((instance) => instance.sessionId));
|
|
401
|
+
const unownedUiSessions = Object.values(snapshot.sessions).filter((session) =>
|
|
402
|
+
session.mode === "ui" &&
|
|
403
|
+
!staleUiSessionIds.has(session.sessionId) &&
|
|
404
|
+
!liveUiSessionIds.has(session.sessionId),
|
|
405
|
+
);
|
|
406
|
+
await Promise.all(unownedUiSessions.map(async (session) =>
|
|
407
|
+
this.registry.upsertSession({
|
|
408
|
+
...session,
|
|
409
|
+
mode: "background",
|
|
410
|
+
state: await isPersistedSessionFile(session.sessionFile) ? "saved" : "pending",
|
|
411
|
+
}),
|
|
412
|
+
));
|
|
413
|
+
|
|
414
|
+
snapshot = await this.registry.readSnapshot();
|
|
415
|
+
const routeAnalyses = await Promise.all(Object.entries(snapshot.routes).map(async ([routeId, route]) => {
|
|
416
|
+
const session = snapshot.sessions[route.sessionId];
|
|
417
|
+
if (!session || !isValidRoute(route) || !isValidSession(session, route.sessionId)) {
|
|
418
|
+
throw new GatewayRuntimeError(
|
|
419
|
+
"registry_inconsistent",
|
|
420
|
+
`route ${routeId} 与 session registry 不一致; 保留绑定并拒绝启动。`,
|
|
421
|
+
);
|
|
422
|
+
}
|
|
423
|
+
const owner = snapshot.instances[route.workerInstanceId];
|
|
424
|
+
const ownerIsActive = Boolean(
|
|
425
|
+
owner &&
|
|
426
|
+
owner.sessionId === route.sessionId &&
|
|
427
|
+
owner.state !== "stale" &&
|
|
428
|
+
owner.state !== "stopping" &&
|
|
429
|
+
this.gatewayWorkerManager.hasAvailableOwner(owner),
|
|
430
|
+
);
|
|
431
|
+
const sessionFileExists = await isPersistedSessionFile(session.sessionFile);
|
|
432
|
+
return { routeId, route, session, ownerIsActive, sessionFileExists };
|
|
433
|
+
}));
|
|
434
|
+
|
|
435
|
+
const restorableRoutes = routeAnalyses.filter(({ session, ownerIsActive, sessionFileExists }) =>
|
|
436
|
+
!ownerIsActive &&
|
|
437
|
+
!staleUiSessionIds.has(session.sessionId) &&
|
|
438
|
+
sessionFileExists &&
|
|
439
|
+
(session.mode === "background" || this.uiWorkerManager.isSupported),
|
|
440
|
+
);
|
|
441
|
+
const unboundRoutes = routeAnalyses.filter(({ ownerIsActive, sessionFileExists, session }) =>
|
|
442
|
+
!ownerIsActive &&
|
|
443
|
+
!staleUiSessionIds.has(session.sessionId) &&
|
|
444
|
+
(!sessionFileExists || (session.mode === "ui" && !this.uiWorkerManager.isSupported)),
|
|
445
|
+
);
|
|
446
|
+
const missingTranscriptSessions = new Map(
|
|
447
|
+
unboundRoutes
|
|
448
|
+
.filter(({ session, sessionFileExists }) => !sessionFileExists && session.state !== "pending")
|
|
449
|
+
.map(({ session }) => [session.sessionId, { ...session, state: "pending" as const }]),
|
|
450
|
+
);
|
|
451
|
+
await Promise.all([
|
|
452
|
+
...[...missingTranscriptSessions.values()].map((session) => this.registry.upsertSession(session)),
|
|
453
|
+
...unboundRoutes.map(({ routeId }) => this.registry.setRoute(routeId, null)),
|
|
454
|
+
]);
|
|
455
|
+
|
|
456
|
+
const restorableBackgroundCount = restorableRoutes.filter(({ session }) =>
|
|
457
|
+
session.mode === "background",
|
|
458
|
+
).length;
|
|
459
|
+
if (restorableBackgroundCount > this.config.runtime.maxBackgroundWorkers) {
|
|
460
|
+
throw new GatewayRuntimeError(
|
|
461
|
+
"worker_capacity",
|
|
462
|
+
`可恢复 background route 数量超过 worker 上限 ${this.config.runtime.maxBackgroundWorkers}; Gateway 未启动。`,
|
|
463
|
+
);
|
|
464
|
+
}
|
|
465
|
+
const restoreOutcomes = await Promise.allSettled(
|
|
466
|
+
restorableRoutes.map((candidate) => this.restoreRoute(candidate)),
|
|
467
|
+
);
|
|
468
|
+
const failedRestore = restoreOutcomes.find((outcome) => outcome.status === "rejected");
|
|
469
|
+
if (failedRestore?.status === "rejected") {
|
|
470
|
+
if (failedRestore.reason instanceof Error) {
|
|
471
|
+
throw failedRestore.reason;
|
|
472
|
+
}
|
|
473
|
+
throw new GatewayRuntimeError(
|
|
474
|
+
"registry_inconsistent",
|
|
475
|
+
"至少一个已保存 route 无法安全恢复; Gateway 未启动。",
|
|
476
|
+
);
|
|
477
|
+
}
|
|
478
|
+
await this.registry.appendEvent("gateway.recovered", {
|
|
479
|
+
staleWorkerCount: deadInstances.length,
|
|
480
|
+
staleUiWorkerCount: staleUiInstances.length,
|
|
481
|
+
reattachedUiWorkerCount: liveUiInstances.length,
|
|
482
|
+
resumedRouteCount: restorableRoutes.length,
|
|
483
|
+
unboundRouteCount: unboundRoutes.length,
|
|
484
|
+
});
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
/**
|
|
488
|
+
* 恢复一个已验证的 Pi session 并更新 route owner generation。
|
|
489
|
+
*
|
|
490
|
+
* @param candidate 已验证 session 文件存在的 route 候选项。
|
|
491
|
+
* @returns 无返回值。
|
|
492
|
+
* @throws {GatewayRuntimeError} Pi worker owner 无法写回 registry 时抛出。
|
|
493
|
+
*/
|
|
494
|
+
private async restoreRoute(candidate: {
|
|
495
|
+
routeId: string;
|
|
496
|
+
route: RouteRecord;
|
|
497
|
+
session: SessionIndexRecord;
|
|
498
|
+
}): Promise<void> {
|
|
499
|
+
const { routeId, route, session } = candidate;
|
|
500
|
+
if (session.state !== "saved") {
|
|
501
|
+
await this.registry.upsertSession({ ...session, state: "saved" });
|
|
502
|
+
}
|
|
503
|
+
const resumed = await this.gatewayWorkerManager.resume(session.sessionId, session.mode);
|
|
504
|
+
const afterResume = await this.registry.readSnapshot();
|
|
505
|
+
const owner = Object.values(afterResume.instances).find((instance) =>
|
|
506
|
+
instance.sessionId === resumed.sessionId,
|
|
507
|
+
);
|
|
508
|
+
if (!owner) {
|
|
509
|
+
throw new GatewayRuntimeError(
|
|
510
|
+
"registry_inconsistent",
|
|
511
|
+
`恢复 session ${resumed.sessionId} 后 registry 未记录 owner。`,
|
|
512
|
+
);
|
|
513
|
+
}
|
|
514
|
+
await this.registry.setRoute(routeId, {
|
|
515
|
+
...route,
|
|
516
|
+
workerInstanceId: owner.instanceId,
|
|
517
|
+
generation: route.generation + 1,
|
|
518
|
+
updatedAt: new Date().toISOString(),
|
|
519
|
+
});
|
|
520
|
+
await this.router.drainPending(routeId);
|
|
521
|
+
}
|
|
522
|
+
|
|
523
|
+
/**
|
|
524
|
+
* 停止轮询与 worker 并尽可能完成 registry 清理。
|
|
525
|
+
*
|
|
526
|
+
* @returns 无返回值。
|
|
527
|
+
* @throws {GatewayRuntimeError} 任一后台 worker 仍可能存活时抛出。
|
|
528
|
+
*/
|
|
529
|
+
private async stopInternal(): Promise<void> {
|
|
530
|
+
this.currentState = "stopping";
|
|
531
|
+
this.emit("status_change", this.currentState);
|
|
532
|
+
if (this.heartbeatTimer) {
|
|
533
|
+
clearInterval(this.heartbeatTimer);
|
|
534
|
+
this.heartbeatTimer = undefined;
|
|
535
|
+
}
|
|
536
|
+
let statusWriteFailed = false;
|
|
537
|
+
try {
|
|
538
|
+
await this.registry.setGateway(this.toGatewayRecord("stopping"));
|
|
539
|
+
} catch {
|
|
540
|
+
statusWriteFailed = true;
|
|
541
|
+
}
|
|
542
|
+
await this.channel.stop();
|
|
543
|
+
await this.queue.waitForIdle();
|
|
544
|
+
await this.uiWorkerManager.detachGateway();
|
|
545
|
+
try {
|
|
546
|
+
await this.gatewayWorkerManager.stopAll();
|
|
547
|
+
} catch {
|
|
548
|
+
throw new GatewayRuntimeError(
|
|
549
|
+
"worker_shutdown_failed",
|
|
550
|
+
"至少一个后台 Pi worker 未能优雅停止; Gateway lease 仍保留, 可重试 /wx stop。",
|
|
551
|
+
);
|
|
552
|
+
}
|
|
553
|
+
|
|
554
|
+
let registryCleanupError: unknown = statusWriteFailed ? new Error("status_write_failed") : undefined;
|
|
555
|
+
try {
|
|
556
|
+
await this.registry.appendEvent("gateway.stopped");
|
|
557
|
+
await this.registry.setGateway(null);
|
|
558
|
+
} catch (error) {
|
|
559
|
+
registryCleanupError = error;
|
|
560
|
+
}
|
|
561
|
+
await this.lease.release();
|
|
562
|
+
this.currentState = "stopped";
|
|
563
|
+
this.emit("status_change", this.currentState);
|
|
564
|
+
if (registryCleanupError) {
|
|
565
|
+
throw new GatewayRuntimeError(
|
|
566
|
+
"registry_inconsistent",
|
|
567
|
+
"Gateway 已停止并释放租约, 但状态文件清理未完成; 下次启动会重新校准。",
|
|
568
|
+
);
|
|
569
|
+
}
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
/**
|
|
573
|
+
* 更新 runtime 和 registry 的 Gateway 状态。
|
|
574
|
+
*
|
|
575
|
+
* @param state 新状态。
|
|
576
|
+
* @returns 无返回值。
|
|
577
|
+
*/
|
|
578
|
+
private async setState(state: GatewayRuntimeState): Promise<void> {
|
|
579
|
+
this.currentState = state;
|
|
580
|
+
this.emit("status_change", state);
|
|
581
|
+
if (state !== "stopped" && state !== "lease_lost") {
|
|
582
|
+
await this.registry.setGateway(this.toGatewayRecord(state));
|
|
583
|
+
}
|
|
584
|
+
}
|
|
585
|
+
|
|
586
|
+
/**
|
|
587
|
+
* 处理 iLink 返回 session expired, 停止继续轮询且保留 lease 供显式关闭。
|
|
588
|
+
*
|
|
589
|
+
* @returns 无返回值。
|
|
590
|
+
*/
|
|
591
|
+
private async markAuthRequired(): Promise<void> {
|
|
592
|
+
if (this.currentState !== "online" && this.currentState !== "starting") {
|
|
593
|
+
return;
|
|
594
|
+
}
|
|
595
|
+
try {
|
|
596
|
+
await this.setState("auth_required");
|
|
597
|
+
await this.registry.appendEvent("channel.session_expired");
|
|
598
|
+
} catch {
|
|
599
|
+
await this.handleLeaseLoss();
|
|
600
|
+
}
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
/**
|
|
604
|
+
* 更新 Gateway owner 心跳。
|
|
605
|
+
*
|
|
606
|
+
* @returns 无返回值。
|
|
607
|
+
*/
|
|
608
|
+
private async refreshHeartbeat(): Promise<void> {
|
|
609
|
+
if (this.currentState !== "online" && this.currentState !== "auth_required") {
|
|
610
|
+
return;
|
|
611
|
+
}
|
|
612
|
+
try {
|
|
613
|
+
const heartbeatAt = await this.lease.heartbeat();
|
|
614
|
+
await this.registry.setGateway({
|
|
615
|
+
...this.toGatewayRecord(this.currentState),
|
|
616
|
+
heartbeatAt,
|
|
617
|
+
});
|
|
618
|
+
} catch {
|
|
619
|
+
await this.handleLeaseLoss();
|
|
620
|
+
}
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
/**
|
|
624
|
+
* 失去 owner 租约后停止所有外部处理, 不触碰被替换的新 owner 锁。
|
|
625
|
+
*
|
|
626
|
+
* @returns 无返回值。
|
|
627
|
+
*/
|
|
628
|
+
private async handleLeaseLoss(): Promise<void> {
|
|
629
|
+
if (this.currentState === "lease_lost" || this.currentState === "stopped") {
|
|
630
|
+
return;
|
|
631
|
+
}
|
|
632
|
+
if (this.heartbeatTimer) {
|
|
633
|
+
clearInterval(this.heartbeatTimer);
|
|
634
|
+
this.heartbeatTimer = undefined;
|
|
635
|
+
}
|
|
636
|
+
this.currentState = "lease_lost";
|
|
637
|
+
this.emit("status_change", this.currentState);
|
|
638
|
+
await this.channel.stop().catch(() => undefined);
|
|
639
|
+
await this.queue.waitForIdle().catch(() => undefined);
|
|
640
|
+
await this.gatewayWorkerManager.stopAll().catch(() => undefined);
|
|
641
|
+
await this.uiWorkerManager.detachGateway().catch(() => undefined);
|
|
642
|
+
await this.lease.release().catch(() => undefined);
|
|
643
|
+
}
|
|
644
|
+
|
|
645
|
+
/**
|
|
646
|
+
* 将当前状态组装为 registry Gateway 记录。
|
|
647
|
+
*
|
|
648
|
+
* @param state 要写入的状态。
|
|
649
|
+
* @returns 含 owner 和心跳信息的 Gateway 记录。
|
|
650
|
+
*/
|
|
651
|
+
private toGatewayRecord(state: Exclude<GatewayRuntimeState, "stopped" | "lease_lost">): GatewayStatusRecord {
|
|
652
|
+
const heartbeatAt = new Date().toISOString();
|
|
653
|
+
return {
|
|
654
|
+
ownerId: this.lease.ownerId,
|
|
655
|
+
pid: this.lease.pid,
|
|
656
|
+
processBirthId: this.lease.processBirthId,
|
|
657
|
+
startedAt: this.startedAt,
|
|
658
|
+
heartbeatAt,
|
|
659
|
+
state,
|
|
660
|
+
};
|
|
661
|
+
}
|
|
662
|
+
}
|
|
663
|
+
|
|
664
|
+
/**
|
|
665
|
+
* 判断 Pi session transcript 文件是否存在且为普通文件。
|
|
666
|
+
*
|
|
667
|
+
* @param sessionFile Pi 返回的 JSONL 文件路径。
|
|
668
|
+
* @returns 文件可恢复时返回 true。
|
|
669
|
+
*/
|
|
670
|
+
async function isPersistedSessionFile(sessionFile: string): Promise<boolean> {
|
|
671
|
+
try {
|
|
672
|
+
return (await stat(sessionFile)).isFile();
|
|
673
|
+
} catch (error) {
|
|
674
|
+
if (isNodeError(error) && error.code === "ENOENT") {
|
|
675
|
+
return false;
|
|
676
|
+
}
|
|
677
|
+
throw error;
|
|
678
|
+
}
|
|
679
|
+
}
|
|
680
|
+
|
|
681
|
+
/**
|
|
682
|
+
* 验证 session registry 的关键恢复字段。
|
|
683
|
+
*
|
|
684
|
+
* @param session 待校验 session 记录。
|
|
685
|
+
* @param expectedSessionId 当前 route 或 worker 声明的 session ID。
|
|
686
|
+
* @returns 记录完整且状态值受支持时返回 true。
|
|
687
|
+
*/
|
|
688
|
+
function isValidSession(session: SessionIndexRecord, expectedSessionId: string): boolean {
|
|
689
|
+
return typeof expectedSessionId === "string" &&
|
|
690
|
+
expectedSessionId.length > 0 &&
|
|
691
|
+
session.sessionId === expectedSessionId &&
|
|
692
|
+
typeof session.sessionFile === "string" &&
|
|
693
|
+
session.sessionFile.length > 0 &&
|
|
694
|
+
typeof session.cwd === "string" &&
|
|
695
|
+
session.cwd.length > 0 &&
|
|
696
|
+
typeof session.projectAlias === "string" &&
|
|
697
|
+
session.projectAlias.length > 0 &&
|
|
698
|
+
(session.mode === "background" || session.mode === "ui") &&
|
|
699
|
+
(session.state === "active" || session.state === "saved" || session.state === "pending") &&
|
|
700
|
+
typeof session.lastActivityAt === "string";
|
|
701
|
+
}
|
|
702
|
+
|
|
703
|
+
/**
|
|
704
|
+
* 验证 route registry 中的 session ID、worker ID 与 generation。
|
|
705
|
+
*
|
|
706
|
+
* @param route route 状态记录。
|
|
707
|
+
* @returns 字段满足恢复约束时返回 true。
|
|
708
|
+
*/
|
|
709
|
+
function isValidRoute(route: RouteRecord): boolean {
|
|
710
|
+
return typeof route.sessionId === "string" &&
|
|
711
|
+
route.sessionId.length > 0 &&
|
|
712
|
+
typeof route.workerInstanceId === "string" &&
|
|
713
|
+
route.workerInstanceId.length > 0 &&
|
|
714
|
+
Number.isInteger(route.generation) &&
|
|
715
|
+
route.generation >= 0;
|
|
716
|
+
}
|
|
717
|
+
|
|
718
|
+
/**
|
|
719
|
+
* 判断值是否为 Node.js 文件系统错误。
|
|
720
|
+
*
|
|
721
|
+
* @param error 待检查值。
|
|
722
|
+
* @returns 值包含 Node.js 错误代码时返回 true。
|
|
723
|
+
*/
|
|
724
|
+
function isNodeError(error: unknown): error is NodeJS.ErrnoException {
|
|
725
|
+
return error instanceof Error && "code" in error;
|
|
726
|
+
}
|