@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.
- package/dist/agents-NMGVORU3.js +232 -0
- package/dist/chunk-E3EVPK4I.js +338 -0
- package/dist/chunk-QCKEGMXD.js +562 -0
- package/dist/cli.js +1703 -820
- package/dist/compose-56JIIIHA.js +15 -0
- package/dist/connectors-ZVEPXSAR.js +23 -0
- package/dist/worker/assets/assets/css/connectors.css +50 -0
- package/dist/worker/assets/assets/js/api.js +3 -0
- package/dist/worker/assets/assets/js/app.js +4 -1
- package/dist/worker/assets/assets/js/icons.js +2 -0
- package/dist/worker/assets/assets/js/state.js +11 -1
- package/dist/worker/assets/assets/js/views/connectors.js +290 -0
- package/dist/worker/assets/index.html +4 -0
- package/dist/worker/index.js +2743 -1014
- package/docs/README.md +1 -0
- package/docs/architecture.md +1 -1
- package/docs/commands.md +37 -1
- package/docs/connectors.md +157 -0
- package/docs/cost.md +1 -1
- package/docs/developing.md +2 -2
- package/docs/doctor-codes.md +5 -1
- package/docs/export.md +1 -1
- package/docs/extending.md +1 -1
- package/docs/hosting.md +13 -1
- package/docs/memory.md +1 -1
- package/docs/org-yaml.md +25 -1
- package/docs/portal.md +18 -1
- package/docs/prompts.md +1 -1
- package/docs/security.md +17 -1
- package/docs/session-workflow.md +23 -5
- package/docs/staff-yaml.md +1 -1
- package/docs/troubleshooting.md +1 -1
- package/docs/upgrading.md +1 -1
- package/docs/writing-a-charter.md +1 -1
- package/package.json +2 -1
- package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +8 -6
- package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +8 -6
- package/templates/ops/.github/workflows/session.yaml +52 -11
- package/templates/ops/agents.mjs +38 -11
- package/templates/ops/compose.mjs +12 -0
- package/templates/ops/connectors.mjs +722 -0
- package/templates/ops/prompts/_identity.md +14 -0
- package/templates/portal/css/connectors.css +50 -0
- package/templates/portal/index.html +4 -0
- package/templates/portal/js/api.js +3 -0
- package/templates/portal/js/app.js +4 -1
- package/templates/portal/js/icons.js +2 -0
- package/templates/portal/js/state.js +11 -1
- 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. |
|
package/docs/architecture.md
CHANGED
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:
|
|
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
package/docs/developing.md
CHANGED
|
@@ -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:
|
|
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
|
package/docs/doctor-codes.md
CHANGED
|
@@ -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:
|
|
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
package/docs/extending.md
CHANGED
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:
|
|
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
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:
|
|
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:
|
|
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
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:
|
|
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
|
package/docs/session-workflow.md
CHANGED
|
@@ -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:
|
|
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. **
|
|
85
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
package/docs/staff-yaml.md
CHANGED
package/docs/troubleshooting.md
CHANGED
package/docs/upgrading.md
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nanocollective/roster",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
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
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|