@theokit/sdk 2.21.0 → 2.23.0

package/dist/a2a/subagent.d.cts

@@ -5,9 +5,69 @@
  * invoked by the LLM, creates a child agent and sends the input as a
  * message. EC-2: delegation depth tracked to prevent infinite recursion.
  *
+ * SE10 — the handler forwards the parent run's `AbortSignal` to the child.
+ * SE11 — optional `onDelegationStart` / `onDelegationComplete` lifecycle hooks
+ * let the caller reject, rewrite, observe, or annotate a delegation.
+ *
  * @public
  */
-import type { CustomTool } from "../types/agent.js";
+import type { CustomTool, ToolContextMessage } from "../types/agent.js";
+/** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */
+export interface MessageFilterArgs {
+    /** The supervisor transcript (read-only text projection) available to this delegation. */
+    messages: readonly ToolContextMessage[];
+    /** The prompt about to be delegated (after any `onDelegationStart` rewrite). */
+    input: string;
+    /** The subagent's name. */
+    name: string;
+}
+/** Context passed to {@link SubAgentSpec.onDelegationStart} before the child runs. */
+export interface DelegationStartContext {
+    input: string;
+    name: string;
+    /**
+     * SE15 — 1-based count of times THIS subagent tool has been invoked (a
+     * per-`defineSubAgent`-instance counter). Incremented before this hook runs;
+     * a rejected delegation still counts. Enables reject-after-N patterns.
+     */
+    iteration: number;
+}
+/**
+ * Decision returned from {@link SubAgentSpec.onDelegationStart}. Discriminated on
+ * `proceed` so a rejection (`proceed: false` + `rejectionReason`) and an approval
+ * (`modifiedInput`) cannot be mixed into one nonsensical object.
+ */
+export type DelegationStartDecision = {
+    proceed: false;
+    rejectionReason?: string;
+} | {
+    proceed?: true;
+    modifiedInput?: string;
+    /** SE13 — cap the child's iteration count (forwarded as `SendOptions.maxIterations`). */
+    modifiedMaxSteps?: number;
+};
+/** Context passed to {@link SubAgentSpec.onDelegationComplete} after the child settles. */
+export interface DelegationCompleteContext {
+    input: string;
+    name: string;
+    /** The child's text result (present on success). */
+    result?: string;
+    /** The error the child threw (present on failure); the error is still re-thrown. */
+    error?: unknown;
+    /** SE15 — the same 1-based iteration this delegation's `onDelegationStart` saw. */
+    iteration: number;
+}
+/**
+ * The return of a delegation hook: a decision, a promise of one, or nothing —
+ * `void` lets a side-effect-only callback (`(ctx) => { log(ctx) }`) type-check,
+ * which is the common case (mirrors Mastra's `async ctx => { ... }` hooks).
+ */
+type DelegationHookResult<T> = T | void | Promise<T | void>;
+/** Decision returned from {@link SubAgentSpec.onDelegationComplete}. */
+export interface DelegationCompleteDecision {
+    /** Appended to the child's result string. */
+    feedback?: string;
+}
 export interface SubAgentSpec {
     name: string;
     description: string;
@@ -15,6 +75,39 @@ export interface SubAgentSpec {
     model?: string;
     tools?: CustomTool[];
     maxDelegationDepth?: number;
+    /**
+     * SE11 — called before the supervisor delegates. Return `{ proceed: false }`
+     * to reject (the child never runs and `rejectionReason` becomes the tool
+     * result), or `{ modifiedInput }` to rewrite the delegated prompt. A throwing
+     * hook surfaces (never silently swallowed).
+     */
+    onDelegationStart?: (ctx: DelegationStartContext) => DelegationHookResult<DelegationStartDecision>;
+    /**
+     * SE11 — called after the delegation settles. On success `ctx.result` is set
+     * and an optional `{ feedback }` is appended to it. On failure `ctx.error` is
+     * set and the original error is ALWAYS re-thrown after this hook runs — a throw
+     * from this hook on the error path is suppressed so it cannot mask the
+     * delegation's real failure (on the success path a throw does propagate).
+     */
+    onDelegationComplete?: (ctx: DelegationCompleteContext) => DelegationHookResult<DelegationCompleteDecision>;
+    /**
+     * SE12 — opt-in parent-context forwarding. When set, the supervisor transcript
+     * (`ctx.messages`, a read-only text projection) is passed to this filter and the
+     * returned subset is forwarded to the child as a role-tagged context preamble
+     * prepended to the delegated input. When ABSENT the child runs input-only —
+     * memory isolation stays the default. A filter returning `[]` forwards nothing.
+     * A throwing filter propagates (fail-fast, never swallowed — same contract as
+     * `onDelegationStart`); the delegation surfaces as a tool error.
+     */
+    messageFilter?: (args: MessageFilterArgs) => readonly ToolContextMessage[];
+    /**
+     * SE14 — opt-in subagent result-context control. When `true`, the child's
+     * completed tool-call results (name + result) are appended to the delegation
+     * payload returned to the supervisor, inside a `<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). See ADR 0006.
+     */
+    includeToolResults?: boolean;
 }
 export declare class MaxDelegationDepthError extends Error {
     readonly currentDepth: number;
@@ -23,3 +116,4 @@ export declare class MaxDelegationDepthError extends Error {
     constructor(currentDepth: number, maxDepth: number);
 }
 export declare function defineSubAgent(spec: SubAgentSpec, _parentDepth?: number): CustomTool;
+export {};

package/dist/a2a/subagent.d.ts

@@ -5,9 +5,69 @@
  * invoked by the LLM, creates a child agent and sends the input as a
  * message. EC-2: delegation depth tracked to prevent infinite recursion.
  *
+ * SE10 — the handler forwards the parent run's `AbortSignal` to the child.
+ * SE11 — optional `onDelegationStart` / `onDelegationComplete` lifecycle hooks
+ * let the caller reject, rewrite, observe, or annotate a delegation.
+ *
  * @public
  */
-import type { CustomTool } from "../types/agent.js";
+import type { CustomTool, ToolContextMessage } from "../types/agent.js";
+/** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */
+export interface MessageFilterArgs {
+    /** The supervisor transcript (read-only text projection) available to this delegation. */
+    messages: readonly ToolContextMessage[];
+    /** The prompt about to be delegated (after any `onDelegationStart` rewrite). */
+    input: string;
+    /** The subagent's name. */
+    name: string;
+}
+/** Context passed to {@link SubAgentSpec.onDelegationStart} before the child runs. */
+export interface DelegationStartContext {
+    input: string;
+    name: string;
+    /**
+     * SE15 — 1-based count of times THIS subagent tool has been invoked (a
+     * per-`defineSubAgent`-instance counter). Incremented before this hook runs;
+     * a rejected delegation still counts. Enables reject-after-N patterns.
+     */
+    iteration: number;
+}
+/**
+ * Decision returned from {@link SubAgentSpec.onDelegationStart}. Discriminated on
+ * `proceed` so a rejection (`proceed: false` + `rejectionReason`) and an approval
+ * (`modifiedInput`) cannot be mixed into one nonsensical object.
+ */
+export type DelegationStartDecision = {
+    proceed: false;
+    rejectionReason?: string;
+} | {
+    proceed?: true;
+    modifiedInput?: string;
+    /** SE13 — cap the child's iteration count (forwarded as `SendOptions.maxIterations`). */
+    modifiedMaxSteps?: number;
+};
+/** Context passed to {@link SubAgentSpec.onDelegationComplete} after the child settles. */
+export interface DelegationCompleteContext {
+    input: string;
+    name: string;
+    /** The child's text result (present on success). */
+    result?: string;
+    /** The error the child threw (present on failure); the error is still re-thrown. */
+    error?: unknown;
+    /** SE15 — the same 1-based iteration this delegation's `onDelegationStart` saw. */
+    iteration: number;
+}
+/**
+ * The return of a delegation hook: a decision, a promise of one, or nothing —
+ * `void` lets a side-effect-only callback (`(ctx) => { log(ctx) }`) type-check,
+ * which is the common case (mirrors Mastra's `async ctx => { ... }` hooks).
+ */
+type DelegationHookResult<T> = T | void | Promise<T | void>;
+/** Decision returned from {@link SubAgentSpec.onDelegationComplete}. */
+export interface DelegationCompleteDecision {
+    /** Appended to the child's result string. */
+    feedback?: string;
+}
 export interface SubAgentSpec {
     name: string;
     description: string;
@@ -15,6 +75,39 @@ export interface SubAgentSpec {
     model?: string;
     tools?: CustomTool[];
     maxDelegationDepth?: number;
+    /**
+     * SE11 — called before the supervisor delegates. Return `{ proceed: false }`
+     * to reject (the child never runs and `rejectionReason` becomes the tool
+     * result), or `{ modifiedInput }` to rewrite the delegated prompt. A throwing
+     * hook surfaces (never silently swallowed).
+     */
+    onDelegationStart?: (ctx: DelegationStartContext) => DelegationHookResult<DelegationStartDecision>;
+    /**
+     * SE11 — called after the delegation settles. On success `ctx.result` is set
+     * and an optional `{ feedback }` is appended to it. On failure `ctx.error` is
+     * set and the original error is ALWAYS re-thrown after this hook runs — a throw
+     * from this hook on the error path is suppressed so it cannot mask the
+     * delegation's real failure (on the success path a throw does propagate).
+     */
+    onDelegationComplete?: (ctx: DelegationCompleteContext) => DelegationHookResult<DelegationCompleteDecision>;
+    /**
+     * SE12 — opt-in parent-context forwarding. When set, the supervisor transcript
+     * (`ctx.messages`, a read-only text projection) is passed to this filter and the
+     * returned subset is forwarded to the child as a role-tagged context preamble
+     * prepended to the delegated input. When ABSENT the child runs input-only —
+     * memory isolation stays the default. A filter returning `[]` forwards nothing.
+     * A throwing filter propagates (fail-fast, never swallowed — same contract as
+     * `onDelegationStart`); the delegation surfaces as a tool error.
+     */
+    messageFilter?: (args: MessageFilterArgs) => readonly ToolContextMessage[];
+    /**
+     * SE14 — opt-in subagent result-context control. When `true`, the child's
+     * completed tool-call results (name + result) are appended to the delegation
+     * payload returned to the supervisor, inside a `<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). See ADR 0006.
+     */
+    includeToolResults?: boolean;
 }
 export declare class MaxDelegationDepthError extends Error {
     readonly currentDepth: number;
@@ -23,3 +116,4 @@ export declare class MaxDelegationDepthError extends Error {
     constructor(currentDepth: number, maxDepth: number);
 }
 export declare function defineSubAgent(spec: SubAgentSpec, _parentDepth?: number): CustomTool;
+export {};

package/dist/{cron-dpvtRoro.d.ts → cron-7CruUd_0.d.ts}

@@ -1,4 +1,4 @@
-import { C as CustomTool, M as ModelSelection, Z as SDKUserMessage, $ as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, F as RunToCompletionOptions, H as RunToCompletionResult, S as SDKMessage, a6 as StreamToCompletionResult, a as McpServerConfig } from './run-BMo8yRwK.js';
+import { C as CustomTool, M as ModelSelection, Z as SDKUserMessage, $ as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, F as RunToCompletionOptions, H as RunToCompletionResult, S as SDKMessage, a6 as StreamToCompletionResult, a as McpServerConfig } from './run-CrIulPF7.js';
 import * as zod from 'zod';
 
 /**

package/dist/{cron-YrmsszEN.d.cts → cron-Bpt_1khA.d.cts}

@@ -1,4 +1,4 @@
-import { C as CustomTool, M as ModelSelection, Z as SDKUserMessage, $ as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, F as RunToCompletionOptions, H as RunToCompletionResult, S as SDKMessage, a6 as StreamToCompletionResult, a as McpServerConfig } from './run-BMo8yRwK.cjs';
+import { C as CustomTool, M as ModelSelection, Z as SDKUserMessage, $ as SendOptions, b as Run, G as GenerateOptions, j as GenerateRunResult, F as RunToCompletionOptions, H as RunToCompletionResult, S as SDKMessage, a6 as StreamToCompletionResult, a as McpServerConfig } from './run-CrIulPF7.cjs';
 import * as zod from 'zod';
 
 /**

package/dist/cron.cjs

@@ -9454,21 +9454,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) {
@@ -10228,6 +10228,14 @@ function computeUsageCost(inputs, usage) {
 }
 
 // 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;
+}
 var MAX_NUDGE_ATTEMPTS = 2;
 var MAX_STOP_FEEDBACK_ATTEMPTS = 2;
 async function runAgentLoop(inputs) {
@@ -10470,7 +10478,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,