@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
package/dist/ctx.js
ADDED
|
@@ -0,0 +1,657 @@
|
|
|
1
|
+
// The context of one request: who calls, the request itself, and what the plugin may do through the platform
|
|
2
|
+
// (dependency calls, its entities and declared transactions, reads of its dependencies' entities, SQL, the
|
|
3
|
+
// directory, the runs of its agents, notifications: `ctx.notifications`, notify.ts; background jobs: `ctx.jobs` to
|
|
4
|
+
// enqueue and cancel runs, `ctx.job` for the run a job's handler is in). Events are not available: those members
|
|
5
|
+
// exist and reject with `unavailable`.
|
|
6
|
+
import { encodeMessage, stringify } from "./codec.js";
|
|
7
|
+
import { Repository, TxRepository } from "./db.js";
|
|
8
|
+
import { RpcError, internal, invalid, unauthenticated, unavailable } from "./errors.js";
|
|
9
|
+
import { durationMs } from "./declare.js";
|
|
10
|
+
import { endpointPath, snake } from "./names.js";
|
|
11
|
+
import { Notifications, linkWire } from "./notify.js";
|
|
12
|
+
import { entityNames, foreignPlugin } from "./schema.js";
|
|
13
|
+
import { startQuery } from "./query.js";
|
|
14
|
+
import { sqlParams, sqlRows } from "./sql.js";
|
|
15
|
+
/** @internal A syscall that the platform answered with an error string (and the details some db refusals have). */
|
|
16
|
+
export class SyscallError extends Error {
|
|
17
|
+
details;
|
|
18
|
+
constructor(message, details) {
|
|
19
|
+
super(message);
|
|
20
|
+
this.details = details;
|
|
21
|
+
this.name = "SyscallError";
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
/** Who calls the request, resolved by the platform from the workspace's members. */
|
|
25
|
+
export class Caller {
|
|
26
|
+
pluginId;
|
|
27
|
+
roleName;
|
|
28
|
+
userId;
|
|
29
|
+
kind;
|
|
30
|
+
displayName;
|
|
31
|
+
/** Effective roles, full names: `workspace.*` (expanded) and `<plugin>.<role>`. */
|
|
32
|
+
roles;
|
|
33
|
+
/** Group ids. */
|
|
34
|
+
groups;
|
|
35
|
+
/** The token's scopes for this plugin, full names `<plugin>:<scope>`. */
|
|
36
|
+
scopes;
|
|
37
|
+
constructor(principal, pluginId, roleName = () => undefined) {
|
|
38
|
+
this.pluginId = pluginId;
|
|
39
|
+
this.roleName = roleName;
|
|
40
|
+
this.userId = principal?.userId || undefined;
|
|
41
|
+
this.kind = !principal ? "system" : principal.kind === "SERVICE" ? "service" : "user";
|
|
42
|
+
this.displayName = principal?.displayName ?? "";
|
|
43
|
+
this.roles = principal?.roles ?? [];
|
|
44
|
+
this.groups = principal?.groups ?? [];
|
|
45
|
+
this.scopes = principal?.scopes ?? [];
|
|
46
|
+
}
|
|
47
|
+
/** The calling user's id; throws 401 `unauthenticated` when the request has none. */
|
|
48
|
+
user() {
|
|
49
|
+
if (!this.userId)
|
|
50
|
+
throw unauthenticated();
|
|
51
|
+
return this.userId;
|
|
52
|
+
}
|
|
53
|
+
/** Holds the role: a role object of this plugin, its short name (`clerk`) or a full name (`workspace.admin`). */
|
|
54
|
+
has(role) {
|
|
55
|
+
const name = typeof role === "string" ? role : this.roleName(role);
|
|
56
|
+
if (!name)
|
|
57
|
+
return false;
|
|
58
|
+
return this.roles.includes(name.includes(".") ? name : `${this.pluginId}.${name}`);
|
|
59
|
+
}
|
|
60
|
+
/** The token allows the scope: short (`read`) or full (`orders:read`). */
|
|
61
|
+
hasScope(scope) {
|
|
62
|
+
return this.scopes.includes(scope.includes(":") ? scope : `${this.pluginId}:${scope}`);
|
|
63
|
+
}
|
|
64
|
+
inGroup(groupId) {
|
|
65
|
+
return this.groups.includes(groupId);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
function notAvailable(what) {
|
|
69
|
+
return Promise.reject(unavailable(`${what} is not available`));
|
|
70
|
+
}
|
|
71
|
+
function memberOf(m) {
|
|
72
|
+
return {
|
|
73
|
+
userId: m.userId,
|
|
74
|
+
kind: m.kind === "SERVICE" ? "service" : "user",
|
|
75
|
+
displayName: m.displayName ?? "",
|
|
76
|
+
roles: m.roles ?? [],
|
|
77
|
+
groups: m.groups ?? [],
|
|
78
|
+
email: m.email ?? "",
|
|
79
|
+
avatarUrl: m.avatarUrl ?? "",
|
|
80
|
+
lastActive: Number(m.lastActive ?? 0),
|
|
81
|
+
locale: m.locale ?? "",
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
const PAGE = 500;
|
|
85
|
+
/** What the platform refuses a job call with besides the db codes (`invalid`, `not_found`). */
|
|
86
|
+
const JOB_REFUSALS = new Map([
|
|
87
|
+
["queue_full", 429],
|
|
88
|
+
["payload_too_large", 413],
|
|
89
|
+
// the run making the call was stopped (its abort)
|
|
90
|
+
["cancelled", 503],
|
|
91
|
+
]);
|
|
92
|
+
/** The admission refusals the platform answers a syscall with (`<code>: <message>`): 403 with that code. */
|
|
93
|
+
const DENIALS = new Set(["call_undeclared", "missing_role", "missing_scope", "reach", "not_a_member"]);
|
|
94
|
+
/**
|
|
95
|
+
* What the platform refuses an `agent_*` syscall with, and the status each code answers: an agent or a run the plugin does
|
|
96
|
+
* not have is 404, a run that ended the platform's `run_ended` conflict; a group the plugin did not found is 404, a
|
|
97
|
+
* group that has the agent already or is full a conflict.
|
|
98
|
+
*/
|
|
99
|
+
const AGENT_REFUSALS = new Map([
|
|
100
|
+
["unknown_agent", 404],
|
|
101
|
+
["not_found", 404],
|
|
102
|
+
["run_ended", 409],
|
|
103
|
+
["unknown_group", 404],
|
|
104
|
+
["agent_in_group", 409],
|
|
105
|
+
["group_full", 409],
|
|
106
|
+
["bad_request", 400],
|
|
107
|
+
["forbidden", 403],
|
|
108
|
+
]);
|
|
109
|
+
/** What the platform refuses a `notify_*` syscall with besides the db codes (`invalid`, `capability_missing`). */
|
|
110
|
+
const NOTIFY_REFUSALS = new Map([
|
|
111
|
+
["follow_limit", 409],
|
|
112
|
+
["rate_limited", 429],
|
|
113
|
+
]);
|
|
114
|
+
/**
|
|
115
|
+
* What the platform refuses a `Db*` or `Tx*` syscall with, and the status each code answers; `version_conflict` carries
|
|
116
|
+
* `details.current`, `unique_conflict` `details.column`.
|
|
117
|
+
*/
|
|
118
|
+
const DB_REFUSALS = new Map([
|
|
119
|
+
["not_found", 404],
|
|
120
|
+
["version_conflict", 409],
|
|
121
|
+
["unique_conflict", 409],
|
|
122
|
+
["transaction_conflict", 409],
|
|
123
|
+
["append_only", 400],
|
|
124
|
+
["invalid", 400],
|
|
125
|
+
["query_rows_limit", 422],
|
|
126
|
+
["bulk_limit", 422],
|
|
127
|
+
["row_locked", 409],
|
|
128
|
+
["transaction_timeout", 504],
|
|
129
|
+
["permission_denied", 403],
|
|
130
|
+
["guard_denied", 403],
|
|
131
|
+
["capability_missing", 403],
|
|
132
|
+
["query_invalid", 500],
|
|
133
|
+
["query_size_limit", 422],
|
|
134
|
+
["query_join_limit", 422],
|
|
135
|
+
["query_response_limit", 422],
|
|
136
|
+
]);
|
|
137
|
+
/**
|
|
138
|
+
* A syscall error as the handler sees it: an admission refusal is 403 with its code, a refusal of an agent, a
|
|
139
|
+
* notification or a db call its own status and code (with the details a db refusal has), anything else 503 `unavailable`.
|
|
140
|
+
*/
|
|
141
|
+
export function syscallFailed(e) {
|
|
142
|
+
if (!(e instanceof SyscallError))
|
|
143
|
+
return e;
|
|
144
|
+
const i = e.message.indexOf(": ");
|
|
145
|
+
const code = i > 0 ? e.message.slice(0, i) : "";
|
|
146
|
+
const message = e.message.slice(i + 2);
|
|
147
|
+
if (DENIALS.has(code))
|
|
148
|
+
return new RpcError(403, code, message);
|
|
149
|
+
const status = AGENT_REFUSALS.get(code) ?? NOTIFY_REFUSALS.get(code) ?? JOB_REFUSALS.get(code);
|
|
150
|
+
if (status !== undefined)
|
|
151
|
+
return new RpcError(status, code, message);
|
|
152
|
+
const db = DB_REFUSALS.get(code);
|
|
153
|
+
if (db !== undefined) {
|
|
154
|
+
const details = {};
|
|
155
|
+
if (code === "version_conflict" && e.details)
|
|
156
|
+
details.current = Number(e.details.currentVersion);
|
|
157
|
+
if (code === "unique_conflict" && e.details)
|
|
158
|
+
details.column = e.details.column;
|
|
159
|
+
return new RpcError(db, code, message, details);
|
|
160
|
+
}
|
|
161
|
+
return unavailable(e.message);
|
|
162
|
+
}
|
|
163
|
+
const ENDED = new Set(["succeeded", "failed", "cancelled", "timed_out"]);
|
|
164
|
+
const RUN_STATUSES = new Set(["starting", "running", "idle", "succeeded", "failed", "cancelled", "timed_out"]);
|
|
165
|
+
/** @internal Reads the hook's body (`{run_id, agent, plugin, status, turn, last_seq, topic, topic_key, ended}`). */
|
|
166
|
+
export function runChangeOf(body) {
|
|
167
|
+
const v = (body !== null && typeof body === "object" ? body : {});
|
|
168
|
+
const get = (snakeName, camel) => v[snakeName] ?? v[camel];
|
|
169
|
+
const str = (snakeName, camel = snakeName) => {
|
|
170
|
+
const x = get(snakeName, camel);
|
|
171
|
+
return typeof x === "string" ? x : "";
|
|
172
|
+
};
|
|
173
|
+
const num = (snakeName, camel = snakeName) => {
|
|
174
|
+
const x = get(snakeName, camel);
|
|
175
|
+
const n = typeof x === "number" ? x : typeof x === "string" && /^\d+$/.test(x) ? Number(x) : 0;
|
|
176
|
+
return Number.isSafeInteger(n) && n >= 0 ? n : 0;
|
|
177
|
+
};
|
|
178
|
+
const runId = str("run_id", "runId");
|
|
179
|
+
if (!runId)
|
|
180
|
+
throw invalid("run_id is required");
|
|
181
|
+
const raw = str("status");
|
|
182
|
+
const status = raw === "queued" ? "starting" : RUN_STATUSES.has(raw) ? raw : "unknown";
|
|
183
|
+
const ended = v.ended;
|
|
184
|
+
return {
|
|
185
|
+
runId,
|
|
186
|
+
agent: str("agent"),
|
|
187
|
+
plugin: str("plugin"),
|
|
188
|
+
status,
|
|
189
|
+
turn: num("turn"),
|
|
190
|
+
lastSeq: num("last_seq", "lastSeq"),
|
|
191
|
+
topic: str("topic"),
|
|
192
|
+
topicKey: str("topic_key", "topicKey"),
|
|
193
|
+
ended: typeof ended === "boolean" ? ended : ENDED.has(status),
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
function runOf(r, what) {
|
|
197
|
+
if (!r)
|
|
198
|
+
throw unavailable(`the platform answered ${what} with something else`);
|
|
199
|
+
// a run the platform names no person at the root of was started by that person
|
|
200
|
+
const root = r.onBehalfOf ?? r.startedBy;
|
|
201
|
+
return {
|
|
202
|
+
id: r.id,
|
|
203
|
+
agent: r.agent,
|
|
204
|
+
plugin: r.plugin,
|
|
205
|
+
engine: r.engine,
|
|
206
|
+
...(r.model ? { model: r.model } : {}),
|
|
207
|
+
status: r.status,
|
|
208
|
+
ended: ENDED.has(r.status),
|
|
209
|
+
session: !!r.session,
|
|
210
|
+
input: r.input ?? "",
|
|
211
|
+
...(r.result ? { result: r.result } : {}),
|
|
212
|
+
...(r.error ? { error: { code: r.error.code, message: r.error.message } } : {}),
|
|
213
|
+
startedBy: { userId: r.startedBy?.userId ?? "", displayName: r.startedBy?.displayName ?? "" },
|
|
214
|
+
...(r.startedByPlugin ? { startedByPlugin: r.startedByPlugin } : {}),
|
|
215
|
+
createdAt: Number(r.createdAt ?? 0),
|
|
216
|
+
updatedAt: Number(r.updatedAt ?? 0),
|
|
217
|
+
deadlineAt: Number(r.deadlineAt ?? 0),
|
|
218
|
+
turn: Number(r.turn ?? 0),
|
|
219
|
+
lastSeq: Number(r.lastSeq ?? 0),
|
|
220
|
+
pod: r.pod ?? "",
|
|
221
|
+
group: r.group ?? "",
|
|
222
|
+
...(r.parent ? { parent: r.parent } : {}),
|
|
223
|
+
...(r.parentAgent ? { parentAgent: r.parentAgent } : {}),
|
|
224
|
+
onBehalfOf: { userId: root?.userId ?? "", displayName: root?.displayName ?? "" },
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
/** The canonical key of a start's `topicKey`, encoded as the topic's key message. */
|
|
228
|
+
function runTopicKey(topic, key) {
|
|
229
|
+
if (typeof topic !== "object" || topic === null) {
|
|
230
|
+
throw new TypeError("agents.run: topicKey needs `topic` as a topic definition (topic(name, key))");
|
|
231
|
+
}
|
|
232
|
+
return canonicalKey(encodeMessage(topic.keyMessage, key));
|
|
233
|
+
}
|
|
234
|
+
/** Whole seconds of `'90s'`, `'15m'`, `'2h'`; 0 (unset) for anything else. */
|
|
235
|
+
function runSeconds(timeout) {
|
|
236
|
+
const m = typeof timeout === "string" ? /^(\d+)(s|m|h)$/.exec(timeout) : null;
|
|
237
|
+
return m ? Number(m[1]) * (m[2] === "s" ? 1 : m[2] === "m" ? 60 : 3600) : 0;
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* @internal A topic key as the platform and the clients match it: the key message's fields by their snake_case names, sorted,
|
|
241
|
+
* values as strings (`{"id":"1048"}`); a key with no scalar fields is "" (every key). Takes the key in the protobuf
|
|
242
|
+
* JSON mapping (camelCase); nested, array and null values are left out.
|
|
243
|
+
*/
|
|
244
|
+
export function canonicalKey(json) {
|
|
245
|
+
const fields = [];
|
|
246
|
+
for (const [k, v] of Object.entries(json)) {
|
|
247
|
+
if (typeof v === "string" || typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") {
|
|
248
|
+
fields.push([snake(k), String(v)]);
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
if (fields.length === 0)
|
|
252
|
+
return "";
|
|
253
|
+
fields.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
|
|
254
|
+
return JSON.stringify(Object.fromEntries(fields));
|
|
255
|
+
}
|
|
256
|
+
/** @internal `ctx.job` outside a run. */
|
|
257
|
+
export const NO_RUN = Object.freeze({
|
|
258
|
+
job: "",
|
|
259
|
+
runId: "",
|
|
260
|
+
attempt: 0,
|
|
261
|
+
maxAttempts: 0,
|
|
262
|
+
scheduledAt: new Date(0),
|
|
263
|
+
isRun: false,
|
|
264
|
+
isLastAttempt: false,
|
|
265
|
+
});
|
|
266
|
+
/** The most a job's payload may weigh, as JSON. */
|
|
267
|
+
const MAX_PAYLOAD = 64 << 10;
|
|
268
|
+
const RUN_STATES = {
|
|
269
|
+
RUN_STATE_PENDING: "pending",
|
|
270
|
+
RUN_STATE_RUNNING: "running",
|
|
271
|
+
RUN_STATE_DONE: "done",
|
|
272
|
+
RUN_STATE_FAILED: "failed",
|
|
273
|
+
RUN_STATE_CANCELLED: "cancelled",
|
|
274
|
+
};
|
|
275
|
+
/** The context of one request, or of one attempt of a job's run. */
|
|
276
|
+
export class Ctx {
|
|
277
|
+
session;
|
|
278
|
+
caller;
|
|
279
|
+
request;
|
|
280
|
+
plugin;
|
|
281
|
+
tx;
|
|
282
|
+
system;
|
|
283
|
+
job;
|
|
284
|
+
log;
|
|
285
|
+
members;
|
|
286
|
+
groups;
|
|
287
|
+
/** The runs of this plugin's agents: start one, read it and its events, write to it, stop it. */
|
|
288
|
+
agents;
|
|
289
|
+
/** Not available: both reject with `unavailable`. */
|
|
290
|
+
events = {
|
|
291
|
+
emit: (_message) => notAvailable("ctx.events"),
|
|
292
|
+
emitMany: (_messages) => notAvailable("ctx.events"),
|
|
293
|
+
};
|
|
294
|
+
constructor(session, caller, request, plugin, log,
|
|
295
|
+
/** @internal the declared transaction this context's repository calls are part of ("0": none) */
|
|
296
|
+
tx = "0",
|
|
297
|
+
/** @internal the reason of a system context ("": the caller's) */
|
|
298
|
+
system = "",
|
|
299
|
+
/** The run a job's handler is in; outside a run its `runId` is empty and `attempt` 0. */
|
|
300
|
+
job = NO_RUN) {
|
|
301
|
+
this.session = session;
|
|
302
|
+
this.caller = caller;
|
|
303
|
+
this.request = request;
|
|
304
|
+
this.plugin = plugin;
|
|
305
|
+
this.tx = tx;
|
|
306
|
+
this.system = system;
|
|
307
|
+
this.job = job;
|
|
308
|
+
this.log = log;
|
|
309
|
+
this.members = {
|
|
310
|
+
list: async () => {
|
|
311
|
+
const out = [];
|
|
312
|
+
let pageToken = "";
|
|
313
|
+
for (;;) {
|
|
314
|
+
const r = await this.syscall({ membersList: { pageToken, limit: PAGE } });
|
|
315
|
+
out.push(...(r.membersPage?.members ?? []).map(memberOf));
|
|
316
|
+
pageToken = r.membersPage?.nextPageToken ?? "";
|
|
317
|
+
if (!pageToken)
|
|
318
|
+
return out;
|
|
319
|
+
}
|
|
320
|
+
},
|
|
321
|
+
get: async (userId) => {
|
|
322
|
+
try {
|
|
323
|
+
const r = await this.session.syscall({ memberGet: { userId } });
|
|
324
|
+
return r.member ? memberOf(r.member) : undefined;
|
|
325
|
+
}
|
|
326
|
+
catch (e) {
|
|
327
|
+
if (e instanceof SyscallError && e.message === "not found")
|
|
328
|
+
return undefined;
|
|
329
|
+
throw syscallFailed(e);
|
|
330
|
+
}
|
|
331
|
+
},
|
|
332
|
+
};
|
|
333
|
+
this.groups = {
|
|
334
|
+
list: async () => {
|
|
335
|
+
const out = [];
|
|
336
|
+
let pageToken = "";
|
|
337
|
+
for (;;) {
|
|
338
|
+
const r = await this.syscall({ groupsList: { pageToken, limit: PAGE } });
|
|
339
|
+
out.push(...(r.groupsPage?.groups ?? []).map((g) => ({ id: g.id, name: g.name, members: g.members ?? [] })));
|
|
340
|
+
pageToken = r.groupsPage?.nextPageToken ?? "";
|
|
341
|
+
if (!pageToken)
|
|
342
|
+
return out;
|
|
343
|
+
}
|
|
344
|
+
},
|
|
345
|
+
};
|
|
346
|
+
this.agents = {
|
|
347
|
+
run: async (agent, input, options = {}) => {
|
|
348
|
+
const start = {
|
|
349
|
+
agent,
|
|
350
|
+
input,
|
|
351
|
+
engine: options.engine ?? "",
|
|
352
|
+
model: options.model ?? "",
|
|
353
|
+
// left out unless said: the agent's declaration decides
|
|
354
|
+
...(options.session === undefined ? {} : { session: options.session }),
|
|
355
|
+
timeoutS: runSeconds(options.timeout),
|
|
356
|
+
requestId: this.request.id,
|
|
357
|
+
// left out unless said: the run founds a new group
|
|
358
|
+
...(options.group === undefined ? {} : { group: options.group }),
|
|
359
|
+
notify: options.notify ?? false,
|
|
360
|
+
...(options.notifyLink ? { notifyLink: linkWire(options.notifyLink) } : {}),
|
|
361
|
+
...(options.topic === undefined ? {} : { topic: typeof options.topic === "string" ? options.topic : options.topic.name }),
|
|
362
|
+
...(options.topicKey === undefined ? {} : { topicKey: runTopicKey(options.topic, options.topicKey) }),
|
|
363
|
+
};
|
|
364
|
+
return runOf((await this.syscall({ agentRun: start })).agentRun, "agent_run");
|
|
365
|
+
},
|
|
366
|
+
available: async () => {
|
|
367
|
+
const r = await this.syscall({ agentsAvailable: { requestId: this.request.id } });
|
|
368
|
+
return (r.agentsAvailable?.agents ?? []).map((a) => ({
|
|
369
|
+
agent: a.agent,
|
|
370
|
+
plugin: a.plugin,
|
|
371
|
+
name: a.name,
|
|
372
|
+
title: a.title,
|
|
373
|
+
description: a.description ?? "",
|
|
374
|
+
...(a.icon ? { icon: a.icon } : {}),
|
|
375
|
+
...(a.engine ? { engine: a.engine } : {}),
|
|
376
|
+
session: !!a.session,
|
|
377
|
+
pluginTitle: a.pluginTitle,
|
|
378
|
+
}));
|
|
379
|
+
},
|
|
380
|
+
get: async (runId) => runOf((await this.syscall({ agentGet: { runId } })).agentRun, "agent_get"),
|
|
381
|
+
events: async (runId, options = {}) => {
|
|
382
|
+
const page = (await this.syscall({ agentEvents: { runId, after: String(options.after ?? 0), limit: options.limit ?? 0 } }))
|
|
383
|
+
.agentEvents;
|
|
384
|
+
const messages = (page?.partial?.messages ?? []).map((m) => ({ messageId: m.messageId, text: m.text }));
|
|
385
|
+
return {
|
|
386
|
+
run: runOf(page?.run, "agent_events"),
|
|
387
|
+
events: (page?.events ?? []).map((e) => {
|
|
388
|
+
let fields = {};
|
|
389
|
+
try {
|
|
390
|
+
fields = JSON.parse(Buffer.from(e.json ?? []).toString("utf8") || "{}");
|
|
391
|
+
}
|
|
392
|
+
catch {
|
|
393
|
+
// an event the platform could not write as JSON keeps its envelope
|
|
394
|
+
}
|
|
395
|
+
return { ...fields, seq: Number(e.seq), at: Number(e.at), type: e.type };
|
|
396
|
+
}),
|
|
397
|
+
partial: { rev: Number(page?.partial?.rev ?? 0), messages, text: messages.map((m) => m.text).join("\n\n") },
|
|
398
|
+
};
|
|
399
|
+
},
|
|
400
|
+
list: async (options = {}) => {
|
|
401
|
+
const r = await this.syscall({ agentRuns: { agent: options.agent ?? "", limit: options.limit ?? 0, group: options.group ?? "" } });
|
|
402
|
+
return (r.agentRuns?.runs ?? []).map((run) => runOf(run, "agent_runs"));
|
|
403
|
+
},
|
|
404
|
+
send: async (runId, text) => {
|
|
405
|
+
const r = await this.syscall({ agentSend: { runId, text, requestId: this.request.id } });
|
|
406
|
+
return Number(r.agentInput?.seq ?? 0);
|
|
407
|
+
},
|
|
408
|
+
cancel: async (runId) => runOf((await this.syscall({ agentCancel: { runId } })).agentRun, "agent_cancel"),
|
|
409
|
+
close: async (runId) => runOf((await this.syscall({ agentClose: { runId } })).agentRun, "agent_close"),
|
|
410
|
+
};
|
|
411
|
+
}
|
|
412
|
+
async syscall(call) {
|
|
413
|
+
try {
|
|
414
|
+
return await this.session.syscall(call);
|
|
415
|
+
}
|
|
416
|
+
catch (e) {
|
|
417
|
+
throw syscallFailed(e);
|
|
418
|
+
}
|
|
419
|
+
}
|
|
420
|
+
/**
|
|
421
|
+
* The plugin's background jobs: `enqueue` a run, `cancel` one. In a declared transaction (`tx.jobs`) an enqueue is
|
|
422
|
+
* part of it.
|
|
423
|
+
*/
|
|
424
|
+
get jobs() {
|
|
425
|
+
return {
|
|
426
|
+
enqueue: async (job, payload, options = {}) => {
|
|
427
|
+
const found = this.session.jobs?.get(job);
|
|
428
|
+
if (!found)
|
|
429
|
+
throw invalid("ctx.jobs.enqueue: the job is not in plugin({ jobs })");
|
|
430
|
+
let json;
|
|
431
|
+
try {
|
|
432
|
+
json = stringify(encodeMessage(found.payload, payload));
|
|
433
|
+
}
|
|
434
|
+
catch (e) {
|
|
435
|
+
throw invalid(`the payload is not a ${found.payload.name}: ${e.message}`);
|
|
436
|
+
}
|
|
437
|
+
const size = Buffer.byteLength(json, "utf8");
|
|
438
|
+
if (size > MAX_PAYLOAD) {
|
|
439
|
+
throw new RpcError(413, "payload_too_large", `the payload of ${found.name} is ${size} bytes, over 64 KiB: put larger input in an entity and pass its id`);
|
|
440
|
+
}
|
|
441
|
+
const when = {};
|
|
442
|
+
if (options.at !== undefined) {
|
|
443
|
+
const ms = options.at instanceof Date ? options.at.getTime() : options.at;
|
|
444
|
+
if (!Number.isFinite(ms))
|
|
445
|
+
throw invalid("ctx.jobs.enqueue: `at` is not a time");
|
|
446
|
+
when.atUnixMs = String(Math.trunc(ms));
|
|
447
|
+
}
|
|
448
|
+
else if (options.delay !== undefined) {
|
|
449
|
+
const ms = durationMs(options.delay);
|
|
450
|
+
if (ms === undefined || ms < 0)
|
|
451
|
+
throw invalid(`ctx.jobs.enqueue: ${JSON.stringify(options.delay)} is not a delay`);
|
|
452
|
+
when.delayMs = String(Math.trunc(ms));
|
|
453
|
+
}
|
|
454
|
+
const r = await this.syscall({
|
|
455
|
+
jobEnqueue: {
|
|
456
|
+
job: found.name,
|
|
457
|
+
payload: json,
|
|
458
|
+
...when,
|
|
459
|
+
singleton: options.singleton ?? "",
|
|
460
|
+
requestId: this.request.id,
|
|
461
|
+
tx: this.tx,
|
|
462
|
+
},
|
|
463
|
+
});
|
|
464
|
+
const e = r.jobEnqueued;
|
|
465
|
+
if (!e)
|
|
466
|
+
throw internal(new Error("the platform answered an enqueue with something else"));
|
|
467
|
+
return { runId: e.runId, existing: !!e.existing, state: RUN_STATES[e.state] ?? "unknown" };
|
|
468
|
+
},
|
|
469
|
+
cancel: async (run) => {
|
|
470
|
+
const runId = typeof run === "string" ? run : run.runId;
|
|
471
|
+
const r = await this.syscall({ jobCancel: { runId, requestId: this.request.id } });
|
|
472
|
+
if (!r.jobCancelled)
|
|
473
|
+
throw internal(new Error("the platform answered a cancel with something else"));
|
|
474
|
+
return !!r.jobCancelled.cancelled;
|
|
475
|
+
},
|
|
476
|
+
};
|
|
477
|
+
}
|
|
478
|
+
/** Aborted at the deadline or when the session ends (the same as `ctx.request.signal`); in a job's run, when it must stop. */
|
|
479
|
+
get signal() {
|
|
480
|
+
return this.request.signal;
|
|
481
|
+
}
|
|
482
|
+
/**
|
|
483
|
+
* Calls an endpoint of a dependency as this request's caller, with raw JSON (protobuf JSON mapping): `input`
|
|
484
|
+
* is sent as is (a bigint as a string), the answer is the parsed body. A non-2xx answer throws an `RpcError`
|
|
485
|
+
* with the dependency's status, code and message. The typed clients `celobus plugin add` writes (`src/deps/`) call it.
|
|
486
|
+
*/
|
|
487
|
+
async call(plugin, endpoint, input = {}) {
|
|
488
|
+
const request = {
|
|
489
|
+
method: "POST",
|
|
490
|
+
path: endpointPath(plugin, endpoint),
|
|
491
|
+
query: "",
|
|
492
|
+
headers: [{ name: "content-type", value: "application/json" }],
|
|
493
|
+
body: Buffer.from(stringify(input)),
|
|
494
|
+
};
|
|
495
|
+
const r = await this.syscall({ invoke: { plugin, request, requestId: this.request.id } });
|
|
496
|
+
const resp = r.invokeResponse;
|
|
497
|
+
if (!resp)
|
|
498
|
+
throw unavailable(`${plugin}: no response`);
|
|
499
|
+
const text = Buffer.from(resp.body ?? []).toString("utf8");
|
|
500
|
+
let body = undefined;
|
|
501
|
+
try {
|
|
502
|
+
body = text ? JSON.parse(text) : {};
|
|
503
|
+
}
|
|
504
|
+
catch {
|
|
505
|
+
body = undefined;
|
|
506
|
+
}
|
|
507
|
+
if (resp.status < 200 || resp.status >= 300) {
|
|
508
|
+
const err = (body ?? {});
|
|
509
|
+
throw new RpcError(resp.status, typeof err.code === "string" ? err.code : "dependency_error", typeof err.message === "string" ? err.message : `${plugin}.${endpoint} answered ${resp.status}`, err.details && typeof err.details === "object" ? err.details : {});
|
|
510
|
+
}
|
|
511
|
+
if (body === undefined)
|
|
512
|
+
throw unavailable(`${plugin}.${endpoint} answered a body that is not JSON`);
|
|
513
|
+
return body;
|
|
514
|
+
}
|
|
515
|
+
/**
|
|
516
|
+
* Tells the screens following `topic` for `key` to re-read (plugin UI). An endpoint that declares
|
|
517
|
+
* `.invalidates(..)` needs no call: the platform emits those after its 2xx answer. This is for the rest: a change made
|
|
518
|
+
* outside a declared endpoint, or a key the endpoint's response does not carry. Nothing is awaited, and a screen
|
|
519
|
+
* that misses it re-reads within its maximum data age.
|
|
520
|
+
*/
|
|
521
|
+
invalidate(topic, key) {
|
|
522
|
+
this.session.invalidate(topic.name, canonicalKey(encodeMessage(topic.keyMessage, key)));
|
|
523
|
+
}
|
|
524
|
+
/** Every key of `topic` re-reads. */
|
|
525
|
+
invalidateAll(topic) {
|
|
526
|
+
this.session.invalidate(topic.name, "");
|
|
527
|
+
}
|
|
528
|
+
/** @internal */
|
|
529
|
+
link() {
|
|
530
|
+
return {
|
|
531
|
+
syscall: (call) => this.syscall(call),
|
|
532
|
+
requestId: this.request.id,
|
|
533
|
+
tx: this.tx,
|
|
534
|
+
asSystem: this.system,
|
|
535
|
+
};
|
|
536
|
+
}
|
|
537
|
+
/**
|
|
538
|
+
* The plugin's notifications: `send` a notice of a declared kind, `ask` an approval or a
|
|
539
|
+
* decision and `resolve` it, `follow` / `unfollow` a key, `following(key)`. In a transaction
|
|
540
|
+
* (`tx.notifications`) the writes are part of it and its members hear of them when it commits: send last in it.
|
|
541
|
+
*/
|
|
542
|
+
get notifications() {
|
|
543
|
+
return new Notifications({ syscall: (call) => this.syscall(call), requestId: this.request.id, tx: this.tx });
|
|
544
|
+
}
|
|
545
|
+
/**
|
|
546
|
+
* The repository of one of the plugin's entities; in a transaction (`tx.db(order)`) its calls are part of it. A
|
|
547
|
+
* dependency's entity is read with `ctx.query` (500 `internal` here).
|
|
548
|
+
*/
|
|
549
|
+
db(entity) {
|
|
550
|
+
const provider = foreignPlugin(entity);
|
|
551
|
+
if (provider) {
|
|
552
|
+
throw internal(new Error(`ctx.db(): ${provider}.${entity.options.name} is another plugin's entity; read it with ctx.query()`));
|
|
553
|
+
}
|
|
554
|
+
const name = entityNames.get(entity) ?? entity.options.name;
|
|
555
|
+
if (!name)
|
|
556
|
+
throw internal(new Error("ctx.db(): the entity is not in plugin({ entities })"));
|
|
557
|
+
return new Repository(this.link(), entity, name);
|
|
558
|
+
}
|
|
559
|
+
/**
|
|
560
|
+
* A typed read across entities, from the root `entity`: one of the plugin's, a dependency's exported one
|
|
561
|
+
* (`ctx.query(customers.customer)`, generated by `celobus plugin add`; it keeps the repository's reads too: `get`,
|
|
562
|
+
* `find`, `count`, `exists`, `all`, `aggregate`), or the directory's (`platform.user` from `@celobus/sdk/platform`).
|
|
563
|
+
* Joins, `where`, `groupBy`, `having`, `select`, `orderBy`, `limit`; then `all`, `first`, `count`, `page`. In a
|
|
564
|
+
* transaction it is part of it; in a system context it reads the plugin's own entities within its `authz:bypass`,
|
|
565
|
+
* the directory as a member does, and a dependency's entity under the provider's rules for the caller (never more
|
|
566
|
+
* than the caller reads without the system context).
|
|
567
|
+
*/
|
|
568
|
+
query(entity) {
|
|
569
|
+
return startQuery(this.link(), entity);
|
|
570
|
+
}
|
|
571
|
+
/**
|
|
572
|
+
* SQL that reads (`select`, `with`, `values`), with positional parameters: `$1` is the first value after the query
|
|
573
|
+
* (`ctx.sql('select owner_id, count(*) as notes from hello_note group by 1 having count(*) >= $1', 2)`). It reads the
|
|
574
|
+
* entities of every installed plugin (`<plugin>_<entity>`: `chat_post`) and of the directory
|
|
575
|
+
* (`platform_user`, `platform_group`, `platform_group_member`, `platform_role_assignment`) as the caller: each
|
|
576
|
+
* entity's own rules and masks apply; never a catalog (`pg_class`, `information_schema`, `pg_stat_activity`) or
|
|
577
|
+
* another workspace: a relation outside these, or a function in `from` other than a few
|
|
578
|
+
* set-returning built-ins (`generate_series`, `unnest`, the JSON element and record functions, `regexp_matches`,
|
|
579
|
+
* `regexp_split_to_table`, `string_to_table`), is 403 `permission_denied`. The rows are JSON objects keyed by column name as SQL names them (snake_case;
|
|
580
|
+
* a bigint is a JSON number); `R` only types them (an interface of the columns), nothing is checked. In a transaction (`tx.sql(..)`) it runs inside
|
|
581
|
+
* it and sees its writes. More than 1,000 rows is 422 `query_rows_limit`; the platform's refusals are those of
|
|
582
|
+
* `ctx.db`. An encrypted field reads as its ciphertext: read it with `ctx.db`.
|
|
583
|
+
*
|
|
584
|
+
* The values follow the query as arguments, as `$1`, `$2`, … follow in the text: a string, number, bigint,
|
|
585
|
+
* boolean, `null`, `Date`, or anything JSON (an object or array is its JSON text). Each is only ever a value,
|
|
586
|
+
* never SQL.
|
|
587
|
+
*/
|
|
588
|
+
sql(query, ...params) {
|
|
589
|
+
return this.runSql(query, params, false);
|
|
590
|
+
}
|
|
591
|
+
/**
|
|
592
|
+
* SQL over the tables of every plugin of the workspace (`chat_post`, `crm_customer`) past their access rules, with
|
|
593
|
+
* the capability `sql:unsafe`: a read, or with the capability `sql:write` also an `insert`, `update` or `delete`
|
|
594
|
+
* (its `returning` rows come back; none without). Never the platform's tables, the directory's (read it with
|
|
595
|
+
* `ctx.sql`) or a catalog (403). It runs in a system context of its own, never in a declared transaction, and each
|
|
596
|
+
* run is recorded in the workspace's audit; the tables keep their soft-deleted rows, and an encrypted field is its
|
|
597
|
+
* ciphertext. Parameters and rows as `ctx.sql`.
|
|
598
|
+
*/
|
|
599
|
+
unsafeSql(query, ...params) {
|
|
600
|
+
return this.runSql(query, params, true);
|
|
601
|
+
}
|
|
602
|
+
async runSql(query, params, unsafe) {
|
|
603
|
+
if (typeof query !== "string" || query.trim() === "")
|
|
604
|
+
throw internal(new Error("ctx.sql(): the query is empty"));
|
|
605
|
+
const r = await this.syscall({
|
|
606
|
+
sql: { requestId: this.request.id, tx: this.tx, query, params: sqlParams(params), unsafe },
|
|
607
|
+
});
|
|
608
|
+
if (!r.dbRows)
|
|
609
|
+
throw internal(new Error("the platform answered SQL with something else"));
|
|
610
|
+
return sqlRows(r.dbRows.rows ?? []);
|
|
611
|
+
}
|
|
612
|
+
/**
|
|
613
|
+
* The same context with the system's rights on the plugin's own entities: its repository calls (and the
|
|
614
|
+
* transactions it begins) bypass the access rules within the scope the plugin declares for `authz:bypass`
|
|
615
|
+
* (outside it, 403 `capability_missing`), read masked columns, and are recorded in the workspace's audit with the
|
|
616
|
+
* caller, the request and `reason`.
|
|
617
|
+
*/
|
|
618
|
+
asSystem(reason) {
|
|
619
|
+
const Kind = this.constructor;
|
|
620
|
+
return new Kind(this.session, this.caller, this.request, this.plugin, this.log, this.tx, reason, this.job);
|
|
621
|
+
}
|
|
622
|
+
/**
|
|
623
|
+
* A declared transaction: `fn` gets `tx`, a context whose repository calls are part of it; it commits when `fn`
|
|
624
|
+
* resolves and rolls back when it throws. Inside a transaction it is nested and rolls back alone. The platform rolls back a
|
|
625
|
+
* transaction still open when the request ends or 5 s pass (504 `transaction_timeout`).
|
|
626
|
+
*/
|
|
627
|
+
async transaction(fn, options = {}) {
|
|
628
|
+
const isolation = { read_committed: "READ_COMMITTED", repeatable_read: "REPEATABLE_READ", serializable: "SERIALIZABLE" }[options.isolation ?? "read_committed"];
|
|
629
|
+
const begun = await this.syscall({
|
|
630
|
+
txBegin: { requestId: this.request.id, tx: this.tx, isolation, readOnly: !!options.readOnly, asSystem: this.system },
|
|
631
|
+
});
|
|
632
|
+
const id = begun.txBegun?.tx;
|
|
633
|
+
if (!id)
|
|
634
|
+
throw internal(new Error("the platform answered a begin with something else"));
|
|
635
|
+
const tx = new TxCtx(this.session, this.caller, this.request, this.plugin, this.log, id, this.system, this.job);
|
|
636
|
+
let value;
|
|
637
|
+
try {
|
|
638
|
+
value = await fn(tx);
|
|
639
|
+
}
|
|
640
|
+
catch (e) {
|
|
641
|
+
await this.syscall({ txRollback: { requestId: this.request.id, tx: id } }).catch(() => { });
|
|
642
|
+
throw e;
|
|
643
|
+
}
|
|
644
|
+
await this.syscall({ txCommit: { requestId: this.request.id, tx: id } });
|
|
645
|
+
return value;
|
|
646
|
+
}
|
|
647
|
+
}
|
|
648
|
+
/**
|
|
649
|
+
* The context inside a declared transaction (`ctx.transaction(async (tx) => ..)`): a `Ctx` whose repositories may
|
|
650
|
+
* lock the rows they read (`tx.db(e).get(id, { lock: 'update' })`, `tx.db(e).find(f).forUpdate().skipLocked()`).
|
|
651
|
+
*/
|
|
652
|
+
export class TxCtx extends Ctx {
|
|
653
|
+
db(entity) {
|
|
654
|
+
const repo = super.db(entity);
|
|
655
|
+
return new TxRepository(this.link(), repo.entity, repo.name);
|
|
656
|
+
}
|
|
657
|
+
}
|