@providerkit/agents 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 +21 -0
- package/README.md +272 -2
- package/dist/delegation.d.ts +66 -0
- package/dist/delegation.d.ts.map +1 -0
- package/dist/delegation.js +267 -0
- package/dist/delegation.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/dist/run.d.ts +8 -0
- package/dist/run.d.ts.map +1 -0
- package/dist/run.js +636 -0
- package/dist/run.js.map +1 -0
- package/dist/runs.d.ts +67 -0
- package/dist/runs.d.ts.map +1 -0
- package/dist/runs.js +256 -0
- package/dist/runs.js.map +1 -0
- package/dist/snapshot.d.ts +26 -0
- package/dist/snapshot.d.ts.map +1 -0
- package/dist/snapshot.js +510 -0
- package/dist/snapshot.js.map +1 -0
- package/dist/tree.d.ts +42 -0
- package/dist/tree.d.ts.map +1 -0
- package/dist/tree.js +151 -0
- package/dist/tree.js.map +1 -0
- package/dist/types.d.ts +292 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +2 -0
- package/dist/types.js.map +1 -0
- package/examples/background.ts +45 -0
- package/examples/basic.ts +44 -0
- package/examples/specialists.ts +99 -0
- package/package.json +62 -4
- package/src/delegation.ts +405 -0
- package/src/index.ts +11 -0
- package/src/run.ts +834 -0
- package/src/runs.ts +365 -0
- package/src/snapshot.ts +628 -0
- package/src/tree.ts +170 -0
- package/src/types.ts +285 -0
package/src/runs.ts
ADDED
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
import type { createRuns, Run, RunEvent, RunHandler, StoredRun } from "@gusnips/server/runs";
|
|
2
|
+
import { AGENT_RUNTIME } from "./delegation.ts";
|
|
3
|
+
import { copyData, equalData, immutableCopy, isId, isRecord } from "./snapshot.ts";
|
|
4
|
+
import { untilAbort } from "./tree.ts";
|
|
5
|
+
import type {
|
|
6
|
+
Agent,
|
|
7
|
+
AgentHost,
|
|
8
|
+
ChildEnvelope,
|
|
9
|
+
RunOptions,
|
|
10
|
+
RunOutcome,
|
|
11
|
+
RunSnapshot,
|
|
12
|
+
} from "./types.ts";
|
|
13
|
+
|
|
14
|
+
export type BackgroundRuns = Pick<
|
|
15
|
+
ReturnType<typeof createRuns>,
|
|
16
|
+
"create" | "read" | "tail" | "cancel"
|
|
17
|
+
>;
|
|
18
|
+
|
|
19
|
+
export interface Continuation {
|
|
20
|
+
/** Unique authorization claim, distinct from both the logical run and the host row. */
|
|
21
|
+
id: string;
|
|
22
|
+
sourceId: string;
|
|
23
|
+
decision: unknown;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export interface BackgroundContext {
|
|
27
|
+
/** From the authenticated caller, or from Run.owner inside a worker. */
|
|
28
|
+
owner: string;
|
|
29
|
+
segmentId: string;
|
|
30
|
+
continuation?: Continuation;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface BackgroundPolicy
|
|
34
|
+
extends
|
|
35
|
+
Required<
|
|
36
|
+
Pick<AgentHost, "authorizeResume" | "approvalContext" | "resolveApproval" | "beforeTool">
|
|
37
|
+
>,
|
|
38
|
+
Pick<AgentHost, "canRunConcurrently"> {
|
|
39
|
+
/** Worker-only values for tools, such as the authenticated actor or a database handle.
|
|
40
|
+
* Never serialized. The SDK supplies reserved operation IDs and cancellation signals. */
|
|
41
|
+
context?: RunOptions["context"];
|
|
42
|
+
/** Called under the worker's lease, after its row exists. Authenticate the decision,
|
|
43
|
+
* recheck resource version/expiry and atomically reserve this approval for continuation.id
|
|
44
|
+
* AND context.segmentId. Repeating that exact claim must succeed; any other claim or segment
|
|
45
|
+
* must fail. authorizeResume checks ownership on every attempt. resolveApproval may reuse a
|
|
46
|
+
* consumed decision only for this same claim/segment. These guarantees need durable host state. */
|
|
47
|
+
claimContinuation: (snapshot: RunSnapshot, continuation: Continuation) => void | Promise<void>;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export interface BackgroundOptions<T> {
|
|
51
|
+
agent: Agent<T>;
|
|
52
|
+
/** Dedicated handler key for this agent version. */
|
|
53
|
+
kind: string;
|
|
54
|
+
runs: BackgroundRuns;
|
|
55
|
+
/** Await durable queue acceptance. A worker calls runs.drive(id, background.handlers).
|
|
56
|
+
* The host must also run runs.sweep on boot and periodically, and drain on shutdown. */
|
|
57
|
+
enqueue: (id: string) => Promise<void>;
|
|
58
|
+
policy: (context: BackgroundContext) => BackgroundPolicy | Promise<BackgroundPolicy>;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
export interface BackgroundRun<T> {
|
|
62
|
+
id: string;
|
|
63
|
+
/** Host completion is not SDK completion: a successful segment can be suspended or failed. */
|
|
64
|
+
status: StoredRun["status"];
|
|
65
|
+
snapshot: RunSnapshot;
|
|
66
|
+
outcome: RunOutcome<T> | null;
|
|
67
|
+
error: StoredRun["error"];
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The row exists. Retry queueing this id, or let the host sweep find it; do not start again. */
|
|
71
|
+
export class BackgroundEnqueueError extends Error {
|
|
72
|
+
constructor(
|
|
73
|
+
readonly id: string,
|
|
74
|
+
cause: unknown,
|
|
75
|
+
) {
|
|
76
|
+
super(
|
|
77
|
+
`Run ${id} was saved, but queueing failed. Enqueue this id again; do not create another run.`,
|
|
78
|
+
{ cause },
|
|
79
|
+
);
|
|
80
|
+
this.name = "BackgroundEnqueueError";
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
interface Segment {
|
|
85
|
+
format: 1;
|
|
86
|
+
snapshot: RunSnapshot;
|
|
87
|
+
continuation?: Continuation;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Restore only the original pending route, using the latest receipts throughout.
|
|
91
|
+
* Ancestors become running during coordination, before the leaf consumes its decision. */
|
|
92
|
+
function restoreApprovalRoute(snapshot: RunSnapshot, initial: RunSnapshot): boolean {
|
|
93
|
+
const pending = initial.state;
|
|
94
|
+
if (pending.status !== "suspended") return false;
|
|
95
|
+
const route = [snapshot];
|
|
96
|
+
let node = snapshot;
|
|
97
|
+
for (const step of pending.path) {
|
|
98
|
+
const child = node.delegations
|
|
99
|
+
.find((journal) => journal.operationId === step.operationId)
|
|
100
|
+
?.children.find((child) => child.key === step.key && child.snapshot.runId === step.runId);
|
|
101
|
+
if (!child) return false;
|
|
102
|
+
node = child.snapshot;
|
|
103
|
+
route.push(node);
|
|
104
|
+
}
|
|
105
|
+
if (node.state.status !== "suspended" || !equalData(node.state.approval, pending.approval))
|
|
106
|
+
return false;
|
|
107
|
+
for (const [index, ancestor] of route.entries()) {
|
|
108
|
+
const state = ancestor.state;
|
|
109
|
+
if (
|
|
110
|
+
state.status !== "running" &&
|
|
111
|
+
!(
|
|
112
|
+
state.status === "suspended" &&
|
|
113
|
+
equalData(state.approval, pending.approval) &&
|
|
114
|
+
equalData(state.path, pending.path.slice(index))
|
|
115
|
+
)
|
|
116
|
+
)
|
|
117
|
+
return false;
|
|
118
|
+
}
|
|
119
|
+
for (const [index, ancestor] of route.entries())
|
|
120
|
+
ancestor.state = { ...copyData(pending), path: pending.path.slice(index) };
|
|
121
|
+
return true;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** Background work uses the host's lease, queue and cancellation. Children stay in-process.
|
|
125
|
+
* Usage remains in stable SDK receipts; this binding never calls additive Run.spend. */
|
|
126
|
+
export function createBackgroundAgent<T>(options: BackgroundOptions<T>) {
|
|
127
|
+
const { agent, kind, runs, enqueue } = options;
|
|
128
|
+
if (!isId(kind) || typeof enqueue !== "function" || typeof options.policy !== "function")
|
|
129
|
+
throw new TypeError(
|
|
130
|
+
"Provide a run kind, a durable enqueue callback and a trusted policy factory.",
|
|
131
|
+
);
|
|
132
|
+
const runtime = agent[AGENT_RUNTIME];
|
|
133
|
+
|
|
134
|
+
async function policy(context: BackgroundContext): Promise<BackgroundPolicy> {
|
|
135
|
+
const value = await options.policy(immutableCopy(context));
|
|
136
|
+
for (const key of [
|
|
137
|
+
"authorizeResume",
|
|
138
|
+
"approvalContext",
|
|
139
|
+
"resolveApproval",
|
|
140
|
+
"beforeTool",
|
|
141
|
+
"claimContinuation",
|
|
142
|
+
] as const)
|
|
143
|
+
if (typeof value?.[key] !== "function")
|
|
144
|
+
throw new TypeError(`Background policy must implement ${key}.`);
|
|
145
|
+
return value;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
function segment(raw: unknown): Segment {
|
|
149
|
+
if (!isRecord(raw) || raw.format !== 1)
|
|
150
|
+
throw new TypeError("This row is not an agent background segment.");
|
|
151
|
+
const snapshot = runtime.restore(raw.snapshot);
|
|
152
|
+
if (raw.continuation === undefined) return { format: 1, snapshot };
|
|
153
|
+
const continuation = raw.continuation;
|
|
154
|
+
if (
|
|
155
|
+
!isRecord(continuation) ||
|
|
156
|
+
!isId(continuation.id) ||
|
|
157
|
+
!isId(continuation.sourceId) ||
|
|
158
|
+
continuation.decision === undefined
|
|
159
|
+
)
|
|
160
|
+
throw new TypeError("The saved continuation is invalid.");
|
|
161
|
+
return {
|
|
162
|
+
format: 1,
|
|
163
|
+
snapshot,
|
|
164
|
+
continuation: {
|
|
165
|
+
id: continuation.id,
|
|
166
|
+
sourceId: continuation.sourceId,
|
|
167
|
+
decision: copyData(continuation.decision),
|
|
168
|
+
},
|
|
169
|
+
};
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
function restore(raw: unknown, initial: RunSnapshot): RunSnapshot {
|
|
173
|
+
const saved = runtime.restore(raw);
|
|
174
|
+
if (
|
|
175
|
+
saved.runId !== initial.runId ||
|
|
176
|
+
saved.input !== initial.input ||
|
|
177
|
+
!equalData(saved.tree, initial.tree)
|
|
178
|
+
)
|
|
179
|
+
throw new TypeError("The saved journal belongs to another logical run.");
|
|
180
|
+
return saved;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
async function load(owner: string, id: string) {
|
|
184
|
+
if (!isId(owner) || !isId(id))
|
|
185
|
+
throw new TypeError("Provide an authenticated owner and run id.");
|
|
186
|
+
const row = await runs.read(id, owner);
|
|
187
|
+
if (!row || row.owner !== owner || row.kind !== kind)
|
|
188
|
+
throw new Error("This background run was not found for this owner and agent.");
|
|
189
|
+
const initial = segment(row.input);
|
|
190
|
+
const snapshot = restore(
|
|
191
|
+
row.status === "succeeded" ? row.result : (row.checkpoint ?? initial.snapshot),
|
|
192
|
+
initial.snapshot,
|
|
193
|
+
);
|
|
194
|
+
if (row.status === "succeeded" && snapshot.state.status === "running")
|
|
195
|
+
throw new TypeError("The host segment ended without a settled agent journal.");
|
|
196
|
+
return { row, initial, snapshot };
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
async function read(owner: string, id: string): Promise<BackgroundRun<T>> {
|
|
200
|
+
const { row, snapshot } = await load(owner, id);
|
|
201
|
+
return {
|
|
202
|
+
id: row.id,
|
|
203
|
+
status: row.status,
|
|
204
|
+
snapshot,
|
|
205
|
+
outcome: snapshot.state.status === "running" ? null : runtime.hydrate(snapshot),
|
|
206
|
+
error: row.error,
|
|
207
|
+
};
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
async function create(owner: string, initial: Segment): Promise<{ id: string }> {
|
|
211
|
+
// Input is stored in the create transaction, before any id is acknowledged or queued.
|
|
212
|
+
const created = await runs.create({ kind, owner, restart: "resume", input: copyData(initial) });
|
|
213
|
+
try {
|
|
214
|
+
await enqueue(created.id);
|
|
215
|
+
} catch (cause) {
|
|
216
|
+
throw new BackgroundEnqueueError(created.id, cause);
|
|
217
|
+
}
|
|
218
|
+
return created;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
async function drive(run: Run): Promise<RunSnapshot> {
|
|
222
|
+
run.signal.throwIfAborted();
|
|
223
|
+
const initial = segment(run.input);
|
|
224
|
+
const snapshot = restore(run.checkpoint ?? initial.snapshot, initial.snapshot);
|
|
225
|
+
const trusted = await untilAbort(
|
|
226
|
+
policy({
|
|
227
|
+
owner: run.owner,
|
|
228
|
+
segmentId: run.id,
|
|
229
|
+
continuation: initial.continuation,
|
|
230
|
+
}),
|
|
231
|
+
run.signal,
|
|
232
|
+
);
|
|
233
|
+
run.signal.throwIfAborted();
|
|
234
|
+
if (initial.continuation)
|
|
235
|
+
await untilAbort(
|
|
236
|
+
Promise.resolve(
|
|
237
|
+
trusted.claimContinuation(
|
|
238
|
+
immutableCopy(initial.snapshot),
|
|
239
|
+
immutableCopy(initial.continuation),
|
|
240
|
+
),
|
|
241
|
+
),
|
|
242
|
+
run.signal,
|
|
243
|
+
);
|
|
244
|
+
const parents = new Map<string, Run>([[snapshot.runId, run]]);
|
|
245
|
+
const host: AgentHost & { authorizeResume: BackgroundPolicy["authorizeResume"] } = {
|
|
246
|
+
authorizeResume(saved) {
|
|
247
|
+
run.signal.throwIfAborted();
|
|
248
|
+
return untilAbort(Promise.resolve(trusted.authorizeResume(saved)), run.signal);
|
|
249
|
+
},
|
|
250
|
+
approvalContext: (request) => trusted.approvalContext(request),
|
|
251
|
+
resolveApproval: (approval, decision) => trusted.resolveApproval(approval, decision),
|
|
252
|
+
beforeTool: (request, approval) => trusted.beforeTool(request, approval),
|
|
253
|
+
canRunConcurrently: (request) => trusted.canRunConcurrently?.(request) === true,
|
|
254
|
+
async checkpoint(saved) {
|
|
255
|
+
run.signal.throwIfAborted();
|
|
256
|
+
await run.save(saved);
|
|
257
|
+
},
|
|
258
|
+
async child(request, execute) {
|
|
259
|
+
const parent = parents.get(request.parentRunId);
|
|
260
|
+
if (!parent) throw new Error("The child's active host parent is missing.");
|
|
261
|
+
let key = request.snapshot.runId;
|
|
262
|
+
for (;;) {
|
|
263
|
+
let executed = false;
|
|
264
|
+
const result = await parent.child<ChildEnvelope>(
|
|
265
|
+
key,
|
|
266
|
+
{
|
|
267
|
+
kind,
|
|
268
|
+
input: { format: 1, snapshot: request.snapshot },
|
|
269
|
+
restart: "resume",
|
|
270
|
+
},
|
|
271
|
+
async (child) => {
|
|
272
|
+
executed = true;
|
|
273
|
+
parents.set(request.snapshot.runId, child);
|
|
274
|
+
try {
|
|
275
|
+
const envelope = await execute();
|
|
276
|
+
run.signal.throwIfAborted();
|
|
277
|
+
return { ...envelope, reference: child.id };
|
|
278
|
+
} finally {
|
|
279
|
+
parents.delete(request.snapshot.runId);
|
|
280
|
+
}
|
|
281
|
+
},
|
|
282
|
+
);
|
|
283
|
+
run.signal.throwIfAborted();
|
|
284
|
+
if (!result.ok) throw new Error(`The host child failed: ${result.error.code}.`);
|
|
285
|
+
const envelope = result.value;
|
|
286
|
+
if (executed || envelope.snapshot.state.status !== "suspended") return envelope;
|
|
287
|
+
// A successful host row cannot reopen. Walk past cached suspensions to a new
|
|
288
|
+
// keyed segment. Completed receipts still return without invoking execute.
|
|
289
|
+
if (!isId(envelope.reference))
|
|
290
|
+
throw new Error("The suspended child has no host reference.");
|
|
291
|
+
key = JSON.stringify([request.snapshot.runId, "after", envelope.reference]);
|
|
292
|
+
}
|
|
293
|
+
},
|
|
294
|
+
};
|
|
295
|
+
const continuation = initial.continuation;
|
|
296
|
+
// Never reapply old evidence to a later approval or roll back a running effect marker.
|
|
297
|
+
const pending = initial.snapshot.state;
|
|
298
|
+
const decision =
|
|
299
|
+
continuation && restoreApprovalRoute(snapshot, initial.snapshot)
|
|
300
|
+
? continuation.decision
|
|
301
|
+
: undefined;
|
|
302
|
+
const result = await agent.resume(snapshot, {
|
|
303
|
+
signal: run.signal,
|
|
304
|
+
context: trusted.context,
|
|
305
|
+
host,
|
|
306
|
+
...(decision !== undefined
|
|
307
|
+
? { decision, approvalPath: pending.status === "suspended" ? pending.path : [] }
|
|
308
|
+
: {}),
|
|
309
|
+
onEvent: (event) => run.emit("agent", event),
|
|
310
|
+
});
|
|
311
|
+
// The portable loop reports cancellation as data. The run service needs its control
|
|
312
|
+
// exception back, or a cancelled/lost/draining worker could record a successful job.
|
|
313
|
+
run.signal.throwIfAborted();
|
|
314
|
+
return result.snapshot;
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
const handlers: Readonly<Record<string, RunHandler>> = Object.freeze({ [kind]: drive });
|
|
318
|
+
return Object.freeze({
|
|
319
|
+
handlers,
|
|
320
|
+
async start(owner: string, input: string): Promise<{ id: string }> {
|
|
321
|
+
if (!isId(owner) || !isId(input))
|
|
322
|
+
throw new TypeError("Provide an authenticated owner and non-empty input.");
|
|
323
|
+
return create(owner, {
|
|
324
|
+
format: 1,
|
|
325
|
+
snapshot: runtime.restore(runtime.create(input, crypto.randomUUID())),
|
|
326
|
+
});
|
|
327
|
+
},
|
|
328
|
+
read,
|
|
329
|
+
async *observe(
|
|
330
|
+
owner: string,
|
|
331
|
+
id: string,
|
|
332
|
+
afterSeq = 0,
|
|
333
|
+
signal?: AbortSignal,
|
|
334
|
+
): AsyncGenerator<RunEvent> {
|
|
335
|
+
await load(owner, id);
|
|
336
|
+
for await (const event of runs.tail(id, afterSeq, signal)) {
|
|
337
|
+
if (signal?.aborted) return;
|
|
338
|
+
yield event;
|
|
339
|
+
}
|
|
340
|
+
},
|
|
341
|
+
async wait(owner: string, id: string, signal?: AbortSignal): Promise<BackgroundRun<T>> {
|
|
342
|
+
await load(owner, id);
|
|
343
|
+
for await (const _event of runs.tail(id, 0, signal)) signal?.throwIfAborted();
|
|
344
|
+
signal?.throwIfAborted();
|
|
345
|
+
return read(owner, id);
|
|
346
|
+
},
|
|
347
|
+
async cancel(owner: string, id: string): Promise<boolean> {
|
|
348
|
+
await load(owner, id);
|
|
349
|
+
return runs.cancel(id);
|
|
350
|
+
},
|
|
351
|
+
/** Queues decision evidence, not permission. The leased worker claims it; read or wait
|
|
352
|
+
* for that segment's outcome to learn whether the host accepted it. */
|
|
353
|
+
async resume(owner: string, id: string, decision: unknown): Promise<{ id: string }> {
|
|
354
|
+
const { row, snapshot } = await load(owner, id);
|
|
355
|
+
if (row.status !== "succeeded" || snapshot.state.status !== "suspended")
|
|
356
|
+
throw new Error("Only a settled, suspended agent segment can accept a decision.");
|
|
357
|
+
if (snapshot.state.approval.scope.expiresAt <= Date.now())
|
|
358
|
+
throw new Error("The approval expired. Request a new decision before continuing.");
|
|
359
|
+
if (decision === undefined)
|
|
360
|
+
throw new TypeError("Provide decision evidence from the authenticated caller.");
|
|
361
|
+
const continuation = copyData({ id: crypto.randomUUID(), sourceId: id, decision });
|
|
362
|
+
return create(owner, { format: 1, snapshot, continuation });
|
|
363
|
+
},
|
|
364
|
+
});
|
|
365
|
+
}
|