@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.
- package/README.md +2 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/node/actions.d.ts +3 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +1 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +1 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/index.d.ts +1 -1
- package/dist/node/index.d.ts.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +13 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-runtime.d.ts +5 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +3 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/types.d.ts +112 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/node/watch-notifications.d.ts +6 -0
- package/dist/node/watch-notifications.d.ts.map +1 -1
- package/dist/node/watch-notifications.js +47 -9
- package/dist/node/watch-notifications.js.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/session/account-hint.d.ts +2 -2
- package/dist/session/account-hint.d.ts.map +1 -1
- package/dist/session/account-hint.js +3 -3
- package/dist/session/account-hint.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/connection.d.ts +18 -0
- package/dist/session/connection.d.ts.map +1 -1
- package/dist/session/connection.js +11 -0
- package/dist/session/connection.js.map +1 -1
- package/dist/session/index.d.ts +2 -2
- package/dist/session/index.d.ts.map +1 -1
- package/dist/session/index.js +2 -2
- package/dist/session/index.js.map +1 -1
- package/dist/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +213 -152
- package/docs/agents.md +198 -167
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -311
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +86 -159
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -65
- package/docs/inbox.md +138 -93
- package/docs/node.md +1081 -996
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +487 -416
- package/docs/spaces.md +261 -246
- package/docs/standard-library.md +487 -526
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -6
- package/dist/elements/auth-styles.d.ts +0 -18
- package/dist/elements/auth-styles.d.ts.map +0 -1
- package/dist/elements/auth-styles.js +0 -206
- package/dist/elements/auth-styles.js.map +0 -1
- package/dist/elements/dom.d.ts +0 -29
- package/dist/elements/dom.d.ts.map +0 -1
- package/dist/elements/dom.js +0 -91
- package/dist/elements/dom.js.map +0 -1
- package/dist/elements/index.d.ts +0 -13
- package/dist/elements/index.d.ts.map +0 -1
- package/dist/elements/index.js +0 -11
- package/dist/elements/index.js.map +0 -1
- package/dist/elements/minca-auth.d.ts +0 -55
- package/dist/elements/minca-auth.d.ts.map +0 -1
- package/dist/elements/minca-auth.js +0 -768
- 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
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
the space, GitHub
|
|
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
|
|
14
|
-
|
|
15
|
-
|
|
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
|
-
|
|
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
|
-
|
|
25
|
-
|
|
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
|
-
|
|
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
|
-
|
|
33
|
-
|
|
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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
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.
|
|
62
|
-
|
|
63
|
-
2.
|
|
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
|
|
66
|
-
3.
|
|
67
|
-
|
|
68
|
-
the bot
|
|
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
|
|
71
|
-
|
|
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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
115
|
+
```ts
|
|
116
|
+
import type { SpaceHostingView } from '@minca/core';
|
|
117
|
+
import { askToConnect, askToDisconnect } from '@minca/core/schemas';
|
|
76
118
|
|
|
77
|
-
|
|
78
|
-
|
|
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
|
|
81
|
-
| --------------- |
|
|
82
|
-
| `std.connect` | **`bot`** DID; **`kind`**
|
|
83
|
-
| `std.connector` | **`bot`** DID; **`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
|
-
|
|
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
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
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
|
|
131
|
-
`data
|
|
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
|
-
|
|
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`,
|
|
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
|
|
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
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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.
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
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.
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
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
|
|
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
|
-
|
|
181
|
-
|
|
182
|
-
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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
|
|
190
|
-
-
|
|
191
|
-
|
|
192
|
-
of them
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
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
|
|
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
|
|