@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/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.
@@ -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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@minca/core",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "type": "module",
5
5
  "description": "Self-sovereign P2P protocol for the browser — identity, schemas, storage, networking, and gossip sync",
6
6
  "repository": {