@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.
Files changed (48) hide show
  1. package/LICENSE +91 -0
  2. package/README.md +38 -2
  3. package/dist/access.d.ts +141 -0
  4. package/dist/access.js +232 -0
  5. package/dist/codec.d.ts +29 -0
  6. package/dist/codec.js +361 -0
  7. package/dist/cron.d.ts +2 -0
  8. package/dist/cron.js +113 -0
  9. package/dist/ctx.d.ts +644 -0
  10. package/dist/ctx.js +657 -0
  11. package/dist/db.d.ts +234 -0
  12. package/dist/db.js +495 -0
  13. package/dist/decimal.d.ts +39 -0
  14. package/dist/decimal.js +158 -0
  15. package/dist/declare.d.ts +311 -0
  16. package/dist/declare.js +78 -0
  17. package/dist/descriptor.d.ts +229 -0
  18. package/dist/descriptor.js +899 -0
  19. package/dist/errors.d.ts +65 -0
  20. package/dist/errors.js +114 -0
  21. package/dist/index.d.ts +17 -0
  22. package/dist/index.js +34 -0
  23. package/dist/log.d.ts +39 -0
  24. package/dist/log.js +101 -0
  25. package/dist/names.d.ts +12 -0
  26. package/dist/names.js +41 -0
  27. package/dist/notify.d.ts +185 -0
  28. package/dist/notify.js +234 -0
  29. package/dist/platform.d.ts +61 -0
  30. package/dist/platform.js +47 -0
  31. package/dist/plugin.d.ts +43 -0
  32. package/dist/plugin.js +117 -0
  33. package/dist/query.d.ts +326 -0
  34. package/dist/query.js +794 -0
  35. package/dist/remote.d.ts +8 -0
  36. package/dist/remote.js +19 -0
  37. package/dist/schema.d.ts +487 -0
  38. package/dist/schema.js +405 -0
  39. package/dist/serve.d.ts +63 -0
  40. package/dist/serve.js +411 -0
  41. package/dist/sql.d.ts +13 -0
  42. package/dist/sql.js +33 -0
  43. package/dist/ui.d.ts +1867 -0
  44. package/dist/ui.js +3964 -0
  45. package/dist/viz-kinds.d.ts +12 -0
  46. package/dist/viz-kinds.js +14 -0
  47. package/package.json +33 -4
  48. 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; }