@aisac/cli 0.4.0-beta.2 → 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.
Files changed (60) hide show
  1. package/README.md +146 -10
  2. package/dist/assets/claude/hooks/context-compaction.ts +17 -5
  3. package/dist/assets/claude/hooks/native-host-contract-runtime.ts +1 -1
  4. package/dist/assets/claude/hooks/native-host-contract.test.ts +8 -4
  5. package/dist/assets/claude/hooks/provider-window.d.ts +83 -0
  6. package/dist/assets/codex-context-compaction.mjs +846 -14
  7. package/dist/assets/jev-paid-pilot-terminal.mjs +12 -1
  8. package/dist/claude-compatibility.mjs +26 -25
  9. package/dist/claude-observation.mjs +2 -1
  10. package/dist/cli.mjs +641 -35
  11. package/dist/codex-compatibility.mjs +48 -2
  12. package/dist/codex-engineering.mjs +165 -0
  13. package/dist/codex-hooks.mjs +411 -0
  14. package/dist/codex-permissions.mjs +67 -34
  15. package/dist/codex-protocol-fingerprint.json +11 -11
  16. package/dist/engineering-init.mjs +615 -0
  17. package/dist/engineering-pack.mjs +276 -23
  18. package/dist/engineering-scan-pins.json +42 -0
  19. package/dist/engineering-scan-report.mjs +1274 -0
  20. package/dist/engineering-scan-tools.mjs +1418 -0
  21. package/dist/engineering-scan.mjs +1265 -0
  22. package/dist/extensions-catalog.mjs +390 -0
  23. package/dist/extensions-cli.mjs +492 -0
  24. package/dist/extensions-preferences.mjs +151 -0
  25. package/dist/guardrails/continuity.mjs +239 -0
  26. package/dist/guardrails/format.mjs +111 -0
  27. package/dist/guardrails/guards.mjs +1557 -0
  28. package/dist/guardrails/patch.mjs +33 -0
  29. package/dist/guardrails/run.mjs +286 -0
  30. package/dist/guardrails/shell-words.mjs +206 -0
  31. package/dist/guardrails-plugin.mjs +207 -0
  32. package/dist/launch.mjs +403 -47
  33. package/dist/managed-host.mjs +977 -0
  34. package/dist/manager/bus.mjs +1921 -0
  35. package/dist/manager/delegation.mjs +354 -0
  36. package/dist/manager/hooks.mjs +918 -0
  37. package/dist/manager/launch-role.mjs +476 -0
  38. package/dist/manager/mcp-stdio.mjs +463 -0
  39. package/dist/manager/messages.mjs +791 -0
  40. package/dist/manager/reserve.mjs +2166 -0
  41. package/dist/manager/room.mjs +106 -0
  42. package/dist/manager/server.mjs +1792 -0
  43. package/dist/manager/status.mjs +118 -0
  44. package/dist/manager/watch.mjs +87 -0
  45. package/dist/manager/worker.mjs +2793 -0
  46. package/dist/manager/workers-cli.mjs +1403 -0
  47. package/dist/mcp-servers.mjs +192 -0
  48. package/dist/mcp.mjs +10 -2
  49. package/dist/monitor.mjs +76 -1
  50. package/dist/package.json +1 -1
  51. package/dist/platform.mjs +78 -29
  52. package/dist/release-manifest-public-keys.json +10 -0
  53. package/dist/release-manifest.json +328 -0
  54. package/dist/release-manifest.mjs +817 -0
  55. package/dist/release-settings.mjs +210 -0
  56. package/dist/self-update.mjs +1036 -0
  57. package/dist/state.mjs +25 -1
  58. package/dist/token-guide.mjs +132 -0
  59. package/dist/update-actions.mjs +442 -0
  60. package/package.json +1 -1
@@ -54,6 +54,55 @@ const MAX_OWNED_REQUESTS = 1_000;
54
54
  const MAX_RETIRED_REQUESTS = 2_000;
55
55
  const MAX_CLIENT_REQUEST_BINDINGS = 128;
56
56
  const MAX_OWNED_THREAD_IDS = 256;
57
+ // AISAC Engineering (ADR-0047 E4c): the launcher's skills root is added to the
58
+ // owned app-server before the client sees its initialize answer.
59
+ const ENGINEERING_SKILLS_ROOT_ENV = 'AISAC_ENGINEERING_SKILLS_ROOT';
60
+ const ENGINEERING_SKILLS_ACK_TIMEOUT_MS = 2_000;
61
+ const MAX_ENGINEERING_PATH_LENGTH = 4_096;
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;
57
106
  const MAX_RECOVERY_ITEMS = 128;
58
107
  const MAX_RECOVERY_SOURCE_INDEX = 65_536;
59
108
  const MAX_NOTE_BYTES = 128 * 1024;
@@ -270,6 +319,10 @@ function codexChildEnvironment() {
270
319
  const environment = { ...process.env };
271
320
  delete environment.JEV_API_KEY;
272
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];
273
326
  return environment;
274
327
  }
275
328
  function isRecord(value) {
@@ -392,6 +445,19 @@ function clientRequestKey(value) {
392
445
  return null;
393
446
  }
394
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
+
395
461
  /**
396
462
  * Closed private diagnostic contract consumed by the client sink. It contains
397
463
  * stage/reason enums, pseudonymous session identity, operation/correlation
@@ -1001,6 +1067,128 @@ async function processIdentity(pid) {
1001
1067
  }
1002
1068
  }
1003
1069
 
1070
+ // macOS has flock(2) but no util-linux helper and no /proc (ADR-0049, spec
1071
+ // codex-macos). The guard helper and the owner identity use fixed system paths:
1072
+ // never PATH lookups, never a shell.
1073
+ const DARWIN_CAPTURE_TOOLS = Object.freeze({
1074
+ perl: '/usr/bin/perl',
1075
+ sysctl: '/usr/sbin/sysctl',
1076
+ ps: '/bin/ps',
1077
+ });
1078
+ const DARWIN_FLOCK_ARGS = Object.freeze([
1079
+ '-MFcntl=:flock',
1080
+ '-e',
1081
+ 'open(my $f, "+<&=", 3) or exit 2; exit(flock($f, LOCK_EX | LOCK_NB) ? 0 : 1)',
1082
+ ]);
1083
+ const DARWIN_TOOL_ENV = Object.freeze({ LC_ALL: 'C', TZ: 'UTC', PATH: '/usr/bin:/bin:/usr/sbin' });
1084
+ const DARWIN_TOOL_TIMEOUT_MS = 2_000;
1085
+ const DARWIN_TOOL_MAX_OUTPUT_BYTES = 4096;
1086
+ const DARWIN_START_TIME = /^[\x20-\x7e]{1,64}$/u;
1087
+ const BOOT_SESSION = /^[a-f0-9-]{36}$/iu;
1088
+ const PS_NO_MATCHING_PROCESS = 1;
1089
+
1090
+ /** Platform and tool paths of the capture lock; replaced only by tests. */
1091
+ let captureLockHost = { platform: process.platform, tools: DARWIN_CAPTURE_TOOLS };
1092
+
1093
+ export function __testSetCaptureLockHost(host) {
1094
+ const previous = captureLockHost;
1095
+ captureLockHost = host;
1096
+ return previous;
1097
+ }
1098
+
1099
+ function guardHelperCommand() {
1100
+ return captureLockHost.platform === 'darwin'
1101
+ ? [captureLockHost.tools.perl, [...DARWIN_FLOCK_ARGS]]
1102
+ : ['flock', ['-x', '-n', '3']];
1103
+ }
1104
+
1105
+ /** @returns {Promise<{ code: number | null, stdout: string }>} */
1106
+ function runDarwinTool(command, args) {
1107
+ return new Promise((resolvePromise) => {
1108
+ const child = spawn(command, args, {
1109
+ env: DARWIN_TOOL_ENV,
1110
+ stdio: ['ignore', 'pipe', 'ignore'],
1111
+ });
1112
+ let stdout = '';
1113
+ let settled = false;
1114
+ const finish = (code) => {
1115
+ if (settled) return;
1116
+ settled = true;
1117
+ clearTimeout(timer);
1118
+ resolvePromise({ code, stdout });
1119
+ };
1120
+ const timer = setTimeout(() => {
1121
+ child.kill('SIGKILL');
1122
+ finish(null);
1123
+ }, DARWIN_TOOL_TIMEOUT_MS);
1124
+ child.stdout.setEncoding('utf8');
1125
+ child.stdout.on('data', (chunk) => {
1126
+ stdout += chunk;
1127
+ if (Buffer.byteLength(stdout) > DARWIN_TOOL_MAX_OUTPUT_BYTES) {
1128
+ child.kill('SIGKILL');
1129
+ finish(null);
1130
+ }
1131
+ });
1132
+ child.once('error', () => finish(null));
1133
+ child.once('close', (code) => finish(code));
1134
+ });
1135
+ }
1136
+
1137
+ async function darwinBootSession() {
1138
+ const result = await runDarwinTool(captureLockHost.tools.sysctl, ['-n', 'kern.bootsessionuuid']);
1139
+ const value = result.stdout.trim();
1140
+ return result.code === 0 && BOOT_SESSION.test(value) ? value.toUpperCase() : null;
1141
+ }
1142
+
1143
+ async function darwinProcessIdentity(pid) {
1144
+ if (!Number.isSafeInteger(pid) || pid <= 0) return { status: 'invalid' };
1145
+ const bootSession = await darwinBootSession();
1146
+ if (bootSession === null) return { status: 'unverifiable' };
1147
+ const result = await runDarwinTool(captureLockHost.tools.ps, [
1148
+ '-o',
1149
+ 'lstart=',
1150
+ '-p',
1151
+ String(pid),
1152
+ ]);
1153
+ const startTime = result.stdout.trim();
1154
+ // BSD ps exits 1 with no output when no process matches the pid.
1155
+ if (result.code === PS_NO_MATCHING_PROCESS && startTime === '') return { status: 'dead' };
1156
+ if (result.code !== 0 || !DARWIN_START_TIME.test(startTime)) return { status: 'unverifiable' };
1157
+ return { status: 'live', startTime, bootSession };
1158
+ }
1159
+
1160
+ async function darwinSentinelOwner(value) {
1161
+ if (
1162
+ !isRecord(value) ||
1163
+ !hasOnlyKeys(value, [
1164
+ 'schema',
1165
+ 'backend',
1166
+ 'platform',
1167
+ 'pid',
1168
+ 'startTime',
1169
+ 'bootSession',
1170
+ 'nonce',
1171
+ ]) ||
1172
+ value.schema !== 1 ||
1173
+ value.backend !== 'flock' ||
1174
+ value.platform !== 'darwin' ||
1175
+ !isSafeBoundedInteger(value.pid, 1, 4_000_000_000) ||
1176
+ typeof value.startTime !== 'string' ||
1177
+ !DARWIN_START_TIME.test(value.startTime) ||
1178
+ typeof value.bootSession !== 'string' ||
1179
+ !BOOT_SESSION.test(value.bootSession) ||
1180
+ typeof value.nonce !== 'string' ||
1181
+ !isUuid(value.nonce)
1182
+ )
1183
+ return { status: 'unverifiable' };
1184
+ const observer = await darwinBootSession();
1185
+ if (observer === null) return { status: 'unverifiable' };
1186
+ if (observer !== value.bootSession.toUpperCase()) return { status: 'dead' };
1187
+ const current = await darwinProcessIdentity(value.pid);
1188
+ if (current.status !== 'live') return { status: current.status };
1189
+ return current.startTime === value.startTime ? { status: 'live' } : { status: 'dead' };
1190
+ }
1191
+
1004
1192
  async function captureSentinelOwner(lockPath, fsOps) {
1005
1193
  let info;
1006
1194
  try {
@@ -1019,6 +1207,7 @@ async function captureSentinelOwner(lockPath, fsOps) {
1019
1207
  } catch {
1020
1208
  return { status: 'unverifiable' };
1021
1209
  }
1210
+ if (captureLockHost.platform === 'darwin') return darwinSentinelOwner(value);
1022
1211
  if (
1023
1212
  !isRecord(value) ||
1024
1213
  !hasOnlyKeys(value, [
@@ -1054,10 +1243,23 @@ async function captureSentinelOwner(lockPath, fsOps) {
1054
1243
  return current.startTime === value.startTime ? { status: 'live' } : { status: 'dead' };
1055
1244
  }
1056
1245
 
1057
- async function ensureCaptureSentinel(lockPath, task) {
1246
+ async function ownSentinelRecord() {
1247
+ if (captureLockHost.platform === 'darwin') {
1248
+ const identity = await darwinProcessIdentity(process.pid);
1249
+ if (identity.status !== 'live') throw captureLockError('capture_lock_owner_unverifiable');
1250
+ return {
1251
+ schema: 1,
1252
+ backend: 'flock',
1253
+ platform: 'darwin',
1254
+ pid: process.pid,
1255
+ startTime: identity.startTime,
1256
+ bootSession: identity.bootSession,
1257
+ nonce: randomUUID(),
1258
+ };
1259
+ }
1058
1260
  const identity = await processIdentity(process.pid);
1059
1261
  if (identity.status !== 'live') throw captureLockError('capture_lock_owner_unverifiable');
1060
- const metadata = `${JSON.stringify({
1262
+ return {
1061
1263
  schema: 1,
1062
1264
  backend: 'flock',
1063
1265
  pid: process.pid,
@@ -1065,7 +1267,11 @@ async function ensureCaptureSentinel(lockPath, task) {
1065
1267
  bootId: identity.bootId,
1066
1268
  pidNamespace: identity.pidNamespace,
1067
1269
  nonce: randomUUID(),
1068
- })}\n`;
1270
+ };
1271
+ }
1272
+
1273
+ async function ensureCaptureSentinel(lockPath, task) {
1274
+ const metadata = `${JSON.stringify(await ownSentinelRecord())}\n`;
1069
1275
  while (true) {
1070
1276
  const temporary = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
1071
1277
  let contention = false;
@@ -1143,7 +1349,8 @@ async function withAdvisoryCaptureLock(directory, task) {
1143
1349
  while (true) {
1144
1350
  let helper;
1145
1351
  try {
1146
- helper = spawn('flock', ['-x', '-n', '3'], {
1352
+ const [command, args] = guardHelperCommand();
1353
+ helper = spawn(command, args, {
1147
1354
  stdio: ['ignore', 'ignore', 'ignore', guardHandle.fd],
1148
1355
  });
1149
1356
  const acquired = await new Promise((resolvePromise, rejectPromise) => {
@@ -2707,6 +2914,10 @@ export function createCodexContextProxy({
2707
2914
  createDiagnosticSink = null,
2708
2915
  brainServer = process.env.AI_BRAIN_MCP_SERVER ?? 'brain',
2709
2916
  clientVersion = process.env.CODEX_CLIENT_VERSION ?? '0.161.0',
2917
+ engineeringSkillsRoot = null,
2918
+ engineeringAckTimeoutMs = ENGINEERING_SKILLS_ACK_TIMEOUT_MS,
2919
+ createWorkerRole = null,
2920
+ clientAtLineBoundary = () => true,
2710
2921
  }) {
2711
2922
  const contextPolicy = normalizeContextPolicy(policy);
2712
2923
  const effectiveThreshold = contextPolicy?.compactAtPercent ?? threshold;
@@ -2719,6 +2930,31 @@ export function createCodexContextProxy({
2719
2930
  const telemetryByThread = new Map();
2720
2931
  const diagnosticSinks = new Map();
2721
2932
  let stopped = false;
2933
+ // AISAC Engineering skills root: 'off' without a root; 'waiting' for the
2934
+ // client's first successful initialize; 'holding' app-server output until
2935
+ // skills/extraRoots/set is answered (or times out); then 'done'.
2936
+ let engineeringState =
2937
+ typeof engineeringSkillsRoot === 'string' && engineeringSkillsRoot.length > 0
2938
+ ? 'waiting'
2939
+ : 'off';
2940
+ const initializeRequestKeys = new Set();
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 = [];
2722
2958
  function emitDiagnostic(event) {
2723
2959
  try {
2724
2960
  const phase = typeof event?.phase === 'string' ? event.phase : '';
@@ -2809,7 +3045,10 @@ export function createCodexContextProxy({
2809
3045
  }
2810
3046
  function cleanupRequest(id) {
2811
3047
  if (!id) return;
3048
+ const owned = ownedRequests.get(id);
2812
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));
2813
3052
  const waiter = internalReads.get(id);
2814
3053
  if (waiter) {
2815
3054
  internalReads.delete(id);
@@ -2896,6 +3135,17 @@ export function createCodexContextProxy({
2896
3135
  resumePending: false,
2897
3136
  resumeRetryRequested: false,
2898
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,
2899
3149
  };
2900
3150
  threads.set(threadId, created);
2901
3151
  return created;
@@ -2917,7 +3167,7 @@ export function createCodexContextProxy({
2917
3167
  ownedRequests.set(id, { kind, threadId });
2918
3168
  if (waiter) internalReads.set(id, waiter);
2919
3169
  try {
2920
- writeJsonLine(child.stdin, { id, method, params });
3170
+ writeAtClientBoundary({ id, method, params }, id);
2921
3171
  } catch (error) {
2922
3172
  cleanupRequest(id);
2923
3173
  throw error;
@@ -3106,7 +3356,14 @@ export function createCodexContextProxy({
3106
3356
  reporter.failed({ operationId, reason: 'native_error' });
3107
3357
  }
3108
3358
  function assertCurrent(threadId, state, pending, revision) {
3109
- 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
+ )
3110
3367
  throw new Error('Codex state changed during compaction');
3111
3368
  }
3112
3369
  async function readThreadCapture(
@@ -3552,13 +3809,31 @@ export function createCodexContextProxy({
3552
3809
  if (state.recoveryAttach === attachment) state.recoveryAttach = null;
3553
3810
  }
3554
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
+ */
3555
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) {
3556
3827
  if (!state.owned) return;
3557
3828
  if (state.resumePending) {
3558
3829
  state.resumeRetryRequested = true;
3559
3830
  return;
3560
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;
3561
3835
  if (recoveryEnabled && recoveryDisclosed) await loadRecoveryState(threadId, state);
3836
+ if (state.workerTurnStarting || terminalWorkInFlight(threadId)) return;
3562
3837
  if (
3563
3838
  state.recovery &&
3564
3839
  ['pending_attachment', 'recovery_uncertain'].includes(state.recovery.status)
@@ -4131,6 +4406,21 @@ export function createCodexContextProxy({
4131
4406
  const owned = ownedRequests.get(message.id);
4132
4407
  ownedRequests.delete(message.id);
4133
4408
  retire(message.id);
4409
+ if (owned.kind === 'engineering') {
4410
+ // An error leaves the session without the pack skills; it is never shown.
4411
+ releaseEngineering();
4412
+ return false;
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
+ }
4134
4424
  if (
4135
4425
  owned.kind === 'read' ||
4136
4426
  owned.kind === 'page' ||
@@ -4181,11 +4471,17 @@ export function createCodexContextProxy({
4181
4471
  typeof message.params.threadId === 'string' &&
4182
4472
  isRecord(message.params.status)
4183
4473
  ) {
4474
+ // The status event that follows the answer to a work request of the terminal.
4475
+ settleAnsweredTerminalWork(message.params.threadId);
4184
4476
  const state = threads.get(message.params.threadId);
4185
4477
  if (!state) return true;
4186
4478
  state.status =
4187
4479
  typeof message.params.status.type === 'string' ? message.params.status.type : 'unknown';
4188
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);
4189
4485
  if (!state.idle) invalidateAttachment(state);
4190
4486
  if (!state.owned) return true;
4191
4487
  if (!state.telemetryConnected) {
@@ -4250,6 +4546,7 @@ export function createCodexContextProxy({
4250
4546
  ) {
4251
4547
  const state = threads.get(message.params.threadId);
4252
4548
  const turnId = message.params.turn.id;
4549
+ endWorkerTurnStart(state);
4253
4550
  if (
4254
4551
  state?.recoveryAttach &&
4255
4552
  typeof turnId === 'string' &&
@@ -4343,6 +4640,9 @@ export function createCodexContextProxy({
4343
4640
  typeof message.params.threadId === 'string'
4344
4641
  ) {
4345
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;
4346
4646
  ownedThreadIds.delete(message.params.threadId);
4347
4647
  threads.delete(message.params.threadId);
4348
4648
  }
@@ -4364,6 +4664,18 @@ export function createCodexContextProxy({
4364
4664
  if (!validRequestId) return;
4365
4665
  const requestKey = clientRequestKey(requestId);
4366
4666
  if (requestKey === null) return;
4667
+ if (
4668
+ message.method === 'initialize' &&
4669
+ engineeringState === 'waiting' &&
4670
+ initializeRequestKeys.size < MAX_TRACKED_INITIALIZE_REQUESTS
4671
+ ) {
4672
+ initializeRequestKeys.add(requestKey);
4673
+ return;
4674
+ }
4675
+ if (TERMINAL_WORK_METHODS.has(message.method)) {
4676
+ observeTerminalWork(requestKey, message.params);
4677
+ return;
4678
+ }
4367
4679
  if (['thread/start', 'thread/resume', 'thread/fork'].includes(message.method)) {
4368
4680
  const threadId =
4369
4681
  isRecord(message.params) && typeof message.params.threadId === 'string'
@@ -4374,7 +4686,9 @@ export function createCodexContextProxy({
4374
4686
  clientRequestBindings.size >= MAX_CLIENT_REQUEST_BINDINGS
4375
4687
  )
4376
4688
  return;
4377
- 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 });
4378
4692
  if (message.method === 'thread/resume') {
4379
4693
  if (threadId === null || threadId.length === 0 || threadId.length > 256) {
4380
4694
  clientRequestBindings.delete(requestKey);
@@ -4388,10 +4702,21 @@ export function createCodexContextProxy({
4388
4702
  }
4389
4703
  }
4390
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
+ }
4391
4714
  function observeClientResponse(message) {
4392
4715
  if (!isRecord(message) || message.id === undefined) return;
4393
4716
  const requestKey = clientRequestKey(message.id);
4394
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);
4395
4720
  const binding = clientRequestBindings.get(requestKey);
4396
4721
  if (binding) {
4397
4722
  clientRequestBindings.delete(requestKey);
@@ -4406,29 +4731,126 @@ export function createCodexContextProxy({
4406
4731
  typeof responseThreadId === 'string' &&
4407
4732
  responseThreadId === binding.threadId
4408
4733
  ) {
4734
+ if (isConversationThread(binding, message.result.thread))
4735
+ currentThreadId = binding.threadId;
4409
4736
  const claimed = claimOwnedThread(binding.threadId);
4737
+ noteReportedStatus(claimed, message.result.thread);
4410
4738
  if (claimed && !state.resumePending && claimed.idle)
4411
4739
  void requestCompaction(binding.threadId, claimed);
4412
4740
  } else if (!state.owned && state.resumeRequests.size === 0 && state.pending === null) {
4413
4741
  threads.delete(binding.threadId);
4414
4742
  }
4743
+ // Only now: the answer's status is recorded and its compaction check counted.
4744
+ notifyWorkerRoleIdle(binding.threadId);
4415
4745
  } else if (message.error === undefined) {
4416
4746
  const selectedId = message.result?.thread?.id;
4417
4747
  if (typeof selectedId === 'string' && selectedId.length > 0 && selectedId.length <= 256) {
4748
+ if (isConversationThread(binding, message.result.thread)) currentThreadId = selectedId;
4418
4749
  const selected = claimOwnedThread(selectedId);
4419
4750
  if (!selected) return;
4751
+ noteReportedStatus(selected, message.result.thread);
4420
4752
  if (selected.idle) void requestCompaction(selectedId, selected);
4421
4753
  }
4422
4754
  }
4423
4755
  }
4424
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
+ }
4425
4847
 
4426
4848
  const decoder = new StringDecoder('utf8');
4427
4849
  let inputBuffer = '';
4428
4850
  let passthrough = false;
4429
4851
  let discardOversized = false;
4430
4852
  let pausedForBackpressure = false;
4431
- const forward = (text) => {
4853
+ const writeOut = (text) => {
4432
4854
  if (!stdout.write(text) && !pausedForBackpressure) {
4433
4855
  pausedForBackpressure = true;
4434
4856
  child.stdout.pause();
@@ -4438,25 +4860,348 @@ export function createCodexContextProxy({
4438
4860
  });
4439
4861
  }
4440
4862
  };
4863
+ const forward = (text) => {
4864
+ if (engineeringHeld === null) {
4865
+ writeOut(text);
4866
+ return;
4867
+ }
4868
+ engineeringHeld.lines.push(text);
4869
+ engineeringHeld.bytes += Buffer.byteLength(text, 'utf8');
4870
+ if (engineeringHeld.bytes > MAX_LINE_BYTES) releaseEngineering();
4871
+ };
4872
+ /** The client's first successful initialize answer, which starts the hold. */
4873
+ function isEngineeringTrigger(message) {
4874
+ if (engineeringState !== 'waiting' || !isRecord(message)) return false;
4875
+ if (message.method !== undefined || !('result' in message)) return false;
4876
+ const key = clientRequestKey(message.id);
4877
+ return key !== null && initializeRequestKeys.has(key);
4878
+ }
4879
+ function holdForEngineering(text) {
4880
+ engineeringState = 'holding';
4881
+ initializeRequestKeys.clear();
4882
+ engineeringHeld = {
4883
+ lines: [text],
4884
+ bytes: Buffer.byteLength(text, 'utf8'),
4885
+ id: null,
4886
+ cancel: null,
4887
+ };
4888
+ try {
4889
+ engineeringHeld.id = sendOwned(
4890
+ 'skills/extraRoots/set',
4891
+ { extraRoots: [engineeringSkillsRoot] },
4892
+ 'engineering',
4893
+ null,
4894
+ );
4895
+ } catch {
4896
+ releaseEngineering();
4897
+ return;
4898
+ }
4899
+ engineeringHeld.cancel = scheduleTimeout(() => releaseEngineering(), engineeringAckTimeoutMs);
4900
+ }
4901
+ /** Forward everything held, in order. Idempotent; the session never waits on the pack. */
4902
+ function releaseEngineering() {
4903
+ if (engineeringHeld === null) return;
4904
+ const held = engineeringHeld;
4905
+ engineeringHeld = null;
4906
+ engineeringState = 'done';
4907
+ held.cancel?.();
4908
+ if (held.id !== null && ownedRequests.has(held.id)) cleanupRequest(held.id);
4909
+ for (const text of held.lines) writeOut(text);
4910
+ }
4441
4911
  const processLine = (line) => {
4442
4912
  if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) {
4443
4913
  const ownedId = internalRequestId(line);
4444
4914
  if (ownedId !== null) {
4445
4915
  stderr.write('codex-context: oversized internal response rejected\n');
4446
4916
  failOversizedInternal(ownedId, Buffer.byteLength(line, 'utf8') + 1);
4447
- } else forward(`${line}\n`);
4917
+ } else {
4918
+ settleOversizedAnswer(line);
4919
+ forward(`${line}\n`);
4920
+ }
4448
4921
  return;
4449
4922
  }
4450
4923
  let forwardLine = true;
4451
4924
  try {
4452
4925
  const message = JSON.parse(line.endsWith('\r') ? line.slice(0, -1) : line);
4453
4926
  observeClientResponse(message);
4927
+ if (isEngineeringTrigger(message)) {
4928
+ holdForEngineering(`${line}\n`);
4929
+ return;
4930
+ }
4454
4931
  forwardLine = handle(message);
4932
+ if (forwardLine && workerRole !== null)
4933
+ forwardLine = workerRoleObserves(message, `${line}\n`);
4455
4934
  } catch {
4456
4935
  /* preserve malformed external protocol lines */
4457
4936
  }
4458
4937
  if (forwardLine) forward(`${line}\n`);
4459
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
+ }
4460
5205
  function internalRequestId(line) {
4461
5206
  const match =
4462
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(
@@ -4488,7 +5233,7 @@ export function createCodexContextProxy({
4488
5233
  return;
4489
5234
  }
4490
5235
  cleanupRequest(id);
4491
- if (owned.kind === 'telemetry') return;
5236
+ if (owned.kind === 'telemetry' || owned.kind === 'worker') return;
4492
5237
  const failure = new Error('oversized internal response');
4493
5238
  failure.diagnosticReason = 'capture_size_exceeded';
4494
5239
  failure.responseBytes = responseBytes;
@@ -4529,6 +5274,7 @@ export function createCodexContextProxy({
4529
5274
  discardOversized = true;
4530
5275
  inputBuffer = '';
4531
5276
  } else {
5277
+ settleOversizedAnswer(inputBuffer);
4532
5278
  forward(inputBuffer);
4533
5279
  inputBuffer = '';
4534
5280
  passthrough = true;
@@ -4536,6 +5282,7 @@ export function createCodexContextProxy({
4536
5282
  }
4537
5283
  });
4538
5284
  child.stdout.on('end', () => {
5285
+ releaseEngineering();
4539
5286
  const tail = inputBuffer + decoder.end();
4540
5287
  if (tail && !discardOversized) forward(tail);
4541
5288
  inputBuffer = '';
@@ -4560,11 +5307,36 @@ export function createCodexContextProxy({
4560
5307
  child.stderr.on('data', () => undefined);
4561
5308
  child.stderr.resume?.();
4562
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
+ }
4563
5318
  return {
4564
5319
  threads,
4565
5320
  observeClientRequest,
4566
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
+ },
4567
5336
  async stop() {
5337
+ releaseEngineering();
5338
+ await stopWorkerRole();
5339
+ cancelAdapterTimers();
4568
5340
  if (stopped) {
4569
5341
  await Promise.all(
4570
5342
  [...diagnosticSinks.values()].map((sink) =>
@@ -4594,6 +5366,53 @@ export function createCodexContextProxy({
4594
5366
  };
4595
5367
  }
4596
5368
 
5369
+ /**
5370
+ * The launcher's AISAC Engineering skills root, or null. Only an absolute,
5371
+ * normalized path without control characters is used.
5372
+ */
5373
+ export function engineeringSkillsRootFrom(value) {
5374
+ if (typeof value !== 'string' || value.length === 0) return null;
5375
+ if (value.length > MAX_ENGINEERING_PATH_LENGTH || /[\u0000-\u001f\u007f]/u.test(value))
5376
+ return null;
5377
+ if (!value.startsWith('/') || resolve(value) !== value) return null;
5378
+ return value;
5379
+ }
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
+
4597
5416
  async function main() {
4598
5417
  if (process.argv.includes('--help')) {
4599
5418
  process.stderr.write(
@@ -4642,17 +5461,25 @@ async function main() {
4642
5461
  diagnosticFactory = null;
4643
5462
  }
4644
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;
4645
5470
  const proxy = createCodexContextProxy({
4646
5471
  child,
4647
5472
  threshold: numberEnv('CODEX_CONTEXT_COMPACT_AT', DEFAULT_THRESHOLD),
4648
5473
  timeoutMs: numberEnv('CODEX_CONTEXT_COMPACT_TIMEOUT_MS', DEFAULT_TIMEOUT_MS),
4649
5474
  policy,
4650
5475
  createDiagnosticSink: diagnosticFactory,
5476
+ engineeringSkillsRoot: engineeringSkillsRootFrom(process.env[ENGINEERING_SKILLS_ROOT_ENV]),
5477
+ createWorkerRole: await workerRoleFactoryFrom(process.env),
5478
+ clientAtLineBoundary: () =>
5479
+ !clientChunkInFlight && clientInputBuffer.length === 0 && !discardOversizedClientFrame,
4651
5480
  });
4652
- const clientDecoder = new StringDecoder('utf8');
4653
- let clientInputBuffer = '';
4654
- let discardOversizedClientFrame = false;
4655
5481
  process.stdin.on('data', (chunk) => {
5482
+ clientChunkInFlight = true;
4656
5483
  const decoded = clientDecoder.write(chunk);
4657
5484
  if (discardOversizedClientFrame) {
4658
5485
  const newline = decoded.indexOf('\n');
@@ -4668,7 +5495,7 @@ async function main() {
4668
5495
  if (!line) continue;
4669
5496
  if (Buffer.byteLength(line, 'utf8') + 1 > MAX_LINE_BYTES) continue;
4670
5497
  try {
4671
- proxy.observeClientRequest(JSON.parse(line));
5498
+ proxy.observeClientMessage(JSON.parse(line));
4672
5499
  } catch {
4673
5500
  /* Preserve malformed/native frames unchanged; the app-server owns validation. */
4674
5501
  }
@@ -4679,6 +5506,11 @@ async function main() {
4679
5506
  }
4680
5507
  });
4681
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
+ });
4682
5514
  process.stdin.on('end', () => child.stdin.end());
4683
5515
  child.on('exit', async (code, signal) => {
4684
5516
  await proxy.stop();