@nanocollective/roster 0.1.0-beta.13 → 0.1.0-beta.15
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 +1731 -830
- 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 +2786 -1028
- 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 +6 -2
- package/docs/export.md +2 -2
- package/docs/extending.md +1 -1
- package/docs/hosting.md +14 -1
- package/docs/memory.md +1 -1
- package/docs/org-yaml.md +33 -1
- package/docs/portal.md +18 -1
- package/docs/prompts.md +3 -2
- 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 +20 -2
- package/templates/ops/connectors.mjs +722 -0
- package/templates/ops/prompts/_identity.md +20 -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
|
|
@@ -25,12 +25,14 @@ ran at all.
|
|
|
25
25
|
|---|---|
|
|
26
26
|
| `gh` | Whether `gh` is installed and authenticated. A warning here means every network check was skipped, not that anything is wrong. |
|
|
27
27
|
| `org.yaml` | The org manifest parsed, and how much it declares. |
|
|
28
|
-
| `human` | **fail.** `org.yaml` names nobody with a `github` login, in either `human` or `humans`. The mention callers gate on those logins, so nothing can wake an agent. |
|
|
28
|
+
| `human` | **fail.** `org.yaml` names nobody with a `github` login, in either `human` or `humans`, who is not `view_only`. The mention callers gate on those logins, so nothing can wake an agent. |
|
|
29
29
|
| `human.login` | One of the people in `humans` has a name but no `github` login. They read as somebody the staff answer to and are not: the gate can never match them. |
|
|
30
30
|
| `repo` | Every repo in `org.yaml` is reachable. A failure means it does not exist or your `gh` cannot see it. |
|
|
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:
|
|
4
|
+
sidebar_order: 19
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# `roster export` reference
|
|
@@ -23,7 +23,7 @@ that reads it gets the same view without reimplementing the memory grammar.
|
|
|
23
23
|
| `name` | the business name |
|
|
24
24
|
| `opsName` | the ops repo's directory, so a consumer can address `org.yaml` and `org/*.md` by path |
|
|
25
25
|
| `human` | the first human, normalised: `{ github, name, marker, role }`. Kept for consumers written when an org had exactly one |
|
|
26
|
-
| `humans[]` | everyone the staff answer to, in order, read from `humans` or the singular `human`. `human` is `humans[0]` |
|
|
26
|
+
| `humans[]` | everyone the staff answer to, in order, read from `humans` or the singular `human`, leaving out anyone `view_only`. `human` is `humans[0]` |
|
|
27
27
|
| `generatedAt` | ISO timestamp |
|
|
28
28
|
| `staff[]` | one entry per staff member |
|
|
29
29
|
|
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
|
|
@@ -35,6 +35,8 @@ does. That is not something to put behind a public URL.
|
|
|
35
35
|
## Who can get in
|
|
36
36
|
|
|
37
37
|
Only the people listed under `humans:` in `org.yaml`, signed in with their own GitHub account.
|
|
38
|
+
That includes anyone marked `view_only`, who can read everything and wake nobody; see
|
|
39
|
+
[org.yaml](org-yaml.md#human-and-humans).
|
|
38
40
|
|
|
39
41
|
- Sign-in is GitHub's own OAuth flow, through an OAuth App your org creates for the portal.
|
|
40
42
|
The token it hands back is that person's, scoped `repo` and `notifications`, the same kind
|
|
@@ -130,6 +132,17 @@ On your machine it is `~/.cache/roster`. On Cloudflare it is the edge cache, whi
|
|
|
130
132
|
setup. To keep it everywhere rather than per data centre, bind a KV namespace as `CACHE` in
|
|
131
133
|
`portal/wrangler.jsonc`.
|
|
132
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` creates one the first time it runs by hand, and writes it into
|
|
140
|
+
`portal/wrangler.jsonc`. Without it, connectors that take a key still work, and the ones that
|
|
141
|
+
sign in are not offered.
|
|
142
|
+
|
|
143
|
+
A run collects a fresh access token from `/connectors/token`, proving with GitHub's OIDC token
|
|
144
|
+
that it is a run of this org's `session.yaml`.
|
|
145
|
+
|
|
133
146
|
## On your machine
|
|
134
147
|
|
|
135
148
|
`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:
|
|
@@ -80,6 +104,7 @@ humans:
|
|
|
80
104
|
| `name` | no | What to call them in prose. Defaults to the login. |
|
|
81
105
|
| `marker` | no | Provenance tag on a fact they ruled on, as in `[will]`. Also used as a label. Defaults to the first part of the name, lowercased. |
|
|
82
106
|
| `role` | no | Prose only. |
|
|
107
|
+
| `view_only` | no | `true` for somebody who should see how the org runs and nothing more. See below. |
|
|
83
108
|
|
|
84
109
|
Both keys are read, and the singular is not deprecated: an org with one human should keep
|
|
85
110
|
writing `human`. When both are present, anyone in `human` who is not already in the list is
|
|
@@ -91,6 +116,13 @@ here"), and a list of two cannot go in that sentence, so the first one goes ther
|
|
|
91
116
|
`{{humans_extra}}` in the identity fragment. Everything that *gates* on identity reads all of
|
|
92
117
|
them: the mention caller's `if:` is `contains(fromJSON('["will-lamerton","sam-x"]'), …)`.
|
|
93
118
|
|
|
119
|
+
**View-only.** `{ name: Ben, github: ben-x, view_only: true }` signs in to the portal and the
|
|
120
|
+
Claude connector like anyone in the list, and reads everything there. They are not in the mention
|
|
121
|
+
gate, so an `@cto` from them wakes nobody, and the portal refuses to post one rather than leave
|
|
122
|
+
them waiting. The staff prompts name them only to say that nothing they write is a ruling, and
|
|
123
|
+
that nothing needing a human goes to them. A view-only person is never the primary, wherever they
|
|
124
|
+
are in the list. What they can do on GitHub itself is still whatever their access there allows.
|
|
125
|
+
|
|
94
126
|
Adding a human changes every generated caller workflow, so it takes a `roster upgrade` to reach
|
|
95
127
|
the brain repos. Until that lands, the new person can open issues and read everything, and
|
|
96
128
|
mentioning a staff member does nothing.
|
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
|
@@ -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:
|
|
4
|
+
sidebar_order: 16
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Prompt reference
|
|
@@ -91,11 +91,12 @@ than a hang.
|
|
|
91
91
|
|---|---|
|
|
92
92
|
| `org` | the whole of `org.yaml` |
|
|
93
93
|
| `org.name`, `org.org` | the business name, the GitHub org |
|
|
94
|
-
| `human` | the primary human: the first of `humans
|
|
94
|
+
| `human` | the primary human: the first of `humans` who is not view-only, or the singular `human` block |
|
|
95
95
|
| `human.name`, `human.github`, `human.marker` | |
|
|
96
96
|
| `humans` | everyone the staff answer to, in order. See [org.yaml](org-yaml.md#human-and-humans) |
|
|
97
97
|
| `human_list` | all of them as a sentence: "Will (@will-lamerton) and Sam (@sam-x)" |
|
|
98
98
|
| `humans_extra` | the same, minus the primary. **Empty when there is only one**, which is what makes `{{#if humans_extra}}` the way to mention the others |
|
|
99
|
+
| `humans_viewing` | the `view_only` humans, as a sentence. Empty when there are none |
|
|
99
100
|
| `ops.dir` | ops repo directory in the checkout |
|
|
100
101
|
| `staff` | the whole of this staff member's `staff.yaml` |
|
|
101
102
|
| `staff.dir` | where their brain lands in the checkout |
|
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.15",
|
|
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"
|