@aisac/cli 0.4.0-beta.21 → 0.4.0-beta.22

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.
@@ -60,6 +60,49 @@ const ENGINEERING_SKILLS_ROOT_ENV = 'AISAC_ENGINEERING_SKILLS_ROOT';
60
60
  const ENGINEERING_SKILLS_ACK_TIMEOUT_MS = 2_000;
61
61
  const MAX_ENGINEERING_PATH_LENGTH = 4_096;
62
62
  const MAX_TRACKED_INITIALIZE_REQUESTS = 4;
63
+ // The worker role (ADR-0058): a launch started with `aisac codex --worker` gives
64
+ // this adapter a role and the module that runs it. Without both, nothing below
65
+ // that mentions the role runs. The names match clients/aibrain/src/manager/bus.mjs.
66
+ export const WORKER_ROLE_ENV = 'AISAC_WORKER_ROLE';
67
+ export const WORKER_MODULE_ENV = 'AISAC_WORKER_MODULE';
68
+ const WORKER_MODULE_SUFFIX = '/manager/worker.mjs';
69
+ // The one request the role may send, and the only fields it may carry: a turn
70
+ // on a thread, with one text input and no override of sandbox, approval policy,
71
+ // model or working directory.
72
+ const WORKER_ROLE_METHOD = 'turn/start';
73
+ const WORKER_TURN_KEYS = new Set(['threadId', 'clientUserMessageId', 'input']);
74
+ const WORKER_INPUT_KEYS = new Set(['type', 'text']);
75
+ // The statuses on which a thread takes a turn of the role. A failed turn leaves
76
+ // the thread in `systemError` and no `idle` follows; a new turn works there
77
+ // (measured on Codex 0.166.0), and without it one provider error would stop
78
+ // every later delivery until a person typed in the terminal.
79
+ const WORKER_TURN_STATUSES = new Set(['idle', 'systemError']);
80
+ // The only answers the role may give to a request it holds.
81
+ const WORKER_ROLE_DECISIONS = new Set(['accept', 'decline']);
82
+ const MAX_WORKER_HELD_REQUESTS = 32;
83
+ // The only server requests the role may hold and answer: the two approvals whose
84
+ // decisions are accept and decline. Every other request goes to the terminal.
85
+ const WORKER_HOLDABLE_METHODS = new Set([
86
+ 'item/commandExecution/requestApproval',
87
+ 'item/fileChange/requestApproval',
88
+ ]);
89
+ // A role turn the app-server never reports stops counting as starting after this.
90
+ const WORKER_TURN_START_DEADLINE_MS = 30_000;
91
+ // How long the adapter waits for the role's stop() once the held lines are out.
92
+ const WORKER_ROLE_STOP_TIMEOUT_MS = 5_000;
93
+ // Requests of the terminal that start work on a thread. From the write until the
94
+ // answer and the thread's next status event the thread still reads idle, so the
95
+ // adapter starts no compaction there and the role no turn (codex-manager-gate.md).
96
+ const TERMINAL_WORK_METHODS = new Set([
97
+ 'turn/start',
98
+ 'turn/steer',
99
+ 'thread/compact/start',
100
+ 'review/start',
101
+ 'thread/shellCommand',
102
+ ]);
103
+ const MAX_TERMINAL_WORK = 128;
104
+ // A terminal work request whose answer or status event is lost stops counting after this.
105
+ const TERMINAL_WORK_DEADLINE_MS = 30_000;
63
106
  const MAX_RECOVERY_ITEMS = 128;
64
107
  const MAX_RECOVERY_SOURCE_INDEX = 65_536;
65
108
  const MAX_NOTE_BYTES = 128 * 1024;
@@ -276,6 +319,10 @@ function codexChildEnvironment() {
276
319
  const environment = { ...process.env };
277
320
  delete environment.JEV_API_KEY;
278
321
  delete environment.TYPESAFE_API_KEY;
322
+ // The role belongs to this adapter alone: the app-server and the commands its
323
+ // model runs never see it.
324
+ delete environment[WORKER_ROLE_ENV];
325
+ delete environment[WORKER_MODULE_ENV];
279
326
  return environment;
280
327
  }
281
328
  function isRecord(value) {
@@ -398,6 +445,19 @@ function clientRequestKey(value) {
398
445
  return null;
399
446
  }
400
447
 
448
+ // The head of an answer line: `{"id":<id>,"result"` or `"error"`, optionally after
449
+ // `"jsonrpc":"2.0"`. A string id with escapes is not read.
450
+ const LEADING_RESPONSE_ID =
451
+ /^\s*\{\s*(?:"jsonrpc"\s*:\s*"2\.0"\s*,\s*)?"id"\s*:\s*(?:(0|[1-9][0-9]{0,15})|"([^"\\\u0000-\u001f]{1,128})")\s*,\s*"(?:result|error)"\s*:/u;
452
+ const LEADING_RESPONSE_SCAN_CHARS = 512;
453
+
454
+ /** The request key of an answer line too large to parse, from its first bytes; null otherwise. */
455
+ function leadingResponseKey(text) {
456
+ const match = LEADING_RESPONSE_ID.exec(text.slice(0, LEADING_RESPONSE_SCAN_CHARS));
457
+ if (!match) return null;
458
+ return match[1] === undefined ? clientRequestKey(match[2]) : clientRequestKey(Number(match[1]));
459
+ }
460
+
401
461
  /**
402
462
  * Closed private diagnostic contract consumed by the client sink. It contains
403
463
  * stage/reason enums, pseudonymous session identity, operation/correlation
@@ -2856,6 +2916,8 @@ export function createCodexContextProxy({
2856
2916
  clientVersion = process.env.CODEX_CLIENT_VERSION ?? '0.161.0',
2857
2917
  engineeringSkillsRoot = null,
2858
2918
  engineeringAckTimeoutMs = ENGINEERING_SKILLS_ACK_TIMEOUT_MS,
2919
+ createWorkerRole = null,
2920
+ clientAtLineBoundary = () => true,
2859
2921
  }) {
2860
2922
  const contextPolicy = normalizeContextPolicy(policy);
2861
2923
  const effectiveThreshold = contextPolicy?.compactAtPercent ?? threshold;
@@ -2877,6 +2939,22 @@ export function createCodexContextProxy({
2877
2939
  : 'off';
2878
2940
  const initializeRequestKeys = new Set();
2879
2941
  let engineeringHeld = null;
2942
+ // The worker role, when the launch gave one (ADR-0058); null keeps every path
2943
+ // below exactly as it is without a role.
2944
+ let workerRole = null;
2945
+ let workerRoleStopped = false;
2946
+ // Held server requests by key: `{ text, id, threadId }`.
2947
+ const workerHeldRequests = new Map();
2948
+ // The terminal's current thread: the last one it started, resumed or forked that
2949
+ // is not ephemeral (spec FR4 step 1). Null when the adapter could not read it.
2950
+ let currentThreadId = null;
2951
+ // Terminal work requests in flight by request key: `{ threadId, answered, cancel }`.
2952
+ // Past the bound nothing more is counted and every thread reads busy until it drains.
2953
+ const terminalWork = new Map();
2954
+ let terminalWorkSaturated = false;
2955
+ // Lines of this adapter's that wait for the terminal to finish the frame it is
2956
+ // writing to the app-server: `{ value, ownedId }`, `ownedId` null for an answer.
2957
+ const deferredWrites = [];
2880
2958
  function emitDiagnostic(event) {
2881
2959
  try {
2882
2960
  const phase = typeof event?.phase === 'string' ? event.phase : '';
@@ -2967,7 +3045,10 @@ export function createCodexContextProxy({
2967
3045
  }
2968
3046
  function cleanupRequest(id) {
2969
3047
  if (!id) return;
3048
+ const owned = ownedRequests.get(id);
2970
3049
  ownedRequests.delete(id);
3050
+ // A role turn given up on (oversized answer, failed write) is not starting any more.
3051
+ if (owned?.kind === 'worker') endWorkerTurnStart(threads.get(owned.threadId));
2971
3052
  const waiter = internalReads.get(id);
2972
3053
  if (waiter) {
2973
3054
  internalReads.delete(id);
@@ -3054,6 +3135,17 @@ export function createCodexContextProxy({
3054
3135
  resumePending: false,
3055
3136
  resumeRetryRequested: false,
3056
3137
  resumeRequests: new Set(),
3138
+ // The worker role wrote a turn/start the app-server has not reported yet:
3139
+ // the thread still reads idle, and no lifecycle of this adapter may start.
3140
+ workerTurnStarting: false,
3141
+ // Cancels the deadline of that start; null when no role turn is starting.
3142
+ workerTurnTimer: null,
3143
+ // Compaction checks in flight, including the ones still loading state.
3144
+ lifecycleChecks: 0,
3145
+ // What the app-server last said the thread's status is, including the
3146
+ // answer to thread/start, which no status event follows. Only the worker
3147
+ // role's gate reads it: `idle` above keeps deciding compaction.
3148
+ reportedStatus: null,
3057
3149
  };
3058
3150
  threads.set(threadId, created);
3059
3151
  return created;
@@ -3075,7 +3167,7 @@ export function createCodexContextProxy({
3075
3167
  ownedRequests.set(id, { kind, threadId });
3076
3168
  if (waiter) internalReads.set(id, waiter);
3077
3169
  try {
3078
- writeJsonLine(child.stdin, { id, method, params });
3170
+ writeAtClientBoundary({ id, method, params }, id);
3079
3171
  } catch (error) {
3080
3172
  cleanupRequest(id);
3081
3173
  throw error;
@@ -3264,7 +3356,14 @@ export function createCodexContextProxy({
3264
3356
  reporter.failed({ operationId, reason: 'native_error' });
3265
3357
  }
3266
3358
  function assertCurrent(threadId, state, pending, revision) {
3267
- if (pending.canceled || state.pending !== pending || !state.idle || state.revision !== revision)
3359
+ if (
3360
+ pending.canceled ||
3361
+ state.pending !== pending ||
3362
+ !state.idle ||
3363
+ state.revision !== revision ||
3364
+ // The terminal started work the app-server has not reported yet.
3365
+ terminalWorkInFlight(threadId)
3366
+ )
3268
3367
  throw new Error('Codex state changed during compaction');
3269
3368
  }
3270
3369
  async function readThreadCapture(
@@ -3710,13 +3809,31 @@ export function createCodexContextProxy({
3710
3809
  if (state.recoveryAttach === attachment) state.recoveryAttach = null;
3711
3810
  }
3712
3811
  }
3812
+ /**
3813
+ * Every lifecycle of this adapter on a thread starts here. The count makes a
3814
+ * check that is still loading state visible to the worker role, which must
3815
+ * not start a turn in that window, and the role hears when the last one ends.
3816
+ */
3713
3817
  async function requestCompaction(threadId, state) {
3818
+ state.lifecycleChecks += 1;
3819
+ try {
3820
+ await compactWhenDue(threadId, state);
3821
+ } finally {
3822
+ state.lifecycleChecks -= 1;
3823
+ notifyWorkerRoleIdle(threadId);
3824
+ }
3825
+ }
3826
+ async function compactWhenDue(threadId, state) {
3714
3827
  if (!state.owned) return;
3715
3828
  if (state.resumePending) {
3716
3829
  state.resumeRetryRequested = true;
3717
3830
  return;
3718
3831
  }
3832
+ // A turn of the worker role, or work of the terminal, is starting: its end
3833
+ // brings the next idle event.
3834
+ if (state.workerTurnStarting || terminalWorkInFlight(threadId)) return;
3719
3835
  if (recoveryEnabled && recoveryDisclosed) await loadRecoveryState(threadId, state);
3836
+ if (state.workerTurnStarting || terminalWorkInFlight(threadId)) return;
3720
3837
  if (
3721
3838
  state.recovery &&
3722
3839
  ['pending_attachment', 'recovery_uncertain'].includes(state.recovery.status)
@@ -4294,6 +4411,16 @@ export function createCodexContextProxy({
4294
4411
  releaseEngineering();
4295
4412
  return false;
4296
4413
  }
4414
+ if (owned.kind === 'worker') {
4415
+ // The role's own request: its answer goes to the role and nowhere else.
4416
+ const waiter = internalReads.get(message.id);
4417
+ internalReads.delete(message.id);
4418
+ if ('error' in message) {
4419
+ endWorkerTurnStart(threads.get(owned.threadId));
4420
+ waiter?.reject(rpcFailure(owned.kind, message.error));
4421
+ } else waiter?.resolve(message.result);
4422
+ return false;
4423
+ }
4297
4424
  if (
4298
4425
  owned.kind === 'read' ||
4299
4426
  owned.kind === 'page' ||
@@ -4344,11 +4471,17 @@ export function createCodexContextProxy({
4344
4471
  typeof message.params.threadId === 'string' &&
4345
4472
  isRecord(message.params.status)
4346
4473
  ) {
4474
+ // The status event that follows the answer to a work request of the terminal.
4475
+ settleAnsweredTerminalWork(message.params.threadId);
4347
4476
  const state = threads.get(message.params.threadId);
4348
4477
  if (!state) return true;
4349
4478
  state.status =
4350
4479
  typeof message.params.status.type === 'string' ? message.params.status.type : 'unknown';
4351
4480
  state.idle = state.status === 'idle';
4481
+ state.reportedStatus = state.status;
4482
+ // A busy thread means the app-server took the role's turn/start; an idle may
4483
+ // have been emitted before it read it.
4484
+ if (!state.idle) endWorkerTurnStart(state);
4352
4485
  if (!state.idle) invalidateAttachment(state);
4353
4486
  if (!state.owned) return true;
4354
4487
  if (!state.telemetryConnected) {
@@ -4413,6 +4546,7 @@ export function createCodexContextProxy({
4413
4546
  ) {
4414
4547
  const state = threads.get(message.params.threadId);
4415
4548
  const turnId = message.params.turn.id;
4549
+ endWorkerTurnStart(state);
4416
4550
  if (
4417
4551
  state?.recoveryAttach &&
4418
4552
  typeof turnId === 'string' &&
@@ -4506,6 +4640,9 @@ export function createCodexContextProxy({
4506
4640
  typeof message.params.threadId === 'string'
4507
4641
  ) {
4508
4642
  fail(message.params.threadId, 'thread closed');
4643
+ endWorkerTurnStart(threads.get(message.params.threadId));
4644
+ settleTerminalWorkOf(message.params.threadId);
4645
+ if (currentThreadId === message.params.threadId) currentThreadId = null;
4509
4646
  ownedThreadIds.delete(message.params.threadId);
4510
4647
  threads.delete(message.params.threadId);
4511
4648
  }
@@ -4535,6 +4672,10 @@ export function createCodexContextProxy({
4535
4672
  initializeRequestKeys.add(requestKey);
4536
4673
  return;
4537
4674
  }
4675
+ if (TERMINAL_WORK_METHODS.has(message.method)) {
4676
+ observeTerminalWork(requestKey, message.params);
4677
+ return;
4678
+ }
4538
4679
  if (['thread/start', 'thread/resume', 'thread/fork'].includes(message.method)) {
4539
4680
  const threadId =
4540
4681
  isRecord(message.params) && typeof message.params.threadId === 'string'
@@ -4545,7 +4686,9 @@ export function createCodexContextProxy({
4545
4686
  clientRequestBindings.size >= MAX_CLIENT_REQUEST_BINDINGS
4546
4687
  )
4547
4688
  return;
4548
- clientRequestBindings.set(requestKey, { method: message.method, threadId });
4689
+ // The terminal's task-title threads ask for `ephemeral` (spec S5).
4690
+ const ephemeral = isRecord(message.params) && message.params.ephemeral === true;
4691
+ clientRequestBindings.set(requestKey, { method: message.method, threadId, ephemeral });
4549
4692
  if (message.method === 'thread/resume') {
4550
4693
  if (threadId === null || threadId.length === 0 || threadId.length > 256) {
4551
4694
  clientRequestBindings.delete(requestKey);
@@ -4559,10 +4702,21 @@ export function createCodexContextProxy({
4559
4702
  }
4560
4703
  }
4561
4704
 
4705
+ /** The status a thread/start, resume or fork answer reports for its thread. */
4706
+ function noteReportedStatus(state, thread) {
4707
+ const type = isRecord(thread) && isRecord(thread.status) ? thread.status.type : null;
4708
+ if (state && typeof type === 'string') state.reportedStatus = type;
4709
+ }
4710
+ /** Whether a start, resume or fork answer names a thread the terminal converses on. */
4711
+ function isConversationThread(binding, thread) {
4712
+ return !binding.ephemeral && !(isRecord(thread) && thread.ephemeral === true);
4713
+ }
4562
4714
  function observeClientResponse(message) {
4563
4715
  if (!isRecord(message) || message.id === undefined) return;
4564
4716
  const requestKey = clientRequestKey(message.id);
4565
4717
  if (requestKey === null) return;
4718
+ // An answer, not a server request that reuses the id.
4719
+ if (message.method === undefined) answerTerminalWork(requestKey, message.error === undefined);
4566
4720
  const binding = clientRequestBindings.get(requestKey);
4567
4721
  if (binding) {
4568
4722
  clientRequestBindings.delete(requestKey);
@@ -4577,22 +4731,119 @@ export function createCodexContextProxy({
4577
4731
  typeof responseThreadId === 'string' &&
4578
4732
  responseThreadId === binding.threadId
4579
4733
  ) {
4734
+ if (isConversationThread(binding, message.result.thread))
4735
+ currentThreadId = binding.threadId;
4580
4736
  const claimed = claimOwnedThread(binding.threadId);
4737
+ noteReportedStatus(claimed, message.result.thread);
4581
4738
  if (claimed && !state.resumePending && claimed.idle)
4582
4739
  void requestCompaction(binding.threadId, claimed);
4583
4740
  } else if (!state.owned && state.resumeRequests.size === 0 && state.pending === null) {
4584
4741
  threads.delete(binding.threadId);
4585
4742
  }
4743
+ // Only now: the answer's status is recorded and its compaction check counted.
4744
+ notifyWorkerRoleIdle(binding.threadId);
4586
4745
  } else if (message.error === undefined) {
4587
4746
  const selectedId = message.result?.thread?.id;
4588
4747
  if (typeof selectedId === 'string' && selectedId.length > 0 && selectedId.length <= 256) {
4748
+ if (isConversationThread(binding, message.result.thread)) currentThreadId = selectedId;
4589
4749
  const selected = claimOwnedThread(selectedId);
4590
4750
  if (!selected) return;
4751
+ noteReportedStatus(selected, message.result.thread);
4591
4752
  if (selected.idle) void requestCompaction(selectedId, selected);
4592
4753
  }
4593
4754
  }
4594
4755
  }
4595
4756
  }
4757
+ /**
4758
+ * An answer over the line limit cannot be parsed, but its leading id still
4759
+ * settles the terminal request it answers: a lost resume binding would leave
4760
+ * the thread busy for good. The status stays unknown until the next event.
4761
+ */
4762
+ function settleOversizedAnswer(text) {
4763
+ const requestKey = leadingResponseKey(text);
4764
+ if (requestKey === null) return;
4765
+ answerTerminalWork(requestKey, true);
4766
+ const binding = clientRequestBindings.get(requestKey);
4767
+ if (!binding) return;
4768
+ clientRequestBindings.delete(requestKey);
4769
+ if (binding.method === 'thread/resume' && binding.threadId !== null) {
4770
+ const state = threads.get(binding.threadId);
4771
+ if (state) {
4772
+ state.resumeRequests.delete(requestKey);
4773
+ state.resumePending = state.resumeRequests.size > 0;
4774
+ state.resumeRetryRequested = false;
4775
+ state.reportedStatus = null;
4776
+ }
4777
+ if (!binding.ephemeral) currentThreadId = binding.threadId;
4778
+ } else if (!binding.ephemeral) {
4779
+ // The terminal moved to a thread whose id the adapter could not read.
4780
+ currentThreadId = null;
4781
+ }
4782
+ }
4783
+
4784
+ /** Count a work request of the terminal on its thread (spec FR4 step 1). */
4785
+ function observeTerminalWork(requestKey, params) {
4786
+ const threadId =
4787
+ isRecord(params) && typeof params.threadId === 'string' ? params.threadId : null;
4788
+ if (threadId === null || threadId.length === 0 || threadId.length > 256) return;
4789
+ if (terminalWork.has(requestKey)) return;
4790
+ if (terminalWork.size >= MAX_TERMINAL_WORK) terminalWorkSaturated = true;
4791
+ else {
4792
+ const cancel = scheduleTimeout(
4793
+ () => terminalWorkEnded(requestKey),
4794
+ TERMINAL_WORK_DEADLINE_MS,
4795
+ );
4796
+ terminalWork.set(requestKey, { threadId, answered: false, cancel });
4797
+ }
4798
+ giveUpUnwrittenCompaction(threadId);
4799
+ }
4800
+ /**
4801
+ * A compaction whose thread/compact/start still waits for the terminal's frame
4802
+ * to end would land right after the terminal's work and interrupt it: it gives
4803
+ * up instead, as it does at every check before that write.
4804
+ */
4805
+ function giveUpUnwrittenCompaction(threadId) {
4806
+ const pending = threads.get(threadId)?.pending;
4807
+ if (!pending || pending.compactId === null) return;
4808
+ if (!deferredWrites.some((entry) => entry.ownedId === pending.compactId)) return;
4809
+ fail(threadId, 'Codex state changed during compaction');
4810
+ }
4811
+ function terminalWorkInFlight(threadId) {
4812
+ if (terminalWorkSaturated) return true;
4813
+ for (const work of terminalWork.values()) if (work.threadId === threadId) return true;
4814
+ return false;
4815
+ }
4816
+ function forgetTerminalWork(requestKey) {
4817
+ const work = terminalWork.get(requestKey);
4818
+ if (!work) return null;
4819
+ terminalWork.delete(requestKey);
4820
+ work.cancel();
4821
+ if (terminalWork.size === 0) terminalWorkSaturated = false;
4822
+ return work;
4823
+ }
4824
+ /** The answer came: an error started nothing; a result waits for the status event. */
4825
+ function answerTerminalWork(requestKey, succeeded) {
4826
+ const work = terminalWork.get(requestKey);
4827
+ if (!work) return;
4828
+ if (succeeded) work.answered = true;
4829
+ else terminalWorkEnded(requestKey);
4830
+ }
4831
+ function settleAnsweredTerminalWork(threadId) {
4832
+ for (const [requestKey, work] of [...terminalWork])
4833
+ if (work.threadId === threadId && work.answered) forgetTerminalWork(requestKey);
4834
+ }
4835
+ function settleTerminalWorkOf(threadId) {
4836
+ for (const [requestKey, work] of [...terminalWork])
4837
+ if (work.threadId === threadId) forgetTerminalWork(requestKey);
4838
+ }
4839
+ /** Work that ended without a status event: what it held back may run now. */
4840
+ function terminalWorkEnded(requestKey) {
4841
+ const work = forgetTerminalWork(requestKey);
4842
+ if (work === null || stopped) return;
4843
+ const state = threads.get(work.threadId);
4844
+ if (state?.owned && state.idle) void requestCompaction(work.threadId, state);
4845
+ else notifyWorkerRoleIdle(work.threadId);
4846
+ }
4596
4847
 
4597
4848
  const decoder = new StringDecoder('utf8');
4598
4849
  let inputBuffer = '';
@@ -4663,7 +4914,10 @@ export function createCodexContextProxy({
4663
4914
  if (ownedId !== null) {
4664
4915
  stderr.write('codex-context: oversized internal response rejected\n');
4665
4916
  failOversizedInternal(ownedId, Buffer.byteLength(line, 'utf8') + 1);
4666
- } else forward(`${line}\n`);
4917
+ } else {
4918
+ settleOversizedAnswer(line);
4919
+ forward(`${line}\n`);
4920
+ }
4667
4921
  return;
4668
4922
  }
4669
4923
  let forwardLine = true;
@@ -4675,11 +4929,279 @@ export function createCodexContextProxy({
4675
4929
  return;
4676
4930
  }
4677
4931
  forwardLine = handle(message);
4932
+ if (forwardLine && workerRole !== null)
4933
+ forwardLine = workerRoleObserves(message, `${line}\n`);
4678
4934
  } catch {
4679
4935
  /* preserve malformed external protocol lines */
4680
4936
  }
4681
4937
  if (forwardLine) forward(`${line}\n`);
4682
4938
  };
4939
+ /** A key for a server request id, or null for anything that is not one. */
4940
+ function serverRequestKey(message) {
4941
+ if (!isRecord(message) || typeof message.method !== 'string') return null;
4942
+ return clientRequestKey(message.id);
4943
+ }
4944
+ /** The thread a server message is about, or null. */
4945
+ function messageThreadId(message) {
4946
+ const threadId = isRecord(message.params) ? message.params.threadId : undefined;
4947
+ return typeof threadId === 'string' && threadId.length > 0 && threadId.length <= 256
4948
+ ? threadId
4949
+ : null;
4950
+ }
4951
+ /**
4952
+ * A held request the app-server no longer waits for is dropped, never forwarded:
4953
+ * it was resolved (answered elsewhere, or dropped when the turn ended), or its
4954
+ * thread closed. The role sees the same notification right after.
4955
+ */
4956
+ function dropSettledWorkerHeld(message) {
4957
+ if (message.method === 'serverRequest/resolved' && isRecord(message.params)) {
4958
+ const key = clientRequestKey(message.params.requestId);
4959
+ if (key !== null) workerHeldRequests.delete(key);
4960
+ return;
4961
+ }
4962
+ if (message.method !== 'thread/closed' && message.method !== 'thread/deleted') return;
4963
+ const threadId = messageThreadId(message);
4964
+ for (const [key, held] of [...workerHeldRequests])
4965
+ if (held.threadId === threadId) workerHeldRequests.delete(key);
4966
+ }
4967
+ /**
4968
+ * Show the role a line the terminal is about to get. False means the role
4969
+ * holds it. `canHold` tells the role whether the adapter would: only a command
4970
+ * or file-change approval of a thread, not already held, under the bound. When
4971
+ * the adapter would not, the line goes to the terminal whatever the role says.
4972
+ * A role that fails never keeps a line from the terminal.
4973
+ */
4974
+ function workerRoleObserves(message, text) {
4975
+ if (workerRoleStopped) return true;
4976
+ dropSettledWorkerHeld(message);
4977
+ const key = serverRequestKey(message);
4978
+ const threadId = messageThreadId(message);
4979
+ const canHold =
4980
+ key !== null &&
4981
+ threadId !== null &&
4982
+ WORKER_HOLDABLE_METHODS.has(message.method) &&
4983
+ !workerHeldRequests.has(key) &&
4984
+ workerHeldRequests.size < MAX_WORKER_HELD_REQUESTS;
4985
+ let held = false;
4986
+ try {
4987
+ held = workerRole.onServerMessage(message, text, { canHold }) === false;
4988
+ } catch {
4989
+ held = false;
4990
+ }
4991
+ if (!held || !canHold) return true;
4992
+ workerHeldRequests.set(key, { text, id: message.id, threadId });
4993
+ return false;
4994
+ }
4995
+ function notifyWorkerRoleIdle(threadId) {
4996
+ if (workerRole === null || stopped || workerRoleStopped || workerThreadBusy(threadId)) return;
4997
+ try {
4998
+ workerRole.onAdapterIdle(threadId);
4999
+ } catch {
5000
+ /* the role never affects the adapter's own lifecycle */
5001
+ }
5002
+ }
5003
+ /** A start, resume or fork of the terminal awaits its answer: the thread may change. */
5004
+ function threadBindingPending(threadId) {
5005
+ for (const binding of clientRequestBindings.values())
5006
+ if (binding.method === 'thread/start' || binding.threadId === threadId) return true;
5007
+ return false;
5008
+ }
5009
+ /**
5010
+ * A turn/start of the role the app-server has not answered. It has no deadline:
5011
+ * an answer that comes late still starts that turn, and a second one written
5012
+ * meanwhile would merge into it.
5013
+ */
5014
+ function workerTurnUnanswered(threadId) {
5015
+ for (const owned of ownedRequests.values())
5016
+ if (owned.kind === 'worker' && owned.threadId === threadId) return true;
5017
+ return false;
5018
+ }
5019
+ /**
5020
+ * Whether a lifecycle of this adapter, or work of the terminal, runs or is about
5021
+ * to run on the thread.
5022
+ */
5023
+ function workerThreadBusy(threadId) {
5024
+ if (terminalWorkInFlight(threadId) || threadBindingPending(threadId)) return true;
5025
+ if (workerTurnUnanswered(threadId)) return true;
5026
+ const state = threads.get(threadId);
5027
+ if (!state) return false;
5028
+ return (
5029
+ state.pending !== null ||
5030
+ state.resumePending ||
5031
+ state.recoveryAttach !== null ||
5032
+ state.lifecycleChecks > 0
5033
+ );
5034
+ }
5035
+ /** A refusal of this adapter's own gate: nothing was written, so it is not the app-server's. */
5036
+ function workerGateRejection(reason) {
5037
+ return Object.assign(new Error(reason), { adapterGate: true });
5038
+ }
5039
+ /** A plain object: no prototype of its own, so no toJSON or inherited fields. */
5040
+ function isPlainRecord(value) {
5041
+ if (!isRecord(value) || Array.isArray(value)) return false;
5042
+ const prototype = Object.getPrototypeOf(value);
5043
+ return prototype === Object.prototype || prototype === null;
5044
+ }
5045
+ /**
5046
+ * One text input and nothing else: the role cannot override how the thread runs.
5047
+ * Each field is read once and the turn written is built from those reads, so
5048
+ * what the app-server gets is exactly what was checked. Null when not allowed.
5049
+ */
5050
+ function workerTurnFrom(params) {
5051
+ if (!isPlainRecord(params) || Object.keys(params).some((key) => !WORKER_TURN_KEYS.has(key)))
5052
+ return null;
5053
+ const { threadId, clientUserMessageId, input } = params;
5054
+ if (typeof threadId !== 'string' || threadId.length === 0 || threadId.length > 256) return null;
5055
+ if (typeof clientUserMessageId !== 'string') return null;
5056
+ if (!Array.isArray(input) || Object.getPrototypeOf(input) !== Array.prototype) return null;
5057
+ if (input.length !== 1) return null;
5058
+ const item = input[0];
5059
+ if (!isPlainRecord(item) || Object.keys(item).some((key) => !WORKER_INPUT_KEYS.has(key)))
5060
+ return null;
5061
+ const { type, text } = item;
5062
+ if (type !== 'text' || typeof text !== 'string') return null;
5063
+ return { threadId, clientUserMessageId, input: [{ type: 'text', text }] };
5064
+ }
5065
+ /** A role turn is written and not yet reported; it stops counting at the deadline. */
5066
+ function beginWorkerTurnStart(state) {
5067
+ endWorkerTurnStart(state);
5068
+ state.workerTurnStarting = true;
5069
+ state.workerTurnTimer = scheduleTimeout(() => {
5070
+ state.workerTurnTimer = null;
5071
+ state.workerTurnStarting = false;
5072
+ }, WORKER_TURN_START_DEADLINE_MS);
5073
+ }
5074
+ function endWorkerTurnStart(state) {
5075
+ if (!state) return;
5076
+ state.workerTurnStarting = false;
5077
+ const cancel = state.workerTurnTimer;
5078
+ state.workerTurnTimer = null;
5079
+ if (typeof cancel === 'function') cancel();
5080
+ }
5081
+ /** A deferred line still worth writing: an answer, or a request not given up on. */
5082
+ function isLiveWrite(entry) {
5083
+ return entry.ownedId === null || ownedRequests.has(entry.ownedId);
5084
+ }
5085
+ /**
5086
+ * Write to the app-server once no terminal frame is half written to it: a line
5087
+ * of the adapter's inside a terminal line corrupts both. `ownedId` names the
5088
+ * adapter request the line carries, so one given up on meanwhile is not sent.
5089
+ */
5090
+ function writeAtClientBoundary(value, ownedId = null) {
5091
+ if (deferredWrites.length === 0 && clientAtLineBoundary()) {
5092
+ writeJsonLine(child.stdin, value);
5093
+ return;
5094
+ }
5095
+ // Requests given up on leave here, so a terminal that never ends its frame
5096
+ // cannot grow the queue past the adapter's own request and hold limits.
5097
+ for (let index = deferredWrites.length - 1; index >= 0; index -= 1)
5098
+ if (!isLiveWrite(deferredWrites[index])) deferredWrites.splice(index, 1);
5099
+ deferredWrites.push({ value, ownedId });
5100
+ }
5101
+ function flushDeferredWrites() {
5102
+ while (!stopped && deferredWrites.length > 0 && clientAtLineBoundary()) {
5103
+ const entry = deferredWrites.shift();
5104
+ if (!isLiveWrite(entry)) continue;
5105
+ try {
5106
+ writeJsonLine(child.stdin, entry.value);
5107
+ } catch {
5108
+ if (entry.ownedId !== null) cleanupRequest(entry.ownedId);
5109
+ }
5110
+ }
5111
+ }
5112
+ // What the worker role may do through this adapter, and nothing more.
5113
+ const workerPort = {
5114
+ request(method, params) {
5115
+ if (stopped || workerRoleStopped) return Promise.reject(new Error('adapter stopped'));
5116
+ const turn = method === WORKER_ROLE_METHOD ? workerTurnFrom(params) : null;
5117
+ if (turn === null) return Promise.reject(new Error('worker request not allowed'));
5118
+ // The role converses only on the terminal's current thread (spec FR4 step 1).
5119
+ if (turn.threadId !== currentThreadId)
5120
+ return Promise.reject(workerGateRejection('thread not current'));
5121
+ // The app-server does not protect a busy thread, so the checks are repeated
5122
+ // here, at the moment of the write.
5123
+ const state = threads.get(turn.threadId);
5124
+ if (
5125
+ !state ||
5126
+ !WORKER_TURN_STATUSES.has(state.reportedStatus) ||
5127
+ state.workerTurnStarting ||
5128
+ workerThreadBusy(turn.threadId)
5129
+ )
5130
+ return Promise.reject(workerGateRejection('thread not idle'));
5131
+ if (!clientAtLineBoundary())
5132
+ return Promise.reject(workerGateRejection('client frame in flight'));
5133
+ const waiter = deferred();
5134
+ try {
5135
+ sendOwned(method, turn, 'worker', turn.threadId, waiter);
5136
+ } catch (error) {
5137
+ return Promise.reject(error);
5138
+ }
5139
+ beginWorkerTurnStart(state);
5140
+ return waiter.promise;
5141
+ },
5142
+ /** True when the answer was written, or waits only for the terminal's frame to end. */
5143
+ respond(requestId, result) {
5144
+ const key = clientRequestKey(requestId);
5145
+ const held = key === null ? undefined : workerHeldRequests.get(key);
5146
+ if (held === undefined || !isPlainRecord(result)) return false;
5147
+ const keys = Object.keys(result);
5148
+ if (keys.length !== 1 || keys[0] !== 'decision') return false;
5149
+ // Read once, from the object's own data property: an accessor gives no value.
5150
+ const decision = Object.getOwnPropertyDescriptor(result, 'decision')?.value;
5151
+ if (!WORKER_ROLE_DECISIONS.has(decision)) return false;
5152
+ workerHeldRequests.delete(key);
5153
+ writeAtClientBoundary({ id: held.id, result: { decision } });
5154
+ return true;
5155
+ },
5156
+ forward(text) {
5157
+ for (const [key, held] of workerHeldRequests) {
5158
+ if (held.text !== text) continue;
5159
+ workerHeldRequests.delete(key);
5160
+ forward(held.text);
5161
+ return;
5162
+ }
5163
+ },
5164
+ threadBusy: workerThreadBusy,
5165
+ clientAtLineBoundary: () => clientAtLineBoundary(),
5166
+ };
5167
+ /** Everything the role still holds goes to the terminal, in the order it came. */
5168
+ function releaseWorkerHeld() {
5169
+ const held = [...workerHeldRequests.values()];
5170
+ workerHeldRequests.clear();
5171
+ for (const entry of held) forward(entry.text);
5172
+ }
5173
+ /**
5174
+ * The terminal gets every held request first, so a role that never finishes
5175
+ * stopping keeps none of them; then the role's stop() gets a bounded wait.
5176
+ */
5177
+ async function stopWorkerRole() {
5178
+ if (workerRole === null || workerRoleStopped) return;
5179
+ workerRoleStopped = true;
5180
+ releaseWorkerHeld();
5181
+ let stopping;
5182
+ try {
5183
+ stopping = Promise.resolve(workerRole.stop()).catch(() => undefined);
5184
+ } catch {
5185
+ /* the role's cleanup never keeps the adapter from stopping */
5186
+ return;
5187
+ }
5188
+ let cancel = () => undefined;
5189
+ const bound = new Promise((resolve) => {
5190
+ cancel = scheduleTimeout(resolve, WORKER_ROLE_STOP_TIMEOUT_MS);
5191
+ });
5192
+ try {
5193
+ await Promise.race([stopping, bound]);
5194
+ } finally {
5195
+ cancel();
5196
+ }
5197
+ }
5198
+ /** No timer of the adapter's own outlives it. */
5199
+ function cancelAdapterTimers() {
5200
+ for (const work of terminalWork.values()) work.cancel();
5201
+ terminalWork.clear();
5202
+ terminalWorkSaturated = false;
5203
+ for (const state of threads.values()) endWorkerTurnStart(state);
5204
+ }
4683
5205
  function internalRequestId(line) {
4684
5206
  const match =
4685
5207
  /^\s*\{\s*(?:"id"\s*:\s*"(ai-brain-context-[A-Za-z0-9._:-]{1,128})"|"jsonrpc"\s*:\s*"2\.0"\s*,\s*"id"\s*:\s*"(ai-brain-context-[A-Za-z0-9._:-]{1,128})")/u.exec(
@@ -4711,7 +5233,7 @@ export function createCodexContextProxy({
4711
5233
  return;
4712
5234
  }
4713
5235
  cleanupRequest(id);
4714
- if (owned.kind === 'telemetry') return;
5236
+ if (owned.kind === 'telemetry' || owned.kind === 'worker') return;
4715
5237
  const failure = new Error('oversized internal response');
4716
5238
  failure.diagnosticReason = 'capture_size_exceeded';
4717
5239
  failure.responseBytes = responseBytes;
@@ -4752,6 +5274,7 @@ export function createCodexContextProxy({
4752
5274
  discardOversized = true;
4753
5275
  inputBuffer = '';
4754
5276
  } else {
5277
+ settleOversizedAnswer(inputBuffer);
4755
5278
  forward(inputBuffer);
4756
5279
  inputBuffer = '';
4757
5280
  passthrough = true;
@@ -4784,12 +5307,36 @@ export function createCodexContextProxy({
4784
5307
  child.stderr.on('data', () => undefined);
4785
5308
  child.stderr.resume?.();
4786
5309
  }
5310
+ if (typeof createWorkerRole === 'function') {
5311
+ try {
5312
+ workerRole = createWorkerRole(workerPort) ?? null;
5313
+ if (workerRole !== null) void Promise.resolve(workerRole.start()).catch(() => undefined);
5314
+ } catch {
5315
+ workerRole = null;
5316
+ }
5317
+ }
4787
5318
  return {
4788
5319
  threads,
4789
5320
  observeClientRequest,
4790
5321
  observeClientResponse,
5322
+ /** Every parsed terminal frame: the adapter's own bookkeeping, then the role's. */
5323
+ observeClientMessage(message) {
5324
+ observeClientRequest(message);
5325
+ if (workerRole === null || workerRoleStopped) return;
5326
+ try {
5327
+ workerRole.onClientMessage(message);
5328
+ } catch {
5329
+ /* the role only observes */
5330
+ }
5331
+ },
5332
+ /** The terminal's last chunk reached the app-server: deferred writes may go. */
5333
+ clientChunkWritten() {
5334
+ flushDeferredWrites();
5335
+ },
4791
5336
  async stop() {
4792
5337
  releaseEngineering();
5338
+ await stopWorkerRole();
5339
+ cancelAdapterTimers();
4793
5340
  if (stopped) {
4794
5341
  await Promise.all(
4795
5342
  [...diagnosticSinks.values()].map((sink) =>
@@ -4831,6 +5378,41 @@ export function engineeringSkillsRootFrom(value) {
4831
5378
  return value;
4832
5379
  }
4833
5380
 
5381
+ /**
5382
+ * The launcher's worker module, or null. Only an absolute, normalized path
5383
+ * without control characters that names the client's worker module is loaded.
5384
+ */
5385
+ export function workerModulePathFrom(value) {
5386
+ if (typeof value !== 'string' || value.length === 0) return null;
5387
+ if (value.length > MAX_ENGINEERING_PATH_LENGTH || /[\u0000-\u001f\u007f]/u.test(value))
5388
+ return null;
5389
+ if (!value.startsWith('/') || resolve(value) !== value) return null;
5390
+ return value.endsWith(WORKER_MODULE_SUFFIX) ? value : null;
5391
+ }
5392
+
5393
+ /**
5394
+ * How this adapter gets its worker role (ADR-0058), or null: no role in the
5395
+ * environment, no module, or a module that does not load all leave the adapter
5396
+ * exactly as it is without the feature.
5397
+ */
5398
+ export async function workerRoleFactoryFrom(environment) {
5399
+ if (typeof environment[WORKER_ROLE_ENV] !== 'string') return null;
5400
+ const modulePath = workerModulePathFrom(environment[WORKER_MODULE_ENV]);
5401
+ if (modulePath === null) return null;
5402
+ try {
5403
+ const module = await import(pathToFileURL(modulePath).href);
5404
+ if (typeof module.createWorkerRoleFromEnvironment !== 'function') return null;
5405
+ // The role and the Codex home whose config the reserve protects; nothing else.
5406
+ const role = {
5407
+ [WORKER_ROLE_ENV]: environment[WORKER_ROLE_ENV],
5408
+ ...(typeof environment.CODEX_HOME === 'string' ? { CODEX_HOME: environment.CODEX_HOME } : {}),
5409
+ };
5410
+ return (port) => module.createWorkerRoleFromEnvironment(role, port, { cwd: process.cwd() });
5411
+ } catch {
5412
+ return null;
5413
+ }
5414
+ }
5415
+
4834
5416
  async function main() {
4835
5417
  if (process.argv.includes('--help')) {
4836
5418
  process.stderr.write(
@@ -4879,6 +5461,12 @@ async function main() {
4879
5461
  diagnosticFactory = null;
4880
5462
  }
4881
5463
  }
5464
+ const clientDecoder = new StringDecoder('utf8');
5465
+ let clientInputBuffer = '';
5466
+ let discardOversizedClientFrame = false;
5467
+ // True from the moment a terminal chunk arrives until the pipe below has
5468
+ // written it: nothing of the adapter's may be written in between.
5469
+ let clientChunkInFlight = false;
4882
5470
  const proxy = createCodexContextProxy({
4883
5471
  child,
4884
5472
  threshold: numberEnv('CODEX_CONTEXT_COMPACT_AT', DEFAULT_THRESHOLD),
@@ -4886,11 +5474,12 @@ async function main() {
4886
5474
  policy,
4887
5475
  createDiagnosticSink: diagnosticFactory,
4888
5476
  engineeringSkillsRoot: engineeringSkillsRootFrom(process.env[ENGINEERING_SKILLS_ROOT_ENV]),
5477
+ createWorkerRole: await workerRoleFactoryFrom(process.env),
5478
+ clientAtLineBoundary: () =>
5479
+ !clientChunkInFlight && clientInputBuffer.length === 0 && !discardOversizedClientFrame,
4889
5480
  });
4890
- const clientDecoder = new StringDecoder('utf8');
4891
- let clientInputBuffer = '';
4892
- let discardOversizedClientFrame = false;
4893
5481
  process.stdin.on('data', (chunk) => {
5482
+ clientChunkInFlight = true;
4894
5483
  const decoded = clientDecoder.write(chunk);
4895
5484
  if (discardOversizedClientFrame) {
4896
5485
  const newline = decoded.indexOf('\n');
@@ -4906,7 +5495,7 @@ async function main() {
4906
5495
  if (!line) continue;
4907
5496
  if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) continue;
4908
5497
  try {
4909
- proxy.observeClientRequest(JSON.parse(line));
5498
+ proxy.observeClientMessage(JSON.parse(line));
4910
5499
  } catch {
4911
5500
  /* Preserve malformed/native frames unchanged; the app-server owns validation. */
4912
5501
  }
@@ -4917,6 +5506,11 @@ async function main() {
4917
5506
  }
4918
5507
  });
4919
5508
  process.stdin.pipe(child.stdin);
5509
+ // Registered after the pipe, so it runs once the chunk is written.
5510
+ process.stdin.on('data', () => {
5511
+ clientChunkInFlight = false;
5512
+ proxy.clientChunkWritten();
5513
+ });
4920
5514
  process.stdin.on('end', () => child.stdin.end());
4921
5515
  child.on('exit', async (code, signal) => {
4922
5516
  await proxy.stop();