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