@nanocollective/roster 0.1.0-beta.14 → 0.1.0-beta.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/dist/agents-NMGVORU3.js +232 -0
  2. package/dist/chunk-E3EVPK4I.js +338 -0
  3. package/dist/chunk-QCKEGMXD.js +562 -0
  4. package/dist/cli.js +1703 -820
  5. package/dist/compose-56JIIIHA.js +15 -0
  6. package/dist/connectors-ZVEPXSAR.js +23 -0
  7. package/dist/worker/assets/assets/css/connectors.css +50 -0
  8. package/dist/worker/assets/assets/js/api.js +3 -0
  9. package/dist/worker/assets/assets/js/app.js +4 -1
  10. package/dist/worker/assets/assets/js/icons.js +2 -0
  11. package/dist/worker/assets/assets/js/state.js +11 -1
  12. package/dist/worker/assets/assets/js/views/connectors.js +290 -0
  13. package/dist/worker/assets/index.html +4 -0
  14. package/dist/worker/index.js +2743 -1014
  15. package/docs/README.md +1 -0
  16. package/docs/architecture.md +1 -1
  17. package/docs/commands.md +37 -1
  18. package/docs/connectors.md +157 -0
  19. package/docs/cost.md +1 -1
  20. package/docs/developing.md +2 -2
  21. package/docs/doctor-codes.md +5 -1
  22. package/docs/export.md +1 -1
  23. package/docs/extending.md +1 -1
  24. package/docs/hosting.md +13 -1
  25. package/docs/memory.md +1 -1
  26. package/docs/org-yaml.md +25 -1
  27. package/docs/portal.md +18 -1
  28. package/docs/prompts.md +1 -1
  29. package/docs/security.md +17 -1
  30. package/docs/session-workflow.md +23 -5
  31. package/docs/staff-yaml.md +1 -1
  32. package/docs/troubleshooting.md +1 -1
  33. package/docs/upgrading.md +1 -1
  34. package/docs/writing-a-charter.md +1 -1
  35. package/package.json +2 -1
  36. package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +8 -6
  37. package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +8 -6
  38. package/templates/ops/.github/workflows/session.yaml +52 -11
  39. package/templates/ops/agents.mjs +38 -11
  40. package/templates/ops/compose.mjs +12 -0
  41. package/templates/ops/connectors.mjs +722 -0
  42. package/templates/ops/prompts/_identity.md +14 -0
  43. package/templates/portal/css/connectors.css +50 -0
  44. package/templates/portal/index.html +4 -0
  45. package/templates/portal/js/api.js +3 -0
  46. package/templates/portal/js/app.js +4 -1
  47. package/templates/portal/js/icons.js +2 -0
  48. package/templates/portal/js/state.js +11 -1
  49. package/templates/portal/js/views/connectors.js +290 -0
@@ -0,0 +1,722 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Connectors: the outside services a staff member may use in a run, as MCP servers.
4
+ *
5
+ * VENDORED into every tenant's ops repo, for the same reason agents.mjs is: a run at 07:00 must
6
+ * not depend on npm or on an org the tenant does not control.
7
+ *
8
+ * org.yaml says who gets what, and nothing else:
9
+ *
10
+ * connectors:
11
+ * sentry:
12
+ * staff: [cto]
13
+ * linear:
14
+ * staff: [cto, cmo]
15
+ *
16
+ * A name from the catalogue below brings its server, how to get a key, and how to check one.
17
+ * Anything else is written out longhand, with a `url` or a `command`. Keys never go in
18
+ * org.yaml: each is a GitHub secret named by `secretName`, and a run reads it from the caller's
19
+ * secrets, which reach session.yaml through `secrets: inherit`.
20
+ *
21
+ * Each agent hears the same list in its own vocabulary: an MCP config file for Claude, the same
22
+ * for nanocoder by its own environment variable, and a config.toml in a fresh CODEX_HOME for
23
+ * Codex.
24
+ * That translation lives here because this is the only file that knows both sides.
25
+ */
26
+
27
+ import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
28
+ import { join, resolve } from "node:path";
29
+ import { fileURLToPath } from "node:url";
30
+
31
+ /* ------------------------------------------------------------------------------------------ */
32
+ /* The catalogue */
33
+ /* ------------------------------------------------------------------------------------------ */
34
+
35
+ /**
36
+ * Well-known services, so that adding one is: pick it, paste a key, tick who gets it.
37
+ *
38
+ * Every entry here takes a key that can be pasted, because a run at 07:00 cannot click through
39
+ * a sign-in. The ones that only offer a sign-in are `auth: "oauth"`, and they work through the
40
+ * hosted portal, which holds the sign-in and hands each run a fresh access token.
41
+ *
42
+ * fields what the person fills in. `secret: true` goes to a GitHub secret, the rest to
43
+ * org.yaml. `pattern` catches a wrong paste before it is stored.
44
+ * server the MCP server, from the filled-in fields. Secret values arrive here only in a run.
45
+ * readOnly how this connector is held to reading, for a read-only staff member or one
46
+ * marked `read_only: true`: a server that can be told (`server` gets
47
+ * `readOnly: true`), or the names of its tools that only read, which only an
48
+ * agent that takes a tool list can enforce. Absent: it is left out for them.
49
+ * check one cheap request that proves a key works, for the Check key button.
50
+ */
51
+ const bearer = (token) => ({ Authorization: `Bearer ${token}` });
52
+ const key = (label, extra = {}) => ({ id: "token", label, secret: true, ...extra });
53
+
54
+ export const CATALOGUE = {
55
+ sentry: {
56
+ name: "Sentry",
57
+ summary: "Read errors, issues and releases.",
58
+ suggest: ["cto"],
59
+ link: "https://sentry.io/settings/account/api/auth-tokens/",
60
+ steps: [
61
+ "Open Sentry, then Settings, then Personal Tokens.",
62
+ "Create a token with read access to your organisation and projects.",
63
+ "Copy it and paste it here.",
64
+ ],
65
+ fields: [key("Auth token")],
66
+ // Sentry-Bearer, not Bearer: Sentry keeps plain Bearer for its own sign-in.
67
+ server: (v) => ({
68
+ transport: "http",
69
+ url: "https://mcp.sentry.dev/mcp",
70
+ headers: { Authorization: `Sentry-Bearer ${v.token}` },
71
+ }),
72
+ check: (v) => ({ url: "https://sentry.io/api/0/organizations/", headers: bearer(v.token) }),
73
+ },
74
+
75
+ linear: {
76
+ name: "Linear",
77
+ summary: "Read and update issues, projects and cycles.",
78
+ suggest: ["cto", "cpo"],
79
+ link: "https://linear.app/settings/account/security",
80
+ steps: [
81
+ "Open Linear, then Settings, then Security & access.",
82
+ "Under Personal API keys, create a key.",
83
+ "Copy it and paste it here.",
84
+ ],
85
+ fields: [key("API key", { pattern: "^lin_api_" })],
86
+ server: (v) => ({ transport: "http", url: "https://mcp.linear.app/mcp", headers: bearer(v.token) }),
87
+ // The GraphQL API takes the key bare, unlike the MCP server.
88
+ check: (v) => ({
89
+ url: "https://api.linear.app/graphql",
90
+ method: "POST",
91
+ headers: { Authorization: v.token, "Content-Type": "application/json" },
92
+ body: JSON.stringify({ query: "{ viewer { id } }" }),
93
+ }),
94
+ },
95
+
96
+ github: {
97
+ name: "GitHub",
98
+ summary: "Read and act on repos outside this org.",
99
+ suggest: [],
100
+ link: "https://github.com/settings/personal-access-tokens",
101
+ steps: [
102
+ "Open GitHub, then Settings, then Developer settings, then Fine-grained tokens.",
103
+ "Create a token for the repos the staff should reach.",
104
+ "Copy it and paste it here.",
105
+ ],
106
+ fields: [key("Personal access token", { pattern: "^(github_pat_|ghp_)" })],
107
+ server: (v, o) => ({
108
+ transport: "http",
109
+ url: "https://api.githubcopilot.com/mcp/",
110
+ headers: { ...bearer(v.token), ...(o.readOnly ? { "X-MCP-Readonly": "true" } : {}) },
111
+ }),
112
+ readOnly: { server: true },
113
+ check: (v) => ({ url: "https://api.github.com/user", headers: bearer(v.token) }),
114
+ },
115
+
116
+ supabase: {
117
+ name: "Supabase",
118
+ summary: "Query the database and read project settings.",
119
+ suggest: ["cto"],
120
+ link: "https://supabase.com/dashboard/account/tokens",
121
+ steps: [
122
+ "Open Supabase, then Account, then Access Tokens.",
123
+ "Generate a token.",
124
+ "Copy it and paste it here, with the project's reference ID from Project Settings.",
125
+ ],
126
+ fields: [
127
+ key("Access token", { pattern: "^sbp_" }),
128
+ { id: "project_ref", label: "Project reference ID", required: false },
129
+ ],
130
+ server: (v, o) => {
131
+ const q = new URLSearchParams();
132
+ if (v.project_ref) q.set("project_ref", v.project_ref);
133
+ if (o.readOnly) q.set("read_only", "true");
134
+ const qs = q.toString();
135
+ return {
136
+ transport: "http",
137
+ url: `https://mcp.supabase.com/mcp${qs ? `?${qs}` : ""}`,
138
+ headers: bearer(v.token),
139
+ };
140
+ },
141
+ readOnly: { server: true },
142
+ check: (v) => ({ url: "https://api.supabase.com/v1/projects", headers: bearer(v.token) }),
143
+ },
144
+
145
+ postgres: {
146
+ name: "Postgres",
147
+ summary: "Query a Postgres database.",
148
+ suggest: ["cto"],
149
+ link: "",
150
+ steps: [
151
+ "Use a connection string for a database user with only the access the staff should have.",
152
+ "It looks like postgresql://user:password@host:5432/database.",
153
+ ],
154
+ fields: [key("Connection string", { pattern: "^postgres(ql)?://" })],
155
+ // No official server. postgres-mcp is the maintained one, and pipx is on GitHub's runners.
156
+ server: (v, o) => ({
157
+ transport: "stdio",
158
+ command: "pipx",
159
+ args: ["run", "postgres-mcp", `--access-mode=${o.readOnly ? "restricted" : "unrestricted"}`],
160
+ env: { DATABASE_URI: v.token },
161
+ }),
162
+ readOnly: { server: true },
163
+ },
164
+
165
+ cloudflare: {
166
+ name: "Cloudflare",
167
+ summary: "Read and change Workers, DNS and other account settings.",
168
+ suggest: ["cto"],
169
+ link: "https://dash.cloudflare.com/profile/api-tokens",
170
+ steps: [
171
+ "Open Cloudflare, then My Profile, then API Tokens.",
172
+ "Create a token with the permissions the staff should have.",
173
+ "Copy it and paste it here.",
174
+ ],
175
+ fields: [key("API token")],
176
+ server: (v) => ({ transport: "http", url: "https://mcp.cloudflare.com/mcp", headers: bearer(v.token) }),
177
+ check: (v) => ({
178
+ url: "https://api.cloudflare.com/client/v4/user/tokens/verify",
179
+ headers: bearer(v.token),
180
+ }),
181
+ },
182
+
183
+ posthog: {
184
+ name: "PostHog",
185
+ summary: "Read analytics, insights and feature flags.",
186
+ suggest: ["cpo", "cmo"],
187
+ link: "https://app.posthog.com/settings/user-api-keys",
188
+ steps: [
189
+ "Open PostHog, then Settings, then Personal API keys.",
190
+ "Create a key with the MCP Server preset.",
191
+ "Copy it and paste it here.",
192
+ ],
193
+ fields: [key("Personal API key", { pattern: "^phx_" })],
194
+ server: (v, o) => ({
195
+ transport: "http",
196
+ url: "https://mcp.posthog.com/mcp",
197
+ headers: { ...bearer(v.token), ...(o.readOnly ? { "x-posthog-read-only": "true" } : {}) },
198
+ }),
199
+ readOnly: { server: true },
200
+ },
201
+
202
+ stripe: {
203
+ name: "Stripe",
204
+ summary: "Read payments, customers and subscriptions.",
205
+ suggest: ["cfo"],
206
+ link: "https://dashboard.stripe.com/apikeys",
207
+ steps: [
208
+ "Open Stripe, then Developers, then API keys.",
209
+ "Create a restricted key for agent access, with read permissions only.",
210
+ "Copy it and paste it here.",
211
+ ],
212
+ fields: [key("Restricted key", { pattern: "^rk_(live|test)_" })],
213
+ server: (v) => ({ transport: "http", url: "https://mcp.stripe.com", headers: bearer(v.token) }),
214
+ check: (v) => ({ url: "https://api.stripe.com/v1/balance", headers: bearer(v.token) }),
215
+ },
216
+
217
+ resend: {
218
+ name: "Resend",
219
+ summary: "Send email and read domains and delivery.",
220
+ suggest: ["cmo"],
221
+ link: "https://resend.com/api-keys",
222
+ steps: ["Open Resend, then API Keys.", "Create a key.", "Copy it and paste it here."],
223
+ fields: [key("API key", { pattern: "^re_" })],
224
+ server: (v) => ({ transport: "http", url: "https://mcp.resend.com/mcp", headers: bearer(v.token) }),
225
+ check: (v) => ({ url: "https://api.resend.com/domains", headers: bearer(v.token) }),
226
+ },
227
+
228
+ notion: {
229
+ name: "Notion",
230
+ summary: "Read and write pages and databases.",
231
+ suggest: ["cmo", "cpo"],
232
+ auth: "oauth",
233
+ steps: ["Sign in to Notion and choose the pages to share."],
234
+ fields: [],
235
+ oauth: { resource: "https://mcp.notion.com/mcp" },
236
+ server: (v) => ({ transport: "http", url: "https://mcp.notion.com/mcp", headers: bearer(v.access_token) }),
237
+ },
238
+
239
+ "notion-key": {
240
+ name: "Notion (integration key)",
241
+ summary: "Read and write the pages shared with an integration.",
242
+ suggest: [],
243
+ link: "https://www.notion.so/profile/integrations",
244
+ steps: [
245
+ "Open Notion, then Settings, then Integrations, and create an internal integration.",
246
+ "Share the pages the staff should see with it.",
247
+ "Copy its secret and paste it here.",
248
+ ],
249
+ fields: [key("Integration secret", { pattern: "^(ntn_|secret_)" })],
250
+ server: (v) => ({
251
+ transport: "stdio",
252
+ command: "npx",
253
+ args: ["-y", "@notionhq/notion-mcp-server"],
254
+ env: { NOTION_TOKEN: v.token },
255
+ }),
256
+ check: (v) => ({
257
+ url: "https://api.notion.com/v1/users/me",
258
+ headers: { ...bearer(v.token), "Notion-Version": "2022-06-28" },
259
+ }),
260
+ },
261
+ };
262
+
263
+ /* ------------------------------------------------------------------------------------------ */
264
+ /* Names */
265
+ /* ------------------------------------------------------------------------------------------ */
266
+
267
+ const ID = /^[a-z][a-z0-9-]{0,30}$/;
268
+
269
+ /** The GitHub secret a connector's field is stored as. Secret names are upper case and `_`. */
270
+ export function secretName(id, field) {
271
+ return `CONNECTOR_${id}_${field}`.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
272
+ }
273
+
274
+ /* ------------------------------------------------------------------------------------------ */
275
+ /* Reading org.yaml */
276
+ /* ------------------------------------------------------------------------------------------ */
277
+
278
+ /**
279
+ * Every connector org.yaml declares, merged with its catalogue entry, valid or not. A problem
280
+ * is reported on the entry rather than thrown, so doctor and the portal can say which one is
281
+ * wrong while the others still work.
282
+ */
283
+ export function declared(org) {
284
+ const raw = org?.connectors;
285
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return [];
286
+ return Object.entries(raw).map(([id, entry]) => describe(id, entry ?? {}));
287
+ }
288
+
289
+ function describe(id, entry) {
290
+ const known = CATALOGUE[entry.catalogue ?? id] ?? null;
291
+ const staff = Array.isArray(entry.staff) ? entry.staff.map(String) : entry.staff ? [String(entry.staff)] : [];
292
+ const out = {
293
+ id,
294
+ name: known?.name ?? entry.name ?? id,
295
+ known: Boolean(known),
296
+ catalogue: known ? (entry.catalogue ?? id) : null,
297
+ staff,
298
+ readOnly: entry.read_only === true,
299
+ auth: known?.auth ?? (entry.auth === "oauth" ? "oauth" : "key"),
300
+ portal: entry.portal ? String(entry.portal) : null,
301
+ settings: {},
302
+ secrets: [],
303
+ problem: null,
304
+ entry,
305
+ };
306
+ if (!ID.test(id)) {
307
+ out.problem = `"${id}" is not a usable name: lower case letters, digits and -, starting with a letter`;
308
+ return out;
309
+ }
310
+ if (known) {
311
+ for (const f of known.fields ?? []) {
312
+ if (f.secret) out.secrets.push({ field: f.id, label: f.label, name: secretName(id, f.id) });
313
+ else if (entry[f.id] !== undefined && entry[f.id] !== null) out.settings[f.id] = String(entry[f.id]);
314
+ else if (f.required !== false) out.problem = `${out.name} needs ${f.id} in org.yaml`;
315
+ }
316
+ if (out.auth === "oauth" && !out.portal) {
317
+ out.problem = `${out.name} signs in through the hosted portal, and org.yaml names none (portal:)`;
318
+ }
319
+ return out;
320
+ }
321
+ // Written out longhand: a url or a command, and the secrets it names.
322
+ if (!entry.url && !entry.command) {
323
+ out.problem = `${id} is not in the catalogue, so it needs a url or a command`;
324
+ return out;
325
+ }
326
+ for (const s of list(entry.secrets)) {
327
+ out.secrets.push({ field: String(s).toLowerCase(), label: String(s), name: secretName(id, String(s)) });
328
+ }
329
+ if (out.auth === "oauth" && (!entry.url || !out.portal)) {
330
+ out.problem = `${id} signs in through the hosted portal, so it needs a url and a portal`;
331
+ }
332
+ return out;
333
+ }
334
+
335
+ function list(v) {
336
+ if (Array.isArray(v)) return v;
337
+ return v === undefined || v === null || v === "" ? [] : [v];
338
+ }
339
+
340
+ /** The connectors one staff member has, in the order org.yaml lists them. */
341
+ export function connectorsOf(org, handle) {
342
+ return declared(org).filter((c) => c.staff.includes(handle));
343
+ }
344
+
345
+ /* ------------------------------------------------------------------------------------------ */
346
+ /* Servers */
347
+ /* ------------------------------------------------------------------------------------------ */
348
+
349
+ /**
350
+ * The MCP server for one connector, neutral of any agent:
351
+ * { name, transport: "http", url, headers } or { name, transport: "stdio", command, args, env }
352
+ * plus `tools`, the tool names it is held to when reading only is enforced by a tool list.
353
+ *
354
+ * `values` maps each secret field to its value; a run has them, nothing else does.
355
+ */
356
+ export function serverFor(c, values, opts = {}) {
357
+ const readOnly = opts.readOnly === true;
358
+ const known = c.catalogue ? CATALOGUE[c.catalogue] : null;
359
+ let spec;
360
+ if (known) {
361
+ spec = known.server({ ...c.settings, ...values }, { readOnly });
362
+ } else {
363
+ const fill = (s) =>
364
+ String(s).replace(/\$\{([A-Za-z0-9_]+)\}/g, (_, k) => values[k.toLowerCase()] ?? "");
365
+ spec = c.entry.url
366
+ ? {
367
+ transport: "http",
368
+ url: String(c.entry.url),
369
+ headers: {
370
+ ...Object.fromEntries(Object.entries(c.entry.headers ?? {}).map(([k, v]) => [k, fill(v)])),
371
+ ...(values.access_token ? bearer(values.access_token) : {}),
372
+ },
373
+ }
374
+ : {
375
+ transport: "stdio",
376
+ ...splitCommand(String(c.entry.command)),
377
+ env: Object.fromEntries(Object.entries(c.entry.env ?? {}).map(([k, v]) => [k, fill(v)])),
378
+ };
379
+ }
380
+ const tools = readOnly && known?.readOnly?.tools ? known.readOnly.tools : null;
381
+ return { name: c.id, ...spec, tools };
382
+ }
383
+
384
+ /**
385
+ * Whether a connector can be given to someone who may only read, and how. A server that can be
386
+ * told is told; a list of reading tools needs an agent that takes a tool list; anything else is
387
+ * left out rather than given in full.
388
+ */
389
+ export function readOnlyMode(c, agentTakesTools) {
390
+ const known = c.catalogue ? CATALOGUE[c.catalogue] : null;
391
+ const how = known?.readOnly;
392
+ if (!how) return null;
393
+ if (how.server) return "server";
394
+ if (how.tools && agentTakesTools) return "tools";
395
+ return null;
396
+ }
397
+
398
+ /** "npx -y @scope/pkg --flag" as a command and its arguments. No shell, so no quoting games. */
399
+ function splitCommand(line) {
400
+ const parts = line.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
401
+ const clean = parts.map((p) => p.replace(/^(["'])(.*)\1$/, "$2"));
402
+ return { command: clean[0] ?? "", args: clean.slice(1) };
403
+ }
404
+
405
+ /* ------------------------------------------------------------------------------------------ */
406
+ /* Each agent's vocabulary */
407
+ /* ------------------------------------------------------------------------------------------ */
408
+
409
+ /** Agents that read Claude Code's MCP config and take a list of tool names. */
410
+ const CLAUDE = new Set(["claude-code-action", "claude"]);
411
+
412
+ /**
413
+ * What one agent needs to see these servers: files to write, flags for its command line, the
414
+ * tool names to add to its allowlist, and environment for the steps after this one.
415
+ *
416
+ * Secrets go in the files and never in flags or environment: a flag is printed in the log of
417
+ * the step that runs it, and a file in the runner's temp directory is not.
418
+ */
419
+ export function wiringFor(agentId, servers, dir) {
420
+ if (!servers.length) return { files: {}, flags: "", tools: [], env: {} };
421
+ if (agentId === "codex") return codexWiring(servers, dir);
422
+ if (agentId === "nanocoder") {
423
+ const file = join(dir, "nanocoder-mcp.json");
424
+ const mcpServers = {};
425
+ for (const s of servers) {
426
+ mcpServers[s.name] =
427
+ s.transport === "http"
428
+ ? { transport: "http", url: s.url, headers: s.headers ?? {} }
429
+ : { transport: "stdio", command: s.command, args: s.args ?? [], env: s.env ?? {} };
430
+ }
431
+ return {
432
+ files: { [file]: JSON.stringify({ mcpServers }, null, 2) },
433
+ flags: "",
434
+ tools: [],
435
+ env: { NANOCODER_MCPSERVERS_FILE: file },
436
+ };
437
+ }
438
+ // Claude, and any agent written out longhand: Claude's format is the one most MCP clients read.
439
+ const file = join(dir, "mcp.json");
440
+ const mcpServers = {};
441
+ for (const s of servers) {
442
+ mcpServers[s.name] =
443
+ s.transport === "http"
444
+ ? { type: "http", url: s.url, headers: s.headers ?? {} }
445
+ : { type: "stdio", command: s.command, args: s.args ?? [], env: s.env ?? {} };
446
+ }
447
+ const tools = servers.flatMap((s) =>
448
+ s.tools ? s.tools.map((t) => `mcp__${s.name}__${t}`) : [`mcp__${s.name}`],
449
+ );
450
+ return {
451
+ files: { [file]: JSON.stringify({ mcpServers }, null, 2) },
452
+ flags: CLAUDE.has(agentId) ? `--mcp-config ${file}` : "",
453
+ tools: CLAUDE.has(agentId) ? tools : [],
454
+ env: { ROSTER_MCP_CONFIG: file },
455
+ };
456
+ }
457
+
458
+ function codexWiring(servers, dir) {
459
+ /* Codex reads MCP servers from config.toml in CODEX_HOME, and does no `${VAR}` expansion, so
460
+ the keys have to be in the file. A fresh CODEX_HOME in the runner's temp directory holds
461
+ it: a runner has no Codex config of its own to lose, and CODEX_API_KEY still signs Codex
462
+ in from the environment, so nothing else needs to live there. */
463
+ const home = join(dir, "codex");
464
+ const lines = [];
465
+ for (const s of servers) {
466
+ lines.push(`[mcp_servers.${tomlKey(s.name)}]`);
467
+ if (s.transport === "http") {
468
+ lines.push(`url = ${toml(s.url)}`);
469
+ if (Object.keys(s.headers ?? {}).length) lines.push(`http_headers = ${toml(s.headers)}`);
470
+ } else {
471
+ lines.push(`command = ${toml(s.command)}`, `args = ${toml(s.args ?? [])}`);
472
+ if (Object.keys(s.env ?? {}).length) lines.push(`env = ${toml(s.env)}`);
473
+ }
474
+ if (s.tools) lines.push(`enabled_tools = ${toml(s.tools)}`);
475
+ lines.push("");
476
+ }
477
+ return {
478
+ files: { [join(home, "config.toml")]: lines.join("\n") },
479
+ flags: "",
480
+ tools: [],
481
+ env: { CODEX_HOME: home },
482
+ };
483
+ }
484
+
485
+ function tomlKey(k) {
486
+ return /^[A-Za-z0-9_-]+$/.test(k) ? k : JSON.stringify(k);
487
+ }
488
+
489
+ /** TOML for a string, a list or a flat table, which is all an MCP server entry holds. */
490
+ function toml(x) {
491
+ if (Array.isArray(x)) return `[${x.map(toml).join(", ")}]`;
492
+ if (x && typeof x === "object") {
493
+ return `{ ${Object.entries(x)
494
+ .map(([k, v]) => `${tomlKey(k)} = ${toml(v)}`)
495
+ .join(", ")} }`;
496
+ }
497
+ return JSON.stringify(String(x));
498
+ }
499
+
500
+ /* ------------------------------------------------------------------------------------------ */
501
+ /* A run */
502
+ /* ------------------------------------------------------------------------------------------ */
503
+
504
+ /**
505
+ * Everything one staff member's run needs, given the caller's secrets.
506
+ *
507
+ * `fetchToken` collects a signed-in connector's access token from the hosted portal; a run
508
+ * passes one, a test passes a stub. Returns the wiring and, for the summary, what was connected
509
+ * and what was left out and why.
510
+ */
511
+ export async function prepare({ org, handle, permissions, agentId, secrets, dir, fetchToken }) {
512
+ const takesTools = CLAUDE.has(agentId);
513
+ const connected = [];
514
+ const skipped = [];
515
+ const servers = [];
516
+ for (const c of connectorsOf(org, handle)) {
517
+ if (c.problem) {
518
+ skipped.push({ id: c.id, why: c.problem });
519
+ continue;
520
+ }
521
+ const readOnly = permissions === "read-only" || c.readOnly;
522
+ if (readOnly && !readOnlyMode(c, takesTools)) {
523
+ skipped.push({ id: c.id, why: `${c.name} cannot be held to reading only on ${agentId}` });
524
+ continue;
525
+ }
526
+ const values = {};
527
+ let missing = null;
528
+ if (c.auth === "oauth") {
529
+ try {
530
+ values.access_token = await fetchToken(c);
531
+ } catch (err) {
532
+ missing = `could not collect its sign-in from ${c.portal}: ${err.message}`;
533
+ }
534
+ } else {
535
+ for (const s of c.secrets) {
536
+ const v = secrets?.[s.name];
537
+ if (!v) {
538
+ missing = `no ${s.name} secret`;
539
+ break;
540
+ }
541
+ values[s.field] = v;
542
+ }
543
+ }
544
+ if (missing) {
545
+ skipped.push({ id: c.id, why: missing });
546
+ continue;
547
+ }
548
+ servers.push(serverFor(c, values, { readOnly }));
549
+ connected.push({ id: c.id, name: c.name, readOnly });
550
+ }
551
+ return { connected, skipped, wiring: wiringFor(agentId, servers, dir) };
552
+ }
553
+
554
+ /**
555
+ * A signed-in connector's access token, from the hosted portal that holds the sign-in.
556
+ *
557
+ * The run proves which repository it is with GitHub's own OIDC token, so no shared secret is
558
+ * needed and the portal can check the repo is the brain of somebody the connector is given to.
559
+ */
560
+ async function portalToken(c, env = process.env) {
561
+ const ask = env.ACTIONS_ID_TOKEN_REQUEST_URL;
562
+ const bearer = env.ACTIONS_ID_TOKEN_REQUEST_TOKEN;
563
+ if (!ask || !bearer) throw new Error("this run has no id-token permission; run roster upgrade");
564
+ const base = c.portal.replace(/\/+$/, "");
565
+ const audience = new URL(base).origin;
566
+ const idRes = await fetch(`${ask}&audience=${encodeURIComponent(audience)}`, {
567
+ headers: { authorization: `Bearer ${bearer}` },
568
+ });
569
+ if (!idRes.ok) throw new Error(`GitHub gave no id token (${idRes.status})`);
570
+ const { value } = await idRes.json();
571
+ const res = await fetch(`${base}/connectors/token`, {
572
+ method: "POST",
573
+ headers: { authorization: `Bearer ${value}`, "content-type": "application/json" },
574
+ body: JSON.stringify({ connector: c.id }),
575
+ });
576
+ const body = await res.json().catch(() => ({}));
577
+ if (!res.ok || !body.access_token) throw new Error(body.error ?? `the portal answered ${res.status}`);
578
+ return body.access_token;
579
+ }
580
+
581
+ /* ------------------------------------------------------------------------------------------ */
582
+ /* Writing org.yaml */
583
+ /* ------------------------------------------------------------------------------------------ */
584
+
585
+ /**
586
+ * org.yaml with its `connectors:` block replaced, everything else as it was.
587
+ *
588
+ * Written as text rather than re-serialised, because org.yaml is a file people edit and comment,
589
+ * and a round trip through a parser would throw their comments away. `entries` maps an id to
590
+ * what goes under it; an empty map removes the block.
591
+ */
592
+ export function withConnectors(text, entries) {
593
+ const lines = text.split("\n");
594
+ const start = lines.findIndex((l) => /^connectors:\s*(#.*)?$/.test(l));
595
+ let end = start;
596
+ if (start !== -1) {
597
+ end = start + 1;
598
+ while (end < lines.length && (lines[end] === "" || /^\s/.test(lines[end]) || /^#/.test(lines[end]))) {
599
+ if (/^#/.test(lines[end])) {
600
+ // A comment at the margin belongs to whatever follows it, unless the block goes on after.
601
+ let next = end + 1;
602
+ while (next < lines.length && /^#/.test(lines[next])) next++;
603
+ if (next >= lines.length || !/^\s/.test(lines[next])) break;
604
+ }
605
+ end++;
606
+ }
607
+ while (end > start + 1 && lines[end - 1] === "") end--;
608
+ }
609
+ const block = renderBlock(entries);
610
+ if (start === -1) {
611
+ if (!block.length) return text;
612
+ const body = text.replace(/\n+$/, "");
613
+ return `${body}\n\n${block.join("\n")}\n`;
614
+ }
615
+ const out = [...lines.slice(0, start), ...block, ...lines.slice(end)];
616
+ return out.join("\n").replace(/\n{3,}/g, "\n\n");
617
+ }
618
+
619
+ function renderBlock(entries) {
620
+ const ids = Object.keys(entries ?? {});
621
+ if (!ids.length) return [];
622
+ const out = ["connectors:"];
623
+ for (const id of ids) {
624
+ out.push(` ${id}:`);
625
+ for (const [k, v] of Object.entries(entries[id] ?? {})) {
626
+ if (v === undefined || v === null || v === "") continue;
627
+ out.push(...renderValue(k, v, 4));
628
+ }
629
+ }
630
+ return out;
631
+ }
632
+
633
+ function renderValue(key, v, indent) {
634
+ const pad = " ".repeat(indent);
635
+ if (Array.isArray(v)) return [`${pad}${key}: [${v.map(scalar).join(", ")}]`];
636
+ if (v && typeof v === "object") {
637
+ const keys = Object.keys(v);
638
+ if (!keys.length) return [];
639
+ return [`${pad}${key}:`, ...keys.flatMap((k) => renderValue(k, v[k], indent + 2))];
640
+ }
641
+ return [`${pad}${key}: ${scalar(v)}`];
642
+ }
643
+
644
+ function scalar(v) {
645
+ if (typeof v === "boolean" || typeof v === "number") return String(v);
646
+ const s = String(v);
647
+ return /^[A-Za-z0-9_./@:-]+$/.test(s) && !/^(true|false|null|~|-?\d+)$/.test(s) && !s.includes(": ")
648
+ ? s
649
+ : JSON.stringify(s);
650
+ }
651
+
652
+ /* ------------------------------------------------------------------------------------------ */
653
+ /* The runner */
654
+ /* ------------------------------------------------------------------------------------------ */
655
+
656
+ async function main(argv) {
657
+ const at = (flag) => {
658
+ const i = argv.indexOf(flag);
659
+ return i === -1 ? undefined : argv[i + 1];
660
+ };
661
+ const opsDir = at("--ops") ?? "roster-ops";
662
+ const brainsDir = at("--brains") ?? ".";
663
+ const handle = at("--staff");
664
+ const dir = resolve(at("--out") ?? join(process.env.RUNNER_TEMP ?? ".", "roster-connectors"));
665
+
666
+ const { parseYaml } = await import("./compose.mjs");
667
+ const { resolveAgent, permissionOf } = await import("./agents.mjs");
668
+ const org = parseYaml(readFileSync(join(opsDir, "org.yaml"), "utf8"), "org.yaml");
669
+ const entry = (org.staff ?? []).find((s) => s.handle === handle);
670
+ if (!entry) throw new Error(`no staff member "${handle}" in org.yaml`);
671
+ let manifest = {};
672
+ try {
673
+ manifest = parseYaml(readFileSync(join(brainsDir, entry.dir ?? entry.handle, "staff.yaml"), "utf8"), "staff.yaml");
674
+ } catch {
675
+ /* As in agents.mjs: the org's defaults still resolve without one. */
676
+ }
677
+ const agent = resolveAgent(org, manifest);
678
+ let secrets = {};
679
+ try {
680
+ secrets = JSON.parse(process.env.ROSTER_SECRETS || "{}");
681
+ } catch {
682
+ process.stderr.write("::warning::the caller's secrets did not arrive as JSON\n");
683
+ }
684
+
685
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
686
+ const { connected, skipped, wiring } = await prepare({
687
+ org,
688
+ handle,
689
+ permissions: permissionOf(org, manifest),
690
+ agentId: agent.id,
691
+ secrets,
692
+ dir,
693
+ fetchToken: (c) => portalToken(c),
694
+ });
695
+ for (const [path, text] of Object.entries(wiring.files)) writeFileSync(path, text, { mode: 0o600 });
696
+
697
+ /* What the next steps read: a manifest of flags and tools for agents.mjs, and environment
698
+ (paths only) for the agent itself. */
699
+ const manifestFile = join(dir, "wiring.json");
700
+ writeFileSync(manifestFile, JSON.stringify({ flags: wiring.flags, tools: wiring.tools }));
701
+ if (process.env.GITHUB_ENV) {
702
+ for (const [k, v] of Object.entries(wiring.env)) appendFileSync(process.env.GITHUB_ENV, `${k}=${v}\n`);
703
+ }
704
+
705
+ const lines = [
706
+ ...connected.map((c) => `- ${c.name}${c.readOnly ? " (read only)" : ""}`),
707
+ ...skipped.map((s) => `- ${s.id}: left out, ${s.why}`),
708
+ ];
709
+ if (lines.length && process.env.GITHUB_STEP_SUMMARY) {
710
+ appendFileSync(process.env.GITHUB_STEP_SUMMARY, `### Connectors\n\n${lines.join("\n")}\n`);
711
+ }
712
+ for (const s of skipped) process.stderr.write(`::warning::connector ${s.id} left out: ${s.why}\n`);
713
+ process.stdout.write(`file=${manifestFile}\nconnected=${connected.map((c) => c.id).join(",")}\n`);
714
+ }
715
+
716
+ const self = import.meta.url ? fileURLToPath(import.meta.url) : "";
717
+ if (process.argv[1] && self.endsWith("connectors.mjs") && resolve(process.argv[1]) === resolve(self)) {
718
+ main(process.argv.slice(2)).catch((err) => {
719
+ process.stderr.write(`::warning::connectors: ${err.message}\n`);
720
+ process.exit(1);
721
+ });
722
+ }