@theokit/sdk 2.21.0 → 2.23.0

package/dist/a2a/index.d.cts

@@ -3,7 +3,8 @@
  * Exported via `@theokit/sdk/a2a`.
  * @public
  */
+export type { ToolContextMessage } from "../types/agent-prims.js";
 export { AgentMailbox } from "./agent-mailbox.js";
 export { MessageBus, type RequestOptions } from "./message-bus.js";
-export { defineSubAgent, MaxDelegationDepthError, type SubAgentSpec, } from "./subagent.js";
+export { type DelegationCompleteContext, type DelegationCompleteDecision, type DelegationStartContext, type DelegationStartDecision, defineSubAgent, MaxDelegationDepthError, type MessageFilterArgs, type SubAgentSpec, } from "./subagent.js";
 export type { A2AMessage, MessageHandler } from "./types.js";

package/dist/a2a/index.d.ts

@@ -3,7 +3,8 @@
  * Exported via `@theokit/sdk/a2a`.
  * @public
  */
+export type { ToolContextMessage } from "../types/agent-prims.js";
 export { AgentMailbox } from "./agent-mailbox.js";
 export { MessageBus, type RequestOptions } from "./message-bus.js";
-export { defineSubAgent, MaxDelegationDepthError, type SubAgentSpec, } from "./subagent.js";
+export { type DelegationCompleteContext, type DelegationCompleteDecision, type DelegationStartContext, type DelegationStartDecision, defineSubAgent, MaxDelegationDepthError, type MessageFilterArgs, type SubAgentSpec, } from "./subagent.js";
 export type { A2AMessage, MessageHandler } from "./types.js";

package/dist/a2a/index.js

@@ -8323,21 +8323,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) {
@@ -9162,6 +9162,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,
@@ -9402,7 +9410,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,
@@ -18413,6 +18423,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;
@@ -18422,25 +18501,26 @@ function defineSubAgent(spec, _parentDepth = 0) {
   const inputSchema = z.object({
     input: 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);
     }
   };
 }