@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.
- package/LICENSE +21 -0
- package/LICENSES/Apache-2.0.txt +201 -0
- package/LICENSES/README.md +19 -0
- package/LICENSES/codex-NOTICE.txt +6 -0
- package/README.md +386 -2
- package/SECURITY.md +145 -0
- package/adapters/briefs/claude.md +43 -0
- package/adapters/briefs/codex.md +56 -0
- package/adapters/briefs/models.json +33 -0
- package/adapters/build.mjs +8 -0
- package/adapters/claude/.claude-plugin/marketplace.json +13 -0
- package/adapters/claude/relay/.claude-plugin/plugin.json +5 -0
- package/adapters/claude/relay/agents/codex.md +21 -0
- package/adapters/claude/relay/agents/operator.md +21 -0
- package/adapters/claude/relay/skills/ask/SKILL.md +20 -0
- package/adapters/claude/relay/skills/chat/SKILL.md +13 -0
- package/adapters/claude/relay/skills/delegate/SKILL.md +21 -0
- package/adapters/claude/relay/skills/discuss/SKILL.md +19 -0
- package/adapters/claude/relay/skills/review/SKILL.md +21 -0
- package/adapters/claude/relay/skills/tree/SKILL.md +10 -0
- package/adapters/claude/relay/skills/write-for-codex/SKILL.md +78 -0
- package/adapters/codex/.agents/plugins/marketplace.json +20 -0
- package/adapters/codex/AGENTS.snippet.md +5 -0
- package/adapters/codex/relay/.codex-plugin/plugin.json +6 -0
- package/adapters/codex/relay/skills/relay-ask/SKILL.md +20 -0
- package/adapters/codex/relay/skills/relay-chat/SKILL.md +13 -0
- package/adapters/codex/relay/skills/relay-delegate/SKILL.md +21 -0
- package/adapters/codex/relay/skills/relay-discuss/SKILL.md +19 -0
- package/adapters/codex/relay/skills/relay-review/SKILL.md +21 -0
- package/adapters/codex/relay/skills/relay-tree/SKILL.md +10 -0
- package/adapters/codex/relay/skills/relay-write-for-claude/SKILL.md +66 -0
- package/adapters/generate.mjs +124 -0
- package/bin/relay +59 -0
- package/codex-pin.json +12 -0
- package/dist/backends/acp.js +1424 -0
- package/dist/backends/claude.js +890 -0
- package/dist/backends/cli-version.js +112 -0
- package/dist/backends/codex-app.js +1525 -0
- package/dist/backends/codex-daybreak.js +75 -0
- package/dist/backends/codex-env.js +656 -0
- package/dist/backends/codex-network.js +304 -0
- package/dist/backends/codex-pin.js +320 -0
- package/dist/backends/codex-shell-policy.js +182 -0
- package/dist/backends/codex-stage2.js +998 -0
- package/dist/backends/codex-subagents.js +47 -0
- package/dist/backends/codex.js +637 -0
- package/dist/backends/copilot.js +246 -0
- package/dist/backends/env.js +147 -0
- package/dist/backends/gemini.js +607 -0
- package/dist/backends/grok.js +337 -0
- package/dist/backends/index.js +8 -0
- package/dist/backends/native-temp.js +187 -0
- package/dist/backends/never-admission.js +90 -0
- package/dist/backends/run.js +67 -0
- package/dist/backends/stream.js +230 -0
- package/dist/backends/tool-discovery.js +15 -0
- package/dist/backends/types.js +264 -0
- package/dist/build-info.json +5 -0
- package/dist/cli.js +344 -0
- package/dist/confine/bridge.js +113 -0
- package/dist/confine/broker-core.js +76 -0
- package/dist/confine/broker-http.js +650 -0
- package/dist/confine/broker-names.js +9 -0
- package/dist/confine/broker.js +258 -0
- package/dist/confine/canary.js +380 -0
- package/dist/confine/diagnostics.js +122 -0
- package/dist/confine/gemini-tools-main.js +8 -0
- package/dist/confine/gemini-tools.js +181 -0
- package/dist/confine/hardlinks.js +58 -0
- package/dist/confine/harness-config.js +16 -0
- package/dist/confine/index.js +117 -0
- package/dist/confine/leases.js +217 -0
- package/dist/confine/paths.js +6 -0
- package/dist/confine/peer.js +115 -0
- package/dist/confine/port-policy.js +8 -0
- package/dist/confine/ports.js +365 -0
- package/dist/confine/private-root.js +208 -0
- package/dist/confine/probe-stage2.js +501 -0
- package/dist/confine/probe.js +1109 -0
- package/dist/confine/proxy.js +783 -0
- package/dist/confine/sbcheck.js +208 -0
- package/dist/confine/seatbelt-never.js +41 -0
- package/dist/confine/seatbelt-stage2.js +139 -0
- package/dist/confine/seatbelt.js +1129 -0
- package/dist/confine/sockets.js +36 -0
- package/dist/confine/turn-probe.js +19 -0
- package/dist/confine/turn.js +86 -0
- package/dist/core/adoption.js +124 -0
- package/dist/core/api-keys.js +423 -0
- package/dist/core/approvals.js +740 -0
- package/dist/core/build-identity.js +248 -0
- package/dist/core/caller.js +749 -0
- package/dist/core/calls.js +102 -0
- package/dist/core/claude-settings.js +1045 -0
- package/dist/core/config.js +453 -0
- package/dist/core/context.js +186 -0
- package/dist/core/db.js +753 -0
- package/dist/core/dispatch.js +110 -0
- package/dist/core/env-broker.js +505 -0
- package/dist/core/env-policy.js +182 -0
- package/dist/core/escalation-authority.js +76 -0
- package/dist/core/escalation-contract.js +13 -0
- package/dist/core/escalation-person-path.js +131 -0
- package/dist/core/escalation-policy.js +79 -0
- package/dist/core/escalation-runtime.js +135 -0
- package/dist/core/escalation-state.js +42 -0
- package/dist/core/escalations.js +191 -0
- package/dist/core/events.js +235 -0
- package/dist/core/executables.js +147 -0
- package/dist/core/extensions.js +645 -0
- package/dist/core/families.js +204 -0
- package/dist/core/git.js +657 -0
- package/dist/core/identity.js +113 -0
- package/dist/core/liveness.js +68 -0
- package/dist/core/mediated-network-provider.js +81 -0
- package/dist/core/never-checkpoint.js +76 -0
- package/dist/core/never-coverage.js +97 -0
- package/dist/core/never-network.js +49 -0
- package/dist/core/never-policy.js +302 -0
- package/dist/core/never-proxy-policy.js +109 -0
- package/dist/core/never-schema.js +61 -0
- package/dist/core/never-tools.js +56 -0
- package/dist/core/notices.js +48 -0
- package/dist/core/ops.js +959 -0
- package/dist/core/outcome.js +224 -0
- package/dist/core/params.js +32 -0
- package/dist/core/presence.js +174 -0
- package/dist/core/procs.js +546 -0
- package/dist/core/prompts.js +363 -0
- package/dist/core/protected-config.js +238 -0
- package/dist/core/raw-network.js +192 -0
- package/dist/core/redact.js +152 -0
- package/dist/core/refusal.js +33 -0
- package/dist/core/relay-command.js +310 -0
- package/dist/core/reported.js +3 -0
- package/dist/core/restart-overlay.js +651 -0
- package/dist/core/retention.js +1135 -0
- package/dist/core/secrets.js +329 -0
- package/dist/core/session-token.js +175 -0
- package/dist/core/session.js +744 -0
- package/dist/core/shell.js +2 -0
- package/dist/core/shipped-pin.js +47 -0
- package/dist/core/shown.js +42 -0
- package/dist/core/slots.js +67 -0
- package/dist/core/stage2-executors.js +453 -0
- package/dist/core/stage2-switch.js +5 -0
- package/dist/core/steering.js +149 -0
- package/dist/core/storage.js +358 -0
- package/dist/core/toml.js +175 -0
- package/dist/core/views.js +324 -0
- package/dist/core/wait.js +114 -0
- package/dist/core/wake.js +207 -0
- package/dist/core/watch.js +247 -0
- package/dist/core/worktree.js +213 -0
- package/dist/hosts/claude-desktop.js +274 -0
- package/dist/hosts/claude.js +249 -0
- package/dist/hosts/codex.js +329 -0
- package/dist/hosts/desktop-shared.js +20 -0
- package/dist/hosts/index.js +11 -0
- package/dist/hosts/types.js +4 -0
- package/dist/install/basics.js +18 -0
- package/dist/install/claude-init.js +133 -0
- package/dist/install/common.js +655 -0
- package/dist/install/doctor.js +629 -0
- package/dist/install/qualify-codex.js +205 -0
- package/dist/install.js +524 -0
- package/dist/mcp/elicit.js +209 -0
- package/dist/mcp/gateway.js +218 -0
- package/dist/mcp/host.js +253 -0
- package/dist/mcp/server.js +1124 -0
- package/dist/mcp/stdio.js +37 -0
- package/dist/modes/discussion.js +393 -0
- package/dist/modes/review.js +722 -0
- package/dist/native/relay-sbcheck +0 -0
- package/dist/targets/briefs.js +86 -0
- package/dist/targets/claude.js +94 -0
- package/dist/targets/codex.js +66 -0
- package/dist/targets/copilot.js +93 -0
- package/dist/targets/gemini.js +119 -0
- package/dist/targets/grok.js +126 -0
- package/dist/targets/index.js +192 -0
- package/dist/targets/types.js +18 -0
- package/dist/targets/verified.js +35 -0
- package/dist/worker.js +113 -0
- package/docs/UPGRADING.md +1502 -0
- package/docs/pinned-codex.md +321 -0
- package/experiments/stage2-redteam/lib/oracles.mjs +214 -0
- package/experiments/stage2-redteam/lib/report.mjs +35 -0
- package/npm-shrinkwrap.json +1632 -0
- package/package.json +82 -4
- package/scripts/codex-qualify/codex-pin-store.mjs +353 -0
- package/scripts/codex-qualify/codex-qualifier-process.mjs +265 -0
- package/scripts/codex-qualify/codex-qualifier.example.json +5 -0
- package/scripts/codex-qualify/codex-qualifier.mjs +281 -0
- package/scripts/codex-qualify/codex-shipped-pin.mjs +158 -0
- package/scripts/codex-qualify/codex-stage2-pin.mjs +48 -0
- package/scripts/codex-qualify/codex-stage2.mjs +2381 -0
- package/scripts/codex-qualify/install-codex-qualifier.mjs +98 -0
- package/scripts/codex-qualify/main-module.mjs +14 -0
- package/scripts/codex-qualify/relay-codex-qualifier.plist +37 -0
- package/scripts/codex-qualify/scratch-env.mjs +31 -0
- package/scripts/codex-qualify/session.mjs +96 -0
- package/scripts/codex-qualify/stage2-escalation-cases.mjs +125 -0
- package/test/codex-permissions.test.ts +875 -0
- package/test/fixtures/boundary-probes.mjs +17 -0
- package/test/fixtures/denial-stream-host.mjs +7 -0
- package/test/fixtures/families.json +246 -0
- package/test/fixtures/install-snapshots/claude-desktop-foreign.txt +158 -0
- package/test/fixtures/install-snapshots/claude-desktop-fresh.txt +101 -0
- package/test/fixtures/install-snapshots/claude-desktop-installed.txt +161 -0
- package/test/fixtures/install-snapshots/claude-foreign.txt +133 -0
- package/test/fixtures/install-snapshots/claude-fresh.txt +77 -0
- package/test/fixtures/install-snapshots/claude-installed.txt +133 -0
- package/test/fixtures/install-snapshots/codex-foreign.txt +159 -0
- package/test/fixtures/install-snapshots/codex-fresh.txt +107 -0
- package/test/fixtures/install-snapshots/codex-installed.txt +161 -0
- package/test/fixtures/link-parent.mjs +6 -0
- package/test/fixtures/mediated-command.cjs +72 -0
- package/test/fixtures/native-skill-isolation.json +280 -0
- package/test/fixtures/pinned-codex-app-server.mjs +25 -0
- package/test/fixtures/qualified-ext-adapters.mjs +36 -0
- package/test/fixtures/refusals/README.md +52 -0
- package/test/fixtures/refusals/claude-source-result.json +7 -0
- package/test/fixtures/refusals/openai-app-capacity.json +24 -0
- package/test/fixtures/refusals/openai-app-cyberPolicy.json +24 -0
- package/test/fixtures/refusals/openai-gpt-6-astra-max.json +12 -0
- package/test/fixtures/refusals/openai-gpt-6.1-sol-xhigh.json +12 -0
- package/test/fixtures/refusals/openai-review-capacity.json +24 -0
- package/test/fixtures/relay-0.2.0.sql +57 -0
- package/test/fixtures/relay-0.9.1.gen.mjs +212 -0
- package/test/fixtures/relay-0.9.1.sql +340 -0
- package/test/fixtures/slow-boundary-probes.mjs +37 -0
- package/test/fixtures/stable-surfaces/config.json +1122 -0
- package/test/fixtures/stable-surfaces/escalation.json +128 -0
- package/test/fixtures/stable-surfaces/events.json +37 -0
- package/test/fixtures/stable-surfaces/gemini-native-resume.json +4 -0
- package/test/fixtures/stable-surfaces/inbox.jsonl +2 -0
- package/test/fixtures/stable-surfaces/notice.txt +1 -0
- package/test/fixtures/stable-surfaces/refusal-item.json +28 -0
- package/test/fixtures/stable-surfaces/refusal-review.json +23 -0
- package/test/fixtures/stable-surfaces/registry.json +49 -0
- package/test/fixtures/stable-surfaces/tools-desktop.json +575 -0
- package/test/fixtures/stable-surfaces/tools.json +716 -0
- package/test/fixtures/stable-surfaces/usage.txt +46 -0
- package/test/fixtures/stage2-acp-native.mjs +138 -0
- package/test/fixtures/stage2-app-server.mjs +23 -0
- package/test/fixtures/stage2-catalog.json +91 -0
- package/test/fixtures/stage2-hostile-web.mjs +35 -0
- package/test/fixtures/stage2-native-network.mjs +62 -0
- package/test/fixtures/stage2-worker.ts +87 -0
- package/test/fixtures/status-views/expected.json +7825 -0
- package/test/fixtures/status-views/registries.json +1 -0
- package/test/fixtures/steering.json +209 -0
- package/test/helpers.ts +740 -0
- package/test/host-env.ts +7 -0
- package/test/keychain-decoy.ts +197 -0
- package/test/live-scope.ts +44 -0
- package/test/mediated-network.test.ts +192 -0
- package/test/mediated-proxy.test.ts +264 -0
- package/test/native-temp-alias.ts +10 -0
- package/test/never-policy.test.ts +629 -0
- package/test/never-tools.test.ts +136 -0
- package/test/process-home.ts +18 -0
- package/test/proxy.test.ts +531 -0
- package/test/restart-overlay-live.test.ts +85 -0
- package/test/restart-overlay-profile.test.ts +66 -0
- package/test/restart-overlay.test.ts +416 -0
- package/test/stable-surfaces.test.ts +249 -0
- package/test/stage2-escalation-live.test.ts +544 -0
- package/test/stage2-escalation-qualification.test.ts +170 -0
- package/test/stage2-escalation.test.ts +747 -0
- package/test/stage2-executor.test.ts +849 -0
- package/test/stage2-grant.test.ts +603 -0
- package/test/stage2-native-live.test.ts +647 -0
- package/test/stage2-network-decisions.test.ts +70 -0
- package/test/stage2-probe.test.ts +845 -0
- package/test/stage2-standing-live.test.ts +203 -0
- package/test/stubs/broker-host.mjs +59 -0
- package/test/stubs/broker-peer.mjs +20 -0
- package/test/stubs/confined-harness.mjs +91 -0
- package/test/stubs/ext-broken-server.mjs +2 -0
- package/test/stubs/ext-odd-server.mjs +21 -0
- package/test/stubs/ext-server.mjs +31 -0
- package/test/stubs/fake-host-cli.mjs +218 -0
- package/test/stubs/procargs.mjs +30 -0
- package/test/stubs/stub-acp +4 -0
- package/test/stubs/stub-agent.mjs +322 -0
- package/test/stubs/stub-claude +4 -0
- package/test/stubs/stub-codex +4 -0
- package/test/stubs/targets/acp.mjs +307 -0
- package/test/stubs/targets/claude.mjs +149 -0
- package/test/stubs/targets/codex.mjs +479 -0
- package/test/stubs/targets/gemini.mjs +604 -0
- package/test/temp-root.ts +11 -0
- package/test/wp4-adapters.test.ts +353 -0
- package/test/wp4-interlock.test.ts +136 -0
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import { sendGroupSignal } from "../core/procs.js";
|
|
3
|
+
/**
|
|
4
|
+
* Streams the kernel's Seatbelt denials for one confined turn into a callback, so a harness that
|
|
5
|
+
* cannot work inside the profile says which rule stopped it (srt does this). Every turn's profile
|
|
6
|
+
* puts the turn's tag on its `(deny default)` rule (seatbelt.ts, `diagnosticTag`), and the kernel
|
|
7
|
+
* appends that tag to each denial it logs; `log stream` is asked for just the denials carrying it.
|
|
8
|
+
* The stream holds no authority and reads only the system log; a failure to start it is swallowed,
|
|
9
|
+
* since it is a diagnostic, never part of the boundary.
|
|
10
|
+
*/
|
|
11
|
+
export const LOG = "/usr/bin/log";
|
|
12
|
+
/**
|
|
13
|
+
* Denials every process on the machine raises against the deny-default profile, which say nothing
|
|
14
|
+
* about the harness: lockdown-mode and boot-args reads the system libraries make at startup. They
|
|
15
|
+
* are filtered out so they do not drown the harness's real denials in the log (review C4).
|
|
16
|
+
*/
|
|
17
|
+
const HARMLESS = new Set(["sysctl-read security.mac.lockdown_mode_state", "sysctl-read kern.bootargs"]);
|
|
18
|
+
/**
|
|
19
|
+
* Parses one `log stream` ndjson line. Returns the denial when the line is a Sandbox denial
|
|
20
|
+
* carrying `tag`, else null. The kernel's message reads `Sandbox: <proc>(<pid>) deny(1) <operation>`
|
|
21
|
+
* then a newline and the tag; a run of identical denials is reported once as "N duplicate reports for …".
|
|
22
|
+
*/
|
|
23
|
+
export function parseDenial(line, tag) {
|
|
24
|
+
let msg;
|
|
25
|
+
try {
|
|
26
|
+
const j = JSON.parse(line);
|
|
27
|
+
if (typeof j.eventMessage !== "string")
|
|
28
|
+
return null;
|
|
29
|
+
msg = j.eventMessage;
|
|
30
|
+
}
|
|
31
|
+
catch {
|
|
32
|
+
return null;
|
|
33
|
+
}
|
|
34
|
+
if (!msg.endsWith(`\n${tag}`))
|
|
35
|
+
return null;
|
|
36
|
+
const first = msg.slice(0, msg.length - tag.length - 1).replace(/^\d+ duplicate reports? for /, "");
|
|
37
|
+
const m = /^Sandbox:\s+(\S+)\s+deny\(\d+\)\s+(.*)$/s.exec(first);
|
|
38
|
+
if (!m)
|
|
39
|
+
return null;
|
|
40
|
+
const operation = m[2].replace(/\s+/g, " ").trim();
|
|
41
|
+
if (HARMLESS.has(operation))
|
|
42
|
+
return null;
|
|
43
|
+
return { process: m[1], operation };
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Starts streaming this turn's sandbox denials. `onDenial` is called for each, at most `limit` of
|
|
47
|
+
* them (default 200), so a flood cannot grow the log without bound. Returns a handle to stop it.
|
|
48
|
+
*/
|
|
49
|
+
export function streamSandboxDenials(tag, onDenial, opts = {}) {
|
|
50
|
+
const limit = opts.limit ?? 200;
|
|
51
|
+
let seen = 0;
|
|
52
|
+
let child = null;
|
|
53
|
+
let closed = false;
|
|
54
|
+
let markReady;
|
|
55
|
+
// Resolves when log stream has attached, or after a grace, so the launch never blocks on it.
|
|
56
|
+
const ready = new Promise((resolve) => (markReady = resolve));
|
|
57
|
+
try {
|
|
58
|
+
// log stream runs forever, and a process killed outright (SIGKILL, a crash) runs no cleanup, so a
|
|
59
|
+
// plain child would be orphaned and keep streaming the whole system log. It runs under a small
|
|
60
|
+
// watchdog shell instead, in its own process group: the shell stops it as soon as the process
|
|
61
|
+
// that started it is gone (checked every second), and close() kills the whole group.
|
|
62
|
+
const watchdog = 'P=$1; shift; "$@" & L=$!; trap \'kill $L 2>/dev/null\' TERM INT HUP EXIT; while kill -0 "$P" 2>/dev/null && kill -0 "$L" 2>/dev/null; do /bin/sleep 1; done; kill $L 2>/dev/null';
|
|
63
|
+
child = spawn("/bin/sh", ["-c", watchdog, "sh", String(process.pid), LOG, "stream", "--style", "ndjson", "--predicate", `sender == "Sandbox" AND eventMessage ENDSWITH "${tag}"`], { stdio: ["ignore", "pipe", "ignore"], detached: true });
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
markReady();
|
|
67
|
+
return { ready, close() { } };
|
|
68
|
+
}
|
|
69
|
+
child.on("error", () => markReady());
|
|
70
|
+
// Give log stream a bounded time to attach; the launch waits for this, not forever.
|
|
71
|
+
const graceTimer = setTimeout(markReady, opts.attachMs ?? 2000);
|
|
72
|
+
if (typeof graceTimer.unref === "function")
|
|
73
|
+
graceTimer.unref();
|
|
74
|
+
let buf = "";
|
|
75
|
+
let banner = false;
|
|
76
|
+
child.stdout?.setEncoding("utf8");
|
|
77
|
+
child.stdout?.on("data", (chunk) => {
|
|
78
|
+
// The first output means the stream has attached (log prints a "Filtering the log data…" banner).
|
|
79
|
+
if (!banner) {
|
|
80
|
+
banner = true;
|
|
81
|
+
clearTimeout(graceTimer);
|
|
82
|
+
markReady();
|
|
83
|
+
}
|
|
84
|
+
buf += chunk;
|
|
85
|
+
for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
|
|
86
|
+
const line = buf.slice(0, i);
|
|
87
|
+
buf = buf.slice(i + 1);
|
|
88
|
+
if (seen >= limit)
|
|
89
|
+
continue;
|
|
90
|
+
const d = parseDenial(line, tag);
|
|
91
|
+
if (d) {
|
|
92
|
+
seen++;
|
|
93
|
+
try {
|
|
94
|
+
onDenial(d);
|
|
95
|
+
}
|
|
96
|
+
catch {
|
|
97
|
+
// The sink's problem is not the turn's.
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
});
|
|
102
|
+
return {
|
|
103
|
+
ready,
|
|
104
|
+
close() {
|
|
105
|
+
if (closed)
|
|
106
|
+
return;
|
|
107
|
+
closed = true;
|
|
108
|
+
clearTimeout(graceTimer);
|
|
109
|
+
try {
|
|
110
|
+
// The whole group: the watchdog shell and log stream with it. Only while the shell that
|
|
111
|
+
// leads it is still relay's child, not yet reaped: Node reaps a child and records its exit
|
|
112
|
+
// (exitCode or signalCode) in one step, and until then the pid, and so the group id, cannot
|
|
113
|
+
// be reused. Once reaped, the id may be another process's group, and the stream has gone.
|
|
114
|
+
if (child?.pid && child.exitCode === null && child.signalCode === null)
|
|
115
|
+
sendGroupSignal(child.pid, "SIGKILL");
|
|
116
|
+
}
|
|
117
|
+
catch {
|
|
118
|
+
// Already gone.
|
|
119
|
+
}
|
|
120
|
+
},
|
|
121
|
+
};
|
|
122
|
+
}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
// The entry point a confined Gemini agent's tool discovery runs (backends/gemini.ts writeGeminiShim):
|
|
2
|
+
// `node --no-warnings gemini-tools-main.js <dir> (--list | <tool>)`. It imports gemini-tools.js and
|
|
3
|
+
// nothing else, which imports only node:fs, node:net and node:path, so a call loads nothing of
|
|
4
|
+
// relay's beyond it. Not cli.js, which is relay's every command: should any module it loads before
|
|
5
|
+
// dispatch reach node:sqlite, a Node before 24.15 prints an ExperimentalWarning to stderr on every
|
|
6
|
+
// run, and Gemini 0.64.0 takes any stderr for a failed call.
|
|
7
|
+
import { geminiTools } from "./gemini-tools.js";
|
|
8
|
+
process.exitCode = await geminiTools(process.argv[2], process.argv.slice(3));
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import net from "node:net";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
/**
|
|
5
|
+
* `relay gemini-tools <dir> --list | <tool>`: relay's tools for a Gemini agent, through Gemini's
|
|
6
|
+
* command-based tool discovery (backends/gemini.ts geminiTools), which runs this, inside the turn's
|
|
7
|
+
* sandbox, through the shim `<dir>/call`. Like `relay bridge` (bridge.ts) it holds no authority of
|
|
8
|
+
* its own and opens nothing of relay's but the turn's broker socket: the broker decides every call.
|
|
9
|
+
*
|
|
10
|
+
* - `--list`: prints `<dir>/tools.json`, the turn's tools as Gemini's function declarations, which
|
|
11
|
+
* relay wrote from the broker's own list before Gemini started, and leaves a mark where
|
|
12
|
+
* `<dir>/bridge.json` says (`listed`, in the turn's private temporary directory), which relay checks
|
|
13
|
+
* before the prompt to know that Gemini ran its discovery (backends/gemini.ts geminiDiscoveryCheck).
|
|
14
|
+
* It reads no broker, so the list cannot fail for want of one (a failed discovery would fail
|
|
15
|
+
* Gemini's session setup); a mark it cannot leave fails nothing.
|
|
16
|
+
* - `<tool>`: reads the arguments, a JSON object, from stdin (as Gemini 0.64.0 writes them,
|
|
17
|
+
* tool-registry.ts:111-112), reads the turn's secret from the broker's file that `<dir>/bridge.json`
|
|
18
|
+
* names (which only this turn's sandbox may read), presents it on the socket named there, as the
|
|
19
|
+
* bridge does, then calls the tool over MCP: initialize, initialized,
|
|
20
|
+
* tools/call. The result's text goes to stdout. Gemini reads any stderr, or a non-zero exit, as a
|
|
21
|
+
* failure (:157-173), so stderr is written only then: a tool error, a refusal, or relay not
|
|
22
|
+
* reachable, in which case the agent is told to continue without relay, as the bridge tells it.
|
|
23
|
+
* Every failure says plainly what failed, with the tool's name, and never what the secret is; one
|
|
24
|
+
* that a Gemini release changing how it runs these commands would cause says that it may be that.
|
|
25
|
+
*
|
|
26
|
+
* Deliberately free of imports beyond node's own.
|
|
27
|
+
*/
|
|
28
|
+
/** As the broker's MAX_MESSAGE: arguments larger than this are refused before anything is sent. */
|
|
29
|
+
const MAX_ARGS = 8 * 1024 * 1024;
|
|
30
|
+
/** The MCP protocol version this client asks for (one relay's server speaks). */
|
|
31
|
+
const PROTOCOL = "2025-06-18";
|
|
32
|
+
const fail = (io, text, code = 1) => {
|
|
33
|
+
io.stderr.write(`${text}\n`);
|
|
34
|
+
return code;
|
|
35
|
+
};
|
|
36
|
+
function readAll(stream) {
|
|
37
|
+
return new Promise((resolve, reject) => {
|
|
38
|
+
let size = 0;
|
|
39
|
+
const chunks = [];
|
|
40
|
+
stream.on("data", (c) => {
|
|
41
|
+
const b = typeof c === "string" ? Buffer.from(c) : c;
|
|
42
|
+
size += b.length;
|
|
43
|
+
if (size > MAX_ARGS)
|
|
44
|
+
return reject(new Error(`the arguments are larger than ${MAX_ARGS} bytes`));
|
|
45
|
+
chunks.push(b);
|
|
46
|
+
});
|
|
47
|
+
stream.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
|
|
48
|
+
stream.on("error", reject);
|
|
49
|
+
});
|
|
50
|
+
}
|
|
51
|
+
/** The text of a tool result's content, as an MCP client shows it: text as it is, anything else as JSON. */
|
|
52
|
+
function contentText(result) {
|
|
53
|
+
const content = Array.isArray(result.content) ? result.content : [];
|
|
54
|
+
return content.map((c) => (c && c.type === "text" && typeof c.text === "string" ? c.text : JSON.stringify(c))).join("\n");
|
|
55
|
+
}
|
|
56
|
+
/** Runs one call through the turn's broker; resolves with the tools/call response, or rejects with what went wrong. */
|
|
57
|
+
function callThroughBroker(socketPath, secret, tool, args) {
|
|
58
|
+
return new Promise((resolve, reject) => {
|
|
59
|
+
const sock = net.connect(socketPath);
|
|
60
|
+
let buf = "";
|
|
61
|
+
let settled = false;
|
|
62
|
+
const done = (fn) => {
|
|
63
|
+
if (settled)
|
|
64
|
+
return;
|
|
65
|
+
settled = true;
|
|
66
|
+
sock.destroy();
|
|
67
|
+
fn();
|
|
68
|
+
};
|
|
69
|
+
const send = (m) => sock.write(JSON.stringify({ jsonrpc: "2.0", ...m }) + "\n");
|
|
70
|
+
sock.setEncoding("utf8");
|
|
71
|
+
sock.on("connect", () => {
|
|
72
|
+
// The turn's secret first, as the bridge presents it; the broker serves nothing until it has it.
|
|
73
|
+
sock.write(JSON.stringify({ relay_bridge_secret: secret }) + "\n");
|
|
74
|
+
send({ id: 1, method: "initialize", params: { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: { name: "relay-gemini-tools", version: "1" } } });
|
|
75
|
+
});
|
|
76
|
+
sock.on("data", (chunk) => {
|
|
77
|
+
buf += chunk;
|
|
78
|
+
for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
|
|
79
|
+
const line = buf.slice(0, i).replace(/\r$/, "");
|
|
80
|
+
buf = buf.slice(i + 1);
|
|
81
|
+
if (!line)
|
|
82
|
+
continue;
|
|
83
|
+
let m;
|
|
84
|
+
try {
|
|
85
|
+
m = JSON.parse(line);
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
90
|
+
// A request of the server's (a ping): answered, or refused as a client with no capabilities would.
|
|
91
|
+
if (typeof m.method === "string" && m.id !== undefined) {
|
|
92
|
+
send(m.method === "ping" ? { id: m.id, result: {} } : { id: m.id, error: { code: -32601, message: `relay's Gemini tool client does not provide ${m.method}` } });
|
|
93
|
+
continue;
|
|
94
|
+
}
|
|
95
|
+
if (m.id === 1) {
|
|
96
|
+
if (m.error)
|
|
97
|
+
return done(() => resolve({ error: m.error }));
|
|
98
|
+
send({ method: "notifications/initialized" });
|
|
99
|
+
send({ id: 2, method: "tools/call", params: { name: tool, arguments: args } });
|
|
100
|
+
}
|
|
101
|
+
else if (m.id === 2) {
|
|
102
|
+
done(() => resolve(m.error ? { error: m.error } : { result: (m.result ?? {}) }));
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
});
|
|
106
|
+
sock.on("error", (err) => done(() => reject(new Error(`the turn it was started for has ended, or its connection could not be opened (${err.code ?? err.message})`))));
|
|
107
|
+
sock.on("close", () => done(() => reject(new Error("relay closed the connection: the turn this agent was started for has ended, or relay refused it"))));
|
|
108
|
+
});
|
|
109
|
+
}
|
|
110
|
+
export async function geminiTools(dir, argv, io = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr }) {
|
|
111
|
+
if (!dir || argv.length !== 1) {
|
|
112
|
+
return fail(io, `usage: relay gemini-tools <dir> (--list | <tool>)\nrelay's tool helper was run with ${argv.length} argument(s) after its directory, where it takes --list or one tool's name (its arguments as JSON on stdin). If Gemini changed how it runs tool commands, relay's tools do not work with this version of it.`, 2);
|
|
113
|
+
}
|
|
114
|
+
if (argv[0] === "--list") {
|
|
115
|
+
let list;
|
|
116
|
+
try {
|
|
117
|
+
list = fs.readFileSync(path.join(dir, "tools.json"), "utf8");
|
|
118
|
+
if (!Array.isArray(JSON.parse(list)))
|
|
119
|
+
throw new Error("it is not a list");
|
|
120
|
+
}
|
|
121
|
+
catch (err) {
|
|
122
|
+
return fail(io, `relay's tool list for this turn could not be read (${err.message}).`);
|
|
123
|
+
}
|
|
124
|
+
// The mark that Gemini ran relay's discovery: where relay's own file says, nothing it cannot leave fatal.
|
|
125
|
+
try {
|
|
126
|
+
const listed = JSON.parse(fs.readFileSync(path.join(dir, "bridge.json"), "utf8")).listed;
|
|
127
|
+
if (typeof listed === "string")
|
|
128
|
+
fs.writeFileSync(listed, "listed\n");
|
|
129
|
+
}
|
|
130
|
+
catch {
|
|
131
|
+
// Relay then tells the agent its tools are unavailable, which is the safe side.
|
|
132
|
+
}
|
|
133
|
+
io.stdout.write(list);
|
|
134
|
+
return 0;
|
|
135
|
+
}
|
|
136
|
+
const tool = argv[0];
|
|
137
|
+
let args;
|
|
138
|
+
try {
|
|
139
|
+
const text = (await readAll(io.stdin)).trim();
|
|
140
|
+
const parsed = text ? JSON.parse(text) : {};
|
|
141
|
+
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
|
|
142
|
+
throw new Error("they are not a JSON object");
|
|
143
|
+
args = parsed;
|
|
144
|
+
}
|
|
145
|
+
catch (err) {
|
|
146
|
+
return fail(io, `relay could not read the arguments for ${tool}: ${err.message}. They come as a JSON object on stdin; if Gemini changed how it passes them, relay's tools do not work with this version of it.`);
|
|
147
|
+
}
|
|
148
|
+
let socketPath, secretFile;
|
|
149
|
+
try {
|
|
150
|
+
// Paths only; the secret's file is the broker's, which this turn's sandbox alone may read.
|
|
151
|
+
const where = JSON.parse(fs.readFileSync(path.join(dir, "bridge.json"), "utf8"));
|
|
152
|
+
if (typeof where.socket !== "string" || typeof where.secret !== "string")
|
|
153
|
+
throw new Error("bridge.json names no socket or secret");
|
|
154
|
+
socketPath = where.socket;
|
|
155
|
+
secretFile = where.secret;
|
|
156
|
+
}
|
|
157
|
+
catch {
|
|
158
|
+
return fail(io, "relay is not reachable from this agent: this turn's connection to relay is gone. Continue without relay.");
|
|
159
|
+
}
|
|
160
|
+
let secret;
|
|
161
|
+
try {
|
|
162
|
+
secret = fs.readFileSync(secretFile, "utf8");
|
|
163
|
+
}
|
|
164
|
+
catch (err) {
|
|
165
|
+
return fail(io, `relay is not reachable from this agent: this turn's credential for relay could not be read (${err.code ?? "error"}), as happens once the turn is over or from outside it. Continue without relay.`);
|
|
166
|
+
}
|
|
167
|
+
let answer;
|
|
168
|
+
try {
|
|
169
|
+
answer = await callThroughBroker(socketPath, secret, tool, args);
|
|
170
|
+
}
|
|
171
|
+
catch (err) {
|
|
172
|
+
return fail(io, `relay is not reachable from this agent: ${err.message}. Continue without relay.`);
|
|
173
|
+
}
|
|
174
|
+
if (answer.error)
|
|
175
|
+
return fail(io, `relay did not run ${tool}: ${answer.error.message ?? `error ${answer.error.code ?? "without a code"}`}`);
|
|
176
|
+
const text = contentText(answer.result ?? {});
|
|
177
|
+
if (answer.result?.isError)
|
|
178
|
+
return fail(io, text ? `${tool} failed: ${text}` : `${tool} failed, and said nothing more`);
|
|
179
|
+
io.stdout.write(text);
|
|
180
|
+
return 0;
|
|
181
|
+
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { within } from "./paths.js";
|
|
4
|
+
/**
|
|
5
|
+
* `roots`: the turn's writable directories (resolved). `denied`: resolved paths the profile
|
|
6
|
+
* hard-denies inside them (files or directories); names there count as outside.
|
|
7
|
+
*/
|
|
8
|
+
export function hardLinksOutside(roots, opts = {}) {
|
|
9
|
+
const started = performance.now();
|
|
10
|
+
const limit = opts.limit ?? 1;
|
|
11
|
+
const all = [...new Set(roots)];
|
|
12
|
+
const denied = opts.denied ?? [];
|
|
13
|
+
// A root inside another is walked as part of it.
|
|
14
|
+
const tops = all.filter((r) => !all.some((o) => o !== r && within(r, o)));
|
|
15
|
+
const multi = new Map();
|
|
16
|
+
let files = 0;
|
|
17
|
+
const stack = [...tops];
|
|
18
|
+
while (stack.length) {
|
|
19
|
+
const dir = stack.pop();
|
|
20
|
+
let entries;
|
|
21
|
+
try {
|
|
22
|
+
entries = fs.readdirSync(dir, { withFileTypes: true });
|
|
23
|
+
}
|
|
24
|
+
catch (err) {
|
|
25
|
+
// A directory that vanished mid-walk is no link; anything else stops the check.
|
|
26
|
+
if (err.code === "ENOENT")
|
|
27
|
+
continue;
|
|
28
|
+
throw err;
|
|
29
|
+
}
|
|
30
|
+
for (const e of entries) {
|
|
31
|
+
const p = path.join(dir, e.name);
|
|
32
|
+
if (denied.some((d) => within(p, d)))
|
|
33
|
+
continue;
|
|
34
|
+
if (e.isDirectory()) {
|
|
35
|
+
stack.push(p);
|
|
36
|
+
continue;
|
|
37
|
+
}
|
|
38
|
+
if (!e.isFile())
|
|
39
|
+
continue;
|
|
40
|
+
files++;
|
|
41
|
+
const st = fs.lstatSync(p, { bigint: true });
|
|
42
|
+
if (st.nlink <= 1n)
|
|
43
|
+
continue;
|
|
44
|
+
const key = `${st.dev}:${st.ino}`;
|
|
45
|
+
const seen = multi.get(key) ?? { names: new Set(), nlink: Number(st.nlink) };
|
|
46
|
+
seen.names.add(p);
|
|
47
|
+
multi.set(key, seen);
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
const linked = [];
|
|
51
|
+
for (const { names, nlink } of multi.values()) {
|
|
52
|
+
if (names.size < nlink)
|
|
53
|
+
linked.push([...names].sort()[0]);
|
|
54
|
+
if (linked.length >= limit)
|
|
55
|
+
break;
|
|
56
|
+
}
|
|
57
|
+
return { linked: linked.sort(), files, ms: Math.round(performance.now() - started) };
|
|
58
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Configuration a harness or a developer tool reads from a project's root: an agent that could plant
|
|
3
|
+
* one of these in a writable root could change how a later turn's harness, or the person's own
|
|
4
|
+
* tools, behave. The profile denies writing, creating or removing any of them at the top of each
|
|
5
|
+
* writable root (the worktree and granted directories), whether it is there already or not. Reads
|
|
6
|
+
* are untouched: a project's own config is still readable. `.git` is handled separately, and stays
|
|
7
|
+
* denied entirely. (Codex protocol/src/permissions.rs, srt sandbox-utils.ts: the reasoning is
|
|
8
|
+
* theirs, these names relay's.) `.gemini` is Gemini CLI's: in a trusted folder it loads
|
|
9
|
+
* `.gemini/settings.json` from its working directory and `.gemini/.env` from there or the nearest
|
|
10
|
+
* directory above that has one (0.64.0 `_doLoadSettings`, `findEnvFile`). Relay's own Gemini turns
|
|
11
|
+
* run untrusted and load neither; the person's own Gemini would.
|
|
12
|
+
*/
|
|
13
|
+
export const HARNESS_CONFIG = [
|
|
14
|
+
".codex", ".agents", ".claude", ".gemini", ".mcp.json", ".aws", ".envrc", ".vscode", ".idea", ".gitconfig", ".gitmodules",
|
|
15
|
+
".bashrc", ".bash_profile", ".bash_login", ".profile", ".zshrc", ".zshenv", ".zprofile", ".zlogin",
|
|
16
|
+
];
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
import os from "node:os";
|
|
2
|
+
import { hardLinksOutside } from "./hardlinks.js";
|
|
3
|
+
import { within } from "./paths.js";
|
|
4
|
+
import { assertProbes, ConfinementRefused, probeBoundary, startDecoySemaphores } from "./probe.js";
|
|
5
|
+
import { boundaryPaths, canonical, seatbelt } from "./seatbelt.js";
|
|
6
|
+
import { PROBES_ENABLED } from "./turn-probe.js";
|
|
7
|
+
import { TARGETS } from "../targets/index.js";
|
|
8
|
+
export { ConfinementRefused } from "./probe.js";
|
|
9
|
+
export { dirIdentity, tokenFileIdentity, tokenStoreProblem, quarantineTokenStore } from "./seatbelt.js";
|
|
10
|
+
/** The confinement mechanism for this platform, or why there is none (callers then refuse the harness). */
|
|
11
|
+
export function confinement() {
|
|
12
|
+
if (process.platform !== "darwin")
|
|
13
|
+
return { reason: `relay has no confinement mechanism for ${process.platform} yet` };
|
|
14
|
+
const reason = seatbelt.unavailable();
|
|
15
|
+
return reason ? { reason } : { mechanism: seatbelt };
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Everything relay does before a confined launch, in order: the hard-link check across every
|
|
19
|
+
* writable directory (hardlinks.ts); wrap the command for this turn; then the boundary probes under exactly that
|
|
20
|
+
* confinement. Throws ConfinementRefused, naming the failed
|
|
21
|
+
* check, when the launch must not happen, or "stopped" once `signal` (the worker's stop) is aborted.
|
|
22
|
+
* Nothing is cached; call it for every turn.
|
|
23
|
+
*/
|
|
24
|
+
export async function prepareLaunch(mechanism, policy, command, args, signal, environment) {
|
|
25
|
+
const stopped = () => {
|
|
26
|
+
if (signal?.aborted)
|
|
27
|
+
throw new ConfinementRefused("stopped", "the turn was stopped while relay was preparing its sandbox, so it does not launch the harness");
|
|
28
|
+
};
|
|
29
|
+
stopped();
|
|
30
|
+
let paths;
|
|
31
|
+
try {
|
|
32
|
+
paths = boundaryPaths(policy);
|
|
33
|
+
}
|
|
34
|
+
catch (err) {
|
|
35
|
+
throw new ConfinementRefused("boundary", err.message);
|
|
36
|
+
}
|
|
37
|
+
// The probes put their outside targets in the system temp dir: a turn that may write there (a
|
|
38
|
+
// shared temp dir passed as tmpDir) cannot be probed, and is refused before anything is walked.
|
|
39
|
+
const systemTmp = canonical(os.tmpdir());
|
|
40
|
+
if (paths.writable.some((w) => within(systemTmp, w))) {
|
|
41
|
+
throw new ConfinementRefused("outside-target", `relay cannot probe this turn's confinement: the system temporary directory ${systemTmp} is writable to it (is tmpDir the shared temporary directory?)`);
|
|
42
|
+
}
|
|
43
|
+
// The probes' decoy semaphores take an osascript start to make (probe.ts): begun now, they are made
|
|
44
|
+
// while the hard-link walk and the wrap run. The probes remove them as they finish; this removes
|
|
45
|
+
// them too, on every path, so that they go whether or not the probes were reached or got as far
|
|
46
|
+
// as their own clean-up (a second removal settles with the first).
|
|
47
|
+
const semaphores = startDecoySemaphores();
|
|
48
|
+
try {
|
|
49
|
+
let linked;
|
|
50
|
+
try {
|
|
51
|
+
// The configuration the profile protects inside writable roots counts as outside too: an alias of it
|
|
52
|
+
// under an ordinary name would let writes through to it (review r_7feaed80 X1).
|
|
53
|
+
({ linked } = hardLinksOutside(paths.writable, { denied: [...paths.hardDenied, ...paths.configDenied] }));
|
|
54
|
+
}
|
|
55
|
+
catch (err) {
|
|
56
|
+
throw new ConfinementRefused("hardlink", `relay could not check this turn's writable directories for hard links (${err.message}), so it does not launch the harness`);
|
|
57
|
+
}
|
|
58
|
+
if (linked.length) {
|
|
59
|
+
throw new ConfinementRefused("hardlink", `relay will not launch this turn: ${linked[0]} is a hard link to a file that also has a name the turn may not write (outside its writable directories, or a path the sandbox always denies), and the sandbox, which decides by path, would let writes through to it. Replace it with a copy (pnpm: use a copying package-import method) and try again.`);
|
|
60
|
+
}
|
|
61
|
+
stopped();
|
|
62
|
+
const launch = mechanism.wrap(policy, command, args);
|
|
63
|
+
// A login store is probed on a decoy of relay's own under the same rules, wrapped the same way.
|
|
64
|
+
const probes = await probeBoundary(launch, policy, { harness: command, signal, env: environment, wrap: (p) => mechanism.wrap(p, command, args), semaphores });
|
|
65
|
+
assertProbes(probes);
|
|
66
|
+
return { launch, probes };
|
|
67
|
+
}
|
|
68
|
+
finally {
|
|
69
|
+
await semaphores.remove();
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* What relay-enforced confinement guarantees on this machine and what it does not, for `relay doctor`
|
|
74
|
+
* and docs/security-model.md. Reads nothing beyond whether the mechanism exists; runs no probe.
|
|
75
|
+
*/
|
|
76
|
+
export function confinementSummary() {
|
|
77
|
+
const found = confinement();
|
|
78
|
+
const targets = TARGETS.filter((t) => t.capabilities.confinement === "relay-enforced");
|
|
79
|
+
const hosts = targets.map((t) => `${t.name}: ${(t.apiHosts ?? []).join(", ")}`).join("; ");
|
|
80
|
+
// A build with PROBES_ENABLED false (turn-probe.ts) launches nothing that needs it, and says so.
|
|
81
|
+
const off = "relay-enforced confinement is built but not enabled in this version of relay";
|
|
82
|
+
return {
|
|
83
|
+
available: "mechanism" in found,
|
|
84
|
+
enabled: PROBES_ENABLED,
|
|
85
|
+
status: !PROBES_ENABLED
|
|
86
|
+
? `${off} (${"mechanism" in found ? "Seatbelt through /usr/bin/sandbox-exec is present" : `it could not run here anyway: ${found.reason}`}): relay refuses every harness that needs it; Claude and Codex keep verified confinement`
|
|
87
|
+
: "mechanism" in found
|
|
88
|
+
? "relay-enforced confinement available (Seatbelt through /usr/bin/sandbox-exec), for harnesses whose own sandbox relay cannot verify; Claude and Codex keep verified confinement"
|
|
89
|
+
: `relay-enforced confinement unavailable: ${found.reason}. Relay refuses harnesses that need it; Claude and Codex keep verified confinement`,
|
|
90
|
+
enforces: [
|
|
91
|
+
`registered relay-enforced targets: ${targets.map((t) => t.name).join(", ")}; these rules apply whenever one is switched on and admitted`,
|
|
92
|
+
"writes only to the worktree (write jobs), granted directories, the turn's temp dir, the writable subdirectories its profile names of state relay keeps for the harness between turns (Copilot: session-state and turn; Grok: sessions and turn; Gemini: .cache, containing its runtime directory .cache/.gemini and its sessions) and named token files; in a login store a target declares (a stated downgrade; Grok's ~/.grok), only its token and lock names and one temp-name pattern, as regular files, with no link, directory or other name and nothing in a subdirectory, each existing one checked before and after every turn to be a regular file of one name under exactly that name, and probed on a decoy store under the same rules; the harness's home is a temporary one in the turn's temp dir (Grok, Gemini) unless its profile keeps the person's own, readable and not writable (Copilot); never the worktree's .git or a granted repository's .git, relay's control directory, other worktrees, the real home, harness configuration or binaries; and harness and developer-tool configuration an agent could plant at the top of a writable root (.claude, .codex, .gemini, .mcp.json, .envrc, .vscode, shell rc files, .gitconfig, and the like) is neither created, written nor removed, though a project's own stays readable; the worktree and writable directories themselves are never removed, renamed or replaced, and are checked to be the same real directories before every turn",
|
|
93
|
+
"no reads, writes, directory listing or existence tests of relay's Codex home (by default ~/.local/share/relay-codex-home), the default API key directory (~/.config/relay-keys), or of a key file moved elsewhere by ~/.config/relay/local.json (the moved file alone, not its directory); these denials apply to every relay-enforced target, even when Gemini is switched off; scratch regressions confirm Seatbelt file-read* denials hold through case-swapped and /System/Volumes/Data spellings",
|
|
94
|
+
"network on (granted): IPv4 to anything but this Mac's own addresses (loopback, the LAN and tailnet addresses it holds, their IPv4-mapped spellings), and no IPv6 at all, since Seatbelt can refuse those spellings only by refusing IPv6; no listening on the network",
|
|
95
|
+
"Codex with grant.raw_network (stage 2, switched on by targets.codex.stage2): Codex's command executor runs under these rules, with stage 2's network instead of network on: any host over IP, raw TCP, UDP, ssh and DNS, but not this Mac's own addresses on the denied ports (a static list, every TCP port anything on this Mac listens on at turn start, and relay's reserved range but the job's block), their IPv4-mapped spellings included, and so no IPv6 to those ports at any host, and no UDP to ports 1900 or 5351; TCP listening only on the job's block of ports; Unix sockets under the turn's temp dir, and a relay-made worktree on write turns; the app server stays outside, its own local actions switched off and read back",
|
|
96
|
+
"Codex with stage-2 mediated or no raw network: the executor's own reserved listener still starts, but the PORT/PORTS block is reserved and denied; only person-consented raw network or an explicit listen/port-0 restart overlay opens block binding. A localhost-connect overlay adds no listener authority",
|
|
97
|
+
`network off: only relay's proxy for the turn, which tunnels HTTPS to the exact API hosts the target declares (${hosts}) and nothing else, its telemetry included; no DNS, IP literals, private addresses, this machine's own addresses or cloud-metadata endpoints; no loopback but the proxy, which closes with the turn; except that a harness taking the certificate-trust downgrade (Copilot) can have the system's trust daemons fetch URLs it supplies, past the proxy; Grok takes that downgrade too, Gemini does not`,
|
|
98
|
+
"Unix sockets only of the turn's own, under its temp dir, its bridge to relay, and the system log's (connected to, as every process's logging does); network-on additionally permits the mDNSResponder resolver socket; other turns' bridges are neither listable nor reachable; no routing sockets",
|
|
99
|
+
"either way: no LaunchServices, Apple events or launchctl, no signals to processes outside the sandbox, no terminal but the turn's own (those it opens itself, and one relay gives it)",
|
|
100
|
+
"Mach services only from a fixed list (directory lookups, preferences, notifications, logging); network-on adds dnssd, mDNSResponder, configd, DNSConfiguration, networkd and nehelper resolver services; no XPC services; no pasteboard; no IOKit user client",
|
|
101
|
+
"no inspection of processes outside the sandbox: not their paths or details, not the list of processes, not their command lines or environment; process-info and sysctl kern.procargs2 permit inspection of same-sandbox processes, including their start-up environment",
|
|
102
|
+
"named POSIX semaphores only under /mp- (Python's multiprocessing), any other name out of reach; no mutating fcntl or fsctl (no alternate chflags), and sysctl writes only to kern.grade_cputype",
|
|
103
|
+
"executables only from system, Homebrew, /usr/local and developer-tool locations, the harness, relay's Node and the writable directories",
|
|
104
|
+
"boundary probes under each turn's exact sandbox before every launch, and a hard-link check of every writable directory; any failure refuses the launch",
|
|
105
|
+
],
|
|
106
|
+
doesNot: [
|
|
107
|
+
"confine reads: everything you can read is readable, except relay's control directory, its sockets directory, its protected config and install paths, relay's Codex home (by default ~/.local/share/relay-codex-home), the default API key directory (~/.config/relay-keys), and a key file moved elsewhere by ~/.config/relay/local.json",
|
|
108
|
+
"protect credentials the harness can read (its own login, other tools' files); the target's API stays reachable, so network off means the target's API hosts only, and for Copilot those include api.github.com, GitHub's whole REST API, where any token the agent holds or reads (its own login is readable through the keychain downgrade) can also change things, as far as that token's permissions allow",
|
|
109
|
+
"allow escalation in 1.0: approval requests from such harnesses are reported, never run outside the sandbox",
|
|
110
|
+
"keep a harness whose profile takes a stated downgrade from what it opens: the keychain (Copilot's login is there; other items its tools are trusted for become readable) or the certificate trust daemons (Copilot checks GitHub's certificates through them; they fetch from URLs their caller supplies, a way out the proxy does not see), or a login store (the harness may replace its token file there with any regular file it writes; and an exchange of two names, which Seatbelt cannot refuse where a rename must be allowed, can put a link at the token's name: relay immediately quarantines unsafe entries and the token files by rename as soon as the turn ends, fails the turn and requires a fresh login before further turns; a failed move is reported loudly; your own harness running concurrently during the turn could still follow the link before quarantine)",
|
|
111
|
+
"stop an agent running a copy of a program it placed in a writable directory (the rules above still bind it)",
|
|
112
|
+
"close the local network or tailnet to a raw-network stage-2 Codex job (Seatbelt cannot express address ranges), or a denied service reached back through a router port forward, NAT hairpin, a tailnet subnet router or a VM bridge; nor deny a local service started after the turn begins; when raw/listen/port-0 authority opens the block, a block port bound on 0.0.0.0 is visible on the LAN and tailnet",
|
|
113
|
+
"isolate named POSIX semaphores under /mp- (where Python's multiprocessing makes its own): that namespace is machine-wide, so another process's /mp- semaphore can be opened, posted or unlinked by a confined process that knows its name; the name is random and there is no call to list them, and Codex's and Claude Code's own runtimes allow semaphores with no name limit at all",
|
|
114
|
+
"keep the turn's proxy credentials out of the harness's environment: HTTPS_PROXY and the like must carry them; the turn's own processes can read each other's start-up environment, including its proxy token, as can your own processes outside the sandbox; other relay-enforced profiles cannot inspect it or connect to this turn's proxy; other loopback-capable processes can connect but need its token; Gemini's API key is handed over ACP, never in an environment",
|
|
115
|
+
],
|
|
116
|
+
};
|
|
117
|
+
}
|