@minca/core 0.1.17 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +3 -1
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/index.d.ts +1 -1
  22. package/dist/node/index.d.ts.map +1 -1
  23. package/dist/node/node-contacts.d.ts.map +1 -1
  24. package/dist/node/node-contacts.js +1 -0
  25. package/dist/node/node-contacts.js.map +1 -1
  26. package/dist/node/node-records.d.ts.map +1 -1
  27. package/dist/node/node-records.js +6 -1
  28. package/dist/node/node-records.js.map +1 -1
  29. package/dist/node/node.d.ts.map +1 -1
  30. package/dist/node/node.js +13 -1
  31. package/dist/node/node.js.map +1 -1
  32. package/dist/node/remote.d.ts.map +1 -1
  33. package/dist/node/remote.js +7 -1
  34. package/dist/node/remote.js.map +1 -1
  35. package/dist/node/space-runtime.d.ts +5 -3
  36. package/dist/node/space-runtime.d.ts.map +1 -1
  37. package/dist/node/space-runtime.js +3 -1
  38. package/dist/node/space-runtime.js.map +1 -1
  39. package/dist/node/types.d.ts +112 -36
  40. package/dist/node/types.d.ts.map +1 -1
  41. package/dist/node/watch-notifications.d.ts +6 -0
  42. package/dist/node/watch-notifications.d.ts.map +1 -1
  43. package/dist/node/watch-notifications.js +47 -9
  44. package/dist/node/watch-notifications.js.map +1 -1
  45. package/dist/query/types.d.ts +1 -0
  46. package/dist/query/types.d.ts.map +1 -1
  47. package/dist/query/types.js.map +1 -1
  48. package/dist/records/contract-builder.d.ts +22 -6
  49. package/dist/records/contract-builder.d.ts.map +1 -1
  50. package/dist/records/contract-builder.js.map +1 -1
  51. package/dist/schemas/automations.d.ts +6 -2
  52. package/dist/schemas/automations.d.ts.map +1 -1
  53. package/dist/schemas/automations.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +4 -3
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/connectors.js +4 -3
  57. package/dist/schemas/connectors.js.map +1 -1
  58. package/dist/schemas/library/media.js +1 -1
  59. package/dist/schemas/library/media.js.map +1 -1
  60. package/dist/session/account-hint.d.ts +2 -2
  61. package/dist/session/account-hint.d.ts.map +1 -1
  62. package/dist/session/account-hint.js +3 -3
  63. package/dist/session/account-hint.js.map +1 -1
  64. package/dist/session/auth.d.ts +7 -3
  65. package/dist/session/auth.d.ts.map +1 -1
  66. package/dist/session/auth.js.map +1 -1
  67. package/dist/session/connection.d.ts +18 -0
  68. package/dist/session/connection.d.ts.map +1 -1
  69. package/dist/session/connection.js +11 -0
  70. package/dist/session/connection.js.map +1 -1
  71. package/dist/session/index.d.ts +2 -2
  72. package/dist/session/index.d.ts.map +1 -1
  73. package/dist/session/index.js +2 -2
  74. package/dist/session/index.js.map +1 -1
  75. package/dist/storage/blob-store.d.ts +3 -0
  76. package/dist/storage/blob-store.d.ts.map +1 -1
  77. package/dist/types.d.ts +11 -2
  78. package/dist/types.d.ts.map +1 -1
  79. package/dist/types.js.map +1 -1
  80. package/docs/README.md +86 -93
  81. package/docs/actions.md +213 -152
  82. package/docs/agents.md +198 -167
  83. package/docs/automations.md +296 -204
  84. package/docs/blueprints-and-guides.md +405 -311
  85. package/docs/bots.md +208 -134
  86. package/docs/building-an-app.md +86 -159
  87. package/docs/collections.md +248 -328
  88. package/docs/computed.md +112 -89
  89. package/docs/contacts.md +151 -112
  90. package/docs/contracts.md +299 -120
  91. package/docs/direct-messages.md +80 -65
  92. package/docs/inbox.md +138 -93
  93. package/docs/node.md +1081 -996
  94. package/docs/permissions.md +142 -0
  95. package/docs/proposing-collections.md +74 -55
  96. package/docs/query-format.md +150 -126
  97. package/docs/records-and-queries.md +205 -126
  98. package/docs/sign-in.md +487 -416
  99. package/docs/spaces.md +261 -246
  100. package/docs/standard-library.md +487 -526
  101. package/docs/storage.md +325 -348
  102. package/docs/usernames.md +164 -97
  103. package/docs/warrants.md +100 -67
  104. package/package.json +1 -6
  105. package/dist/elements/auth-styles.d.ts +0 -18
  106. package/dist/elements/auth-styles.d.ts.map +0 -1
  107. package/dist/elements/auth-styles.js +0 -206
  108. package/dist/elements/auth-styles.js.map +0 -1
  109. package/dist/elements/dom.d.ts +0 -29
  110. package/dist/elements/dom.d.ts.map +0 -1
  111. package/dist/elements/dom.js +0 -91
  112. package/dist/elements/dom.js.map +0 -1
  113. package/dist/elements/index.d.ts +0 -13
  114. package/dist/elements/index.d.ts.map +0 -1
  115. package/dist/elements/index.js +0 -11
  116. package/dist/elements/index.js.map +0 -1
  117. package/dist/elements/minca-auth.d.ts +0 -55
  118. package/dist/elements/minca-auth.d.ts.map +0 -1
  119. package/dist/elements/minca-auth.js +0 -768
  120. package/dist/elements/minca-auth.js.map +0 -1
package/docs/bots.md CHANGED
@@ -1,47 +1,54 @@
1
1
  # Bots and their connectors
2
2
 
3
- A bot is an account of its own in a space: one a host runs
4
- ([spec 08](../../../spec/08-hosting.md) §3), or one a member runs with
5
- `minca agent --bot`. What it does is the space's automations naming it
6
- ([automations.md](automations.md)). This page covers who may configure a bot,
7
- the instructions it follows, and how one is connected to a service outside
8
- the space, GitHub first.
3
+ A bot is an account of its own, added to a space like a member. A host can
4
+ run it, or a member can, with `minca agent --bot`. What a bot does is decided
5
+ by the space's [automations](automations.md) that name it in `by`.
6
+
7
+ This page covers who may configure a bot, the instructions it follows, and
8
+ how to connect it to a service outside the space, like GitHub.
9
+
10
+ [Spec 08 §3](../../../spec/08-hosting.md) covers bots on a host.
9
11
 
10
12
  ## Who may configure a bot
11
13
 
12
- Someone who holds `/std.automation/instruct` in the space and every role the
13
- bot holds there: `mayConfigure(node, space, bot, who)`. The second half means
14
- nobody reaches past their own grants through the bot. In the community
15
- preset, founders, admins and moderators hold the grant.
14
+ Someone who holds `/std.automation/instruct` in the space, and every role the
15
+ bot holds there. The second half means nobody reaches past their own grants
16
+ through a bot. In the `community` preset, founders, admins and moderators
17
+ hold the grant.
16
18
 
17
- A bot never passes for itself: steered once, it could otherwise leave
18
- itself instructions that count. Nor does another bot, as no chat app lets
19
- one integration reprogram the next: a host never counts a bot it runs
20
- (`isBot` in `runAutomations`), and the add-bot dialog offers a bot no role
21
- that grants `/std.automation/instruct`. The bot, its host and the app all ask this
22
- one function, of whoever wrote the version in question (`root`):
19
+ Ask with `mayConfigure`:
23
20
 
24
- - a bot follows what a record asks only when its writer passes;
25
- - a bot follows instructions (`std.bot`) only from someone who passes;
26
- - a bot acts on GitHub only for an automation whose current words were
27
- written by someone who passes, whoever sets it off;
28
- - a host connects or disconnects a bot only for someone who passes.
21
+ ```ts
22
+ import { mayConfigure } from '@minca/core/schemas';
29
23
 
30
- ## Instructions
24
+ async function openSettings(bot: string, person: string) {
25
+ if (await mayConfigure(node, space.id, bot, person)) {
26
+ // show the bot's settings
27
+ }
28
+ }
29
+ ```
31
30
 
32
- `std.bot` is how a community wants its bot to be: a name to go by, a tone,
33
- what to know. Each person keeps their own (`onePer: [@author, bot]`), so
34
- nobody's words overwrite another's. The bot reads the newest whose current
35
- version was written by someone who may configure it, as a person and not an
36
- agent, and adds it to its system prompt after its own rules, saying whose
37
- words they are. They can't undo those rules: what set an automation off is
38
- still data, and deleting is still refused. Everyone in the space can read
39
- them. An app showing a bot's instructions must pick them the same way
40
- (`personaIn` in `packages/cli/src/bot-runner.ts`).
31
+ The bot, its host and the app all ask this one function, about whoever wrote
32
+ the version in question (its `root`):
41
33
 
42
- | Collection | Body | Rules |
43
- | ---------- | ----------------------------------------------- | ------------------------ |
44
- | `std.bot` | **`bot`** DID; **`instructions`** string ≤ 2000 | `onePer: [@author, bot]` |
34
+ - A bot follows what a record asks only when its writer passes.
35
+ - A bot follows instructions (`std.bot`) only from someone who passes.
36
+ - A bot acts on GitHub only for an automation whose current words were written
37
+ by someone who passes, whoever sets it off.
38
+ - A host connects or disconnects a bot only for someone who passes.
39
+
40
+ ### Bots don't configure bots
41
+
42
+ A bot never passes for itself. Steered once, it could leave itself
43
+ instructions that count. Nor does another bot, just as no chat app lets one
44
+ integration reprogram the next. A host never counts a bot it runs (`isBot` in
45
+ `runAutomations`), and the add-bot dialog offers a bot no role that grants
46
+ `/std.automation/instruct`.
47
+
48
+ ## Instructions
49
+
50
+ A `std.bot` record says how a community wants its bot to be: a name to go by,
51
+ a tone, what to know.
45
52
 
46
53
  ```json
47
54
  {
@@ -50,39 +57,83 @@ them. An app showing a bot's instructions must pick them the same way
50
57
  }
51
58
  ```
52
59
 
60
+ | Collection | Body | Rules |
61
+ | ---------- | ----------------------------------------------- | ------------------------ |
62
+ | `std.bot` | **`bot`** DID; **`instructions`** string ≤ 2000 | `onePer: [@author, bot]` |
63
+
64
+ Each person keeps their own, so nobody's words overwrite another's. The bot
65
+ reads the newest one whose current version was written by someone who may
66
+ configure it, as a person and not through an agent. It adds them to its
67
+ system prompt after its own rules, saying whose words they are.
68
+
69
+ Instructions can't undo the bot's rules. What set an automation off is still
70
+ data, and deleting is still refused. Everyone in the space can read them.
71
+
72
+ An app that shows a bot's instructions must pick them the same way, as the
73
+ CLI's `personaIn` does.
74
+
53
75
  ## Connecting a bot
54
76
 
55
- A host whose description names `connectors` can connect its bots to those
56
- services: whichever it offers, GitHub, a calendar, a drive. The person never
57
- handles a key: they go through the service's own consent screen, and the host
58
- keeps what reaches the service. An app needs to know nothing about a service
59
- but its id and name.
77
+ A host can connect its bots to outside services, like GitHub, a calendar or a
78
+ drive. The person never handles a key. They go through the service's own
79
+ consent screen, and the host keeps what reaches the service. Your app only
80
+ needs each service's id and name.
60
81
 
61
- 1. The app reads what the host offers from its view of the space
62
- (`node.hosting.space(space)`, each view's `connectors`: `{ id, name }`).
63
- 2. It calls `askToConnect(node, space, bot, id)`: that makes a random 32-byte
82
+ 1. Read what the host offers from `node.hosting.space(space.id)`. Each view has
83
+ `connectors`, a list of `{ id, name }`, and the host's `url`.
84
+ 2. Call `askToConnect(node, space, bot, id)`. It makes a random 32-byte
64
85
  secret, keeps it, and writes a `std.connect` naming the bot, the service
65
- and the secret's hash, valid for nine minutes.
66
- 3. It opens `connectPage(hostUrl, ask)` in a window of its own, opened in the
67
- click so the browser doesn't block it. The host checks the request through
68
- the bot (spec 08 §3.1) and sends the window to the service.
86
+ and the secret's hash. The request is valid for nine minutes.
87
+ 3. Open `connectPage(hostUrl, ask)` in a new window. Open it in the click
88
+ handler, so the browser doesn't block it. The host checks the request
89
+ through the bot and sends the window on to the service.
69
90
  4. When the service sends it back, the bot writes its own `std.connector`
70
- saying what it is connected to, and the window tells the app (a
71
- `postMessage` of `{ minca: 'connected' }`) and closes.
91
+ saying what it is connected to. The window posts `{ minca: 'connected' }`
92
+ to your app and closes.
93
+
94
+ ```ts
95
+ import type { SpaceHostingView } from '@minca/core';
96
+ import { askToConnect, connectPage } from '@minca/core/schemas';
97
+
98
+ async function connect(host: SpaceHostingView, bot: string) {
99
+ // Opened in the click, before any await, or the browser blocks it.
100
+ const page = window.open('about:blank', 'minca-connect');
101
+ const ask = await askToConnect(node, space.id, bot, 'github');
102
+ if (page) page.location.href = connectPage(host.url, ask);
103
+ }
104
+ ```
105
+
106
+ Define `std.connect` and `std.connector` in the space before you write a
107
+ request. Show a `std.connector` only when its writer is the bot it names.
108
+
109
+ ### Disconnecting
110
+
111
+ Write the request with `disconnect: true`, then send it with
112
+ `askToDisconnect`. The host checks it the same way, forgets the connection,
113
+ and the bot deletes its `std.connector`.
72
114
 
73
- Disconnecting is `askToConnect(node, space, bot, id, { disconnect: true })`,
74
- then `askToDisconnect(hostUrl, ask)`: the host checks it the same way,
75
- forgets the connection, and the bot deletes its `std.connector`.
115
+ ```ts
116
+ import type { SpaceHostingView } from '@minca/core';
117
+ import { askToConnect, askToDisconnect } from '@minca/core/schemas';
76
118
 
77
- An app must show a `std.connector` only when its writer is the bot it names,
78
- and must define the collections before it writes a request.
119
+ async function disconnect(host: SpaceHostingView, bot: string) {
120
+ const ask = await askToConnect(node, space.id, bot, 'github', { disconnect: true });
121
+ await askToDisconnect(host.url, ask);
122
+ }
123
+ ```
124
+
125
+ ### The records
79
126
 
80
- | Collection | Body | Rules |
81
- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
82
- | `std.connect` | **`bot`** DID; **`kind`** the service's id, string 1–40; `verifier` base64url(SHA-256(secret)), 43–64 chars; **`expires`** date-time; `disconnect` boolean | |
83
- | `std.connector` | **`bot`** DID; **`kind`** string 1–40; **`account`** string ≤ 100, whose account at the service; `reaches` strings ≤ 200, what it reaches, ≤ 100; **`by`** DID; **`since`** date-time | `onePer: [@author, kind]` |
127
+ | Collection | Body | Rules |
128
+ | --------------- | --------------------------------------------------------------------------------------------------------- | ------------------------- |
129
+ | `std.connect` | **`bot`** DID; **`kind`** service id, 1–40 chars; `verifier`; **`expires`** date-time; `disconnect` bool | |
130
+ | `std.connector` | **`bot`** DID; **`kind`** 1–40 chars; **`account`** ≤ 100; `reaches`; **`by`** DID; **`since`** date-time | `onePer: [@author, kind]` |
84
131
 
85
- Example request, for the secret `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA` (43 `A`s):
132
+ - `verifier` is base64url(SHA-256(secret)), 43–64 characters.
133
+ - `account` is whose account at the service it is.
134
+ - `reaches` is what it reaches: up to 100 strings of up to 200 characters.
135
+
136
+ A request, for the secret `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA` (43 `A`s):
86
137
 
87
138
  ```json
88
139
  {
@@ -93,81 +144,106 @@ Example request, for the secret `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA` (4
93
144
  }
94
145
  ```
95
146
 
147
+ [Spec 08 §3.1](../../../spec/08-hosting.md) covers how the host checks it.
148
+
96
149
  ## Writing a connector
97
150
 
98
151
  Each host decides which services it connects its bots to. In the reference
99
- host a service is one module implementing `HostConnector`
100
- (`packages/cli/src/connectors/connector.ts`), passed to `startHost` as
101
- `connectors`:
102
-
103
- - `id` and `name`: what the host's description names.
104
- - `consentUrl(state, callback)`: where the browser goes to consent. It must
105
- come back to `callback`, `<host>/host/connect/<id>/callback`, with `state`.
106
- - `complete(query, callback)`: the browser back, with the callback's query.
107
- It answers what was connected (`account`, `reaches`, and `data` the host
108
- keeps and never shows, such as a refresh token), or why not. The host has
109
- already checked the state, the browser and the request; the connector checks
110
- what only the service can say, such as whether this person may give that
111
- account to a bot.
112
- - `tools(connection, { mayWrite, budget })`: what the bot may do on a
113
- connection. Tools that write must refuse without `mayWrite`, and each call
114
- to the service takes one from `budget`. What the service returns is someone
115
- else's words: mark it as data, as the GitHub tools do.
116
- - Set the host's public address (`MINCA_HOST_URL`) when a connector sends a
117
- `redirect_uri`: otherwise `callback` is worked out from each request.
118
- - `hook(body, headers)`, optional: calls from the service itself, at
119
- `<host>/host/connect/<id>/hook`. It answers `unsigned` for a call that isn't
120
- the service's, or which connections are gone (`forget`), or what they now
121
- reach at most (`reaches`): the host only narrows what a connection reaches,
122
- since one account at a service may serve several communities.
123
-
124
- Whatever the connector, the reference host stops acting through a
125
- connection, and forgets it, once the bot holds no role in the space or
126
- whoever made it may no longer configure the bot; it only ever narrows what a
127
- connection reaches; and it refuses two connectors with one id.
152
+ host, a service is one module implementing `HostConnector`, passed to
153
+ `startHost` as `connectors`. It lives in the CLI, which the API reference
154
+ doesn't cover, so here are its members:
155
+
156
+ | Member | Does |
157
+ | ----------------------------------------- | ------------------------------------------------------------ |
158
+ | `id`, `name` | What the host's description names |
159
+ | `consentUrl(state, callback)` | Where the browser goes to consent |
160
+ | `complete(query, callback)` | Handles the browser coming back, and says what was connected |
161
+ | `tools(connection, { mayWrite, budget })` | What the bot may do on a connection |
162
+ | `hook(body, headers)` | Optional. Handles calls from the service itself |
163
+
164
+ `consentUrl` must send the browser back to `callback`,
165
+ `<host>/host/connect/<id>/callback`, with `state`. Set the host's public
166
+ address (`MINCA_HOST_URL`) when a connector sends a `redirect_uri`. Otherwise
167
+ `callback` is worked out from each request.
168
+
169
+ `complete` gets the callback's query. It answers what was connected
170
+ (`account`, `reaches`, and `data` the host keeps and never shows, like a
171
+ refresh token), or why not. The host has already checked the state, the
172
+ browser and the request. The connector checks what only the service can say,
173
+ like whether this person may give that account to a bot.
174
+
175
+ `tools` that write must refuse without `mayWrite`, and each call to the
176
+ service takes one from `budget`. What the service returns is someone else's
177
+ words: mark it as data, as the GitHub tools do.
178
+
179
+ `hook` gets calls at `<host>/host/connect/<id>/hook`. It answers `unsigned`
180
+ for a call that isn't the service's, `forget` with the connections that are
181
+ gone, or `reaches` with what they now reach at most. The host only ever
182
+ narrows what a connection reaches, since one account at a service may serve
183
+ several communities.
184
+
185
+ Whatever the connector, the reference host:
186
+
187
+ - stops acting through a connection, and forgets it, once the bot holds no
188
+ role in the space or its maker may no longer configure the bot;
189
+ - only ever narrows what a connection reaches;
190
+ - refuses two connectors with one id.
128
191
 
129
192
  A Google Calendar connector, say, would send the browser to Google's consent
130
- screen, exchange the code for tokens in `complete`, keep the refresh token in
131
- `data`, and offer `calendar_events` and, with `mayWrite`, `calendar_add`.
193
+ screen, exchange the code for tokens in `complete`, and keep the refresh token
194
+ in `data`. It would offer `calendar_events`, and with `mayWrite`,
195
+ `calendar_add`.
132
196
 
133
197
  ## GitHub, in the reference host
134
198
 
135
- The reference host's GitHub connector
136
- (`packages/cli/src/connectors/github-connector.ts`) is a GitHub App. Its
137
- operator registers it once, with:
199
+ The reference host's GitHub connector is a GitHub App. Whoever
200
+ runs the host registers it once, with:
138
201
 
139
- - Callback URL `<host>/host/connect/github/callback`, and "Request user
202
+ - Callback URL `<host>/host/connect/github/callback`, with "Request user
140
203
  authorization (OAuth) during installation" ticked.
141
204
  - Webhook URL `<host>/host/connect/github/hook`, with a secret, subscribed to
142
205
  installation events.
143
- - Permissions: Issues and Pull requests read and write; Contents and Metadata
206
+ - Permissions: Issues and Pull requests read and write. Contents and Metadata
144
207
  read.
145
208
  - `MINCA_GITHUB_APP_ID`, `MINCA_GITHUB_APP_SLUG`, `MINCA_GITHUB_CLIENT_ID`,
146
- `MINCA_GITHUB_CLIENT_SECRET`, `MINCA_GITHUB_PRIVATE_KEY` (the PEM, or a
147
- path to it) and `MINCA_GITHUB_WEBHOOK_SECRET` in the host's environment,
148
- with `MINCA_HOST_BOTS=1`. Without the webhook secret the host takes no
149
- webhook calls, and learns of an uninstall only when a call fails.
209
+ `MINCA_GITHUB_CLIENT_SECRET`, `MINCA_GITHUB_PRIVATE_KEY` (the PEM, or a path
210
+ to it) and `MINCA_GITHUB_WEBHOOK_SECRET` in the host's environment, with
211
+ `MINCA_HOST_BOTS=1`.
212
+
213
+ Without the webhook secret, the host takes no webhook calls, and learns of an
214
+ uninstall only when a call fails.
215
+
216
+ ### Installing
150
217
 
151
218
  The person picks the organisation and its repositories on GitHub's install
152
- screen. GitHub doesn't vouch for the installation id it sends back, and lists
153
- an installation to anyone with access to one of its repositories, so the
154
- connector exchanges GitHub's code for the user's own token and keeps the
155
- installation only if it is on that user's account, or an organisation they
156
- are an active admin of. The bot then acts on GitHub as the App,
157
- `<slug>[bot]`, with tokens that last an hour, on those repositories only.
219
+ screen. The bot then acts on GitHub as the App, `<slug>[bot]`, on those
220
+ repositories only, with tokens that last an hour.
221
+
222
+ GitHub doesn't vouch for the installation id it sends back, and lists an
223
+ installation to anyone with access to one of its repositories. So the connector
224
+ exchanges GitHub's code for the user's own token, and keeps the installation
225
+ only if it is on that user's account, or on an organisation they are an
226
+ active admin of.
227
+
158
228
  When the App is uninstalled or suspended, the host forgets every connection
159
- through it. One installation may serve several communities of the same
160
- account, so a connection keeps the repositories it was made with: when GitHub
161
- says they changed, the host only narrows them, and each bot says so in its
162
- `std.connector`. Reaching a repository added later means connecting again.
163
- Repositories are kept by name: one renamed away, and another made under its
164
- old name in an installation for all repositories, is reached in its place.
165
- The App stays installed on GitHub after a disconnect, where whoever installed
166
- it can remove it.
229
+ through it. After a disconnect the App stays installed on GitHub, where
230
+ whoever installed it can remove it.
231
+
232
+ ### Which repositories
233
+
234
+ One installation may serve several communities of the same account. So a
235
+ connection keeps the repositories it was made with. When GitHub says they
236
+ changed, the host only narrows them, and each bot says so in its
237
+ `std.connector`. To reach a repository added later, connect again.
238
+
239
+ Repositories are kept by name. If one is renamed and another is made under its
240
+ old name, in an installation for all repositories, the new one is reached in
241
+ its place.
167
242
 
168
243
  ### The bot's tools
169
244
 
170
- A bot connected in a space has these there, beside its node actions:
245
+ A bot connected in a space has these there, beside its [node
246
+ actions](actions.md):
171
247
 
172
248
  | Tool | Does |
173
249
  | ---------------- | -------------------------------------------------------------------------------- |
@@ -177,31 +253,29 @@ A bot connected in a space has these there, beside its node actions:
177
253
  | `github_comment` | Comments on an issue or pull request |
178
254
  | `github_issue` | Opens an issue |
179
255
 
180
- - Every call names a repository the installation reaches, checked in code;
181
- a search is scoped to them.
182
- - It works like a chat app a workspace installs. The two that write run for
183
- an automation someone who may configure the bot made, whoever sets it off;
184
- what sets it off reaches the model as data, and can still steer it. An
185
- automation whose current words are by someone who may not instruct the bot
186
- isn't run at all.
256
+ It works like a chat app a workspace installs:
257
+
258
+ - The two that write run for an automation made by someone who may configure
259
+ the bot, whoever sets it off. What sets it off reaches the model as data,
260
+ and can still steer it. An automation whose current words are by someone
261
+ who may not instruct the bot doesn't run at all.
187
262
  - The three that read run for anyone whose record sets an automation off. A
188
263
  member can ask the bot what is in the connected repositories, private ones
189
- included, so connect only what everyone in the space may read.
190
- - A search shows only results in the connection's repositories, checked by
191
- each result's own repository, whatever the query says; an issue moved out
192
- of them isn't read at its old address.
193
- - Repositories are kept by name. A run keeps the tools it started with until
194
- it ends, a disconnect or uninstall notwithstanding.
195
- - Of several people's instructions, the bot takes the one written last as
196
- its writer's clock says; whoever may configure the bot is trusted with
197
- that, as with editing a bot's settings in any chat app.
198
- - The model never sees a token: each call adds one.
264
+ included. So connect only what everyone in the space may read.
265
+ - Every call names a repository the installation reaches, checked in code.
266
+ - A search is scoped to those repositories, and shows only results whose own
267
+ repository is one of them, whatever the query says. An issue moved out of
268
+ them isn't read at its old address.
269
+ - A run keeps the tools it started with until it ends, even through a
270
+ disconnect or uninstall.
271
+ - Of several people's instructions, the bot takes the one written last by its
272
+ writer's clock. Whoever may configure the bot is trusted with that, as with
273
+ a bot's settings in any chat app.
274
+ - The model never sees a token. Each call adds one.
199
275
  - What GitHub returns was written by people, possibly outside the space, and
200
276
  reaches the model marked as data.
201
- - 200 calls a bot a day, across its connectors, so a loop can't use up a
202
- service's limits.
203
-
204
- _Source: `packages/core/src/schemas/connectors.ts` (`connect`, `connector`, `botSettings`, `mayConfigure`, `askToConnect`, `connectPage`, `askToDisconnect`), `packages/core/src/session/hosting.ts` (`connectorOffers`), `packages/cli/src/host-connect.ts` (`createBotConnect`), `packages/cli/src/connectors/connector.ts` (`HostConnector`), `packages/cli/src/connectors/github-connector.ts` (`githubConnector`), `packages/cli/src/connectors/github.ts` (`createGitHubApp`), `packages/cli/src/connectors/github-tools.ts` (`githubTools`), `packages/cli/src/bot-runner.ts` (`runAutomations`, `personaIn`), `packages/cli/src/host-setup.ts` (`githubFromEnv`), `apps/shared/src/BotConnectors.tsx`. Tests: `packages/cli/tests/host-github.test.ts` ("connecting a bot to GitHub"), `packages/cli/tests/host-connect.test.ts` ("a host’s own connectors"), `packages/cli/tests/github.test.ts`, `packages/cli/tests/agent-automations.test.ts` ("a bot’s connectors", "a bot’s instructions", "takes instructions only from someone holding every grant of its roles")._
277
+ - A bot makes at most 200 calls a day across its connectors, so a loop can't
278
+ use up a service's limits.
205
279
 
206
280
  ## Planned
207
281