@celobus/sdk 0.0.0-stage → 0.1.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/LICENSE +91 -0
- package/README.md +38 -2
- package/dist/access.d.ts +141 -0
- package/dist/access.js +232 -0
- package/dist/codec.d.ts +29 -0
- package/dist/codec.js +361 -0
- package/dist/cron.d.ts +2 -0
- package/dist/cron.js +113 -0
- package/dist/ctx.d.ts +644 -0
- package/dist/ctx.js +657 -0
- package/dist/db.d.ts +234 -0
- package/dist/db.js +495 -0
- package/dist/decimal.d.ts +39 -0
- package/dist/decimal.js +158 -0
- package/dist/declare.d.ts +311 -0
- package/dist/declare.js +78 -0
- package/dist/descriptor.d.ts +229 -0
- package/dist/descriptor.js +899 -0
- package/dist/errors.d.ts +65 -0
- package/dist/errors.js +114 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.js +34 -0
- package/dist/log.d.ts +39 -0
- package/dist/log.js +101 -0
- package/dist/names.d.ts +12 -0
- package/dist/names.js +41 -0
- package/dist/notify.d.ts +185 -0
- package/dist/notify.js +234 -0
- package/dist/platform.d.ts +61 -0
- package/dist/platform.js +47 -0
- package/dist/plugin.d.ts +43 -0
- package/dist/plugin.js +117 -0
- package/dist/query.d.ts +326 -0
- package/dist/query.js +794 -0
- package/dist/remote.d.ts +8 -0
- package/dist/remote.js +19 -0
- package/dist/schema.d.ts +487 -0
- package/dist/schema.js +405 -0
- package/dist/serve.d.ts +63 -0
- package/dist/serve.js +411 -0
- package/dist/sql.d.ts +13 -0
- package/dist/sql.js +33 -0
- package/dist/ui.d.ts +1867 -0
- package/dist/ui.js +3964 -0
- package/dist/viz-kinds.d.ts +12 -0
- package/dist/viz-kinds.js +14 -0
- package/package.json +33 -4
- package/proto/plugin.proto +994 -0
|
@@ -0,0 +1,994 @@
|
|
|
1
|
+
syntax = "proto3";
|
|
2
|
+
|
|
3
|
+
package celobus.v1;
|
|
4
|
+
|
|
5
|
+
option csharp_namespace = "Celobus.V1";
|
|
6
|
+
|
|
7
|
+
// The plugin contract: the session a plugin keeps with the platform, the calls it makes over it and what it declares
|
|
8
|
+
// about itself. Every SDK speaks it; a plugin never uses it directly.
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
// A plugin opens one session: the platform sends client requests, the plugin sends responses and syscalls.
|
|
12
|
+
service Celld {
|
|
13
|
+
rpc Session(stream PluginMessage) returns (stream CelldMessage);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
message Header {
|
|
17
|
+
string name = 1;
|
|
18
|
+
string value = 2;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
// plugin -> platform
|
|
22
|
+
message PluginMessage {
|
|
23
|
+
oneof kind {
|
|
24
|
+
Register register = 1; // first message of the session
|
|
25
|
+
Response response = 2;
|
|
26
|
+
Syscall syscall = 3;
|
|
27
|
+
Invalidate invalidate = 4;
|
|
28
|
+
JobDone job_done = 5; // the outcome of a run's attempt (JobRun)
|
|
29
|
+
PluginLog plugin_log = 6; // a log line of a run
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
// Plugin UI: a change to what a topic's followers read, sent by plugin code (`ctx.invalidate`)
|
|
34
|
+
// for keys an endpoint's `invalidates` cannot name. It carries no data: followers re-read as themselves.
|
|
35
|
+
message Invalidate {
|
|
36
|
+
string topic = 1;
|
|
37
|
+
string key = 2; // the canonical key: the key message's fields, sorted, values as strings; "" = every key
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
message Register {
|
|
41
|
+
string plugin = 1; // plugin name: /w/{workspace}/p/{plugin}/...
|
|
42
|
+
string version = 2;
|
|
43
|
+
string runtime = 3; // rust | node | dotnet
|
|
44
|
+
// plugins this plugin calls (from its dependency contracts); the plugin is ready only when they are attached
|
|
45
|
+
repeated string depends = 4;
|
|
46
|
+
// digest of the plugin's manifest (roles, scopes, method requirements); the platform refuses a mismatch
|
|
47
|
+
// with the installed manifest
|
|
48
|
+
string manifest_digest = 5;
|
|
49
|
+
// the token the platform handed this process (`CELOBUS_PLUGIN_TOKEN` in its environment): a session is
|
|
50
|
+
// accepted only for the plugin and the process it was issued for
|
|
51
|
+
string token = 6;
|
|
52
|
+
// how many runs of its jobs the process starts at once (its job pool); 0 = it runs no jobs. The platform never
|
|
53
|
+
// hands it more runs at once than this, so a run's timeout starts when its handler starts.
|
|
54
|
+
uint32 job_slots = 7;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
message Response {
|
|
58
|
+
uint64 id = 1; // request id from Request
|
|
59
|
+
uint32 status = 2;
|
|
60
|
+
repeated Header headers = 3;
|
|
61
|
+
bytes body = 4;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
message Syscall {
|
|
65
|
+
uint64 id = 1; // chosen by the plugin; echoed in SyscallResult
|
|
66
|
+
reserved 2, 3, 4, 6, 7, 8, 29, 38; // removed
|
|
67
|
+
reserved "kv_get", "kv_set", "kv_delete", "authz_check", "sql_read";
|
|
68
|
+
oneof call {
|
|
69
|
+
Invoke invoke = 5;
|
|
70
|
+
MembersList members_list = 9;
|
|
71
|
+
MemberGet member_get = 10;
|
|
72
|
+
GroupsList groups_list = 11;
|
|
73
|
+
AgentRunStart agent_run = 12;
|
|
74
|
+
AgentRunGet agent_get = 13;
|
|
75
|
+
AgentRunEvents agent_events = 14;
|
|
76
|
+
AgentRunList agent_runs = 15;
|
|
77
|
+
AgentRunSend agent_send = 16;
|
|
78
|
+
AgentRunCancel agent_cancel = 17;
|
|
79
|
+
AgentRunClose agent_close = 18;
|
|
80
|
+
DbGet db_get = 19;
|
|
81
|
+
DbFind db_find = 20;
|
|
82
|
+
DbCount db_count = 21;
|
|
83
|
+
DbCreate db_create = 22;
|
|
84
|
+
DbUpdate db_update = 23;
|
|
85
|
+
DbDelete db_delete = 24;
|
|
86
|
+
DbRestore db_restore = 25;
|
|
87
|
+
TxBegin tx_begin = 26;
|
|
88
|
+
TxCommit tx_commit = 27;
|
|
89
|
+
TxRollback tx_rollback = 28;
|
|
90
|
+
NotifySend notify_send = 30;
|
|
91
|
+
NotifyFollow notify_follow = 31;
|
|
92
|
+
NotifyResolve notify_resolve = 32;
|
|
93
|
+
AgentsAvailable agents_available = 33;
|
|
94
|
+
DbAggregate db_aggregate = 34;
|
|
95
|
+
DbUpdateWhere db_update_where = 35;
|
|
96
|
+
DbUpsert db_upsert = 36;
|
|
97
|
+
QueryRead query = 37;
|
|
98
|
+
SqlRun sql = 39;
|
|
99
|
+
JobEnqueue job_enqueue = 40;
|
|
100
|
+
JobCancel job_cancel = 41;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// The repository of the calling plugin's own entities: the platform stores the
|
|
105
|
+
// entities its descriptor declares in the workspace's database: a plugin sends typed requests and never sees a
|
|
106
|
+
// credential. A plugin reaches only its own entities (another plugin's data only through that plugin's endpoints).
|
|
107
|
+
// `entity` is the entity's name in the calling plugin's descriptor (`order_line`); a plugin without a descriptor has
|
|
108
|
+
// no entities (`unavailable`).
|
|
109
|
+
//
|
|
110
|
+
// A row crosses the session as the entity's message in the protobuf JSON mapping (UTF-8 JSON object: lowerCamelCase
|
|
111
|
+
// names, int64 and decimals as strings, absent fields omitted), the encoding every SDK's message codec speaks. Rows
|
|
112
|
+
// the platform returns also carry the system columns `createdAt`, `updatedAt` (always), `deletedAt` (soft-delete
|
|
113
|
+
// entities, when set) and `version` (versioned entities); in the entity's protobuf contract they are the fields
|
|
114
|
+
// 1001-1004.
|
|
115
|
+
//
|
|
116
|
+
// Every call carries `request_id`, the id of the Request the plugin is handling (as Invoke does; 0 outside one), and
|
|
117
|
+
// `tx`, a transaction from TxBegin (0: the call is a statement of its own). Errors are `<code>: <message>` in
|
|
118
|
+
// SyscallResult.error, with `error_details` for the codes that have some: `not_found` (404), `version_conflict` (409,
|
|
119
|
+
// `current_version`), `unique_conflict` (409, `column`), `append_only` (400), `invalid` (400: a row, a filter or a
|
|
120
|
+
// field the descriptor does not have; a call of another request than the one its transaction was begun in),
|
|
121
|
+
// `query_rows_limit` and `bulk_limit` (422), `row_locked` (409: a lock read with `NOWAIT` met a row another
|
|
122
|
+
// transaction holds), `transaction_timeout` (504: the transaction outlived its request's 5 s,
|
|
123
|
+
// or the request ended), `transaction_conflict` (409: a serialization failure or a deadlock), `unavailable` (503: no
|
|
124
|
+
// database, no connection within 1 s, a statement past its 2 s), and the refusals of the entity's access rules (403):
|
|
125
|
+
// `permission_denied` (a write the rules do not grant, or one that would leave the row unreadable to the writer; a
|
|
126
|
+
// row the caller cannot read is `not_found`), `guard_denied` (a change of a guarded column no guard rule admits),
|
|
127
|
+
// `capability_missing` (`as_system` on an entity or an operation outside the plugin's `authz:bypass`).
|
|
128
|
+
//
|
|
129
|
+
// Reads answer as the caller: rows the caller's rules grant, masked columns left out. `as_system` runs the call with
|
|
130
|
+
// the system context instead (every row of the entity, no masks), within the scope the plugin's `authz:bypass`
|
|
131
|
+
// capability declares, and each such call is recorded in the workspace's audit.
|
|
132
|
+
//
|
|
133
|
+
// A read of a dependency's entity (`ctx.query()`): DbGet, DbFind and DbCount with `dependency`, the provider's plugin
|
|
134
|
+
// id, and `entity` the provider's entity. The calling plugin's descriptor must declare that it reads the entity
|
|
135
|
+
// (`dependencies[].reads`), and the provider must export its `read`; the platform reads it as the caller, so the
|
|
136
|
+
// provider's read rules and masks apply, with only the fields the reader declared. Never with
|
|
137
|
+
// `as_system` (`capability_missing`): a system context does not reach another plugin's rows. `permission_denied`
|
|
138
|
+
// when the read is not declared or the provider does not export it; `unavailable` when the provider is not installed
|
|
139
|
+
// in the workspace or its installed contract lacks a field the reader declared.
|
|
140
|
+
message DbGet {
|
|
141
|
+
uint64 request_id = 1;
|
|
142
|
+
uint64 tx = 2;
|
|
143
|
+
string entity = 3;
|
|
144
|
+
string id = 4; // the key as protobuf JSON writes it: a UUID, an int64 in decimal, a string key
|
|
145
|
+
bool with_deleted = 5; // a soft-deleted row too
|
|
146
|
+
string as_system = 6; // the reason of a system context (`ctx.as_system`); empty: the caller's
|
|
147
|
+
string dependency = 7; // the provider whose exported entity is read; empty: the plugin's own entity
|
|
148
|
+
// navigations to bring with the row (`.include(..)`): a forward nav (or its ref column's name) or an inverse nav
|
|
149
|
+
// of the entity, each read under its target's own read rules; the answer's DbRows.included. Not with `dependency`.
|
|
150
|
+
repeated string include = 8;
|
|
151
|
+
DbLock lock = 9; // a row lock: only inside a transaction (`tx` set), only on the plugin's own entity
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
// A row lock of a read inside a declared transaction (`tx.db::<E>().get(id).for_update()`): the rows the read answers
|
|
155
|
+
// are locked until the transaction ends. Waiting for a lock counts against the transaction's 5 s (past them,
|
|
156
|
+
// `transaction_timeout`); `NOWAIT` fails at once with `row_locked` (409); `SKIP_LOCKED` leaves out the rows another
|
|
157
|
+
// transaction holds (a work queue). Refused (`invalid`) outside a transaction, on a dependency's entity, and with
|
|
158
|
+
// `with_deleted` or `all`.
|
|
159
|
+
message DbLock {
|
|
160
|
+
enum Strength { LOCK_NONE = 0; FOR_UPDATE = 1; FOR_SHARE = 2; }
|
|
161
|
+
Strength strength = 1;
|
|
162
|
+
enum Wait { WAIT = 0; NOWAIT = 1; SKIP_LOCKED = 2; }
|
|
163
|
+
Wait wait = 2;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
// One page of rows matching `filter` (unset: every row), in `order` then by id; keyset paging by `page_token`.
|
|
167
|
+
message DbFind {
|
|
168
|
+
uint64 request_id = 1;
|
|
169
|
+
uint64 tx = 2;
|
|
170
|
+
string entity = 3;
|
|
171
|
+
DbFilter filter = 4;
|
|
172
|
+
repeated DbOrder order = 5;
|
|
173
|
+
uint32 limit = 6; // 0 = 100; at most 100
|
|
174
|
+
string page_token = 7; // from DbRows.next_page_token; opaque
|
|
175
|
+
bool with_deleted = 8;
|
|
176
|
+
// every matching row at once (`.all()`): limit and page_token are ignored, and more than 1,000 rows is
|
|
177
|
+
// `query_rows_limit` (nothing is returned)
|
|
178
|
+
bool all = 9;
|
|
179
|
+
string as_system = 10;
|
|
180
|
+
string dependency = 11; // as in DbGet
|
|
181
|
+
// as in DbGet; the rows they bring count toward the 1,000 rows of a read (`query_rows_limit`)
|
|
182
|
+
repeated string include = 12;
|
|
183
|
+
DbLock lock = 13; // as in DbGet (not with `all`)
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
// Groups of the rows matching `filter` (unset: every row; soft-deleted rows only `with_deleted`), read as the
|
|
187
|
+
// caller as any read is: by the values of `group_by` (empty: one group of every row), each with the
|
|
188
|
+
// count of its rows (`COUNT`) or the sum of `field` (`SUM`: an int32, int64, double or decimal field; null values
|
|
189
|
+
// count as nothing, a group of none sums to 0). At most 1,000 groups (`query_rows_limit`, nothing answered), in the
|
|
190
|
+
// order of their keys (nulls last). The answer is DbGroups.
|
|
191
|
+
message DbAggregate {
|
|
192
|
+
uint64 request_id = 1;
|
|
193
|
+
uint64 tx = 2;
|
|
194
|
+
string entity = 3;
|
|
195
|
+
DbFilter filter = 4;
|
|
196
|
+
bool with_deleted = 5;
|
|
197
|
+
string as_system = 6;
|
|
198
|
+
string dependency = 7; // as in DbGet
|
|
199
|
+
string group_by = 8; // a comparable field or system column; empty: no groups
|
|
200
|
+
enum Measure { COUNT = 0; SUM = 1; }
|
|
201
|
+
Measure measure = 9;
|
|
202
|
+
string field = 10; // SUM: the field summed
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
// Changes the fields `patch` names (as DbUpdate) on every row matching `filter` (unset: every row) that the caller
|
|
206
|
+
// may read, in one statement: each row must pass the entity's `update` grant and its guards, as DbUpdate's does
|
|
207
|
+
// (one that does not refuses the whole statement: `permission_denied`, `guard_denied`); more than 1,000 rows is
|
|
208
|
+
// `bulk_limit` and nothing is written. `version` and `updated_at` move on each row changed; soft-deleted rows are
|
|
209
|
+
// not changed. The answer is DbCountResult: the rows changed.
|
|
210
|
+
message DbUpdateWhere {
|
|
211
|
+
uint64 request_id = 1;
|
|
212
|
+
uint64 tx = 2;
|
|
213
|
+
string entity = 3;
|
|
214
|
+
DbFilter filter = 4;
|
|
215
|
+
bytes patch = 5;
|
|
216
|
+
string as_system = 6;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
// Creates `row`, or, when a row with the same value of the unique column `on` exists (on a soft-delete entity: a
|
|
220
|
+
// row that is not deleted), changes that row to it (every field of `row`; `version` and `updated_at` move). `on`
|
|
221
|
+
// is a single-column unique field, or `id` on a `string`-key entity. The new row passes the `create` grant, the
|
|
222
|
+
// changed one the `update` grant and the guards (else `permission_denied` / `guard_denied`). The answer is DbRows
|
|
223
|
+
// with the row.
|
|
224
|
+
message DbUpsert {
|
|
225
|
+
uint64 request_id = 1;
|
|
226
|
+
uint64 tx = 2;
|
|
227
|
+
string entity = 3;
|
|
228
|
+
string on = 4;
|
|
229
|
+
bytes row = 5;
|
|
230
|
+
string as_system = 6;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
message DbCount {
|
|
234
|
+
uint64 request_id = 1;
|
|
235
|
+
uint64 tx = 2;
|
|
236
|
+
string entity = 3;
|
|
237
|
+
DbFilter filter = 4;
|
|
238
|
+
bool with_deleted = 5;
|
|
239
|
+
string as_system = 6;
|
|
240
|
+
string dependency = 7; // as in DbGet
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
// New rows, in one statement: the key is made by the platform for `uuid` (a UUIDv7) and `i64` (an identity) entities
|
|
244
|
+
// and taken from the row for `string` ones; system columns in a row are ignored. At most 1,000 rows (`bulk_limit`).
|
|
245
|
+
message DbCreate {
|
|
246
|
+
uint64 request_id = 1;
|
|
247
|
+
uint64 tx = 2;
|
|
248
|
+
string entity = 3;
|
|
249
|
+
repeated bytes rows = 4;
|
|
250
|
+
string as_system = 5;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
// Changes the fields `patch` names (a JSON object: a field set to `null` becomes null, a field not in it stays);
|
|
254
|
+
// `version` moves by one and `updated_at` to now. With `expected_version`, a row at another version is
|
|
255
|
+
// `version_conflict` (the current version in the details).
|
|
256
|
+
message DbUpdate {
|
|
257
|
+
uint64 request_id = 1;
|
|
258
|
+
uint64 tx = 2;
|
|
259
|
+
string entity = 3;
|
|
260
|
+
string id = 4;
|
|
261
|
+
bytes patch = 5;
|
|
262
|
+
optional int64 expected_version = 6;
|
|
263
|
+
string as_system = 7;
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
// Deletes a row: a soft-delete entity's row is marked (`deleted_at`) unless `force`, any other is removed.
|
|
267
|
+
message DbDelete {
|
|
268
|
+
uint64 request_id = 1;
|
|
269
|
+
uint64 tx = 2;
|
|
270
|
+
string entity = 3;
|
|
271
|
+
string id = 4;
|
|
272
|
+
optional int64 expected_version = 5;
|
|
273
|
+
bool force = 6;
|
|
274
|
+
string as_system = 7;
|
|
275
|
+
}
|
|
276
|
+
|
|
277
|
+
// Clears `deleted_at` of a soft-deleted row.
|
|
278
|
+
message DbRestore {
|
|
279
|
+
uint64 request_id = 1;
|
|
280
|
+
uint64 tx = 2;
|
|
281
|
+
string entity = 3;
|
|
282
|
+
string id = 4;
|
|
283
|
+
string as_system = 5;
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
// A condition tree over the entity's fields and system columns, by their canonical (snake_case) names. Never SQL.
|
|
287
|
+
message DbFilter {
|
|
288
|
+
oneof node {
|
|
289
|
+
DbFilters and = 1;
|
|
290
|
+
DbFilters or = 2;
|
|
291
|
+
DbFilter not = 3;
|
|
292
|
+
DbCondition condition = 4;
|
|
293
|
+
}
|
|
294
|
+
}
|
|
295
|
+
message DbFilters { repeated DbFilter items = 1; }
|
|
296
|
+
message DbCondition {
|
|
297
|
+
string field = 1;
|
|
298
|
+
enum Op {
|
|
299
|
+
OP_UNSPECIFIED = 0;
|
|
300
|
+
EQ = 1;
|
|
301
|
+
NE = 2;
|
|
302
|
+
LT = 3;
|
|
303
|
+
LE = 4;
|
|
304
|
+
GT = 5;
|
|
305
|
+
GE = 6;
|
|
306
|
+
IN = 7; // any of `values`
|
|
307
|
+
IS_NULL = 8; // no values
|
|
308
|
+
IS_NOT_NULL = 9;
|
|
309
|
+
// full-text search of a `searchable` field: `values` is one string of words, read as `websearch_to_tsquery` in
|
|
310
|
+
// the field's language (`"quoted phrase"`, `or`, `-word`); refused (`invalid`) on a field that is not searchable
|
|
311
|
+
SEARCH = 10;
|
|
312
|
+
// a case-insensitive substring of a string field: `values` is one string, taken literally (no wildcards)
|
|
313
|
+
CONTAINS = 11;
|
|
314
|
+
}
|
|
315
|
+
Op op = 2;
|
|
316
|
+
repeated DbValue values = 3; // one for a comparison
|
|
317
|
+
}
|
|
318
|
+
// A parameter, converted by the platform to the field's type (a decimal, a UUID, a timestamp or a date is a string as
|
|
319
|
+
// in protobuf JSON, bytes are bytes).
|
|
320
|
+
message DbValue {
|
|
321
|
+
oneof kind {
|
|
322
|
+
string string_value = 1;
|
|
323
|
+
int64 int_value = 2;
|
|
324
|
+
double double_value = 3;
|
|
325
|
+
bool bool_value = 4;
|
|
326
|
+
bytes bytes_value = 5;
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
message DbOrder { string field = 1; bool desc = 2; }
|
|
330
|
+
|
|
331
|
+
message DbRows {
|
|
332
|
+
repeated bytes rows = 1; // as in DbCreate, with the system columns
|
|
333
|
+
string next_page_token = 2; // empty: the last page
|
|
334
|
+
// with `include`: one JSON object per row, in the order of `rows`, from each included name to the row a forward
|
|
335
|
+
// nav names (left out when there is none or the caller may not read it) or the list of rows of an inverse nav
|
|
336
|
+
// (in id order; `[]` when none)
|
|
337
|
+
repeated bytes included = 3;
|
|
338
|
+
}
|
|
339
|
+
message DbCountResult { uint64 count = 1; }
|
|
340
|
+
message DbGroups { repeated DbGroup groups = 1; }
|
|
341
|
+
// A group's key (the group_by field's value as protobuf JSON: `null` for rows without one; `null` without groups)
|
|
342
|
+
// and its measure (a count as an int64, a sum as the field's type: an int64 for int32 and int64 fields), each the
|
|
343
|
+
// UTF-8 JSON of the value.
|
|
344
|
+
message DbGroup { bytes key = 1; bytes value = 2; }
|
|
345
|
+
|
|
346
|
+
// A declared transaction (`ctx.transaction`): open until TxCommit or TxRollback; the platform rolls it back when the
|
|
347
|
+
// request it was begun in ends, when its 5 s pass or when the session closes. A TxBegin with `tx` set is a nested
|
|
348
|
+
// transaction inside that one, which rolls back alone; ending one ends the transactions nested in it.
|
|
349
|
+
message TxBegin {
|
|
350
|
+
uint64 request_id = 1;
|
|
351
|
+
uint64 tx = 2; // the enclosing transaction: a nested one
|
|
352
|
+
enum Isolation { READ_COMMITTED = 0; REPEATABLE_READ = 1; SERIALIZABLE = 2; }
|
|
353
|
+
Isolation isolation = 3; // not on a nested transaction
|
|
354
|
+
bool read_only = 4;
|
|
355
|
+
string as_system = 5; // a transaction of a system context: its calls carry the same reason
|
|
356
|
+
}
|
|
357
|
+
message TxBegun { uint64 tx = 1; }
|
|
358
|
+
|
|
359
|
+
// SQL the plugin sends as text (`ctx.sql`, `ctx.unsafe_sql`), with `params` a JSON array:
|
|
360
|
+
// `$1` is its first value (a string, a number, `true`, `false`, `null`, an object or array as its JSON), typed where
|
|
361
|
+
// it stands in the query; a value never becomes SQL. The SQL is PostgreSQL's. The answer is DbRows: one JSON object
|
|
362
|
+
// per row (its columns by name), at most 1,000 (`query_rows_limit`), within the statement timeout (2 s).
|
|
363
|
+
// * `unsafe` false (`ctx.sql`): one query that reads (`select`, `with`, `values`, `table`) the entities of every
|
|
364
|
+
// installed plugin and the directory (`chat_post`, `platform_user`) as the caller: every entity's own rules and
|
|
365
|
+
// masks apply, and a system context lifts only its own plugin's. Part of the transaction inside one, read-only
|
|
366
|
+
// outside. Catalogs (`pg_*`, `information_schema`) and other workspaces are refused.
|
|
367
|
+
// * `unsafe` true (`ctx.unsafe_sql`, the capability `sql:unsafe`): the tables of every plugin of the workspace
|
|
368
|
+
// (`chat_post`, `crm_customer`) past their rules; a read, or with the capability `sql:write` also `insert`,
|
|
369
|
+
// `update` or `delete` (the rows of `returning` come back). Every relation it reads or writes must be a plugin's
|
|
370
|
+
// entity, never the platform's own data, the directory (`platform_user`) or a catalog (`permission_denied`
|
|
371
|
+
// otherwise). It runs in a system context of its own (guards and versions still hold) outside a transaction, and
|
|
372
|
+
// each run is recorded in the workspace's audit.
|
|
373
|
+
message SqlRun {
|
|
374
|
+
uint64 request_id = 1;
|
|
375
|
+
uint64 tx = 2;
|
|
376
|
+
string query = 3;
|
|
377
|
+
bytes params = 4;
|
|
378
|
+
bool unsafe = 5;
|
|
379
|
+
}
|
|
380
|
+
// A typed read across entities (`ctx.query()`): the SDK sends the query
|
|
381
|
+
// as a tree of entities and columns by their canonical names, operators and values as typed parameters, never SQL.
|
|
382
|
+
// The platform checks the tree against the installed descriptors and runs it as one read as the caller (read-only
|
|
383
|
+
// outside a declared transaction, part of the transaction inside one), within the statement timeout (2 s). Every
|
|
384
|
+
// entity of the tree is read through its own rules: the plugin's own entities by theirs, a dependency's exported
|
|
385
|
+
// entity (one the plugin declares it reads, with the fields it declares) by the provider's, the workspace directory
|
|
386
|
+
// (`platform.*`) by the reader's base role. A system context (`as_system`) reads the plugin's own entities within its
|
|
387
|
+
// `authz:bypass` (`read`) scope and the directory as a member does; a dependency's entity or one outside the scope
|
|
388
|
+
// is `capability_missing`.
|
|
389
|
+
//
|
|
390
|
+
// The answer: ALL, FIRST and PAGE are DbRows, one row per result row: a JSON array of the select items' values as
|
|
391
|
+
// protobuf JSON (`null` for none; a `label` is `{"id", "text", "avatarUrl"}` or `null`), or, without select, the root
|
|
392
|
+
// entity's row as DbFind answers it; COUNT is DbCountResult (the rows, or the groups of a grouped query).
|
|
393
|
+
//
|
|
394
|
+
// Errors besides the Db* calls': `query_invalid` (500: the tree names an entity, a column, a type or an operator the
|
|
395
|
+
// installed descriptors refuse, or breaks a rule of the tree; the message names the entity or the column),
|
|
396
|
+
// `query_size_limit` (422: the encoded tree is over 64 KiB, has more than 500 nodes or nests deeper than 16),
|
|
397
|
+
// `query_join_limit` (422: more than 8 entities, joined and in `exists`), `query_rows_limit` (422: ALL past 1,000
|
|
398
|
+
// rows or groups), `query_response_limit` (422: rows over 4 MiB).
|
|
399
|
+
message QueryRead {
|
|
400
|
+
uint64 request_id = 1;
|
|
401
|
+
uint64 tx = 2;
|
|
402
|
+
Query query = 3;
|
|
403
|
+
enum Mode {
|
|
404
|
+
ALL = 0; // every row, at most 1,000 (or `limit`)
|
|
405
|
+
FIRST = 1; // the first row, or none
|
|
406
|
+
COUNT = 2; // how many rows (or groups)
|
|
407
|
+
PAGE = 3; // a page of `limit` rows (0 = 100, at most 100) after `page_token`: keyset over the order and the keys
|
|
408
|
+
}
|
|
409
|
+
Mode mode = 4;
|
|
410
|
+
string page_token = 5; // PAGE: from DbRows.next_page_token; opaque, bound to the query's shape
|
|
411
|
+
string as_system = 6;
|
|
412
|
+
// where the query was composed (`src/jobs/remind.rs:52`): the platform logs it with a slow or refused query
|
|
413
|
+
string source = 7;
|
|
414
|
+
}
|
|
415
|
+
|
|
416
|
+
// The query tree. Names are canonical: an entity is `order` (the plugin's own), `crm.customer` (a dependency's) or
|
|
417
|
+
// `platform.user` (the directory: `platform.user`, `platform.group`, `platform.group_member`,
|
|
418
|
+
// `platform.role_assignment`); a column is a field's snake_case name, `id` or a system column (`created_at`, ...).
|
|
419
|
+
message Query {
|
|
420
|
+
repeated QuerySource sources = 1; // the first is the root (ROOT), each other joined to one before it
|
|
421
|
+
QueryExpr filter = 2; // unset: every row
|
|
422
|
+
repeated QueryColumn group_by = 3;
|
|
423
|
+
QueryExpr having = 4; // conditions on aggregates and grouped columns
|
|
424
|
+
repeated QuerySelect select = 5; // empty: the root's rows
|
|
425
|
+
repeated QueryOrder order = 6; // then the keys (each source's `id`, or the grouped columns)
|
|
426
|
+
uint32 limit = 7; // 0: none
|
|
427
|
+
}
|
|
428
|
+
|
|
429
|
+
// An entity of the query under its alias (`[a-z][a-z0-9_]{0,63}`, unique in the query; the SDKs default it to the
|
|
430
|
+
// canonical name with `_` for `.`: `crm_customer`). A join's `left` is a column of a source before it, `right` one of
|
|
431
|
+
// this source, both of one key: a ref and the `id` it names (either direction), or two refs to the same entity. A
|
|
432
|
+
// left-joined source's columns are null where no row (or no row the caller may read) matches.
|
|
433
|
+
message QuerySource {
|
|
434
|
+
string entity = 1;
|
|
435
|
+
string alias = 2;
|
|
436
|
+
enum Join { ROOT = 0; INNER = 1; LEFT = 2; }
|
|
437
|
+
Join join = 3;
|
|
438
|
+
QueryColumn left = 4;
|
|
439
|
+
QueryColumn right = 5;
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
message QueryColumn {
|
|
443
|
+
string source = 1; // a source's alias
|
|
444
|
+
string field = 2;
|
|
445
|
+
}
|
|
446
|
+
|
|
447
|
+
message QueryExpr {
|
|
448
|
+
oneof node {
|
|
449
|
+
QueryExprs and = 1;
|
|
450
|
+
QueryExprs or = 2;
|
|
451
|
+
QueryExpr not = 3;
|
|
452
|
+
QueryCompare compare = 4;
|
|
453
|
+
QueryExists exists = 5;
|
|
454
|
+
}
|
|
455
|
+
}
|
|
456
|
+
message QueryExprs { repeated QueryExpr items = 1; }
|
|
457
|
+
|
|
458
|
+
// `left op values` (EQ ... GE with one value, IN with any, IS_NULL and IS_NOT_NULL with none, SEARCH and CONTAINS with
|
|
459
|
+
// one string, as in DbCondition) or `left op right` (EQ ... GE: two columns of one type, or an aggregate and a column).
|
|
460
|
+
message QueryCompare {
|
|
461
|
+
QueryTerm left = 1;
|
|
462
|
+
DbCondition.Op op = 2;
|
|
463
|
+
repeated DbValue values = 3;
|
|
464
|
+
QueryTerm right = 4;
|
|
465
|
+
}
|
|
466
|
+
|
|
467
|
+
message QueryTerm {
|
|
468
|
+
oneof kind {
|
|
469
|
+
QueryColumn column = 1;
|
|
470
|
+
QueryAggregate aggregate = 2;
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
|
|
474
|
+
// COUNT counts rows (`column` unset); COUNT_DISTINCT the distinct values of a column; SUM (0 for none) and AVG of a
|
|
475
|
+
// number; MIN and MAX of a comparable column (null for none).
|
|
476
|
+
message QueryAggregate {
|
|
477
|
+
enum Fn { COUNT = 0; COUNT_DISTINCT = 1; SUM = 2; AVG = 3; MIN = 4; MAX = 5; }
|
|
478
|
+
Fn fn = 1;
|
|
479
|
+
QueryColumn column = 2;
|
|
480
|
+
}
|
|
481
|
+
|
|
482
|
+
// A correlated `EXISTS`: a row of `source` (an entity and its alias; the join fields are not used) for which `filter`
|
|
483
|
+
// holds; the filter may name the query's sources. NOT EXISTS is `not` around it.
|
|
484
|
+
message QueryExists {
|
|
485
|
+
QuerySource source = 1;
|
|
486
|
+
QueryExpr filter = 2;
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
// A select item: a row's values come back in the order of the items (an SDK names them by position).
|
|
490
|
+
message QuerySelect {
|
|
491
|
+
oneof kind {
|
|
492
|
+
QueryColumn column = 1;
|
|
493
|
+
QueryAggregate aggregate = 2;
|
|
494
|
+
// the label of the row a ref names (or of the source's own row, field `id`): a person's or a group's name (and
|
|
495
|
+
// avatar) from the directory, which every reader may read; another row's label column through its
|
|
496
|
+
// entity's rules (null when the caller may not read it)
|
|
497
|
+
QueryColumn label = 3;
|
|
498
|
+
}
|
|
499
|
+
}
|
|
500
|
+
|
|
501
|
+
message QueryOrder {
|
|
502
|
+
QueryTerm term = 1;
|
|
503
|
+
bool desc = 2; // ascending: nulls last; descending: nulls first
|
|
504
|
+
}
|
|
505
|
+
|
|
506
|
+
message TxCommit { uint64 request_id = 1; uint64 tx = 2; }
|
|
507
|
+
message TxRollback { uint64 request_id = 1; uint64 tx = 2; }
|
|
508
|
+
|
|
509
|
+
// Notifications: the calling plugin sends, the platform stores them, tracks read and done,
|
|
510
|
+
// follows and preferences, checks access and delivers (the inbox, live, and a daily email digest). A plugin never
|
|
511
|
+
// reads a notification, a follow or a member's settings, its own included; the one read it has is whether the
|
|
512
|
+
// caller of its request follows one of its own keys (NotifyFollow with op GET).
|
|
513
|
+
//
|
|
514
|
+
// NotifySend and NotifyFollow need the plugin's capability `push:send` (`capability_missing`, 403). Every call
|
|
515
|
+
// carries `request_id` (0 outside a request) and `tx` (0: written alone and emitted at once; a transaction of TxBegin:
|
|
516
|
+
// written in it and emitted when it commits, nothing when it rolls back). Errors are `<code>: <message>` in
|
|
517
|
+
// SyscallResult.error: `invalid` (400: an undeclared kind, a link, button, subject or actor the rules refuse, a
|
|
518
|
+
// field over its limit, an unspecified enum), `follow_limit` (409: a MANUAL follow outside a transaction would give a
|
|
519
|
+
// key more than 2,000 active followers), `unavailable` (503: no database, a statement past its 2 s; outside a
|
|
520
|
+
// transaction), and the transaction's own (`transaction_timeout`). In a transaction a call the database or a limit
|
|
521
|
+
// refuses is let go alone (logged) and answers `ok`, so a notification never undoes the plugin's write. Sends over
|
|
522
|
+
// 50 a second per plugin instance (bursts of 200) are let go too, in a transaction or not (the SDKs still map
|
|
523
|
+
// `rate_limited` to 429).
|
|
524
|
+
// NotifySend and NotifyResolve answer `ok`, and say nothing about who received what: a member's settings are not
|
|
525
|
+
// the plugin's to learn.
|
|
526
|
+
message NotifySend {
|
|
527
|
+
uint64 request_id = 1; // the request being handled: its caller is the default actor; 0 outside one
|
|
528
|
+
uint64 tx = 2; // written in that transaction; emitted when it commits
|
|
529
|
+
string kind = 3; // a kind of the plugin's descriptor; must be empty when `ask` is set
|
|
530
|
+
repeated string to = 4; // user ids, at most 100
|
|
531
|
+
bool followers = 5; // also the active followers of `key`
|
|
532
|
+
repeated string except = 6; // user ids left out (those already told in this request)
|
|
533
|
+
string key = 7; // <= 200 bytes; groups unread rows; required with followers and with ask
|
|
534
|
+
string subject = 8; // "<entity>/<id>" of the plugin's own entity: hidden from who cannot read the row
|
|
535
|
+
NotifyActor actor = 9;
|
|
536
|
+
string title = 10; // <= 140 characters, plain text
|
|
537
|
+
string body = 11; // <= 500 characters, plain text
|
|
538
|
+
NotifySource source = 12;
|
|
539
|
+
NotifyLink link = 13;
|
|
540
|
+
NotifyAsk ask = 14; // set: an approval or a decision; the only discriminator of an ask
|
|
541
|
+
string once = 15; // <= 120 bytes: a member gets at most one notification of this plugin per value
|
|
542
|
+
// (within retention); not with `ask`, whose key is its identity
|
|
543
|
+
}
|
|
544
|
+
message NotifyActor {
|
|
545
|
+
oneof who {
|
|
546
|
+
bool caller = 1; // the caller of request_id (the default when unset)
|
|
547
|
+
string agent = 2; // one of the plugin's own agents, by name: its service account
|
|
548
|
+
bool none = 3; // nobody: the plugin's mark is shown
|
|
549
|
+
}
|
|
550
|
+
}
|
|
551
|
+
message NotifySource {
|
|
552
|
+
string label = 1; // "#fulfilment", <= 80 characters
|
|
553
|
+
string icon = 2; // an icon of the kit by name ("hash")
|
|
554
|
+
}
|
|
555
|
+
message NotifyLink {
|
|
556
|
+
string screen = 1; // a screen of the plugin's UI document
|
|
557
|
+
string overlay = 2; // or a document-level overlay (a side panel: shown beside the inbox list)
|
|
558
|
+
string args = 3; // JSON object of the target's params, <= 1 KiB
|
|
559
|
+
// the plugin whose UI it opens: empty (the sending plugin; the starting plugin of AgentRunStart.notify_link) or
|
|
560
|
+
// that plugin's own id (`invalid` otherwise). The inbox's item names it as `link.plugin` when the row's plugin is
|
|
561
|
+
// another one (an agent run's end, a row of `platform`)
|
|
562
|
+
string plugin = 4;
|
|
563
|
+
}
|
|
564
|
+
message NotifyAsk {
|
|
565
|
+
enum Kind { KIND_UNSPECIFIED = 0; APPROVAL = 1; DECISION = 2; } // unspecified: `invalid`
|
|
566
|
+
Kind kind = 1;
|
|
567
|
+
repeated NotifyButton buttons = 2; // 1 to 3
|
|
568
|
+
string review = 3; // the link's label ("Review 5 changes"); the link is NotifySend.link
|
|
569
|
+
}
|
|
570
|
+
message NotifyButton {
|
|
571
|
+
string label = 1; // <= 32 characters
|
|
572
|
+
string endpoint = 2; // a declared `ui` endpoint of the plugin, by name ("ApproveRun")
|
|
573
|
+
string body = 3; // its request, a JSON object, <= 2 KiB
|
|
574
|
+
bool primary = 4;
|
|
575
|
+
string icon = 5;
|
|
576
|
+
}
|
|
577
|
+
// Follow, stop following, or ask whether the caller follows a key of the plugin.
|
|
578
|
+
message NotifyFollow {
|
|
579
|
+
uint64 request_id = 1;
|
|
580
|
+
uint64 tx = 2;
|
|
581
|
+
string key = 3; // <= 200 bytes
|
|
582
|
+
string subject = 4; // "<entity>/<id>": inherited by followers sends that name none
|
|
583
|
+
string noun = 5; // <= 24 characters: "thread" (the inbox's "Stop following this thread")
|
|
584
|
+
repeated string users = 6; // empty: the caller of request_id; at most 100; others than the caller only in a
|
|
585
|
+
// FOLLOW with REPLIED or EDITED (a manual follow and a stop are the member's own)
|
|
586
|
+
enum Reason { REASON_UNSPECIFIED = 0; MANUAL = 1; REPLIED = 2; EDITED = 3; } // unspecified: `invalid` (FOLLOW)
|
|
587
|
+
Reason reason = 7; // REPLIED / EDITED follow only members whose setting says so and who never stopped
|
|
588
|
+
enum Op { OP_UNSPECIFIED = 0; FOLLOW = 1; UNFOLLOW = 2; GET = 3; } // unspecified: `invalid`
|
|
589
|
+
Op op = 8; // GET: the caller's state (`users` empty); FOLLOW beyond 2,000: `follow_limit`
|
|
590
|
+
}
|
|
591
|
+
message NotifyFollowState { bool following = 1; }
|
|
592
|
+
// Every open ask of the plugin with this key is resolved (read and done, with its outcome), for every member.
|
|
593
|
+
message NotifyResolve {
|
|
594
|
+
uint64 request_id = 1;
|
|
595
|
+
uint64 tx = 2;
|
|
596
|
+
string key = 3;
|
|
597
|
+
string outcome = 4; // <= 80 characters: "Approved by Sarah Bennett"
|
|
598
|
+
}
|
|
599
|
+
|
|
600
|
+
// Member directory of the workspace, answered by the platform.
|
|
601
|
+
// `Member.email` is filled only for plugins whose manifest declares the permission `members.email`.
|
|
602
|
+
message MembersList { string page_token = 1; uint32 limit = 2; } // limit <= 500
|
|
603
|
+
message MemberGet { string user_id = 1; }
|
|
604
|
+
message GroupsList { string page_token = 1; uint32 limit = 2; }
|
|
605
|
+
message MembersPage { repeated Member members = 1; string next_page_token = 2; }
|
|
606
|
+
message GroupsPage { repeated Group groups = 1; string next_page_token = 2; }
|
|
607
|
+
|
|
608
|
+
// Agent runs from a plugin's code. A plugin starts the runs of its own
|
|
609
|
+
// agents (`agent` is a name it declares) and of the agents of the workspace's other plugins that the caller of the
|
|
610
|
+
// request it handles reaches (`<plugin>.<name>`; never for a caller that is an agent's account: `forbidden`). It reads and acts on the runs of its own agents and on the runs
|
|
611
|
+
// its code started; any other run answers `not_found`. Errors are `<code>: <message>` in SyscallResult.error:
|
|
612
|
+
// `unknown_agent`, `not_found` (404), `run_ended` (409), `bad_request` (400), `forbidden` and the admission refusals
|
|
613
|
+
// (403).
|
|
614
|
+
message AgentRunStart {
|
|
615
|
+
// the agent: its name in the calling plugin (`assistant`), or `<plugin>.<name>` of an agent of another installed
|
|
616
|
+
// plugin, which the caller of the request (`request_id`) must reach as for `POST /sys/agent-runs` (`forbidden`)
|
|
617
|
+
string agent = 1;
|
|
618
|
+
string input = 2; // the task
|
|
619
|
+
// What a start leaves out is what the agent's declaration says, then the platform's default.
|
|
620
|
+
string engine = 3; // claude | codex | pi; empty = unset
|
|
621
|
+
string model = 4; // empty = unset
|
|
622
|
+
optional bool session = 5;
|
|
623
|
+
uint32 timeout_s = 6; // 0 = unset
|
|
624
|
+
// the id of the Request this plugin is handling: its caller is who started the run (`started_by`). A start
|
|
625
|
+
// without a request in progress is refused (`forbidden`)
|
|
626
|
+
uint64 request_id = 7;
|
|
627
|
+
// The group the run joins: the id of a group this plugin's code founded, that is, of
|
|
628
|
+
// a run its code started without one. Empty: the run founds a new group. `unknown_group` (404) when the platform no
|
|
629
|
+
// longer remembers the group's first run or another plugin founded it, `agent_in_group` (409) when the agent has
|
|
630
|
+
// a live run in the group already, `group_full` (409) when the group has its eight live runs.
|
|
631
|
+
string group = 8;
|
|
632
|
+
// Tell the person the run works for when it finishes; a failure always notifies.
|
|
633
|
+
bool notify = 9;
|
|
634
|
+
// Where the notification of its end opens (a screen or overlay of the calling plugin's UI).
|
|
635
|
+
NotifyLink notify_link = 10;
|
|
636
|
+
// A topic of the calling plugin (one its descriptor declares; `bad_request` otherwise), invalidated whenever this
|
|
637
|
+
// run changes, as the topic its agent declares is. Empty: none.
|
|
638
|
+
string topic = 11;
|
|
639
|
+
// The key of `topic` to invalidate: the canonical key, as Invalidate.key (the key message's fields, sorted, values
|
|
640
|
+
// as strings). Empty: every key. A key without a topic is `bad_request`.
|
|
641
|
+
string topic_key = 12;
|
|
642
|
+
}
|
|
643
|
+
message AgentRunGet { string run_id = 1; }
|
|
644
|
+
// The events after `after` (a sequence number; 0 = from the first), oldest first, at most `limit` (0 = all the run
|
|
645
|
+
// keeps), with the run and its unfinished text. Answered at once: a follower re-reads when the agent's topic is
|
|
646
|
+
// invalidated (`Agent.topic` in the descriptor).
|
|
647
|
+
message AgentRunEvents { string run_id = 1; uint64 after = 2; uint32 limit = 3; }
|
|
648
|
+
// The recent runs the calling plugin sees (of its own agents, and the runs its code started), newest first; `agent`
|
|
649
|
+
// narrows them to one agent: a name of its own, or `<plugin>.<name>`. limit: 0 = 50, at most 200. `group` narrows
|
|
650
|
+
// them to the runs of one group (AgentRun.group).
|
|
651
|
+
message AgentRunList { string agent = 1; uint32 limit = 2; string group = 3; }
|
|
652
|
+
// A follow-up input of a run that has not ended, recorded as sent by the caller of the request in progress
|
|
653
|
+
// (`request_id`, as in AgentRunStart).
|
|
654
|
+
message AgentRunSend { string run_id = 1; string text = 2; uint64 request_id = 3; }
|
|
655
|
+
message AgentRunCancel { string run_id = 1; } // stop now
|
|
656
|
+
message AgentRunClose { string run_id = 1; } // end a session after its turn
|
|
657
|
+
|
|
658
|
+
// A run as its plugin sees it.
|
|
659
|
+
message AgentRun {
|
|
660
|
+
string id = 1;
|
|
661
|
+
string agent = 2; // the agent's name in its plugin
|
|
662
|
+
string plugin = 3;
|
|
663
|
+
string engine = 4;
|
|
664
|
+
string model = 5; // empty: the engine's own
|
|
665
|
+
string status = 6; // starting | running | idle | succeeded | failed | cancelled | timed_out
|
|
666
|
+
bool session = 7;
|
|
667
|
+
string input = 8;
|
|
668
|
+
string result = 9; // of the last finished turn; empty: none yet
|
|
669
|
+
AgentRunError error = 10; // unset unless the run failed or timed out
|
|
670
|
+
AgentRunActor started_by = 11; // the caller of the request the run was started in, or of the HTTP call
|
|
671
|
+
string started_by_plugin = 12; // the plugin whose code started it; empty: started over HTTP
|
|
672
|
+
int64 created_at = 13; // unix milliseconds, like the two below
|
|
673
|
+
int64 updated_at = 14;
|
|
674
|
+
int64 deadline_at = 15;
|
|
675
|
+
uint32 turn = 16;
|
|
676
|
+
uint64 last_seq = 17; // the sequence number of its last event
|
|
677
|
+
string pod = 18; // where the run executes, as last reported; for diagnostics
|
|
678
|
+
// The group the run belongs to: the id of the group's first run (its own id for a run that founded one). The
|
|
679
|
+
// agents of a group message each other by name; an agent never leaves its group.
|
|
680
|
+
string group = 19;
|
|
681
|
+
string parent = 20; // the agent run that started this one; empty: a person or a plugin's code did
|
|
682
|
+
string parent_agent = 21; // that run's agent, `<plugin>.<name>`; empty with `parent`
|
|
683
|
+
AgentRunActor on_behalf_of = 22; // the person at the root: who started the run, or the run that started it
|
|
684
|
+
}
|
|
685
|
+
message AgentRunError { string code = 1; string message = 2; }
|
|
686
|
+
message AgentRunActor { string user_id = 1; string display_name = 2; }
|
|
687
|
+
// One event of a run. `json` is the whole event as the HTTP route returns it (a JSON object: `seq`, `at`, `type`
|
|
688
|
+
// and the fields of its type).
|
|
689
|
+
message AgentRunEvent { uint64 seq = 1; int64 at = 2; string type = 3; bytes json = 4; }
|
|
690
|
+
// The messages being written right now: text, not events. `rev` counts the changes (0: none yet).
|
|
691
|
+
message AgentRunPartial {
|
|
692
|
+
uint64 rev = 1;
|
|
693
|
+
repeated AgentRunPartialMessage messages = 2;
|
|
694
|
+
}
|
|
695
|
+
message AgentRunPartialMessage { string message_id = 1; string text = 2; }
|
|
696
|
+
message AgentRunEventsPage {
|
|
697
|
+
AgentRun run = 1;
|
|
698
|
+
repeated AgentRunEvent events = 2;
|
|
699
|
+
AgentRunPartial partial = 3;
|
|
700
|
+
}
|
|
701
|
+
message AgentRunsPage { repeated AgentRun runs = 1; }
|
|
702
|
+
message AgentRunInput { uint64 seq = 1; } // the sequence number of the input a send recorded
|
|
703
|
+
|
|
704
|
+
// The agents of the workspace's installed plugins that the caller of the request in progress (`request_id`) may
|
|
705
|
+
// start a run of: those of the plugins they reach, the calling plugin's own among them. Refused (`forbidden`) without
|
|
706
|
+
// a request of a signed-in caller.
|
|
707
|
+
message AgentsAvailable { uint64 request_id = 1; }
|
|
708
|
+
// An agent as its installed package describes it.
|
|
709
|
+
message AvailableAgent {
|
|
710
|
+
string agent = 1; // `<plugin>.<name>`: what AgentRunStart.agent takes
|
|
711
|
+
string plugin = 2;
|
|
712
|
+
string name = 3;
|
|
713
|
+
string title = 4; // its display name: the declared title, else its name
|
|
714
|
+
string description = 5;
|
|
715
|
+
string icon = 6; // its glyph, a lucide icon name; empty: none
|
|
716
|
+
// the engine its runs get in this workspace when a start names none: an owner's or admin's choice, else the
|
|
717
|
+
// declared one, else its connection's protocol's (AgentEngines); empty: none can be resolved (no connection)
|
|
718
|
+
string engine = 7;
|
|
719
|
+
bool session = 8; // its runs are sessions by its declaration
|
|
720
|
+
string plugin_title = 9; // its plugin's title, else the plugin's id
|
|
721
|
+
}
|
|
722
|
+
// Sorted by plugin, then name.
|
|
723
|
+
message AvailableAgents { repeated AvailableAgent agents = 1; }
|
|
724
|
+
|
|
725
|
+
// Call another plugin of the workspace (through the platform).
|
|
726
|
+
message Invoke {
|
|
727
|
+
string plugin = 1;
|
|
728
|
+
Request request = 2; // id is ignored; principal is set by the platform
|
|
729
|
+
// the id of the Request this plugin is handling: the call runs as that request's caller and must pass
|
|
730
|
+
// the same admission test for the target. 0 = no caller (refused by methods that need a member)
|
|
731
|
+
uint64 request_id = 3;
|
|
732
|
+
}
|
|
733
|
+
|
|
734
|
+
// Background jobs. A job is a payload message and a handler, declared in the plugin's descriptor
|
|
735
|
+
// (`jobs`) with its retries, timeout, concurrency, schedule and who it runs as. A run is one execution of a job, with
|
|
736
|
+
// a stable id across its attempts; the platform delivers it at least once (JobRun), and the plugin answers each
|
|
737
|
+
// attempt (JobDone). A plugin reaches only its own jobs and runs.
|
|
738
|
+
|
|
739
|
+
// Starts a run of one of the calling plugin's jobs, as the caller of the request or run in progress (a job declared
|
|
740
|
+
// to run as the system always does). With `tx`, the run is written in that transaction and exists only if it
|
|
741
|
+
// commits; without, it is recorded when the call returns. Errors: `invalid` (job not declared, payload not the
|
|
742
|
+
// job's message, `at` more than a year ahead), `payload_too_large` (over 64 KiB: put larger input in an entity and
|
|
743
|
+
// pass its id), `queue_full` (429: 10,000 pending runs of the plugin), `cancelled` (the run making the call was
|
|
744
|
+
// aborted). A singleton enqueue inside a transaction may wait for a concurrent transaction enqueuing the same key.
|
|
745
|
+
message JobEnqueue {
|
|
746
|
+
string job = 1; // the job's key in the plugin (`remind_unpaid`)
|
|
747
|
+
string payload = 2; // the job's message, protobuf JSON mapping
|
|
748
|
+
oneof when {
|
|
749
|
+
uint64 delay_ms = 3;
|
|
750
|
+
int64 at_unix_ms = 4; // unset: now
|
|
751
|
+
}
|
|
752
|
+
// non-empty: one run per key and job while that run is kept (7 days after it ends, 30 if it failed); past
|
|
753
|
+
// 100,000 kept runs of a job, the oldest keys may be reused earlier
|
|
754
|
+
string singleton = 5;
|
|
755
|
+
uint64 request_id = 6; // as on every call
|
|
756
|
+
uint64 tx = 7; // 0: not in a transaction
|
|
757
|
+
}
|
|
758
|
+
// existing: the key was taken by an earlier run, whose id and state are returned (its payload is kept, not replaced)
|
|
759
|
+
message JobEnqueued {
|
|
760
|
+
string run_id = 1;
|
|
761
|
+
bool existing = 2;
|
|
762
|
+
RunState state = 3;
|
|
763
|
+
}
|
|
764
|
+
// The state of a run. `failed` means failed for good: its retries used up, or it failed as permanent.
|
|
765
|
+
enum RunState {
|
|
766
|
+
RUN_STATE_UNSPECIFIED = 0;
|
|
767
|
+
RUN_STATE_PENDING = 1;
|
|
768
|
+
RUN_STATE_RUNNING = 2;
|
|
769
|
+
RUN_STATE_DONE = 3;
|
|
770
|
+
RUN_STATE_FAILED = 4;
|
|
771
|
+
RUN_STATE_CANCELLED = 5;
|
|
772
|
+
}
|
|
773
|
+
|
|
774
|
+
// Cancels one of the plugin's own runs: a pending run never starts, a running one is aborted (JobAbort, CANCELLED).
|
|
775
|
+
// `not_found` when the plugin has no such run.
|
|
776
|
+
message JobCancel {
|
|
777
|
+
string run_id = 1;
|
|
778
|
+
uint64 request_id = 2;
|
|
779
|
+
}
|
|
780
|
+
message JobCancelled { bool cancelled = 1; } // false: it had already ended
|
|
781
|
+
|
|
782
|
+
// A run to execute now. The handler's calls carry `request_id`, as a request's do, and run as the run's principal.
|
|
783
|
+
message JobRun {
|
|
784
|
+
string run_id = 1;
|
|
785
|
+
string job = 2; // the job's key
|
|
786
|
+
uint32 attempt = 3; // 1 on the first delivery
|
|
787
|
+
// retries + 1; after an admin's retry: the attempts so far + retries + 1 (`attempt` never restarts, so
|
|
788
|
+
// `attempt == max_attempts` is always the last try)
|
|
789
|
+
uint32 max_attempts = 4;
|
|
790
|
+
string payload = 5; // protobuf JSON mapping
|
|
791
|
+
Principal principal = 6; // unset: the plugin's system principal
|
|
792
|
+
// the occurrence (or due time) the run stands for; the same in every attempt
|
|
793
|
+
int64 scheduled_at_unix_ms = 7;
|
|
794
|
+
uint32 timeout_ms = 8;
|
|
795
|
+
uint64 request_id = 9;
|
|
796
|
+
}
|
|
797
|
+
// Stop the run's handler; answer its JobDone when it has stopped. From this moment every call carrying the
|
|
798
|
+
// attempt's `request_id` is answered `cancelled`, and its open transactions roll back.
|
|
799
|
+
message JobAbort {
|
|
800
|
+
string run_id = 1;
|
|
801
|
+
// An open set: an SDK treats a reason it does not know as CANCELLED.
|
|
802
|
+
enum Reason {
|
|
803
|
+
REASON_UNSPECIFIED = 0;
|
|
804
|
+
TIMEOUT = 1; // past the job's timeout
|
|
805
|
+
CANCELLED = 2; // by the plugin (JobCancel) or a workspace admin
|
|
806
|
+
SHUTDOWN = 3; // the platform stops; the attempt is not charged
|
|
807
|
+
LEASE_LOST = 4; // the platform lost track of the attempt and will deliver the run again
|
|
808
|
+
AUTH_CHANGED = 5; // the principal it runs as left the workspace
|
|
809
|
+
REMOVED = 6; // the job or the plugin was removed
|
|
810
|
+
}
|
|
811
|
+
Reason reason = 2;
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
// The outcome of one attempt of a run (`attempt` as in its JobRun). A late answer to an attempt that already ended
|
|
815
|
+
// is ignored.
|
|
816
|
+
message JobDone {
|
|
817
|
+
string run_id = 1;
|
|
818
|
+
uint32 attempt = 2;
|
|
819
|
+
oneof outcome {
|
|
820
|
+
JobOk ok = 3;
|
|
821
|
+
JobError error = 4;
|
|
822
|
+
}
|
|
823
|
+
}
|
|
824
|
+
message JobOk {}
|
|
825
|
+
message JobError {
|
|
826
|
+
// For the admin screen and logs. Codes the platform itself records for an attempt: `timeout`, `cancelled`,
|
|
827
|
+
// `shutdown`, `lease_lost`, `process_exited`, `auth_changed`, `job_removed`, `plugin_removed`,
|
|
828
|
+
// `payload_invalid`; the SDKs send their error classes (`unavailable`, `internal`, `invalid`, `not_found`,
|
|
829
|
+
// `permission_denied`); a plugin's own codes are free-form.
|
|
830
|
+
string code = 1;
|
|
831
|
+
string message = 2; // at most 2 KiB is kept
|
|
832
|
+
bool permanent = 3; // the only signal: true = not retried
|
|
833
|
+
}
|
|
834
|
+
|
|
835
|
+
// One log line of the run whose `request_id` it carries; kept with the run, by attempt. Lines of a request are not
|
|
836
|
+
// kept this way.
|
|
837
|
+
message PluginLog {
|
|
838
|
+
uint64 request_id = 1;
|
|
839
|
+
enum Level {
|
|
840
|
+
LEVEL_UNSPECIFIED = 0;
|
|
841
|
+
DEBUG = 1;
|
|
842
|
+
INFO = 2;
|
|
843
|
+
WARN = 3;
|
|
844
|
+
ERROR = 4;
|
|
845
|
+
}
|
|
846
|
+
Level level = 2;
|
|
847
|
+
string message = 3; // cut at 2 KiB
|
|
848
|
+
int64 at_unix_ms = 4;
|
|
849
|
+
}
|
|
850
|
+
|
|
851
|
+
// platform -> plugin
|
|
852
|
+
message CelldMessage {
|
|
853
|
+
oneof kind {
|
|
854
|
+
Registered registered = 1;
|
|
855
|
+
Request request = 2;
|
|
856
|
+
SyscallResult syscall_result = 3;
|
|
857
|
+
JobRun job_run = 4;
|
|
858
|
+
JobAbort job_abort = 5;
|
|
859
|
+
}
|
|
860
|
+
}
|
|
861
|
+
|
|
862
|
+
message Registered {
|
|
863
|
+
string instance_id = 1;
|
|
864
|
+
}
|
|
865
|
+
|
|
866
|
+
message Request {
|
|
867
|
+
uint64 id = 1;
|
|
868
|
+
string method = 2;
|
|
869
|
+
string path = 3; // path after /w/{workspace}/p/{plugin}
|
|
870
|
+
string query = 4;
|
|
871
|
+
repeated Header headers = 5;
|
|
872
|
+
bytes body = 6;
|
|
873
|
+
// who calls: set by the platform (never by a plugin); unset for system calls
|
|
874
|
+
Principal principal = 7;
|
|
875
|
+
}
|
|
876
|
+
|
|
877
|
+
// The caller of a plugin request, resolved by the platform. An invoke between plugins carries the original caller.
|
|
878
|
+
message Principal {
|
|
879
|
+
string user_id = 1;
|
|
880
|
+
enum Kind { KIND_UNSPECIFIED = 0; PERSON = 1; SERVICE = 2; }
|
|
881
|
+
Kind kind = 2;
|
|
882
|
+
string display_name = 3;
|
|
883
|
+
// effective roles: workspace.owner|admin|member (expanded) and plugin roles <plugin>.<role>
|
|
884
|
+
repeated string roles = 4;
|
|
885
|
+
repeated string groups = 5; // group ids
|
|
886
|
+
// the token's scopes for the target plugin, expanded: plugin:* / plugin:<name> -> every scope the
|
|
887
|
+
// plugin declares, as <plugin>:<scope>
|
|
888
|
+
repeated string scopes = 6;
|
|
889
|
+
}
|
|
890
|
+
|
|
891
|
+
// A workspace member as plugins see it (directory).
|
|
892
|
+
message Member {
|
|
893
|
+
string user_id = 1;
|
|
894
|
+
Principal.Kind kind = 2;
|
|
895
|
+
string display_name = 3;
|
|
896
|
+
repeated string roles = 4;
|
|
897
|
+
repeated string groups = 5;
|
|
898
|
+
string email = 6; // only for plugins with members.email
|
|
899
|
+
string avatar_url = 7;
|
|
900
|
+
int64 last_active = 8; // unix seconds, hour resolution
|
|
901
|
+
string locale = 9;
|
|
902
|
+
}
|
|
903
|
+
|
|
904
|
+
message Group {
|
|
905
|
+
string id = 1;
|
|
906
|
+
string name = 2;
|
|
907
|
+
repeated string members = 3; // user ids
|
|
908
|
+
}
|
|
909
|
+
|
|
910
|
+
message SyscallResult {
|
|
911
|
+
uint64 id = 1;
|
|
912
|
+
string error = 2; // empty = success
|
|
913
|
+
reserved 3, 6, 21; // removed
|
|
914
|
+
reserved "kv_value", "authz";
|
|
915
|
+
oneof result {
|
|
916
|
+
Response invoke_response = 4;
|
|
917
|
+
Empty ok = 5;
|
|
918
|
+
MembersPage members_page = 7;
|
|
919
|
+
Member member = 8; // MemberGet; error "not found" when absent
|
|
920
|
+
GroupsPage groups_page = 9;
|
|
921
|
+
AgentRun agent_run = 10; // AgentRunStart/Get/Cancel/Close
|
|
922
|
+
AgentRunEventsPage agent_events = 11;
|
|
923
|
+
AgentRunsPage agent_runs = 12;
|
|
924
|
+
AgentRunInput agent_input = 13; // AgentRunSend
|
|
925
|
+
DbRows db_rows = 14; // DbGet (one row), DbFind, DbCreate, DbUpdate, DbRestore (one row), SqlRun, QueryRead
|
|
926
|
+
DbCountResult db_count = 15; // DbCount, DbUpdateWhere, QueryRead (COUNT)
|
|
927
|
+
TxBegun tx_begun = 16;
|
|
928
|
+
NotifyFollowState notify_follow_state = 18; // NotifyFollow; NotifySend and NotifyResolve answer ok
|
|
929
|
+
AvailableAgents agents_available = 19;
|
|
930
|
+
DbGroups db_groups = 20; // DbAggregate
|
|
931
|
+
JobEnqueued job_enqueued = 22; // JobEnqueue
|
|
932
|
+
JobCancelled job_cancelled = 23; // JobCancel
|
|
933
|
+
}
|
|
934
|
+
DbErrorDetails error_details = 17; // with some `error` codes of the Db* calls
|
|
935
|
+
}
|
|
936
|
+
|
|
937
|
+
message DbErrorDetails {
|
|
938
|
+
int64 current_version = 1; // version_conflict
|
|
939
|
+
string column = 2; // unique_conflict
|
|
940
|
+
}
|
|
941
|
+
|
|
942
|
+
message Empty {}
|
|
943
|
+
|
|
944
|
+
|
|
945
|
+
// What a plugin declares about itself (installed with the plugin; part of the manifest digest).
|
|
946
|
+
message PluginManifest {
|
|
947
|
+
repeated RoleDecl roles = 1;
|
|
948
|
+
repeated ScopeDecl scopes = 2;
|
|
949
|
+
repeated AgentDecl agents = 3;
|
|
950
|
+
repeated string depends = 4;
|
|
951
|
+
repeated string permissions = 5; // e.g. members.email
|
|
952
|
+
repeated MethodRequirement requires = 6;
|
|
953
|
+
// The dependency endpoints the plugin calls (`/<dep>.v1.<Service>/<Method>`); an invoke of another endpoint of a
|
|
954
|
+
// dependency that has entries here is refused (`call_undeclared`).
|
|
955
|
+
repeated string calls = 7;
|
|
956
|
+
// The connections the plugin declares: installing it creates them, not set up, in the
|
|
957
|
+
// workspace; an owner or admin fills them in; uninstalling removes them.
|
|
958
|
+
repeated ConnectionDecl connections = 8;
|
|
959
|
+
}
|
|
960
|
+
message ConnectionDecl {
|
|
961
|
+
string name = 1; // snake_case, unique in the plugin
|
|
962
|
+
string kind = 2; // llm | stt
|
|
963
|
+
string title = 3;
|
|
964
|
+
string description = 4;
|
|
965
|
+
}
|
|
966
|
+
message RoleDecl {
|
|
967
|
+
string name = 1; // without the plugin prefix
|
|
968
|
+
string title = 2;
|
|
969
|
+
string description = 3;
|
|
970
|
+
enum Default { NONE = 0; MEMBER = 1; ADMIN = 2; }
|
|
971
|
+
Default default_for = 4;
|
|
972
|
+
}
|
|
973
|
+
message ScopeDecl { string name = 1; string title = 2; string description = 3; } // becomes <plugin>:<name>
|
|
974
|
+
message AgentDecl {
|
|
975
|
+
string name = 1;
|
|
976
|
+
repeated string roles = 2;
|
|
977
|
+
// the workspace permissions the agent asks for: with
|
|
978
|
+
// one, it does the workspace operations that take it as an admin would
|
|
979
|
+
repeated string workspace = 3;
|
|
980
|
+
// The agents this one may bring into its group when they are not there: an agent of
|
|
981
|
+
// the same plugin by its name, or `<dependency>.<agent>`. Messaging an agent that is in the group already needs
|
|
982
|
+
// no entry here.
|
|
983
|
+
repeated string delegates = 4;
|
|
984
|
+
// The `llm` connection its runs use: `<name>` of a connection of this plugin, or `<dependency>.<name>`. Empty: none
|
|
985
|
+
// (a run fails `unconfigured` until an owner or admin chooses one in the agent's settings).
|
|
986
|
+
string connection = 5;
|
|
987
|
+
// The agent has an SSH key of its own (ed25519, one pair per workspace), given to its runs in `~/.ssh`.
|
|
988
|
+
bool ssh_key = 6;
|
|
989
|
+
// The agent's service account asks for base role admin instead of member:
|
|
990
|
+
// only an owner installs or upgrades to a version that asks for it. Never owner.
|
|
991
|
+
bool admin = 7;
|
|
992
|
+
}
|
|
993
|
+
// method = "/<package>.<Service>/<Method>"; empty any_role and scope = the default (an active member)
|
|
994
|
+
message MethodRequirement { string method = 1; string scope = 2; repeated string any_role = 3; }
|