@agentpro/scroll 0.0.0-stage → 2.5.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 (61) hide show
  1. package/AGENTS.md +55 -0
  2. package/LICENSE +21 -0
  3. package/README.md +293 -2
  4. package/SPEC.md +1079 -0
  5. package/bin/scroll.js +8 -0
  6. package/docs/prompt-caching.md +128 -0
  7. package/index.js +33 -0
  8. package/lib/audit.js +358 -0
  9. package/lib/auth.js +849 -0
  10. package/lib/chat-sdk/admin-controller.js +289 -0
  11. package/lib/chat-sdk/debouncer.js +94 -0
  12. package/lib/chat-sdk/group-grants.js +150 -0
  13. package/lib/chat-sdk/index.js +222 -0
  14. package/lib/chat-sdk/long-task-runner.js +413 -0
  15. package/lib/chat-session.js +1788 -0
  16. package/lib/chat-telemetry.js +557 -0
  17. package/lib/codex-app-server.js +851 -0
  18. package/lib/digest.js +112 -0
  19. package/lib/effects.js +157 -0
  20. package/lib/eval.js +408 -0
  21. package/lib/grounding.js +356 -0
  22. package/lib/installers.js +176 -0
  23. package/lib/knowledge.js +335 -0
  24. package/lib/ledger.js +38 -0
  25. package/lib/loop.js +197 -0
  26. package/lib/mcp-client.js +926 -0
  27. package/lib/memory-cli.js +66 -0
  28. package/lib/memory-tracker.js +1472 -0
  29. package/lib/memory.js +1279 -0
  30. package/lib/people-cli.js +81 -0
  31. package/lib/people.js +534 -0
  32. package/lib/permissions.js +272 -0
  33. package/lib/providers.js +1572 -0
  34. package/lib/runtime.js +928 -0
  35. package/lib/sandbox.js +744 -0
  36. package/lib/scheduler.js +402 -0
  37. package/lib/scroll.js +1225 -0
  38. package/lib/skill-cli.js +120 -0
  39. package/lib/skill-eval.js +156 -0
  40. package/lib/skills.js +860 -0
  41. package/lib/style.js +126 -0
  42. package/lib/tool-retriever.js +489 -0
  43. package/lib/tools.js +1833 -0
  44. package/lib/user.js +711 -0
  45. package/lib/vault.js +151 -0
  46. package/package.json +88 -4
  47. package/templates/agent/IDENTITY.md +56 -0
  48. package/templates/agent/SOUL.md +23 -0
  49. package/templates/agent/TOOLS.md +25 -0
  50. package/templates/agent/evals/case-02-citation-discipline.md +29 -0
  51. package/templates/agent/evals/case-03-boundary.md +27 -0
  52. package/templates/agent/evals/case-example.md +43 -0
  53. package/templates/agent/hard-rules.md +11 -0
  54. package/templates/agent/memory/lessons.md +5 -0
  55. package/templates/agent/memory/log/.gitkeep +0 -0
  56. package/templates/external-safety-contract.md +5 -0
  57. package/templates/long-task-planner.md +17 -0
  58. package/templates/work/LOOP.md +37 -0
  59. package/templates/work/WORK.md +50 -0
  60. package/types/chat.d.ts +61 -0
  61. package/types/index.d.ts +112 -0
@@ -0,0 +1,851 @@
1
+ // SCROLL 2.0 -- §46 Persistent Codex App-Server JSON-RPC 2.0 stdio client.
2
+ //
3
+ // Why: spawning `codex exec` cold per chat turn incurs ~1.5-3s startup overhead and loses
4
+ // thread continuity. `codex app-server --listen stdio://` keeps a single persistent JSON-RPC
5
+ // daemon that natively manages Sign in with ChatGPT OAuth (`account/read`, `account/login/start`),
6
+ // rate limits (`account/rateLimits/read`), model discovery (`model/list`), and streaming turns
7
+ // (`thread/start`, `turn/start`, `item/agentMessage/delta`, `turn/interrupt`).
8
+ //
9
+ // Zero runtime dependencies. Node >= 20 built-ins only.
10
+ import fs from 'node:fs';
11
+ import os from 'node:os';
12
+ import path from 'node:path';
13
+ import crypto from 'node:crypto';
14
+ import readline from 'node:readline';
15
+ import { spawn, spawnSync } from 'node:child_process';
16
+
17
+ const MAX_INLINE_IMAGE_BYTES = 12 * 1024 * 1024;
18
+
19
+ function extForImageMime(mimeType) {
20
+ const m = String(mimeType || '').toLowerCase();
21
+ if (m.includes('png')) return '.png';
22
+ if (m.includes('webp')) return '.webp';
23
+ if (m.includes('gif')) return '.gif';
24
+ return '.jpg';
25
+ }
26
+
27
+ function writeTempImageBase64(b64, mimeType) {
28
+ const clean = String(b64 || '').replace(/^data:[^;]+;base64,/i, '').trim();
29
+ if (!clean) throw new Error('codex_image_base64_empty');
30
+ const buf = Buffer.from(clean, 'base64');
31
+ if (buf.length === 0) throw new Error('codex_image_base64_empty');
32
+ if (buf.length > MAX_INLINE_IMAGE_BYTES) {
33
+ throw new Error(`codex_image_exceeds_max_bytes:${buf.length}>${MAX_INLINE_IMAGE_BYTES}`);
34
+ }
35
+ const tmpPath = path.join(
36
+ os.tmpdir(),
37
+ `scroll-vision-${process.pid}-${crypto.randomBytes(8).toString('hex')}${extForImageMime(mimeType)}`
38
+ );
39
+ fs.writeFileSync(tmpPath, buf, { mode: 0o600 });
40
+ return tmpPath;
41
+ }
42
+
43
+ function isExecutableFile(p) {
44
+ if (!p) return false;
45
+ try {
46
+ const st = fs.statSync(p);
47
+ return st.isFile();
48
+ } catch {
49
+ return false;
50
+ }
51
+ }
52
+
53
+ export function findCodexBinary({ command = null, searchPaths = [], env = process.env } = {}) {
54
+ const direct = [command, env.CODEX_APP_SERVER_BIN, env.CODEX_CLI].filter(Boolean);
55
+ for (const cand of direct) {
56
+ if (cand.includes('/') && isExecutableFile(cand)) return cand;
57
+ if (!cand.includes('/')) {
58
+ const r = spawnSync('bash', ['-lc', `command -v ${JSON.stringify(cand)}`], { encoding: 'utf8' });
59
+ if (r.status === 0 && r.stdout.trim()) return r.stdout.trim();
60
+ }
61
+ }
62
+ for (const cand of searchPaths || []) {
63
+ if (isExecutableFile(cand)) return cand;
64
+ }
65
+ const onPath = spawnSync('bash', ['-lc', 'command -v codex'], { encoding: 'utf8' });
66
+ if (onPath.status === 0 && onPath.stdout.trim()) return onPath.stdout.trim();
67
+ return null;
68
+ }
69
+
70
+ export function createCodexAppServerClient({
71
+ command = null,
72
+ args = null,
73
+ searchPaths = [],
74
+ cwd = process.cwd(),
75
+ env = process.env,
76
+ timeoutMs = 120_000,
77
+ clientInfo = { name: 'scroll-runtime', version: '2.0.0' },
78
+ defaultModel = null,
79
+ disableBuiltinTools = true,
80
+ maxRestarts = 2,
81
+ } = {}) {
82
+ let proc = null;
83
+ let rl = null;
84
+ let started = false;
85
+ let startPromise = null;
86
+ let closing = false;
87
+ let nextId = 1;
88
+ let restartCount = 0;
89
+ let cachedModels = null;
90
+ let stderrTail = '';
91
+
92
+ const pending = new Map();
93
+ const notificationListeners = new Set();
94
+ // Active turn-bound tool handlers: threadId -> { turnId, handler, signal, closed, completedCalls, inflightCalls, pendingCalls }
95
+ const activeTurnBindings = new Map();
96
+ // Completed/aborted turn IDs per thread so late RPCs from an earlier turn can NEVER bind to a new turn
97
+ const finishedTurnIdsByThread = new Map();
98
+
99
+ function markTurnFinished(threadId, tid) {
100
+ if (!threadId || !tid) return;
101
+ let set = finishedTurnIdsByThread.get(threadId);
102
+ if (!set) {
103
+ set = new Set();
104
+ finishedTurnIdsByThread.set(threadId, set);
105
+ }
106
+ set.add(String(tid));
107
+ if (set.size > 64) {
108
+ const first = set.values().next().value;
109
+ set.delete(first);
110
+ }
111
+ }
112
+
113
+ function resolvedBinary() {
114
+ return findCodexBinary({ command, searchPaths, env });
115
+ }
116
+
117
+ function buildArgs() {
118
+ if (Array.isArray(args)) return [...args];
119
+ const base = ['app-server', '--listen', 'stdio://'];
120
+ if (disableBuiltinTools) base.push('-c', 'apps._default.default_tools_enabled=false');
121
+ return base;
122
+ }
123
+
124
+ function onNotification(fn) {
125
+ notificationListeners.add(fn);
126
+ return () => notificationListeners.delete(fn);
127
+ }
128
+
129
+ function rejectAllPending(err) {
130
+ for (const [, entry] of pending) {
131
+ clearTimeout(entry.timer);
132
+ entry.reject(err);
133
+ }
134
+ pending.clear();
135
+ }
136
+
137
+ function sendToolResult(id, text, ok) {
138
+ try {
139
+ sendRaw({
140
+ jsonrpc: '2.0',
141
+ id,
142
+ result: {
143
+ contentItems: [{ type: 'inputText', text }],
144
+ success: Boolean(ok),
145
+ },
146
+ });
147
+ } catch { /* ignore closed pipe */ }
148
+ }
149
+
150
+ function handleServerRequest(msg) {
151
+ const id = msg.id;
152
+ const method = msg.method;
153
+ const p = msg.params || {};
154
+ if (method === 'item/tool/call') {
155
+ if (!p.threadId) {
156
+ sendToolResult(id, JSON.stringify({ error: 'missing_thread_id', tool: p.tool }), false);
157
+ return;
158
+ }
159
+ const binding = activeTurnBindings.get(p.threadId);
160
+ if (!binding || typeof binding.handler !== 'function') {
161
+ sendToolResult(id, JSON.stringify({ error: 'no_tool_handler_registered', tool: p.tool }), false);
162
+ return;
163
+ }
164
+ if (binding.closed || binding.signal?.aborted) {
165
+ sendToolResult(id, JSON.stringify({ error: 'turn_closed_or_aborted', tool: p.tool }), false);
166
+ return;
167
+ }
168
+ const prevSet = finishedTurnIdsByThread.get(p.threadId);
169
+ if (p.turnId && prevSet && prevSet.has(String(p.turnId))) {
170
+ sendToolResult(
171
+ id,
172
+ JSON.stringify({ error: 'stale_turn_id_rejected', gotTurnId: p.turnId, tool: p.tool }),
173
+ false
174
+ );
175
+ return;
176
+ }
177
+ if (!binding.turnId) {
178
+ if (!p.turnId) {
179
+ sendToolResult(id, JSON.stringify({ error: 'missing_turn_id', tool: p.tool }), false);
180
+ return;
181
+ }
182
+ binding.pendingCalls.push({ id, p });
183
+ return;
184
+ }
185
+ dispatchToolCall(id, p, binding);
186
+ return;
187
+ }
188
+ // Fail-closed default for unhandled server approval requests so turns never hang
189
+ try {
190
+ sendRaw({ jsonrpc: '2.0', id, result: { decision: 'decline' } });
191
+ } catch { /* ignore */ }
192
+ }
193
+
194
+ function dispatchToolCall(id, p, binding) {
195
+ if (binding.closed || binding.signal?.aborted) {
196
+ sendToolResult(id, JSON.stringify({ error: 'turn_closed_or_aborted', tool: p.tool }), false);
197
+ return;
198
+ }
199
+ if (!binding.turnId || !p.turnId || p.turnId !== binding.turnId) {
200
+ sendToolResult(
201
+ id,
202
+ JSON.stringify({ error: 'turn_id_mismatch', expectedTurnId: binding.turnId || null, gotTurnId: p.turnId || null, tool: p.tool }),
203
+ false
204
+ );
205
+ return;
206
+ }
207
+ const callKey = p.callId ? String(p.callId) : null;
208
+ if (callKey && binding.completedCalls.has(callKey)) {
209
+ const cached = binding.completedCalls.get(callKey);
210
+ sendToolResult(id, cached.text, cached.ok);
211
+ return;
212
+ }
213
+ const invokePromise = (callKey && binding.inflightCalls.has(callKey))
214
+ ? binding.inflightCalls.get(callKey)
215
+ : Promise.resolve().then(() => binding.handler({
216
+ tool: p.tool,
217
+ arguments: p.arguments || {},
218
+ callId: callKey,
219
+ threadId: p.threadId || null,
220
+ turnId: p.turnId || binding.turnId || null,
221
+ }));
222
+ if (callKey && !binding.inflightCalls.has(callKey)) {
223
+ binding.inflightCalls.set(callKey, invokePromise);
224
+ }
225
+ invokePromise
226
+ .then((res) => {
227
+ const text = typeof res === 'string'
228
+ ? res
229
+ : (typeof res?.text === 'string' ? res.text : JSON.stringify(res ?? {}));
230
+ const ok = res?.ok !== false && res?.success !== false;
231
+ if (callKey) {
232
+ binding.inflightCalls.delete(callKey);
233
+ binding.completedCalls.set(callKey, { text, ok });
234
+ }
235
+ if (binding.closed || binding.signal?.aborted) {
236
+ sendToolResult(id, JSON.stringify({ error: 'turn_closed_or_aborted', tool: p.tool }), false);
237
+ return;
238
+ }
239
+ sendToolResult(id, text, ok);
240
+ })
241
+ .catch((err) => {
242
+ if (callKey) binding.inflightCalls.delete(callKey);
243
+ sendToolResult(id, JSON.stringify({ error: String(err?.message || err) }), false);
244
+ });
245
+ }
246
+
247
+ function bindAuthoritativeTurnId(binding, tid) {
248
+ if (!binding || !tid || binding.turnId) return;
249
+ binding.turnId = String(tid);
250
+ const queued = binding.pendingCalls.splice(0, binding.pendingCalls.length);
251
+ for (const item of queued) {
252
+ dispatchToolCall(item.id, item.p, binding);
253
+ }
254
+ }
255
+
256
+ function handleMessage(msg) {
257
+ if (!msg || typeof msg !== 'object') return;
258
+ // Server-to-client RPC request (has BOTH method and id)
259
+ if (msg.method && msg.id !== undefined) {
260
+ handleServerRequest(msg);
261
+ return;
262
+ }
263
+ if (msg.id !== undefined && pending.has(msg.id)) {
264
+ const entry = pending.get(msg.id);
265
+ pending.delete(msg.id);
266
+ clearTimeout(entry.timer);
267
+ if (msg.error) {
268
+ const err = new Error(msg.error.message || JSON.stringify(msg.error));
269
+ err.code = msg.error.code;
270
+ err.data = msg.error.data;
271
+ entry.reject(err);
272
+ } else {
273
+ entry.resolve(msg.result);
274
+ }
275
+ return;
276
+ }
277
+ if (msg.method) {
278
+ for (const listener of notificationListeners) {
279
+ try { listener(msg); } catch { /* listener error isolated */ }
280
+ }
281
+ }
282
+ }
283
+
284
+ function sendRaw(obj) {
285
+ if (!proc || !proc.stdin || proc.stdin.destroyed) {
286
+ throw new Error('codex_app_server_not_running');
287
+ }
288
+ proc.stdin.write(JSON.stringify(obj) + '\n');
289
+ }
290
+
291
+ function notify(method, params = {}) {
292
+ sendRaw({ jsonrpc: '2.0', method, params });
293
+ }
294
+
295
+ function request(method, params = {}, { timeoutMs: reqTimeout = timeoutMs, signal = null } = {}) {
296
+ return new Promise((resolve, reject) => {
297
+ if (signal && signal.aborted) {
298
+ reject(Object.assign(new Error('aborted'), { name: 'AbortError' }));
299
+ return;
300
+ }
301
+ const id = nextId++;
302
+ const onAbort = () => {
303
+ if (pending.has(id)) {
304
+ pending.delete(id);
305
+ clearTimeout(timer);
306
+ reject(Object.assign(new Error('aborted'), { name: 'AbortError' }));
307
+ }
308
+ };
309
+ const timer = setTimeout(() => {
310
+ if (pending.has(id)) {
311
+ pending.delete(id);
312
+ if (signal) signal.removeEventListener('abort', onAbort);
313
+ reject(new Error(`codex_rpc_timeout:${method}:${reqTimeout}ms`));
314
+ }
315
+ }, reqTimeout);
316
+ if (signal) signal.addEventListener('abort', onAbort, { once: true });
317
+ pending.set(id, {
318
+ resolve: (val) => {
319
+ if (signal) signal.removeEventListener('abort', onAbort);
320
+ resolve(val);
321
+ },
322
+ reject: (err) => {
323
+ if (signal) signal.removeEventListener('abort', onAbort);
324
+ reject(err);
325
+ },
326
+ timer,
327
+ });
328
+ try {
329
+ sendRaw({ jsonrpc: '2.0', id, method, params });
330
+ } catch (err) {
331
+ pending.delete(id);
332
+ clearTimeout(timer);
333
+ if (signal) signal.removeEventListener('abort', onAbort);
334
+ reject(err);
335
+ }
336
+ });
337
+ }
338
+
339
+ async function start() {
340
+ if (started && proc && proc.exitCode === null) return;
341
+ if (startPromise) return startPromise;
342
+ closing = false;
343
+ startPromise = (async () => {
344
+ const bin = resolvedBinary();
345
+ if (!bin) throw new Error('codex_binary_not_found');
346
+ const spawnArgs = buildArgs();
347
+ stderrTail = '';
348
+ const myProc = spawn(bin, spawnArgs, {
349
+ cwd,
350
+ env,
351
+ stdio: ['pipe', 'pipe', 'pipe'],
352
+ });
353
+ proc = myProc;
354
+ const startedAtMs = Date.now();
355
+ myProc.stdin?.on('error', (err) => {
356
+ if (proc === myProc && !closing) rejectAllPending(err);
357
+ });
358
+ myProc.stderr.on('data', (buf) => {
359
+ stderrTail = (stderrTail + buf.toString('utf8')).slice(-2000);
360
+ });
361
+ const myRl = readline.createInterface({ input: myProc.stdout });
362
+ rl = myRl;
363
+ myRl.on('line', (line) => {
364
+ if (proc !== myProc) return;
365
+ const trimmed = line.trim();
366
+ if (!trimmed || !trimmed.startsWith('{')) return;
367
+ try {
368
+ handleMessage(JSON.parse(trimmed));
369
+ } catch {
370
+ // ignore non-JSON diagnostic line
371
+ }
372
+ });
373
+ myProc.once('exit', (code, sig) => {
374
+ if (proc !== myProc) {
375
+ try { myRl.close(); } catch { /* ignore */ }
376
+ return;
377
+ }
378
+ const wasStarted = started;
379
+ started = false;
380
+ startPromise = null;
381
+ try { myRl.close(); } catch { /* ignore */ }
382
+ if (rl === myRl) rl = null;
383
+ proc = null;
384
+ if (!closing) {
385
+ rejectAllPending(new Error(`codex_app_server_exited:${code ?? sig}:${stderrTail.slice(-200)}`));
386
+ if (wasStarted) {
387
+ // Reset restart counter if process ran stably for >= 60s before exiting
388
+ if (Date.now() - startedAtMs >= 60_000) restartCount = 0;
389
+ restartCount++;
390
+ }
391
+ }
392
+ });
393
+ myProc.once('error', (err) => {
394
+ if (proc !== myProc) return;
395
+ started = false;
396
+ startPromise = null;
397
+ rejectAllPending(err);
398
+ });
399
+ try {
400
+ const initRes = await request('initialize', {
401
+ clientInfo,
402
+ capabilities: { experimentalApi: true },
403
+ }, { timeoutMs: Math.min(timeoutMs, 30_000) });
404
+ notify('initialized', {});
405
+ started = true;
406
+ return initRes;
407
+ } catch (err) {
408
+ // Kill child process cleanly on init timeout/error so no orphan leaks or disrupts future procs
409
+ started = false;
410
+ try { myRl.close(); } catch { /* ignore */ }
411
+ if (rl === myRl) rl = null;
412
+ if (proc === myProc) proc = null;
413
+ if (myProc.exitCode === null) {
414
+ try { myProc.kill('SIGKILL'); } catch { /* ignore */ }
415
+ }
416
+ throw err;
417
+ }
418
+ })();
419
+ try {
420
+ return await startPromise;
421
+ } finally {
422
+ startPromise = null;
423
+ }
424
+ }
425
+
426
+ async function ensureStarted() {
427
+ if (started && proc && proc.exitCode === null) return;
428
+ if (restartCount > maxRestarts) {
429
+ throw new Error(`codex_app_server_max_restarts_exceeded:${maxRestarts}`);
430
+ }
431
+ await start();
432
+ }
433
+
434
+ async function readAccount({ refreshToken = false } = {}) {
435
+ await ensureStarted();
436
+ return request('account/read', { refreshToken });
437
+ }
438
+
439
+ async function startLogin({ type = 'chatgpt', apiKey = null } = {}) {
440
+ await ensureStarted();
441
+ const params = type === 'apiKey' ? { type: 'apiKey', apiKey } : { type };
442
+ return request('account/login/start', params);
443
+ }
444
+
445
+ async function readRateLimits() {
446
+ await ensureStarted();
447
+ return request('account/rateLimits/read', {});
448
+ }
449
+
450
+ async function listModels({ refresh = false } = {}) {
451
+ await ensureStarted();
452
+ if (!refresh && Array.isArray(cachedModels) && cachedModels.length) return cachedModels;
453
+ const res = await request('model/list', {});
454
+ const list = Array.isArray(res?.data) ? res.data : (Array.isArray(res?.models) ? res.models : []);
455
+ cachedModels = list;
456
+ return list;
457
+ }
458
+
459
+ async function resolveModel(requested = null) {
460
+ const models = await listModels();
461
+ const knownIds = new Set(models.map((m) => m.id || m.model).filter(Boolean));
462
+ const pickIfKnown = (cand) => {
463
+ if (!cand || cand === 'auto' || cand === 'codex-default') return null;
464
+ if (!knownIds.size || knownIds.has(cand)) return cand;
465
+ return null;
466
+ };
467
+ const exact = pickIfKnown(requested) || pickIfKnown(defaultModel);
468
+ if (exact) return exact;
469
+ if (!models.length) return requested && requested !== 'auto' ? requested : (defaultModel || 'gpt-5');
470
+ const def = models.find((m) => m.isDefault === true) || models[0];
471
+ return def.id || def.model || 'gpt-5';
472
+ }
473
+
474
+ function toDynamicTools(tools) {
475
+ if (!Array.isArray(tools) || !tools.length) return null;
476
+ return tools.map((t) => ({
477
+ type: 'function',
478
+ name: String(t.name),
479
+ description: String(t.description || ''),
480
+ inputSchema: t.inputSchema || t.parameters || { type: 'object', properties: {} },
481
+ deferLoading: false,
482
+ }));
483
+ }
484
+
485
+ async function startThread({
486
+ model = null,
487
+ ephemeral = true,
488
+ approvalPolicy = 'never',
489
+ sandbox = 'read-only',
490
+ baseInstructions = null,
491
+ developerInstructions = null,
492
+ dynamicTools = null,
493
+ cwd: threadCwd = cwd,
494
+ } = {}) {
495
+ await ensureStarted();
496
+ const resolvedModel = await resolveModel(model);
497
+ const params = {
498
+ model: resolvedModel,
499
+ ephemeral,
500
+ approvalPolicy,
501
+ sandbox,
502
+ cwd: threadCwd,
503
+ };
504
+ if (baseInstructions) params.baseInstructions = baseInstructions;
505
+ if (developerInstructions) params.developerInstructions = developerInstructions;
506
+ const dyn = toDynamicTools(dynamicTools);
507
+ if (dyn) params.dynamicTools = dyn;
508
+ const res = await request('thread/start', params);
509
+ const threadId = res?.thread?.id || res?.threadId || res?.id || null;
510
+ if (!threadId) throw new Error('codex_thread_start_missing_id');
511
+ return { threadId, model: resolvedModel, raw: res };
512
+ }
513
+
514
+ async function runTurn({
515
+ threadId,
516
+ input,
517
+ model = null,
518
+ effort = null,
519
+ onDelta = null,
520
+ onToolCall = null,
521
+ signal = null,
522
+ timeoutMs: turnTimeout = timeoutMs,
523
+ } = {}) {
524
+ await ensureStarted();
525
+ if (!threadId) throw new Error('runTurn: threadId is required');
526
+ const items = Array.isArray(input)
527
+ ? input
528
+ : [{ type: 'text', text: String(input ?? '') }];
529
+ const startedAt = Date.now();
530
+
531
+ const turnBinding = typeof onToolCall === 'function'
532
+ ? {
533
+ turnId: null,
534
+ handler: onToolCall,
535
+ signal,
536
+ closed: false,
537
+ completedCalls: new Map(),
538
+ inflightCalls: new Map(),
539
+ pendingCalls: [],
540
+ }
541
+ : null;
542
+ if (turnBinding) activeTurnBindings.set(threadId, turnBinding);
543
+
544
+ return new Promise((resolve, reject) => {
545
+ let settled = false;
546
+ let turnId = null;
547
+ let text = '';
548
+ let finalItemText = '';
549
+ let usage = { uncachedInputTokens: 0, cachedInputTokens: 0, outputTokens: 0, providerTotalTokens: 0 };
550
+
551
+ const cleanup = () => {
552
+ if (turnId) markTurnFinished(threadId, turnId);
553
+ if (turnBinding) {
554
+ turnBinding.closed = true;
555
+ for (const item of turnBinding.pendingCalls.splice(0, turnBinding.pendingCalls.length)) {
556
+ sendToolResult(item.id, JSON.stringify({ error: 'turn_closed_or_aborted', tool: item.p?.tool }), false);
557
+ }
558
+ if (activeTurnBindings.get(threadId) === turnBinding) {
559
+ activeTurnBindings.delete(threadId);
560
+ }
561
+ }
562
+ unsub();
563
+ clearTimeout(timer);
564
+ if (signal) signal.removeEventListener('abort', onAbort);
565
+ };
566
+
567
+ const finish = (err, val) => {
568
+ if (settled) return;
569
+ settled = true;
570
+ cleanup();
571
+ if (err) reject(err);
572
+ else resolve(val);
573
+ };
574
+
575
+ const onAbort = () => {
576
+ if (turnBinding) turnBinding.closed = true;
577
+ if (turnId) {
578
+ request('turn/interrupt', { threadId, turnId }, { timeoutMs: 5000 }).catch(() => {});
579
+ }
580
+ finish(Object.assign(new Error('aborted'), { name: 'AbortError' }));
581
+ };
582
+ if (signal) {
583
+ if (signal.aborted) {
584
+ finish(Object.assign(new Error('aborted'), { name: 'AbortError' }));
585
+ return;
586
+ }
587
+ signal.addEventListener('abort', onAbort, { once: true });
588
+ }
589
+
590
+ const timer = setTimeout(() => {
591
+ if (turnBinding) turnBinding.closed = true;
592
+ if (turnId) {
593
+ request('turn/interrupt', { threadId, turnId }, { timeoutMs: 5000 }).catch(() => {});
594
+ }
595
+ finish(new Error(`codex_turn_timeout:${turnTimeout}ms`));
596
+ }, turnTimeout);
597
+
598
+ const pendingNotifications = [];
599
+ const pendingTerminalByTurn = new Map();
600
+
601
+ const handleTurnNotification = (msg) => {
602
+ if (settled) return;
603
+ const p = msg.params || {};
604
+ // Strict thread/turn binding: never leak notifications missing threadId or belonging to another turn
605
+ const msgThreadId = p.threadId || p.turn?.threadId || null;
606
+ if (typeof msgThreadId !== 'string' || msgThreadId !== threadId) return;
607
+ // Read ONLY protocol-defined turnId fields per Codex App-Server v2 JSON schema (no item.turnId fallback, no String() coercion!)
608
+ const isTurnLifecycle = msg.method === 'turn/started' || msg.method === 'turn/completed';
609
+ const rawTurnId = isTurnLifecycle ? p.turn?.id : p.turnId;
610
+ const msgTurnId = typeof rawTurnId === 'string' && rawTurnId.length > 0 ? rawTurnId : null;
611
+ if (msg.method === 'turn/started') {
612
+ if (!msgTurnId) return;
613
+ const prevSet = finishedTurnIdsByThread.get(threadId);
614
+ if (prevSet && prevSet.has(msgTurnId)) return;
615
+ if (!turnId) {
616
+ turnId = msgTurnId;
617
+ bindAuthoritativeTurnId(turnBinding, turnId);
618
+ flushPendingNotifications();
619
+ }
620
+ return;
621
+ }
622
+ if (!msgTurnId) return;
623
+ if (finishedTurnIdsByThread.get(threadId)?.has(msgTurnId)) return;
624
+ if (!turnId) {
625
+ // Buffer turn-scoped notifications before authoritative turnId binds:
626
+ // always preserve turn/completed in pendingTerminalByTurn and coalesce consecutive deltas so bursts never drop completion!
627
+ if (msg.method === 'turn/completed') {
628
+ if (pendingTerminalByTurn.size >= 64 && !pendingTerminalByTurn.has(msgTurnId)) {
629
+ const oldest = pendingTerminalByTurn.keys().next().value;
630
+ pendingTerminalByTurn.delete(oldest);
631
+ }
632
+ pendingTerminalByTurn.set(msgTurnId, msg);
633
+ return;
634
+ }
635
+ if (msg.method === 'item/agentMessage/delta' && typeof p.delta === 'string') {
636
+ const last = pendingNotifications[pendingNotifications.length - 1];
637
+ if (last && last.method === 'item/agentMessage/delta' && last.params?.turnId === msgTurnId) {
638
+ last.params = { ...last.params, delta: String(last.params.delta || '') + p.delta };
639
+ return;
640
+ }
641
+ }
642
+ if (pendingNotifications.length < 256) {
643
+ pendingNotifications.push({ ...msg, params: { ...p } });
644
+ }
645
+ return;
646
+ }
647
+ // Strict exact-string turnId match for ALL turn notifications including thread/tokenUsage/updated
648
+ if (msgTurnId !== turnId) return;
649
+ if (msg.method === 'item/agentMessage/delta') {
650
+ const delta = typeof p.delta === 'string' ? p.delta : '';
651
+ if (delta) {
652
+ text += delta;
653
+ if (typeof onDelta === 'function') {
654
+ try { onDelta(delta); } catch { /* ignore callback error */ }
655
+ }
656
+ }
657
+ } else if (msg.method === 'item/completed' && p.item && (p.item.type === 'agentMessage' || p.item.type === 'agent_message')) {
658
+ if (typeof p.item.text === 'string' && p.item.text) finalItemText = p.item.text;
659
+ } else if (msg.method === 'thread/tokenUsage/updated' || msg.method === 'turn/tokenUsage/updated') {
660
+ const u = p.tokenUsage?.last || p.tokenUsage?.total || p.usage || {};
661
+ const input = Number(u.inputTokens ?? u.input_tokens ?? 0);
662
+ const cached = Number(u.cachedInputTokens ?? u.cached_input_tokens ?? 0);
663
+ const out = Number(u.outputTokens ?? u.output_tokens ?? 0);
664
+ const total = Number(u.totalTokens ?? u.total_tokens ?? (input + out));
665
+ usage = {
666
+ uncachedInputTokens: Math.max(0, input - cached),
667
+ cachedInputTokens: cached,
668
+ outputTokens: out,
669
+ providerTotalTokens: total,
670
+ };
671
+ } else if (msg.method === 'turn/completed') {
672
+ const status = p.turn?.status || 'completed';
673
+ const errObj = p.turn?.error || null;
674
+ if (status === 'failed' || errObj) {
675
+ const errMsg = (errObj && (errObj.message || JSON.stringify(errObj))) || 'codex_turn_failed';
676
+ const err = new Error(errMsg);
677
+ if (/429|rate.?limit|quota/i.test(errMsg)) err.status = 429;
678
+ else if (/401|auth|login/i.test(errMsg)) err.status = 401;
679
+ else if (/context.?length|maximum.?context|too many tokens|prompt.?too.?long/i.test(errMsg)) {
680
+ err.status = 400;
681
+ err.code = 'CONTEXT_LENGTH_EXCEEDED';
682
+ }
683
+ finish(err);
684
+ return;
685
+ }
686
+ finish(null, {
687
+ text: (text || finalItemText || '').trim(),
688
+ status,
689
+ usage,
690
+ threadId,
691
+ turnId: p.turn?.id || turnId,
692
+ durationMs: Date.now() - startedAt,
693
+ });
694
+ }
695
+ };
696
+
697
+ const flushPendingNotifications = () => {
698
+ if (!turnId) return;
699
+ if (pendingNotifications.length) {
700
+ const queued = pendingNotifications.splice(0, pendingNotifications.length);
701
+ for (const m of queued) {
702
+ handleTurnNotification(m);
703
+ if (settled) break;
704
+ }
705
+ }
706
+ if (!settled && pendingTerminalByTurn.has(turnId)) {
707
+ const termMsg = pendingTerminalByTurn.get(turnId);
708
+ pendingTerminalByTurn.clear();
709
+ handleTurnNotification(termMsg);
710
+ } else {
711
+ pendingTerminalByTurn.clear();
712
+ }
713
+ };
714
+
715
+ const unsub = onNotification(handleTurnNotification);
716
+
717
+ const params = { threadId, input: items };
718
+ if (model && model !== 'auto') params.model = model;
719
+ if (effort) params.effort = effort;
720
+ request('turn/start', params, { timeoutMs: Math.min(turnTimeout, 30_000), signal })
721
+ .then((res) => {
722
+ if (typeof res?.turn?.id === 'string' && res.turn.id.length > 0 && !turnId) {
723
+ turnId = res.turn.id;
724
+ bindAuthoritativeTurnId(turnBinding, turnId);
725
+ flushPendingNotifications();
726
+ }
727
+ })
728
+ .catch((err) => finish(err));
729
+ });
730
+ }
731
+
732
+ async function generate(prompt, {
733
+ system = null,
734
+ messages = null,
735
+ tools = null,
736
+ onToolCall = null,
737
+ images = null,
738
+ model = null,
739
+ effort = null,
740
+ threadId = null,
741
+ ephemeral = true,
742
+ onDelta = null,
743
+ signal = null,
744
+ timeoutMs: turnTimeout = timeoutMs,
745
+ } = {}) {
746
+ await ensureStarted();
747
+ const resolvedModel = await resolveModel(model);
748
+ let activeThreadId = threadId;
749
+ if (!activeThreadId) {
750
+ const th = await startThread({
751
+ model: resolvedModel,
752
+ ephemeral,
753
+ baseInstructions: system || undefined,
754
+ dynamicTools: Array.isArray(tools) && tools.length && typeof onToolCall === 'function' ? tools : null,
755
+ });
756
+ activeThreadId = th.threadId;
757
+ }
758
+ const input = [];
759
+ let bodyText = '';
760
+ if (Array.isArray(messages) && messages.length) {
761
+ bodyText = messages.map((m) => {
762
+ const role = m.role === 'assistant' ? 'Assistant' : (m.role === 'tool' ? `Tool(${m.name || 'tool'})` : 'User');
763
+ return `[${role}]\n${typeof m.content === 'string' ? m.content : JSON.stringify(m.content)}`;
764
+ }).join('\n\n');
765
+ } else {
766
+ bodyText = String(prompt ?? '');
767
+ }
768
+ input.push({ type: 'text', text: bodyText });
769
+ const tempFiles = [];
770
+ let res;
771
+ try {
772
+ if (Array.isArray(images)) {
773
+ for (const img of images) {
774
+ if (!img) continue;
775
+ if (img.url) {
776
+ input.push({ type: 'image', url: img.url });
777
+ } else if (img.path) {
778
+ input.push({ type: 'localImage', path: img.path });
779
+ } else if (img.base64) {
780
+ const tmpPath = writeTempImageBase64(img.base64, img.mimeType);
781
+ tempFiles.push(tmpPath);
782
+ input.push({ type: 'localImage', path: tmpPath });
783
+ }
784
+ }
785
+ }
786
+ res = await runTurn({
787
+ threadId: activeThreadId,
788
+ input,
789
+ model: resolvedModel,
790
+ effort,
791
+ onDelta,
792
+ onToolCall,
793
+ signal,
794
+ timeoutMs: turnTimeout,
795
+ });
796
+ } finally {
797
+ for (const f of tempFiles) {
798
+ try { fs.rmSync(f, { force: true }); } catch { /* ignore */ }
799
+ }
800
+ }
801
+ return {
802
+ text: res.text,
803
+ usage: res.usage,
804
+ durationMs: res.durationMs,
805
+ responseId: res.turnId || activeThreadId,
806
+ threadId: activeThreadId,
807
+ model: resolvedModel,
808
+ };
809
+ }
810
+
811
+ async function close() {
812
+ closing = true;
813
+ started = false;
814
+ rejectAllPending(new Error('codex_app_server_closed'));
815
+ if (rl) { try { rl.close(); } catch { /* ignore */ } rl = null; }
816
+ const child = proc;
817
+ proc = null;
818
+ if (!child) return;
819
+ await new Promise((resolve) => {
820
+ let done = false;
821
+ const fin = () => { if (!done) { done = true; resolve(); } };
822
+ child.once('exit', fin);
823
+ try { child.kill('SIGTERM'); } catch { fin(); }
824
+ setTimeout(() => {
825
+ if (!done) {
826
+ try { child.kill('SIGKILL'); } catch { /* ignore */ }
827
+ fin();
828
+ }
829
+ }, 2000).unref();
830
+ });
831
+ }
832
+
833
+ return {
834
+ get ready() { return Boolean(resolvedBinary()); },
835
+ get running() { return Boolean(started && proc && proc.exitCode === null); },
836
+ resolvedBinary,
837
+ start,
838
+ request,
839
+ notify,
840
+ onNotification,
841
+ readAccount,
842
+ startLogin,
843
+ readRateLimits,
844
+ listModels,
845
+ resolveModel,
846
+ startThread,
847
+ runTurn,
848
+ generate,
849
+ close,
850
+ };
851
+ }