@jbkjr/relay 0.0.0-stage → 1.2.2

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 +393 -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 +1539 -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 +345 -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 +641 -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 +345 -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 +635 -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 +1518 -0
  186. package/docs/pinned-codex.md +333 -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,192 @@
1
+ // The registry of targets. Adding one is a module beside claude.ts and a line here, and its
2
+ // backend in backends/index.ts: there is no loading of targets from config, so that each one relay
3
+ // can launch is reviewed as code. The registry is data: it imports no backend, so that the
4
+ // backends and the config can import it.
5
+ import { claude } from "./claude.js";
6
+ import { codex } from "./codex.js";
7
+ import { copilot } from "./copilot.js";
8
+ import { gemini } from "./gemini.js";
9
+ import { grok } from "./grok.js";
10
+ import { TARGET_IDS } from "./types.js";
11
+ import { unknownStrict, unknownRefusal, unknownOff, noneRefusal, familyRefusal, defaultRefusal } from "../core/steering.js";
12
+ export { SPEEDS, speedRank, TARGET_IDS, VENDOR_NAMES } from "./types.js";
13
+ export const TARGETS = [claude, codex, copilot, gemini, grok];
14
+ /**
15
+ * The side label of the calling agent in a discussion or review where its target id would be the
16
+ * other side's too (same_family "allow", or an existing session of its own family), and the prefix
17
+ * of its review items. Rows recorded before relay refused callers of unknown family use it for
18
+ * those. No target uses either.
19
+ */
20
+ export const CALLER_LABEL = "caller";
21
+ export const CALLER_PREFIX = "R";
22
+ {
23
+ const ids = TARGETS.map((t) => t.id);
24
+ if (ids.some((id) => id === "unknown" || id === CALLER_LABEL))
25
+ throw new Error("target ids unknown and caller are reserved");
26
+ if (ids.join() !== TARGET_IDS.join())
27
+ throw new Error(`relay's target registry (${ids.join(", ")}) does not match TARGET_IDS (${TARGET_IDS.join(", ")})`);
28
+ const prefixes = TARGETS.map((t) => t.reviewPrefix);
29
+ if (new Set(prefixes).size !== prefixes.length || prefixes.some((p) => !/^[A-Z]{1,2}$/.test(p) || p === CALLER_PREFIX)) {
30
+ throw new Error(`relay's targets need distinct review prefixes of one or two capital letters other than ${CALLER_PREFIX}, not ${prefixes.join(", ")}`);
31
+ }
32
+ }
33
+ const BY_ID = new Map(TARGETS.map((t) => [t.id, t]));
34
+ export const isTarget = (id) => typeof id === "string" && BY_ID.has(id);
35
+ export const targetDef = (id) => BY_ID.get(id);
36
+ /** Human-facing target name or id. Opting in does not make an unqualified target qualified. */
37
+ export const targetLabel = (t, label = t.name) => `${label}${t.qualified === false ? " (experimental)" : ""}`;
38
+ /** One value per target, keyed by id. */
39
+ export const perTarget = (fn) => Object.fromEntries(TARGETS.map((t) => [t.id, fn(t)]));
40
+ /** The floor versions relay's confinement was checked against by hand. Older ones are refused. */
41
+ export const TESTED = perTarget((t) => t.tested);
42
+ /** The first x.y.z in a version line: "codex-cli 0.162.1" is [0, 162, 1]. */
43
+ export const versionOf = (text) => {
44
+ const m = /(\d+)\.(\d+)\.(\d+)/.exec(typeof text === "string" ? text : "");
45
+ return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
46
+ };
47
+ /** Whether version `a` is older than `b`, compared number by number over `b`'s (a missing number in `a` counts as 0). */
48
+ export function olderVersion(a, b) {
49
+ for (let i = 0; i < b.length; i++)
50
+ if ((a[i] ?? 0) !== b[i])
51
+ return (a[i] ?? 0) < b[i];
52
+ return false;
53
+ }
54
+ /**
55
+ * Credentials any registered target's CLI would take from the environment in place of its stored
56
+ * login. All of them, whichever target is launched: no agent is handed another vendor's keys,
57
+ * except under the legacy global child_auth "any", which removes none (see scrubbedCredentials).
58
+ */
59
+ export const CREDENTIALS = new RegExp(TARGETS.map((t) => `(?:${t.credentialEnv.source})`).join("|"));
60
+ /**
61
+ * The targets of other families that `id`'s sessions reach as shipped (switched on by default),
62
+ * for what is written ahead of any config: the generated skills and adapters.
63
+ */
64
+ export const otherTargets = (id) => TARGETS.filter((t) => t.vendor !== targetDef(id).vendor && t.enabledByDefault);
65
+ /** The same, named: "Codex". */
66
+ export const otherFamilies = (id) => otherTargets(id).map((t) => targetLabel(t)).join(", ");
67
+ /**
68
+ * The family a target answers with when running `model`: its own, or for a harness of several
69
+ * families' models the model's, from its reviewed list; null when relay cannot tell (no model, an
70
+ * unknown id, an automatic choice).
71
+ */
72
+ export function vendorFor(def, model) {
73
+ if (def.vendor)
74
+ return def.vendor;
75
+ if (!model || !def.models || !Object.hasOwn(def.models, model))
76
+ return null;
77
+ return def.models[model];
78
+ }
79
+ // Discussions and reviews have two sides, each labelled with its target's id (or CALLER_LABEL).
80
+ /** How a side is named in messages: "Claude", or "the calling agent's" side for CALLER_LABEL. */
81
+ export const sideName = (label) => (isTarget(label) ? targetLabel(targetDef(label)) : "calling");
82
+ /** The prefix of a side's review items: C1, X2, or R3 for a caller of unknown family. */
83
+ export const sidePrefix = (label) => (isTarget(label) ? targetDef(label).reviewPrefix : CALLER_PREFIX);
84
+ /** The side a review item id belongs to, by its prefix, or null for an id no side would give. */
85
+ export function sideOfItem(id) {
86
+ const prefix = /^([A-Z]+)\d+$/.exec(id)?.[1];
87
+ if (!prefix)
88
+ return null;
89
+ if (prefix === CALLER_PREFIX)
90
+ return CALLER_LABEL;
91
+ return TARGETS.find((t) => t.reviewPrefix === prefix)?.id ?? null;
92
+ }
93
+ /** Two side labels in registry order (an unknown caller last), so that what is listed by side reads the same whoever called. */
94
+ export const inSideOrder = (labels) => {
95
+ const rank = (l) => (isTarget(l) ? TARGET_IDS.indexOf(l) : TARGET_IDS.length);
96
+ return [...labels].sort((a, b) => rank(a) - rank(b));
97
+ };
98
+ export const targetEnabled = (cfg, id) => cfg.targets?.[id]?.enabled ?? targetDef(id).enabledByDefault;
99
+ /** Resolve each call: explicit targets are allowed and labelled by default; omitted targets
100
+ * always cross the current routing family. Unknown callers use only their explicit target or
101
+ * default_target.unknown. Strict policy retains 0.9 admission; authority checks stay separate. */
102
+ export function resolveTarget(caller, requested, cfg, opts = {}) {
103
+ const registry = opts.registry ?? TARGETS;
104
+ const find = (id) => registry.find((t) => t.id === id);
105
+ const settings = (t) => cfg.targets?.[t.id];
106
+ const on = (t) => settings(t)?.enabled ?? t.enabledByDefault;
107
+ const modelOf = (t) => opts.model ?? settings(t)?.default_model ?? undefined;
108
+ const familyOf = (t) => vendorFor(t, modelOf(t));
109
+ const names = (ts) => ts.map((t) => targetLabel(t)).join(" or ");
110
+ const me = caller ? find(caller) : undefined;
111
+ const mine = opts.callerVendor !== undefined ? opts.callerVendor : (me?.vendor ?? null);
112
+ const strict = cfg.same_family === "refuse";
113
+ const reached = (def) => ({ target: def.id, ...(def.vendor === null && modelOf(def) ? { model: modelOf(def) } : {}) });
114
+ if (!me || !mine) {
115
+ if (strict)
116
+ return { reason: unknownStrict };
117
+ const id = requested ?? cfg.default_target?.unknown;
118
+ if (!id)
119
+ return { reason: unknownRefusal(cfg, registry) };
120
+ const def = find(id);
121
+ if (!def)
122
+ return { reason: `relay has no agent called "${id}"; it knows ${registry.map((t) => targetLabel(t, t.id)).join(", ")}.` };
123
+ if (!opts.existing && !on(def))
124
+ return { reason: requested === undefined ? unknownOff(id) : `${targetLabel(def)} is switched off in relay's config (targets.${def.id}.enabled). Do this part yourself.` };
125
+ return reached(def);
126
+ }
127
+ const others = registry.filter((t) => on(t) && familyOf(t) !== null && familyOf(t) !== mine);
128
+ /** Models of `t` from families other than the caller's, as examples for a message. */
129
+ const examples = (t) => Object.entries(t.models ?? {}).filter(([, v]) => v !== mine).map(([m]) => m).slice(0, 6).join(", ");
130
+ /** Said with a refusal of the caller's own family: what the person can change, if they want such calls. */
131
+ /**
132
+ * Why the caller cannot reach `def` with the model it would run, or null. `named`: the call names
133
+ * the target itself, the only way the caller's own family is ever reached, and only where the
134
+ * config allows it; a default never is.
135
+ */
136
+ const crossing = (def, named) => {
137
+ if (named && !strict)
138
+ return null;
139
+ if (!named && def.vendor === null && (!familyOf(def) || familyOf(def) === mine))
140
+ return defaultRefusal(me.id, def, modelOf(def), mine, examples(def));
141
+ return familyRefusal(def, me, mine, modelOf(def), named, others, examples(def));
142
+ };
143
+ if (requested !== undefined) {
144
+ const def = find(requested);
145
+ if (!def)
146
+ return { reason: `relay has no agent called "${requested}"; it knows ${registry.map((t) => targetLabel(t, t.id)).join(", ")}.` };
147
+ const no = opts.existing ? null : crossing(def, true);
148
+ if (no)
149
+ return { reason: no };
150
+ if (!opts.existing && !on(def)) {
151
+ return { reason: `${targetLabel(def)} is switched off in relay's config (targets.${def.id}.enabled).${others.length ? ` Use ${names(others)} instead, or do this part yourself.` : " Do this part yourself."}` };
152
+ }
153
+ return reached(def);
154
+ }
155
+ const preset = cfg.default_target?.[me.id];
156
+ if (preset) {
157
+ const def = find(preset);
158
+ if (!def || def.vendor === mine)
159
+ return { reason: `default_target.${me.id} in relay's config names ${def ? targetLabel(def, preset) : preset}, which a ${targetLabel(me)} agent cannot reach. Name a target, or fix the config.` };
160
+ const no = crossing(def, false);
161
+ if (no)
162
+ return { reason: no };
163
+ if (!on(def))
164
+ return { reason: `default_target.${me.id} in relay's config names ${targetLabel(def, preset)}, which is switched off. Name a target, or fix the config.` };
165
+ return reached(def);
166
+ }
167
+ if (others.length === 1)
168
+ return reached(others[0]);
169
+ if (!others.length)
170
+ return { reason: noneRefusal };
171
+ return { reason: `several agents of other families are available (${others.map((t) => targetLabel(t, t.id)).join(", ")}), so name one with target, or set default_target.${me.id} in relay's config.` };
172
+ }
173
+ /**
174
+ * Why `def` cannot honour a call that needs `needs`, or null. Admission control: a call is refused
175
+ * up front rather than run with less than it was promised. Whether relay's own confinement can
176
+ * enforce on this machine is checked by the caller (ops), which can reach the mechanism.
177
+ */
178
+ export function incapable(def, needs) {
179
+ const c = def.capabilities;
180
+ if (c.confinement === "none")
181
+ return `${targetLabel(def)} has no confinement relay can enforce or verify, so relay does not launch it.`;
182
+ if (needs.mode === "read" && !c.readOnly)
183
+ return `relay cannot keep ${targetLabel(def)} read-only, so it does not start read-only work there. Use another agent, or do this part yourself.`;
184
+ if (!needs.network && !c.networkOff) {
185
+ return `relay cannot keep ${targetLabel(def)} off the network yet${c.confinement === "relay-enforced" ? " (relay does not know which hosts it needs to reach its model, so its network proxy would admit none)" : ""}, so it starts ${targetLabel(def)} only with network access: pass grant: { network: true } if the work may use the network, or use another agent.`;
186
+ }
187
+ if (needs.writePaths && !c.writeRoots)
188
+ return `relay cannot give ${targetLabel(def)} write access outside its worktree, so grant.write_paths cannot be honoured there.`;
189
+ if (needs.continues && !c.resume)
190
+ return `${targetLabel(def)} sessions cannot be continued in a later turn, so relay cannot follow up, resume or hold a discussion there.`;
191
+ return null;
192
+ }
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Every target relay knows, in registry order. A target is what callers name and what a node
3
+ * records (nodes.target, review files, transcripts), so an id, once shipped, is never renamed.
4
+ */
5
+ export const TARGET_IDS = ["claude", "codex", "copilot", "gemini", "grok"];
6
+ /** How families are named in messages. */
7
+ export const VENDOR_NAMES = {
8
+ anthropic: "Anthropic", openai: "OpenAI", google: "Google", xai: "xAI", moonshot: "Moonshot", microsoft: "Microsoft",
9
+ };
10
+ /**
11
+ * How fast a launched agent's model answers, in relay's names, slowest first. Standard is every
12
+ * harness's own default, and what relay asks for unless told otherwise; the faster speeds cost the
13
+ * person money or allowance (Claude's fast mode is billed to usage credits; Codex's faster service
14
+ * tiers use more of the plan).
15
+ */
16
+ export const SPEEDS = ["standard", "fast", "ultrafast"];
17
+ /** How a speed compares with another: its place in SPEEDS. */
18
+ export const speedRank = (s) => SPEEDS.indexOf(s);
@@ -0,0 +1,35 @@
1
+ // The harness versions relay has checked by hand or by the maintainer's release checks, one list per
2
+ // pin, oldest first. A version is appended only with the evidence for it in
3
+ // docs/research/claude-temp-limit.md or docs/qualification/, and only after the maintainer reviews it.
4
+ // Each list stays on one line of exactly this shape, which the release checks rewrite, and the docs'
5
+ // `<!-- verified:KEY -->` markers repeat it (test/verified.test.ts).
6
+ // Nothing here is a `tested` floor: those stay in each target's module.
7
+ export const VERIFIED = {
8
+ // Claude Code versions whose temporary-directory code relay has read: each measures
9
+ // CLAUDE_CODE_TMPDIR before resolving links. The newest is the long-home link's ceiling
10
+ // (backends/native-temp.ts, CLAUDE_TEMP_LINK_VERIFIED_THROUGH).
11
+ claudeTempLink: ["2.1.302", "2.1.303", "2.1.304", "2.1.308", "2.1.325", "2.1.326"],
12
+ // Claude Code versions whose built-in plugin registry CLAUDE_BUILTIN_PLUGINS (backends/claude.ts)
13
+ // was checked against (2.1.325: docs/research/claude-builtin-plugins.md). The list holds every
14
+ // listed version's registry and is exactly the newest's. Evidence only: an unfamiliar built-in
15
+ // plugin fails a turn on any version.
16
+ claudeBuiltinPlugins: ["2.1.303", "2.1.308", "2.1.325", "2.1.326"],
17
+ // Claude Code versions whose cc-plugin-privacy relay has read and leaves on in the Claude agents it
18
+ // launches (backends/claude.ts keepsPrivacyPlugin; 2.1.325 and 2.1.326: docs/research/claude-builtin-plugins.md).
19
+ // A safety pin, matched whole: on any other version relay disables that plugin like every other
20
+ // built-in, and a turn whose init report lists it is refused.
21
+ claudePrivacyPlugin: ["2.1.325", "2.1.326"],
22
+ // Gemini CLI versions on which relay's tools through Gemini's command-based tool discovery were
23
+ // checked, matched whole: live on 0.64.0 and 0.65.0, by source comparison on 0.67.0 and 0.68.0
24
+ // (docs/qualification/gemini-<v>.md) (targets/gemini.ts toolDiscovery, backends/tool-discovery.ts).
25
+ // Informational: the tools are offered on every version, and each launch checks discovery ran.
26
+ geminiToolDiscovery: ["0.64.0", "0.65.0", "0.67.0", "0.68.0"],
27
+ // Codex CLI releases on which relay's Codex route was checked: 0.163.0 by its qualification
28
+ // (docs/UPGRADING.md), 0.164.0 by hand (2026-10-23), later ones by the release
29
+ // watcher (docs/qualification/codex-<v>.md). Informational: targets/codex.ts's `tested` stays the floor.
30
+ codexCli: ["0.163.0", "0.164.0", "0.167.0", "0.167.1", "0.167.2", "0.170.0"],
31
+ };
32
+ /** "a", "a and b", "a, b and c": a list as relay's messages and docs write one. */
33
+ export const englishList = (xs) => (xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`);
34
+ /** The newest version of a list. */
35
+ export const newest = (key) => VERIFIED[key][VERIFIED[key].length - 1];
package/dist/worker.js ADDED
@@ -0,0 +1,113 @@
1
+ import { closeTurns, db, getNode, nextQueuedTurn, recordLaunchLeader, registerSelf, runConfig, tx, updateNode } from "./core/db.js";
2
+ import { procStart } from "./core/procs.js";
3
+ import { finishNode, finishTurn, settleIdle } from "./core/outcome.js";
4
+ import { cancelActiveTurns, isCancelled, runSessionTurn } from "./core/session.js";
5
+ import { housekeepDaily } from "./core/retention.js";
6
+ import { loadConfig } from "./core/config.js";
7
+ import { redact } from "./core/secrets.js";
8
+ import { storageProblem } from "./core/storage.js";
9
+ import { workerRedaction } from "./core/env-broker.js";
10
+ import { nextOverlayTurn } from "./core/restart-overlay.js";
11
+ let terminating = false;
12
+ /**
13
+ * Entry point of a detached worker. A worker owns one session and drains its queued turns. It
14
+ * outlives the MCP server that started it, because a child agent's MCP server exits when that
15
+ * agent's turn ends.
16
+ */
17
+ export async function runWorker(nodeId) {
18
+ // Until the owning root supplies its redaction-only set, no path or diagnostic line can be
19
+ // vouched for. Withhold whole writes, including buffers, rather than leak unknown root values.
20
+ let redactionReady = false;
21
+ for (const stream of [process.stdout, process.stderr]) {
22
+ const write = stream.write.bind(stream);
23
+ stream.write = ((chunk, ...rest) => write(redactionReady
24
+ ? redact(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"))
25
+ : "relay: worker diagnostic withheld: root redaction values unavailable\n", ...rest));
26
+ }
27
+ const node = getNode(nodeId);
28
+ if (!node)
29
+ throw new Error(`unknown node ${nodeId}`);
30
+ updateNode(nodeId, { worker_pid: process.pid, worker_start: procStart(process.pid) });
31
+ registerSelf("worker", nodeId);
32
+ // The worker runs detached (dispatch.ts), so it leads its own session and group: record its pid
33
+ // as a launched leader for the run's lifetime, so a process left in its group or session is
34
+ // placed inside the launched tree even after the worker has died (src/core/presence.ts).
35
+ recordLaunchLeader(node.run_id, process.pid, "worker", nodeId);
36
+ const stop = () => {
37
+ if (terminating)
38
+ return;
39
+ terminating = true;
40
+ // Once its turns have ended, the session loop records them (each turn cancelled, the node
41
+ // settled, the worker's claim let go) and the worker ends by itself when nothing is left to do,
42
+ // its writes included. The timer is only a ceiling, for whatever might still hold the process
43
+ // open, and does not itself keep it open.
44
+ void cancelActiveTurns().then(() => setTimeout(() => process.exit(0), 300).unref());
45
+ };
46
+ process.on("SIGTERM", stop);
47
+ process.on("SIGINT", stop);
48
+ const cancelCheck = () => terminating || isCancelled(nodeId);
49
+ try {
50
+ // Fail the queued turns before recording prompts or errors that could contain root values.
51
+ // Housekeeping still runs below, with diagnostic writes withheld if this claim fails.
52
+ await workerRedaction(nodeId);
53
+ redactionReady = true;
54
+ // Only sessions have workers. A discussion or a review is a record that its caller advances.
55
+ if (node.kind !== "job" && node.kind !== "thread" && node.kind !== "participant")
56
+ throw new Error(`a ${node.kind} has no worker`);
57
+ await sessionWorker(nodeId, cancelCheck);
58
+ }
59
+ catch (err) {
60
+ // What a person can act on when the control directory is full or not writable; otherwise the
61
+ // stack. No turn of the session is left marked running or queued with no worker to run it.
62
+ const problem = redactionReady ? storageProblem(err, "the session's worker stopped there") : null;
63
+ const error = redactionReady ? redact(problem ? `${problem}.` : `worker error: ${err.stack ?? err}`)
64
+ : "the owning root's environment broker could not supply worker redaction values: restart the root, or on a shared relay call relay again from the conversation that owns this run, before resuming";
65
+ // Together, as a turn's end is recorded with its session's (outcome.ts finishTurn).
66
+ tx(() => {
67
+ closeTurns(nodeId, "failed", error);
68
+ finishNode(nodeId, "failed", { error, worker_pid: null });
69
+ });
70
+ }
71
+ // With its session's turns done (not before, which would hold them up), at most once a day: the
72
+ // sweep of relay's leftover temporary directories, and old runs' records where keep_records_days
73
+ // is set. Retention is the person's policy now, not the run's when it began: their config as it is.
74
+ // Not on the way out after a stop.
75
+ try {
76
+ if (!terminating)
77
+ await housekeepDaily(loadConfig());
78
+ }
79
+ catch (err) {
80
+ console.error(`relay: housekeeping was not done: ${err.message}`);
81
+ }
82
+ }
83
+ async function sessionWorker(nodeId, cancelCheck) {
84
+ for (;;) {
85
+ // Releasing ownership and finding the inbox empty happen in one transaction, so a message
86
+ // queued at the same moment either is seen here or finds no live worker and starts a new one.
87
+ const turn = tx(() => {
88
+ const t = cancelCheck() ? undefined : nextOverlayTurn(nodeId) ?? nextQueuedTurn(nodeId);
89
+ if (!t) {
90
+ updateNode(nodeId, { worker_pid: null, worker_start: null });
91
+ // Requeued for a turn that was cancelled before it ran, the node is not left queued.
92
+ if (!cancelCheck())
93
+ settleIdle(nodeId);
94
+ }
95
+ return t;
96
+ });
97
+ if (!turn) {
98
+ // Leaving because of a cancel must not strand the node as queued with no worker.
99
+ if (cancelCheck())
100
+ finishNode(nodeId, "cancelled");
101
+ return;
102
+ }
103
+ const node = getNode(nodeId);
104
+ const cfg = runConfig(node.run_id);
105
+ db().prepare("UPDATE nodes SET status = 'queued', ended_at = NULL WHERE id = ? AND status != 'cancelled'").run(nodeId);
106
+ const o = await runSessionTurn(nodeId, turn.id, turn.body, turn.access, node.kind === "job" ? cfg.job_timeout_s : cfg.turn_timeout_s, cancelCheck);
107
+ // Cancelled while it waited for a slot: nothing ran, so nothing is recorded.
108
+ if (o.skipped)
109
+ continue;
110
+ // What the turn produced is recorded, and the session goes on to its next turn or settles, in one transaction.
111
+ finishTurn(node, turn, o, cfg);
112
+ }
113
+ }