@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/src/tree.ts ADDED
@@ -0,0 +1,170 @@
1
+ import { EMPTY_USAGE, addUsage, createGate, messageOf, type TokenUsage } from "@providerkit/core";
2
+ import { immutableCopy } from "./snapshot.ts";
3
+ import type { AgentHost, RunOptions, RunSnapshot, RunState } from "./types.ts";
4
+
5
+ export type StopState = Exclude<RunState, { status: "running" | "completed" }>;
6
+
7
+ export class Halt extends Error {
8
+ constructor(readonly state: StopState) {
9
+ super(state.status);
10
+ }
11
+ }
12
+
13
+ export function fail(code: string, message: string, operationId?: string): never {
14
+ throw new Halt({ status: "failed", error: { code, message, operationId } });
15
+ }
16
+
17
+ /** Cancellation stops SDK work, not external effects which ignore their signal. */
18
+ export async function untilAbort<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
19
+ let onAbort = () => {};
20
+ try {
21
+ return await Promise.race([
22
+ work,
23
+ new Promise<never>((_resolve, reject) => {
24
+ onAbort = () => reject(signal.reason);
25
+ if (signal.aborted) onAbort();
26
+ else signal.addEventListener("abort", onAbort, { once: true });
27
+ }),
28
+ ]);
29
+ } finally {
30
+ signal.removeEventListener("abort", onAbort);
31
+ }
32
+ }
33
+
34
+ export function* snapshots(root: RunSnapshot): Generator<RunSnapshot> {
35
+ yield root;
36
+ for (const delegation of root.delegations)
37
+ for (const child of delegation.children) yield* snapshots(child.snapshot);
38
+ }
39
+
40
+ /** Count local receipts once. Never add a child's already aggregated total. */
41
+ export function treeUsage(root: RunSnapshot): TokenUsage {
42
+ let usage = { ...EMPTY_USAGE };
43
+ const seen = new Set<string>();
44
+ for (const snapshot of snapshots(root)) {
45
+ for (const model of snapshot.models) {
46
+ if (seen.has(model.id)) continue;
47
+ seen.add(model.id);
48
+ usage = addUsage(usage, model.usage);
49
+ }
50
+ }
51
+ return usage;
52
+ }
53
+
54
+ export async function authorizeTree(root: RunSnapshot, host: AgentHost): Promise<void> {
55
+ if (!host.authorizeResume)
56
+ throw new TypeError("Resume requires a trusted host.authorizeResume callback.");
57
+ // A parent's ownership is not authority over a descendant's tools or approvals.
58
+ for (const snapshot of snapshots(root)) await host.authorizeResume(immutableCopy(snapshot));
59
+ }
60
+
61
+ /** One root lease belongs to the host. This scope only coordinates its in-process tree. */
62
+ export class ExecutionTree {
63
+ readonly signal: AbortSignal;
64
+ readonly gate;
65
+ private readonly timeout = new AbortController();
66
+ private readonly broken = new AbortController();
67
+ private readonly timer;
68
+ private writes = Promise.resolve();
69
+ private toolBarrier = Promise.resolve();
70
+ private toolsSettled = Promise.resolve();
71
+ private checkpointFailure: Extract<RunState, { status: "failed" }> | undefined;
72
+
73
+ constructor(
74
+ readonly root: RunSnapshot,
75
+ private readonly options: RunOptions,
76
+ ) {
77
+ this.gate = createGate(root.tree.limits.maxParallel);
78
+ this.signal = AbortSignal.any([
79
+ this.timeout.signal,
80
+ this.broken.signal,
81
+ ...(options.signal ? [options.signal] : []),
82
+ ]);
83
+ this.timer = setTimeout(
84
+ () => this.timeout.abort(new Error("The agent tree reached its time limit.")),
85
+ Math.max(0, root.tree.startedAt + root.tree.limits.elapsedMs - Date.now()),
86
+ );
87
+ }
88
+
89
+ active(): void {
90
+ if (this.checkpointFailure) throw new Halt(this.checkpointFailure);
91
+ if (this.options.signal?.aborted) throw new Halt({ status: "cancelled" });
92
+ if (
93
+ this.timeout.signal.aborted ||
94
+ Date.now() >= this.root.tree.startedAt + this.root.tree.limits.elapsedMs
95
+ )
96
+ throw new Halt({ status: "limited", limit: "treeElapsedMs" });
97
+ }
98
+
99
+ reserveModel(): void {
100
+ this.active();
101
+ // ponytail: a bounded tree is small. Deriving counters from the journal also
102
+ // preserves every reservation across resume without a second mutable ledger.
103
+ let models = 0;
104
+ for (const snapshot of snapshots(this.root)) models += snapshot.models.length;
105
+ if (models >= this.root.tree.limits.modelCalls)
106
+ throw new Halt({ status: "limited", limit: "modelCalls" });
107
+ }
108
+
109
+ reserveChild(depth: number): void {
110
+ this.active();
111
+ if (depth > this.root.tree.limits.maxDepth)
112
+ throw new Halt({ status: "limited", limit: "maxDepth" });
113
+ if ([...snapshots(this.root)].length - 1 >= this.root.tree.limits.maxChildren)
114
+ throw new Halt({ status: "limited", limit: "maxChildren" });
115
+ }
116
+
117
+ async invokeTool<T>(
118
+ parallel: boolean,
119
+ signal: AbortSignal,
120
+ invoke: () => Promise<T>,
121
+ ): Promise<T> {
122
+ // Safe calls share a barrier. A serial call waits for all prior calls and
123
+ // becomes the barrier for later ones, across every specialist in this tree.
124
+ const previous = parallel ? this.toolBarrier : this.toolsSettled;
125
+ const work = previous.then(() => {
126
+ signal.throwIfAborted();
127
+ return untilAbort(invoke(), signal);
128
+ });
129
+ const settled = work.then(
130
+ () => {},
131
+ () => {},
132
+ );
133
+ this.toolsSettled = Promise.all([this.toolsSettled, settled]).then(() => {});
134
+ if (!parallel) this.toolBarrier = this.toolsSettled;
135
+ // Cancelling a queued call must return without waiting for another child.
136
+ // This cannot stop external effects that ignore their signal.
137
+ return untilAbort(work, signal);
138
+ }
139
+
140
+ async save(): Promise<void> {
141
+ const saved = immutableCopy(this.root);
142
+ // Every descendant writes the whole root through this one queue. Capturing at
143
+ // enqueue time keeps a slow earlier save from erasing a newer child's receipt.
144
+ this.writes = this.writes.then(async () => {
145
+ await this.options.host?.checkpoint?.(saved);
146
+ });
147
+ try {
148
+ await this.writes;
149
+ } catch (error) {
150
+ this.checkpointFailure ??= {
151
+ status: "failed",
152
+ error: {
153
+ code: "checkpoint_failed",
154
+ message: `Checkpoint failed: ${messageOf(error)}. Reconcile stored state before resuming.`,
155
+ },
156
+ };
157
+ this.broken.abort(error);
158
+ throw new Halt(this.checkpointFailure);
159
+ }
160
+ }
161
+
162
+ close(): void {
163
+ clearTimeout(this.timer);
164
+ }
165
+ }
166
+
167
+ export interface ExecutionScope {
168
+ tree: ExecutionTree;
169
+ depth: number;
170
+ }
package/src/types.ts ADDED
@@ -0,0 +1,285 @@
1
+ import type {
2
+ ChatMessage,
3
+ JsonObjectSchema,
4
+ Provider,
5
+ ProviderChunk,
6
+ TokenUsage,
7
+ Tool,
8
+ ToolCall,
9
+ ToolContext,
10
+ ToolFailure,
11
+ Turn,
12
+ } from "@providerkit/core";
13
+
14
+ import type {
15
+ AGENT_RUNTIME,
16
+ AgentRuntime,
17
+ Delegation,
18
+ SpecialistToolOptions,
19
+ } from "./delegation.ts";
20
+
21
+ /** Tree limits count the root too, except maxChildren and maxDepth (root depth is zero). */
22
+ export interface TreeLimits {
23
+ maxParallel: number;
24
+ maxChildren: number;
25
+ maxDepth: number;
26
+ /** SDK admissions only. Provider-internal retries stay in core. */
27
+ modelCalls: number;
28
+ /** Includes queueing and waiting for approval, across resumed attempts. */
29
+ elapsedMs: number;
30
+ }
31
+
32
+ /** Limits for one run, not a whole tree of delegated runs. Cancellation is cooperative:
33
+ * an admitted call can still finish or incur a charge after the signal aborts. */
34
+ export interface RunLimits {
35
+ turns: number;
36
+ toolCalls: number;
37
+ /** Wall time, including time spent waiting for approval. */
38
+ elapsedMs: number;
39
+ parallelTools: number;
40
+ }
41
+
42
+ export interface ResultSchema<T> {
43
+ schema: JsonObjectSchema;
44
+ /** Pure runtime validation. Throw to reject; also used when restoring a result. */
45
+ validate: (value: unknown) => T;
46
+ }
47
+
48
+ export interface AgentConfig {
49
+ id: string;
50
+ /** Change this when instructions, tools or output contracts change. */
51
+ version: string;
52
+ instructions: string;
53
+ /** Already composed with whatever routing, retries and watchdog the caller needs. */
54
+ provider: Provider;
55
+ /** Core tools or delegation descriptors. Terminal tools use the output contract. */
56
+ tools?: readonly (Tool | Delegation)[];
57
+ limits?: Partial<RunLimits>;
58
+ /** Applies when this agent is the root. Descendants share the root's limits. */
59
+ treeLimits?: Partial<TreeLimits>;
60
+ }
61
+
62
+ export type AgentDefinition<T = string> = AgentConfig & { output?: ResultSchema<T> };
63
+
64
+ export interface Agent<T = string> {
65
+ readonly id: string;
66
+ readonly version: string;
67
+ run(input: string, options?: RunOptions): Promise<RunOutcome<T>>;
68
+ /** Structural validation is not authorization. A host must authorize every resume. */
69
+ resume(snapshot: unknown, options: ResumeOptions): Promise<RunOutcome<T>>;
70
+ asTool(options: SpecialistToolOptions<T>): Delegation;
71
+ /** @internal Execution is scoped explicitly, never through global current-run state. */
72
+ readonly [AGENT_RUNTIME]: AgentRuntime<T>;
73
+ }
74
+
75
+ export interface ToolRequest {
76
+ agentId: string;
77
+ version: string;
78
+ runId: string;
79
+ attemptId: string;
80
+ operationId: string;
81
+ call: ToolCall;
82
+ arguments: Record<string, unknown>;
83
+ }
84
+
85
+ export interface ApprovalScope {
86
+ actorId: string;
87
+ resource: { id: string; version: string };
88
+ expiresAt: number;
89
+ }
90
+
91
+ export interface PendingApproval {
92
+ request: ToolRequest;
93
+ scope: ApprovalScope;
94
+ }
95
+
96
+ export interface ChildPathStep {
97
+ operationId: string;
98
+ key: string;
99
+ runId: string;
100
+ }
101
+
102
+ export interface ChildEnvelope {
103
+ snapshot: RunSnapshot;
104
+ /** An opaque host execution segment, not an independently owned SDK run. */
105
+ reference?: string;
106
+ }
107
+
108
+ export interface ChildRequest extends ChildEnvelope {
109
+ key: string;
110
+ parentRunId: string;
111
+ operationId: string;
112
+ /** A stored SDK child needs resuming, not replay of a successful host segment. */
113
+ resume: boolean;
114
+ }
115
+
116
+ /** Host callbacks are trusted code, never functions reconstructed from a client snapshot.
117
+ * Data passed to callbacks is a frozen copy, not the loop's live state. Without checkpoint,
118
+ * execution is in-memory only. Checkpoints are not leases or exactly-once effect guarantees. */
119
+ export interface AgentHost {
120
+ /** Persist the whole snapshot before returning. Writes are serialized within this attempt. */
121
+ checkpoint?: (snapshot: RunSnapshot) => void | Promise<void>;
122
+ /** Load/compare authoritative state and check ownership and freshness, or throw.
123
+ * The host must also exclude concurrent attempts; this loop does not take a lease. */
124
+ authorizeResume?: (snapshot: RunSnapshot) => void | Promise<void>;
125
+ /** Supplies the actor and resource version from trusted host state. */
126
+ approvalContext?: (request: ToolRequest) => ApprovalScope | Promise<ApprovalScope>;
127
+ /** Authenticate and consume a decision once. A supplied value is evidence, not permission.
128
+ * A crash after consumption but before the running marker may need host reconciliation. */
129
+ resolveApproval?: (
130
+ approval: PendingApproval,
131
+ decision: unknown,
132
+ ) => "approved" | "denied" | "pending" | Promise<"approved" | "denied" | "pending">;
133
+ /** Recheck permissions and resource versions immediately before each invocation.
134
+ * Required before executing an approved call. Throw to refuse the run. */
135
+ beforeTool?: (request: ToolRequest, approval?: PendingApproval) => void | Promise<void>;
136
+ /** Both this callback and the tool's isConcurrencySafe flag must allow batching. */
137
+ canRunConcurrently?: (request: ToolRequest) => boolean;
138
+ /** Optional in-process child binding under this root's lease and cancellation.
139
+ * A host may return a saved envelope. To resume a suspended SDK child it must call
140
+ * execute in a new/resumable segment, not treat a cached suspension as completion.
141
+ * execute may be called once, and must settle before the hook returns. */
142
+ child?: (request: ChildRequest, execute: () => Promise<ChildEnvelope>) => Promise<ChildEnvelope>;
143
+ }
144
+
145
+ export interface RunOptions {
146
+ runId?: string;
147
+ signal?: AbortSignal;
148
+ /** Passed to tools with reserved runId, attemptId, operationId, callId and signal supplied by the loop. */
149
+ context?: ToolContext;
150
+ host?: AgentHost;
151
+ /** Best-effort progress from the one stream reader. Observer errors do not stop work. */
152
+ onEvent?: (event: AgentEvent) => void | Promise<void>;
153
+ }
154
+
155
+ export interface ResumeOptions extends Omit<RunOptions, "runId"> {
156
+ host: AgentHost & { authorizeResume: NonNullable<AgentHost["authorizeResume"]> };
157
+ /** JSON evidence for resolveApproval, never a trusted approve flag. */
158
+ decision?: unknown;
159
+ /** Exact path from the suspended outcome. Required for descendant decision evidence. */
160
+ approvalPath?: readonly ChildPathStep[];
161
+ }
162
+
163
+ export interface RunFailure {
164
+ code: string;
165
+ message: string;
166
+ operationId?: string;
167
+ }
168
+
169
+ export type LimitReason =
170
+ | "turns"
171
+ | "toolCalls"
172
+ | "elapsedMs"
173
+ | "outputTokens"
174
+ | "maxChildren"
175
+ | "maxDepth"
176
+ | "modelCalls"
177
+ | "treeElapsedMs";
178
+
179
+ export type RunState =
180
+ | { status: "running" }
181
+ /** Saves the original result input, not a validator's potentially non-JSON return value. */
182
+ | { status: "completed"; candidate: unknown }
183
+ | { status: "suspended"; approval: PendingApproval; path: ChildPathStep[] }
184
+ | { status: "cancelled" }
185
+ | { status: "limited"; limit: LimitReason }
186
+ | { status: "failed"; error: RunFailure };
187
+
188
+ export type ToolResult =
189
+ | { ok: true; content: string }
190
+ | { ok: false; content: string; kind: ToolFailure | "denied" | "unknown_tool" };
191
+
192
+ export type ToolExecution =
193
+ | { id: string; status: "pending" }
194
+ | { id: string; status: "running"; attemptId: string }
195
+ /** Pure coordination can replay. Its children keep their own effect journals. */
196
+ | { id: string; status: "delegating"; attemptId: string }
197
+ | { id: string; status: "completed"; attemptId: string; result: ToolResult };
198
+
199
+ export type ModelExecution =
200
+ | { id: string; attemptId: string; status: "running"; usage: TokenUsage }
201
+ | {
202
+ id: string;
203
+ attemptId: string;
204
+ status: "completed";
205
+ usage: TokenUsage;
206
+ turn: Turn;
207
+ tools: ToolExecution[];
208
+ };
209
+
210
+ export interface DelegationExecution {
211
+ operationId: string;
212
+ /** Admission order is the deterministic join/approval order. Receipts are never removed. */
213
+ children: (ChildEnvelope & { key: string })[];
214
+ }
215
+
216
+ /** JSON-serializable execution journal. Contains private prompts, arguments and results;
217
+ * the host owns storage, access and retention. Never accept it as proof of permission. */
218
+ export interface RunSnapshot {
219
+ format: 2;
220
+ agentId: string;
221
+ version: string;
222
+ runId: string;
223
+ attemptId: string;
224
+ startedAt: number;
225
+ input: string;
226
+ limits: RunLimits;
227
+ models: ModelExecution[];
228
+ delegations: DelegationExecution[];
229
+ /** Identical in every node. Admissions are counted from the journals, including running work. */
230
+ tree: { runId: string; startedAt: number; limits: TreeLimits };
231
+ state: RunState;
232
+ }
233
+
234
+ /** Stable operation identity; an attempt changes on resume, an operation does not.
235
+ * A model receipt's usage may be partial if the stream failed. */
236
+ export type OperationReceipt =
237
+ | {
238
+ kind: "model";
239
+ id: string;
240
+ attemptId: string;
241
+ status: "running" | "completed";
242
+ usage: TokenUsage;
243
+ source?: Turn["source"];
244
+ }
245
+ | {
246
+ kind: "tool" | "delegation";
247
+ id: string;
248
+ callId: string;
249
+ attemptId: string;
250
+ status: "running" | "completed";
251
+ result?: ToolResult;
252
+ };
253
+
254
+ interface RunRecord {
255
+ runId: string;
256
+ attemptId: string;
257
+ usage: TokenUsage;
258
+ /** This run and all descendants, deduplicated by stable model receipt IDs. */
259
+ treeUsage: TokenUsage;
260
+ /** Whole settled turns only. An unfinished tool round remains in snapshot.models. */
261
+ history: ChatMessage[];
262
+ receipts: OperationReceipt[];
263
+ snapshot: RunSnapshot;
264
+ }
265
+
266
+ export type RunOutcome<T = string> = RunRecord &
267
+ (
268
+ | { status: "completed"; output: T }
269
+ | { status: "suspended"; approval: PendingApproval; path: ChildPathStep[] }
270
+ | { status: "cancelled" }
271
+ | { status: "limited"; limit: LimitReason }
272
+ | { status: "failed"; error: RunFailure }
273
+ );
274
+
275
+ export type AgentEvent =
276
+ | {
277
+ type: "model_chunk";
278
+ runId: string;
279
+ attemptId: string;
280
+ operationId: string;
281
+ chunk: ProviderChunk;
282
+ }
283
+ | { type: "tool_start"; request: ToolRequest }
284
+ | { type: "tool_result"; request: ToolRequest; result: ToolResult }
285
+ | { type: "state"; runId: string; attemptId: string; state: RunState };