@providerkit/agents 0.1.0 → 0.2.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.
Files changed (291) hide show
  1. package/LICENSE-APACHE-2.0 +202 -0
  2. package/README.md +2108 -52
  3. package/THIRD_PARTY_NOTICES.md +521 -0
  4. package/dist/a2a/auth.d.ts +10 -0
  5. package/dist/a2a/auth.d.ts.map +1 -0
  6. package/dist/a2a/auth.js +52 -0
  7. package/dist/a2a/auth.js.map +1 -0
  8. package/dist/a2a/client.d.ts +74 -0
  9. package/dist/a2a/client.d.ts.map +1 -0
  10. package/dist/a2a/client.js +601 -0
  11. package/dist/a2a/client.js.map +1 -0
  12. package/dist/a2a/index.d.ts +22 -0
  13. package/dist/a2a/index.d.ts.map +1 -0
  14. package/dist/a2a/index.js +11 -0
  15. package/dist/a2a/index.js.map +1 -0
  16. package/dist/a2a/memory-runs.d.ts +62 -0
  17. package/dist/a2a/memory-runs.d.ts.map +1 -0
  18. package/dist/a2a/memory-runs.js +349 -0
  19. package/dist/a2a/memory-runs.js.map +1 -0
  20. package/dist/a2a/policy.d.ts +15 -0
  21. package/dist/a2a/policy.d.ts.map +1 -0
  22. package/dist/a2a/policy.js +114 -0
  23. package/dist/a2a/policy.js.map +1 -0
  24. package/dist/a2a/push.d.ts +34 -0
  25. package/dist/a2a/push.d.ts.map +1 -0
  26. package/dist/a2a/push.js +180 -0
  27. package/dist/a2a/push.js.map +1 -0
  28. package/dist/a2a/remote.d.ts +155 -0
  29. package/dist/a2a/remote.d.ts.map +1 -0
  30. package/dist/a2a/remote.js +1196 -0
  31. package/dist/a2a/remote.js.map +1 -0
  32. package/dist/a2a/server.d.ts +110 -0
  33. package/dist/a2a/server.d.ts.map +1 -0
  34. package/dist/a2a/server.js +1139 -0
  35. package/dist/a2a/server.js.map +1 -0
  36. package/dist/a2a/signing.d.ts +21 -0
  37. package/dist/a2a/signing.d.ts.map +1 -0
  38. package/dist/a2a/signing.js +305 -0
  39. package/dist/a2a/signing.js.map +1 -0
  40. package/dist/a2a/tasks.d.ts +88 -0
  41. package/dist/a2a/tasks.d.ts.map +1 -0
  42. package/dist/a2a/tasks.js +170 -0
  43. package/dist/a2a/tasks.js.map +1 -0
  44. package/dist/a2a/wire.d.ts +267 -0
  45. package/dist/a2a/wire.d.ts.map +1 -0
  46. package/dist/a2a/wire.js +1202 -0
  47. package/dist/a2a/wire.js.map +1 -0
  48. package/dist/background-types.d.ts +76 -0
  49. package/dist/background-types.d.ts.map +1 -0
  50. package/dist/background-types.js +2 -0
  51. package/dist/background-types.js.map +1 -0
  52. package/dist/child.d.ts +25 -0
  53. package/dist/child.d.ts.map +1 -0
  54. package/dist/child.js +129 -0
  55. package/dist/child.js.map +1 -0
  56. package/dist/code-driver.d.ts +40 -0
  57. package/dist/code-driver.d.ts.map +1 -0
  58. package/dist/code-driver.js +2 -0
  59. package/dist/code-driver.js.map +1 -0
  60. package/dist/code-mode.d.ts +3 -0
  61. package/dist/code-mode.d.ts.map +1 -0
  62. package/dist/code-mode.js +2 -0
  63. package/dist/code-mode.js.map +1 -0
  64. package/dist/code-script.d.ts +3 -0
  65. package/dist/code-script.d.ts.map +1 -0
  66. package/dist/code-script.js +149 -0
  67. package/dist/code-script.js.map +1 -0
  68. package/dist/code.d.ts +75 -0
  69. package/dist/code.d.ts.map +1 -0
  70. package/dist/code.js +326 -0
  71. package/dist/code.js.map +1 -0
  72. package/dist/compaction.d.ts +15 -0
  73. package/dist/compaction.d.ts.map +1 -0
  74. package/dist/compaction.js +168 -0
  75. package/dist/compaction.js.map +1 -0
  76. package/dist/delegation.d.ts +85 -16
  77. package/dist/delegation.d.ts.map +1 -1
  78. package/dist/delegation.js +240 -106
  79. package/dist/delegation.js.map +1 -1
  80. package/dist/evals/driver.d.ts +10 -0
  81. package/dist/evals/driver.d.ts.map +1 -0
  82. package/dist/evals/driver.js +192 -0
  83. package/dist/evals/driver.js.map +1 -0
  84. package/dist/evals/journal.d.ts +26 -0
  85. package/dist/evals/journal.d.ts.map +1 -0
  86. package/dist/evals/journal.js +483 -0
  87. package/dist/evals/journal.js.map +1 -0
  88. package/dist/evals/judge.d.ts +31 -0
  89. package/dist/evals/judge.d.ts.map +1 -0
  90. package/dist/evals/judge.js +142 -0
  91. package/dist/evals/judge.js.map +1 -0
  92. package/dist/evals/report.d.ts +38 -0
  93. package/dist/evals/report.d.ts.map +1 -0
  94. package/dist/evals/report.js +241 -0
  95. package/dist/evals/report.js.map +1 -0
  96. package/dist/evals/runner.d.ts +24 -0
  97. package/dist/evals/runner.d.ts.map +1 -0
  98. package/dist/evals/runner.js +655 -0
  99. package/dist/evals/runner.js.map +1 -0
  100. package/dist/evals/scorers.d.ts +36 -0
  101. package/dist/evals/scorers.d.ts.map +1 -0
  102. package/dist/evals/scorers.js +259 -0
  103. package/dist/evals/scorers.js.map +1 -0
  104. package/dist/evals/simulation.d.ts +7 -0
  105. package/dist/evals/simulation.d.ts.map +1 -0
  106. package/dist/evals/simulation.js +38 -0
  107. package/dist/evals/simulation.js.map +1 -0
  108. package/dist/evals/testing.d.ts +36 -0
  109. package/dist/evals/testing.d.ts.map +1 -0
  110. package/dist/evals/testing.js +87 -0
  111. package/dist/evals/testing.js.map +1 -0
  112. package/dist/evals/trajectory.d.ts +11 -0
  113. package/dist/evals/trajectory.d.ts.map +1 -0
  114. package/dist/evals/trajectory.js +180 -0
  115. package/dist/evals/trajectory.js.map +1 -0
  116. package/dist/evals/types.d.ts +431 -0
  117. package/dist/evals/types.d.ts.map +1 -0
  118. package/dist/evals/types.js +4 -0
  119. package/dist/evals/types.js.map +1 -0
  120. package/dist/evals.d.ts +14 -0
  121. package/dist/evals.d.ts.map +1 -0
  122. package/dist/evals.js +9 -0
  123. package/dist/evals.js.map +1 -0
  124. package/dist/extensions.d.ts +33 -0
  125. package/dist/extensions.d.ts.map +1 -0
  126. package/dist/extensions.js +188 -0
  127. package/dist/extensions.js.map +1 -0
  128. package/dist/handoff.d.ts +58 -0
  129. package/dist/handoff.d.ts.map +1 -0
  130. package/dist/handoff.js +160 -0
  131. package/dist/handoff.js.map +1 -0
  132. package/dist/index.d.ts +14 -0
  133. package/dist/index.d.ts.map +1 -1
  134. package/dist/index.js +8 -0
  135. package/dist/index.js.map +1 -1
  136. package/dist/input.d.ts +42 -0
  137. package/dist/input.d.ts.map +1 -0
  138. package/dist/input.js +266 -0
  139. package/dist/input.js.map +1 -0
  140. package/dist/mcp.d.ts +77 -0
  141. package/dist/mcp.d.ts.map +1 -0
  142. package/dist/mcp.js +505 -0
  143. package/dist/mcp.js.map +1 -0
  144. package/dist/memory-store.d.ts +11 -0
  145. package/dist/memory-store.d.ts.map +1 -0
  146. package/dist/memory-store.js +272 -0
  147. package/dist/memory-store.js.map +1 -0
  148. package/dist/memory.d.ts +212 -0
  149. package/dist/memory.d.ts.map +1 -0
  150. package/dist/memory.js +613 -0
  151. package/dist/memory.js.map +1 -0
  152. package/dist/otel.d.ts +74 -0
  153. package/dist/otel.d.ts.map +1 -0
  154. package/dist/otel.js +427 -0
  155. package/dist/otel.js.map +1 -0
  156. package/dist/progress.d.ts +17 -0
  157. package/dist/progress.d.ts.map +1 -0
  158. package/dist/progress.js +193 -0
  159. package/dist/progress.js.map +1 -0
  160. package/dist/quickjs.d.ts +19 -0
  161. package/dist/quickjs.d.ts.map +1 -0
  162. package/dist/quickjs.js +519 -0
  163. package/dist/quickjs.js.map +1 -0
  164. package/dist/recovery.d.ts +10 -0
  165. package/dist/recovery.d.ts.map +1 -0
  166. package/dist/recovery.js +62 -0
  167. package/dist/recovery.js.map +1 -0
  168. package/dist/request.d.ts +88 -0
  169. package/dist/request.d.ts.map +1 -0
  170. package/dist/request.js +422 -0
  171. package/dist/request.js.map +1 -0
  172. package/dist/run.d.ts +16 -4
  173. package/dist/run.d.ts.map +1 -1
  174. package/dist/run.js +2016 -245
  175. package/dist/run.js.map +1 -1
  176. package/dist/runs.d.ts +77 -34
  177. package/dist/runs.d.ts.map +1 -1
  178. package/dist/runs.js +267 -85
  179. package/dist/runs.js.map +1 -1
  180. package/dist/schema-to-ts.d.ts +4 -0
  181. package/dist/schema-to-ts.d.ts.map +1 -0
  182. package/dist/schema-to-ts.js +191 -0
  183. package/dist/schema-to-ts.js.map +1 -0
  184. package/dist/session.d.ts +23 -0
  185. package/dist/session.d.ts.map +1 -0
  186. package/dist/session.js +137 -0
  187. package/dist/session.js.map +1 -0
  188. package/dist/snapshot.d.ts +57 -8
  189. package/dist/snapshot.d.ts.map +1 -1
  190. package/dist/snapshot.js +1206 -109
  191. package/dist/snapshot.js.map +1 -1
  192. package/dist/steering.d.ts +75 -0
  193. package/dist/steering.d.ts.map +1 -0
  194. package/dist/steering.js +214 -0
  195. package/dist/steering.js.map +1 -0
  196. package/dist/subagents.d.ts +141 -0
  197. package/dist/subagents.d.ts.map +1 -0
  198. package/dist/subagents.js +746 -0
  199. package/dist/subagents.js.map +1 -0
  200. package/dist/tool-retry.d.ts +12 -0
  201. package/dist/tool-retry.d.ts.map +1 -0
  202. package/dist/tool-retry.js +53 -0
  203. package/dist/tool-retry.js.map +1 -0
  204. package/dist/tree.d.ts +62 -6
  205. package/dist/tree.d.ts.map +1 -1
  206. package/dist/tree.js +192 -23
  207. package/dist/tree.js.map +1 -1
  208. package/dist/types.d.ts +767 -52
  209. package/dist/types.d.ts.map +1 -1
  210. package/dist/workflow-snapshot.d.ts +8 -0
  211. package/dist/workflow-snapshot.d.ts.map +1 -0
  212. package/dist/workflow-snapshot.js +276 -0
  213. package/dist/workflow-snapshot.js.map +1 -0
  214. package/dist/workflow-types.d.ts +171 -0
  215. package/dist/workflow-types.d.ts.map +1 -0
  216. package/dist/workflow-types.js +2 -0
  217. package/dist/workflow-types.js.map +1 -0
  218. package/dist/workflow.d.ts +19 -0
  219. package/dist/workflow.d.ts.map +1 -0
  220. package/dist/workflow.js +1053 -0
  221. package/dist/workflow.js.map +1 -0
  222. package/examples/a2a-remote.ts +85 -0
  223. package/examples/a2a-server.ts +100 -0
  224. package/examples/background.ts +18 -4
  225. package/examples/code-mode.ts +76 -0
  226. package/examples/conversation.ts +57 -0
  227. package/examples/evals.ts +79 -0
  228. package/examples/guardrails.ts +56 -0
  229. package/examples/handoff.ts +79 -0
  230. package/examples/memory.ts +44 -0
  231. package/examples/otel.ts +99 -0
  232. package/examples/steering.ts +69 -0
  233. package/examples/structured-handoff.ts +92 -0
  234. package/examples/subagents.ts +127 -0
  235. package/examples/workflow.ts +74 -0
  236. package/package.json +58 -6
  237. package/src/a2a/auth.ts +62 -0
  238. package/src/a2a/client.ts +733 -0
  239. package/src/a2a/index.ts +74 -0
  240. package/src/a2a/memory-runs.ts +448 -0
  241. package/src/a2a/policy.ts +148 -0
  242. package/src/a2a/push.ts +251 -0
  243. package/src/a2a/remote.ts +1652 -0
  244. package/src/a2a/server.ts +1390 -0
  245. package/src/a2a/signing.ts +348 -0
  246. package/src/a2a/tasks.ts +260 -0
  247. package/src/a2a/wire.ts +1443 -0
  248. package/src/background-types.ts +86 -0
  249. package/src/child.ts +181 -0
  250. package/src/code-driver.ts +48 -0
  251. package/src/code-mode.ts +12 -0
  252. package/src/code-script.ts +149 -0
  253. package/src/code.ts +424 -0
  254. package/src/compaction.ts +212 -0
  255. package/src/delegation.ts +444 -155
  256. package/src/evals/driver.ts +222 -0
  257. package/src/evals/journal.ts +605 -0
  258. package/src/evals/judge.ts +188 -0
  259. package/src/evals/report.ts +295 -0
  260. package/src/evals/runner.ts +826 -0
  261. package/src/evals/scorers.ts +339 -0
  262. package/src/evals/simulation.ts +46 -0
  263. package/src/evals/testing.ts +126 -0
  264. package/src/evals/trajectory.ts +223 -0
  265. package/src/evals/types.ts +463 -0
  266. package/src/evals.ts +72 -0
  267. package/src/extensions.ts +247 -0
  268. package/src/handoff.ts +214 -0
  269. package/src/index.ts +51 -0
  270. package/src/input.ts +319 -0
  271. package/src/mcp.ts +690 -0
  272. package/src/memory-store.ts +366 -0
  273. package/src/memory.ts +893 -0
  274. package/src/otel.ts +568 -0
  275. package/src/progress.ts +214 -0
  276. package/src/quickjs.ts +524 -0
  277. package/src/recovery.ts +90 -0
  278. package/src/request.ts +513 -0
  279. package/src/run.ts +2678 -313
  280. package/src/runs.ts +464 -133
  281. package/src/schema-to-ts.ts +194 -0
  282. package/src/session.ts +178 -0
  283. package/src/snapshot.ts +1595 -124
  284. package/src/steering.ts +329 -0
  285. package/src/subagents.ts +1084 -0
  286. package/src/tool-retry.ts +86 -0
  287. package/src/tree.ts +223 -27
  288. package/src/types.ts +711 -52
  289. package/src/workflow-snapshot.ts +366 -0
  290. package/src/workflow-types.ts +213 -0
  291. package/src/workflow.ts +1316 -0
@@ -1,40 +1,105 @@
1
+ import type { RemoteAgent, RemoteInput, RemoteOutcome } from "./a2a/remote.ts";
2
+ import type { Workflow, WorkflowOutcome } from "./workflow-types.ts";
3
+ import type { TreeNode } from "./types.ts";
1
4
  import { type JsonObjectSchema, type ToolDefinition } from "@providerkit/core";
5
+ import { RequestJournal } from "./request.ts";
6
+ import { type SubagentCreation, type SubagentRecord } from "./subagents.ts";
7
+ import { type Handoff } from "./handoff.ts";
2
8
  import { type ExecutionScope } from "./tree.ts";
3
- import type { Agent, ChildPathStep, DelegationExecution, RunOptions, RunOutcome, RunSnapshot, ToolResult } from "./types.ts";
9
+ import type { Agent, AgentConfig, AgentInput, AgentMessage, Answer, QuestionAsk, DelegationExecution, RunOptions, RunLimits, RunOutcome, RunSnapshot, ToolRequest, ToolResult, UserContent } from "./types.ts";
4
10
  /** Internal symbol holds no execution state. Every invocation receives its own scope. */
5
11
  export declare const AGENT_RUNTIME: unique symbol;
6
- export interface ApprovalEvidence {
7
- path: readonly ChildPathStep[];
8
- decision: unknown;
12
+ /** @internal Only the built-in helper coordinator receives this journaled admission path. */
13
+ export declare const SUBAGENT_CONTEXT: unique symbol;
14
+ /** @internal What a new run starts from, checked: the history before the new turn, the turn,
15
+ * and the session the history came from. */
16
+ export interface RunStart {
17
+ history: AgentMessage[];
18
+ input: UserContent;
19
+ session?: RunSnapshot["session"];
9
20
  }
21
+ export type Specialist = Agent<unknown> | Workflow<unknown, unknown> | RemoteAgent<unknown>;
22
+ export type NodeOutcome<T = unknown> = RunOutcome<T> | WorkflowOutcome<T> | RemoteOutcome<T>;
23
+ export interface NodeRuntime<R extends NodeOutcome = NodeOutcome> {
24
+ restore(raw: unknown, tree?: RunSnapshot["tree"], subagent?: SubagentRecord): TreeNode;
25
+ hydrate(snapshot: TreeNode): R;
26
+ answerRequests(snapshot: TreeNode, options: RunOptions, scope: ExecutionScope, answers: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<void>;
27
+ execute(snapshot: TreeNode, options: RunOptions, scope: ExecutionScope, answers?: Readonly<Record<string, unknown>>): Promise<R>;
28
+ }
29
+ export declare function runtimeOf<T>(node: Agent<T>): NodeRuntime<RunOutcome<T>>;
30
+ export declare function runtimeOf<T>(node: RemoteAgent<T>): NodeRuntime<RemoteOutcome<T>>;
31
+ export declare function runtimeOf<I, O>(node: Workflow<I, O>): NodeRuntime<WorkflowOutcome<O>>;
32
+ export declare function runtimeOf(node: Specialist): NodeRuntime;
10
33
  /** @internal */
11
34
  export interface AgentRuntime<T> {
12
- create(input: string, runId: string, tree?: RunSnapshot["tree"]): RunSnapshot;
13
- restore(raw: unknown, tree?: RunSnapshot["tree"]): RunSnapshot;
35
+ readonly node: NodeRuntime<RunOutcome<T>>;
36
+ readonly handoffs: readonly Handoff[];
37
+ readonly tools: NonNullable<AgentConfig["tools"]>;
38
+ readonly enabledTools: readonly string[] | undefined;
39
+ readonly limits: RunLimits;
40
+ /** JSON identity of host configuration. Callbacks need an agent version change. */
41
+ configuration(): Record<string, unknown>;
42
+ /** Recheck current selection without resolving or replacing recorded instructions. */
43
+ checkTools(snapshot: RunSnapshot, options: RunOptions): Promise<void>;
44
+ /** A new root run's snapshot: the input normalized, the session read once and the history
45
+ * prepared, repaired and frozen, before anything is saved. */
46
+ open(input: AgentInput, options: RunOptions, runId: string): Promise<RunSnapshot>;
47
+ /** The history repaired with this agent's tools and the inline bytes checked: the exact form
48
+ * a snapshot stores, so a saved child can be compared with a new request for its key. */
49
+ freeze(start: RunStart): RunStart;
50
+ /** Resolves the run definition once, then creates a snapshot from the repaired history. */
51
+ create(start: RunStart, runId: string, tree?: RunSnapshot["tree"], options?: RunOptions, subagent?: SubagentCreation): Promise<RunSnapshot>;
52
+ restore(raw: unknown, tree?: RunSnapshot["tree"], subagent?: SubagentRecord): RunSnapshot;
14
53
  hydrate(snapshot: RunSnapshot): RunOutcome<T>;
15
- execute(snapshot: RunSnapshot, options: RunOptions, scope: ExecutionScope, evidence?: ApprovalEvidence): Promise<RunOutcome<T>>;
54
+ answerRequests(snapshot: RunSnapshot, options: RunOptions, scope: ExecutionScope, answers: Readonly<Record<string, unknown>>, signal: AbortSignal): Promise<void>;
55
+ execute(snapshot: RunSnapshot, options: RunOptions, scope: ExecutionScope, answers?: Readonly<Record<string, unknown>>): Promise<RunOutcome<T>>;
16
56
  }
17
- export interface ChildHandle<T = unknown> {
57
+ export interface ChildHandle<T = unknown, R extends NodeOutcome<T> = RunOutcome<T>> {
18
58
  readonly key: string;
19
59
  readonly runId: string;
20
60
  /** A started child, not another provider call. Repeated joins reuse the same outcome. */
21
- join(): Promise<RunOutcome<T>>;
61
+ join(): Promise<R>;
22
62
  }
23
- export type Joined<H extends readonly ChildHandle<unknown>[]> = {
24
- [K in keyof H]: H[K] extends ChildHandle<infer T> ? RunOutcome<T> : never;
63
+ export type Joined<H extends readonly ChildHandle<unknown, NodeOutcome>[]> = {
64
+ [K in keyof H]: H[K] extends ChildHandle<unknown, infer R> ? R : never;
25
65
  };
26
66
  export interface DelegationContext {
27
- child<T>(key: string, agent: Agent<T>, input: string): ChildHandle<T>;
67
+ /** @internal Kept off the public barrel. Model-created helpers use the same child journal. */
68
+ readonly [SUBAGENT_CONTEXT]?: {
69
+ parent: RunSnapshot;
70
+ journal: DelegationExecution;
71
+ scope: ExecutionScope;
72
+ request: ToolRequest;
73
+ signal: AbortSignal;
74
+ recheck(agent: Agent<unknown>, snapshot: RunSnapshot): Promise<void>;
75
+ child<T>(key: string, agent: Agent<T>, input: AgentInput, subagent: SubagentCreation): ChildHandle<T>;
76
+ };
77
+ /** Pure coordination replays from its start. The saved answer is matched by key and checked
78
+ * by this pure validator, not by a saved JavaScript stack. A rejected form is asked again. */
79
+ ask<T>(question: Omit<QuestionAsk, "type">, validate: (answer: Answer) => T): Promise<T>;
80
+ /** `key` becomes part of the child's run id and of every operation id under it, which
81
+ * progress events carry and a display layer may send to a browser. Key by position or a
82
+ * fixed name ("topic-1"), never by the input. The input is checked like `run`'s, except
83
+ * that provider-owned fields are kept: coordinator code is trusted. A child never gets the
84
+ * parent's session. */
85
+ child<I, O>(key: string, workflow: Workflow<I, O>, input: I): ChildHandle<O, WorkflowOutcome<O>>;
86
+ child<T>(key: string, agent: Agent<T>, input: AgentInput): ChildHandle<T>;
87
+ child<T>(key: string, agent: RemoteAgent<T>, input: RemoteInput): ChildHandle<T, RemoteOutcome<T>>;
28
88
  /** Settles in caller order, not completion order. No child may outlive this barrier. */
29
- join<const H extends readonly ChildHandle<unknown>[]>(handles: H): Promise<Joined<H>>;
89
+ join<const H extends readonly ChildHandle<unknown, NodeOutcome>[]>(handles: H): Promise<Joined<H>>;
90
+ /** The parent's conversation before this tool call: no system prompt and no unfinished
91
+ * round. Frozen. A child sees none of it unless you forward it, for example
92
+ * `{ messages: [...context.conversation, { role: "user", content: task }] }`. */
93
+ readonly conversation: readonly AgentMessage[];
30
94
  }
31
95
  export interface DelegationSpec<I, O> {
32
96
  name: string;
33
97
  description: string;
34
98
  inputSchema: JsonObjectSchema;
99
+ needsApproval?: boolean;
35
100
  validate: (raw: unknown) => I;
36
101
  /** Fixed allow-list. Agents cannot add tools or specialists at runtime. */
37
- specialists: readonly Agent<unknown>[];
102
+ specialists: readonly Specialist[];
38
103
  /** Pure, deterministic coordination only: use child and join for work. This callback
39
104
  * can replay after interruption; do not put external effects or mutable host state here. */
40
105
  run: (input: I, context: DelegationContext) => Promise<O>;
@@ -44,12 +109,14 @@ export interface DelegationSpec<I, O> {
44
109
  export interface Delegation {
45
110
  readonly kind: "delegation";
46
111
  readonly name: string;
47
- readonly specialists: readonly Agent<unknown>[];
112
+ readonly needsApproval: boolean;
113
+ readonly specialists: readonly Specialist[];
48
114
  definition(): ToolDefinition;
49
115
  /** @internal Errors and suspensions must not go through Tool.invoke's error conversion. */
50
116
  execute(raw: unknown, context: DelegationContext): Promise<ToolResult>;
51
117
  }
52
118
  export interface SpecialistToolOptions<T> {
119
+ needsApproval?: boolean;
53
120
  name: string;
54
121
  description: string;
55
122
  /** Pure; may run again when replaying coordination. */
@@ -60,7 +127,9 @@ export declare function isDelegation(value: {
60
127
  }): value is Delegation;
61
128
  export declare function defineDelegation<I, O>(spec: DelegationSpec<I, O>): Delegation;
62
129
  export declare function specialistTool<T>(agent: Agent<T>, options: SpecialistToolOptions<T>): Delegation;
130
+ /** Known local failures are tool data. Authority and journal failures still stop the tree. */
131
+ export declare function specialistFailures(descriptor: Delegation): Delegation;
63
132
  /** The whole pure coordination barrier lends its parent's slot, not each join.
64
133
  * Overlapping joins therefore cannot reacquire a slot while another join still waits. */
65
- export declare function executeDelegation(descriptor: Delegation, journal: DelegationExecution, parent: RunSnapshot, raw: unknown, options: RunOptions, scope: ExecutionScope, signal: AbortSignal, active: () => void, evidence?: ApprovalEvidence): Promise<ToolResult>;
134
+ export declare function executeDelegation(descriptor: Delegation, journal: DelegationExecution, parent: RunSnapshot, raw: Record<string, unknown>, options: RunOptions, scope: ExecutionScope, signal: AbortSignal, active: () => void, requests: RequestJournal): Promise<ToolResult>;
66
135
  //# sourceMappingURL=delegation.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../src/delegation.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"delegation.d.ts","sourceRoot":"","sources":["../src/delegation.ts"],"names":[],"mappings":"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"}
@@ -1,8 +1,20 @@
1
1
  import { messageOf } from "@providerkit/core";
2
- import { checkChildProgress, checkTree, childRunId, copyData, equalData, immutableCopy, isId, isRecord, } from "./snapshot.js";
3
- import { fail, Halt, untilAbort } from "./tree.js";
2
+ import { admitChild, startChild, childOptions, prepareChild } from "./child.js";
3
+ import { RequestJournal } from "./request.js";
4
+ import { checkMemoryBinding } from "./memory.js";
5
+ import { isSubagentTool } from "./subagents.js";
6
+ import { successfulToolResult } from "./extensions.js";
7
+ import { handoffRef } from "./handoff.js";
8
+ import { conversationOf, inputOf } from "./input.js";
9
+ import { agentSnapshot, childRunId, copyData, equalData, immutableCopy, isId, isRecord, } from "./snapshot.js";
10
+ import { emitEvent, fail, Halt, isLocalStop, nodeId, untilAbort, } from "./tree.js";
4
11
  /** Internal symbol holds no execution state. Every invocation receives its own scope. */
5
12
  export const AGENT_RUNTIME = Symbol("agent-runtime");
13
+ /** @internal Only the built-in helper coordinator receives this journaled admission path. */
14
+ export const SUBAGENT_CONTEXT = Symbol("subagent-context");
15
+ export function runtimeOf(node) {
16
+ return node.kind === "agent" ? node[AGENT_RUNTIME].node : node[AGENT_RUNTIME];
17
+ }
6
18
  export function isDelegation(value) {
7
19
  return "kind" in value && value.kind === "delegation";
8
20
  }
@@ -28,6 +40,7 @@ export function defineDelegation(spec) {
28
40
  return Object.freeze({
29
41
  kind: "delegation",
30
42
  name: spec.name,
43
+ needsApproval: spec.needsApproval ?? false,
31
44
  specialists,
32
45
  definition: () => copyData(definition),
33
46
  async execute(raw, context) {
@@ -42,12 +55,12 @@ export function defineDelegation(spec) {
42
55
  const content = summarize ? summarize(output) : JSON.stringify(output);
43
56
  if (typeof content !== "string")
44
57
  throw new TypeError("A delegation summary must be text.");
45
- return { ok: true, content };
58
+ return successfulToolResult({ output, summary: content });
46
59
  },
47
60
  });
48
61
  }
49
62
  export function specialistTool(agent, options) {
50
- return defineDelegation({
63
+ const descriptor = defineDelegation({
51
64
  ...options,
52
65
  inputSchema: {
53
66
  type: "object",
@@ -73,105 +86,137 @@ export function specialistTool(agent, options) {
73
86
  return result.output;
74
87
  },
75
88
  });
89
+ return specialistFailures(descriptor);
90
+ }
91
+ /** Known local failures are tool data. Authority and journal failures still stop the tree. */
92
+ export function specialistFailures(descriptor) {
93
+ return Object.freeze({
94
+ ...descriptor,
95
+ async execute(raw, context) {
96
+ try {
97
+ return await descriptor.execute(raw, context);
98
+ }
99
+ catch (error) {
100
+ if (!(error instanceof Halt) || !isLocalStop(error.state))
101
+ throw error;
102
+ const reason = error.state.status === "limited"
103
+ ? `its ${error.state.limit === "steps" ? "step" : error.state.limit === "elapsedMs" ? "time" : error.state.limit === "outputTokens" ? "output" : error.state.limit === "toolCalls" ? "tool-call" : "model-turn"} limit`
104
+ : error.state.status === "failed" &&
105
+ ["memory_missing", "memory_unavailable"].includes(error.state.error.code)
106
+ ? "a problem reading saved notes"
107
+ : "a model or result failure";
108
+ return {
109
+ ok: false,
110
+ kind: "failed",
111
+ content: `The specialist could not finish because of ${reason}. Continue with the other results.`,
112
+ };
113
+ }
114
+ },
115
+ });
76
116
  }
77
117
  /** The whole pure coordination barrier lends its parent's slot, not each join.
78
118
  * Overlapping joins therefore cannot reacquire a slot while another join still waits. */
79
- export async function executeDelegation(descriptor, journal, parent, raw, options, scope, signal, active, evidence) {
119
+ export async function executeDelegation(descriptor, journal, parent, raw, options, scope, signal, active, requests) {
80
120
  let open = true;
81
121
  const started = new Map();
122
+ const requested = new Map();
123
+ // Resolve new child definitions in admission order, without delaying children already
124
+ // running. No half-resolved definition can appear in another child's root checkpoint.
125
+ let admissions = Promise.resolve();
82
126
  const handles = new WeakSet();
83
- function child(key, agent, input) {
127
+ // Computed again on a replay from the same settled rounds, so a coordinator that forwards it
128
+ // asks for the same child input and reuses the saved child.
129
+ const conversation = immutableCopy(conversationOf(parent));
130
+ const inherited = childOptions(options);
131
+ async function recheck(agent, snapshot) {
132
+ if (!options.host?.beforeTool)
133
+ fail("subagent_authority_missing", "Supply host.beforeTool to authorize helper forks and follow-ups.");
134
+ await agent[AGENT_RUNTIME].checkTools(snapshot, { ...inherited, signal });
135
+ checkMemoryBinding(snapshot, inherited.memory);
136
+ if (inherited.memory) {
137
+ const { store, scope, shared = [] } = inherited.memory;
138
+ try {
139
+ for (const access of [...(scope ? [scope] : []), ...shared]) {
140
+ const current = await untilAbort(store.access(immutableCopy(access.scope), { signal }), signal);
141
+ if (!equalData(current, access))
142
+ throw new Error("Changed memory access");
143
+ }
144
+ }
145
+ catch {
146
+ signal.throwIfAborted();
147
+ fail("subagent_memory_changed", "The helper's memory access changed or could not be checked. Obtain fresh host authorization before starting new work.");
148
+ }
149
+ }
150
+ await requests.recheck({ ...requests.call, arguments: raw });
151
+ await requests.assertFresh();
152
+ active();
153
+ }
154
+ function child(key, agent, input, subagent) {
84
155
  if (!open)
85
156
  throw new Error("This delegation has ended; start children only inside its coordinator.");
86
157
  active();
87
- if (!isId(key) || !isId(input))
88
- throw new TypeError("A child needs a non-empty key and text input.");
158
+ if (!isId(key))
159
+ throw new TypeError("A child needs a non-empty key.");
89
160
  if (!descriptor.specialists.includes(agent))
90
- fail("unregistered_specialist", "Register this specialist in the delegation before starting it.", journal.operationId);
91
- const runtime = agent[AGENT_RUNTIME];
161
+ fail("unregistered_specialist", "Register this specialist before starting it.", journal.operationId);
162
+ const runtime = runtimeOf(agent);
163
+ const prepared = prepareChild(agent, input, subagent, scope.tree.root);
164
+ const start = prepared.input;
165
+ const identity = { agentId: agent.id, version: agent.version, start, subagent };
166
+ const prior = requested.get(key);
167
+ if (prior && !equalData(prior, identity))
168
+ fail("child_key_conflict", "This child key belongs to another definition or input.", journal.operationId);
169
+ requested.set(key, identity);
170
+ const runId = childRunId(journal.operationId, key);
92
171
  let entry = journal.children.find((saved) => saved.key === key);
93
172
  const resume = entry !== undefined;
94
173
  if (entry) {
95
- if (entry.snapshot.agentId !== agent.id ||
96
- entry.snapshot.version !== agent.version ||
97
- entry.snapshot.input !== input)
98
- fail("child_key_conflict", "This child key already belongs to another agent, version or input.", journal.operationId);
99
- }
100
- else {
101
- scope.tree.reserveChild(scope.depth + 1);
102
- entry = {
103
- key,
104
- snapshot: runtime.create(input, childRunId(journal.operationId, key), parent.tree),
105
- };
106
- journal.children.push(entry);
174
+ const saved = entry.snapshot;
175
+ const savedStart = saved.kind === "agent" ? { history: saved.history, input: saved.input } : saved.input;
176
+ if (saved.kind !== agent.kind ||
177
+ nodeId(saved) !== agent.id ||
178
+ saved.version !== agent.version ||
179
+ !equalData(savedStart, start) ||
180
+ !equalData(saved.kind === "agent" && saved.subagent
181
+ ? { ...saved.subagent, base: undefined }
182
+ : undefined, subagent?.record))
183
+ fail("child_key_conflict", "This child key belongs to another definition or input.", journal.operationId);
107
184
  }
108
- const saved = entry;
109
185
  if (!started.has(key)) {
186
+ let admitted;
187
+ if (entry)
188
+ admitted = Promise.resolve(entry);
189
+ else {
190
+ scope.tree.reserveChild(scope.depth + 1);
191
+ admitted = admissions.then(async () => {
192
+ const snapshot = await prepared.create(runId, parent.tree, { ...inherited, signal });
193
+ active();
194
+ entry = admitChild(journal.children, { key, snapshot }, scope);
195
+ return entry;
196
+ });
197
+ admissions = admitted.then(() => { }, () => { });
198
+ }
110
199
  const work = async () => {
111
- if (saved.snapshot.state.status !== "running" &&
112
- saved.snapshot.state.status !== "suspended")
113
- return;
114
- await scope.tree.save();
115
- active();
116
- const step = { operationId: journal.operationId, key, runId: saved.snapshot.runId };
117
- const childEvidence = evidence && equalData(evidence.path[0], step)
118
- ? { path: evidence.path.slice(1), decision: evidence.decision }
119
- : undefined;
120
- let execution;
121
- let hookOpen = true;
122
- let executionSettled = false;
123
- const execute = () => {
124
- if (!hookOpen || execution)
125
- throw new Error("A host child may execute once, before its hook returns.");
126
- execution = (async () => {
127
- if (resume)
128
- saved.snapshot.attemptId = crypto.randomUUID();
129
- const result = await runtime.execute(saved.snapshot, { ...options, signal }, { tree: scope.tree, depth: scope.depth + 1 }, childEvidence);
130
- executionSettled = true;
131
- return { snapshot: result.snapshot };
132
- })();
133
- // A hook that throws or forgets to await cannot leave an unhandled child promise.
134
- void execution.catch(() => { });
135
- return execution;
136
- };
137
- let envelope;
138
- try {
139
- envelope = options.host?.child
140
- ? await untilAbort(Promise.resolve(options.host.child(immutableCopy({
141
- ...saved,
142
- parentRunId: parent.runId,
200
+ const saved = await admitted;
201
+ await startChild(saved, parent, journal.operationId, runtime, inherited, scope, signal, active, resume, async () => {
202
+ if (agent.kind === "agent" &&
203
+ saved.snapshot.kind === "agent" &&
204
+ (saved.snapshot.subagent?.fork || saved.snapshot.subagent?.previousRunId))
205
+ await recheck(agent, saved.snapshot);
206
+ if (journal.kind === "handoff")
207
+ emitEvent(options, {
208
+ type: "handoff",
209
+ runId: parent.runId,
210
+ attemptId: parent.attemptId,
143
211
  operationId: journal.operationId,
144
- resume,
145
- }), execute)), signal)
146
- : await execute();
147
- if (execution && !executionSettled)
148
- fail("invalid_child_host", "The child hook returned before its execution settled.", journal.operationId);
149
- }
150
- finally {
151
- hookOpen = false;
152
- if (execution)
153
- await execution;
154
- }
155
- if (!isRecord(envelope) || (envelope.reference !== undefined && !isId(envelope.reference)))
156
- fail("invalid_child_host", "The child hook must return a snapshot envelope.", journal.operationId);
157
- const restored = runtime.restore(envelope.snapshot, parent.tree);
158
- checkChildProgress(saved.snapshot, restored);
159
- if (restored.state.status === "running")
160
- fail("invalid_child_host", "The child hook returned an unfinished child.", journal.operationId);
161
- // Returning a cached suspended host segment cannot consume an SDK approval.
162
- if (!execution && childEvidence && restored.state.status === "suspended")
163
- fail("host_resume_unsupported", "The host returned a cached suspension. Resume this child in a new or resumable host segment.", journal.operationId);
164
- const previous = saved.snapshot;
165
- saved.snapshot = restored;
166
- try {
167
- checkTree(scope.tree.root);
168
- }
169
- catch (error) {
170
- saved.snapshot = previous;
171
- throw error;
172
- }
173
- saved.reference = envelope.reference ?? saved.reference;
174
- await scope.tree.save();
212
+ childRunId: saved.snapshot.runId,
213
+ from: handoffRef(parent),
214
+ to: journal.target,
215
+ ...(journal.note !== undefined ? { note: journal.note } : {}),
216
+ });
217
+ }, journal.kind === "handoff"
218
+ ? (parent.inputs.at(-1)?.content ?? scope.handoffInput ?? parent.input)
219
+ : undefined);
175
220
  };
176
221
  const promise = work().catch(async (error) => {
177
222
  let failure = error;
@@ -181,8 +226,8 @@ export async function executeDelegation(descriptor, journal, parent, raw, option
181
226
  catch (stopped) {
182
227
  failure = stopped;
183
228
  }
184
- if (saved.snapshot.state.status === "running") {
185
- saved.snapshot.state =
229
+ if (entry?.snapshot.state.status === "running") {
230
+ entry.snapshot.state =
186
231
  failure instanceof Halt
187
232
  ? failure.state
188
233
  : {
@@ -199,9 +244,12 @@ export async function executeDelegation(descriptor, journal, parent, raw, option
199
244
  const pending = started.get(key);
200
245
  const handle = Object.freeze({
201
246
  key,
202
- runId: saved.snapshot.runId,
247
+ runId,
203
248
  async join() {
204
249
  await pending;
250
+ const saved = journal.children.find((child) => child.key === key);
251
+ if (!saved)
252
+ throw new Error("The child ended before its definition resolved.");
205
253
  return runtime.hydrate(saved.snapshot);
206
254
  },
207
255
  });
@@ -213,10 +261,64 @@ export async function executeDelegation(descriptor, journal, parent, raw, option
213
261
  throw new TypeError("Join only handles created by this delegation context.");
214
262
  return Promise.all(items.map((handle) => handle.join()));
215
263
  }
264
+ // Adapted from LangGraph.js (MIT), interrupt.ts: return a saved answer on replay.
265
+ // Keys replace positional matching; validation stays with the trusted coordinator.
266
+ let asks = Promise.resolve();
267
+ const asking = [];
268
+ function ask(question, validate) {
269
+ if (!open)
270
+ throw new Error("Ask only inside the active coordinator.");
271
+ const work = asks.then(async () => {
272
+ active();
273
+ const record = await requests.ensure({ ...question, type: "question" });
274
+ if (!record.decision)
275
+ throw new Halt({ status: "suspended" });
276
+ if (record.decision.type === "stop") {
277
+ scope.tree.stop();
278
+ throw new Halt({ status: "cancelled" });
279
+ }
280
+ if (record.decision.type === "cancel")
281
+ throw new CancelledQuestion();
282
+ if (record.decision.type !== "answer")
283
+ throw new TypeError("This question needs an answer.");
284
+ await requests.recheck({ ...requests.call, arguments: raw });
285
+ active();
286
+ try {
287
+ return validate(immutableCopy(record.decision.answer));
288
+ }
289
+ catch (error) {
290
+ record.closed = "invalid";
291
+ await requests.open({ ...question, type: "question" }, { code: "invalid_answer", message: messageOf(error) });
292
+ throw new Halt({ status: "suspended" });
293
+ }
294
+ });
295
+ asks = work.then(() => { }, () => { });
296
+ asking.push(work);
297
+ void work.catch(() => { });
298
+ return work;
299
+ }
216
300
  let result;
217
301
  let failure;
218
302
  try {
219
- result = await untilAbort(descriptor.execute(raw, Object.freeze({ child, join })), signal);
303
+ result = await untilAbort(descriptor.execute(raw, Object.freeze({
304
+ child,
305
+ join,
306
+ ask,
307
+ conversation,
308
+ ...(isSubagentTool(descriptor)
309
+ ? {
310
+ [SUBAGENT_CONTEXT]: {
311
+ parent,
312
+ journal,
313
+ scope,
314
+ request: { ...requests.call, arguments: raw },
315
+ signal,
316
+ recheck,
317
+ child,
318
+ },
319
+ }
320
+ : {}),
321
+ })), signal);
220
322
  }
221
323
  catch (error) {
222
324
  failure = { error };
@@ -228,40 +330,72 @@ export async function executeDelegation(descriptor, journal, parent, raw, option
228
330
  for (const entry of journal.children) {
229
331
  if (started.has(entry.key))
230
332
  continue;
231
- const agent = descriptor.specialists.find((agent) => agent.id === entry.snapshot.agentId && agent.version === entry.snapshot.version);
333
+ const agent = descriptor.specialists.find((agent) => agent.kind === entry.snapshot.kind &&
334
+ agent.id === nodeId(entry.snapshot) &&
335
+ agent.version === entry.snapshot.version);
232
336
  if (!agent)
233
337
  fail("unregistered_specialist", "The saved child is not a registered specialist.");
234
- child(entry.key, agent, entry.snapshot.input);
338
+ // A rejected helper definition must not resume saved work through this fallback.
339
+ // Already started children still settle below, as for every delegation.
340
+ if (failure && entry.snapshot.kind === "agent" && entry.snapshot.subagent)
341
+ continue;
342
+ if (entry.snapshot.kind === "agent" && entry.snapshot.subagent && agent.kind === "agent") {
343
+ const { base, ...record } = entry.snapshot.subagent;
344
+ child(entry.key, agent, inputOf(entry.snapshot), {
345
+ record,
346
+ ...(record.previousRunId
347
+ ? { source: base }
348
+ : record.policy.self
349
+ ? { source: parent.definition }
350
+ : {}),
351
+ });
352
+ }
353
+ else if (agent.kind === "agent")
354
+ child(entry.key, agent, inputOf(agentSnapshot(entry.snapshot)));
355
+ else if (agent.kind === "remote" && entry.snapshot.kind === "remote")
356
+ child(entry.key, agent, entry.snapshot.input);
357
+ else if (agent.kind === "workflow")
358
+ child(entry.key, agent, entry.snapshot.input);
235
359
  }
236
360
  }
237
361
  catch (error) {
238
362
  failure ??= { error };
239
363
  }
240
364
  open = false;
241
- const settled = await Promise.allSettled(started.values());
242
- const rejected = settled.find((item) => item.status === "rejected");
365
+ const settled = await Promise.allSettled([...started.values(), ...asking]);
366
+ const rejected = settled.find((item) => item.status === "rejected" &&
367
+ !(item.reason instanceof Halt && item.reason.state.status === "suspended")) ?? settled.find((item) => item.status === "rejected");
243
368
  if (rejected?.status === "rejected")
244
369
  failure = { error: rejected.reason };
245
370
  }
246
371
  active();
372
+ // A coordinator may inspect or ignore outcomes, but cannot waive cancellation, tree limits
373
+ // or broken host/journal contracts. All admitted children have settled at this point.
374
+ for (const { snapshot } of journal.children) {
375
+ const state = snapshot.state;
376
+ if (state.status === "cancelled")
377
+ scope.tree.stop();
378
+ if ((state.status === "cancelled" || state.status === "limited" || state.status === "failed") &&
379
+ !isLocalStop(state))
380
+ throw new Halt(state);
381
+ }
382
+ if (failure?.error instanceof CancelledQuestion)
383
+ return {
384
+ ok: false,
385
+ kind: "cancelled",
386
+ content: "The person cancelled this question. Continue without this action.",
387
+ };
247
388
  if (failure && !(failure.error instanceof Halt && failure.error.state.status === "suspended"))
248
389
  throw failure.error;
249
- for (const entry of journal.children) {
250
- const state = entry.snapshot.state;
251
- if (state.status === "suspended") {
252
- throw new Halt({
253
- ...state,
254
- path: [
255
- { operationId: journal.operationId, key: entry.key, runId: entry.snapshot.runId },
256
- ...state.path,
257
- ],
258
- });
259
- }
260
- }
390
+ if (journal.children.some((entry) => entry.snapshot.state.status === "suspended") ||
391
+ requests.execution.asks?.some((record) => !record.closed && !record.decision))
392
+ throw new Halt({ status: "suspended" });
261
393
  if (failure)
262
394
  throw failure.error;
263
395
  if (!result)
264
396
  throw new Error("The delegation ended without a result.");
265
397
  return result;
266
398
  }
399
+ class CancelledQuestion extends Error {
400
+ }
267
401
  //# sourceMappingURL=delegation.js.map