@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.d.ts
ADDED
|
@@ -0,0 +1,644 @@
|
|
|
1
|
+
import { Repository, TxRepository, type DbLink, type DbResult } from "./db.js";
|
|
2
|
+
import { type AgentEngine, type AgentTimeout, type Duration, type JobDef, type JobPayload, type JobPayloadType } from "./declare.js";
|
|
3
|
+
import type { ResolvedJob } from "./descriptor.js";
|
|
4
|
+
import type { Logger } from "./log.js";
|
|
5
|
+
import { Notifications, type NotifyLink } from "./notify.js";
|
|
6
|
+
import { type EntityDef } from "./schema.js";
|
|
7
|
+
import { type Query, type Queryable } from "./query.js";
|
|
8
|
+
import { type SqlRow } from "./sql.js";
|
|
9
|
+
import type { TopicDef } from "./ui.js";
|
|
10
|
+
/** @internal What the platform answers a syscall (`SyscallResult`, protobuf field names in camelCase). */
|
|
11
|
+
export interface SyscallResult extends DbResult {
|
|
12
|
+
id: string;
|
|
13
|
+
error: string;
|
|
14
|
+
errorDetails?: {
|
|
15
|
+
currentVersion: string | number;
|
|
16
|
+
column: string;
|
|
17
|
+
} | null;
|
|
18
|
+
result?: string;
|
|
19
|
+
invokeResponse?: {
|
|
20
|
+
status: number;
|
|
21
|
+
headers: {
|
|
22
|
+
name: string;
|
|
23
|
+
value: string;
|
|
24
|
+
}[];
|
|
25
|
+
body: Buffer;
|
|
26
|
+
} | null;
|
|
27
|
+
membersPage?: {
|
|
28
|
+
members: WireMember[];
|
|
29
|
+
nextPageToken: string;
|
|
30
|
+
} | null;
|
|
31
|
+
member?: WireMember | null;
|
|
32
|
+
groupsPage?: {
|
|
33
|
+
groups: Group[];
|
|
34
|
+
nextPageToken: string;
|
|
35
|
+
} | null;
|
|
36
|
+
agentRun?: WireRun | null;
|
|
37
|
+
agentEvents?: {
|
|
38
|
+
run?: WireRun | null;
|
|
39
|
+
events?: {
|
|
40
|
+
seq: string | number;
|
|
41
|
+
at: string | number;
|
|
42
|
+
type: string;
|
|
43
|
+
json: Buffer;
|
|
44
|
+
}[];
|
|
45
|
+
partial?: {
|
|
46
|
+
rev: string | number;
|
|
47
|
+
messages?: {
|
|
48
|
+
messageId: string;
|
|
49
|
+
text: string;
|
|
50
|
+
}[];
|
|
51
|
+
} | null;
|
|
52
|
+
} | null;
|
|
53
|
+
agentRuns?: {
|
|
54
|
+
runs?: WireRun[];
|
|
55
|
+
} | null;
|
|
56
|
+
agentInput?: {
|
|
57
|
+
seq: string | number;
|
|
58
|
+
} | null;
|
|
59
|
+
agentsAvailable?: {
|
|
60
|
+
agents?: WireAvailableAgent[];
|
|
61
|
+
} | null;
|
|
62
|
+
notifyFollowState?: {
|
|
63
|
+
following: boolean;
|
|
64
|
+
} | null;
|
|
65
|
+
jobEnqueued?: {
|
|
66
|
+
runId: string;
|
|
67
|
+
existing: boolean;
|
|
68
|
+
state: string;
|
|
69
|
+
} | null;
|
|
70
|
+
jobCancelled?: {
|
|
71
|
+
cancelled: boolean;
|
|
72
|
+
} | null;
|
|
73
|
+
}
|
|
74
|
+
/** `AvailableAgent` as the platform sends it. */
|
|
75
|
+
interface WireAvailableAgent {
|
|
76
|
+
agent: string;
|
|
77
|
+
plugin: string;
|
|
78
|
+
name: string;
|
|
79
|
+
title: string;
|
|
80
|
+
description: string;
|
|
81
|
+
icon: string;
|
|
82
|
+
engine: string;
|
|
83
|
+
session: boolean;
|
|
84
|
+
pluginTitle: string;
|
|
85
|
+
}
|
|
86
|
+
/** `AgentRun` as the platform sends it (64-bit numbers as strings). */
|
|
87
|
+
interface WireRun {
|
|
88
|
+
id: string;
|
|
89
|
+
agent: string;
|
|
90
|
+
plugin: string;
|
|
91
|
+
engine: string;
|
|
92
|
+
model: string;
|
|
93
|
+
status: string;
|
|
94
|
+
session: boolean;
|
|
95
|
+
input: string;
|
|
96
|
+
result: string;
|
|
97
|
+
error?: {
|
|
98
|
+
code: string;
|
|
99
|
+
message: string;
|
|
100
|
+
} | null;
|
|
101
|
+
startedBy?: {
|
|
102
|
+
userId: string;
|
|
103
|
+
displayName: string;
|
|
104
|
+
} | null;
|
|
105
|
+
startedByPlugin: string;
|
|
106
|
+
createdAt: string | number;
|
|
107
|
+
updatedAt: string | number;
|
|
108
|
+
deadlineAt: string | number;
|
|
109
|
+
turn: number;
|
|
110
|
+
lastSeq: string | number;
|
|
111
|
+
pod: string;
|
|
112
|
+
group: string;
|
|
113
|
+
parent: string;
|
|
114
|
+
parentAgent: string;
|
|
115
|
+
onBehalfOf?: {
|
|
116
|
+
userId: string;
|
|
117
|
+
displayName: string;
|
|
118
|
+
} | null;
|
|
119
|
+
}
|
|
120
|
+
/** @internal A syscall that the platform answered with an error string (and the details some db refusals have). */
|
|
121
|
+
export declare class SyscallError extends Error {
|
|
122
|
+
readonly details?: {
|
|
123
|
+
currentVersion: string | number;
|
|
124
|
+
column: string;
|
|
125
|
+
} | null | undefined;
|
|
126
|
+
constructor(message: string, details?: {
|
|
127
|
+
currentVersion: string | number;
|
|
128
|
+
column: string;
|
|
129
|
+
} | null | undefined);
|
|
130
|
+
}
|
|
131
|
+
/** @internal The session as a context uses it. */
|
|
132
|
+
export interface SyscallSession {
|
|
133
|
+
/** Sends a `Syscall` (without its id) and resolves with the result; rejects with `SyscallError` or when the session ends. */
|
|
134
|
+
syscall(call: Record<string, unknown>): Promise<SyscallResult>;
|
|
135
|
+
/** Sends an `Invalidate` when the session is up; nothing is awaited. */
|
|
136
|
+
invalidate(topic: string, key: string): void;
|
|
137
|
+
/** The plugin's jobs by their declarations (what `ctx.jobs.enqueue` takes); absent: none. */
|
|
138
|
+
jobs?: ReadonlyMap<JobDef<any>, ResolvedJob>;
|
|
139
|
+
}
|
|
140
|
+
/** @internal `Principal` as the platform sends it. */
|
|
141
|
+
export interface WirePrincipal {
|
|
142
|
+
userId: string;
|
|
143
|
+
kind: string;
|
|
144
|
+
displayName: string;
|
|
145
|
+
roles: string[];
|
|
146
|
+
groups: string[];
|
|
147
|
+
scopes: string[];
|
|
148
|
+
}
|
|
149
|
+
interface WireMember {
|
|
150
|
+
userId: string;
|
|
151
|
+
kind: string;
|
|
152
|
+
displayName: string;
|
|
153
|
+
roles: string[];
|
|
154
|
+
groups: string[];
|
|
155
|
+
email: string;
|
|
156
|
+
avatarUrl: string;
|
|
157
|
+
lastActive: string | number;
|
|
158
|
+
locale: string;
|
|
159
|
+
}
|
|
160
|
+
/** A role a check can name: a role object of this plugin, or a full name (`workspace.admin`, `orders.clerk`). */
|
|
161
|
+
export type RoleLike = string | {
|
|
162
|
+
readonly __role: true;
|
|
163
|
+
};
|
|
164
|
+
/** `user`: a person; `service`: a service account; `system`: a call without a caller. */
|
|
165
|
+
export type CallerKind = "user" | "service" | "system";
|
|
166
|
+
/** Who calls the request, resolved by the platform from the workspace's members. */
|
|
167
|
+
export declare class Caller {
|
|
168
|
+
private readonly pluginId;
|
|
169
|
+
private readonly roleName;
|
|
170
|
+
readonly userId: string | undefined;
|
|
171
|
+
readonly kind: CallerKind;
|
|
172
|
+
readonly displayName: string;
|
|
173
|
+
/** Effective roles, full names: `workspace.*` (expanded) and `<plugin>.<role>`. */
|
|
174
|
+
readonly roles: readonly string[];
|
|
175
|
+
/** Group ids. */
|
|
176
|
+
readonly groups: readonly string[];
|
|
177
|
+
/** The token's scopes for this plugin, full names `<plugin>:<scope>`. */
|
|
178
|
+
readonly scopes: readonly string[];
|
|
179
|
+
constructor(principal: WirePrincipal | null | undefined, pluginId: string, roleName?: (role: RoleLike) => string | undefined);
|
|
180
|
+
/** The calling user's id; throws 401 `unauthenticated` when the request has none. */
|
|
181
|
+
user(): string;
|
|
182
|
+
/** Holds the role: a role object of this plugin, its short name (`clerk`) or a full name (`workspace.admin`). */
|
|
183
|
+
has(role: RoleLike): boolean;
|
|
184
|
+
/** The token allows the scope: short (`read`) or full (`orders:read`). */
|
|
185
|
+
hasScope(scope: string): boolean;
|
|
186
|
+
inGroup(groupId: string): boolean;
|
|
187
|
+
}
|
|
188
|
+
/** A workspace member from the directory. */
|
|
189
|
+
export interface Member {
|
|
190
|
+
userId: string;
|
|
191
|
+
kind: "user" | "service";
|
|
192
|
+
displayName: string;
|
|
193
|
+
roles: string[];
|
|
194
|
+
groups: string[];
|
|
195
|
+
/** empty unless the plugin declares the permission `members.email` */
|
|
196
|
+
email: string;
|
|
197
|
+
avatarUrl: string;
|
|
198
|
+
/** unix seconds, hour resolution */
|
|
199
|
+
lastActive: number;
|
|
200
|
+
locale: string;
|
|
201
|
+
}
|
|
202
|
+
export interface Group {
|
|
203
|
+
id: string;
|
|
204
|
+
name: string;
|
|
205
|
+
/** user ids */
|
|
206
|
+
members: string[];
|
|
207
|
+
}
|
|
208
|
+
export interface RequestInfo {
|
|
209
|
+
/** The request id the platform gave it (a decimal string). */
|
|
210
|
+
readonly id: string;
|
|
211
|
+
/** When the endpoint's timeout passes. */
|
|
212
|
+
readonly deadline: Date;
|
|
213
|
+
/** Aborted at the deadline, or when the session to the platform ends: pass it to your own I/O. */
|
|
214
|
+
readonly signal: AbortSignal;
|
|
215
|
+
}
|
|
216
|
+
export interface PluginInfo {
|
|
217
|
+
readonly id: string;
|
|
218
|
+
readonly version: string;
|
|
219
|
+
}
|
|
220
|
+
/** How a declared transaction runs: read committed by default; not for a nested one (it rolls back alone). */
|
|
221
|
+
export interface TransactionOptions {
|
|
222
|
+
isolation?: "read_committed" | "repeatable_read" | "serializable";
|
|
223
|
+
/** Refuses writes. */
|
|
224
|
+
readOnly?: boolean;
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* A syscall error as the handler sees it: an admission refusal is 403 with its code, a refusal of an agent, a
|
|
228
|
+
* notification or a db call its own status and code (with the details a db refusal has), anything else 503 `unavailable`.
|
|
229
|
+
*/
|
|
230
|
+
export declare function syscallFailed(e: unknown): unknown;
|
|
231
|
+
/** Where a run is: `starting` → `running` ⇄ `idle` (a session between turns) → one of the four ends. */
|
|
232
|
+
export type AgentRunStatus = "starting" | "running" | "idle" | "succeeded" | "failed" | "cancelled" | "timed_out";
|
|
233
|
+
/** A run of one of the plugin's agents, or one its code started. Times are unix milliseconds. */
|
|
234
|
+
export interface AgentRun {
|
|
235
|
+
id: string;
|
|
236
|
+
/** The agent's name in its plugin (`plugin`). */
|
|
237
|
+
agent: string;
|
|
238
|
+
plugin: string;
|
|
239
|
+
engine: string;
|
|
240
|
+
/** `undefined`: the engine's own model. */
|
|
241
|
+
model?: string;
|
|
242
|
+
status: AgentRunStatus;
|
|
243
|
+
/** The run is over: nothing more is written to it. */
|
|
244
|
+
ended: boolean;
|
|
245
|
+
/** The run waits for follow-up messages after every turn. */
|
|
246
|
+
session: boolean;
|
|
247
|
+
/** The task it was started with. */
|
|
248
|
+
input: string;
|
|
249
|
+
/** The result of the last finished turn. */
|
|
250
|
+
result?: string;
|
|
251
|
+
/** Why it failed or timed out (`start_timeout`, `lost`, `agent_failed`, …). */
|
|
252
|
+
error?: {
|
|
253
|
+
code: string;
|
|
254
|
+
message: string;
|
|
255
|
+
};
|
|
256
|
+
/** The caller of the request the run was started in (or of the HTTP call that started it). */
|
|
257
|
+
startedBy: {
|
|
258
|
+
userId: string;
|
|
259
|
+
displayName: string;
|
|
260
|
+
};
|
|
261
|
+
/** The plugin whose code started it; `undefined`: started over HTTP (the CLI, a client). */
|
|
262
|
+
startedByPlugin?: string;
|
|
263
|
+
createdAt: number;
|
|
264
|
+
updatedAt: number;
|
|
265
|
+
deadlineAt: number;
|
|
266
|
+
turn: number;
|
|
267
|
+
/** The sequence number of the run's last event. */
|
|
268
|
+
lastSeq: number;
|
|
269
|
+
/** Where the run executes, as the platform last reported it (an opaque name). */
|
|
270
|
+
pod: string;
|
|
271
|
+
/**
|
|
272
|
+
* The group the run belongs to: the id of the group's first run (its own id for a run that founded one). The
|
|
273
|
+
* agents of a group message each other by name.
|
|
274
|
+
*/
|
|
275
|
+
group: string;
|
|
276
|
+
/** The agent run that started this one; `undefined`: a person or a plugin's code did. */
|
|
277
|
+
parent?: string;
|
|
278
|
+
/** The agent of that run, `<plugin>.<name>`; `undefined` with `parent`. */
|
|
279
|
+
parentAgent?: string;
|
|
280
|
+
/** The person at the root: who started the run, or the run that started it. */
|
|
281
|
+
onBehalfOf: {
|
|
282
|
+
userId: string;
|
|
283
|
+
displayName: string;
|
|
284
|
+
};
|
|
285
|
+
}
|
|
286
|
+
/**
|
|
287
|
+
* One event of a run, as the platform keeps it: `type` is `message`, `tool`, `turn`, `status`, `progress` or
|
|
288
|
+
* `error`, and the fields of that type come with it (`text`, `role`, `name`, `phase`, `summary`, …).
|
|
289
|
+
*/
|
|
290
|
+
export interface AgentEvent {
|
|
291
|
+
seq: number;
|
|
292
|
+
/** Unix milliseconds. */
|
|
293
|
+
at: number;
|
|
294
|
+
type: string;
|
|
295
|
+
[field: string]: unknown;
|
|
296
|
+
}
|
|
297
|
+
/** A run with its events after a sequence number and the text being written. */
|
|
298
|
+
export interface AgentEvents {
|
|
299
|
+
run: AgentRun;
|
|
300
|
+
/** Oldest first. */
|
|
301
|
+
events: AgentEvent[];
|
|
302
|
+
/**
|
|
303
|
+
* The messages being written right now: text, not events (the finished message arrives as an event and takes
|
|
304
|
+
* their place). `rev` counts the changes (0: nothing was written yet); `text` is the messages joined by blank lines.
|
|
305
|
+
*/
|
|
306
|
+
partial: {
|
|
307
|
+
rev: number;
|
|
308
|
+
messages: {
|
|
309
|
+
messageId: string;
|
|
310
|
+
text: string;
|
|
311
|
+
}[];
|
|
312
|
+
text: string;
|
|
313
|
+
};
|
|
314
|
+
}
|
|
315
|
+
/** How a run is started, when it differs from what the agent declares. */
|
|
316
|
+
export interface AgentRunOptions {
|
|
317
|
+
engine?: AgentEngine;
|
|
318
|
+
model?: string;
|
|
319
|
+
/** The run is a session (it waits for follow-up messages after every turn), or is not. */
|
|
320
|
+
session?: boolean;
|
|
321
|
+
/** The longest the run takes, from a minute to six hours: `'90s'`, `'15m'`, `'2h'`. */
|
|
322
|
+
timeout?: AgentTimeout;
|
|
323
|
+
/**
|
|
324
|
+
* The group the run joins: the `group` of a run this plugin's code started. Left out: the run founds a new group.
|
|
325
|
+
*/
|
|
326
|
+
group?: string;
|
|
327
|
+
/**
|
|
328
|
+
* Tell the person the run works for, in their inbox, when it finishes (a run that fails or runs out of time always
|
|
329
|
+
* tells them).
|
|
330
|
+
*/
|
|
331
|
+
notify?: boolean;
|
|
332
|
+
/**
|
|
333
|
+
* Where the notification of the run's end opens: `notify.screen(..)` or `notify.overlay(..)` of this plugin's UI
|
|
334
|
+
* (400 `bad_request` when the UI has no such target or params).
|
|
335
|
+
*/
|
|
336
|
+
notifyLink?: NotifyLink;
|
|
337
|
+
/**
|
|
338
|
+
* A topic of this plugin (declared in `plugin({ topics })`) the platform invalidates, for every key, whenever the run
|
|
339
|
+
* changes, as it does the topic the agent declares: how a plugin follows the runs it starts of another plugin's
|
|
340
|
+
* agent. 400 `bad_request` when the plugin declares no such topic.
|
|
341
|
+
*/
|
|
342
|
+
topic?: TopicDef<any> | string;
|
|
343
|
+
/**
|
|
344
|
+
* The key of `topic` to invalidate: only the screens that follow the topic for this key re-read (a conversation's
|
|
345
|
+
* screens, not every screen of the plugin). Needs `topic` as a `TopicDef`; left out: every key.
|
|
346
|
+
*/
|
|
347
|
+
topicKey?: Record<string, unknown>;
|
|
348
|
+
}
|
|
349
|
+
/** An agent of the workspace the caller of the request may start a run of (`ctx.agents.available()`). */
|
|
350
|
+
export interface AvailableAgent {
|
|
351
|
+
/** `<plugin>.<name>`: what `run` takes. */
|
|
352
|
+
agent: string;
|
|
353
|
+
plugin: string;
|
|
354
|
+
name: string;
|
|
355
|
+
/** Its display name: the declared title, else its name. */
|
|
356
|
+
title: string;
|
|
357
|
+
/** What it is for, in a sentence (empty: not said). */
|
|
358
|
+
description: string;
|
|
359
|
+
/** Its glyph, a lucide icon name. */
|
|
360
|
+
icon?: string;
|
|
361
|
+
/** The engine its runs get in this workspace when a start names none: an owner's or admin's choice, else the one it declares, else its connection's; `undefined`: none can be resolved (it has no connection). */
|
|
362
|
+
engine?: string;
|
|
363
|
+
/** Its runs are sessions by its declaration. */
|
|
364
|
+
session: boolean;
|
|
365
|
+
/** Its plugin's title, else the plugin's id. */
|
|
366
|
+
pluginTitle: string;
|
|
367
|
+
}
|
|
368
|
+
/**
|
|
369
|
+
* The runs of the plugin's own agents and of the agents of other plugins its code starts (`ctx.agents`).
|
|
370
|
+
*/
|
|
371
|
+
export interface Agents {
|
|
372
|
+
/**
|
|
373
|
+
* Starts a run of the agent `agent` with the task `input`, as the agent declares its runs unless `options` say
|
|
374
|
+
* otherwise: the plugin's own agent by its name in `plugin({ agents })` (in snake_case), or an agent of another
|
|
375
|
+
* plugin of the workspace as `<plugin>.<name>` (403 `forbidden` when the caller does not reach that plugin or is an
|
|
376
|
+
* agent's account). It is
|
|
377
|
+
* started by this request's caller; outside a request the platform refuses (403 `forbidden`). 404 `unknown_agent` when
|
|
378
|
+
* there is no such agent.
|
|
379
|
+
* With `options.group` the run joins a group this plugin's code founded (the `group` of a run its code started);
|
|
380
|
+
* without it the run founds a new group. 404 `unknown_group` when the platform no longer remembers the group's first
|
|
381
|
+
* run or another plugin founded it, 409 `agent_in_group` when the agent has a live run in the group already, 409
|
|
382
|
+
* `group_full` when the group has its eight live runs.
|
|
383
|
+
*/
|
|
384
|
+
run(agent: string, input: string, options?: AgentRunOptions): Promise<AgentRun>;
|
|
385
|
+
/**
|
|
386
|
+
* The agents of the workspace this request's caller may start a run of: those of the plugins they reach, this
|
|
387
|
+
* plugin's own among them, sorted by plugin and name. 403 `forbidden` outside a request of a signed-in caller and
|
|
388
|
+
* for an agent's account.
|
|
389
|
+
*/
|
|
390
|
+
available(): Promise<AvailableAgent[]>;
|
|
391
|
+
/** The run; 404 `not_found` when it is neither a run of this plugin's agents nor one its code started. */
|
|
392
|
+
get(runId: string): Promise<AgentRun>;
|
|
393
|
+
/**
|
|
394
|
+
* The run, its events after the sequence number `after` (default 0: from the first; oldest first, at most
|
|
395
|
+
* `limit`, default all the run keeps) and the text being written. Answered at once: follow the agent's topic to
|
|
396
|
+
* know when to read again.
|
|
397
|
+
*/
|
|
398
|
+
events(runId: string, options?: {
|
|
399
|
+
after?: number;
|
|
400
|
+
limit?: number;
|
|
401
|
+
}): Promise<AgentEvents>;
|
|
402
|
+
/**
|
|
403
|
+
* The recent runs the plugin sees (of its agents, and the runs its code started), newest first: of one agent (its
|
|
404
|
+
* name, or `<plugin>.<name>` of another plugin's) or of all, of one group (`group`: the `group` of a run) or of all,
|
|
405
|
+
* at most `limit` (default 50).
|
|
406
|
+
*/
|
|
407
|
+
list(options?: {
|
|
408
|
+
agent?: string;
|
|
409
|
+
limit?: number;
|
|
410
|
+
group?: string;
|
|
411
|
+
}): Promise<AgentRun[]>;
|
|
412
|
+
/**
|
|
413
|
+
* Sends a follow-up message to a run that has not ended, as this request's caller; resolves with the sequence
|
|
414
|
+
* number of the input. 409 `run_ended` when the run is over.
|
|
415
|
+
*/
|
|
416
|
+
send(runId: string, text: string): Promise<number>;
|
|
417
|
+
/** Stops the run now; a run that ended stays as it is. */
|
|
418
|
+
cancel(runId: string): Promise<AgentRun>;
|
|
419
|
+
/** Ends a session after the turn in progress. */
|
|
420
|
+
close(runId: string): Promise<AgentRun>;
|
|
421
|
+
}
|
|
422
|
+
/**
|
|
423
|
+
* A change of a run the plugin sees, as the run-change hook tells it (`plugin({..}).onRunChange(handler)`): a run of
|
|
424
|
+
* one of the plugin's agents, or one its code started. It names the run and where it stands; the handler reads the
|
|
425
|
+
* rest with `ctx.agents`. Delivered at least once and coalesced (the latest state of a burst): handle it
|
|
426
|
+
* idempotently, and read the run rather than trust the order of deliveries.
|
|
427
|
+
*/
|
|
428
|
+
export interface RunChange {
|
|
429
|
+
runId: string;
|
|
430
|
+
/** The agent's name in its plugin. */
|
|
431
|
+
agent: string;
|
|
432
|
+
/** The agent's plugin. */
|
|
433
|
+
plugin: string;
|
|
434
|
+
/** `unknown`: a status this SDK does not know. */
|
|
435
|
+
status: AgentRunStatus | "unknown";
|
|
436
|
+
turn: number;
|
|
437
|
+
/** The sequence number of the run's last event. */
|
|
438
|
+
lastSeq: number;
|
|
439
|
+
/** The topic the start named (empty: none), and its canonical key (empty: every key). */
|
|
440
|
+
topic: string;
|
|
441
|
+
topicKey: string;
|
|
442
|
+
/** The run is over: nothing more is written to it. */
|
|
443
|
+
ended: boolean;
|
|
444
|
+
}
|
|
445
|
+
/** The run-change hook's handler: a system request (no caller); an error makes the platform call again. */
|
|
446
|
+
export type RunChangeHandler = (ctx: Ctx, change: RunChange) => void | Promise<void>;
|
|
447
|
+
/** @internal Reads the hook's body (`{run_id, agent, plugin, status, turn, last_seq, topic, topic_key, ended}`). */
|
|
448
|
+
export declare function runChangeOf(body: unknown): RunChange;
|
|
449
|
+
/**
|
|
450
|
+
* @internal A topic key as the platform and the clients match it: the key message's fields by their snake_case names, sorted,
|
|
451
|
+
* values as strings (`{"id":"1048"}`); a key with no scalar fields is "" (every key). Takes the key in the protobuf
|
|
452
|
+
* JSON mapping (camelCase); nested, array and null values are left out.
|
|
453
|
+
*/
|
|
454
|
+
export declare function canonicalKey(json: Record<string, unknown>): string;
|
|
455
|
+
/** The run a job's handler is in (`ctx.job`); outside a run its `runId` is empty and `attempt` 0. */
|
|
456
|
+
export interface JobInfo {
|
|
457
|
+
/** The job's name (`remind_unpaid`). */
|
|
458
|
+
readonly job: string;
|
|
459
|
+
/** The run's id, the same in every attempt: the idempotency key of the handler's outside effects. */
|
|
460
|
+
readonly runId: string;
|
|
461
|
+
/** 1 on the first attempt. */
|
|
462
|
+
readonly attempt: number;
|
|
463
|
+
/** The attempts the run may take; `attempt === maxAttempts` on the last one. */
|
|
464
|
+
readonly maxAttempts: number;
|
|
465
|
+
/** The occurrence (or due time) the run stands for, the same in every attempt. */
|
|
466
|
+
readonly scheduledAt: Date;
|
|
467
|
+
/** Whether this is a job's run. */
|
|
468
|
+
readonly isRun: boolean;
|
|
469
|
+
/** Whether a failure of this attempt ends the run as failed. */
|
|
470
|
+
readonly isLastAttempt: boolean;
|
|
471
|
+
}
|
|
472
|
+
/** @internal `ctx.job` outside a run. */
|
|
473
|
+
export declare const NO_RUN: JobInfo;
|
|
474
|
+
/** The state of a run; `failed`: failed for good (its retries used up, or permanent); `unknown`: one this SDK does not know. */
|
|
475
|
+
export type RunState = "pending" | "running" | "done" | "failed" | "cancelled" | "unknown";
|
|
476
|
+
/**
|
|
477
|
+
* A run started by an enqueue: `runId`, and `existing` when its singleton key was taken by an earlier run (whose id and
|
|
478
|
+
* state these are; its payload is kept).
|
|
479
|
+
*/
|
|
480
|
+
export interface Enqueued {
|
|
481
|
+
runId: string;
|
|
482
|
+
existing: boolean;
|
|
483
|
+
state: RunState;
|
|
484
|
+
}
|
|
485
|
+
export interface EnqueueOptions {
|
|
486
|
+
/** Due after this long (default: now). */
|
|
487
|
+
delay?: Duration;
|
|
488
|
+
/** Due at this time, a `Date` or unix milliseconds (at most a year ahead; a time past is now). */
|
|
489
|
+
at?: Date | number;
|
|
490
|
+
/**
|
|
491
|
+
* At most one run per key and job while that run is kept (7 days after it ends, 30 if it failed): an enqueue with a
|
|
492
|
+
* key taken answers the earlier run (`existing`) and keeps its payload.
|
|
493
|
+
*/
|
|
494
|
+
singleton?: string;
|
|
495
|
+
}
|
|
496
|
+
/** The plugin's background jobs: `ctx.jobs`, `tx.jobs` in a declared transaction. */
|
|
497
|
+
export interface Jobs {
|
|
498
|
+
/**
|
|
499
|
+
* Starts a run of `job` (one of `plugin({ jobs })`) with `payload`, as the caller of the request or run in progress (a
|
|
500
|
+
* job declared `as: 'system'` runs as the system). In a declared transaction (`tx.jobs`) the run is written in it and
|
|
501
|
+
* exists only if it commits; a singleton enqueue there may wait for a concurrent transaction enqueuing the same key.
|
|
502
|
+
* Errors: 400 `invalid` (the job is not the plugin's, the payload does not fit its message, `at` more than a year
|
|
503
|
+
* ahead), 413 `payload_too_large` (over 64 KiB as JSON: put larger input in an entity and pass its id), 429
|
|
504
|
+
* `queue_full` (10,000 pending runs of the plugin).
|
|
505
|
+
*/
|
|
506
|
+
enqueue<P extends JobPayloadType>(job: JobDef<P>, payload: JobPayload<P>, options?: EnqueueOptions): Promise<Enqueued>;
|
|
507
|
+
/**
|
|
508
|
+
* Cancels one of the plugin's runs (its id, or what `enqueue` answered): a pending run never starts, a running one is
|
|
509
|
+
* stopped. `false` when it had already ended; 404 `not_found` when the plugin has no such run.
|
|
510
|
+
*/
|
|
511
|
+
cancel(run: string | Enqueued): Promise<boolean>;
|
|
512
|
+
}
|
|
513
|
+
/** The context of one request, or of one attempt of a job's run. */
|
|
514
|
+
export declare class Ctx {
|
|
515
|
+
private readonly session;
|
|
516
|
+
readonly caller: Caller;
|
|
517
|
+
readonly request: RequestInfo;
|
|
518
|
+
readonly plugin: PluginInfo;
|
|
519
|
+
/** @internal the declared transaction this context's repository calls are part of ("0": none) */
|
|
520
|
+
private readonly tx;
|
|
521
|
+
/** @internal the reason of a system context ("": the caller's) */
|
|
522
|
+
private readonly system;
|
|
523
|
+
/** The run a job's handler is in; outside a run its `runId` is empty and `attempt` 0. */
|
|
524
|
+
readonly job: JobInfo;
|
|
525
|
+
readonly log: Logger;
|
|
526
|
+
readonly members: {
|
|
527
|
+
/** Every member of the workspace. */
|
|
528
|
+
list(): Promise<Member[]>;
|
|
529
|
+
/** The member, or `undefined` when there is none. */
|
|
530
|
+
get(userId: string): Promise<Member | undefined>;
|
|
531
|
+
};
|
|
532
|
+
readonly groups: {
|
|
533
|
+
list(): Promise<Group[]>;
|
|
534
|
+
};
|
|
535
|
+
/** The runs of this plugin's agents: start one, read it and its events, write to it, stop it. */
|
|
536
|
+
readonly agents: Agents;
|
|
537
|
+
/** Not available: both reject with `unavailable`. */
|
|
538
|
+
readonly events: {
|
|
539
|
+
emit: (_message: unknown) => Promise<never>;
|
|
540
|
+
emitMany: (_messages: unknown) => Promise<never>;
|
|
541
|
+
};
|
|
542
|
+
constructor(session: SyscallSession, caller: Caller, request: RequestInfo, plugin: PluginInfo, log: Logger,
|
|
543
|
+
/** @internal the declared transaction this context's repository calls are part of ("0": none) */
|
|
544
|
+
tx?: string,
|
|
545
|
+
/** @internal the reason of a system context ("": the caller's) */
|
|
546
|
+
system?: string,
|
|
547
|
+
/** The run a job's handler is in; outside a run its `runId` is empty and `attempt` 0. */
|
|
548
|
+
job?: JobInfo);
|
|
549
|
+
private syscall;
|
|
550
|
+
/**
|
|
551
|
+
* The plugin's background jobs: `enqueue` a run, `cancel` one. In a declared transaction (`tx.jobs`) an enqueue is
|
|
552
|
+
* part of it.
|
|
553
|
+
*/
|
|
554
|
+
get jobs(): Jobs;
|
|
555
|
+
/** Aborted at the deadline or when the session ends (the same as `ctx.request.signal`); in a job's run, when it must stop. */
|
|
556
|
+
get signal(): AbortSignal;
|
|
557
|
+
/**
|
|
558
|
+
* Calls an endpoint of a dependency as this request's caller, with raw JSON (protobuf JSON mapping): `input`
|
|
559
|
+
* is sent as is (a bigint as a string), the answer is the parsed body. A non-2xx answer throws an `RpcError`
|
|
560
|
+
* with the dependency's status, code and message. The typed clients `celobus plugin add` writes (`src/deps/`) call it.
|
|
561
|
+
*/
|
|
562
|
+
call<T = unknown>(plugin: string, endpoint: string, input?: unknown): Promise<T>;
|
|
563
|
+
/**
|
|
564
|
+
* Tells the screens following `topic` for `key` to re-read (plugin UI). An endpoint that declares
|
|
565
|
+
* `.invalidates(..)` needs no call: the platform emits those after its 2xx answer. This is for the rest: a change made
|
|
566
|
+
* outside a declared endpoint, or a key the endpoint's response does not carry. Nothing is awaited, and a screen
|
|
567
|
+
* that misses it re-reads within its maximum data age.
|
|
568
|
+
*/
|
|
569
|
+
invalidate<K>(topic: TopicDef<K>, key: K): void;
|
|
570
|
+
/** Every key of `topic` re-reads. */
|
|
571
|
+
invalidateAll<K>(topic: TopicDef<K>): void;
|
|
572
|
+
/** @internal */
|
|
573
|
+
protected link(): DbLink;
|
|
574
|
+
/**
|
|
575
|
+
* The plugin's notifications: `send` a notice of a declared kind, `ask` an approval or a
|
|
576
|
+
* decision and `resolve` it, `follow` / `unfollow` a key, `following(key)`. In a transaction
|
|
577
|
+
* (`tx.notifications`) the writes are part of it and its members hear of them when it commits: send last in it.
|
|
578
|
+
*/
|
|
579
|
+
get notifications(): Notifications;
|
|
580
|
+
/**
|
|
581
|
+
* The repository of one of the plugin's entities; in a transaction (`tx.db(order)`) its calls are part of it. A
|
|
582
|
+
* dependency's entity is read with `ctx.query` (500 `internal` here).
|
|
583
|
+
*/
|
|
584
|
+
db<E extends EntityDef<any>>(entity: E & (E extends EntityDef<any, true> ? never : unknown)): Repository<E>;
|
|
585
|
+
/**
|
|
586
|
+
* A typed read across entities, from the root `entity`: one of the plugin's, a dependency's exported one
|
|
587
|
+
* (`ctx.query(customers.customer)`, generated by `celobus plugin add`; it keeps the repository's reads too: `get`,
|
|
588
|
+
* `find`, `count`, `exists`, `all`, `aggregate`), or the directory's (`platform.user` from `@celobus/sdk/platform`).
|
|
589
|
+
* Joins, `where`, `groupBy`, `having`, `select`, `orderBy`, `limit`; then `all`, `first`, `count`, `page`. In a
|
|
590
|
+
* transaction it is part of it; in a system context it reads the plugin's own entities within its `authz:bypass`,
|
|
591
|
+
* the directory as a member does, and a dependency's entity under the provider's rules for the caller (never more
|
|
592
|
+
* than the caller reads without the system context).
|
|
593
|
+
*/
|
|
594
|
+
query<E extends Queryable>(entity: E): Query<E>;
|
|
595
|
+
/**
|
|
596
|
+
* SQL that reads (`select`, `with`, `values`), with positional parameters: `$1` is the first value after the query
|
|
597
|
+
* (`ctx.sql('select owner_id, count(*) as notes from hello_note group by 1 having count(*) >= $1', 2)`). It reads the
|
|
598
|
+
* entities of every installed plugin (`<plugin>_<entity>`: `chat_post`) and of the directory
|
|
599
|
+
* (`platform_user`, `platform_group`, `platform_group_member`, `platform_role_assignment`) as the caller: each
|
|
600
|
+
* entity's own rules and masks apply; never a catalog (`pg_class`, `information_schema`, `pg_stat_activity`) or
|
|
601
|
+
* another workspace: a relation outside these, or a function in `from` other than a few
|
|
602
|
+
* set-returning built-ins (`generate_series`, `unnest`, the JSON element and record functions, `regexp_matches`,
|
|
603
|
+
* `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;
|
|
604
|
+
* 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
|
|
605
|
+
* it and sees its writes. More than 1,000 rows is 422 `query_rows_limit`; the platform's refusals are those of
|
|
606
|
+
* `ctx.db`. An encrypted field reads as its ciphertext: read it with `ctx.db`.
|
|
607
|
+
*
|
|
608
|
+
* The values follow the query as arguments, as `$1`, `$2`, … follow in the text: a string, number, bigint,
|
|
609
|
+
* boolean, `null`, `Date`, or anything JSON (an object or array is its JSON text). Each is only ever a value,
|
|
610
|
+
* never SQL.
|
|
611
|
+
*/
|
|
612
|
+
sql<R = SqlRow>(query: string, ...params: unknown[]): Promise<R[]>;
|
|
613
|
+
/**
|
|
614
|
+
* SQL over the tables of every plugin of the workspace (`chat_post`, `crm_customer`) past their access rules, with
|
|
615
|
+
* the capability `sql:unsafe`: a read, or with the capability `sql:write` also an `insert`, `update` or `delete`
|
|
616
|
+
* (its `returning` rows come back; none without). Never the platform's tables, the directory's (read it with
|
|
617
|
+
* `ctx.sql`) or a catalog (403). It runs in a system context of its own, never in a declared transaction, and each
|
|
618
|
+
* run is recorded in the workspace's audit; the tables keep their soft-deleted rows, and an encrypted field is its
|
|
619
|
+
* ciphertext. Parameters and rows as `ctx.sql`.
|
|
620
|
+
*/
|
|
621
|
+
unsafeSql<R = SqlRow>(query: string, ...params: unknown[]): Promise<R[]>;
|
|
622
|
+
private runSql;
|
|
623
|
+
/**
|
|
624
|
+
* The same context with the system's rights on the plugin's own entities: its repository calls (and the
|
|
625
|
+
* transactions it begins) bypass the access rules within the scope the plugin declares for `authz:bypass`
|
|
626
|
+
* (outside it, 403 `capability_missing`), read masked columns, and are recorded in the workspace's audit with the
|
|
627
|
+
* caller, the request and `reason`.
|
|
628
|
+
*/
|
|
629
|
+
asSystem(reason: string): this;
|
|
630
|
+
/**
|
|
631
|
+
* A declared transaction: `fn` gets `tx`, a context whose repository calls are part of it; it commits when `fn`
|
|
632
|
+
* resolves and rolls back when it throws. Inside a transaction it is nested and rolls back alone. The platform rolls back a
|
|
633
|
+
* transaction still open when the request ends or 5 s pass (504 `transaction_timeout`).
|
|
634
|
+
*/
|
|
635
|
+
transaction<T>(fn: (tx: TxCtx) => Promise<T>, options?: TransactionOptions): Promise<T>;
|
|
636
|
+
}
|
|
637
|
+
/**
|
|
638
|
+
* The context inside a declared transaction (`ctx.transaction(async (tx) => ..)`): a `Ctx` whose repositories may
|
|
639
|
+
* lock the rows they read (`tx.db(e).get(id, { lock: 'update' })`, `tx.db(e).find(f).forUpdate().skipLocked()`).
|
|
640
|
+
*/
|
|
641
|
+
export declare class TxCtx extends Ctx {
|
|
642
|
+
db<E extends EntityDef<any>>(entity: E & (E extends EntityDef<any, true> ? never : unknown)): TxRepository<E>;
|
|
643
|
+
}
|
|
644
|
+
export {};
|