@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
package/docs/README.md CHANGED
@@ -28,6 +28,7 @@ Read in this order.
28
28
  | [Manual steps](manual-steps.md) | What only a person can do, why, and what breaks if it is skipped. |
29
29
  | [Concepts](concepts.md) | The three things you need to know, then the detail. |
30
30
  | [Choosing a coding agent](agents.md) | Claude, Codex, Nanocoder, or anything with a command line. |
31
+ | [Connectors](connectors.md) | Give staff outside services: Sentry, Linear, Stripe and more. |
31
32
  | [Writing a charter](writing-a-charter.md) | The one file nothing can generate for you. |
32
33
  | [Extending it](extending.md) | The four seams, and which one to reach for. |
33
34
  | [Memory](memory.md) | The grammar, and why deleting is the maintenance. |
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Architecture"
3
3
  description: "What happens during a run, and the constraint that decided the design."
4
- sidebar_order: 20
4
+ sidebar_order: 21
5
5
  ---
6
6
 
7
7
  # Architecture
package/docs/commands.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Commands"
3
3
  description: "Every CLI command and flag."
4
- sidebar_order: 8
4
+ sidebar_order: 9
5
5
  ---
6
6
 
7
7
  # Commands
@@ -128,6 +128,42 @@ claude setup-token # Claude Code; see docs/agents.md for the others
128
128
  roster credential --apply
129
129
  ```
130
130
 
131
+ ## `roster connector`
132
+
133
+ Give staff an outside service to use in their runs, as an MCP server. See
134
+ [connectors](connectors.md).
135
+
136
+ ```
137
+ roster connector [list]
138
+ roster connector add <name> [--staff <handles>] [--read-only] [--set <field=value>] [--apply]
139
+ roster connector remove <name> [--apply]
140
+ ```
141
+
142
+ ```
143
+ --staff <handles> who gets it, comma separated (default: the catalogue's suggestion)
144
+ --read-only hold it to reading, for everybody who has it
145
+ --set <field=value> a setting the service needs, such as --set project_ref=abc123
146
+ --url <url> a service roster does not know: its MCP server's URL
147
+ --command <line> or the command that starts it
148
+ --secret <NAME> a key that service needs, by the name it is given (repeatable)
149
+ --keep-key change who has it without asking for the key again
150
+ --apply do it
151
+ ```
152
+
153
+ `list` shows the services roster knows and the ones this org has, with who has each and whether
154
+ its key is stored. `add` asks for the key at a prompt that does not echo, checks it with the
155
+ service, stores it as a GitHub secret every brain repo can read, and commits `org.yaml`. A key
156
+ the service rejects is not stored. `remove` deletes the keys and takes the connector out of
157
+ `org.yaml`.
158
+
159
+ ```bash
160
+ roster connector add sentry --staff cto --apply
161
+ roster connector add supabase --set project_ref=abc123 --read-only --apply
162
+ ```
163
+
164
+ Notion's hosted server signs in with a browser, so it is added from the hosted portal's
165
+ Connectors page.
166
+
131
167
  ## `roster run <handle>`
132
168
 
133
169
  Start one daily run now and follow it to the end.
@@ -0,0 +1,157 @@
1
+ ---
2
+ title: "Connectors"
3
+ description: "Give staff outside services, like Sentry, Linear or Stripe, to use in their runs."
4
+ sidebar_order: 5
5
+ ---
6
+
7
+ # Connectors
8
+
9
+ A connector gives staff an outside service to use in their runs: errors from Sentry, issues in
10
+ Linear, payments in Stripe. Each one is an [MCP](https://modelcontextprotocol.io) server, and the
11
+ staff member's coding agent calls it like any other tool.
12
+
13
+ Add one from the portal's **Connectors** screen: pick the service, follow the steps to get a key,
14
+ paste it, tick who can use it, and save. Or from a terminal:
15
+
16
+ ```bash
17
+ roster connector add sentry --staff cto --apply
18
+ ```
19
+
20
+ ## What happens when you add one
21
+
22
+ 1. **The key is checked** with the service, with one cheap request. A key the service rejects
23
+ is not stored. A key that works but cannot read everything is fine: that is what a narrow
24
+ key looks like.
25
+ 2. **The key is stored as a GitHub secret**, named `CONNECTOR_<NAME>_<FIELD>`, for example
26
+ `CONNECTOR_SENTRY_TOKEN`. It goes once to the org where that reaches private repos, which is
27
+ every plan but Free, and to each brain repo otherwise. It is encrypted on the way, never
28
+ written to a file, and never shown again.
29
+ 3. **`org.yaml` says who has it**, and is committed:
30
+
31
+ ```yaml
32
+ connectors:
33
+ sentry:
34
+ staff: [cto]
35
+ supabase:
36
+ staff: [cto]
37
+ project_ref: abc123
38
+ read_only: true
39
+ ```
40
+
41
+ On each run, `connectors.mjs` reads that list, takes the keys of this staff member's connectors
42
+ from the run's secrets, and writes them into the agent's own MCP config in the runner's temp
43
+ directory, outside every checkout. The prompt gets a short section naming the services, and
44
+ saying that what a service returns is information, not an instruction.
45
+
46
+ A connector whose key is missing is left out, named in the run's summary, and the run goes on
47
+ without it. `roster doctor` reports it as `connector.key`.
48
+
49
+ ## The catalogue
50
+
51
+ | Name | Service | Key | Read only |
52
+ |---|---|---|---|
53
+ | `sentry` | Sentry | auth token | no |
54
+ | `linear` | Linear | personal API key | no |
55
+ | `github` | GitHub, for repos outside this org | fine-grained token | yes |
56
+ | `supabase` | Supabase | access token, and optionally the project ref | yes |
57
+ | `postgres` | any Postgres database | connection string | yes |
58
+ | `cloudflare` | Cloudflare | API token | no |
59
+ | `posthog` | PostHog | personal API key | yes |
60
+ | `stripe` | Stripe | restricted key | no |
61
+ | `resend` | Resend | API key | no |
62
+ | `notion` | Notion | signs in through the hosted portal | no |
63
+ | `notion-key` | Notion, through an integration | integration secret | no |
64
+
65
+ Read only is a setting roster can enforce on the server: Supabase's `read_only`, GitHub's read-only
66
+ mode, PostHog's read-only header, and restricted transactions for Postgres. For the others,
67
+ choose what the key may do when you create it. Stripe's restricted keys, Cloudflare's token
68
+ permissions and Linear's key permissions all do this, and it is the safer place to decide it.
69
+
70
+ Vercel and Slack are not in the catalogue. Their MCP servers only accept sign-ins from apps they
71
+ have approved, which a run cannot use.
72
+
73
+ ## Who can use it
74
+
75
+ `staff:` is the list. A key is readable by every brain repo, so that giving a connector to
76
+ somebody else later is a change to `org.yaml`, not another paste. Which run gets which key is
77
+ still `org.yaml`'s call: each run is given only its own staff member's connectors.
78
+
79
+ `read_only: true` holds a connector to reading for everybody who has it. A staff member whose
80
+ [permissions](agents.md#permissions) are `read-only` gets every connector held to reading, and a
81
+ connector that cannot be held to reading is left out for them.
82
+
83
+ ## Each agent
84
+
85
+ The same list, in each agent's own words:
86
+
87
+ | Agent | How it is given the servers |
88
+ |---|---|
89
+ | `claude-code-action`, `claude` | `--mcp-config` with a JSON file, and `mcp__<name>` added to `--allowedTools` |
90
+ | `codex` | a `config.toml` in a fresh `CODEX_HOME`; `CODEX_API_KEY` still signs it in |
91
+ | `nanocoder` | `NANOCODER_MCPSERVERS_FILE`, pointing at its own format |
92
+
93
+ Nanocoder only shows MCP tools to a model whose tool profile resolves to `full`. A small local
94
+ model may not see them.
95
+
96
+ ## Signing in: Notion
97
+
98
+ Notion's hosted MCP server takes no key: it signs in with a browser. A run cannot do that, so the
99
+ [hosted portal](hosting.md) does it once and keeps the sign-in:
100
+
101
+ 1. On the Connectors screen, pick Notion, tick who can use it, and press **Sign in to Notion**.
102
+ 2. Notion asks which pages to share. The portal keeps the sign-in, sealed under its session key,
103
+ in a KV namespace of its own.
104
+ 3. Each run asks the portal for a fresh access token. It proves which run it is with GitHub's own
105
+ OIDC token, and the portal only answers a run of this org's `session.yaml`. No secret is
106
+ shared with the run to make that work.
107
+
108
+ This needs the hosted portal, with a KV namespace bound as `CONNECTORS`. `roster portal deploy`
109
+ creates one. A sign-in Notion has not used for 30 days, or one older than 180 days, has to be
110
+ done again; the Connectors screen says so.
111
+
112
+ Without the hosted portal, use `notion-key`: an internal integration's secret, pasted like any
113
+ other key.
114
+
115
+ ## A service that is not in the catalogue
116
+
117
+ Write it out in `org.yaml`, with a `url` or a `command`, and the names of the keys it needs:
118
+
119
+ ```yaml
120
+ connectors:
121
+ acme-api:
122
+ staff: [cto]
123
+ url: https://mcp.acme.dev/mcp
124
+ secrets: [TOKEN]
125
+ headers:
126
+ Authorization: "Bearer ${TOKEN}"
127
+ local-thing:
128
+ staff: [cmo]
129
+ command: npx -y @acme/mcp-server
130
+ secrets: [API_KEY]
131
+ env:
132
+ ACME_API_KEY: "${API_KEY}"
133
+ ```
134
+
135
+ `${TOKEN}` is replaced with the secret `CONNECTOR_ACME_API_TOKEN` in the run. Store it with:
136
+
137
+ ```bash
138
+ roster connector add acme-api --url https://mcp.acme.dev/mcp --secret TOKEN --apply
139
+ ```
140
+
141
+ A name is lower case letters, digits and `-`, because it becomes part of each tool's name.
142
+
143
+ ## Safety
144
+
145
+ - Text a service returns is treated as information. The prompt says so, and says that anything
146
+ acting in public under your name, like sending an email or charging a customer, needs a
147
+ `decision` issue first.
148
+ - Give each key the least it needs. A read-only key is a limit no prompt can talk its way past.
149
+ - The agent can read its own MCP config, and so its keys, in the run. Treat a connector's key as
150
+ given to the staff members who have it.
151
+ - Removing a connector deletes its keys and its sign-in, and takes it out of `org.yaml`.
152
+
153
+ ## Callers from before connectors
154
+
155
+ Keys reach a run because the callers pass their secrets on with `secrets: inherit`. Callers
156
+ generated before connectors map their secrets by hand, so no connector's key reaches them;
157
+ `roster doctor` reports it as `connector.caller`, and `roster upgrade --apply` regenerates them.
package/docs/cost.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Cost"
3
3
  description: "What an agent-run org spends, and on what."
4
- sidebar_order: 12
4
+ sidebar_order: 13
5
5
  ---
6
6
 
7
7
  # Cost
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Working on roster itself"
3
3
  description: "Layout, template classes, and the rules that matter."
4
- sidebar_order: 22
4
+ sidebar_order: 23
5
5
  ---
6
6
 
7
7
  # Working on roster itself
@@ -80,7 +80,7 @@ registers into at boot.
80
80
 
81
81
  ## The rule that matters
82
82
 
83
- **Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `runner-plan.mjs`,
83
+ **Never fix a generated file in a tenant.** `compose.mjs`, `agents.mjs`, `connectors.mjs`, `runner-plan.mjs`,
84
84
  `inflight.mjs`, `run-record.mjs`, `status-week.mjs` and `session.yaml` live in `templates/ops/`. Fix them there and run `roster upgrade`.
85
85
 
86
86
  A fix made in the tenant's copy goes unnoticed until the framework next touches that file, and
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "doctor codes"
3
3
  description: "Every finding roster doctor can emit, what it means, and what to do."
4
- sidebar_order: 19
4
+ sidebar_order: 20
5
5
  ---
6
6
 
7
7
  # doctor codes
@@ -31,6 +31,8 @@ ran at all.
31
31
  | `repo.visibility` | A repo's real visibility disagrees with what `org.yaml` records. Cosmetic, but the posture it records is then fiction. |
32
32
  | `agent` | Which runner this org uses, resolved from the tenant's own `agents.mjs`. **fail** if `org.yaml` names one it does not know. |
33
33
  | `agent.config` | **fail.** The agent needs a config file of its own and it is missing, or still has a `FILL IN` in it. Nanocoder is the one preset that does: it is a client rather than a model, so without a provider it starts, finds nothing to call, and exits. |
34
+ | `connector` | Each [connector](connectors.md) in `org.yaml` is usable: in the catalogue or written out with a `url` or `command`, with any setting it needs. A run leaves out one that is not. |
35
+ | `connector.staff` | A connector is given to a handle that is not one of the staff. |
34
36
  | `business` | **fail** if `org/business.md` is missing. Every prompt is composed on top of it. |
35
37
  | `business.stub` | `org/business.md` is still the questions it shipped with. Nothing errors; the agents just write competent work about a business that does not exist. |
36
38
  | `priorities` | No `org/priorities.md`. Nothing breaks; each staff member just picks its own direction. See [concepts](concepts.md#priorities). |
@@ -58,6 +60,8 @@ ran at all.
58
60
  | `memory` | `memory/INDEX.md` parses, and how many facts and notes it holds. |
59
61
  | `compose` | All three prompts compose. A failure names the kind and the placeholder. |
60
62
  | `callers` | Three caller workflows exist. |
63
+ | `connector.key` | A connector this staff member has has no key on their brain repo, neither its own secret nor one shared from the org. The run goes ahead without it. |
64
+ | `connector.caller` | This staff member has connectors, and their callers were generated before connectors: they map their secrets by hand rather than passing them on, so no key reaches a run. `roster upgrade --apply`. |
61
65
  | `callers.uses` | **fail.** A caller references no reusable workflow, or one in a different organisation. A private reusable workflow is only callable inside its own org. |
62
66
  | `callers.target` | **fail.** A caller points at a workflow file that is not in the ops repo. Fails at run time as "workflow not found". |
63
67
  | `surfaces` | A surface declared in `staff.yaml` is not on disk. The portal renders nothing for it. |
package/docs/export.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "roster export reference"
3
3
  description: "The JSON shape, field by field."
4
- sidebar_order: 18
4
+ sidebar_order: 19
5
5
  ---
6
6
 
7
7
  # `roster export` reference
package/docs/extending.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Extending it"
3
3
  description: "The four seams, and which one to reach for."
4
- sidebar_order: 6
4
+ sidebar_order: 7
5
5
  ---
6
6
 
7
7
  # Extending it for your business
package/docs/hosting.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Hosting the portal"
3
3
  description: "The portal on your own URL, behind Sign in with GitHub, redeploying itself."
4
- sidebar_order: 11
4
+ sidebar_order: 12
5
5
  ---
6
6
 
7
7
  # Hosting the portal
@@ -132,6 +132,18 @@ On your machine it is `~/.cache/roster`. On Cloudflare it is the edge cache, whi
132
132
  setup. To keep it everywhere rather than per data centre, bind a KV namespace as `CACHE` in
133
133
  `portal/wrangler.jsonc`.
134
134
 
135
+ ## Signed-in connectors
136
+
137
+ A [connector](connectors.md) that signs in with a browser, like Notion, keeps its sign-in on the
138
+ hosted portal, which needs somewhere durable to keep it: a KV namespace bound as `CONNECTORS`.
139
+ `roster portal deploy` finds one by name, or creates it, on any deploy that does not have it
140
+ bound yet, the morning one included; a deploy by hand also writes it into
141
+ `portal/wrangler.jsonc`. Without it, connectors that take a key still work, and the ones that
142
+ sign in are not offered.
143
+
144
+ A run collects a fresh access token from `/connectors/token`, proving with GitHub's OIDC token
145
+ that it is a run of this org's `session.yaml`.
146
+
135
147
  ## On your machine
136
148
 
137
149
  `roster portal` binds to `127.0.0.1` and acts as whoever `gh` is signed in as. To open an org
package/docs/memory.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Memory"
3
3
  description: "The grammar, the five rules, and why deleting is the maintenance."
4
- sidebar_order: 7
4
+ sidebar_order: 8
5
5
  ---
6
6
 
7
7
  # Memory
package/docs/org-yaml.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "org.yaml reference"
3
3
  description: "Every field in the org manifest, and what reads it."
4
- sidebar_order: 13
4
+ sidebar_order: 14
5
5
  ---
6
6
 
7
7
  # `org.yaml` reference
@@ -64,6 +64,30 @@ repos:
64
64
  | `budget` | no | USD over any trailing 30 days, for the whole org. See [below](#budget). |
65
65
  | `review_gate` | no | `true` to have GitHub require a reviewed pull request before anything merges into a product repo. Off by default, because private repos need a paid plan for it. See [security](security.md#the-review-gate). |
66
66
 
67
+ ### `connectors`
68
+
69
+ Outside services staff can use in their runs, by name, with who has each. Keys are never here:
70
+ they are GitHub secrets. See [connectors](connectors.md).
71
+
72
+ ```yaml
73
+ connectors:
74
+ sentry:
75
+ staff: [cto]
76
+ supabase:
77
+ staff: [cto]
78
+ project_ref: abc123
79
+ read_only: true
80
+ ```
81
+
82
+ | Field | Required | Means |
83
+ |---|---|---|
84
+ | `staff` | yes | Handles of the staff who can use it. |
85
+ | `read_only` | no | `true` to hold it to reading for everybody who has it. |
86
+ | `portal` | for a sign-in | The hosted portal that keeps its sign-in. Written by the portal. |
87
+ | `url`, `command`, `secrets`, `headers`, `env` | for a service not in the catalogue | See [connectors](connectors.md#a-service-that-is-not-in-the-catalogue). |
88
+
89
+ Anything else is a setting the service needs, such as Supabase's `project_ref`.
90
+
67
91
  ### `human` and `humans`
68
92
 
69
93
  Who the staff answer to. One person is a `human` map; more than one is a `humans` list:
package/docs/portal.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "The portal"
3
3
  description: "Every view and every action."
4
- sidebar_order: 17
4
+ sidebar_order: 18
5
5
  ---
6
6
 
7
7
  # The portal
@@ -402,6 +402,23 @@ from `org.yaml` and from every peer, and deletes the dead `from-<handle>` labels
402
402
  what it keeps as prominently as what it stops, because that is the thing you have to believe
403
403
  before clicking it.
404
404
 
405
+ ## Connectors
406
+
407
+ Outside services the staff can use in their runs: Sentry, Linear, Stripe and the rest of the
408
+ [catalogue](connectors.md#the-catalogue).
409
+
410
+ What is connected is a list: each service, who can use it, and whether its key is stored. **Edit**
411
+ changes who can use it, or replaces the key; **Remove** asks once more, then deletes the keys and
412
+ takes it out of `org.yaml`.
413
+
414
+ Below it is every service you can add. Picking one opens a sheet with the steps to get a key, a
415
+ link to the right settings page, the key, and who can use it, ticked for the roles that usually
416
+ want it. **Check key** asks the service whether the key works before anything is stored. **Save**
417
+ checks it again, stores it as a GitHub secret and commits `org.yaml`.
418
+
419
+ Notion signs in instead, on the [hosted portal](hosting.md) only: **Sign in to Notion** goes to
420
+ Notion and comes back here.
421
+
405
422
  ## Brain
406
423
 
407
424
  Memory and the file tree, merged, because they were always the same thing: both manifests
package/docs/prompts.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Prompt reference"
3
3
  description: "The template syntax, the context, and what has to be guarded."
4
- sidebar_order: 15
4
+ sidebar_order: 16
5
5
  ---
6
6
 
7
7
  # Prompt reference
package/docs/security.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Security model"
3
3
  description: "What can reach what, what stops it, and what is not defended against."
4
- sidebar_order: 21
4
+ sidebar_order: 22
5
5
  ---
6
6
 
7
7
  # Security model
@@ -177,6 +177,22 @@ the org.
177
177
  tokens cannot read notifications, and unread in the portal is GitHub's own unread, kept in step
178
178
  with the website and your phone.
179
179
 
180
+ ## Connectors
181
+
182
+ A [connector](connectors.md)'s key is a GitHub secret every brain repo can read, encrypted to
183
+ GitHub's key by the portal or the CLI before it leaves your machine. It reaches a run because the
184
+ callers pass their secrets on with `secrets: inherit`. Inside the run, one step reads them
185
+ (`connectors.mjs`) and writes only this staff member's connectors' keys into the agent's MCP
186
+ config, in the runner's temp directory. No other step, and no agent, sees the rest.
187
+
188
+ The agent can read that config, so treat a key as given to the staff members who have it, and
189
+ give it the least it needs: a read-only key is a limit no prompt can argue with.
190
+
191
+ A signed-in connector's refresh token stays on the hosted portal, sealed under its session key.
192
+ A run gets a short-lived access token, and only after proving with GitHub's OIDC token that it is
193
+ a job of this org's `session.yaml`; a token minted for any other audience, workflow or org is
194
+ refused.
195
+
180
196
  ## Trust in a prompt
181
197
 
182
198
  Everything composed into a prompt is content you or your agents wrote: `org/`, the charter, the
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "The session workflow"
3
3
  description: "Inputs, secrets, and what runs in what order."
4
- sidebar_order: 16
4
+ sidebar_order: 17
5
5
  ---
6
6
 
7
7
  # The session workflow
@@ -35,9 +35,20 @@ repositories in this organisation**. Without it, callers fail with "workflow not
35
35
  | `comment_id` | string | `""` | Trigger context. |
36
36
  | `trigger` | string | `""` | What started the run: `daily`, `manual`, `follow-on`, `mention` or `peer`. Passed to the prompt. |
37
37
  | `max_runs_per_day` | number | `6` | How many `peer` and `follow-on` runs may start in a UTC day. Mentions are never counted. |
38
+ | `secret_prefix` | string | `""` | The prefix of this staff member's App secrets, so `CTO` reads `CTO_APP_ID`. |
39
+ | `public_secret_prefix` | string | `""` | The same for the public App. |
40
+ | `agent_secret` | string | `""` | The name of the secret holding the agent's credential. |
38
41
 
39
42
  ## Secrets
40
43
 
44
+ A caller passes `secrets: inherit`, so every secret the brain repo can read reaches the session
45
+ under its own name. That is what lets a [connector](connectors.md)'s key reach a run without
46
+ the caller naming it. Inheriting cannot rename, so the three inputs above say which names are
47
+ this staff member's: `secret_prefix: CTO` means `CTO_APP_ID` and `CTO_APP_PRIVATE_KEY`.
48
+
49
+ A caller generated before connectors maps its secrets by hand instead, under the names below,
50
+ and those are read first. Both kinds work against the same `session.yaml`.
51
+
41
52
  | Secret | Required | Means |
42
53
  |---|---|---|
43
54
  | `APP_ID` | yes | This staff member's own App. |
@@ -81,17 +92,22 @@ Then the session:
81
92
  Never fatal. See [architecture](architecture.md#the-weeks-status-issue).
82
93
  13. **Compose the prompt**, to a step output and to `.roster-prompt.txt`.
83
94
  14. **Check the agent has a credential.**
84
- 15. **Work out which agent runs this**, by running `agents.mjs`.
85
- 16. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
95
+ 15. **Connect services**, by running `connectors.mjs`: each [connector](connectors.md) this
96
+ staff member has, written as the agent's own MCP config in the runner's temp directory,
97
+ with its key read from the inherited secrets. Never fatal: one without its key is left out
98
+ and named in the job summary.
99
+ 16. **Work out which agent runs this**, by running `agents.mjs`, which adds the connectors'
100
+ tools to the agent's allowlist.
101
+ 17. **Run the session**, by one of two steps: the Action-based reference runner, or the generic
86
102
  CLI one. See [choosing a coding agent](agents.md).
87
103
  Then, for a mention, **check the request was answered**: a reply in the thread, or the issue
88
104
  closed. Neither fails the job, so the notice below tells the human.
89
105
  Then, for a daily run that finished and wrote `.roster-run/continue`, **start a follow-on
90
106
  run**: one more daily run with `trigger: follow-on`, which waits for this one to end.
91
- 17. **Write down the run**, whatever happened: staff, kind, outcome, duration, and turns, cost
107
+ 18. **Write down the run**, whatever happened: staff, kind, outcome, duration, and turns, cost
92
108
  and tokens where the agent reports them. Into the job summary, and kept as an artifact
93
109
  called `roster-run`. Never fatal. See [cost](cost.md#what-each-run-cost).
94
- 18. **Say so if the run did not finish.** A comment on the status issue, or on the issue that
110
+ 19. **Say so if the run did not finish.** A comment on the status issue, or on the issue that
95
111
  woke a mention, linking the run.
96
112
 
97
113
  ## When the failure is the token
@@ -111,6 +127,8 @@ jobs:
111
127
  permissions:
112
128
  contents: read
113
129
  issues: write
130
+ actions: write
131
+ id-token: write
114
132
  uses: acme/roster-ops/.github/workflows/session.yaml@main
115
133
  ```
116
134
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "staff.yaml reference"
3
3
  description: "Every field in a staff member's manifest."
4
- sidebar_order: 14
4
+ sidebar_order: 15
5
5
  ---
6
6
 
7
7
  # `staff.yaml` reference
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Troubleshooting"
3
3
  description: "Every trap we have actually hit, and what it looks like from the outside."
4
- sidebar_order: 10
4
+ sidebar_order: 11
5
5
  ---
6
6
 
7
7
  # Troubleshooting
package/docs/upgrading.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Upgrading"
3
3
  description: "How framework changes reach a tenant without eating your edits."
4
- sidebar_order: 9
4
+ sidebar_order: 10
5
5
  ---
6
6
 
7
7
  # Upgrading
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  title: "Writing a charter"
3
3
  description: "The one file nothing can generate for you, and the shape that has worked."
4
- sidebar_order: 5
4
+ sidebar_order: 6
5
5
  ---
6
6
 
7
7
  # Writing a charter
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nanocollective/roster",
3
- "version": "0.1.0-beta.14",
3
+ "version": "0.1.0-beta.16",
4
4
  "description": "An agent-run org, powered by GitHub. Scaffold AI staff members whose brain is a repo.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -39,6 +39,7 @@
39
39
  "@types/node": "^22.10.2",
40
40
  "c8": "^12.0.0",
41
41
  "knip": "^6.34.0",
42
+ "libsodium-wrappers": "^0.8.4",
42
43
  "tsup": "^8.3.5",
43
44
  "tsx": "^4.19.2",
44
45
  "typescript": "^5.7.2"
@@ -41,6 +41,7 @@ jobs:
41
41
  contents: read
42
42
  issues: write
43
43
  actions: write
44
+ id-token: write
44
45
  uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
45
46
  with:
46
47
  staff: %%STAFF%%
@@ -51,9 +52,10 @@ jobs:
51
52
  model: %%MODEL%%
52
53
  timeout_minutes: %%TIMEOUT%%
53
54
  allowed_tools: "%%ALLOWED_TOOLS%%"
54
- secrets:
55
- APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
56
- APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}
57
- PUBLIC_APP_ID: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_ID }}
58
- PUBLIC_APP_PRIVATE_KEY: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_PRIVATE_KEY }}
59
- AGENT_TOKEN: ${{ secrets.%%AGENT_SECRET%% }}
55
+ secret_prefix: %%SECRET_PREFIX%%
56
+ public_secret_prefix: %%PUBLIC_SECRET_PREFIX%%
57
+ agent_secret: %%AGENT_SECRET%%
58
+ # Inherited rather than listed, so a connector's key added later reaches the run without
59
+ # this file changing. session.yaml reads the App's pair and the agent credential by the
60
+ # names above, and each connector's key by the name its connector gives it.
61
+ secrets: inherit
@@ -97,6 +97,7 @@ jobs:
97
97
  contents: read
98
98
  issues: write
99
99
  actions: write
100
+ id-token: write
100
101
  uses: %%OPS_REPO%%/.github/workflows/session.yaml@main
101
102
  with:
102
103
  staff: %%STAFF%%
@@ -109,9 +110,10 @@ jobs:
109
110
  allowed_tools: "%%ALLOWED_TOOLS%%"
110
111
  issue_number: ${{ github.event.issue.number }}
111
112
  comment_id: ${{ github.event.comment.id }}
112
- secrets:
113
- APP_ID: ${{ secrets.%%SECRET_PREFIX%%_APP_ID }}
114
- APP_PRIVATE_KEY: ${{ secrets.%%SECRET_PREFIX%%_APP_PRIVATE_KEY }}
115
- PUBLIC_APP_ID: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_ID }}
116
- PUBLIC_APP_PRIVATE_KEY: ${{ secrets.%%PUBLIC_SECRET_PREFIX%%_APP_PRIVATE_KEY }}
117
- AGENT_TOKEN: ${{ secrets.%%AGENT_SECRET%% }}
113
+ secret_prefix: %%SECRET_PREFIX%%
114
+ public_secret_prefix: %%PUBLIC_SECRET_PREFIX%%
115
+ agent_secret: %%AGENT_SECRET%%
116
+ # Inherited rather than listed, so a connector's key added later reaches the run without
117
+ # this file changing. session.yaml reads the App's pair and the agent credential by the
118
+ # names above, and each connector's key by the name its connector gives it.
119
+ secrets: inherit