@minca/core 0.1.2 → 0.1.3
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 +7 -5
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +3 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/types.d.ts +2 -0
- package/dist/node/types.d.ts.map +1 -1
- package/dist/schemas/connectors.d.ts +189 -0
- package/dist/schemas/connectors.d.ts.map +1 -0
- package/dist/schemas/connectors.js +134 -0
- package/dist/schemas/connectors.js.map +1 -0
- package/dist/schemas/index.d.ts +2 -0
- package/dist/schemas/index.d.ts.map +1 -1
- package/dist/schemas/index.js +1 -0
- package/dist/schemas/index.js.map +1 -1
- package/dist/schemas/standard.d.ts.map +1 -1
- package/dist/schemas/standard.js +2 -0
- package/dist/schemas/standard.js.map +1 -1
- package/dist/session/hosting.d.ts +9 -0
- package/dist/session/hosting.d.ts.map +1 -1
- package/dist/session/hosting.js +16 -0
- package/dist/session/hosting.js.map +1 -1
- package/docs/README.md +1 -0
- package/docs/actions.md +18 -10
- package/docs/agents.md +6 -1
- package/docs/bots.md +210 -0
- package/docs/standard-library.md +7 -0
- package/package.json +1 -1
package/docs/agents.md
CHANGED
|
@@ -81,8 +81,13 @@ What the reference sides add:
|
|
|
81
81
|
- The terminal waits 60 s to hear `code:heard`, then 10 minutes for the
|
|
82
82
|
answer, and checks the grant with `checkGrant(grant, did, { recordsOnly: true })`
|
|
83
83
|
before keeping it, and again each time it starts.
|
|
84
|
+
- The terminal makes a new key for each code. Connecting again, after a
|
|
85
|
+
disconnect or to renew, gives a new key and note; a running `minca mcp`
|
|
86
|
+
takes them up without a restart. The earlier connection stays in the
|
|
87
|
+
account home until it runs out or is disconnected there, and nothing can use
|
|
88
|
+
it: its key is gone from the computer.
|
|
84
89
|
|
|
85
|
-
_Source: `packages/core/src/session/connect-code.ts`, `packages/cli/src/agent.ts` (`connectAgent`, `startAgentNode`), `apps/example/src/components/ConnectAgent.tsx`, `apps/example/src/program-terms.ts`, `apps/home/src/components/ConnectPage.tsx`. Tests: `packages/core/tests/connect-code.test.ts`, `packages/core/tests/records-only.test.ts` ("a program connected by code, through the account home"), `apps/example/tests/program-terms.test.ts`._
|
|
90
|
+
_Source: `packages/core/src/session/connect-code.ts`, `packages/cli/src/agent.ts` (`connectAgent`, `startAgentNode`, `reloadOnConnect`), `apps/example/src/components/ConnectAgent.tsx`, `apps/example/src/program-terms.ts`, `apps/home/src/components/ConnectPage.tsx`. Tests: `packages/core/tests/connect-code.test.ts`, `packages/core/tests/records-only.test.ts` ("a program connected by code, through the account home"), `apps/example/tests/program-terms.test.ts`, `packages/cli/tests/agent-reconnect.test.ts`._
|
|
86
91
|
|
|
87
92
|
## Tools an agent gets
|
|
88
93
|
|
package/docs/bots.md
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
# Bots and their connectors
|
|
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.
|
|
9
|
+
|
|
10
|
+
## Who may configure a bot
|
|
11
|
+
|
|
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.
|
|
16
|
+
|
|
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`):
|
|
23
|
+
|
|
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.
|
|
29
|
+
|
|
30
|
+
## Instructions
|
|
31
|
+
|
|
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`).
|
|
41
|
+
|
|
42
|
+
| Collection | Body | Rules |
|
|
43
|
+
| ---------- | ----------------------------------------------- | ------------------------ |
|
|
44
|
+
| `std.bot` | **`bot`** DID; **`instructions`** string ≤ 2000 | `onePer: [@author, bot]` |
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"bot": "did:key:zDnaeYffVz7N…",
|
|
49
|
+
"instructions": "You are Ferris, the team's helper. Answer briefly, and link issues as #N."
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Connecting a bot
|
|
54
|
+
|
|
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.
|
|
60
|
+
|
|
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
|
|
64
|
+
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.
|
|
69
|
+
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.
|
|
72
|
+
|
|
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`.
|
|
76
|
+
|
|
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.
|
|
79
|
+
|
|
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]` |
|
|
84
|
+
|
|
85
|
+
Example request, for the secret `AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA` (43 `A`s):
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"bot": "did:key:zDnaeYffVz7N…",
|
|
90
|
+
"kind": "github",
|
|
91
|
+
"verifier": "DwBzhbb51LfusnSGBa_hqYSgo7-j8BTQnip4TOnlzRo",
|
|
92
|
+
"expires": "2026-10-15T12:09:00Z"
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Writing a connector
|
|
97
|
+
|
|
98
|
+
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.
|
|
128
|
+
|
|
129
|
+
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`.
|
|
132
|
+
|
|
133
|
+
## GitHub, in the reference host
|
|
134
|
+
|
|
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:
|
|
138
|
+
|
|
139
|
+
- Callback URL `<host>/host/connect/github/callback`, and "Request user
|
|
140
|
+
authorization (OAuth) during installation" ticked.
|
|
141
|
+
- Webhook URL `<host>/host/connect/github/hook`, with a secret, subscribed to
|
|
142
|
+
installation events.
|
|
143
|
+
- Permissions: Issues and Pull requests read and write; Contents and Metadata
|
|
144
|
+
read.
|
|
145
|
+
- `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.
|
|
150
|
+
|
|
151
|
+
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.
|
|
158
|
+
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.
|
|
167
|
+
|
|
168
|
+
### The bot's tools
|
|
169
|
+
|
|
170
|
+
A bot connected in a space has these there, beside its node actions:
|
|
171
|
+
|
|
172
|
+
| Tool | Does |
|
|
173
|
+
| ---------------- | -------------------------------------------------------------------------------- |
|
|
174
|
+
| `github_search` | Issues and pull requests in its repositories, in GitHub's search syntax |
|
|
175
|
+
| `github_get` | One issue or pull request: text, labels, latest comments, a pull request's files |
|
|
176
|
+
| `github_file` | A file at a branch, tag or commit |
|
|
177
|
+
| `github_comment` | Comments on an issue or pull request |
|
|
178
|
+
| `github_issue` | Opens an issue |
|
|
179
|
+
|
|
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.
|
|
187
|
+
- The three that read run for anyone whose record sets an automation off. A
|
|
188
|
+
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.
|
|
199
|
+
- What GitHub returns was written by people, possibly outside the space, and
|
|
200
|
+
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.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")._
|
|
205
|
+
|
|
206
|
+
## Planned
|
|
207
|
+
|
|
208
|
+
- GitHub events as records ("PR #12 opened"), so automations can answer them.
|
|
209
|
+
- Connectors for a bot a member runs, which has no public address for a
|
|
210
|
+
service to send people back to.
|
package/docs/standard-library.md
CHANGED
|
@@ -266,6 +266,13 @@ to be a certain way, or at set times, and what each automation did. An
|
|
|
266
266
|
account keeps automations of its own in its registry too, which notify it. Described in
|
|
267
267
|
[automations.md](automations.md).
|
|
268
268
|
|
|
269
|
+
**Bots**
|
|
270
|
+
|
|
271
|
+
`std.bot`, `std.connect` and `std.connector`: how a community wants its bot
|
|
272
|
+
to be, someone asking a bot's host to connect the bot to a service such as
|
|
273
|
+
GitHub, and the bot saying what it is connected to. Described in
|
|
274
|
+
[bots.md](bots.md).
|
|
275
|
+
|
|
269
276
|
**Activity.** `std.activity` is someone at work on a record, for apps to show
|
|
270
277
|
while it lasts: "My bot is working on it…" under a message, a spinner on a
|
|
271
278
|
task. Anyone may write one, only about their own work, and apps show it as
|