@nanocollective/roster 0.1.0-alpha.9 → 0.1.0-beta.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -0
- package/dist/cli.js +4079 -1950
- package/dist/worker/assets/assets/css/base.css +312 -0
- package/dist/worker/assets/assets/css/brain.css +116 -0
- package/dist/worker/assets/assets/css/diff.css +33 -0
- package/dist/worker/assets/assets/css/graph.css +39 -0
- package/dist/worker/assets/assets/css/health.css +75 -0
- package/dist/worker/assets/assets/css/home.css +101 -0
- package/dist/worker/assets/assets/css/inbox.css +199 -0
- package/dist/worker/assets/assets/css/layout.css +175 -0
- package/dist/worker/assets/assets/css/markdown.css +96 -0
- package/dist/worker/assets/assets/css/runs.css +13 -0
- package/dist/worker/assets/assets/css/search.css +48 -0
- package/dist/worker/assets/assets/css/setup.css +194 -0
- package/dist/worker/assets/assets/js/api.js +161 -0
- package/dist/worker/assets/assets/js/app.js +465 -0
- package/dist/worker/assets/assets/js/dialog.js +196 -0
- package/dist/worker/assets/assets/js/dom.js +131 -0
- package/dist/worker/assets/assets/js/homesort.js +174 -0
- package/dist/worker/assets/assets/js/icons.js +142 -0
- package/dist/worker/assets/assets/js/inflight.js +18 -0
- package/dist/worker/assets/assets/js/lightbox.js +273 -0
- package/dist/worker/assets/assets/js/md.js +406 -0
- package/dist/worker/assets/assets/js/mdedit.js +84 -0
- package/dist/worker/assets/assets/js/mention.js +264 -0
- package/dist/worker/assets/assets/js/readiness.js +70 -0
- package/dist/worker/assets/assets/js/refresh.js +197 -0
- package/dist/worker/assets/assets/js/router.js +20 -0
- package/dist/worker/assets/assets/js/search.js +366 -0
- package/dist/worker/assets/assets/js/state.js +213 -0
- package/dist/worker/assets/assets/js/textdiff.js +96 -0
- package/dist/worker/assets/assets/js/views/app.js +145 -0
- package/dist/worker/assets/assets/js/views/brain.js +260 -0
- package/dist/worker/assets/assets/js/views/changed.js +157 -0
- package/dist/worker/assets/assets/js/views/checklist.js +115 -0
- package/dist/worker/assets/assets/js/views/credential.js +84 -0
- package/dist/worker/assets/assets/js/views/docs.js +174 -0
- package/dist/worker/assets/assets/js/views/files.js +139 -0
- package/dist/worker/assets/assets/js/views/graph.js +436 -0
- package/dist/worker/assets/assets/js/views/health.js +304 -0
- package/dist/worker/assets/assets/js/views/hire.js +593 -0
- package/dist/worker/assets/assets/js/views/home.js +585 -0
- package/dist/worker/assets/assets/js/views/inbox.js +1558 -0
- package/dist/worker/assets/assets/js/views/memory.js +150 -0
- package/dist/worker/assets/assets/js/views/org.js +195 -0
- package/dist/worker/assets/assets/js/views/orgedit.js +240 -0
- package/dist/worker/assets/assets/js/views/paste.js +216 -0
- package/dist/worker/assets/assets/js/views/prompt.js +457 -0
- package/dist/worker/assets/assets/js/views/repos.js +97 -0
- package/dist/worker/assets/assets/js/views/runonce.js +94 -0
- package/dist/worker/assets/assets/js/views/runs.js +182 -0
- package/dist/worker/assets/assets/js/views/setup.js +557 -0
- package/dist/worker/assets/assets/js/views/staff.js +291 -0
- package/dist/worker/assets/assets/js/views/todo.js +62 -0
- package/dist/worker/assets/assets/js/yaml.js +134 -0
- package/dist/worker/assets/docs-images/brain.jpg +0 -0
- package/dist/worker/assets/docs-images/home.jpg +0 -0
- package/dist/worker/assets/docs-images/org.jpg +0 -0
- package/dist/worker/assets/docs-images/prompt.jpg +0 -0
- package/dist/worker/assets/docs-images/setup-org.jpg +0 -0
- package/dist/worker/assets/docs-images/setup-plan.jpg +0 -0
- package/dist/worker/assets/docs-images/staff.jpg +0 -0
- package/dist/worker/assets/index.html +82 -0
- package/dist/worker/index.js +4442 -0
- package/docs/README.md +2 -2
- package/docs/architecture.md +1 -1
- package/docs/charters/analyst.md +65 -0
- package/docs/charters/community.md +63 -0
- package/docs/charters/designer.md +65 -0
- package/docs/charters/devops.md +65 -0
- package/docs/charters/pm.md +70 -0
- package/docs/charters/qa.md +65 -0
- package/docs/charters/writer.md +63 -0
- package/docs/commands.md +9 -3
- package/docs/concepts.md +33 -20
- package/docs/cost.md +3 -3
- package/docs/developing.md +27 -9
- package/docs/doctor-codes.md +3 -1
- package/docs/export.md +2 -0
- package/docs/getting-started.md +44 -27
- package/docs/hosting.md +89 -43
- package/docs/images/brain.jpg +0 -0
- package/docs/images/home.jpg +0 -0
- package/docs/images/org.jpg +0 -0
- package/docs/images/prompt.jpg +0 -0
- package/docs/images/staff.jpg +0 -0
- package/docs/manual-steps.md +3 -2
- package/docs/org-yaml.md +3 -0
- package/docs/portal.md +143 -45
- package/docs/prompts.md +6 -0
- package/docs/security.md +57 -11
- package/docs/session-workflow.md +14 -0
- package/docs/staff-yaml.md +17 -1
- package/docs/upgrading.md +3 -3
- package/docs/writing-a-charter.md +19 -6
- package/package.json +4 -3
- package/templates/brain/.github/workflows/%%STAFF%%-daily.yaml +20 -1
- package/templates/brain/.github/workflows/%%STAFF%%-mention.yaml +53 -13
- package/templates/brain/staff.yaml +4 -1
- package/templates/briefs/amend.md +4 -3
- package/templates/briefs/priorities.md +46 -0
- package/templates/ops/.github/workflows/session.yaml +137 -3
- package/templates/ops/compose.mjs +35 -8
- package/templates/ops/org/operating.md +29 -10
- package/templates/ops/prompts/daily.md +23 -4
- package/templates/ops/prompts/mention.md +19 -0
- package/templates/ops/run-record.mjs +5 -3
- package/templates/portal/css/base.css +34 -0
- package/templates/portal/css/health.css +14 -1
- package/templates/portal/css/home.css +101 -0
- package/templates/portal/css/inbox.css +21 -4
- package/templates/portal/css/layout.css +29 -3
- package/templates/portal/css/markdown.css +19 -0
- package/templates/portal/css/search.css +48 -0
- package/templates/portal/css/setup.css +79 -4
- package/templates/portal/index.html +15 -9
- package/templates/portal/js/api.js +30 -4
- package/templates/portal/js/app.js +90 -7
- package/templates/portal/js/dialog.js +36 -0
- package/templates/portal/js/homesort.js +174 -0
- package/templates/portal/js/icons.js +41 -0
- package/templates/portal/js/inflight.js +18 -0
- package/templates/portal/js/md.js +5 -2
- package/templates/portal/js/mdedit.js +84 -0
- package/templates/portal/js/readiness.js +70 -0
- package/templates/portal/js/refresh.js +10 -2
- package/templates/portal/js/search.js +366 -0
- package/templates/portal/js/state.js +11 -5
- package/templates/portal/js/views/app.js +1 -2
- package/templates/portal/js/views/brain.js +1 -1
- package/templates/portal/js/views/checklist.js +19 -4
- package/templates/portal/js/views/credential.js +42 -51
- package/templates/portal/js/views/health.js +11 -6
- package/templates/portal/js/views/hire.js +593 -0
- package/templates/portal/js/views/home.js +585 -0
- package/templates/portal/js/views/inbox.js +237 -68
- package/templates/portal/js/views/org.js +31 -111
- package/templates/portal/js/views/orgedit.js +240 -0
- package/templates/portal/js/views/paste.js +111 -66
- package/templates/portal/js/views/prompt.js +94 -40
- package/templates/portal/js/views/repos.js +10 -10
- package/templates/portal/js/views/runs.js +21 -4
- package/templates/portal/js/views/setup.js +130 -163
- package/templates/portal/js/views/staff.js +181 -301
- package/templates/portal/js/views/todo.js +62 -0
package/docs/developing.md
CHANGED
|
@@ -12,15 +12,16 @@ npm test # the whole suite
|
|
|
12
12
|
npx tsc --noEmit # typecheck
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
Tests are `node:test` run through `tsx`. There is no build step for development, and the
|
|
16
|
-
has no build step at all.
|
|
15
|
+
Tests are `node:test` run through `tsx`. There is no build step for development, and the
|
|
16
|
+
portal's page has no build step at all. `npm run build` builds the CLI and the portal's Worker.
|
|
17
17
|
|
|
18
18
|
## Layout
|
|
19
19
|
|
|
20
20
|
```
|
|
21
21
|
src/cli.ts command table and help
|
|
22
22
|
src/commands/ one file per command
|
|
23
|
-
src/lib/ shared: workspace, memory, render, merge, gh, templates, docs
|
|
23
|
+
src/lib/ shared: workspace, memory, render, merge, gh, github, vfs, templates, docs
|
|
24
|
+
src/portal/ the portal's server: handler.ts, and the Worker that hosts it
|
|
24
25
|
templates/ops/ what a tenant's ops repo is generated from
|
|
25
26
|
templates/brain/ what a staff member's repo is generated from
|
|
26
27
|
templates/portal/ the portal: a shell, css/, and js/ as ES modules
|
|
@@ -28,14 +29,31 @@ docs/ these pages
|
|
|
28
29
|
test/ one file per area
|
|
29
30
|
```
|
|
30
31
|
|
|
31
|
-
## The portal
|
|
32
|
+
## The portal's server
|
|
33
|
+
|
|
34
|
+
`src/portal/handler.ts` answers every route that works the same on your machine and hosted. It
|
|
35
|
+
reads the org through snapshots of its repositories on GitHub (`snapshot.ts`), mounted where a
|
|
36
|
+
checkout would be by `src/lib/vfs.ts`, so the readers in `src/lib` work on either. It acts
|
|
37
|
+
through `src/lib/github.ts`, a `fetch` client holding the person's token.
|
|
38
|
+
|
|
39
|
+
- `src/commands/portal.ts` is the local server. It sends those routes to the handler and keeps
|
|
40
|
+
the ones that need a checkout: setup, the App hand-off, doctor, hire and retire.
|
|
41
|
+
- `src/portal/worker.ts` is the hosted one: the same handler behind Sign in with GitHub
|
|
42
|
+
(`session.ts`). `scripts/build-worker.mjs` builds it into `dist/worker/`, and
|
|
43
|
+
`roster portal deploy` deploys it.
|
|
44
|
+
|
|
45
|
+
`test/hosted-portal.test.ts` runs the handler against a scaffolded tenant served in the API's
|
|
46
|
+
shapes (`test/helpers/githubrepos.ts`), so it needs neither the network nor an org.
|
|
47
|
+
|
|
48
|
+
## The portal's page has no build step, on purpose
|
|
32
49
|
|
|
33
50
|
`templates/portal/` is a plain `index.html`, one stylesheet per area under `css/`, and one ES
|
|
34
51
|
module per screen under `js/views/`. `roster portal` serves them from `/assets`, reading each
|
|
35
|
-
file per request. Editing a stylesheet and reloading the page is the whole edit loop.
|
|
52
|
+
file per request. Editing a stylesheet and reloading the page is the whole edit loop. The
|
|
53
|
+
Worker serves the same files, copied as they are.
|
|
36
54
|
|
|
37
|
-
No bundler, because the browser resolves the module graph itself
|
|
38
|
-
|
|
55
|
+
No bundler for the page, because the browser resolves the module graph itself. Only the
|
|
56
|
+
Worker's server code is bundled, because a Worker is one module.
|
|
39
57
|
|
|
40
58
|
```
|
|
41
59
|
templates/portal/
|
|
@@ -51,8 +69,8 @@ templates/portal/
|
|
|
51
69
|
```
|
|
52
70
|
|
|
53
71
|
`js/icons.js` holds two dozen [Lucide](https://lucide.dev) glyphs as inlined path data, ISC
|
|
54
|
-
licensed. Vendored rather than fetched, because
|
|
55
|
-
|
|
72
|
+
licensed. Vendored rather than fetched, because an icon that needs a third party's network is an
|
|
73
|
+
icon that is sometimes a blank square. They take colour from
|
|
56
74
|
`currentColor` and size from a `--ic` custom property, so a component styles them in CSS and
|
|
57
75
|
never touches the SVG. Nothing in the UI should draw with a text character.
|
|
58
76
|
|
package/docs/doctor-codes.md
CHANGED
|
@@ -39,7 +39,7 @@ ran at all.
|
|
|
39
39
|
| `workflows` | No workflow in the repo is failing run after run. Reported for the ops repo here, and for each brain repo under its staff member. |
|
|
40
40
|
| `workflows.failing` | **fail.** A workflow that is not one of roster's callers has failed at least its last two runs, with the date it started. Skipped and cancelled runs are stepped over. This is the canary that goes red and stays red, because whatever would have said so broke with it. |
|
|
41
41
|
| `budget` | Trailing 30-day spend against a `budget` in `org.yaml`, for the org here and for a staff member under their name. A warning when it is past, never a failure, and only read when a budget is set. Cost comes from each run's record, so it says how many runs it could price. See [cost](cost.md#budgets). |
|
|
42
|
-
| `review-gate` |
|
|
42
|
+
| `review-gate` | Off unless `review_gate: true` is in `org.yaml`, and then a note that it is off. When on, one per product repo. **fail** when nothing requires a pull request on its default branch, or a staff App can bypass the rule; a warning when a PR is required with no approving review, when the repo is private on GitHub Free (which can't enforce the rule), or when the settings cannot be read. See [security](security.md#the-review-gate). |
|
|
43
43
|
| `upgrade` | The tenant is in sync with the framework. |
|
|
44
44
|
| `upgrade.stale` | Generated files are behind. `roster upgrade --apply`. |
|
|
45
45
|
| `upgrade.owned` | **fail.** A framework-owned file was edited in the tenant. Move the change upstream or the next upgrade reverts it. |
|
|
@@ -63,6 +63,8 @@ ran at all.
|
|
|
63
63
|
| `surfaces` | A surface declared in `staff.yaml` is not on disk. The portal renders nothing for it. |
|
|
64
64
|
| `secrets` | Every secret the callers reference exists on the brain repo, or is an organisation secret shared with it. Derived from the callers themselves, not a fixed list. |
|
|
65
65
|
| `labels` | Every label declared in `staff.yaml` exists. An agent applying a label that does not exist gets an API error mid-run. |
|
|
66
|
+
| `owned-labels` | Roster's own labels exist on the tracker: `decision`, `review`, `chore` and `keep-open`. Checked whatever `staff.yaml` declares, since the prompts apply them. The fix is the `gh label create` lines. |
|
|
67
|
+
| `ask-kind` | An open issue assigned to a human has no ask kind, or more than one. Home sorts what needs you by kind, so an ask without one lands nowhere. |
|
|
66
68
|
| `peer-labels` | The `from-<handle>` label exists on the *peer's* tracker, which is where this staff member's asks land. |
|
|
67
69
|
| `status-issue` | The declared status issue is actually pinned. If not, the place you look is not the place the agent maintains. |
|
|
68
70
|
| `runs` | A window of recent runs. See below. |
|
package/docs/export.md
CHANGED
|
@@ -35,6 +35,7 @@ that reads it gets the same view without reimplementing the memory grammar.
|
|
|
35
35
|
| `statusIssue` | pinned issue number |
|
|
36
36
|
| `schedule` | cron |
|
|
37
37
|
| `mention` | what wakes them |
|
|
38
|
+
| `icon` | the icon set by `icon:` in staff.yaml, if any |
|
|
38
39
|
| `bots[]` | every App login, `[bot]` suffix stripped |
|
|
39
40
|
| `soloBots[]` | identities unique to this staff member |
|
|
40
41
|
| `sharedBots[]` | identities shared with others |
|
|
@@ -99,6 +100,7 @@ Only surfaces that exist on disk appear. A declared surface that is missing show
|
|
|
99
100
|
|---|---|
|
|
100
101
|
| `workflows[]` | filenames under `.github/workflows/` |
|
|
101
102
|
| `hasCharter`, `hasManifest` | |
|
|
103
|
+
| `charterStub` | `CHARTER.md` is absent or still the scaffold, the same test as doctor's `charter.stub` |
|
|
102
104
|
| `missingSurfaces[]` | declared, not on disk |
|
|
103
105
|
| `memoryBytes` | size of `INDEX.md` |
|
|
104
106
|
| `notesBytes` | total size of `memory/notes/` |
|
package/docs/getting-started.md
CHANGED
|
@@ -30,7 +30,7 @@ hour is the part not to rush.
|
|
|
30
30
|
- **A credential for your [coding agent](agents.md).** For Claude Code, run
|
|
31
31
|
`claude setup-token` and keep the token it prints for step 5.
|
|
32
32
|
|
|
33
|
-
You only need [the
|
|
33
|
+
You only need [the three things in Concepts](concepts.md#the-three-things-you-need-to-know) to follow
|
|
34
34
|
this. Everything else can wait.
|
|
35
35
|
|
|
36
36
|
## 1. Say which organisation, then read the plan
|
|
@@ -51,7 +51,8 @@ can call its workflow. Without that every run fails with "workflow not found". I
|
|
|
51
51
|
(it needs admin on the repo), the page says why and links to the setting to click instead.
|
|
52
52
|
|
|
53
53
|
The rest of the steps stay on the same page. Reload it and the portal opens on **Getting
|
|
54
|
-
started**, which keeps them in the sidebar until they are done, with hiring first.
|
|
54
|
+
started**, which keeps them in the sidebar until they are done, with hiring first. The sidebar
|
|
55
|
+
counts them: three for the org, five for each staff member.
|
|
55
56
|
|
|
56
57
|
## 2. Say what the business is
|
|
57
58
|
|
|
@@ -71,49 +72,61 @@ See [concepts](concepts.md#priorities).
|
|
|
71
72
|
|
|
72
73
|

|
|
73
74
|
|
|
74
|
-
**Staff
|
|
75
|
-
|
|
76
|
-
|
|
75
|
+
**Staff**, then pick a role: CTO, CMO, Support, or **Something else** with a name and a sentence
|
|
76
|
+
about what they do. With nobody hired yet the Staff screen opens on the picker. The role fills
|
|
77
|
+
in the handle, name and repo; they are under **Advanced** if you want to change them.
|
|
77
78
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
79
|
+
The role opens a numbered list: hire, create their GitHub App, write their charter, add your
|
|
80
|
+
agent credential, run once now. The steps after the hire say *Hire first* until it is done.
|
|
81
|
+
|
|
82
|
+
Step 1 says in one sentence what the hire creates and when they run. **Show details** has the
|
|
83
|
+
full plan: the repo, the schedule and why, and the commits it will make **as you** in repos that
|
|
84
|
+
already exist: each peer's `staff.yaml`, and `org.yaml`. Nothing is left uncommitted on disk.
|
|
85
|
+
|
|
86
|
+
For the first hire there is nobody to copy an App name from, so **Advanced** also has two:
|
|
87
|
+
this staff member's App, and the shared public App, filled in as `<org>-<handle>` and
|
|
88
|
+
`<org>-robot`. Names are unique across GitHub, so keep the org prefix. The public one only
|
|
89
|
+
matters if a product repo is public.
|
|
82
90
|
|
|
83
91
|
Product repos come from `org.yaml`. Mark one on the setup screen, or later with **Org → Add a
|
|
84
92
|
product repo**.
|
|
85
93
|
|
|
94
|
+
After **Hire** the list stays on the same staff member, now on step 2. Leave and come back later
|
|
95
|
+
with **Finish setting up** on their card.
|
|
96
|
+
|
|
86
97
|
## 4. Create the App, and confirm the install
|
|
87
98
|
|
|
88
|
-
**
|
|
99
|
+
**Create the App**, in step 2. GitHub has no API that creates an App, so a tab opens and you
|
|
89
100
|
confirm. The App's id and private key go straight into the repo's secrets and never touch disk.
|
|
101
|
+
The public App is offered too when a product repo is public.
|
|
90
102
|
|
|
91
103
|
Then **Install it**. The install page opens with the organisation and every repo this staff
|
|
92
104
|
member needs already ticked: its brain, the trackers of its peers, and the product repos. Check
|
|
93
105
|
the list and confirm. That confirmation is yours by design: installing grants access, and GitHub
|
|
94
106
|
asks a person.
|
|
95
107
|
|
|
96
|
-
## 5.
|
|
108
|
+
## 5. Write the charter
|
|
97
109
|
|
|
98
|
-
**
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
110
|
+
Step 3. **Let an AI interview you** is the same copy-a-prompt loop as step 2 of this guide, aimed
|
|
111
|
+
at `CHARTER.md`, carrying the org layer, the peers' charters and, where the role matches one, a
|
|
112
|
+
[worked example](writing-a-charter.md#worked-examples) to model the shape on. **Start from the
|
|
113
|
+
template** opens that example in an editor with your business's name in it; edit it so it fits
|
|
114
|
+
before saving. **Edit the file** is the file as it is. roster never generates a charter, because
|
|
115
|
+
a generated one makes exactly the generic agent this whole arrangement exists to avoid.
|
|
102
116
|
|
|
103
|
-
|
|
104
|
-
instead, and the page says so. It is still one paste now; a later hire needs it once more.
|
|
117
|
+
## 6. Store the agent credential, once
|
|
105
118
|
|
|
106
|
-
|
|
119
|
+
Step 4, shown only while no credential is stored. It is also on the card and on the setup
|
|
120
|
+
screen. Paste the token from `claude setup-token` (or your agent's key; the box says where to
|
|
121
|
+
get one). It is stored as one organisation secret, shared with the brain repos, and each later
|
|
122
|
+
hire is added to it. It is not asked for again.
|
|
107
123
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
[worked example](writing-a-charter.md#worked-examples) to model the shape on. The brief
|
|
111
|
-
interviews you; the charter is yours. roster never generates one, because a generated charter
|
|
112
|
-
makes exactly the generic agent this whole arrangement exists to avoid.
|
|
124
|
+
On GitHub Free an org secret does not reach private repos, so there it goes on each brain repo
|
|
125
|
+
instead, and the page says so. It is still one paste now; a later hire needs it once more.
|
|
113
126
|
|
|
114
127
|
## 7. Run it once
|
|
115
128
|
|
|
116
|
-
**Run once now**, on the card
|
|
129
|
+
**Run once now**, step 5, also on the card and on **Health**. It starts the daily workflow, follows it, and
|
|
117
130
|
tells you how it ended, with the log.
|
|
118
131
|
|
|
119
132
|
**A workflow that has never run has proved nothing**: not that the App is installed on the right
|
|
@@ -144,9 +157,13 @@ member on their next run.
|
|
|
144
157
|
|
|
145
158
|
The same road, command by command. Each prints its plan and changes nothing without `--apply`.
|
|
146
159
|
|
|
160
|
+
`roster` below means `npx @nanocollective/roster@latest`, unless you have installed it with
|
|
161
|
+
`npm install -g @nanocollective/roster`.
|
|
162
|
+
|
|
147
163
|
```bash
|
|
148
164
|
roster init --org acme --apply # the ops repo, and its Actions access
|
|
149
|
-
roster brief discover # a brief for org/business.md
|
|
165
|
+
roster brief discover # a brief for org/business.md
|
|
166
|
+
roster brief priorities # a brief for org/priorities.md
|
|
150
167
|
roster hire cto --apply # the brain, the wiring, the commits as you
|
|
151
168
|
roster app cto --apply # the App, its secrets, and a pre-ticked install link
|
|
152
169
|
roster credential --apply # the agent credential, once for the org
|
|
@@ -165,8 +182,8 @@ each.
|
|
|
165
182
|
|
|
166
183
|
- **A second staff member**: Staff → Hire someone, then GitHub App, the charter and one run. The
|
|
167
184
|
credential is already there.
|
|
168
|
-
- **Answering your agents**: [
|
|
169
|
-
|
|
185
|
+
- **Answering your agents**: [Home](portal.md#home) is what needs you, who is working and
|
|
186
|
+
what you asked for. Replies and merges go out as you.
|
|
170
187
|
- **A framework update**: `roster upgrade`, or the same from the portal. See
|
|
171
188
|
[upgrading](upgrading.md).
|
|
172
189
|
- **The whole portal**, screen by screen: [the portal](portal.md).
|
package/docs/hosting.md
CHANGED
|
@@ -1,72 +1,118 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Hosting the portal"
|
|
3
|
-
description: "
|
|
3
|
+
description: "The portal on your own URL, behind Sign in with GitHub, redeploying itself."
|
|
4
4
|
sidebar_order: 11
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Hosting the portal
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
repositories from disk, needs no authentication, hits no API rate limits, and works offline.
|
|
9
|
+
The portal runs in two places, and it is the same code in both.
|
|
11
10
|
|
|
12
11
|
```bash
|
|
13
|
-
roster portal
|
|
14
|
-
roster portal --
|
|
12
|
+
roster portal # on your machine, http://localhost:4300
|
|
13
|
+
roster portal deploy --domain roster.acme.com # on the web, on Cloudflare Workers
|
|
15
14
|
```
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
Both read the org from GitHub, so neither needs the repos checked out to show it. Both act on
|
|
17
|
+
GitHub as the person using them. The hosted one adds a sign-in in front, and leaves out the
|
|
18
|
+
few screens that need a checkout.
|
|
18
19
|
|
|
19
|
-
|
|
20
|
-
repository secrets, and none of that belongs behind a tunnel or an access proxy. Everything below
|
|
21
|
-
is about a portal over an org that already exists.
|
|
20
|
+
## What you get, and what stays on your machine
|
|
22
21
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
22
|
+
Hosted, you get everything you use day to day: Home, the trackers, threads and replies, pull
|
|
23
|
+
requests (approve and merge), Runs, the brains, prompts, the org files and their editors, and
|
|
24
|
+
the docs.
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
These stay on your machine, and the hosted page says so where they would be:
|
|
28
27
|
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
|
|
32
|
-
- an `Origin` header, if present, must be localhost
|
|
28
|
+
- **Setup**: standing up an org, the GitHub Apps, the agent credential
|
|
29
|
+
- **Hiring and retiring**
|
|
30
|
+
- **Doctor and the Health checklist**, which read the checkout and the org's secrets
|
|
33
31
|
|
|
34
|
-
|
|
35
|
-
|
|
32
|
+
They create repositories and Apps and write secrets, which is the most privileged thing roster
|
|
33
|
+
does. That is not something to put behind a public URL.
|
|
36
34
|
|
|
37
|
-
##
|
|
35
|
+
## Who can get in
|
|
38
36
|
|
|
39
|
-
|
|
37
|
+
Only the people listed under `humans:` in `org.yaml`, signed in with their own GitHub account.
|
|
40
38
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
39
|
+
- Sign-in is GitHub's own OAuth flow, through an OAuth App your org creates for the portal.
|
|
40
|
+
The token it hands back is that person's, scoped `repo` and `notifications`, the same kind
|
|
41
|
+
`gh` holds on their machine.
|
|
42
|
+
- Everything they do is as themselves. A reply is theirs, a merge is theirs, and what they can
|
|
43
|
+
read is what GitHub lets them read.
|
|
44
|
+
- Somebody who signs in and is not one of the humans, or cannot read the ops repo, is turned
|
|
45
|
+
away and their token revoked. Somebody removed from `humans:` stops getting in within a few
|
|
46
|
+
minutes.
|
|
47
|
+
- A sign-in lasts fourteen days. Signing out revokes the token on GitHub.
|
|
44
48
|
|
|
45
|
-
|
|
46
|
-
|
|
49
|
+
See [security](security.md#the-hosted-portal) for what is held where.
|
|
50
|
+
|
|
51
|
+
## Deploying it
|
|
52
|
+
|
|
53
|
+
You need a Cloudflare account with the domain on it, and wrangler signed in to it. If your
|
|
54
|
+
login can see more than one account, pass `--account <id>` with the one that has the domain, and
|
|
55
|
+
it is pinned in the config so a later deploy cannot land anywhere else:
|
|
47
56
|
|
|
48
57
|
```bash
|
|
49
|
-
|
|
58
|
+
npx wrangler login
|
|
59
|
+
roster portal deploy --domain roster.acme.com # says what it will do
|
|
60
|
+
roster portal deploy --domain roster.acme.com --apply # does it
|
|
50
61
|
```
|
|
51
62
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
63
|
+
The first time, it stops for the one thing only you can do: **create the OAuth App**. It prints
|
|
64
|
+
the link and the three fields:
|
|
65
|
+
|
|
66
|
+
| Field | Value |
|
|
67
|
+
|---|---|
|
|
68
|
+
| Application name | `<org> roster` |
|
|
69
|
+
| Homepage URL | `https://roster.acme.com` |
|
|
70
|
+
| Authorization callback URL | `https://roster.acme.com/auth/callback` |
|
|
71
|
+
|
|
72
|
+
Register it, generate a client secret, and paste the two values when asked. The secret is not
|
|
73
|
+
shown as you type.
|
|
74
|
+
|
|
75
|
+
Then it deploys the Worker, stores the App's secret and a fresh session key as Worker secrets,
|
|
76
|
+
and commits two files to the ops repo:
|
|
77
|
+
|
|
78
|
+
- `portal/wrangler.jsonc`: the Worker's name, the domain, the org. Nothing secret.
|
|
79
|
+
- `.github/workflows/portal.yaml`: redeploys it.
|
|
80
|
+
|
|
81
|
+
## Keeping it up to date
|
|
82
|
+
|
|
83
|
+
The workflow redeploys the portal when its config changes, every morning, and when you run it
|
|
84
|
+
by hand. Each deploy uses the newest roster, so updates arrive by themselves.
|
|
55
85
|
|
|
56
|
-
|
|
57
|
-
work. **This is private business content and a map of what your agents know**, so an
|
|
58
|
-
unauthenticated URL is not an option even if nobody knows it.
|
|
86
|
+
It needs two secrets on the ops repo:
|
|
59
87
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
88
|
+
| Secret | Where from |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `CLOUDFLARE_API_TOKEN` | Cloudflare dashboard → API Tokens → the **Edit Cloudflare Workers** template |
|
|
91
|
+
| `CLOUDFLARE_ACCOUNT_ID` | the Workers page of the dashboard |
|
|
64
92
|
|
|
65
|
-
|
|
93
|
+
Without them the portal still runs; it only stops updating itself.
|
|
66
94
|
|
|
67
|
-
The portal reads
|
|
68
|
-
|
|
69
|
-
|
|
95
|
+
The portal reads GitHub fresh as you use it, so there is nothing to sync. It asks whether
|
|
96
|
+
anything has moved every few seconds, and an answer of "no" costs nothing against GitHub's
|
|
97
|
+
hourly limit.
|
|
98
|
+
|
|
99
|
+
## The cache
|
|
100
|
+
|
|
101
|
+
The portal keeps what it has read from GitHub: file contents by their hash, each commit's file
|
|
102
|
+
dates, and finished runs' costs. All of it is immutable, so it is never stale.
|
|
103
|
+
|
|
104
|
+
On your machine it is `~/.cache/roster`. On Cloudflare it is the edge cache, which needs no
|
|
105
|
+
setup. To keep it everywhere rather than per data centre, bind a KV namespace as `CACHE` in
|
|
106
|
+
`portal/wrangler.jsonc`.
|
|
107
|
+
|
|
108
|
+
## On your machine
|
|
109
|
+
|
|
110
|
+
`roster portal` binds to `127.0.0.1` and acts as whoever `gh` is signed in as. To open an org
|
|
111
|
+
you have never cloned:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
roster portal --org acme
|
|
115
|
+
```
|
|
70
116
|
|
|
71
|
-
|
|
72
|
-
|
|
117
|
+
`--host` overrides the bind address and prints a warning. The local server has no sign-in, so
|
|
118
|
+
use the hosted portal instead of exposing it.
|
package/docs/images/brain.jpg
CHANGED
|
Binary file
|
|
Binary file
|
package/docs/images/org.jpg
CHANGED
|
Binary file
|
package/docs/images/prompt.jpg
CHANGED
|
Binary file
|
package/docs/images/staff.jpg
CHANGED
|
Binary file
|
package/docs/manual-steps.md
CHANGED
|
@@ -45,8 +45,9 @@ hand. roster says so if it happens.
|
|
|
45
45
|
## 3. Confirm the App's install
|
|
46
46
|
|
|
47
47
|
**Do:** press **Install it** in the portal, or open the link `roster app` prints. The page opens
|
|
48
|
-
with the organisation and the repos this staff member needs already selected: its brain,
|
|
49
|
-
peer's tracker, and the product repos. Check the
|
|
48
|
+
with the organisation and the repos this staff member needs already selected: its brain, the
|
|
49
|
+
ops repo (every run checks it out first), each peer's tracker, and the product repos. Check the
|
|
50
|
+
list and confirm. Choosing **All repositories** instead also works.
|
|
50
51
|
|
|
51
52
|
**Why not automated:** installing is a grant of access to specific repositories, and GitHub asks
|
|
52
53
|
a person to confirm it. That is correct and should not be worked around.
|
package/docs/org-yaml.md
CHANGED
|
@@ -39,6 +39,7 @@ defaults:
|
|
|
39
39
|
mention_timeout_minutes: 90
|
|
40
40
|
|
|
41
41
|
budget: 300
|
|
42
|
+
review_gate: true
|
|
42
43
|
|
|
43
44
|
staff:
|
|
44
45
|
- { handle: cto, dir: technology, name: Chief Technology Officer, schedule: "0 7 * * 1-5" }
|
|
@@ -61,6 +62,7 @@ repos:
|
|
|
61
62
|
| `ops_dir` | no | Directory name of the ops repo in the runner checkout. Defaults to `roster-ops`. |
|
|
62
63
|
| `experiment_private` | no | Whether the fact that this org is agent-run is itself private. Read by the guardrails fragment. |
|
|
63
64
|
| `budget` | no | USD over any trailing 30 days, for the whole org. See [below](#budget). |
|
|
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). |
|
|
64
66
|
|
|
65
67
|
### `human` and `humans`
|
|
66
68
|
|
|
@@ -124,6 +126,7 @@ Fallbacks for staff members who do not set their own.
|
|
|
124
126
|
| `model` | Model id passed to the agent. |
|
|
125
127
|
| `timeout_minutes` | Ceiling on a daily session. `90` if unset. |
|
|
126
128
|
| `mention_timeout_minutes` | Ceiling on a mention run. Falls back to `timeout_minutes`, then `90`. |
|
|
129
|
+
| `max_runs_per_day` | What a new hire's `max_runs_per_day` starts at. `6` when unset. |
|
|
127
130
|
| `allowed_tools` | Claude's own spelling of a permission level, kept because it predates `agent.permissions` and still wins for the agents that take a tool list. Nothing translates it for the others: a list written for one agent is not a permission level for another. Prefer [`agent.permissions`](agents.md#permissions), which every agent understands. |
|
|
128
131
|
|
|
129
132
|
### `memory`
|