@theokit/sdk 2.22.0 → 2.24.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 2.24.0
+
+### Minor Changes
+
+- 7be1f18: **SE16 — `outputSchema` on `defineTool` (validate + infer the tool's return).**
+
+  `defineTool` (from `@theokit/sdk`) gains an optional `outputSchema` (a Zod schema). When set, the handler returns the STRUCTURED output inferred from it (`z.infer<outputSchema>`), the value is validated against the schema, and the tool result becomes its serialization — a string stays as-is, an object is JSON-stringified. A validation failure raises `ZodError` (converted to a `tool_result(isError)`), so a malformed tool output fails loudly instead of silently reaching the model.
+
+  Additive + fully backward-compatible: with no `outputSchema` the handler returns a plain `string` exactly as before (the handler return type is `string` when `outputSchema` is absent, `z.infer<outputSchema>` when present, via a conditional type). Mirrors Mastra `createTool`'s `outputSchema`. Pairs with SE17 (`toModelOutput`). From the Mastra Tools comparison (SDK Evolution roadmap SE16).
+
+- f621734: **SE17 — `toModelOutput` on `defineTool` (model-facing vs app-facing output split).**
+
+  `defineTool` (from `@theokit/sdk`) gains an optional `toModelOutput`. The handler returns the FULL result (validated by SE16's `outputSchema`); `toModelOutput(output)` maps it to the compact / multimodal representation the MODEL sees in the `tool_result` — so rich app-facing detail is not forced into model context. It returns a `string` OR SE7 `ToolResultContentBlock[]` (text + image). Absent ⇒ the tool result is the serialized handler output (SE16 / pre-SE17 behavior, unchanged).
+
+  Mirrors Mastra's `toModelOutput` and the Vercel AI SDK. Additive + backward-compatible. From the Mastra Tools comparison (SDK Evolution roadmap SE17).
+
+- 72435db: **SE18 — `SendOptions.activeTools` (per-send runtime tool subset).**
+
+  `agent.send(input, { activeTools })` restricts, per send, which of the agent's registered tools the model may actually call. A tool whose canonical name is not in the list is vetoed at dispatch (its handler never runs) — reusing the existing `withToolWhitelist` path that `Agent.fork`'s `allowedTools` uses, NOT `PermissionEngine`. Composes with `toolChoice`: `activeTools` narrows the set, `toolChoice` gates calling within it. Absent ⇒ the full toolset is available (unchanged).
+
+  The loop runs inside a `withToolWhitelist(new Set(activeTools))` scope when set. Additive + backward-compatible. Mirrors Mastra `activeTools` + the Vercel AI SDK. From the Mastra Tools comparison (SDK Evolution roadmap SE18).
+
+- f92f720: **SE19 — `workflowAsTool` (expose a Workflow as an agent tool).**
+
+  `workflowAsTool(workflow, { name, description, inputSchema })` (from `@theokit/sdk/workflow`) turns a `Workflow` into an agent `CustomTool`, completing the Mastra "X as tools" trio (tools; agents-as-tools via `defineSubAgent`; workflows-as-tools). The handler validates the model's args against `spec.inputSchema`, runs the workflow, and returns its output (a string as-is, else JSON). A run that does not reach `status: "completed"` raises a typed `WorkflowToolError` (workflow step errors do NOT throw — they surface via `run.status === "failed"`).
+
+  Because a `Workflow` carries no top-level schema (`WorkflowOptions` is `name`/`persistence`/`workflowId`; schemas are per-step), the caller supplies the tool `inputSchema` in the spec (like `defineTool`). Accepts any `{ run }`-shaped workflow (structural), so it never imports the `Workflow` class. New exports: `workflowAsTool`, `WorkflowToolError`, `WorkflowAsToolSpec`. Additive. From the Mastra Tools comparison (SDK Evolution roadmap SE19).
+
+## 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

@@ -12922,6 +12922,7 @@ function buildLoopInputs(options, runId, userText) {
     ...options.onStep !== void 0 ? { onStep: options.onStep } : {},
     ...options.onDelta !== void 0 ? { onDelta: options.onDelta } : {},
     ...options.sendOptions.toolChoice !== void 0 ? { toolChoice: options.sendOptions.toolChoice } : {},
+    ...options.sendOptions.activeTools !== void 0 ? { activeTools: options.sendOptions.activeTools } : {},
     ...options.priorMessages !== void 0 ? { priorMessages: options.priorMessages } : {},
     ...options.memoryTools !== void 0 && options.memoryTools.length > 0 ? { memoryTools: options.memoryTools } : {},
     ...buildCustomToolsInput(
@@ -13021,6 +13022,7 @@ var init_real_local_run = __esm({
     init_register_plugin_providers();
     init_tracer();
     init_personality_filter();
+    init_async_local_storage();
     init_fixture_run_base();
     init_run_registry();
     pluginProvidersAnnounced = false;
@@ -13070,7 +13072,7 @@ var init_real_local_run = __esm({
       }
       async executeAgentLoop(inputs) {
         try {
-          const output = await runAgentLoop(inputs);
+          const output = inputs.activeTools !== void 0 ? await withToolWhitelist(new Set(inputs.activeTools), () => runAgentLoop(inputs)) : await runAgentLoop(inputs);
           this.applyAgentLoopOutput(output);
           this.transitionTo(output.finalStatus);
         } catch (cause) {
@@ -18426,15 +18428,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 runChildAgent(spec, input, signal) {
+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 } } : {},
@@ -18442,17 +18462,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 +18492,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 +18506,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);
     }
   };
 }