@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,310 @@
1
+ // A conservative recognizer, not a shell evaluator. False positives ask the person; aliases,
2
+ // script files and names constructed at runtime still depend on the host's permission system.
3
+ import path from "node:path";
4
+ import { canonical, RELAY_CLI } from "./config.js";
5
+ const NEVER_RUN_ARGUMENTS = new Set(["cat", "cd", "echo", "file", "grep", "head", "ls", "printf", "pwd", "stat", "tail", "wc"]);
6
+ const ASSIGNMENT = /^[A-Za-z_][A-Za-z_0-9]*=/;
7
+ // An interpreter named in command position reads a program relay cannot see — from stdin when a
8
+ // pipe feeds it, or from an inline-code flag — so such a command position fails closed.
9
+ // sed/awk/xargs are left out: they can run commands too, but flagging every `… | sed -n …` or
10
+ // `… | xargs wc -l` is noise, and the structural terminal check is the real boundary.
11
+ const INTERPRETER = /^(?:sh|bash|zsh|dash|ksh|fish|rc|python[0-9.]*|perl|ruby|node|deno|bun|osascript|tclsh|lua|php)$/;
12
+ // Per-interpreter inline-code flags. Shells (sh/bash/zsh/dash/ksh/fish/rc) are deliberately absent:
13
+ // their `-c <string>` argument is shell that the word recursion below already parses, and Codex runs
14
+ // every command as `/bin/zsh -lc '<cmd>'`, so flagging a shell `-c` would make every Codex command
15
+ // person-only. Each entry is single-dash letters that carry code and exact long flags.
16
+ const CODE_FLAGS = [
17
+ { match: (n) => /^python[0-9.]*$/.test(n), letters: "c" },
18
+ { match: (n) => n === "perl", letters: "eE" },
19
+ { match: (n) => n === "ruby", letters: "e" },
20
+ { match: (n) => n === "node", letters: "ep", long: ["--eval", "--print"] },
21
+ { match: (n) => n === "osascript", letters: "e" },
22
+ { match: (n) => n === "php", letters: "r" },
23
+ { match: (n) => n === "lua", letters: "e" },
24
+ { match: (n) => n === "bun", letters: "e", long: ["--eval"] },
25
+ ];
26
+ /**
27
+ * Whether words give the named interpreter code to run inline (so relay cannot see the program).
28
+ * A single-dash word counts when one of the interpreter's code letters is in its leading letter
29
+ * cluster, whatever follows (`-c`, `-ec`, and code attached to its flag such as `-cprint(1)` or
30
+ * `-eprint 1`); a long flag counts as itself or with `=value` (`--eval=…`).
31
+ */
32
+ function hasInlineCode(name, words) {
33
+ if (name === "deno")
34
+ return words.includes("eval"); // deno's `eval` subcommand
35
+ const spec = CODE_FLAGS.find((s) => s.match(name));
36
+ if (!spec)
37
+ return false;
38
+ return words.some((w) => {
39
+ if (spec.long?.some((l) => w === l || w.startsWith(`${l}=`)))
40
+ return true;
41
+ const cluster = /^-([A-Za-z]+)/.exec(w)?.[1];
42
+ return cluster !== undefined && [...spec.letters].some((l) => cluster.includes(l));
43
+ });
44
+ }
45
+ // Commands that run another command they are given, after their own options: the real command name
46
+ // is the first word past them (and their option values). Resolved before the interpreter test so
47
+ // `… | env FOO=1 sh` and `… | nice -n 5 bash` are seen as sh and bash.
48
+ const WRAPPERS = new Set(["env", "command", "builtin", "exec", "nohup", "time", "timeout", "nice", "stdbuf", "setsid", "ionice", "caffeinate", "arch", "sudo"]);
49
+ // Option arity for the wrappers whose options take a value, so a value is not mistaken for the
50
+ // wrapped command (`env -u NAME sh` is sh, not NAME). An unrecognised option on one of these —
51
+ // including a `--name=value` / `-o=value` whose name is not one of its value options — fails closed
52
+ // rather than guess (defence in depth; the word recursion still catches an explicit relay).
53
+ const WRAPPER_ARITY = {
54
+ env: { value: new Set(["-u", "-C", "-S", "-P", "--unset", "--chdir", "--split-string"]), novalue: new Set(["-i", "-0", "-v", "--ignore-environment", "--null", "--debug"]) },
55
+ timeout: { value: new Set(["-s", "-k", "--signal", "--kill-after"]), novalue: new Set(["-v", "-f", "-p", "--verbose", "--foreground", "--preserve-status"]) },
56
+ stdbuf: { value: new Set(["-i", "-o", "-e", "--input", "--output", "--error"]), novalue: new Set() },
57
+ nice: { value: new Set(["-n", "--adjustment"]), novalue: new Set() },
58
+ sudo: { value: new Set(["-u", "-g", "-C", "-D", "-R", "-p", "-T", "-U"]), novalue: new Set(["-b", "-E", "-H", "-i", "-K", "-k", "-l", "-n", "-P", "-S", "-s", "-V", "-v", "-A", "-e", "-r"]) },
59
+ exec: { value: new Set(["-a"]), novalue: new Set(["-c", "-l"]) },
60
+ };
61
+ // Glob metacharacters in command position: the name is a pattern the shell expands to whatever
62
+ // matches (a `rela?` could be `relay`), so relay cannot establish the command and fails closed.
63
+ const COMMAND_GLOB = /[*?[]/;
64
+ /**
65
+ * The real command name a simple command runs: the first non-assignment word past any wrappers and
66
+ * their options/values. `fail` means a wrapper option could not be classified, so command position
67
+ * cannot be established and the caller fails closed. `name` is undefined when there is no command word.
68
+ */
69
+ function commandName(words) {
70
+ for (let i = 0; i < words.length; i++) {
71
+ const w = words[i];
72
+ if (ASSIGNMENT.test(w))
73
+ continue;
74
+ const base = path.basename(w.replace(/^[+!|]+/, ""));
75
+ if (WRAPPERS.has(base)) {
76
+ const arity = WRAPPER_ARITY[base];
77
+ // Consume this wrapper's options (and the values of value-taking ones) up to the wrapped command.
78
+ while (i + 1 < words.length) {
79
+ const opt = words[i + 1];
80
+ if (ASSIGNMENT.test(opt)) {
81
+ i++;
82
+ continue;
83
+ } // env VAR=val
84
+ if (opt === "--") {
85
+ // End of the wrapper's options: what follows is the command (after timeout's DURATION),
86
+ // even a word that starts with "-".
87
+ i++;
88
+ const after = words[i + 1];
89
+ if (after !== undefined && after.startsWith("-"))
90
+ return { name: path.basename(after) };
91
+ break;
92
+ }
93
+ if (!opt.startsWith("-") || opt === "-")
94
+ break; // the wrapped command (or a positional like timeout's DURATION)
95
+ if (!arity) {
96
+ i++;
97
+ continue;
98
+ } // wrapper with no value-taking options: skip the flag
99
+ if (opt.includes("=")) {
100
+ // --name=value or -o=value, one token: only a known value option of this wrapper.
101
+ if (arity.value.has(opt.slice(0, opt.indexOf("=")))) {
102
+ i++;
103
+ continue;
104
+ }
105
+ return { fail: true };
106
+ }
107
+ if (base === "nice" && /^-\d+$/.test(opt)) {
108
+ i++;
109
+ continue;
110
+ } // legacy `nice -10 cmd`
111
+ if (arity.value.has(opt)) {
112
+ i += 2;
113
+ continue;
114
+ } // -u NAME
115
+ if (!opt.startsWith("--") && opt.length > 2 && arity.value.has(opt.slice(0, 2))) {
116
+ i++;
117
+ continue;
118
+ } // -uNAME attached
119
+ if (arity.novalue.has(opt) || (!opt.startsWith("--") && opt.length > 2 && [...opt.slice(1)].every((c) => arity.novalue.has("-" + c)))) {
120
+ i++;
121
+ continue;
122
+ } // -i / bundled -bES
123
+ return { fail: true }; // unclassifiable option on a known wrapper: fail closed
124
+ }
125
+ continue;
126
+ }
127
+ if (w.startsWith("-") || /^\d+$/.test(w))
128
+ continue; // a wrapper's leftover option or numeric positional
129
+ return { name: base };
130
+ }
131
+ return {};
132
+ }
133
+ /** Shell words, simple commands and substitutions. null means the syntax cannot be established. */
134
+ function splitShell(text) {
135
+ const commands = [], substitutions = [];
136
+ let words = [], word = "", started = false, quote = "", piped = false;
137
+ const endWord = () => { if (started)
138
+ words.push(word); word = ""; started = false; };
139
+ // `nextPiped` says whether the command that follows this separator reads a pipe (`|` or `|&`).
140
+ const endCommand = (nextPiped = false) => { endWord(); if (words.length)
141
+ commands.push({ words, piped }); words = []; piped = nextPiped; };
142
+ for (let i = 0; i < text.length; i++) {
143
+ const c = text[i];
144
+ if (c === "\\" && quote !== "'") {
145
+ if (++i >= text.length)
146
+ return null;
147
+ if (text[i] !== "\n") {
148
+ word += text[i];
149
+ started = true;
150
+ }
151
+ continue;
152
+ }
153
+ if (quote === "'") {
154
+ if (c === "'")
155
+ quote = "";
156
+ else
157
+ word += c;
158
+ continue;
159
+ }
160
+ if (c === "`" || (c === "$" && text[i + 1] === "(")) {
161
+ const backtick = c === "`";
162
+ const start = i + (backtick ? 1 : 2);
163
+ let depth = 1, innerQuote = "", j = start;
164
+ for (; j < text.length; j++) {
165
+ const t = text[j];
166
+ if (t === "\\" && innerQuote !== "'") {
167
+ j++;
168
+ continue;
169
+ }
170
+ if (backtick && t === "`")
171
+ break;
172
+ if (innerQuote) {
173
+ if (t === innerQuote)
174
+ innerQuote = "";
175
+ continue;
176
+ }
177
+ if (t === "'" || t === '"' || t === "`") {
178
+ innerQuote = t;
179
+ continue;
180
+ }
181
+ if (!backtick && t === "(")
182
+ depth++;
183
+ if (!backtick && t === ")" && --depth === 0)
184
+ break;
185
+ }
186
+ if (j === text.length)
187
+ return null;
188
+ substitutions.push(text.slice(start, j));
189
+ i = j;
190
+ started = true;
191
+ continue;
192
+ }
193
+ if (quote === '"') {
194
+ if (c === '"')
195
+ quote = "";
196
+ else
197
+ word += c;
198
+ continue;
199
+ }
200
+ if (c === "'" || c === '"') {
201
+ quote = c;
202
+ started = true;
203
+ continue;
204
+ }
205
+ if (c === "#" && !started) {
206
+ while (i < text.length && text[i] !== "\n")
207
+ i++;
208
+ endCommand();
209
+ continue;
210
+ }
211
+ if (c === "<" && text[i + 1] === "<")
212
+ return null; // here-documents/strings: fail closed
213
+ if (c === "|") {
214
+ // `|` and `|&` pipe into the next command; `||` is logical OR, not a pipe.
215
+ if (text[i + 1] === "|") {
216
+ i++;
217
+ endCommand(false);
218
+ }
219
+ else {
220
+ if (text[i + 1] === "&")
221
+ i++;
222
+ endCommand(true);
223
+ }
224
+ continue;
225
+ }
226
+ if (c === "&") {
227
+ if (text[i + 1] === "&")
228
+ i++;
229
+ endCommand(false);
230
+ continue;
231
+ } // `&&` and background `&`
232
+ if (c === ";" || c === "(" || c === ")") {
233
+ endCommand(false);
234
+ continue;
235
+ }
236
+ if (c === "\n") {
237
+ // A newline right after a pipe (possibly across blank space) continues the pipeline, so the
238
+ // command after it still reads the pipe; otherwise it ends the command.
239
+ if (piped && !started && !words.length)
240
+ continue;
241
+ endCommand(false);
242
+ continue;
243
+ }
244
+ if (/\s/.test(c)) {
245
+ endWord();
246
+ continue;
247
+ }
248
+ word += c;
249
+ started = true;
250
+ }
251
+ if (quote)
252
+ return null;
253
+ endCommand();
254
+ return { commands, substitutions };
255
+ }
256
+ /** Argument vectors are inspected as vectors, never joined and reparsed. */
257
+ export function runsRelayCommand(command, cwd = process.cwd(), depth = 0) {
258
+ if (depth > 16 || (typeof command === "string" && command.length > 100_000))
259
+ return true;
260
+ const inspectWords = ({ words, piped }) => {
261
+ const first = words.find((w) => !ASSIGNMENT.test(w));
262
+ // The command actually run, past any wrappers, for the interpreter tests.
263
+ const { name, fail } = commandName(words);
264
+ // Defence in depth (brief, 2026-10-27): a command position relay cannot pin down fails closed,
265
+ // before the never-run exemption, so neither obfuscation gets through here.
266
+ // - a wrapper option whose value could not be classified (so the command word is uncertain);
267
+ if (fail)
268
+ return true;
269
+ // - a glob in the command name (literal first word or the resolved command);
270
+ if ((first && COMMAND_GLOB.test(first)) || (name && COMMAND_GLOB.test(name)))
271
+ return true;
272
+ // - an interpreter fed by a pipe (reads its program from stdin), or given inline code we do not parse.
273
+ if (name && INTERPRETER.test(name) && (piped || hasInlineCode(name, words)))
274
+ return true;
275
+ if (first && NEVER_RUN_ARGUMENTS.has(path.basename(first)))
276
+ return false;
277
+ return words.some((w) => {
278
+ const value = /^(?:--[^=]+|[A-Za-z_][A-Za-z_0-9]*)=(.*)$/s.exec(w)?.[1];
279
+ const candidate = (value ?? w).replace(/^[+!|]+/, "");
280
+ if (path.basename(candidate) === "relay" || canonical(path.resolve(cwd, candidate)) === canonical(RELAY_CLI))
281
+ return true;
282
+ return /[\s;&|()$`]/.test(candidate) && runsRelayCommand(candidate, cwd, depth + 1);
283
+ });
284
+ };
285
+ if (typeof command !== "string")
286
+ return inspectWords({ words: [...command], piped: false });
287
+ const split = splitShell(command);
288
+ return !split || split.substitutions.some((s) => runsRelayCommand(s, cwd, depth + 1)) || split.commands.some(inspectWords);
289
+ }
290
+ /**
291
+ * Requests retain the target's command identity: ACP argv wins over its ambiguous summary, and a
292
+ * Codex command whose summary also names the access it asks to add (codex-app.ts commandAsk) is
293
+ * read from the command it gave alone.
294
+ */
295
+ export function requestRunsRelayCommand(r, cwd) {
296
+ if (r.kind !== "command")
297
+ return false;
298
+ let detail;
299
+ try {
300
+ detail = JSON.parse(r.detail_json ?? "{}");
301
+ }
302
+ catch {
303
+ return true;
304
+ }
305
+ if (!detail || typeof detail !== "object")
306
+ return true;
307
+ const command = Array.isArray(detail.argv) && detail.argv.length && detail.argv.every((v) => typeof v === "string") ? detail.argv
308
+ : typeof detail.command === "string" ? detail.command : r.summary;
309
+ return runsRelayCommand(command, typeof detail.cwd === "string" ? detail.cwd : cwd);
310
+ }
@@ -0,0 +1,3 @@
1
+ // Internal snapshot carried through result spreads, but omitted by JSON.stringify. Naming an
2
+ // item is not evidence that a result reports its completion (pending handles and run listings).
3
+ export const REPORTED_COMPLETION = Symbol("reported completion");