@theokit/sdk 2.21.0 → 2.23.0

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # 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
+
+- 12cb30d: **SE10 — subagent delegation forwards the parent's `AbortSignal` (cancellation propagation).**
+
+  `defineSubAgent()` (from `@theokit/sdk/a2a`) now threads the run's cancellation into the child agent. When the agent loop dispatches the subagent tool it already passes the run's `AbortSignal` as the handler's `ctx.signal`; the subagent handler now forwards that signal to the child `agent.send(input, { signal })`. Aborting the parent run cancels the in-flight subagent at its next step instead of letting it run to completion (and burn tokens).
+
+  - Additive + backward-compatible: a handler invoked with no `ctx` (single-arg call sites) behaves exactly as before — no signal, no cancellation.
+  - The child agent is still disposed in `finally`, including on cancel.
+
+  Matches the Mastra supervisor-agents "abortSignal forwarded to delegated subagents" behavior (SDK Evolution roadmap SE10).
+
+- 8e3249d: **SE11 — delegation lifecycle hooks on `defineSubAgent` (`onDelegationStart` / `onDelegationComplete`).**
+
+  `SubAgentSpec` (from `@theokit/sdk/a2a`) gains two optional hooks that let the caller intercept a delegation as it happens:
+
+  - `onDelegationStart({ input, name })` — return `{ proceed: false, rejectionReason }` to reject the delegation (the child never runs; `rejectionReason` becomes the tool result), or `{ modifiedInput }` to rewrite the prompt sent to the child.
+  - `onDelegationComplete({ input, name, result?, error? })` — runs after the delegation settles; on success an optional `{ feedback }` is appended to the child's result, and on failure `ctx.error` is set (the error is still re-thrown — never swallowed, Unbreakable Rule 8).
+
+  Additive + backward-compatible: specs without hooks behave exactly as before. New exported types: `DelegationStartContext`, `DelegationStartDecision`, `DelegationCompleteContext`, `DelegationCompleteDecision`.
+
+  Matches the Mastra supervisor `onDelegationStart` / `onDelegationComplete` control points (SDK Evolution roadmap SE11).
+
+- d2d0d16: **SE12 — opt-in parent-context forwarding for subagents (`messageFilter`).**
+
+  `SubAgentSpec` (from `@theokit/sdk/a2a`) gains an optional `messageFilter`. When set, `defineSubAgent` forwards a filtered view of the supervisor's conversation to the child; when absent, the child runs input-only — **memory isolation stays the default**.
+
+  - New `ctx.messages` on the custom-tool handler `ToolContext`: a **read-only, text-only** projection of the current turn's transcript (`ToolContextMessage[]`), threaded by the agent loop the same way `ctx.signal` (#65) and `ctx.context` (M7) are. Non-text parts (tool calls / results) are dropped — a tool never sees raw wire parts or nested tool args.
+  - `messageFilter({ messages, input, name })` returns the subset to forward; `defineSubAgent` prepends it to the delegated input as a role-tagged context preamble. A filter returning `[]` forwards nothing. A filter that drops sensitive turns (e.g. anything `confidential`) provably keeps them out of the child context.
+
+  New exported types: `ToolContextMessage`, `MessageFilterArgs`. Additive + backward-compatible. Rationale + the transcript-exposure trade-off are recorded in ADR 0005. From the Mastra supervisor-agents comparison (SDK Evolution roadmap SE12).
+
 ## 2.21.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -8326,21 +8326,21 @@ async function executeTool(inputs, resolved, call) {
   if (resolved.origin === "shell") return runShellTool(inputs, call);
   if (resolved.origin === "memory") return runMemoryTool(resolved, call, inputs.context);
   if (resolved.origin === "custom")
-    return runCustomTool(resolved, call, inputs.signal, inputs.context);
+    return runCustomTool(resolved, call, inputs.signal, inputs.context, inputs.messages);
   return runMcpTool(inputs, resolved, call);
 }
 async function runMemoryTool(resolved, call, context) {
   return runHandlerTool("memory", resolved.memoryHandler, call, void 0, context);
 }
-async function runCustomTool(resolved, call, signal, context) {
-  return runHandlerTool("custom", resolved.customHandler, call, signal, context);
+async function runCustomTool(resolved, call, signal, context, messages) {
+  return runHandlerTool("custom", resolved.customHandler, call, signal, context, messages);
 }
-async function runHandlerTool(kind, handler, call, signal, context) {
+async function runHandlerTool(kind, handler, call, signal, context, messages) {
   if (handler === void 0) {
     return { stdout: "", stderr: `${kind} tool ${call.name} has no handler`, exitCode: 127 };
   }
   try {
-    const out = await handler(call.input, { signal, context });
+    const out = await handler(call.input, { signal, context, messages });
     if (typeof out !== "string") return { stdout: "", stderr: "", exitCode: 0, content: out };
     return { stdout: out, stderr: "", exitCode: 0 };
   } catch (cause) {
@@ -9165,6 +9165,14 @@ var init_usage_and_cost = __esm({
 });
 
 // src/internal/agent-loop/loop.ts
+function projectToolContextMessages(messages) {
+  const projected = [];
+  for (const m of messages) {
+    const content = m.content.flatMap((p) => p.type === "text" ? [p.text] : []).join("");
+    if (content !== "") projected.push({ role: m.role, content });
+  }
+  return projected;
+}
 async function runAgentLoop(inputs) {
   const sendSpan = inputs.telemetry?.startSpan("agent.send", {
     agentId: inputs.agentId,
@@ -9405,7 +9413,9 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
   const outText = await transformLlmOutputText(inputs, llmOutput.text, tCtx);
   ctx.messages.push(buildAssistantTurn(outText, llmOutput.toolCalls));
   const rawResults = await dispatchTools(
-    inputs,
+    // SE12 — forward a read-only text projection of the transcript-so-far to tool
+    // handlers via `ctx.messages` (consumed by defineSubAgent's messageFilter).
+    { ...inputs, messages: projectToolContextMessages(ctx.messages) },
     ctx.tools,
     llmOutput.toolCalls,
     ctx.events,
@@ -18416,6 +18426,75 @@ var MaxDelegationDepthError = class extends Error {
   maxDepth;
   code = "max_delegation_depth";
 };
+async function applyDelegationStart(spec, input, iteration) {
+  if (spec.onDelegationStart === void 0) return { input };
+  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,
+    ...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, maxSteps) {
+  const { Agent: Agent2 } = await Promise.resolve().then(() => (init_agent(), agent_exports));
+  const agent = await Agent2.create({
+    ...spec.model ? { model: { id: spec.model } } : {},
+    systemPrompt: spec.instructions,
+    tools: spec.tools ?? []
+  });
+  try {
+    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();
+    const text = result.result ?? "(no response)";
+    return spec.includeToolResults === true ? text + await collectChildToolResults(run) : text;
+  } finally {
+    agent.dispose();
+  }
+}
+async function notifyDelegationError(spec, input, error, iteration) {
+  if (spec.onDelegationComplete === void 0) return;
+  try {
+    await spec.onDelegationComplete({ input, name: spec.name, error, iteration });
+  } catch {
+  }
+}
+function applyMessageFilter(spec, input, messages) {
+  if (spec.messageFilter === void 0 || messages === void 0) return input;
+  const filtered = spec.messageFilter({ messages, input, name: spec.name });
+  if (filtered.length === 0) return input;
+  const preamble = filtered.map((m) => `${m.role}: ${m.content}`).join("\n");
+  return `Prior conversation:
+${preamble}
+
+Task:
+${input}`;
+}
+async function applyDelegationComplete(spec, input, result, iteration) {
+  if (spec.onDelegationComplete === void 0) return 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) {
   const currentDepth = _parentDepth + 1;
   const maxDepth = spec.maxDelegationDepth ?? 3;
@@ -18425,25 +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) => {
-      const { input } = inputSchema.parse(rawInput);
-      const { Agent: Agent2 } = await Promise.resolve().then(() => (init_agent(), agent_exports));
-      const agent = await Agent2.create({
-        ...spec.model ? { model: { id: spec.model } } : {},
-        systemPrompt: spec.instructions,
-        tools: spec.tools ?? []
-      });
+    handler: async (rawInput, ctx) => {
+      const { input: parsed } = inputSchema.parse(rawInput);
+      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 {
-        const run = await agent.send(input);
-        const result = await run.wait();
-        return result.result ?? "(no response)";
-      } finally {
-        agent.dispose();
+        result = await runChildAgent(spec, input, ctx?.signal, start.maxSteps);
+      } catch (error) {
+        await notifyDelegationError(spec, input, error, capturedIteration);
+        throw error;
       }
+      return applyDelegationComplete(spec, input, result, capturedIteration);
     }
   };
 }