@theokit/sdk 2.21.0 → 2.22.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 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,52 @@ var MaxDelegationDepthError = class extends Error {
   maxDepth;
   code = "max_delegation_depth";
 };
+async function applyDelegationStart(spec, input) {
+  if (spec.onDelegationStart === void 0) return { input };
+  const decision = await spec.onDelegationStart({ input, name: spec.name });
+  if (decision === void 0) return { input };
+  if (decision.proceed === false)
+    return { reject: decision.rejectionReason ?? "(delegation rejected)" };
+  return { input: decision.modifiedInput ?? input };
+}
+async function runChildAgent(spec, input, signal) {
+  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 run = signal !== void 0 ? await agent.send(input, { signal }) : await agent.send(input);
+    const result = await run.wait();
+    return result.result ?? "(no response)";
+  } finally {
+    agent.dispose();
+  }
+}
+async function notifyDelegationError(spec, input, error) {
+  if (spec.onDelegationComplete === void 0) return;
+  try {
+    await spec.onDelegationComplete({ input, name: spec.name, error });
+  } 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) {
+  if (spec.onDelegationComplete === void 0) return result;
+  const completion = await spec.onDelegationComplete({ input, name: spec.name, result });
+  return completion?.feedback !== void 0 ? result + completion.feedback : result;
+}
 function defineSubAgent(spec, _parentDepth = 0) {
   const currentDepth = _parentDepth + 1;
   const maxDepth = spec.maxDelegationDepth ?? 3;
@@ -18429,21 +18485,19 @@ function defineSubAgent(spec, _parentDepth = 0) {
     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);
+      const start = await applyDelegationStart(spec, parsed);
+      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);
+      } catch (error) {
+        await notifyDelegationError(spec, input, error);
+        throw error;
       }
+      return applyDelegationComplete(spec, input, result);
     }
   };
 }