@theokit/sdk 2.22.0 → 2.23.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 2.23.0
+
+### Minor Changes
+
+- 271f6e4: **SE13 — `modifiedMaxSteps` on `onDelegationStart` (cap the subagent's iterations).**
+
+  `DelegationStartDecision` (from `@theokit/sdk/a2a`) gains `modifiedMaxSteps?: number`. When an `onDelegationStart` hook returns it (and does not reject), `defineSubAgent` forwards it as `SendOptions.maxIterations` to the child `agent.send`, capping how many tool-loop rounds the subagent may run. Composes with SE10 (`signal`) and SE12 (`messageFilter` preamble) onto a single child `send`. Absent ⇒ the child uses its default iteration ceiling (unchanged).
+
+  Completes the SE11 `onDelegationStart` decision contract (the deferred `modifiedMaxSteps` — the `SendOptions.maxIterations` plumbing already existed). Additive + backward-compatible. From the Mastra supervisor-agents comparison (SDK Evolution roadmap SE13).
+
+- b51dc6a: **SE14 — subagent result-context control (`SubAgentSpec.includeToolResults`).**
+
+  `defineSubAgent()` (from `@theokit/sdk/a2a`) gains an opt-in `includeToolResults`. When `true`, the child's completed tool-call results (name + result) are appended to the delegation payload returned to the supervisor, inside a delimited `<subagent-tool-results>` block; when absent/`false` the delegation returns the child's final text only — **text-only stays the default** (Mastra's scoped posture).
+
+  Implemented as a `run.stream()` replay after `run.wait()` (a proven, safe idiom — the run buffers events and `stream()` replays them) collecting `tool_call` events with `status: "completed"`. **No `RunResult` change** — reads the existing public stream surface; tool _args_ are never surfaced (only completed results). Rationale + the `RunResult`-field alternative are recorded in ADR 0006.
+
+  Additive + backward-compatible (default `false` never touches the stream). From the Mastra supervisor-agents comparison (SDK Evolution roadmap SE14).
+
+- 30e02d9: **SE15 — `iteration` count on the delegation-hook context (reject-after-N).**
+
+  `DelegationStartContext` and `DelegationCompleteContext` (from `@theokit/sdk/a2a`) gain `iteration: number` — a 1-based per-`defineSubAgent`-instance invocation counter, incremented before `onDelegationStart` runs (a rejected delegation still counts). This enables the Mastra reject-after-N-iterations pattern: `onDelegationStart: (ctx) => ctx.iteration > 8 ? { proceed: false, rejectionReason } : { proceed: true }`. `onDelegationComplete` sees the same iteration its `onDelegationStart` did.
+
+  Also fixes a delegation-hook DX regression: `onDelegationStart` / `onDelegationComplete` now accept a **side-effect-only (void-returning) callback** (e.g. `(ctx) => { log(ctx) }`) — the common case, mirroring Mastra's `async ctx => { … }` hooks — via a shared `DelegationHookResult<T>` return type. Additive + backward-compatible. From the Mastra supervisor-agents comparison (SDK Evolution roadmap SE15).
+
 ## 2.22.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -18426,15 +18426,33 @@ var MaxDelegationDepthError = class extends Error {
   maxDepth;
   code = "max_delegation_depth";
 };
-async function applyDelegationStart(spec, input) {
+async function applyDelegationStart(spec, input, iteration) {
   if (spec.onDelegationStart === void 0) return { input };
-  const decision = await spec.onDelegationStart({ input, name: spec.name });
+  const decision = await spec.onDelegationStart({ input, name: spec.name, iteration });
   if (decision === void 0) return { input };
   if (decision.proceed === false)
     return { reject: decision.rejectionReason ?? "(delegation rejected)" };
-  return { input: decision.modifiedInput ?? input };
+  return {
+    input: decision.modifiedInput ?? input,
+    ...decision.modifiedMaxSteps !== void 0 ? { maxSteps: decision.modifiedMaxSteps } : {}
+  };
+}
+async function collectChildToolResults(run) {
+  const lines = [];
+  for await (const event of run.stream()) {
+    if (event.type === "tool_call" && event.status === "completed") {
+      const rendered = typeof event.result === "string" ? event.result : JSON.stringify(event.result ?? null);
+      lines.push(`${event.name}: ${rendered}`);
+    }
+  }
+  if (lines.length === 0) return "";
+  return `
+
+<subagent-tool-results>
+${lines.join("\n")}
+</subagent-tool-results>`;
 }
-async function runChildAgent(spec, input, signal) {
+async function runChildAgent(spec, input, signal, maxSteps) {
   const { Agent: Agent2 } = await Promise.resolve().then(() => (init_agent(), agent_exports));
   const agent = await Agent2.create({
     ...spec.model ? { model: { id: spec.model } } : {},
@@ -18442,17 +18460,22 @@ async function runChildAgent(spec, input, signal) {
     tools: spec.tools ?? []
   });
   try {
-    const run = signal !== void 0 ? await agent.send(input, { signal }) : await agent.send(input);
+    const sendOptions = {
+      ...signal !== void 0 ? { signal } : {},
+      ...maxSteps !== void 0 ? { maxIterations: maxSteps } : {}
+    };
+    const run = Object.keys(sendOptions).length > 0 ? await agent.send(input, sendOptions) : await agent.send(input);
     const result = await run.wait();
-    return result.result ?? "(no response)";
+    const text = result.result ?? "(no response)";
+    return spec.includeToolResults === true ? text + await collectChildToolResults(run) : text;
   } finally {
     agent.dispose();
   }
 }
-async function notifyDelegationError(spec, input, error) {
+async function notifyDelegationError(spec, input, error, iteration) {
   if (spec.onDelegationComplete === void 0) return;
   try {
-    await spec.onDelegationComplete({ input, name: spec.name, error });
+    await spec.onDelegationComplete({ input, name: spec.name, error, iteration });
   } catch {
   }
 }
@@ -18467,9 +18490,9 @@ ${preamble}
 Task:
 ${input}`;
 }
-async function applyDelegationComplete(spec, input, result) {
+async function applyDelegationComplete(spec, input, result, iteration) {
   if (spec.onDelegationComplete === void 0) return result;
-  const completion = await spec.onDelegationComplete({ input, name: spec.name, result });
+  const completion = await spec.onDelegationComplete({ input, name: spec.name, result, iteration });
   return completion?.feedback !== void 0 ? result + completion.feedback : result;
 }
 function defineSubAgent(spec, _parentDepth = 0) {
@@ -18481,23 +18504,26 @@ function defineSubAgent(spec, _parentDepth = 0) {
   const inputSchema = zod.z.object({
     input: zod.z.string().describe("Task for the subagent")
   });
+  let iteration = 0;
   return {
     name: spec.name,
     description: spec.description,
     inputSchema,
     handler: async (rawInput, ctx) => {
       const { input: parsed } = inputSchema.parse(rawInput);
-      const start = await applyDelegationStart(spec, parsed);
+      iteration += 1;
+      const capturedIteration = iteration;
+      const start = await applyDelegationStart(spec, parsed, capturedIteration);
       if ("reject" in start) return start.reject;
       const input = applyMessageFilter(spec, start.input, ctx?.messages);
       let result;
       try {
-        result = await runChildAgent(spec, input, ctx?.signal);
+        result = await runChildAgent(spec, input, ctx?.signal, start.maxSteps);
       } catch (error) {
-        await notifyDelegationError(spec, input, error);
+        await notifyDelegationError(spec, input, error, capturedIteration);
         throw error;
       }
-      return applyDelegationComplete(spec, input, result);
+      return applyDelegationComplete(spec, input, result, capturedIteration);
     }
   };
 }