@hjd-hitsz/claudex-web 4.1.5 → 4.2.1

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 (82) hide show
  1. package/.env.example +2 -0
  2. package/CHANGELOG.md +57 -0
  3. package/README.md +16 -4
  4. package/bin/auth.mjs +86 -0
  5. package/bin/claudex-web.mjs +20 -0
  6. package/bin/p2p.mjs +134 -0
  7. package/build-info.json +4 -4
  8. package/client/dist/app.js +154 -122
  9. package/client/dist/code-highlight-style.js +23 -45
  10. package/client/dist/document-editor.js +54 -54
  11. package/client/dist/file-panel.js +5 -5
  12. package/client/dist/notification-worker.js +2 -1
  13. package/client/dist/p2p-sw.js +162 -0
  14. package/client/dist/style.css +1 -1
  15. package/client/dist/terminal-panel.js +11 -11
  16. package/docs/architecture/backends.md +11 -2
  17. package/docs/architecture/behavior.md +173 -59
  18. package/docs/architecture.md +36 -339
  19. package/docs/background-tasks.md +32 -26
  20. package/docs/deployment.md +53 -12
  21. package/docs/development.md +121 -149
  22. package/docs/images/desktop-dark.png +0 -0
  23. package/docs/images/desktop-light.png +0 -0
  24. package/docs/images/mobile-sidebar.png +0 -0
  25. package/docs/images/mobile.png +0 -0
  26. package/docs/releases/v4.2.0.md +15 -0
  27. package/docs/releases/v4.2.1.md +15 -0
  28. package/docs/versioning.md +15 -5
  29. package/package.json +9 -2
  30. package/packages/background-terminal/LICENSE +674 -0
  31. package/packages/background-terminal/README.md +17 -0
  32. package/packages/background-terminal/background-jobs.mjs +457 -0
  33. package/packages/background-terminal/background-mcp.mjs +79 -0
  34. package/packages/background-terminal/background-protocol.mjs +90 -0
  35. package/packages/background-terminal/cli.mjs +14 -0
  36. package/packages/background-terminal/client.mjs +61 -0
  37. package/packages/background-terminal/codex.mjs +88 -0
  38. package/packages/background-terminal/delivery.mjs +194 -0
  39. package/packages/background-terminal/log.mjs +25 -0
  40. package/packages/background-terminal/native-watches.mjs +160 -0
  41. package/packages/background-terminal/package.json +15 -0
  42. package/packages/background-terminal/service.mjs +126 -0
  43. package/packages/translation-engine/package.json +1 -1
  44. package/server/src/application.mjs +82 -10
  45. package/server/src/auth-http.mjs +187 -0
  46. package/server/src/auth-login.mjs +144 -0
  47. package/server/src/auth-totp.mjs +233 -0
  48. package/server/src/auth.mjs +169 -220
  49. package/server/src/backends/claude/background-tasks.mjs +88 -35
  50. package/server/src/backends/claude/messages.mjs +1 -1
  51. package/server/src/backends/claude/worker-client.mjs +47 -35
  52. package/server/src/backends/claude/worker-lines.mjs +17 -0
  53. package/server/src/backends/claude/worker-server.mjs +49 -69
  54. package/server/src/backends/codex/adapter.mjs +57 -7
  55. package/server/src/backends/codex/background-service.mjs +85 -0
  56. package/server/src/backends/codex/background-task-views.mjs +87 -0
  57. package/server/src/backends/codex/background-terminals.mjs +103 -0
  58. package/server/src/backends/codex/events.mjs +25 -1
  59. package/server/src/backends/codex/methods.mjs +1 -0
  60. package/server/src/backends/codex/native-background-handoff.mjs +72 -0
  61. package/server/src/backends/codex/requests.mjs +67 -38
  62. package/server/src/backends/codex/streaming-messages.mjs +50 -0
  63. package/server/src/backends/codex/subscriptions.mjs +34 -4
  64. package/server/src/backends/configuration.mjs +8 -0
  65. package/server/src/backends/manager.mjs +34 -32
  66. package/server/src/backends/storage.mjs +3 -14
  67. package/server/src/config.mjs +13 -0
  68. package/server/src/http/business.mjs +21 -0
  69. package/server/src/http/router.mjs +12 -25
  70. package/server/src/p2p/http.mjs +136 -0
  71. package/server/src/p2p/peers.mjs +132 -0
  72. package/server/src/p2p/service.mjs +229 -0
  73. package/server/src/p2p/storage.mjs +45 -0
  74. package/server/src/p2p/tunnel.mjs +95 -0
  75. package/server/src/p2p-http.mjs +149 -0
  76. package/server/src/p2p-peer.mjs +135 -0
  77. package/server/src/private-file.mjs +14 -0
  78. package/server/src/summary-translation.mjs +1 -1
  79. package/server/src/thread-folders.mjs +3 -13
  80. package/server/src/translation-service.mjs +3 -8
  81. package/shared/codex-preferences.mjs +9 -0
  82. package/shared/p2p-wire.mjs +157 -0
@@ -0,0 +1,17 @@
1
+ # Codex background terminal
2
+
3
+ A Linux stdio MCP extension for a local Codex app-server. Requires Node.js 24.5 or newer. Start the service under the same user as Codex, using a private state directory and the app-server's loopback WebSocket URL.
4
+
5
+ ```bash
6
+ state_dir="${XDG_STATE_HOME:-$HOME/.local/state}/codex-background-terminal"
7
+ codex-background-terminal serve "$state_dir" ws://127.0.0.1:8765
8
+ ```
9
+
10
+ In a second shell, register the MCP entry point for the same app-server.
11
+
12
+ ```bash
13
+ state_dir="${XDG_STATE_HOME:-$HOME/.local/state}/codex-background-terminal"
14
+ codex mcp add claudex_background -- codex-background-terminal mcp "$state_dir"
15
+ ```
16
+
17
+ The server uses the calling thread's full-access permission and working directory. Each thread can start, list, read and cancel its own jobs. Finishing jobs wake the originating thread through the app-server. Keep the service running while jobs execute. For a supervised deployment, run the service in its own systemd unit with the default control-group kill mode.
@@ -0,0 +1,457 @@
1
+ import { spawn } from "node:child_process";
2
+ import { randomUUID } from "node:crypto";
3
+ import {
4
+ appendFile,
5
+ mkdir,
6
+ open,
7
+ readFile,
8
+ readdir,
9
+ rename,
10
+ writeFile,
11
+ } from "node:fs/promises";
12
+ import { join } from "node:path";
13
+ import { userInfo } from "node:os";
14
+ import { readTaskLog } from "./log.mjs";
15
+ import { validateBackgroundArguments } from "./background-protocol.mjs";
16
+
17
+ const LOG_LIMIT = 64 * 1024 * 1024;
18
+ const terminal = (job) => job.status !== "running";
19
+
20
+ export async function createBackgroundJobs({
21
+ directory,
22
+ readThread,
23
+ terminateNative,
24
+ shell = process.env.SHELL || userInfo().shell || "/bin/sh",
25
+ }) {
26
+ await mkdir(directory, { recursive: true, mode: 0o700 });
27
+ const jobs = new Map(),
28
+ children = new Map(),
29
+ completions = new Map(),
30
+ terminations = new Map(),
31
+ writes = new Map(),
32
+ starting = new Map();
33
+ const batches = new Map();
34
+ let closing = false;
35
+ const save = (kind, id, value) => {
36
+ const key = kind + id;
37
+ const snapshot = JSON.stringify(value);
38
+ const next = (writes.get(key) || Promise.resolve())
39
+ .catch(() => {})
40
+ .then(async () => {
41
+ const file = join(directory, `${kind}-${id}.json`);
42
+ await writeFile(file + ".tmp", snapshot, { mode: 0o600 });
43
+ await rename(file + ".tmp", file);
44
+ });
45
+ writes.set(key, next);
46
+ return next;
47
+ };
48
+ for (const name of await readdir(directory)) {
49
+ if (!/^(job|batch)-[\w-]+\.json$/.test(name)) continue;
50
+ const value = JSON.parse(await readFile(join(directory, name), "utf8"));
51
+ if (name.startsWith("batch-")) {
52
+ // preparing 尚未提交 Codex;sending 的结果须由投递服务读取历史核对。
53
+ if (value.status === "preparing") value.status = "pending";
54
+ if (value.status === "sending") value.status = "uncertain";
55
+ batches.set(value.id, value);
56
+ await save("batch", value.id, value);
57
+ } else {
58
+ if (value.status === "running") {
59
+ value.status = "interrupted";
60
+ value.completedAt = Date.now();
61
+ value.error = "后台任务服务重启,原进程执行结果需要检查";
62
+ }
63
+ jobs.set(value.id, value);
64
+ await save("job", value.id, value);
65
+ }
66
+ }
67
+ for (const batch of batches.values())
68
+ for (const id of batch.jobIds) {
69
+ const job = jobs.get(id);
70
+ if (job && !["consumed", "suppressed"].includes(job.delivery)) {
71
+ job.delivery = batch.status;
72
+ await save("job", id, job);
73
+ }
74
+ }
75
+ const owned = (threadId, id) => {
76
+ const job = jobs.get(id);
77
+ if (!job || job.threadId !== threadId)
78
+ throw new Error("该对话中没有此后台任务");
79
+ return job;
80
+ };
81
+ const publicJob = (job) => ({ ...job, pid: undefined });
82
+ const list = (threadId) =>
83
+ [...jobs.values()]
84
+ .filter((job) => !threadId || job.threadId === threadId)
85
+ .sort((a, b) => b.startedAt - a.startedAt)
86
+ .map(publicJob);
87
+ const logPath = (job) => join(directory, `output-${job.id}.log`);
88
+ const read = async (threadId, id, offset) => {
89
+ const job = owned(threadId, id);
90
+ const output = await readTaskLog(logPath(job), offset);
91
+ return { job: publicJob(job), ...output };
92
+ };
93
+ const nativeLogSizes = new Map();
94
+ async function registerNative(threadId, turnId, item) {
95
+ const existing = [...jobs.values()].find(
96
+ (job) =>
97
+ job.threadId === threadId &&
98
+ job.native?.turnId === turnId &&
99
+ job.native.itemId === item.id,
100
+ );
101
+ if (existing) return publicJob(existing);
102
+ const job = {
103
+ id: randomUUID(),
104
+ threadId,
105
+ native: { turnId, itemId: item.id, processId: item.processId },
106
+ cwd: item.cwd,
107
+ command: item.command,
108
+ title: item.command,
109
+ startedAt: item.startedAtMs ?? Date.now(),
110
+ completedAt: null,
111
+ status: "running",
112
+ exitCode: null,
113
+ delivery: "pending",
114
+ logTruncated: false,
115
+ };
116
+ await writeFile(logPath(job), "", { mode: 0o600, flag: "wx" });
117
+ await save("job", job.id, job);
118
+ jobs.set(job.id, job);
119
+ return publicJob(job);
120
+ }
121
+ async function appendNative(threadId, id, delta) {
122
+ const job = owned(threadId, id);
123
+ if (terminal(job)) return;
124
+ const size = nativeLogSizes.get(id) ?? 0;
125
+ const bytes = Buffer.from(delta);
126
+ const remaining = LOG_LIMIT - size;
127
+ if (bytes.length > remaining) job.logTruncated = true;
128
+ if (remaining <= 0) return;
129
+ const output = bytes.subarray(0, remaining);
130
+ await appendFile(logPath(job), output);
131
+ nativeLogSizes.set(id, size + output.length);
132
+ }
133
+ async function finishNative(threadId, id, item) {
134
+ const job = owned(threadId, id);
135
+ if (job.completedAt) return;
136
+ if (typeof item.aggregatedOutput === "string")
137
+ await writeFile(logPath(job), item.aggregatedOutput);
138
+ nativeLogSizes.delete(id);
139
+ job.completedAt = item.completedAtMs ?? Date.now();
140
+ job.exitCode = item.exitCode ?? null;
141
+ if (job.status === "running")
142
+ job.status = item.status === "completed" ? "succeeded" : item.status;
143
+ await save("job", id, job);
144
+ }
145
+ const start = async (threadId, callId, args) => {
146
+ if (closing) throw new Error("后台任务服务正在停止");
147
+ if (!callId || typeof callId !== "string")
148
+ throw new Error("后台任务缺少工具调用标识");
149
+ const key = JSON.stringify([threadId, callId]);
150
+ if (starting.has(key)) return starting.get(key);
151
+ const duplicate = [...jobs.values()].find(
152
+ (job) => job.threadId === threadId && job.callId === callId,
153
+ );
154
+ if (duplicate)
155
+ return { job: publicJob(duplicate), completion_delivery: "automatic" };
156
+ const work = (async () => {
157
+ const thread = await readThread(threadId);
158
+ if (
159
+ !thread?.cwd ||
160
+ thread.archived ||
161
+ thread.path?.replaceAll("\\", "/").includes("/archived_sessions/")
162
+ )
163
+ throw new Error("后台任务所属对话不可用");
164
+ const job = {
165
+ id: randomUUID(),
166
+ threadId,
167
+ callId,
168
+ cwd: thread.cwd,
169
+ command: args.command,
170
+ title: args.title,
171
+ startedAt: Date.now(),
172
+ completedAt: null,
173
+ status: "running",
174
+ exitCode: null,
175
+ delivery: "pending",
176
+ logTruncated: false,
177
+ };
178
+ const logFile = await open(
179
+ join(directory, `output-${job.id}.log`),
180
+ "wx",
181
+ 0o600,
182
+ );
183
+ try {
184
+ await save("job", job.id, job);
185
+ } catch (error) {
186
+ await logFile.close();
187
+ throw error;
188
+ }
189
+ jobs.set(job.id, job);
190
+ let size = 0,
191
+ timedOut = false,
192
+ processError;
193
+ const log = logFile.createWriteStream();
194
+ log.on("error", (error) => {
195
+ processError = "保存日志失败:" + error.message;
196
+ stopProcess(job.id);
197
+ });
198
+ const child = spawn(shell, ["-lc", job.command], {
199
+ cwd: job.cwd,
200
+ detached: true,
201
+ stdio: ["ignore", "pipe", "pipe"],
202
+ });
203
+ job.pid = child.pid;
204
+ children.set(job.id, child);
205
+ const append = (stream, chunk) => {
206
+ const bytes = chunk.subarray(0, Math.max(0, LOG_LIMIT - size));
207
+ size += bytes.length;
208
+ if (bytes.length < chunk.length) job.logTruncated = true;
209
+ if (bytes.length && !log.write(bytes)) {
210
+ stream.pause();
211
+ log.once("drain", () => stream.resume());
212
+ }
213
+ };
214
+ child.stdout.on("data", (chunk) => append(child.stdout, chunk));
215
+ child.stderr.on("data", (chunk) => append(child.stderr, chunk));
216
+ child.on("error", (error) => {
217
+ processError = error.message;
218
+ });
219
+ const timeout = args.timeout_ms
220
+ ? setTimeout(() => {
221
+ timedOut = true;
222
+ stopProcess(job.id);
223
+ }, args.timeout_ms)
224
+ : null;
225
+ let complete;
226
+ const completion = new Promise((resolve) => (complete = resolve));
227
+ completions.set(job.id, completion);
228
+ child.on("close", async (code, signal) => {
229
+ clearTimeout(timeout);
230
+ if (!log.destroyed)
231
+ await new Promise((resolve) => {
232
+ log.once("close", resolve);
233
+ log.end();
234
+ });
235
+ children.delete(job.id);
236
+ job.completedAt = Date.now();
237
+ job.exitCode = code;
238
+ job.signal = signal;
239
+ if (job.status === "running")
240
+ job.status = timedOut
241
+ ? "timed_out"
242
+ : processError
243
+ ? "failed"
244
+ : code === 0
245
+ ? "succeeded"
246
+ : "failed";
247
+ if (processError) job.error = processError;
248
+ await save("job", job.id, job).catch((error) =>
249
+ console.error("保存后台任务结果:", error.message),
250
+ );
251
+ completions.delete(job.id);
252
+ complete();
253
+ });
254
+ await save("job", job.id, job);
255
+ return { job: publicJob(job), completion_delivery: "automatic" };
256
+ })().finally(() => starting.delete(key));
257
+ starting.set(key, work);
258
+ return work;
259
+ };
260
+ function stopProcess(id) {
261
+ if (terminations.has(id)) return;
262
+ const child = children.get(id);
263
+ if (!child?.pid) return;
264
+ const kill = (signal) => {
265
+ try {
266
+ process.kill(-child.pid, signal);
267
+ } catch (error) {
268
+ if (error.code !== "ESRCH") throw error;
269
+ }
270
+ };
271
+ kill("SIGTERM");
272
+ let complete;
273
+ terminations.set(id, new Promise((resolve) => (complete = resolve)));
274
+ setTimeout(() => {
275
+ try {
276
+ kill("SIGKILL");
277
+ } finally {
278
+ terminations.delete(id);
279
+ complete();
280
+ }
281
+ }, 2000);
282
+ }
283
+ const cancel = async (threadId, id) => {
284
+ const job = owned(threadId, id);
285
+ job.delivery = "suppressed";
286
+ if (job.native && !terminal(job)) {
287
+ await save("job", id, job);
288
+ const result = await terminateNative(job);
289
+ if (result.terminated) job.status = "cancelled";
290
+ await save("job", id, job);
291
+ return { job: publicJob(job) };
292
+ }
293
+ if (!terminal(job)) {
294
+ job.status = "cancelled";
295
+ stopProcess(id);
296
+ }
297
+ await Promise.all([
298
+ save("job", id, job),
299
+ completions.get(id),
300
+ terminations.get(id),
301
+ ]);
302
+ return { job: publicJob(job) };
303
+ };
304
+ const pendingJobs = () =>
305
+ [...jobs.values()].filter(
306
+ (job) =>
307
+ terminal(job) &&
308
+ job.delivery === "pending" &&
309
+ job.status !== "cancelled",
310
+ );
311
+ return {
312
+ list,
313
+ read,
314
+ registerNative,
315
+ appendNative,
316
+ finishNative,
317
+ async tool({ name, args, threadId, callId }) {
318
+ validateBackgroundArguments(name, args);
319
+ if (typeof threadId !== "string" || !threadId)
320
+ throw new Error("缺少所属对话");
321
+ if (name === "background_start") return start(threadId, callId, args);
322
+ if (name === "background_read") {
323
+ const result = await read(threadId, args.job_id, args.offset);
324
+ const job = owned(threadId, args.job_id);
325
+ if (
326
+ terminal(job) &&
327
+ ["pending", "batched", "preparing"].includes(job.delivery)
328
+ ) {
329
+ job.delivery = "consumed";
330
+ await save("job", job.id, job);
331
+ for (const batch of batches.values())
332
+ if (
333
+ batch.jobIds.includes(job.id) &&
334
+ batch.jobIds.every((id) =>
335
+ ["consumed", "suppressed"].includes(jobs.get(id)?.delivery),
336
+ )
337
+ ) {
338
+ batch.status = "suppressed";
339
+ await save("batch", batch.id, batch);
340
+ }
341
+ result.job = publicJob(job);
342
+ }
343
+ return result;
344
+ }
345
+ if (name === "background_list") return { jobs: list(threadId) };
346
+ return cancel(threadId, args.job_id);
347
+ },
348
+ snapshot() {
349
+ return { jobs: list(), batches: [...batches.values()] };
350
+ },
351
+ async claim(threadId, owner) {
352
+ const existing = [...batches.values()].find(
353
+ (batch) =>
354
+ batch.threadId === threadId &&
355
+ ["pending", "preparing"].includes(batch.status),
356
+ );
357
+ if (existing) {
358
+ if (
359
+ existing.status === "preparing" &&
360
+ existing.owner !== owner &&
361
+ Date.now() - existing.updatedAt < 120000
362
+ )
363
+ return null;
364
+ if (existing.status === "preparing") existing.status = "pending";
365
+ if (existing.status !== "pending") return null;
366
+ existing.owner = owner;
367
+ existing.status = "preparing";
368
+ existing.updatedAt = Date.now();
369
+ await save("batch", existing.id, existing);
370
+ return existing;
371
+ }
372
+ const selected = pendingJobs()
373
+ .filter((job) => job.threadId === threadId)
374
+ .slice(0, 8);
375
+ if (!selected.length) return null;
376
+ const batch = {
377
+ id: randomUUID(),
378
+ threadId,
379
+ jobIds: selected.map((job) => job.id),
380
+ owner,
381
+ status: "preparing",
382
+ updatedAt: Date.now(),
383
+ };
384
+ batches.set(batch.id, batch);
385
+ await save("batch", batch.id, batch);
386
+ for (const job of selected) {
387
+ if (["consumed", "suppressed"].includes(job.delivery)) continue;
388
+ job.delivery = "batched";
389
+ await save("job", job.id, job);
390
+ }
391
+ return batch;
392
+ },
393
+ async updateBatch({ id, status, error, turnId, owner }) {
394
+ const batch = batches.get(id);
395
+ if (!batch) throw new Error("后台完成通知不存在");
396
+ if (owner && batch.owner !== owner)
397
+ throw new Error("后台完成通知已由另一服务处理");
398
+ if (
399
+ !["pending", "sending", "accepted", "uncertain", "suppressed"].includes(
400
+ status,
401
+ )
402
+ )
403
+ throw new Error("无效投递状态");
404
+ if (["accepted", "suppressed"].includes(batch.status)) return batch;
405
+ if (status === "sending") {
406
+ batch.attemptedAt = Date.now();
407
+ batch.deliveryJobIds = batch.jobIds.filter(
408
+ (jobId) =>
409
+ !["consumed", "suppressed"].includes(jobs.get(jobId)?.delivery),
410
+ );
411
+ if (!batch.deliveryJobIds.length) status = "suppressed";
412
+ }
413
+ Object.assign(batch, { status, error, turnId, updatedAt: Date.now() });
414
+ for (const jobId of batch.jobIds) {
415
+ const job = jobs.get(jobId);
416
+ if (job && !["suppressed", "consumed"].includes(job.delivery)) {
417
+ job.delivery = status;
418
+ job.deliveryError = error;
419
+ await save("job", job.id, job);
420
+ }
421
+ }
422
+ await save("batch", id, batch);
423
+ return batch;
424
+ },
425
+ async suppressThread(threadId, cancelRunning = false) {
426
+ for (const job of jobs.values())
427
+ if (job.threadId === threadId) {
428
+ if (cancelRunning) await cancel(threadId, job.id);
429
+ else {
430
+ job.delivery = "suppressed";
431
+ await save("job", job.id, job);
432
+ }
433
+ }
434
+ for (const batch of batches.values())
435
+ if (batch.threadId === threadId && batch.status !== "accepted") {
436
+ batch.status = "suppressed";
437
+ await save("batch", batch.id, batch);
438
+ }
439
+ return {};
440
+ },
441
+ async close() {
442
+ closing = true;
443
+ await Promise.allSettled(starting.values());
444
+ for (const [id] of children) {
445
+ const job = jobs.get(id);
446
+ if (job.status === "running") {
447
+ job.status = "interrupted";
448
+ job.error = "后台任务服务已停止";
449
+ }
450
+ stopProcess(id);
451
+ }
452
+ await Promise.all(completions.values());
453
+ await Promise.all(terminations.values());
454
+ await Promise.all(writes.values());
455
+ },
456
+ };
457
+ }
@@ -0,0 +1,79 @@
1
+ import { createInterface } from "node:readline";
2
+ import {
3
+ BACKGROUND_INSTRUCTIONS,
4
+ BACKGROUND_TOOLS,
5
+ validateBackgroundArguments,
6
+ } from "./background-protocol.mjs";
7
+ import { taskRequest } from "./client.mjs";
8
+
9
+ const directory = process.argv[3];
10
+ const input = createInterface({ input: process.stdin });
11
+ for await (const line of input) {
12
+ let request;
13
+ try {
14
+ request = JSON.parse(line);
15
+ if (request?.id === undefined) continue;
16
+ let result;
17
+ if (request.method === "initialize") {
18
+ result = {
19
+ protocolVersion: request.params.protocolVersion,
20
+ capabilities: { tools: {} },
21
+ serverInfo: { name: "Codex 后台终端", version: "1" },
22
+ instructions: BACKGROUND_INSTRUCTIONS,
23
+ };
24
+ } else if (request.method === "ping") result = {};
25
+ else if (request.method === "tools/list")
26
+ result = { tools: BACKGROUND_TOOLS };
27
+ else if (
28
+ ["resources/list", "resources/templates/list", "prompts/list"].includes(
29
+ request.method,
30
+ )
31
+ )
32
+ result = { resources: [], resourceTemplates: [], prompts: [] };
33
+ else if (request.method === "tools/call") {
34
+ try {
35
+ const { name, arguments: args = {}, _meta: meta = {} } = request.params;
36
+ validateBackgroundArguments(name, args);
37
+ if (typeof meta.threadId !== "string" || !meta.threadId)
38
+ throw new Error("后台工具需要所属 Codex 对话");
39
+
40
+ const value = await taskRequest(directory, "tool", {
41
+ name,
42
+ args,
43
+ threadId: meta.threadId,
44
+ callId: meta.callId,
45
+ expectedUpstream: process.env.CLAUDEX_BACKGROUND_UPSTREAM,
46
+ });
47
+ result = {
48
+ content: [{ type: "text", text: JSON.stringify(value) }],
49
+ isError: false,
50
+ };
51
+ } catch (error) {
52
+ result = {
53
+ content: [{ type: "text", text: error.message }],
54
+ isError: true,
55
+ };
56
+ }
57
+ } else {
58
+ process.stdout.write(
59
+ JSON.stringify({
60
+ jsonrpc: "2.0",
61
+ id: request.id,
62
+ error: { code: -32601, message: "未知 MCP 方法" },
63
+ }) + "\n",
64
+ );
65
+ continue;
66
+ }
67
+ process.stdout.write(
68
+ JSON.stringify({ jsonrpc: "2.0", id: request.id, result }) + "\n",
69
+ );
70
+ } catch (error) {
71
+ process.stdout.write(
72
+ JSON.stringify({
73
+ jsonrpc: "2.0",
74
+ id: request?.id ?? null,
75
+ error: { code: request ? -32602 : -32700, message: error.message },
76
+ }) + "\n",
77
+ );
78
+ }
79
+ }
@@ -0,0 +1,90 @@
1
+ export const BACKGROUND_INSTRUCTIONS = [
2
+ "When background_start is available, use it as the initial execution call for a command you expect to take minutes, such as a large download or a lengthy build or test. Use foreground execution for quick commands.",
3
+ "If a foreground exec_command unexpectedly returns a running session ID, the same process can continue in the background. Do not restart it just to move it to the background.",
4
+ "Once the job is running, do only requested work that can actually proceed independently. If the next step depends on the result, give a brief status update in your final response and end this turn. Do not wait with sleep, poll the job or terminal, or fill the wait with unrelated work. The task service will automatically start a new turn with background_completed so you can continue.",
5
+ ].join("\n");
6
+
7
+ export const BACKGROUND_TURN_CONTEXT = {
8
+ claudex_background_execution: {
9
+ kind: "application",
10
+ value: BACKGROUND_INSTRUCTIONS,
11
+ },
12
+ };
13
+
14
+ const jobId = { type: "string", description: "后台工具返回的任务 ID" };
15
+ const tool = (name, description, properties, required = []) => ({
16
+ name,
17
+ description,
18
+ inputSchema: {
19
+ type: "object",
20
+ properties,
21
+ required,
22
+ additionalProperties: false,
23
+ },
24
+ });
25
+ export const BACKGROUND_TOOLS = [
26
+ tool(
27
+ "background_start",
28
+ "Start an expected minutes-long command directly in the background. Use this for large downloads and lengthy builds or tests. Returns immediately with a job ID. When subsequent work depends on the result, finish the turn after a brief status update. The job's completion automatically resumes the conversation.",
29
+ {
30
+ command: {
31
+ type: "string",
32
+ description: "在当前对话工作目录执行的 shell 命令",
33
+ },
34
+ title: { type: "string", description: "简短任务名称" },
35
+ timeout_ms: {
36
+ type: "integer",
37
+ minimum: 1,
38
+ maximum: 604800000,
39
+ description: "可选执行时限,单位毫秒",
40
+ },
41
+ },
42
+ ["command", "title"],
43
+ ),
44
+ tool(
45
+ "background_read",
46
+ "读取当前对话后台任务的状态和日志。按需读取,无需轮询等待结束。",
47
+ {
48
+ job_id: jobId,
49
+ offset: {
50
+ type: "integer",
51
+ minimum: 0,
52
+ description: "日志字节偏移;省略时读取末尾",
53
+ },
54
+ },
55
+ ["job_id"],
56
+ ),
57
+ tool("background_list", "列出当前对话的后台任务及完成结果投递状态。", {}),
58
+ tool(
59
+ "background_cancel",
60
+ "停止当前对话的指定后台任务及其子进程,并取消自动续跑。",
61
+ { job_id: jobId },
62
+ ["job_id"],
63
+ ),
64
+ ];
65
+
66
+ export function validateBackgroundArguments(name, args) {
67
+ const definition = BACKGROUND_TOOLS.find((entry) => entry.name === name);
68
+ if (!definition) throw new Error("未知后台工具");
69
+ if (!args || typeof args !== "object" || Array.isArray(args))
70
+ throw new Error("工具参数必须为对象");
71
+ for (const key of Object.keys(args))
72
+ if (!Object.hasOwn(definition.inputSchema.properties, key))
73
+ throw new Error("未知参数:" + key);
74
+ for (const key of definition.inputSchema.required)
75
+ if (typeof args[key] !== "string" || !args[key].trim())
76
+ throw new Error(key + " 必须为非空文字");
77
+ if (args.command?.length > 100000 || args.title?.length > 200)
78
+ throw new Error("命令或任务名称过长");
79
+ for (const [key, max] of [
80
+ ["offset", Number.MAX_SAFE_INTEGER],
81
+ ["timeout_ms", 604800000],
82
+ ])
83
+ if (
84
+ args[key] !== undefined &&
85
+ (!Number.isSafeInteger(args[key]) ||
86
+ args[key] < (key === "offset" ? 0 : 1) ||
87
+ args[key] > max)
88
+ )
89
+ throw new Error(key + " 超出有效范围");
90
+ }
@@ -0,0 +1,14 @@
1
+ #!/usr/bin/env node
2
+ import { resolve } from "node:path";
3
+ const [mode, state, upstream] = process.argv.slice(2);
4
+ if (mode === "serve" && state && upstream) {
5
+ const { serve } = await import("./service.mjs");
6
+ await serve(resolve(state), upstream);
7
+ } else if (mode === "mcp" && state && !upstream) {
8
+ await import("./background-mcp.mjs");
9
+ } else {
10
+ console.error(
11
+ "Usage: codex-background-terminal serve STATE_DIR ws://127.0.0.1:PORT | mcp STATE_DIR",
12
+ );
13
+ process.exitCode = 2;
14
+ }