@theokit/sdk 2.21.0 → 2.22.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,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;
@@ -18426,21 +18482,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);
     }
   };
 }