@jbkjr/relay 0.0.0-stage → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (296) hide show
  1. package/LICENSE +21 -0
  2. package/LICENSES/Apache-2.0.txt +201 -0
  3. package/LICENSES/README.md +19 -0
  4. package/LICENSES/codex-NOTICE.txt +6 -0
  5. package/README.md +386 -2
  6. package/SECURITY.md +145 -0
  7. package/adapters/briefs/claude.md +43 -0
  8. package/adapters/briefs/codex.md +56 -0
  9. package/adapters/briefs/models.json +33 -0
  10. package/adapters/build.mjs +8 -0
  11. package/adapters/claude/.claude-plugin/marketplace.json +13 -0
  12. package/adapters/claude/relay/.claude-plugin/plugin.json +5 -0
  13. package/adapters/claude/relay/agents/codex.md +21 -0
  14. package/adapters/claude/relay/agents/operator.md +21 -0
  15. package/adapters/claude/relay/skills/ask/SKILL.md +20 -0
  16. package/adapters/claude/relay/skills/chat/SKILL.md +13 -0
  17. package/adapters/claude/relay/skills/delegate/SKILL.md +21 -0
  18. package/adapters/claude/relay/skills/discuss/SKILL.md +19 -0
  19. package/adapters/claude/relay/skills/review/SKILL.md +21 -0
  20. package/adapters/claude/relay/skills/tree/SKILL.md +10 -0
  21. package/adapters/claude/relay/skills/write-for-codex/SKILL.md +78 -0
  22. package/adapters/codex/.agents/plugins/marketplace.json +20 -0
  23. package/adapters/codex/AGENTS.snippet.md +5 -0
  24. package/adapters/codex/relay/.codex-plugin/plugin.json +6 -0
  25. package/adapters/codex/relay/skills/relay-ask/SKILL.md +20 -0
  26. package/adapters/codex/relay/skills/relay-chat/SKILL.md +13 -0
  27. package/adapters/codex/relay/skills/relay-delegate/SKILL.md +21 -0
  28. package/adapters/codex/relay/skills/relay-discuss/SKILL.md +19 -0
  29. package/adapters/codex/relay/skills/relay-review/SKILL.md +21 -0
  30. package/adapters/codex/relay/skills/relay-tree/SKILL.md +10 -0
  31. package/adapters/codex/relay/skills/relay-write-for-claude/SKILL.md +66 -0
  32. package/adapters/generate.mjs +124 -0
  33. package/bin/relay +59 -0
  34. package/codex-pin.json +12 -0
  35. package/dist/backends/acp.js +1424 -0
  36. package/dist/backends/claude.js +890 -0
  37. package/dist/backends/cli-version.js +112 -0
  38. package/dist/backends/codex-app.js +1525 -0
  39. package/dist/backends/codex-daybreak.js +75 -0
  40. package/dist/backends/codex-env.js +656 -0
  41. package/dist/backends/codex-network.js +304 -0
  42. package/dist/backends/codex-pin.js +320 -0
  43. package/dist/backends/codex-shell-policy.js +182 -0
  44. package/dist/backends/codex-stage2.js +998 -0
  45. package/dist/backends/codex-subagents.js +47 -0
  46. package/dist/backends/codex.js +637 -0
  47. package/dist/backends/copilot.js +246 -0
  48. package/dist/backends/env.js +147 -0
  49. package/dist/backends/gemini.js +607 -0
  50. package/dist/backends/grok.js +337 -0
  51. package/dist/backends/index.js +8 -0
  52. package/dist/backends/native-temp.js +187 -0
  53. package/dist/backends/never-admission.js +90 -0
  54. package/dist/backends/run.js +67 -0
  55. package/dist/backends/stream.js +230 -0
  56. package/dist/backends/tool-discovery.js +15 -0
  57. package/dist/backends/types.js +264 -0
  58. package/dist/build-info.json +5 -0
  59. package/dist/cli.js +344 -0
  60. package/dist/confine/bridge.js +113 -0
  61. package/dist/confine/broker-core.js +76 -0
  62. package/dist/confine/broker-http.js +650 -0
  63. package/dist/confine/broker-names.js +9 -0
  64. package/dist/confine/broker.js +258 -0
  65. package/dist/confine/canary.js +380 -0
  66. package/dist/confine/diagnostics.js +122 -0
  67. package/dist/confine/gemini-tools-main.js +8 -0
  68. package/dist/confine/gemini-tools.js +181 -0
  69. package/dist/confine/hardlinks.js +58 -0
  70. package/dist/confine/harness-config.js +16 -0
  71. package/dist/confine/index.js +117 -0
  72. package/dist/confine/leases.js +217 -0
  73. package/dist/confine/paths.js +6 -0
  74. package/dist/confine/peer.js +115 -0
  75. package/dist/confine/port-policy.js +8 -0
  76. package/dist/confine/ports.js +365 -0
  77. package/dist/confine/private-root.js +208 -0
  78. package/dist/confine/probe-stage2.js +501 -0
  79. package/dist/confine/probe.js +1109 -0
  80. package/dist/confine/proxy.js +783 -0
  81. package/dist/confine/sbcheck.js +208 -0
  82. package/dist/confine/seatbelt-never.js +41 -0
  83. package/dist/confine/seatbelt-stage2.js +139 -0
  84. package/dist/confine/seatbelt.js +1129 -0
  85. package/dist/confine/sockets.js +36 -0
  86. package/dist/confine/turn-probe.js +19 -0
  87. package/dist/confine/turn.js +86 -0
  88. package/dist/core/adoption.js +124 -0
  89. package/dist/core/api-keys.js +423 -0
  90. package/dist/core/approvals.js +740 -0
  91. package/dist/core/build-identity.js +248 -0
  92. package/dist/core/caller.js +749 -0
  93. package/dist/core/calls.js +102 -0
  94. package/dist/core/claude-settings.js +1045 -0
  95. package/dist/core/config.js +453 -0
  96. package/dist/core/context.js +186 -0
  97. package/dist/core/db.js +753 -0
  98. package/dist/core/dispatch.js +110 -0
  99. package/dist/core/env-broker.js +505 -0
  100. package/dist/core/env-policy.js +182 -0
  101. package/dist/core/escalation-authority.js +76 -0
  102. package/dist/core/escalation-contract.js +13 -0
  103. package/dist/core/escalation-person-path.js +131 -0
  104. package/dist/core/escalation-policy.js +79 -0
  105. package/dist/core/escalation-runtime.js +135 -0
  106. package/dist/core/escalation-state.js +42 -0
  107. package/dist/core/escalations.js +191 -0
  108. package/dist/core/events.js +235 -0
  109. package/dist/core/executables.js +147 -0
  110. package/dist/core/extensions.js +645 -0
  111. package/dist/core/families.js +204 -0
  112. package/dist/core/git.js +657 -0
  113. package/dist/core/identity.js +113 -0
  114. package/dist/core/liveness.js +68 -0
  115. package/dist/core/mediated-network-provider.js +81 -0
  116. package/dist/core/never-checkpoint.js +76 -0
  117. package/dist/core/never-coverage.js +97 -0
  118. package/dist/core/never-network.js +49 -0
  119. package/dist/core/never-policy.js +302 -0
  120. package/dist/core/never-proxy-policy.js +109 -0
  121. package/dist/core/never-schema.js +61 -0
  122. package/dist/core/never-tools.js +56 -0
  123. package/dist/core/notices.js +48 -0
  124. package/dist/core/ops.js +959 -0
  125. package/dist/core/outcome.js +224 -0
  126. package/dist/core/params.js +32 -0
  127. package/dist/core/presence.js +174 -0
  128. package/dist/core/procs.js +546 -0
  129. package/dist/core/prompts.js +363 -0
  130. package/dist/core/protected-config.js +238 -0
  131. package/dist/core/raw-network.js +192 -0
  132. package/dist/core/redact.js +152 -0
  133. package/dist/core/refusal.js +33 -0
  134. package/dist/core/relay-command.js +310 -0
  135. package/dist/core/reported.js +3 -0
  136. package/dist/core/restart-overlay.js +651 -0
  137. package/dist/core/retention.js +1135 -0
  138. package/dist/core/secrets.js +329 -0
  139. package/dist/core/session-token.js +175 -0
  140. package/dist/core/session.js +744 -0
  141. package/dist/core/shell.js +2 -0
  142. package/dist/core/shipped-pin.js +47 -0
  143. package/dist/core/shown.js +42 -0
  144. package/dist/core/slots.js +67 -0
  145. package/dist/core/stage2-executors.js +453 -0
  146. package/dist/core/stage2-switch.js +5 -0
  147. package/dist/core/steering.js +149 -0
  148. package/dist/core/storage.js +358 -0
  149. package/dist/core/toml.js +175 -0
  150. package/dist/core/views.js +324 -0
  151. package/dist/core/wait.js +114 -0
  152. package/dist/core/wake.js +207 -0
  153. package/dist/core/watch.js +247 -0
  154. package/dist/core/worktree.js +213 -0
  155. package/dist/hosts/claude-desktop.js +274 -0
  156. package/dist/hosts/claude.js +249 -0
  157. package/dist/hosts/codex.js +329 -0
  158. package/dist/hosts/desktop-shared.js +20 -0
  159. package/dist/hosts/index.js +11 -0
  160. package/dist/hosts/types.js +4 -0
  161. package/dist/install/basics.js +18 -0
  162. package/dist/install/claude-init.js +133 -0
  163. package/dist/install/common.js +655 -0
  164. package/dist/install/doctor.js +629 -0
  165. package/dist/install/qualify-codex.js +205 -0
  166. package/dist/install.js +524 -0
  167. package/dist/mcp/elicit.js +209 -0
  168. package/dist/mcp/gateway.js +218 -0
  169. package/dist/mcp/host.js +253 -0
  170. package/dist/mcp/server.js +1124 -0
  171. package/dist/mcp/stdio.js +37 -0
  172. package/dist/modes/discussion.js +393 -0
  173. package/dist/modes/review.js +722 -0
  174. package/dist/native/relay-sbcheck +0 -0
  175. package/dist/targets/briefs.js +86 -0
  176. package/dist/targets/claude.js +94 -0
  177. package/dist/targets/codex.js +66 -0
  178. package/dist/targets/copilot.js +93 -0
  179. package/dist/targets/gemini.js +119 -0
  180. package/dist/targets/grok.js +126 -0
  181. package/dist/targets/index.js +192 -0
  182. package/dist/targets/types.js +18 -0
  183. package/dist/targets/verified.js +35 -0
  184. package/dist/worker.js +113 -0
  185. package/docs/UPGRADING.md +1502 -0
  186. package/docs/pinned-codex.md +321 -0
  187. package/experiments/stage2-redteam/lib/oracles.mjs +214 -0
  188. package/experiments/stage2-redteam/lib/report.mjs +35 -0
  189. package/npm-shrinkwrap.json +1632 -0
  190. package/package.json +82 -4
  191. package/scripts/codex-qualify/codex-pin-store.mjs +353 -0
  192. package/scripts/codex-qualify/codex-qualifier-process.mjs +265 -0
  193. package/scripts/codex-qualify/codex-qualifier.example.json +5 -0
  194. package/scripts/codex-qualify/codex-qualifier.mjs +281 -0
  195. package/scripts/codex-qualify/codex-shipped-pin.mjs +158 -0
  196. package/scripts/codex-qualify/codex-stage2-pin.mjs +48 -0
  197. package/scripts/codex-qualify/codex-stage2.mjs +2381 -0
  198. package/scripts/codex-qualify/install-codex-qualifier.mjs +98 -0
  199. package/scripts/codex-qualify/main-module.mjs +14 -0
  200. package/scripts/codex-qualify/relay-codex-qualifier.plist +37 -0
  201. package/scripts/codex-qualify/scratch-env.mjs +31 -0
  202. package/scripts/codex-qualify/session.mjs +96 -0
  203. package/scripts/codex-qualify/stage2-escalation-cases.mjs +125 -0
  204. package/test/codex-permissions.test.ts +875 -0
  205. package/test/fixtures/boundary-probes.mjs +17 -0
  206. package/test/fixtures/denial-stream-host.mjs +7 -0
  207. package/test/fixtures/families.json +246 -0
  208. package/test/fixtures/install-snapshots/claude-desktop-foreign.txt +158 -0
  209. package/test/fixtures/install-snapshots/claude-desktop-fresh.txt +101 -0
  210. package/test/fixtures/install-snapshots/claude-desktop-installed.txt +161 -0
  211. package/test/fixtures/install-snapshots/claude-foreign.txt +133 -0
  212. package/test/fixtures/install-snapshots/claude-fresh.txt +77 -0
  213. package/test/fixtures/install-snapshots/claude-installed.txt +133 -0
  214. package/test/fixtures/install-snapshots/codex-foreign.txt +159 -0
  215. package/test/fixtures/install-snapshots/codex-fresh.txt +107 -0
  216. package/test/fixtures/install-snapshots/codex-installed.txt +161 -0
  217. package/test/fixtures/link-parent.mjs +6 -0
  218. package/test/fixtures/mediated-command.cjs +72 -0
  219. package/test/fixtures/native-skill-isolation.json +280 -0
  220. package/test/fixtures/pinned-codex-app-server.mjs +25 -0
  221. package/test/fixtures/qualified-ext-adapters.mjs +36 -0
  222. package/test/fixtures/refusals/README.md +52 -0
  223. package/test/fixtures/refusals/claude-source-result.json +7 -0
  224. package/test/fixtures/refusals/openai-app-capacity.json +24 -0
  225. package/test/fixtures/refusals/openai-app-cyberPolicy.json +24 -0
  226. package/test/fixtures/refusals/openai-gpt-6-astra-max.json +12 -0
  227. package/test/fixtures/refusals/openai-gpt-6.1-sol-xhigh.json +12 -0
  228. package/test/fixtures/refusals/openai-review-capacity.json +24 -0
  229. package/test/fixtures/relay-0.2.0.sql +57 -0
  230. package/test/fixtures/relay-0.9.1.gen.mjs +212 -0
  231. package/test/fixtures/relay-0.9.1.sql +340 -0
  232. package/test/fixtures/slow-boundary-probes.mjs +37 -0
  233. package/test/fixtures/stable-surfaces/config.json +1122 -0
  234. package/test/fixtures/stable-surfaces/escalation.json +128 -0
  235. package/test/fixtures/stable-surfaces/events.json +37 -0
  236. package/test/fixtures/stable-surfaces/gemini-native-resume.json +4 -0
  237. package/test/fixtures/stable-surfaces/inbox.jsonl +2 -0
  238. package/test/fixtures/stable-surfaces/notice.txt +1 -0
  239. package/test/fixtures/stable-surfaces/refusal-item.json +28 -0
  240. package/test/fixtures/stable-surfaces/refusal-review.json +23 -0
  241. package/test/fixtures/stable-surfaces/registry.json +49 -0
  242. package/test/fixtures/stable-surfaces/tools-desktop.json +575 -0
  243. package/test/fixtures/stable-surfaces/tools.json +716 -0
  244. package/test/fixtures/stable-surfaces/usage.txt +46 -0
  245. package/test/fixtures/stage2-acp-native.mjs +138 -0
  246. package/test/fixtures/stage2-app-server.mjs +23 -0
  247. package/test/fixtures/stage2-catalog.json +91 -0
  248. package/test/fixtures/stage2-hostile-web.mjs +35 -0
  249. package/test/fixtures/stage2-native-network.mjs +62 -0
  250. package/test/fixtures/stage2-worker.ts +87 -0
  251. package/test/fixtures/status-views/expected.json +7825 -0
  252. package/test/fixtures/status-views/registries.json +1 -0
  253. package/test/fixtures/steering.json +209 -0
  254. package/test/helpers.ts +740 -0
  255. package/test/host-env.ts +7 -0
  256. package/test/keychain-decoy.ts +197 -0
  257. package/test/live-scope.ts +44 -0
  258. package/test/mediated-network.test.ts +192 -0
  259. package/test/mediated-proxy.test.ts +264 -0
  260. package/test/native-temp-alias.ts +10 -0
  261. package/test/never-policy.test.ts +629 -0
  262. package/test/never-tools.test.ts +136 -0
  263. package/test/process-home.ts +18 -0
  264. package/test/proxy.test.ts +531 -0
  265. package/test/restart-overlay-live.test.ts +85 -0
  266. package/test/restart-overlay-profile.test.ts +66 -0
  267. package/test/restart-overlay.test.ts +416 -0
  268. package/test/stable-surfaces.test.ts +249 -0
  269. package/test/stage2-escalation-live.test.ts +544 -0
  270. package/test/stage2-escalation-qualification.test.ts +170 -0
  271. package/test/stage2-escalation.test.ts +747 -0
  272. package/test/stage2-executor.test.ts +849 -0
  273. package/test/stage2-grant.test.ts +603 -0
  274. package/test/stage2-native-live.test.ts +647 -0
  275. package/test/stage2-network-decisions.test.ts +70 -0
  276. package/test/stage2-probe.test.ts +845 -0
  277. package/test/stage2-standing-live.test.ts +203 -0
  278. package/test/stubs/broker-host.mjs +59 -0
  279. package/test/stubs/broker-peer.mjs +20 -0
  280. package/test/stubs/confined-harness.mjs +91 -0
  281. package/test/stubs/ext-broken-server.mjs +2 -0
  282. package/test/stubs/ext-odd-server.mjs +21 -0
  283. package/test/stubs/ext-server.mjs +31 -0
  284. package/test/stubs/fake-host-cli.mjs +218 -0
  285. package/test/stubs/procargs.mjs +30 -0
  286. package/test/stubs/stub-acp +4 -0
  287. package/test/stubs/stub-agent.mjs +322 -0
  288. package/test/stubs/stub-claude +4 -0
  289. package/test/stubs/stub-codex +4 -0
  290. package/test/stubs/targets/acp.mjs +307 -0
  291. package/test/stubs/targets/claude.mjs +149 -0
  292. package/test/stubs/targets/codex.mjs +479 -0
  293. package/test/stubs/targets/gemini.mjs +604 -0
  294. package/test/temp-root.ts +11 -0
  295. package/test/wp4-adapters.test.ts +353 -0
  296. package/test/wp4-interlock.test.ts +136 -0
@@ -0,0 +1,744 @@
1
+ import { escalationEnabled } from "./config.js";
2
+ import fs from "node:fs";
3
+ import path from "node:path";
4
+ import { launchTurn } from "../backends/run.js";
5
+ import { prepareCodexHome } from "../backends/codex-pin.js";
6
+ import { recordServed, recordWaiver } from "./families.js";
7
+ import { expireRequests, hasPending, heldForJob, requestApproval } from "./approvals.js";
8
+ import { localModeRetired, rawNetworkConsent, stage2Enabled } from "./raw-network.js";
9
+ import { recordEnforcement, stage2SkillAssets, turnConfinement } from "../backends/codex-stage2.js";
10
+ import { nodeDir } from "./config.js";
11
+ import { writeContextFile } from "./context.js";
12
+ import { cancelledAbove, db, getNode, getTurn, nodeTurns, now, recordLaunchLeader, runConfig, normaliseWorkCwd, setParam, tx, updateNode, updateTurn, workCwd } from "./db.js";
13
+ import { groupAlive } from "./procs.js";
14
+ import { dropSkillAssets, nodeHasLiveExecutor, noteSkillAssets } from "./stage2-executors.js";
15
+ import { assertOverlayLaunch, consumeOverlay, destinationOverlay, finishOverlay, getOverlay, originOverlay, overlayDeadlineExpired, overlayPrompt, overlayRemainingMs, overlayTurnProblem, prepareOverlayRestart, stopOverlay } from "./restart-overlay.js";
16
+ import { localNetworkKey, queuedSpeeds, reviewParams, sessionParams, speedChange, speedOf } from "./params.js";
17
+ import { acquireSlot, releaseSlot } from "./slots.js";
18
+ import { speedRank, targetDef, targetLabel } from "../targets/index.js";
19
+ import { clipped } from "./shown.js";
20
+ import { redactOwnReview } from "./redact.js";
21
+ import { redact, withTurnSecrets } from "./secrets.js";
22
+ import { keepRecord, storageProblem, takeDiagnosticProblems, useStoragePolicy } from "./storage.js";
23
+ import { hardLinkProblem, prepareTurnTree, turnTree } from "./worktree.js";
24
+ import { buildSkillPackage, consentText, extensionsOf, gatewayWarnings, readMcpFile, writeManifest } from "./extensions.js";
25
+ import { claimTurnEnvironment } from "./env-broker.js";
26
+ import { assertNeverLaunchCurrent, checkpointNever } from "./never-checkpoint.js";
27
+ import { neverGrantProblem } from "./never-policy.js";
28
+ import { neverToolAdapters } from "./never-tools.js";
29
+ import { capturedLaunchClass, reserveLaunch, launchReservationState, finishLaunchReservation } from "./restart-overlay.js";
30
+ /** Turns in flight in this worker process, so a signal handler can cancel them. */
31
+ const active = new Set();
32
+ /**
33
+ * Starts still under way in this worker process. A backend's start can await something before it
34
+ * launches the agent (the `codex exec` fallback's configuration check), and a stop that came then
35
+ * would find no turn to cancel. So a stop aborts them (TurnSpec.signal), waits for each to settle,
36
+ * and cancels what any of them launched with the turns already in flight (review C7/X1). Each
37
+ * settles only once what it launched is in `active`. A relay-enforced (ACP) start gives up at each
38
+ * step of its launch (broker, proxy, boundary probes, spawn) once the signal is aborted, cleaning up
39
+ * what it had made (consolidation-confine.md E18).
40
+ */
41
+ const starting = new Set();
42
+ const stopping = new AbortController();
43
+ /** Stops this worker's turns: aborts the starts under way, waits for them, then cancels every turn in flight and waits for it to end. */
44
+ export async function cancelActiveTurns() {
45
+ stopping.abort();
46
+ await Promise.allSettled([...starting]);
47
+ await Promise.all([...active].map((h) => h.cancel()));
48
+ }
49
+ /**
50
+ * Starts a turn and puts it in `active`. The start gets the worker's stop signal and is in
51
+ * `starting` until it has settled. It is called in the same tick as the turn's last cancelCheck
52
+ * (acquireSlot), so a stop finds the start here or its turn in `active`.
53
+ */
54
+ async function startTurn(start) {
55
+ const started = (async () => {
56
+ const handle = await start(stopping.signal);
57
+ active.add(handle);
58
+ return handle;
59
+ })();
60
+ starting.add(started);
61
+ try {
62
+ return await started;
63
+ }
64
+ finally {
65
+ starting.delete(started);
66
+ }
67
+ }
68
+ /** True when the node, any ancestor, or the run has been cancelled, or the node is no longer in the registry. */
69
+ export function isCancelled(nodeId) {
70
+ const n = getNode(nodeId);
71
+ return !n || cancelledAbove(n, { self: true });
72
+ }
73
+ /** A turn that ended before an agent ran. */
74
+ function notRun(status, error) {
75
+ return { status, finalMessage: "", error, exitCode: null, timedOut: false, warnings: [] };
76
+ }
77
+ export function processWarnings(r) {
78
+ const out = [...(r.warnings ?? [])];
79
+ if (r.survivors?.length)
80
+ out.push(`Processes the agent started could not be stopped and may still be running (pids ${r.survivors.join(", ")}).`);
81
+ if (r.unseenMs !== undefined) {
82
+ out.push(`The agent was gone before relay could take a last look at what it had started; it last looked ${r.unseenMs} ms before the agent exited. Anything started in that time cannot be traced and may still be running.`);
83
+ }
84
+ return out;
85
+ }
86
+ /**
87
+ * A person's/root's cancel closes the running turn in the registry before it signals the worker.
88
+ * Backend teardown can subsequently report a transport/process failure caused by that signal. The
89
+ * durable cancel wins in that ordering; a backend result which reached this function first still
90
+ * records normally, before a later cancel can select the already-settled node.
91
+ */
92
+ export function applyRecordedCancellation(result, recordedStatus) {
93
+ if (recordedStatus !== "cancelled")
94
+ return result;
95
+ const { refusal, ...rest } = result;
96
+ const warnings = [...(result.warnings ?? [])];
97
+ if (result.error && result.error !== "cancelled")
98
+ warnings.push(result.error);
99
+ if (refusal?.message)
100
+ warnings.push(refusal.message);
101
+ return { ...rest, ...(warnings.length ? { warnings } : {}), status: "interrupted", error: "cancelled" };
102
+ }
103
+ /**
104
+ * As the turn `turnId` starts (in the transaction that claims it): the speed it runs at, which
105
+ * becomes the session's (SessionParams.speed). That is the one the call that queued it was admitted
106
+ * at (caller.ts changeSpeed), else the session's, the speed of the turn before it. A raise is kept
107
+ * with the speed before it (speed_change), for settleSpeedChange. Speeds kept for this turn and for
108
+ * earlier ones (which ended without starting) are dropped.
109
+ */
110
+ function startSpeed(nodeId, turnId) {
111
+ const n = getNode(nodeId);
112
+ const p = sessionParams(n);
113
+ const from = speedOf(n);
114
+ const queued = queuedSpeeds(n);
115
+ const to = queued.find(([t]) => t === turnId)?.[1] ?? from;
116
+ const later = queued.filter(([t]) => t > turnId);
117
+ if (queued.length)
118
+ setParam(nodeId, "speed_queued", later.length ? Object.fromEntries(later.map(([t, sp]) => [String(t), sp])) : null);
119
+ if (to !== from)
120
+ setParam(nodeId, "speed", to);
121
+ const change = speedRank(to) > speedRank(from) ? { turn: turnId, from, to } : null;
122
+ if (change || p.speed_change)
123
+ setParam(nodeId, "speed_change", change);
124
+ return to;
125
+ }
126
+ /**
127
+ * Settles the raise of speed the turn `turnId` started with (startSpeed), as the turn is recorded
128
+ * as over: kept if the turn reached the model, undone if it never did (refused before its first
129
+ * model request, a speed the account's catalog does not offer, say), so that a later call naming no
130
+ * speed is not refused the same way. A turn that never started raised nothing.
131
+ */
132
+ function settleSpeedChange(nodeId, turnId, reached) {
133
+ const n = getNode(nodeId);
134
+ const change = n ? speedChange(n, turnId) : null;
135
+ if (!change)
136
+ return;
137
+ if (!reached && speedOf(n) === change.to)
138
+ setParam(nodeId, "speed", change.from);
139
+ setParam(nodeId, "speed_change", null);
140
+ }
141
+ /**
142
+ * Runs one turn on a session node: takes a concurrency slot, starts the agent with the given
143
+ * access, enforces the wall-clock timeout, and records the session id and reply.
144
+ */
145
+ export function runSessionTurn(...args) {
146
+ return withTurnSecrets(() => runScopedSessionTurn(...args));
147
+ }
148
+ async function runScopedSessionTurn(
149
+ /** timeoutS: the turn's wall-clock limit, or null for none. */
150
+ nodeId, turnId, prompt, access, timeoutS, cancelCheck) {
151
+ /** Set once the turn is claimed as running: from then on its agent's relay connection holds the turn's authority (db.ts turnEnded). */
152
+ let started = false;
153
+ /**
154
+ * Records the turn as over, and the speed change it carried with it (settleSpeedChange). A turn
155
+ * that has started is recorded so at once, since its authority ends with it. One that never
156
+ * started holds none: what records it is returned (close) for the worker to run in the
157
+ * transaction that records the turn's end for its session (outcome.ts finishTurn), so that a
158
+ * call waiting on the turn cannot find it over before its session has settled with it.
159
+ */
160
+ const endTurn = (fields, reached) => {
161
+ const close = () => {
162
+ if (Object.keys(fields).length)
163
+ updateTurn(turnId, fields);
164
+ settleSpeedChange(nodeId, turnId, reached);
165
+ };
166
+ if (!started)
167
+ return { close };
168
+ tx(close);
169
+ return {};
170
+ };
171
+ // A write job recorded by an earlier relay with a subdirectory cwd is rewritten to its worktree
172
+ // root first (the subdirectory kept in its params), so nothing below reads the old path.
173
+ const node = normaliseWorkCwd(getNode(nodeId));
174
+ const cfg = runConfig(node.run_id);
175
+ // The agent's log is rotated as the run's config says (log_max_mb).
176
+ useStoragePolicy(cfg);
177
+ const dir = nodeDir(node.run_id, node.id);
178
+ /** What relay could not keep of this turn's records; said with its result. */
179
+ const recordWarnings = [];
180
+ // Decide at dispatch, not when a follow-up is queued: an earlier turn may still be running
181
+ // then. Without a CLI session, none of the earlier prompts (including the preamble) survived.
182
+ if (!node.session_id) {
183
+ const earlier = nodeTurns(nodeId).filter((t) => t.id < turnId).map((t) => t.body);
184
+ prompt = [...earlier, prompt].join("\n\n[relay] Follow-up message:\n\n");
185
+ }
186
+ // A copy for the person to read later. The agent is handed the prompt itself, so a copy that
187
+ // cannot be written (a full disk, say) is said in the turn's warnings, and the turn goes on.
188
+ const promptPath = path.join(dir, `prompt-${turnId}.txt`);
189
+ const unkept = keepRecord(promptPath, prompt, { consequence: "no copy of this turn's prompt was kept" });
190
+ if (unkept)
191
+ recordWarnings.push(`${unkept}.`);
192
+ else
193
+ updateTurn(turnId, { prompt_path: promptPath });
194
+ /** Ends the turn as failed before its agent ran: why, cut of secrets as everything relay keeps of a turn is. */
195
+ const refused = (why) => {
196
+ const problem = redact(why);
197
+ const ended = endTurn({ status: "failed", error: problem, ended_at: now() }, false);
198
+ const unused = destinationOverlay(nodeId, turnId);
199
+ if (unused?.state === "ready")
200
+ finishOverlay(node.run_id, unused.id, { clean: true, problem: "destination failed before overlay consumption" });
201
+ return { ...notRun("failed", problem), ...ended };
202
+ };
203
+ const overlayProblem = overlayTurnProblem(nodeId, turnId);
204
+ if (overlayProblem)
205
+ return refused(overlayProblem);
206
+ let overlay = null;
207
+ let overlayTimer;
208
+ let overlayCleanup = { clean: false, problem: "overlay launch/cleanup was not confirmed" };
209
+ const overlayAbort = new AbortController();
210
+ // A worktree removed after its branch was merged is put back when the session is used again.
211
+ const unprepared = prepareTurnTree(node, cfg);
212
+ if (unprepared)
213
+ return refused(unprepared);
214
+ // A job with its own worktree starts at the worktree root (restored above), whatever subdirectory
215
+ // an earlier relay recorded as its cwd; an in-place session inside a job's worktree starts at
216
+ // that worktree's root too (workCwd), and any other session in its own directory.
217
+ const startDir = workCwd(node);
218
+ if (!fs.existsSync(startDir)) {
219
+ // An in-place session works in its caller's directory; if that was a job's worktree, it may have been cleaned up since.
220
+ return refused(`its working directory ${startDir} no longer exists (it belonged to a job whose worktree has been removed). Start a new job or consult instead.`);
221
+ }
222
+ const cancelledQueued = () => ({ ...notRun("interrupted", "cancelled while queued"), ...endTurn({ status: "cancelled", ended_at: now() }, false) });
223
+ const dropped = () => ({ ...notRun("interrupted", "cancelled while queued"), skipped: true });
224
+ // The turn's complete effective grant, with the environment names its caller requested, is
225
+ // recorded while it is still queued: its environment claim, the person's consent and its launch
226
+ // then all see the same grant. One no longer queued was dropped by a cancel and is skipped.
227
+ const recorded = tx(() => {
228
+ const turn = getTurn(turnId);
229
+ if (turn?.status !== "queued")
230
+ return false;
231
+ const requested = JSON.parse(turn.grant_json ?? "{}").env;
232
+ updateTurn(turnId, { grant_json: JSON.stringify({ ...grantFor(node, access), ...(requested?.length ? { env: requested } : {}) }) });
233
+ return true;
234
+ });
235
+ if (!recorded)
236
+ return cancelCheck() ? cancelledQueued() : dropped();
237
+ // The turn's environment is claimed from the owning root now, before it waits for a slot, and
238
+ // held in memory until it launches: a root that exits after this no longer fails the turn (W9).
239
+ // The person is asked here about a one-turn grant.env request, and a denial fails the turn.
240
+ let reserved = false, launchAttempted = false;
241
+ let appClean = false;
242
+ try {
243
+ if (node.target === "codex") {
244
+ const launchClass = capturedLaunchClass(nodeId, turnId);
245
+ if (launchClass) {
246
+ const retired = launchClass === "local" ? localModeRetired(cfg) : null;
247
+ if (retired)
248
+ return refused(`${retired}. So this job's agent was not started: continue it with one of those grants instead of local_network.`);
249
+ reserveLaunch(nodeId, turnId, launchClass);
250
+ reserved = true;
251
+ }
252
+ }
253
+ }
254
+ catch (err) {
255
+ return refused(err.message);
256
+ }
257
+ let environment;
258
+ try {
259
+ environment = await claimTurnEnvironment(turnId, stopping.signal);
260
+ }
261
+ catch (err) {
262
+ if (reserved)
263
+ finishLaunchReservation(node.run_id, turnId, { clean: true });
264
+ // A fault in relay itself (a session whose target it does not know, say) stops the worker, said
265
+ // with its stack as any other. What the claim refused (no broker, a denial) fails this turn alone.
266
+ if (err instanceof TypeError || err instanceof ReferenceError || err instanceof RangeError)
267
+ throw err;
268
+ if (cancelCheck() || stopping.signal.aborted)
269
+ return cancelledQueued();
270
+ if (getTurn(turnId)?.status !== "queued")
271
+ return dropped();
272
+ return refused(storageProblem(err, "the agent was not started") ?? err.message);
273
+ }
274
+ // What the session was given beyond relay's isolation, and the turn's own directory for it (the
275
+ // skill package and the gateway's manifest), in relay's control directory and removed at the end.
276
+ const ext = extensionsOf(node);
277
+ const extDir = path.join(dir, `ext-${turnId}`);
278
+ // Stage 2 (backends/codex-stage2.ts): a copy of the skill package its commands can read, outside
279
+ // relay's control directory, which relay's profile denies them. Removed with extDir.
280
+ let extAssets = null;
281
+ let slot = null;
282
+ try {
283
+ slot = await acquireSlot(node.run_id, node.id, cancelCheck);
284
+ if (slot === null)
285
+ return cancelledQueued();
286
+ // A turn whose claim no longer applies fails as soon as it has its slot, before it starts and
287
+ // before the person is asked about its extensions. The launch checks the claim again (take).
288
+ try {
289
+ environment.check();
290
+ }
291
+ catch (err) {
292
+ return cancelCheck() ? cancelledQueued() : refused(err.message);
293
+ }
294
+ // Any turn (a job's, a consult's, a discussion's) may ask for approval to act outside its
295
+ // sandbox, unless approval requests are off or full access is already on. What a read-only turn
296
+ // may ask for (the web, or a command; never file changes) is checked where the request is filed.
297
+ const escalate = escalationEnabled(cfg) && !cfg.allow_dangerous;
298
+ // A turn given MCP servers needs the server too: their tools are offered through it. It may
299
+ // not delegate, whatever the session was started with: an agent it started would have none of
300
+ // its limits (docs/extensions.md).
301
+ const servers = Boolean(ext?.mcp_servers.length);
302
+ const mayDelegate = node.allow_delegation === 1 && !servers;
303
+ let relay = null;
304
+ // Claude needs its permission prompt transport; Codex needs the stage-2 escalation broker
305
+ // even when delegation is disabled. Tool availability cannot depend on mayDelegate.
306
+ if (mayDelegate || servers || (escalate && ((node.target === "codex" && cfg.codex_backend === "app-server" && stage2Enabled(process.env, cfg)) || targetDef(node.target).approvals.channel === "relay-tool"))) {
307
+ // What this one turn may do travels with it. The child's relay server takes its authority
308
+ // from here and from the registry, never from how the session was first created.
309
+ const contextFile = path.join(dir, "context.json");
310
+ writeContextFile(contextFile, {
311
+ run_id: node.run_id, node_id: node.id, depth: node.depth,
312
+ turn_id: turnId, access, may_delegate: mayDelegate, may_ask: escalate,
313
+ ...(servers ? { extensions: path.join(extDir, "gateway.json") } : {}),
314
+ });
315
+ relay = { runId: node.run_id, nodeId: node.id, depth: node.depth, contextFile, turnId, mayDelegate, mayAsk: escalate };
316
+ }
317
+ // The turn starts only if it is still queued: a cancel may have dropped it while it waited for
318
+ // its slot (a discussion's turn on a session it borrowed, see cancel). It takes its speed as it starts.
319
+ const speed = tx(() => {
320
+ const claimed = db().prepare("UPDATE turns SET status = 'running', started_at = ? WHERE id = ? AND status = 'queued'").run(now(), turnId);
321
+ if (Number(claimed.changes) !== 1)
322
+ return null;
323
+ return startSpeed(nodeId, turnId);
324
+ });
325
+ if (speed === null)
326
+ return dropped();
327
+ started = true;
328
+ // A node shows as queued until it actually holds a slot.
329
+ db().prepare("UPDATE nodes SET status = 'running', started_at = COALESCE(started_at, ?) WHERE id = ? AND status = 'queued'").run(now(), nodeId);
330
+ // Extensions need the person's consent before the agent starts, once per session.
331
+ const extensions = ext ? await prepareExtensions(node, turnId, ext, extDir, cancelCheck) : null;
332
+ // Either way the agent never ran, so the speed change the turn carried is settled as unreached (endTurn).
333
+ if (extensions && "cancelled" in extensions) {
334
+ endTurn({ status: "cancelled", ended_at: now() }, false);
335
+ return notRun("interrupted", extensions.cancelled);
336
+ }
337
+ if (extensions && "refusal" in extensions)
338
+ return refused(extensions.refusal);
339
+ // A Codex write job given local network: the person's consent, once for the grant it holds.
340
+ const local = await localNetworkConsent(node, turnId, access, cancelCheck);
341
+ if (local && "cancelled" in local) {
342
+ endTurn({ status: "cancelled", ended_at: now() }, false);
343
+ return notRun("interrupted", local.cancelled);
344
+ }
345
+ if (local && "refusal" in local)
346
+ return refused(local.refusal);
347
+ // A Codex job given raw network (stage 2): the person's consent, once for the grant it holds (WP-E).
348
+ const raw = await rawNetworkConsent(node, turnId, access, cancelCheck);
349
+ if (raw && "cancelled" in raw) {
350
+ endTurn({ status: "cancelled", ended_at: now() }, false);
351
+ return notRun("interrupted", raw.cancelled);
352
+ }
353
+ if (raw && "refusal" in raw)
354
+ return refused(raw.refusal);
355
+ let handle;
356
+ try {
357
+ if (cancelCheck())
358
+ throw new Error("cancelled before environment release");
359
+ // Checked last thing before the launch: until then the agent of an earlier turn may have left
360
+ // something running in the worktree. A turn in a job's worktree (its own, or one it works in
361
+ // place in) gets that worktree's git directories as the repository records them; one whose
362
+ // `.git` the agent changed is not started.
363
+ const tree = turnTree(node);
364
+ if (tree && "error" in tree)
365
+ throw new Error(tree.error);
366
+ // A stage-2 Codex turn is confined by relay's own Seatbelt, whose launch makes this check (prepareLaunch).
367
+ const confinement = turnConfinement({ config: cfg, target: targetDef(node.target), grant: grantFor(node, access) });
368
+ const hardLinked = hardLinkProblem(node, access, cfg.allow_dangerous, tree ?? null, grantFor(node, access), confinement);
369
+ if (hardLinked)
370
+ throw new Error(hardLinked);
371
+ // The environment claimed as the turn was picked up, only if nothing it was claimed under has
372
+ // changed while the turn waited (its policy, config file, directory, grant or worker): if it
373
+ // has, the turn fails here rather than launch on the earlier authority.
374
+ const authorized = environment.take();
375
+ // Only standing environment policy is live. Other execution limits retain the run snapshot.
376
+ Object.assign(cfg, authorized.config);
377
+ // A job with its own worktree is launched at the worktree root as jobTree checked it (its real
378
+ // path, whose parent no agent can write), never at a path below it, which something the agent
379
+ // left running could swap for a link between a check and the launch. Where the person was
380
+ // working is said in the prompt instead (prompts.ts). An in-place session inside a job's
381
+ // worktree starts at that worktree's root (workCwd); any other session in its own directory.
382
+ const launchCwd = tree ? tree.worktree : workCwd(node);
383
+ // A job's own worktree's git directories, for a target that commits natively (child_git "native").
384
+ const gitDirs = node.worktree && tree ? [tree.commonDir, tree.gitDir] : undefined;
385
+ const reviewId = sessionParams(node).review_id;
386
+ const reviewNode = reviewId ? getNode(reviewId) : null;
387
+ const independent = nodeTurns(node.id).find((t) => t.id === turnId)?.source === `review:${reviewId}`;
388
+ // Stage 2, only while switched on: who confines this Codex turn's commands, for status and brief
389
+ // (no registry schema change); the skill package copied where its commands can read it.
390
+ let skills = extensions?.skills;
391
+ if (stage2Enabled(process.env, cfg) && node.target === "codex") {
392
+ const relayEnforced = Boolean(destinationOverlay(nodeId, turnId)) || turnConfinement({ config: cfg, target: targetDef(node.target), grant: grantFor(node, access) }) === "relay-enforced";
393
+ recordEnforcement(node.id, turnId, relayEnforced ? "relay" : "codex");
394
+ if (relayEnforced && skills) {
395
+ extAssets = stage2SkillAssets({ skills });
396
+ // Named in the registry, so that the retention sweep can remove it should this process die before the turn does.
397
+ if (extAssets)
398
+ noteSkillAssets(node.id, turnId, extAssets);
399
+ skills = { dir: extAssets, names: skills.names };
400
+ }
401
+ }
402
+ // Bootstrap relay-owned directories before capturing their protected identities. Doing
403
+ // this later in backend preparation let a sibling checkpoint invalidate a fresh launch.
404
+ if (node.target === "codex")
405
+ prepareCodexHome(cfg);
406
+ const neverPolicy = checkpointNever(node.run_id, "launch");
407
+ const neverProblem = neverGrantProblem(neverPolicy, grantFor(node, access) ?? {}, access === "write" ? [launchCwd] : []);
408
+ if (neverProblem)
409
+ throw new Error(neverProblem);
410
+ const pendingOverlay = destinationOverlay(nodeId, turnId);
411
+ if (pendingOverlay) {
412
+ overlay = consumeOverlay(node.run_id, pendingOverlay.id, turnId);
413
+ overlayTimer = setTimeout(() => {
414
+ stopOverlay(node.run_id, overlay.id, "overlay deadline expired");
415
+ overlayAbort.abort();
416
+ }, overlayRemainingMs(overlay));
417
+ }
418
+ setParam(node.id, "never_policy", { hash: neverPolicy.hash, version: neverPolicy.version, removed_builtins: neverPolicy.removed, hosted_web: neverPolicy.hosts.length ? "disabled" : "host policy", extension_tools: "qualified adapters only" });
419
+ handle = await startTurn((signal) => launchTurn(targetDef(node.target), {
420
+ neverPolicy,
421
+ ...(overlay ? { overlay } : {}),
422
+ checkEnvironment: () => {
423
+ if (reserved) {
424
+ launchReservationState(node.run_id, turnId, "running");
425
+ launchAttempted = true;
426
+ }
427
+ // Even without an overlay, observe this Mac's addresses as well as any additions
428
+ // another checkpoint kept while the backend prepared the turn.
429
+ checkpointNever(node.run_id, "launch");
430
+ if (overlay)
431
+ assertOverlayLaunch(overlay, turnId);
432
+ assertNeverLaunchCurrent(node.run_id, neverPolicy);
433
+ },
434
+ onNote: (note) => {
435
+ const notes = sessionParams(getNode(node.id)).notes ?? [];
436
+ setParam(node.id, "notes", [...new Set([...notes, `Turn ${turnId}: ${redact(note)}`])]);
437
+ },
438
+ onServed: (model) => {
439
+ try {
440
+ recordServed(node.id, targetDef(node.target), model);
441
+ }
442
+ catch {
443
+ throw new Error("relay could not record the agent's model; the turn must stop.");
444
+ }
445
+ },
446
+ onWaived: (which) => {
447
+ try {
448
+ recordWaiver(node.id, which);
449
+ }
450
+ catch {
451
+ throw new Error("relay could not record the endpoint/settings waiver; the turn must stop.");
452
+ }
453
+ },
454
+ target: targetDef(node.target),
455
+ turnId,
456
+ sessionId: node.session_id ?? undefined,
457
+ prompt,
458
+ cwd: launchCwd,
459
+ access,
460
+ reviewReadDeny: independent && reviewNode ? reviewParams(reviewNode).caller_transcripts : undefined,
461
+ relay,
462
+ model: node.model ?? cfg.targets[node.target]?.default_model ?? undefined,
463
+ effort: node.effort ?? cfg.targets[node.target]?.default_effort ?? undefined,
464
+ // As the turn took it when it started (startSpeed).
465
+ speed,
466
+ config: cfg,
467
+ environment: authorized.selection.env,
468
+ environmentReleased: authorized.selection.releasedNames,
469
+ dir,
470
+ logPath: node.log_path ?? path.join(dir, "agent.log"),
471
+ gitDirs,
472
+ worktreePin: sessionParams(getNode(node.id)).worktree_pin,
473
+ gitEnv: tree?.env,
474
+ escalate,
475
+ onApproval: (ask, turnOver) => {
476
+ const problem = overlayTurnProblem(nodeId, turnId);
477
+ if (problem)
478
+ return Promise.resolve({ allow: false, note: problem });
479
+ return requestApproval(node.id, turnId, ask, () => turnOver() || cancelCheck() || Boolean(overlayTurnProblem(nodeId, turnId)));
480
+ },
481
+ heldForJob: (ask) => heldForJob(node.id, ask),
482
+ grant: grantFor(node, access),
483
+ markers: { runId: node.run_id, nodeId: node.id, depth: node.depth },
484
+ ...(skills ? { skills } : {}),
485
+ ...(ext?.mcp_servers.length ? { extensionServers: ext.mcp_servers.map((s) => s.name) } : {}),
486
+ // For progress lines in the root session: what the agent is doing now.
487
+ onActivity: (text) => {
488
+ try {
489
+ // Stored escaped whatever the backend made of it: status, progress lines and relay
490
+ // tree show it to a person (review C12). Text already escaped passes unchanged.
491
+ updateTurn(turnId, { activity: clipped(redact(text), 300), activity_at: now() });
492
+ }
493
+ catch {
494
+ // Progress only.
495
+ }
496
+ },
497
+ onUsage: (usage) => {
498
+ try {
499
+ updateTurn(turnId, { usage_json: JSON.stringify(usage) });
500
+ }
501
+ catch {
502
+ // Reporting only.
503
+ }
504
+ },
505
+ signal: AbortSignal.any([signal, overlayAbort.signal]),
506
+ }));
507
+ }
508
+ catch (err) {
509
+ // Stopped while it started (the worker's stop aborted it): the turn was cancelled, not refused.
510
+ if (stopping.signal.aborted) {
511
+ endTurn({ status: "cancelled", ended_at: now() }, false);
512
+ return notRun("interrupted", "cancelled while the agent was being started");
513
+ }
514
+ // A backend refuses to launch rather than launch without the confinement it was asked for,
515
+ // or because it could not write the files it launches the agent with (storageProblem). What
516
+ // it refused can quote a secret (an endpoint's URL with its key in it, say).
517
+ return refused(storageProblem(err, "the agent was not started") ?? err.message);
518
+ }
519
+ updateNode(nodeId, { agent_pid: handle.pid, agent_pgid: handle.pgid, agent_start: handle.startedAt, log_path: node.log_path ?? path.join(dir, "agent.log") });
520
+ // The agent leads its own session and group (launched detached). Keep its leader id for the
521
+ // run's lifetime so a process left in its group or session is placed inside the launched tree
522
+ // after it exits (src/core/presence.ts), even once agent_pgid is cleared below.
523
+ recordLaunchLeader(node.run_id, handle.pgid, "agent", nodeId);
524
+ let timedOut = false;
525
+ let ranMs = 0;
526
+ let pausedMs = 0;
527
+ const tick = 500;
528
+ const maxPauseMs = 2 * cfg.approval_timeout_s * 1000;
529
+ // Time spent waiting for someone to answer an approval request does not count against the
530
+ // turn's limit. A cancel request can also arrive through the registry alone (from the CLI).
531
+ const poll = setInterval(() => {
532
+ if (cancelCheck())
533
+ return void handle.cancel();
534
+ const closing = originOverlay(nodeId, turnId);
535
+ if (closing && (closing.receipt?.delivered !== undefined || overlayDeadlineExpired(closing)))
536
+ return void handle.cancel();
537
+ if (overlay) {
538
+ const current = getOverlay(node.run_id, overlay.id);
539
+ if (current.state !== "running" || overlayDeadlineExpired(current)) {
540
+ stopOverlay(node.run_id, overlay.id, current.outcome ?? "overlay deadline expired");
541
+ overlayAbort.abort();
542
+ return void handle.cancel();
543
+ }
544
+ }
545
+ // The pause is capped, so repeated requests cannot hold a turn open indefinitely.
546
+ if (hasPending(nodeId) && pausedMs < maxPauseMs)
547
+ pausedMs += tick;
548
+ else
549
+ ranMs += tick;
550
+ if (timeoutS !== null && ranMs >= timeoutS * 1000 && !timedOut) {
551
+ timedOut = true;
552
+ void handle.cancel();
553
+ }
554
+ }, tick);
555
+ const done = applyRecordedCancellation(await handle.done, getTurn(turnId)?.status);
556
+ clearInterval(poll);
557
+ active.delete(handle);
558
+ // What relay keeps of the turn (its reply, its error, the backend's warnings and speed warnings,
559
+ // which can quote Claude's fast-mode notice, the commands its agent was refused) holds none of
560
+ // the secrets relay passes on, nor the structured own_review arguments a reply can echo:
561
+ // filtered before the turn row or outcome files are written, including the result returned to
562
+ // the worker, which a job's `blocked`, a discussion's and a review's warnings are made from.
563
+ const result = {
564
+ ...done, finalMessage: redact(redactOwnReview(done.finalMessage)),
565
+ ...(done.error !== undefined ? { error: redact(done.error) } : {}),
566
+ ...(done.refusal ? { refusal: { ...done.refusal, message: redact(redactOwnReview(done.refusal.message)) } } : {}),
567
+ ...(done.warnings ? { warnings: done.warnings.map((w) => redact(w)) } : {}),
568
+ ...(done.speedWarnings ? { speedWarnings: done.speedWarnings.map((w) => redact(w)) } : {}),
569
+ ...(done.denials ? { denials: done.denials.map((d) => redact(d)) } : {}),
570
+ };
571
+ const errorOf = (warnings) => redactOwnReview([timedOut ? `timed out after ${timeoutS}s.` : result.status === "ok" ? "" : (result.error ?? result.status), ...warnings, ...(result.speedWarnings ?? [])].filter(Boolean).join(" "), true) || null;
572
+ // The turn's authority ends with its agent: the turn is recorded as over now, before relay's own
573
+ // work on what the agent left (its process checks, the final message's file, the warnings), so
574
+ // that nothing left of the agent can act for the turn meanwhile (db.ts turnEnded). What that work
575
+ // finds is added to the turn's error below, before the worker records the turn's end for its
576
+ // session; a call waiting on the turn takes it only then (db.ts turnSettled).
577
+ const earlyError = errorOf([]);
578
+ endTurn({
579
+ status: result.status === "refused" ? "refused" : result.status === "ok" ? "done" : result.status === "interrupted" && !timedOut ? "cancelled" : "failed",
580
+ refusal_json: result.refusal ? JSON.stringify(result.refusal) : null,
581
+ reply: result.finalMessage,
582
+ error: earlyError,
583
+ denials: result.denials?.length ? JSON.stringify(result.denials) : null,
584
+ ended_at: now(),
585
+ }, result.delivered !== false);
586
+ appClean = !done.survivors?.length && done.unseenMs === undefined && !groupAlive(handle.pgid);
587
+ overlayCleanup = { clean: !nodeHasLiveExecutor(nodeId) && !done.survivors?.length && done.unseenMs === undefined && !groupAlive(handle.pgid), problem: done.warnings?.join(" ") ?? "", ...(done.survivors?.length ? { survivors: done.survivors } : {}) };
588
+ if (reserved)
589
+ finishLaunchReservation(node.run_id, turnId, { ...overlayCleanup, appClean });
590
+ // The final message, kept whole in a file: one that cannot be written is said with the turn's
591
+ // own warnings, which are what ask's caller is given.
592
+ const finalPath = path.join(dir, `final-${turnId}.md`);
593
+ const finalUnkept = keepRecord(finalPath, result.finalMessage, { consequence: "the final message is kept only in the registry" });
594
+ if (finalUnkept)
595
+ recordWarnings.push(`${finalUnkept}.`);
596
+ // The backend resolves only once the agent's process group is empty. If something survived
597
+ // even that, the record stays so it can still be found and stopped.
598
+ const fields = groupAlive(handle.pgid) ? {} : { agent_pid: null, agent_pgid: null, agent_start: null };
599
+ // A session the prompt never reached holds none of the work: the next turn replays it all.
600
+ if (result.sessionId && result.delivered !== false)
601
+ fields.session_id = result.sessionId;
602
+ updateNode(nodeId, fields);
603
+ // Anything the agent started that relay cannot account for is reported, not forgotten, and so
604
+ // is any server or tool of its extensions that relay could not offer.
605
+ const warnings = [...processWarnings(result), ...(ext?.mcp_servers.length ? gatewayWarnings(extDir) : []), ...recordWarnings, ...takeDiagnosticProblems()].map((w) => redact(w));
606
+ const error = errorOf(warnings);
607
+ if (error !== earlyError)
608
+ updateTurn(turnId, { error });
609
+ // Only once the turn is recorded as over: a request still queued behind another is filed only
610
+ // while its turn is running, so none can be filed after this.
611
+ expireRequests(nodeId);
612
+ const closing = originOverlay(nodeId, turnId);
613
+ if (closing) {
614
+ try {
615
+ const next = prepareOverlayRestart(node.run_id, closing.id, overlayCleanup);
616
+ if (next.state === "ready")
617
+ return { ...result, status: "ok", finalMessage: overlayPrompt(next), error: undefined, timedOut, warnings, finalPath: finalUnkept ? null : finalPath, restartPending: true };
618
+ }
619
+ catch (err) {
620
+ finishOverlay(node.run_id, closing.id, { ...overlayCleanup, problem: err.message });
621
+ warnings.push(`Overlay allowed, not executed: ${err.message}`);
622
+ }
623
+ }
624
+ if (overlay)
625
+ warnings.push(overlayPrompt(getOverlay(overlay.runId, overlay.id)), `Overlay cleanup: ${overlayCleanup.clean ? "verified teardown" : "tainted; reservations retained"}.`);
626
+ return { ...result, error: error ?? undefined, timedOut, warnings, finalPath: finalUnkept ? null : finalPath };
627
+ }
628
+ finally {
629
+ if (reserved)
630
+ finishLaunchReservation(node.run_id, turnId, launchAttempted ? { ...overlayCleanup, appClean } : { clean: true });
631
+ if (overlayTimer)
632
+ clearTimeout(overlayTimer);
633
+ if (overlay)
634
+ finishOverlay(node.run_id, overlay.id, overlayCleanup);
635
+ // A turn that ended without launching (cancelled while it waited for its slot, say) forgets
636
+ // the environment it claimed. One that launched has already taken it.
637
+ environment.drop();
638
+ if (slot !== null)
639
+ releaseSlot(slot);
640
+ fs.rmSync(extDir, { recursive: true, force: true });
641
+ if (extAssets) {
642
+ fs.rmSync(extAssets, { recursive: true, force: true });
643
+ try {
644
+ dropSkillAssets(nodeId, turnId);
645
+ }
646
+ catch { /* the sweep finds it gone and forgets it */ }
647
+ }
648
+ }
649
+ }
650
+ /**
651
+ * Before a turn of a session given extensions: the person's consent, asked once per session as an
652
+ * approval request only they can allow (docs/extensions.md), then the turn's skill package and the
653
+ * gateway's manifest. A refusal says why the agent was not started.
654
+ */
655
+ async function prepareExtensions(node, turnId, ext, extDir, cancelCheck) {
656
+ // Identify unqualified effects before consent or model launch. The gateway repeats the exact
657
+ // definition/version/schema check and centrally screens every forwarded call.
658
+ let catalog;
659
+ try {
660
+ catalog = await neverToolAdapters(ext.mcp_servers.length ? readMcpFile() : {});
661
+ }
662
+ catch (err) {
663
+ return { refusal: `never cannot qualify extension tools: ${err.message}` };
664
+ }
665
+ const opaque = ext.mcp_servers.filter(s => !catalog.some(a => a.identity.server === s.name));
666
+ if (opaque.length)
667
+ return { refusal: `never withholds extension tools from ${opaque.map(s => s.name).join(", ")}: no qualified tool-specific effects adapter; opaque paths, network destinations, redirects or commands cannot be screened. Continue without these servers.` };
668
+ if (!ext.consent) {
669
+ const answer = await requestApproval(node.id, turnId, { kind: "extensions", summary: consentText(node, ext) }, cancelCheck);
670
+ if (!answer.allow) {
671
+ // A cancel while it waited ends the turn as cancelled, not failed.
672
+ if (cancelCheck())
673
+ return { cancelled: "cancelled while waiting for the user's consent to its extensions" };
674
+ const item = node.kind === "thread" ? "thread" : "job";
675
+ // Who decided, in relay's words (deciderForAgent): the root session may deny, and so may anyone from a terminal.
676
+ const why = answer.decider
677
+ ? `consent to the extensions this ${item} was given was refused ${answer.decider}${answer.deciderNote ? ` (${answer.deciderNote})` : ""}`
678
+ : `nobody consented to the extensions this ${item} was given (${answer.note ?? "no answer"})`;
679
+ return { refusal: `${why}, so its agent was not started. Continue it to be asked again, or start the work without extensions.` };
680
+ }
681
+ setParam(node.id, "extensions", { ...ext, consent: { by: answer.decider ?? "by the user", at: now() } });
682
+ }
683
+ try {
684
+ if (ext.mcp_servers.length)
685
+ writeManifest(extDir, ext.mcp_servers, node.run_id);
686
+ if (!ext.skills.length)
687
+ return {};
688
+ // Claude takes the package as a plugin; Codex as an extra skill root, with no plugin manifest.
689
+ buildSkillPackage(extDir, ext.skills, { plugin: node.target === "claude" });
690
+ return { skills: { dir: extDir, names: ext.skills.map((s) => s.name) } };
691
+ }
692
+ catch (err) {
693
+ return { refusal: `${err.message}, so the agent was not started.` };
694
+ }
695
+ }
696
+ export { localNetworkKey };
697
+ /** The question the person is asked about a Codex job's local network. */
698
+ export function localNetworkText(node) {
699
+ return `allow ${node.id} (${node.target ? targetLabel(targetDef(node.target)) : "the agent"}, a write job) to reach this Mac's loopback and the local network from its shell: every service listening there, sshd and screen sharing included, with your account's reach, loopback directly as well as through Codex's proxy; and to listen on every interface, so devices on your local network or tailnet can connect to servers it starts; for the rest of the job`;
700
+ }
701
+ /**
702
+ * Before a turn of a Codex write job whose grant says local_network: the person's consent, asked as
703
+ * an approval request only they can allow (PERSON_KINDS), once for the grant the job holds
704
+ * (localNetworkKey). A refusal says why the agent was not started; without consent nothing runs,
705
+ * rather than running with less than the caller asked for.
706
+ */
707
+ async function localNetworkConsent(node, turnId, access, cancelCheck) {
708
+ // A consent is for the grant it was given under. Once the session holds another (local network
709
+ // taken away, write paths changed), it is gone, whatever this turn's access: a grant that comes
710
+ // back later is asked about again.
711
+ const params = sessionParams(getNode(node.id));
712
+ const given = params.local_network_consent;
713
+ if (given && (!params.grant?.local_network || localNetworkKey(params.grant) !== given.grant))
714
+ setParam(node.id, "local_network_consent", null);
715
+ const grant = grantFor(node, access);
716
+ if (node.target !== "codex" || access !== "write" || !grant?.network || !grant.local_network)
717
+ return null;
718
+ // While stage 2 is switched on, local mode is refused outright, not asked about (raw-network.ts localModeRetired; decision D2).
719
+ const retired = localModeRetired(runConfig(node.run_id));
720
+ if (retired)
721
+ return { refusal: `${retired}. So this job's agent was not started: continue it with one of those grants instead of local_network.` };
722
+ const key = localNetworkKey(grant);
723
+ if (sessionParams(getNode(node.id)).local_network_consent?.grant === key)
724
+ return null;
725
+ const answer = await requestApproval(node.id, turnId, { kind: "local_network", summary: localNetworkText(node) }, cancelCheck);
726
+ if (!answer.allow) {
727
+ if (cancelCheck())
728
+ return { cancelled: "cancelled while waiting for the user's consent to its local network" };
729
+ const why = answer.decider
730
+ ? `consent to this job's local network was refused ${answer.decider}${answer.deciderNote ? ` (${answer.deciderNote})` : ""}`
731
+ : `nobody consented to this job's local network (${answer.note ?? "no answer"})`;
732
+ return { refusal: `${why}, so its agent was not started. Continue it to be asked again, or continue it with a grant without local_network for internet access only.` };
733
+ }
734
+ setParam(node.id, "local_network_consent", { grant: key, by: answer.decider ?? "by the user", at: now() });
735
+ return null;
736
+ }
737
+ /** A read turn keeps only the network part of a grant: extra write paths never apply to it. */
738
+ function grantFor(node, access) {
739
+ const grant = sessionParams(node).grant ?? undefined;
740
+ if (!grant)
741
+ return undefined;
742
+ const { env, ...standing } = grant;
743
+ return access === "write" ? standing : standing.network ? { network: true } : undefined;
744
+ }