@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.
- 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 +393 -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 +1539 -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 +345 -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 +641 -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 +345 -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 +635 -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 +1518 -0
- package/docs/pinned-codex.md +333 -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,645 @@
|
|
|
1
|
+
// Extensions for launched agents (docs/extensions.md): the skills and MCP servers a job or thread
|
|
2
|
+
// is given when the root session asks for them and the person consents. Here: what the config
|
|
3
|
+
// allows resolved into what one session holds, relay's own definitions of the servers (mcp.json),
|
|
4
|
+
// the filtered package of skills a turn gets, the consent text, and what an extension counts for
|
|
5
|
+
// in authority. The gateway that serves the servers' tools is src/mcp/gateway.ts.
|
|
6
|
+
import fs from "node:fs";
|
|
7
|
+
import os from "node:os";
|
|
8
|
+
import path from "node:path";
|
|
9
|
+
import { z } from "zod";
|
|
10
|
+
import { canonical, configPath, expandHome, hasExtensions, inside, insideAnyCase, serverOf } from "./config.js";
|
|
11
|
+
import { getNode } from "./db.js";
|
|
12
|
+
import { mcpFile } from "./protected-config.js";
|
|
13
|
+
import { sessionParams } from "./params.js";
|
|
14
|
+
import { targetDef } from "../targets/index.js";
|
|
15
|
+
/** The plugin a Claude agent's skills come in, so that they are relay-skills:<name>. */
|
|
16
|
+
export const SKILLS_PLUGIN = "relay-skills";
|
|
17
|
+
/** The extensions a session holds, or undefined for none. */
|
|
18
|
+
export const extensionsOf = (n) => (n ? sessionParams(n).extensions ?? undefined : undefined);
|
|
19
|
+
/** Whether a session holds MCP servers: then it has no network, and only the person can allow its requests. */
|
|
20
|
+
export const holdsServers = (n) => Boolean(extensionsOf(n)?.mcp_servers.length);
|
|
21
|
+
// Relay's own definitions of the servers.
|
|
22
|
+
/** Where relay's MCP definitions are: mcp.json beside config.json (not synced; it may hold credentials). */
|
|
23
|
+
export { mcpFile };
|
|
24
|
+
/**
|
|
25
|
+
* Relay's own config files, config.json and mcp.json, which say what launched agents may be given
|
|
26
|
+
* and which servers run outside their sandboxes: each where relay looks for it and, if that is a
|
|
27
|
+
* link, where the link leads (config.json is often a link into a synced repository).
|
|
28
|
+
*/
|
|
29
|
+
export function configFiles() {
|
|
30
|
+
const out = new Set();
|
|
31
|
+
for (const f of [configPath(), mcpFile()]) {
|
|
32
|
+
const at = path.resolve(expandHome(f));
|
|
33
|
+
out.add(path.join(canonical(path.dirname(at)), path.basename(at)));
|
|
34
|
+
out.add(canonical(at));
|
|
35
|
+
}
|
|
36
|
+
return [...out];
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* The config file of relay's that changing `p` could change, or undefined: `p` is one of them (by
|
|
40
|
+
* either name, and on macOS in any case), or a directory holding one. No grant may cover one, and
|
|
41
|
+
* no file request change one.
|
|
42
|
+
*/
|
|
43
|
+
export function touchesConfig(p) {
|
|
44
|
+
return configFiles().find((f) => insideAnyCase(f, p));
|
|
45
|
+
}
|
|
46
|
+
/**
|
|
47
|
+
* Every name relay's mcp.json has, if it exists: where relay looks for it and, if that is a link,
|
|
48
|
+
* where the link leads. It may hold credentials, so launched Claude agents are denied reading it
|
|
49
|
+
* (backends/claude.ts). Relay's Codex profile denies no reads (a profile could, with `deny`
|
|
50
|
+
* entries), so a Codex agent can read it.
|
|
51
|
+
*/
|
|
52
|
+
export function mcpFileNames() {
|
|
53
|
+
const at = path.resolve(expandHome(mcpFile()));
|
|
54
|
+
if (!fs.existsSync(at))
|
|
55
|
+
return [];
|
|
56
|
+
return [...new Set([at, path.join(canonical(path.dirname(at)), path.basename(at)), canonical(at)])];
|
|
57
|
+
}
|
|
58
|
+
const ServerDef = z.object({
|
|
59
|
+
type: z.literal("stdio").optional(),
|
|
60
|
+
command: z.string().min(1),
|
|
61
|
+
args: z.array(z.string()).optional(),
|
|
62
|
+
env: z.record(z.string(), z.string()).optional(),
|
|
63
|
+
cwd: z.string().refine((p) => path.isAbsolute(expandHome(p)), "cwd must be an absolute path").optional(),
|
|
64
|
+
}).strict();
|
|
65
|
+
const McpFile = z.object({ mcpServers: z.record(z.string(), ServerDef) }).strict();
|
|
66
|
+
/** Relay's server definitions, read and checked strictly. Throws, saying what is wrong, never quoting a value (an env may hold a key). */
|
|
67
|
+
export function readMcpFile(file = mcpFile()) {
|
|
68
|
+
let text;
|
|
69
|
+
try {
|
|
70
|
+
text = fs.readFileSync(file, "utf8");
|
|
71
|
+
}
|
|
72
|
+
catch (e) {
|
|
73
|
+
const code = e.code;
|
|
74
|
+
throw new Error(code === "ENOENT" ? `relay's MCP definitions file ${file} does not exist` : `relay could not read its MCP definitions file ${file} (${code ?? "error"})`);
|
|
75
|
+
}
|
|
76
|
+
let raw;
|
|
77
|
+
try {
|
|
78
|
+
raw = JSON.parse(text);
|
|
79
|
+
}
|
|
80
|
+
catch {
|
|
81
|
+
throw new Error(`relay's MCP definitions file ${file} is not valid JSON`);
|
|
82
|
+
}
|
|
83
|
+
const r = McpFile.safeParse(raw);
|
|
84
|
+
if (!r.success)
|
|
85
|
+
throw new Error(`relay's MCP definitions file ${file} is not valid: ${r.error.issues.map((i) => `${i.path.join(".") || "(top level)"}: ${i.message}`).join("; ")}. Each server is { "command", "args", "env", "cwd" } under "mcpServers" (stdio servers only)`);
|
|
86
|
+
return r.data.mcpServers;
|
|
87
|
+
}
|
|
88
|
+
// Skills.
|
|
89
|
+
/** Where the person's own user skills are, in lookup order. `env` is the root relay
|
|
90
|
+
* process's environment, before selectEnvironment replaces Codex's runtime CODEX_HOME. */
|
|
91
|
+
export function skillRoots(target, env = process.env) {
|
|
92
|
+
const home = env.HOME || os.homedir();
|
|
93
|
+
if (target === "claude")
|
|
94
|
+
return [path.join(env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), "skills")];
|
|
95
|
+
if (target === "codex")
|
|
96
|
+
return [path.join(env.CODEX_HOME || path.join(home, ".codex"), "skills"), path.join(home, ".agents", "skills")];
|
|
97
|
+
return [];
|
|
98
|
+
}
|
|
99
|
+
const SKILL_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
100
|
+
const isDir = (p) => {
|
|
101
|
+
try {
|
|
102
|
+
return fs.statSync(p).isDirectory();
|
|
103
|
+
}
|
|
104
|
+
catch {
|
|
105
|
+
return false;
|
|
106
|
+
}
|
|
107
|
+
};
|
|
108
|
+
/** Whether a directory is a skill directory: it holds a SKILL.md, whether relay can give it or not (checkSkill says). */
|
|
109
|
+
const hasSkill = (dir) => {
|
|
110
|
+
try {
|
|
111
|
+
return isDir(dir) && Boolean(fs.lstatSync(path.join(dir, "SKILL.md")));
|
|
112
|
+
}
|
|
113
|
+
catch {
|
|
114
|
+
return false;
|
|
115
|
+
}
|
|
116
|
+
};
|
|
117
|
+
/** Whether a file name is SKILL.md's in any case: on a case-insensitive disk (macOS's, by default) a harness opening SKILL.md opens it. */
|
|
118
|
+
const isSkillFile = (name) => name.toLowerCase() === "skill.md";
|
|
119
|
+
/**
|
|
120
|
+
* How many levels below a root Codex finds a skill directory: codex-cli 0.163.0 (observed) looked
|
|
121
|
+
* six deep, inside skill directories too, never in a dot-directory, and only for a file named
|
|
122
|
+
* exactly SKILL.md. Relay looks as deep (codexSkillFiles, userSkillDirs).
|
|
123
|
+
*/
|
|
124
|
+
const CODEX_DEPTH = 6;
|
|
125
|
+
/**
|
|
126
|
+
* The skill directories of one root of the person's, by the name each goes under, as the target's
|
|
127
|
+
* CLI finds them: Claude Code takes each directory directly in the root (as it does a plugin's
|
|
128
|
+
* skills/); Codex also looks inside a directory that is not a skill itself (a group), as deep as
|
|
129
|
+
* CODEX_DEPTH. Dot-directories are left out ($CODEX_HOME/skills/.system).
|
|
130
|
+
*/
|
|
131
|
+
function userSkillDirs(root, target) {
|
|
132
|
+
const out = [];
|
|
133
|
+
const seen = new Set();
|
|
134
|
+
const walk = (dir, depth) => {
|
|
135
|
+
let entries;
|
|
136
|
+
try {
|
|
137
|
+
const real = fs.realpathSync(dir);
|
|
138
|
+
if (seen.has(real))
|
|
139
|
+
return;
|
|
140
|
+
seen.add(real);
|
|
141
|
+
entries = fs.readdirSync(dir).filter((n) => !n.startsWith(".")).sort();
|
|
142
|
+
}
|
|
143
|
+
catch {
|
|
144
|
+
return;
|
|
145
|
+
}
|
|
146
|
+
for (const n of entries) {
|
|
147
|
+
const sub = path.join(dir, n);
|
|
148
|
+
if (hasSkill(sub))
|
|
149
|
+
out.push({ name: n, dir: sub });
|
|
150
|
+
else if (target === "codex" && depth + 1 < CODEX_DEPTH && isDir(sub))
|
|
151
|
+
walk(sub, depth + 1);
|
|
152
|
+
}
|
|
153
|
+
};
|
|
154
|
+
walk(root, 0);
|
|
155
|
+
return out;
|
|
156
|
+
}
|
|
157
|
+
/**
|
|
158
|
+
* Why a skill directory cannot go into a package, or that it is a person's slash command only
|
|
159
|
+
* (its front matter sets disable-model-invocation to anything but a plain false: the model may
|
|
160
|
+
* never load it, so a launched agent, where nobody types slash commands, could not use it).
|
|
161
|
+
*/
|
|
162
|
+
function checkSkill(dir) {
|
|
163
|
+
const file = path.join(dir, "SKILL.md");
|
|
164
|
+
let st;
|
|
165
|
+
try {
|
|
166
|
+
st = fs.lstatSync(file);
|
|
167
|
+
}
|
|
168
|
+
catch {
|
|
169
|
+
return { problem: `${dir} holds no SKILL.md` };
|
|
170
|
+
}
|
|
171
|
+
// Read through a link, a SKILL.md would be checked here and then left out of the copy (which takes regular files only).
|
|
172
|
+
if (st.isSymbolicLink())
|
|
173
|
+
return { problem: `${file} is a symbolic link, and relay copies only a skill's regular files, so the skill would reach the agent without it` };
|
|
174
|
+
if (!st.isFile())
|
|
175
|
+
return { problem: `${file} is not a regular file` };
|
|
176
|
+
const named = fs.readdirSync(dir).filter(isSkillFile);
|
|
177
|
+
if (!named.includes("SKILL.md"))
|
|
178
|
+
return { problem: `${dir} names its SKILL.md ${named.join(", ")}: relay reads only a file named exactly SKILL.md` };
|
|
179
|
+
let text;
|
|
180
|
+
try {
|
|
181
|
+
text = fs.readFileSync(file, "utf8");
|
|
182
|
+
}
|
|
183
|
+
catch {
|
|
184
|
+
return { problem: `relay could not read ${file}` };
|
|
185
|
+
}
|
|
186
|
+
const split = splitSkill(text);
|
|
187
|
+
if (typeof split === "string")
|
|
188
|
+
return { problem: `${file}: ${split}` };
|
|
189
|
+
if (!split.blocks.some((b) => b.key === "description"))
|
|
190
|
+
return { problem: `${file} has no description` };
|
|
191
|
+
if (modelBarred(split.blocks))
|
|
192
|
+
return { userOnly: true };
|
|
193
|
+
// A skill larger than the package takes cannot reach the agent whole: refused now, not after the person consents.
|
|
194
|
+
try {
|
|
195
|
+
eachPackaged(dir, path.basename(dir), () => { });
|
|
196
|
+
}
|
|
197
|
+
catch (err) {
|
|
198
|
+
return { problem: err.message };
|
|
199
|
+
}
|
|
200
|
+
return null;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Whether front matter keeps the model from loading a skill: disable-model-invocation given as
|
|
204
|
+
* anything but a plain false (Claude Code reads true, "yes", "on", "1"… as true). Fail-closed: a
|
|
205
|
+
* value relay cannot read for certain as false counts as true. The key is not copied either way.
|
|
206
|
+
*/
|
|
207
|
+
function modelBarred(blocks) {
|
|
208
|
+
const b = blocks.find((x) => x.key === "disable-model-invocation");
|
|
209
|
+
if (!b)
|
|
210
|
+
return false;
|
|
211
|
+
const more = b.lines.slice(1).some((l) => l.trim() && !l.trimStart().startsWith("#"));
|
|
212
|
+
const value = b.lines[0].slice(b.lines[0].indexOf(":") + 1).replace(/[ \t]+#.*$/, "").trim();
|
|
213
|
+
return more || !/^(["']?)(?:false|no|off|0)\1$/i.test(value);
|
|
214
|
+
}
|
|
215
|
+
/** The skills targets.<id>.skills selects, by name and real source directory, or why it cannot be given. */
|
|
216
|
+
export function resolveSkills(setting, target, env = process.env) {
|
|
217
|
+
if (setting === undefined || setting === "none")
|
|
218
|
+
return [];
|
|
219
|
+
const roots = skillRoots(target, env);
|
|
220
|
+
const found = [];
|
|
221
|
+
const add = (name, dir) => {
|
|
222
|
+
if (!SKILL_NAME.test(name))
|
|
223
|
+
return `the skill directory ${dir} has a name relay cannot give a skill (letters, digits, '.', '_', '-')`;
|
|
224
|
+
if (found.some((s) => s.name === name))
|
|
225
|
+
return `two skills would both be called ${name}`;
|
|
226
|
+
found.push({ name, source: fs.realpathSync(dir) });
|
|
227
|
+
return null;
|
|
228
|
+
};
|
|
229
|
+
if (setting === "user") {
|
|
230
|
+
// Every skill the CLI would find in the person's roots; for a name found twice, the first (in
|
|
231
|
+
// root order, then by path). A slash command only a person can use is left out.
|
|
232
|
+
for (const root of roots) {
|
|
233
|
+
for (const { name, dir } of userSkillDirs(root, target)) {
|
|
234
|
+
if (found.some((s) => s.name === name))
|
|
235
|
+
continue;
|
|
236
|
+
const check = checkSkill(dir);
|
|
237
|
+
if (check && "userOnly" in check)
|
|
238
|
+
continue;
|
|
239
|
+
const why = check ? check.problem : add(name, dir);
|
|
240
|
+
if (why)
|
|
241
|
+
return { reason: `${why}, so relay cannot give your user skills` };
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
if (!found.length)
|
|
245
|
+
return { reason: `targets.${target}.skills is "user", but there are no skills in ${roots.join(" or ")} that a launched agent could load` };
|
|
246
|
+
return found;
|
|
247
|
+
}
|
|
248
|
+
for (const ref of setting) {
|
|
249
|
+
const isPath = ref.startsWith("/") || ref.startsWith("~/");
|
|
250
|
+
// A name is a skill the CLI itself would find under that name, as under "user" (for Codex, one in a group directory too).
|
|
251
|
+
const dir = isPath ? path.resolve(expandHome(ref)) : roots.map((r) => userSkillDirs(r, target).find((s) => s.name === ref)?.dir).find(Boolean);
|
|
252
|
+
if (!dir || !hasSkill(dir)) {
|
|
253
|
+
return { reason: isPath ? `the skill ${ref} in targets.${target}.skills is not a directory holding a SKILL.md` : `the skill ${ref} in targets.${target}.skills is not in ${roots.join(" or ")}` };
|
|
254
|
+
}
|
|
255
|
+
const check = checkSkill(dir);
|
|
256
|
+
if (check && "userOnly" in check) {
|
|
257
|
+
return { reason: `the skill ${ref} in targets.${target}.skills sets disable-model-invocation, so only a person typing its slash command can use it, and a launched agent could never load it` };
|
|
258
|
+
}
|
|
259
|
+
const why = check ? check.problem : add(path.basename(dir), dir);
|
|
260
|
+
if (why)
|
|
261
|
+
return { reason: why };
|
|
262
|
+
}
|
|
263
|
+
return found;
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* The front-matter keys a skill keeps in the package. Anything else (allowed-tools, hooks, model,
|
|
267
|
+
* context, agent…) could pre-approve tools, run hooks or start other agents. user-invocable is
|
|
268
|
+
* dropped too: Claude Code 2.1.302 leaves a skill with user-invocable false out of its init
|
|
269
|
+
* report, where relay checks that every given skill loaded, and a launched agent has nobody
|
|
270
|
+
* typing slash commands. disable-model-invocation is read first (checkSkill), then dropped.
|
|
271
|
+
*/
|
|
272
|
+
const KEPT_KEYS = new Set(["name", "description", "license", "metadata", "argument-hint"]);
|
|
273
|
+
/** A top-level key's line, as a YAML reader takes one: a bare key at the start of the line, then a colon and a space or the end of the line. */
|
|
274
|
+
const KEY_LINE = /^([A-Za-z0-9_-]+)[ \t]*:(?:[ \t]|$)/;
|
|
275
|
+
/** An item of a block sequence written at the start of the line, under the key above it. */
|
|
276
|
+
const ITEM_LINE = /^-(?:[ \t]|$)/;
|
|
277
|
+
/**
|
|
278
|
+
* A SKILL.md split into its front-matter blocks (a key's line and the lines that continue it) and
|
|
279
|
+
* its body, or why relay will not read it. It fails closed: a line that starts at the left margin
|
|
280
|
+
* must be a bare key (KEY_LINE), an item of the sequence above it, a comment or blank; indented
|
|
281
|
+
* lines continue the block above. Anything else at the margin (a quoted key, a `?` or `<<` key, a
|
|
282
|
+
* flow collection, an anchor, a tag, a tab, a document marker) is refused, since a YAML reader
|
|
283
|
+
* could take it for a key relay did not see; so are a key given twice and line breaks other than
|
|
284
|
+
* \n, which a reader may split lines at where relay does not.
|
|
285
|
+
*/
|
|
286
|
+
function splitSkill(text) {
|
|
287
|
+
const lf = text.replace(/^\uFEFF/, "").replace(/\r\n/g, "\n");
|
|
288
|
+
const m = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(lf);
|
|
289
|
+
if (!m)
|
|
290
|
+
return "it has no front matter (--- … ---) relay can read";
|
|
291
|
+
if (/[\r\u0085\u2028\u2029]/.test(m[1]))
|
|
292
|
+
return "its front matter has a line break other than \\n, which relay does not read";
|
|
293
|
+
const blocks = [];
|
|
294
|
+
for (const [i, line] of m[1].split("\n").entries()) {
|
|
295
|
+
const key = KEY_LINE.exec(line)?.[1];
|
|
296
|
+
if (key) {
|
|
297
|
+
if (blocks.some((b) => b.key === key))
|
|
298
|
+
return `its front matter gives ${key} twice`;
|
|
299
|
+
blocks.push({ key, lines: [line] });
|
|
300
|
+
}
|
|
301
|
+
else if (!line.trim() || line.startsWith("#") || (line.startsWith(" ") && line.trim().length)) {
|
|
302
|
+
if (blocks.length)
|
|
303
|
+
blocks.at(-1).lines.push(line);
|
|
304
|
+
else if (line.trim() && !line.trimStart().startsWith("#"))
|
|
305
|
+
return "its front matter starts with an indented line, which relay does not read";
|
|
306
|
+
}
|
|
307
|
+
else if (ITEM_LINE.test(line) && blocks.length)
|
|
308
|
+
blocks.at(-1).lines.push(line);
|
|
309
|
+
else
|
|
310
|
+
return `line ${i + 2} of its front matter is not a plain key (key: value), an indented line, a list item or a comment, so relay cannot tell which keys it holds`;
|
|
311
|
+
}
|
|
312
|
+
return { blocks, body: lf.slice(m[0].length) };
|
|
313
|
+
}
|
|
314
|
+
/** A SKILL.md as it goes into the package: its front matter cut to KEPT_KEYS, named `name`, its body unchanged. */
|
|
315
|
+
export function filteredSkill(text, name) {
|
|
316
|
+
const split = splitSkill(text);
|
|
317
|
+
if (typeof split === "string")
|
|
318
|
+
throw new Error(split);
|
|
319
|
+
const kept = split.blocks.filter((b) => KEPT_KEYS.has(b.key) && b.key !== "name").flatMap((b) => b.lines);
|
|
320
|
+
return ["---", `name: ${name}`, ...kept, "---", split.body].join("\n");
|
|
321
|
+
}
|
|
322
|
+
/** The most a package copies of one skill: beyond it the skill is refused, not cut. */
|
|
323
|
+
const MAX_FILES = 200;
|
|
324
|
+
const MAX_BYTES = 5 * 1024 * 1024;
|
|
325
|
+
/** Harness metadata at a skill's top (Codex reads MCP dependencies from these), in lower case: left out by any case of the name, which a disk that ignores case (macOS's, by default) opens as the same. */
|
|
326
|
+
const METADATA = new Set(["agents", "skill.json"]);
|
|
327
|
+
/**
|
|
328
|
+
* Walks what a skill's package takes from `dir`, in order: each directory, then what it holds, and
|
|
329
|
+
* each regular file, by its path relative to `dir`, with its stats. Left out are dot-files, harness
|
|
330
|
+
* metadata at the top (agents/, SKILL.json, in any case), every SKILL.md in any case but the top
|
|
331
|
+
* one by exactly that name (Codex would load one below the top as a skill of its own, unfiltered),
|
|
332
|
+
* and symlinks and anything else that is not a regular file or a directory (a link could lead
|
|
333
|
+
* anywhere). Throws, naming the skill, when it holds more than relay copies: it is refused, not cut.
|
|
334
|
+
*/
|
|
335
|
+
function eachPackaged(dir, name, visit) {
|
|
336
|
+
let files = 0;
|
|
337
|
+
let bytes = 0;
|
|
338
|
+
const walk = (rel, top) => {
|
|
339
|
+
for (const entry of fs.readdirSync(path.join(dir, rel)).sort()) {
|
|
340
|
+
if (entry.startsWith(".") || (top && METADATA.has(entry.toLowerCase())))
|
|
341
|
+
continue;
|
|
342
|
+
if (isSkillFile(entry) && !(top && entry === "SKILL.md"))
|
|
343
|
+
continue;
|
|
344
|
+
const r = path.join(rel, entry);
|
|
345
|
+
const st = fs.lstatSync(path.join(dir, r));
|
|
346
|
+
if (st.isDirectory()) {
|
|
347
|
+
visit(r, st);
|
|
348
|
+
walk(r, false);
|
|
349
|
+
}
|
|
350
|
+
else if (st.isFile()) {
|
|
351
|
+
if (++files > MAX_FILES || (bytes += st.size) > MAX_BYTES)
|
|
352
|
+
throw new Error(`the skill ${name} (${dir}) is larger than relay copies (${MAX_FILES} files, ${MAX_BYTES / 1024 / 1024} MB)`);
|
|
353
|
+
visit(r, st);
|
|
354
|
+
}
|
|
355
|
+
}
|
|
356
|
+
};
|
|
357
|
+
walk("", true);
|
|
358
|
+
}
|
|
359
|
+
/**
|
|
360
|
+
* Builds a turn's package of skills under `root`, a directory of relay's own (in the node's
|
|
361
|
+
* directory, which no agent can write): root/skills/<name>/ for each skill and, for Claude
|
|
362
|
+
* (`plugin`), root/.claude-plugin/plugin.json, which makes the package a plugin. Codex gets no
|
|
363
|
+
* manifest: with one, codex-cli 0.163.0 names every skill under the root <plugin>:<name>.
|
|
364
|
+
* Copied is what eachPackaged walks: the skill's regular files only, without symlinks, dot-files,
|
|
365
|
+
* harness metadata or a SKILL.md below its top. SKILL.md's front matter is filtered
|
|
366
|
+
* (filteredSkill). Throws, naming the skill, for one it cannot copy whole.
|
|
367
|
+
*/
|
|
368
|
+
export function buildSkillPackage(root, skills, o) {
|
|
369
|
+
fs.mkdirSync(path.join(root, "skills"), { recursive: true, mode: 0o700 });
|
|
370
|
+
if (o.plugin) {
|
|
371
|
+
fs.mkdirSync(path.join(root, ".claude-plugin"), { recursive: true, mode: 0o700 });
|
|
372
|
+
fs.writeFileSync(path.join(root, ".claude-plugin", "plugin.json"), JSON.stringify({ name: SKILLS_PLUGIN, version: "1.0.0", description: "Skills relay gave this agent: each skill's regular files, without hooks, MCP servers, agent definitions or pre-approved tools." }, null, 2));
|
|
373
|
+
}
|
|
374
|
+
for (const s of skills) {
|
|
375
|
+
const dest = path.join(root, "skills", s.name);
|
|
376
|
+
try {
|
|
377
|
+
// Checked again, size included: the skill may have changed since the call.
|
|
378
|
+
const check = checkSkill(s.source);
|
|
379
|
+
if (check)
|
|
380
|
+
throw new Error("problem" in check ? check.problem : "it now sets disable-model-invocation, so the agent could not load it");
|
|
381
|
+
fs.mkdirSync(dest, { recursive: true, mode: 0o700 });
|
|
382
|
+
eachPackaged(s.source, s.name, (rel, st) => {
|
|
383
|
+
const from = path.join(s.source, rel);
|
|
384
|
+
const to = path.join(dest, rel);
|
|
385
|
+
if (st.isDirectory())
|
|
386
|
+
fs.mkdirSync(to, { recursive: true, mode: 0o700 });
|
|
387
|
+
else if (rel === "SKILL.md")
|
|
388
|
+
fs.writeFileSync(to, filteredSkill(fs.readFileSync(from, "utf8"), s.name));
|
|
389
|
+
else
|
|
390
|
+
fs.copyFileSync(from, to);
|
|
391
|
+
});
|
|
392
|
+
if (!fs.lstatSync(path.join(dest, "SKILL.md")).isFile())
|
|
393
|
+
throw new Error("its SKILL.md was not copied");
|
|
394
|
+
}
|
|
395
|
+
catch (err) {
|
|
396
|
+
throw new Error(`relay could not package the skill ${s.name} from ${s.source}: ${err.message}`);
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
}
|
|
400
|
+
/**
|
|
401
|
+
* The SKILL.md files runtime Codex would find for a turn in `cwd` (codex-cli 0.163.0, observed):
|
|
402
|
+
* its own runtime CODEX_HOME/skills including .system, the shared ~/.agents/skills, the repository's
|
|
403
|
+
* (.agents/skills and .codex/skills in every directory from cwd up to the repository's top) and the
|
|
404
|
+
* machine's (/etc/codex/skills). Each by the path found and its real path. Relay switches them off
|
|
405
|
+
* for every turn, and then checks what Codex will load, so a place missed here stops the
|
|
406
|
+
* turn rather than letting a skill through. Unlike skillRoots, `env` is the selected child
|
|
407
|
+
* environment: the person's original CODEX_HOME is only a consent/copy source.
|
|
408
|
+
*/
|
|
409
|
+
export function codexSkillFiles(cwd, env = process.env) {
|
|
410
|
+
const home = env.HOME || os.homedir();
|
|
411
|
+
const roots = [path.join(env.CODEX_HOME || path.join(home, ".codex"), "skills"), path.join(home, ".agents", "skills"), "/etc/codex/skills"];
|
|
412
|
+
const system = path.join(roots[0], ".system");
|
|
413
|
+
roots.push(system);
|
|
414
|
+
for (let dir = path.resolve(cwd);; dir = path.dirname(dir)) {
|
|
415
|
+
roots.push(path.join(dir, ".agents", "skills"), path.join(dir, ".codex", "skills"));
|
|
416
|
+
if (fs.existsSync(path.join(dir, ".git")) || dir === home || path.dirname(dir) === dir)
|
|
417
|
+
break;
|
|
418
|
+
}
|
|
419
|
+
const out = new Set();
|
|
420
|
+
// 0.163.0 installs these bundled skills on its first start, including under a fresh HOME.
|
|
421
|
+
// Disable their future paths too; an upstream addition still refuses at skills/list.
|
|
422
|
+
for (const name of ["imagegen", "openai-docs", "review-agent", "skill-creator", "skill-installer"]) {
|
|
423
|
+
out.add(path.join(system, name, "SKILL.md"));
|
|
424
|
+
out.add(path.join(canonical(system), name, "SKILL.md"));
|
|
425
|
+
}
|
|
426
|
+
const seen = new Set();
|
|
427
|
+
const walk = (dir, depth) => {
|
|
428
|
+
let real;
|
|
429
|
+
try {
|
|
430
|
+
real = fs.realpathSync(dir);
|
|
431
|
+
}
|
|
432
|
+
catch {
|
|
433
|
+
return;
|
|
434
|
+
}
|
|
435
|
+
if (seen.has(real) || depth > CODEX_DEPTH)
|
|
436
|
+
return;
|
|
437
|
+
seen.add(real);
|
|
438
|
+
const md = path.join(dir, "SKILL.md");
|
|
439
|
+
if (fs.existsSync(md)) {
|
|
440
|
+
out.add(md);
|
|
441
|
+
out.add(path.join(real, "SKILL.md"));
|
|
442
|
+
}
|
|
443
|
+
let entries = [];
|
|
444
|
+
try {
|
|
445
|
+
entries = fs.readdirSync(dir);
|
|
446
|
+
}
|
|
447
|
+
catch {
|
|
448
|
+
return;
|
|
449
|
+
}
|
|
450
|
+
for (const e of entries.sort())
|
|
451
|
+
if (!e.startsWith(".") && isDir(path.join(dir, e)))
|
|
452
|
+
walk(path.join(dir, e), depth + 1);
|
|
453
|
+
};
|
|
454
|
+
for (const r of roots)
|
|
455
|
+
walk(r, 0);
|
|
456
|
+
return [...out];
|
|
457
|
+
}
|
|
458
|
+
/**
|
|
459
|
+
* The names of the skills Claude Code would load by itself for a turn in `cwd`, were relay's
|
|
460
|
+
* settings not isolating it: the person's ($CLAUDE_CONFIG_DIR/skills or ~/.claude/skills) and the
|
|
461
|
+
* repository's (.claude/skills in every directory from cwd up to the repository's top). Under
|
|
462
|
+
* `--setting-sources ""` none of them loads (observed with Claude Code 2.1.302). Under inherited
|
|
463
|
+
* settings these names receive skillOverrides "off" too; every turn's init report is checked.
|
|
464
|
+
*/
|
|
465
|
+
export function claudeSkillNames(cwd, env = process.env) {
|
|
466
|
+
const home = env.HOME || os.homedir();
|
|
467
|
+
const roots = skillRoots("claude", env);
|
|
468
|
+
for (let dir = path.resolve(cwd);; dir = path.dirname(dir)) {
|
|
469
|
+
roots.push(path.join(dir, ".claude", "skills"));
|
|
470
|
+
if (fs.existsSync(path.join(dir, ".git")) || dir === home || path.dirname(dir) === dir)
|
|
471
|
+
break;
|
|
472
|
+
}
|
|
473
|
+
return [...new Set(roots.flatMap((r) => userSkillDirs(r, "claude").map((s) => s.name)))];
|
|
474
|
+
}
|
|
475
|
+
// What a session is given, from the call.
|
|
476
|
+
/** The tools of a server entry that run without asking. */
|
|
477
|
+
const allowTools = (e) => (typeof e === "string" ? [] : [...(e.allow_tools ?? [])]);
|
|
478
|
+
/** Why a target takes no extensions, or null: an ACP harness runs inside relay's own sandbox, which a skill or server from outside would cross. */
|
|
479
|
+
export function takesNone(target) {
|
|
480
|
+
const def = targetDef(target);
|
|
481
|
+
return def.capabilities.extensions ? null : `relay gives extensions only to Claude and Codex agents; ${def.name} runs inside relay's own sandbox and takes none. Omit extensions.`;
|
|
482
|
+
}
|
|
483
|
+
/**
|
|
484
|
+
* The extensions the config allows for `target`, resolved for one session: the skills found now,
|
|
485
|
+
* and the servers, each checked against relay's mcp.json. Or why none can be given.
|
|
486
|
+
*/
|
|
487
|
+
export function resolveExtensions(cfg, target, env = process.env) {
|
|
488
|
+
const none = takesNone(target);
|
|
489
|
+
if (none)
|
|
490
|
+
return { reason: none };
|
|
491
|
+
const t = cfg.targets[target];
|
|
492
|
+
if (!hasExtensions(t))
|
|
493
|
+
return { reason: `relay's config allows no extensions for ${target} (targets.${target}.skills or targets.${target}.mcp_servers), so there are none to give. Omit extensions, or ask the user to allow some.` };
|
|
494
|
+
const mcp_servers = (t.mcp_servers ?? []).map((e) => ({ name: serverOf(e), allow_tools: allowTools(e) }));
|
|
495
|
+
if (mcp_servers.length) {
|
|
496
|
+
let defs;
|
|
497
|
+
try {
|
|
498
|
+
defs = readMcpFile();
|
|
499
|
+
}
|
|
500
|
+
catch (err) {
|
|
501
|
+
return { reason: `${err.message}, so relay cannot give ${target} agents the MCP servers its config names (${mcp_servers.map((s) => s.name).join(", ")}). Omit extensions, or ask the user to define them there.` };
|
|
502
|
+
}
|
|
503
|
+
const missing = mcp_servers.filter((s) => !Object.hasOwn(defs, s.name)).map((s) => s.name);
|
|
504
|
+
if (missing.length)
|
|
505
|
+
return { reason: `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} named in targets.${target}.mcp_servers but not defined in ${mcpFile()}. Omit extensions, or ask the user to define ${missing.length === 1 ? "it" : "them"} there.` };
|
|
506
|
+
}
|
|
507
|
+
const skills = resolveSkills(t.skills, target, env);
|
|
508
|
+
if ("reason" in skills)
|
|
509
|
+
return { reason: `${skills.reason}. Omit extensions, or ask the user to fix targets.${target}.skills.` };
|
|
510
|
+
return { skills, mcp_servers, consent: null };
|
|
511
|
+
}
|
|
512
|
+
// What is said about them.
|
|
513
|
+
const list = (xs) => (xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`);
|
|
514
|
+
/** A server as the consent text and prompts name it: with the tools that run without asking. */
|
|
515
|
+
const serverLine = (s) => s.allow_tools.length ? `${s.name} (${list(s.allow_tools)} without asking you; every other tool asks you)` : `${s.name} (every tool asks you)`;
|
|
516
|
+
/** The text of the request for consent to a session's extensions: every extension, named. */
|
|
517
|
+
export function consentText(node, ext) {
|
|
518
|
+
const parts = [
|
|
519
|
+
...(ext.skills.length ? [`skills ${ext.skills.map((s) => s.name).join(", ")}`] : []),
|
|
520
|
+
...(ext.mcp_servers.length ? [`MCP servers ${ext.mcp_servers.map(serverLine).join(", ")}`] : []),
|
|
521
|
+
];
|
|
522
|
+
return `give this ${node.target ? targetDef(node.target).name : ""} ${node.kind === "thread" ? "thread" : "job"} these extensions for the rest of it: ${parts.join("; ")}`.replace(/\s+/g, " ");
|
|
523
|
+
}
|
|
524
|
+
/**
|
|
525
|
+
* What allowing that request does, for the person to read (a request's effect): from what the
|
|
526
|
+
* session was given. Only a session given MCP servers has their limits (no network, no write paths,
|
|
527
|
+
* no relay delegating, every request of its the person's alone); skills alone change nothing of
|
|
528
|
+
* what it may do. Relay's limit on delegating is on other relay agents: the harness's own subagents
|
|
529
|
+
* (Claude's Task tool) work inside the same agent, its sandbox and relay's gate.
|
|
530
|
+
*/
|
|
531
|
+
export function consentEffect(node, ext) {
|
|
532
|
+
const item = node.kind === "thread" ? "thread" : "job";
|
|
533
|
+
const skills = ext?.skills.length
|
|
534
|
+
? `copies of these skills (their instruction files and scripts, without hooks, MCP servers, agent definitions or pre-approved tools), which the agent reads and runs through its own sandboxed tools`
|
|
535
|
+
: "";
|
|
536
|
+
if (!ext?.mcp_servers.length)
|
|
537
|
+
return `gives it ${skills || "these extensions"} for the rest of the ${item}`;
|
|
538
|
+
// A thread is read-only: it has no write paths to be refused.
|
|
539
|
+
const limits = item === "job" ? "no network and no write paths outside its worktree" : "no network";
|
|
540
|
+
return `gives it ${skills ? `${skills}, and ` : ""}these MCP servers for the rest of the ${item}: the servers run outside its sandbox as your own processes, every call of their tools asks you unless named as running without asking, ` +
|
|
541
|
+
`the ${item} gets ${limits}, may not start or steer other relay agents while it has them (its own CLI's subagents work under the same sandbox and gate), and only you can allow its requests`;
|
|
542
|
+
}
|
|
543
|
+
/** What a session's extensions look like in status, result and a starting call's answer. */
|
|
544
|
+
export function extensionsView(ext, o = {}) {
|
|
545
|
+
return {
|
|
546
|
+
skills: ext.skills.map((s) => s.name),
|
|
547
|
+
// allow_tools as relay's config names them: the tools that run without asking the user.
|
|
548
|
+
mcp_servers: ext.mcp_servers.map((s) => ({ name: s.name, allow_tools: s.allow_tools })),
|
|
549
|
+
...(o.consent === false ? {} : { consent: ext.consent ? `given ${ext.consent.by}` : "not given yet: the user is asked before the agent starts" }),
|
|
550
|
+
};
|
|
551
|
+
}
|
|
552
|
+
/** One line for relay tree: every extension a session was given, and whether the person has consented. */
|
|
553
|
+
export function extensionsSummary(ext) {
|
|
554
|
+
const parts = [
|
|
555
|
+
...(ext.skills.length ? [`skills ${ext.skills.map((s) => s.name).join(", ")}`] : []),
|
|
556
|
+
...(ext.mcp_servers.length ? [`MCP servers ${ext.mcp_servers.map((s) => (s.allow_tools.length ? `${s.name} (${s.allow_tools.join(", ")} without asking)` : s.name)).join(", ")}`] : []),
|
|
557
|
+
];
|
|
558
|
+
return `${parts.join("; ")}; consent ${ext.consent ? `given ${ext.consent.by}` : "not given yet"}`;
|
|
559
|
+
}
|
|
560
|
+
/** What the agent is told it has, in its preamble. */
|
|
561
|
+
export function extensionsLine(target, ext) {
|
|
562
|
+
const parts = [];
|
|
563
|
+
if (ext.skills.length) {
|
|
564
|
+
const names = ext.skills.map((s) => (target === "claude" ? `${SKILLS_PLUGIN}:${s.name}` : s.name));
|
|
565
|
+
parts.push(`skills ${names.join(", ")} (load one when it applies${target === "claude" ? ", with the Skill tool" : ""})`);
|
|
566
|
+
}
|
|
567
|
+
if (ext.mcp_servers.length) {
|
|
568
|
+
const servers = ext.mcp_servers.map((s) => (s.allow_tools.length ? `${s.name} (${list(s.allow_tools)} run at once; every other tool waits for the user's yes)` : `${s.name} (every tool waits for the user's yes)`));
|
|
569
|
+
parts.push(`MCP servers through relay's tools named <server>__<tool>: ${servers.join(", ")}. A call the user refuses comes back as an error: do not try to reach that service another way (you have no network for it); continue without it and say what you needed. ` +
|
|
570
|
+
"A server whose tools you do not have could not be started for this turn (relay's server instructions say why): work without it and say so");
|
|
571
|
+
}
|
|
572
|
+
return `Extensions the user consented to before you started: ${parts.join("; ")}.`;
|
|
573
|
+
}
|
|
574
|
+
// Authority.
|
|
575
|
+
/**
|
|
576
|
+
* What a session's extensions count for in authority (caller.ts authority): each skill by its
|
|
577
|
+
* source, each server, and each tool of one that runs without asking. A launched agent may act on
|
|
578
|
+
* an item only if it holds none of these that the agent's own session does not.
|
|
579
|
+
*/
|
|
580
|
+
export function extensionKeys(ext) {
|
|
581
|
+
if (!ext)
|
|
582
|
+
return [];
|
|
583
|
+
return [
|
|
584
|
+
...ext.skills.map((s) => `skill:${s.source}`),
|
|
585
|
+
...ext.mcp_servers.flatMap((s) => [`mcp:${s.name}`, ...s.allow_tools.map((t) => `mcp:${s.name}:${t}`)]),
|
|
586
|
+
];
|
|
587
|
+
}
|
|
588
|
+
/** Request kinds only the person can allow. */
|
|
589
|
+
const PERSON_KINDS = new Set(["extensions", "mcp", "env", "local_network", "raw_network"]);
|
|
590
|
+
/**
|
|
591
|
+
* Whether only the person may allow a request: consent to extensions, a call of an extension's
|
|
592
|
+
* tool, release of environment values, consent to a Codex job's local network or raw network, and every request of a session that holds MCP servers (a command outside the sandbox, the
|
|
593
|
+
* web or a file outside the worktree would each be a way round relay's gate).
|
|
594
|
+
*/
|
|
595
|
+
export function personOnly(r) {
|
|
596
|
+
if (r.kind === "escalation") {
|
|
597
|
+
// Read the authoritative row when a notification passes only its kind/node projection.
|
|
598
|
+
const raw = r.detail_json;
|
|
599
|
+
if (raw) {
|
|
600
|
+
try {
|
|
601
|
+
if (JSON.parse(raw).escalation?.required_decider === "person")
|
|
602
|
+
return true;
|
|
603
|
+
}
|
|
604
|
+
catch {
|
|
605
|
+
return true;
|
|
606
|
+
}
|
|
607
|
+
}
|
|
608
|
+
}
|
|
609
|
+
return PERSON_KINDS.has(r.kind) || holdsServers(getNode(r.node_id));
|
|
610
|
+
}
|
|
611
|
+
/**
|
|
612
|
+
* Where the person can allow a person-only request: relay's question in the root session, where
|
|
613
|
+
* its host is known to show the question to a person, and the host's own permission prompt
|
|
614
|
+
* through confirm. Not a command (`relay approve`): any agent with a shell tool can run one, with
|
|
615
|
+
* a terminal of its own if it wants. Review C2/X1 requires person-only consent and names no route;
|
|
616
|
+
* these two are the lane's choice (plan-1.0.md A6, reading (5)).
|
|
617
|
+
*/
|
|
618
|
+
export const PERSON_ROUTES = "in relay's question in the root session, where its host shows it to them, or in the host's permission prompt through confirm";
|
|
619
|
+
/** Why `relay approve` does not allow this request, or null: only the person may allow it, and a command could be any agent's. */
|
|
620
|
+
export function commandRefusal(r) {
|
|
621
|
+
if (!personOnly(r))
|
|
622
|
+
return null;
|
|
623
|
+
return `only the user can allow ${r.id}, and relay takes that only ${PERSON_ROUTES}, never from a command, which any agent with a shell could run. ` +
|
|
624
|
+
`relay deny ${r.id} denies it.`;
|
|
625
|
+
}
|
|
626
|
+
/** Writes a turn's gateway manifest into its extensions directory (relay's own) and returns its path. */
|
|
627
|
+
export function writeManifest(dir, servers, runId) {
|
|
628
|
+
fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
|
|
629
|
+
const file = path.join(dir, "gateway.json");
|
|
630
|
+
const manifest = { mcp_file: mcpFile(), servers, report: path.join(dir, "gateway-report.json"), ...(runId ? { run_id: runId } : {}) };
|
|
631
|
+
fs.writeFileSync(file, JSON.stringify(manifest, null, 2), { mode: 0o600 });
|
|
632
|
+
return file;
|
|
633
|
+
}
|
|
634
|
+
/** What the gateway reported for the turn, as warnings for its result. */
|
|
635
|
+
export function gatewayWarnings(dir) {
|
|
636
|
+
try {
|
|
637
|
+
const r = JSON.parse(fs.readFileSync(path.join(dir, "gateway-report.json"), "utf8"));
|
|
638
|
+
return Array.isArray(r.warnings) ? r.warnings.filter((w) => typeof w === "string") : [];
|
|
639
|
+
}
|
|
640
|
+
catch {
|
|
641
|
+
return [];
|
|
642
|
+
}
|
|
643
|
+
}
|
|
644
|
+
/** Whether a manifest path is one relay wrote: in relay's control directory. */
|
|
645
|
+
export const ownManifest = (file, home) => inside(file, home);
|