@runtypelabs/sdk 1.16.0 → 1.17.0

package/dist/index.cjs

@@ -7453,6 +7453,103 @@ var FlowBuilder = class {
     return this;
   }
   // ============================================================================
+  // Subagent Helpers
+  // ============================================================================
+  /**
+   * Attach a subagent runtime tool to the most recent prompt step.
+   *
+   * A subagent tool spawns a focused child agent in its own context window
+   * when the parent's model calls it. The child runs with a whitelisted tool
+   * subset drawn from `allowedTools` (every entry must be available on the
+   * parent step). The parent only sees the child's final result.
+   *
+   * Pass either `agentId` (for a saved agent in the same org) or `agent`
+   * (an inline exported-agent JSON shape) — exactly one is required.
+   *
+   * @example
+   * ```typescript
+   * new FlowBuilder()
+   *   .createFlow({ name: 'Research' })
+   *   .prompt({ name: 'Plan', model: 'claude-sonnet-4-5', userPrompt: '...' })
+   *   .withSubagentTool('research_topic', {
+   *     agentId: 'agent_01h...',
+   *     allowedTools: ['builtin:exa_search'],
+   *     outputFormat: 'text',
+   *   })
+   * ```
+   */
+  withSubagentTool(name, opts) {
+    const lastStep = this.steps[this.steps.length - 1];
+    if (!lastStep || lastStep.type !== "prompt") {
+      throw new Error(
+        "withSubagentTool() must be called after a .prompt() step \u2014 it attaches a runtime tool to the last prompt step."
+      );
+    }
+    const config = {
+      agentId: opts.agentId,
+      agent: opts.agent,
+      allowedTools: opts.allowedTools,
+      maxTurns: opts.maxTurns,
+      maxCost: opts.maxCost,
+      timeoutMs: opts.timeoutMs,
+      outputFormat: opts.outputFormat,
+      inheritMessages: opts.inheritMessages,
+      taskTemplate: opts.taskTemplate
+    };
+    const tool = {
+      name,
+      description: opts.description ?? `Spawn the ${name} subagent for a focused sub-task. Returns only the subagent's final result.`,
+      toolType: "subagent",
+      parametersSchema: opts.parametersSchema ?? {
+        type: "object",
+        properties: {
+          task: {
+            type: "string",
+            description: "Self-contained task for the subagent. The subagent cannot see this conversation."
+          }
+        },
+        required: ["task"]
+      },
+      config
+    };
+    const existingTools = lastStep.config.tools ?? {};
+    const runtimeTools = [...existingTools.runtimeTools ?? [], tool];
+    lastStep.config.tools = { ...existingTools, runtimeTools };
+    return this;
+  }
+  /**
+   * Enable agent-driven dynamic subagent spawning on the most recent prompt
+   * step (surface C of the subagent design).
+   *
+   * When set, the API synthesizes a `spawn_subagent` tool the parent's model
+   * can call at runtime to spin off a focused child agent. The child's tools
+   * are drawn from `toolPool`, which must be a subset of the parent step's
+   * resolved tools. The API validates pool entries and rejects escalation.
+   *
+   * @example
+   * ```typescript
+   * new FlowBuilder()
+   *   .createFlow({ name: 'Explore' })
+   *   .prompt({ name: 'Research', model: 'claude-sonnet-4-5', userPrompt: '...' })
+   *   .withSubagents({
+   *     toolPool: ['builtin:exa_search', 'mcp:*'],
+   *     maxSpawnsPerRun: 3,
+   *     allowNesting: false,
+   *   })
+   * ```
+   */
+  withSubagents(opts) {
+    const lastStep = this.steps[this.steps.length - 1];
+    if (!lastStep || lastStep.type !== "prompt") {
+      throw new Error(
+        "withSubagents() must be called after a .prompt() step \u2014 it configures subagent spawning on the last prompt step."
+      );
+    }
+    const existingTools = lastStep.config.tools ?? {};
+    lastStep.config.tools = { ...existingTools, subagentConfig: opts };
+    return this;
+  }
+  // ============================================================================
   // Build Method
   // ============================================================================
   /**

package/dist/index.d.cts

@@ -367,14 +367,14 @@ interface Tool {
     organizationId?: string;
     name: string;
     description: string;
-    toolType: 'flow' | 'custom' | 'external' | 'local';
+    toolType: 'flow' | 'custom' | 'external' | 'local' | 'subagent';
     parametersSchema: JSONSchema;
     config: ToolConfig;
     isActive: boolean;
     createdAt: string;
     updatedAt: string;
 }
-type ToolConfig = FlowToolConfig | CustomToolConfig | ExternalToolConfig | LocalToolConfig;
+type ToolConfig = FlowToolConfig | CustomToolConfig | ExternalToolConfig | LocalToolConfig | SubagentToolConfig;
 interface FlowToolConfig {
     flowId: string;
     parameterMapping: Record<string, string>;
@@ -395,6 +395,35 @@ interface ExternalToolConfig {
 interface LocalToolConfig {
     [key: string]: JsonValue;
 }
+/**
+ * Subagent tool configuration (surfaces A + B in the subagent design plan).
+ *
+ * Surface A — saved subagent: set `agentId` to a saved agent in the same org.
+ * Surface B — inline subagent: set `agent` to a full exported agent JSON shape
+ *   validated by the API at dispatch time.
+ *
+ * Exactly one of `agentId` / `agent` must be present; the API validator enforces this.
+ */
+interface SubagentToolConfig {
+    /** (A) Saved agent — org-scoped, ownership-checked at dispatch. */
+    agentId?: string;
+    /** (B) Inline agent definition. Full exported-agent JSON shape. */
+    agent?: JsonObject;
+    /** Tool subset granted to the child. REQUIRED. Must be a subset of the parent's resolved tools. */
+    allowedTools: string[];
+    /** Override the child agent's loop maxTurns. Default 5. */
+    maxTurns?: number;
+    /** Optional cap on the child's running cost. Default: inherits parent budget. */
+    maxCost?: number;
+    /** Per-invocation timeout in ms. Default 300_000 (5 min). */
+    timeoutMs?: number;
+    /** How the child's result is returned. Default 'text'. */
+    outputFormat?: 'text' | 'json' | 'last_message';
+    /** If true, prepend the parent's current messages to the child's initial context. Default false. */
+    inheritMessages?: boolean;
+    /** Optional template rendering the child's initial user message from the tool-call `parameters`. */
+    taskTemplate?: string;
+}
 interface BuiltInTool {
     id: string;
     name: string;
@@ -421,7 +450,7 @@ interface ToolExecution {
 interface CreateToolRequest {
     name: string;
     description: string;
-    toolType: 'flow' | 'custom' | 'external';
+    toolType: 'flow' | 'custom' | 'external' | 'subagent';
     parametersSchema: JSONSchema;
     config: ToolConfig;
 }
@@ -555,14 +584,14 @@ interface ModelUsageResponse {
 interface RuntimeTool {
     name: string;
     description: string;
-    toolType: 'flow' | 'custom' | 'external' | 'local';
+    toolType: 'flow' | 'custom' | 'external' | 'local' | 'subagent';
     parametersSchema: JSONSchema;
     config?: RuntimeToolConfig;
 }
 /**
  * Config options for runtime tools
  */
-type RuntimeToolConfig = RuntimeFlowToolConfig | RuntimeCustomToolConfig | RuntimeExternalToolConfig | RuntimeLocalToolConfig;
+type RuntimeToolConfig = RuntimeFlowToolConfig | RuntimeCustomToolConfig | RuntimeExternalToolConfig | RuntimeLocalToolConfig | RuntimeSubagentToolConfig;
 interface RuntimeLocalToolConfig {
     [key: string]: JsonValue;
 }
@@ -583,6 +612,41 @@ interface RuntimeExternalToolConfig {
     headers?: Record<string, string>;
     body?: string;
 }
+/**
+ * Runtime subagent tool config — inline form used when passing a subagent
+ * tool via `runtimeTools[]` rather than saving it.
+ *
+ * Structurally identical to `SubagentToolConfig`: the API validates the same
+ * fields on both paths, so keeping a single source of truth avoids silent
+ * divergence if a field is added on one side only. Kept as a named alias for
+ * readability at call sites that deal with runtime-only tools.
+ */
+type RuntimeSubagentToolConfig = SubagentToolConfig;
+/**
+ * Opt-in configuration for agent-driven dynamic subagent spawning (surface C
+ * of the subagent design).
+ *
+ * When present on a prompt step's `tools.subagentConfig`, the API synthesizes
+ * a `spawn_subagent` tool that the parent LLM can call at runtime to spin off
+ * a focused child agent. The child's tools are drawn from `toolPool`, which
+ * must be a subset of the parent step's resolved tools.
+ */
+interface AgentSubagentConfig {
+    /** Pool of tool IDs the parent is permitted to grant. Supports wildcards (e.g. `mcp:*`). */
+    toolPool: string[];
+    /** Default iteration cap for spawned subagents. Default 5. */
+    defaultMaxTurns?: number;
+    /** Hard ceiling a subagent may request via maxTurns. Default 10. */
+    maxTurnsLimit?: number;
+    /** Total spawns per top-level parent run. Default 5. */
+    maxSpawnsPerRun?: number;
+    /** Default model for spawned subagents. Defaults to parent's model. */
+    defaultModel?: string;
+    /** Whether spawned subagents can themselves spawn. Default false. */
+    allowNesting?: boolean;
+    /** Default per-spawn timeout. Default 300_000. */
+    defaultTimeoutMs?: number;
+}
 /**
  * Tools configuration for prompt steps.
  * Supports both saved tools (by ID) and runtime tools (inline definitions).
@@ -677,6 +741,12 @@ interface ToolsConfig {
     toolIds?: string[];
     /** Inline runtime tool definitions (not persisted) */
     runtimeTools?: RuntimeTool[];
+    /**
+     * Opt-in agent-driven subagent spawning. When set, the API synthesizes a
+     * `spawn_subagent` tool that the step's model can call at runtime. Pool
+     * entries must be a subset of the parent step's resolved tools.
+     */
+    subagentConfig?: AgentSubagentConfig;
     /**
      * Custom MCP servers with credentials passed at runtime.
      * Maximum 5 servers per step.
@@ -1425,6 +1495,64 @@ declare class FlowBuilder {
      * Add a fetch GitHub step
      */
     fetchGitHub(config: FetchGitHubStepConfig$1): this;
+    /**
+     * Attach a subagent runtime tool to the most recent prompt step.
+     *
+     * A subagent tool spawns a focused child agent in its own context window
+     * when the parent's model calls it. The child runs with a whitelisted tool
+     * subset drawn from `allowedTools` (every entry must be available on the
+     * parent step). The parent only sees the child's final result.
+     *
+     * Pass either `agentId` (for a saved agent in the same org) or `agent`
+     * (an inline exported-agent JSON shape) — exactly one is required.
+     *
+     * @example
+     * ```typescript
+     * new FlowBuilder()
+     *   .createFlow({ name: 'Research' })
+     *   .prompt({ name: 'Plan', model: 'claude-sonnet-4-5', userPrompt: '...' })
+     *   .withSubagentTool('research_topic', {
+     *     agentId: 'agent_01h...',
+     *     allowedTools: ['builtin:exa_search'],
+     *     outputFormat: 'text',
+     *   })
+     * ```
+     */
+    withSubagentTool(name: string, opts: {
+        description?: string;
+        agentId?: string;
+        agent?: JsonObject;
+        allowedTools: string[];
+        parametersSchema?: JSONSchema;
+        maxTurns?: number;
+        maxCost?: number;
+        timeoutMs?: number;
+        outputFormat?: 'text' | 'json' | 'last_message';
+        inheritMessages?: boolean;
+        taskTemplate?: string;
+    }): this;
+    /**
+     * Enable agent-driven dynamic subagent spawning on the most recent prompt
+     * step (surface C of the subagent design).
+     *
+     * When set, the API synthesizes a `spawn_subagent` tool the parent's model
+     * can call at runtime to spin off a focused child agent. The child's tools
+     * are drawn from `toolPool`, which must be a subset of the parent step's
+     * resolved tools. The API validates pool entries and rejects escalation.
+     *
+     * @example
+     * ```typescript
+     * new FlowBuilder()
+     *   .createFlow({ name: 'Explore' })
+     *   .prompt({ name: 'Research', model: 'claude-sonnet-4-5', userPrompt: '...' })
+     *   .withSubagents({
+     *     toolPool: ['builtin:exa_search', 'mcp:*'],
+     *     maxSpawnsPerRun: 3,
+     *     allowNesting: false,
+     *   })
+     * ```
+     */
+    withSubagents(opts: AgentSubagentConfig): this;
     /**
      * Build the final dispatch request configuration
      */
@@ -4065,7 +4193,7 @@ interface AgentToolStartEvent extends BaseAgentEvent {
     iteration: number;
     toolCallId: string;
     toolName: string;
-    toolType: 'flow' | 'mcp' | 'builtin' | 'custom' | 'external';
+    toolType: 'flow' | 'mcp' | 'builtin' | 'custom' | 'external' | 'advisor' | 'subagent';
     parameters?: Record<string, unknown>;
 }
 /**
@@ -4283,7 +4411,7 @@ interface LocalToolDefinition {
 interface AgentRuntimeToolDefinition {
     name: string;
     description: string;
-    toolType: 'flow' | 'custom' | 'external' | 'local';
+    toolType: 'flow' | 'custom' | 'external' | 'local' | 'subagent';
     parametersSchema: Record<string, unknown>;
     config?: Record<string, unknown>;
 }
@@ -5518,4 +5646,4 @@ declare function getLikelySupportingCandidatePaths(bestCandidatePath: string | u
 declare function getDefaultPlanPath(taskName: string): string;
 declare function sanitizeTaskSlug(taskName: string): string;
 
-export { type Agent, type AgentCompleteEvent, type AgentErrorEvent, type AgentEvent, type AgentEventType, type AgentExecuteRequest, type AgentExecuteResponse, type AgentIterationCompleteEvent, type AgentIterationStartEvent, type AgentMessage, type AgentPausedEvent, type AgentPingEvent, type AgentReflectionEvent, type AgentRuntimeToolDefinition, type AgentStartEvent, type AgentStreamCallbacks, type AgentToolCompleteEvent, type AgentToolDeltaEvent, type AgentToolInputCompleteEvent, type AgentToolInputDeltaEvent, type AgentToolStartEvent, type AgentTurnCompleteEvent, type AgentTurnDeltaEvent, type AgentTurnStartEvent, AgentsEndpoint, AnalyticsEndpoint, type ApiClient, type ApiKey, ApiKeysEndpoint, type ApiResponse, type ApplyGeneratedProposalOptions, type ApplyGeneratedProposalResult, type AttachRuntimeToolsOptions, type BaseAgentEvent, BatchBuilder, type BatchClient, type BatchListParams, type BatchOptions, type BatchRequest, type BatchResult, type BatchScheduleConfig, type BatchStatus, BatchesNamespace, type BuiltInTool, type BulkEditCondition, type BulkEditRequest, type BulkEditResponse, type BulkEditResult, ChatEndpoint, ClientBatchBuilder, type ClientConfig, type ClientConversation, ClientEvalBuilder, ClientFlowBuilder, type ClientToken, type ClientTokenConfig, type ClientTokenEnvironment, type ClientTokenVersionPin, ClientTokensEndpoint, type ClientWidgetTheme, type ConditionalStepConfig$1 as ConditionalStepConfig, type ContextErrorHandling, type ContextFallback, ContextTemplatesEndpoint, type CreateApiKeyRequest, type CreateClientTokenRequest, type CreateClientTokenResponse, type CreateFlowRequest, type CreateModelConfigRequest, type CreatePromptData, type CreatePromptRequest, type CreateProviderKeyRequest, type CreateRecordRequest, type CreateToolRequest, type CustomMCPServer, type CustomMCPServerAuth, type CustomToolConfig, type DeployCfSandboxRequest, type DeployCfSandboxResponse, type DeploySandboxRequest, type DeploySandboxResponse, type DispatchClient, DispatchEndpoint, type DispatchEnvironment, type DispatchOptions$1 as DispatchOptions, type DispatchRequest, type ErrorHandlingMode, EvalBuilder, type EvalClient, EvalEndpoint, type EvalListParams, type EvalOptions, type EvalRecord, type EvalRequest, type EvalResult, type EvalRunConfig, EvalRunner, type EvalStatus, EvalsNamespace, type ExecuteToolRequest, type ExecuteToolResponse, type ExternalToolConfig, type FallbackFailEvent, type FallbackStartEvent, type FallbackSuccessEvent, type FallbacksExhaustedEvent, type FallbacksInitiatedEvent, type FetchGitHubStepConfig$1 as FetchGitHubStepConfig, type FetchUrlStepConfig$1 as FetchUrlStepConfig, type FileContentPart, type Flow, type FlowAttachment, FlowBuilder, type FlowCompleteEvent, type FlowConfig$1 as FlowConfig, type FlowErrorEvent, type FlowFallback, type FlowPausedEvent, FlowResult, type FlowStartEvent, type FlowStep, FlowStepsEndpoint, type FlowSummary, type FlowToolConfig, FlowsEndpoint, FlowsNamespace, type GenerateEmbeddingStepConfig$1 as GenerateEmbeddingStepConfig, type GeneratedRuntimeToolGateDecision, type GeneratedRuntimeToolGateOptions, type ImageContentPart, type JSONSchema, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, type ListConversationsResponse, type ListParams, type LocalToolConfig, type LocalToolDefinition, type LocalToolExecutionCompleteEvent, type LocalToolExecutionLoopSnapshotSlice, type LocalToolExecutionStartEvent, type Message$1 as Message, type MessageContent, type Metadata, type ModelConfig, ModelConfigsEndpoint, type ModelFallback, type ModelOverride, type ModelUsageDetail, type ModelUsageQueryParams, type ModelUsageResponse, type ModelUsageSummary, type ModelUsageTimeSeries, type PaginationResponse, type Prompt$1 as Prompt, type PromptErrorHandling, type PromptFallback, type PromptListParams, type PromptRunOptions, PromptRunner, type PromptStepConfig$1 as PromptStepConfig, PromptsEndpoint, PromptsNamespace, type ProviderApiKey, type ReasoningConfig, type ReasoningValue, type RecordConfig$1 as RecordConfig, type RecordListParams, RecordsEndpoint, type RetrieveRecordStepConfig$1 as RetrieveRecordStepConfig, type RetryFallback, type RunTaskContextBudgetBreakdown, type RunTaskContextCompactionEvent, type RunTaskContextCompactionStrategy, type RunTaskContextNoticeEvent, type RunTaskContinuation, type RunTaskOnContextCompaction, type RunTaskOnContextNotice, type RunTaskOnSession, type RunTaskOptions, type RunTaskResult, type RunTaskResumeState, type RunTaskSessionSummary, type RunTaskState, type RunTaskStateSlice, type RunTaskStatus, type RunTaskToolTraceSlice, type RuntimeCustomToolConfig, type RuntimeExternalToolConfig, type RuntimeFlowToolConfig, type RuntimeLocalToolConfig, type RuntimeTool, type RuntimeToolConfig, Runtype, RuntypeApiError, RuntypeClient, type ConditionalStepConfig as RuntypeConditionalStepConfig, type RuntypeConfig, type FetchGitHubStepConfig as RuntypeFetchGitHubStepConfig, type FetchUrlStepConfig as RuntypeFetchUrlStepConfig, RuntypeFlowBuilder, type FlowConfig as RuntypeFlowConfig, type GenerateEmbeddingStepConfig as RuntypeGenerateEmbeddingStepConfig, type Message as RuntypeMessage, type ModelOverride$1 as RuntypeModelOverride, type Prompt as RuntypePrompt, type PromptStepConfig as RuntypePromptStepConfig, type RuntypeRecord, type RecordConfig as RuntypeRecordConfig, type RetrieveRecordStepConfig as RuntypeRetrieveRecordStepConfig, type SearchStepConfig as RuntypeSearchStepConfig, type SendEmailStepConfig as RuntypeSendEmailStepConfig, type SendEventStepConfig as RuntypeSendEventStepConfig, type SendStreamStepConfig as RuntypeSendStreamStepConfig, type SendTextStepConfig as RuntypeSendTextStepConfig, type SetVariableStepConfig as RuntypeSetVariableStepConfig, type TransformDataStepConfig as RuntypeTransformDataStepConfig, type UpsertFlowConfig as RuntypeUpsertFlowConfig, type UpsertRecordStepConfig as RuntypeUpsertRecordStepConfig, type VectorSearchStepConfig as RuntypeVectorSearchStepConfig, type WaitUntilStepConfig as RuntypeWaitUntilStepConfig, type SearchStepConfig$1 as SearchStepConfig, type SendEmailStepConfig$1 as SendEmailStepConfig, type SendEventStepConfig$1 as SendEventStepConfig, type SendStreamStepConfig$1 as SendStreamStepConfig, type SendTextStepConfig$1 as SendTextStepConfig, type SetVariableStepConfig$1 as SetVariableStepConfig, type StepChunkEvent, type StepCompleteEvent, type StepDeltaEvent, type StepFallback, type StepStartEvent, type StepWaitingLocalEvent, type StreamCallbacks, type StreamEvent, type TextContentPart, type Tool, type ToolConfig, type ToolExecution, type ToolsConfig, ToolsEndpoint, type TransformDataStepConfig$1 as TransformDataStepConfig, type UpdateClientTokenRequest, type UpdatePromptData, type UpdateProviderKeyRequest, type UpdateToolRequest, type UpsertFlowConfig$1 as UpsertFlowConfig, type UpsertOptions$2 as UpsertOptions, type UpsertRecordStepConfig$1 as UpsertRecordStepConfig, type UserProfile, UsersEndpoint, type VectorSearchStepConfig$1 as VectorSearchStepConfig, type WaitUntilStepConfig$1 as WaitUntilStepConfig, type WorkflowContext, type WorkflowDefinition, type WorkflowPhase, applyGeneratedRuntimeToolProposalToDispatchRequest, attachRuntimeToolsToDispatchRequest, buildGeneratedRuntimeToolGateOutput, createClient, createExternalTool, defaultWorkflow, deployWorkflow, evaluateGeneratedRuntimeToolProposal, gameWorkflow, getDefaultPlanPath, getLikelySupportingCandidatePaths, isDiscoveryToolName, isMarathonArtifactPath, isPreservationSensitiveTask, normalizeCandidatePath, parseFinalBuffer, parseSSEChunk, processStream, sanitizeTaskSlug, streamEvents };
+export { type Agent, type AgentCompleteEvent, type AgentErrorEvent, type AgentEvent, type AgentEventType, type AgentExecuteRequest, type AgentExecuteResponse, type AgentIterationCompleteEvent, type AgentIterationStartEvent, type AgentMessage, type AgentPausedEvent, type AgentPingEvent, type AgentReflectionEvent, type AgentRuntimeToolDefinition, type AgentStartEvent, type AgentStreamCallbacks, type AgentSubagentConfig, type AgentToolCompleteEvent, type AgentToolDeltaEvent, type AgentToolInputCompleteEvent, type AgentToolInputDeltaEvent, type AgentToolStartEvent, type AgentTurnCompleteEvent, type AgentTurnDeltaEvent, type AgentTurnStartEvent, AgentsEndpoint, AnalyticsEndpoint, type ApiClient, type ApiKey, ApiKeysEndpoint, type ApiResponse, type ApplyGeneratedProposalOptions, type ApplyGeneratedProposalResult, type AttachRuntimeToolsOptions, type BaseAgentEvent, BatchBuilder, type BatchClient, type BatchListParams, type BatchOptions, type BatchRequest, type BatchResult, type BatchScheduleConfig, type BatchStatus, BatchesNamespace, type BuiltInTool, type BulkEditCondition, type BulkEditRequest, type BulkEditResponse, type BulkEditResult, ChatEndpoint, ClientBatchBuilder, type ClientConfig, type ClientConversation, ClientEvalBuilder, ClientFlowBuilder, type ClientToken, type ClientTokenConfig, type ClientTokenEnvironment, type ClientTokenVersionPin, ClientTokensEndpoint, type ClientWidgetTheme, type ConditionalStepConfig$1 as ConditionalStepConfig, type ContextErrorHandling, type ContextFallback, ContextTemplatesEndpoint, type CreateApiKeyRequest, type CreateClientTokenRequest, type CreateClientTokenResponse, type CreateFlowRequest, type CreateModelConfigRequest, type CreatePromptData, type CreatePromptRequest, type CreateProviderKeyRequest, type CreateRecordRequest, type CreateToolRequest, type CustomMCPServer, type CustomMCPServerAuth, type CustomToolConfig, type DeployCfSandboxRequest, type DeployCfSandboxResponse, type DeploySandboxRequest, type DeploySandboxResponse, type DispatchClient, DispatchEndpoint, type DispatchEnvironment, type DispatchOptions$1 as DispatchOptions, type DispatchRequest, type ErrorHandlingMode, EvalBuilder, type EvalClient, EvalEndpoint, type EvalListParams, type EvalOptions, type EvalRecord, type EvalRequest, type EvalResult, type EvalRunConfig, EvalRunner, type EvalStatus, EvalsNamespace, type ExecuteToolRequest, type ExecuteToolResponse, type ExternalToolConfig, type FallbackFailEvent, type FallbackStartEvent, type FallbackSuccessEvent, type FallbacksExhaustedEvent, type FallbacksInitiatedEvent, type FetchGitHubStepConfig$1 as FetchGitHubStepConfig, type FetchUrlStepConfig$1 as FetchUrlStepConfig, type FileContentPart, type Flow, type FlowAttachment, FlowBuilder, type FlowCompleteEvent, type FlowConfig$1 as FlowConfig, type FlowErrorEvent, type FlowFallback, type FlowPausedEvent, FlowResult, type FlowStartEvent, type FlowStep, FlowStepsEndpoint, type FlowSummary, type FlowToolConfig, FlowsEndpoint, FlowsNamespace, type GenerateEmbeddingStepConfig$1 as GenerateEmbeddingStepConfig, type GeneratedRuntimeToolGateDecision, type GeneratedRuntimeToolGateOptions, type ImageContentPart, type JSONSchema, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, type ListConversationsResponse, type ListParams, type LocalToolConfig, type LocalToolDefinition, type LocalToolExecutionCompleteEvent, type LocalToolExecutionLoopSnapshotSlice, type LocalToolExecutionStartEvent, type Message$1 as Message, type MessageContent, type Metadata, type ModelConfig, ModelConfigsEndpoint, type ModelFallback, type ModelOverride, type ModelUsageDetail, type ModelUsageQueryParams, type ModelUsageResponse, type ModelUsageSummary, type ModelUsageTimeSeries, type PaginationResponse, type Prompt$1 as Prompt, type PromptErrorHandling, type PromptFallback, type PromptListParams, type PromptRunOptions, PromptRunner, type PromptStepConfig$1 as PromptStepConfig, PromptsEndpoint, PromptsNamespace, type ProviderApiKey, type ReasoningConfig, type ReasoningValue, type RecordConfig$1 as RecordConfig, type RecordListParams, RecordsEndpoint, type RetrieveRecordStepConfig$1 as RetrieveRecordStepConfig, type RetryFallback, type RunTaskContextBudgetBreakdown, type RunTaskContextCompactionEvent, type RunTaskContextCompactionStrategy, type RunTaskContextNoticeEvent, type RunTaskContinuation, type RunTaskOnContextCompaction, type RunTaskOnContextNotice, type RunTaskOnSession, type RunTaskOptions, type RunTaskResult, type RunTaskResumeState, type RunTaskSessionSummary, type RunTaskState, type RunTaskStateSlice, type RunTaskStatus, type RunTaskToolTraceSlice, type RuntimeCustomToolConfig, type RuntimeExternalToolConfig, type RuntimeFlowToolConfig, type RuntimeLocalToolConfig, type RuntimeSubagentToolConfig, type RuntimeTool, type RuntimeToolConfig, Runtype, RuntypeApiError, RuntypeClient, type ConditionalStepConfig as RuntypeConditionalStepConfig, type RuntypeConfig, type FetchGitHubStepConfig as RuntypeFetchGitHubStepConfig, type FetchUrlStepConfig as RuntypeFetchUrlStepConfig, RuntypeFlowBuilder, type FlowConfig as RuntypeFlowConfig, type GenerateEmbeddingStepConfig as RuntypeGenerateEmbeddingStepConfig, type Message as RuntypeMessage, type ModelOverride$1 as RuntypeModelOverride, type Prompt as RuntypePrompt, type PromptStepConfig as RuntypePromptStepConfig, type RuntypeRecord, type RecordConfig as RuntypeRecordConfig, type RetrieveRecordStepConfig as RuntypeRetrieveRecordStepConfig, type SearchStepConfig as RuntypeSearchStepConfig, type SendEmailStepConfig as RuntypeSendEmailStepConfig, type SendEventStepConfig as RuntypeSendEventStepConfig, type SendStreamStepConfig as RuntypeSendStreamStepConfig, type SendTextStepConfig as RuntypeSendTextStepConfig, type SetVariableStepConfig as RuntypeSetVariableStepConfig, type TransformDataStepConfig as RuntypeTransformDataStepConfig, type UpsertFlowConfig as RuntypeUpsertFlowConfig, type UpsertRecordStepConfig as RuntypeUpsertRecordStepConfig, type VectorSearchStepConfig as RuntypeVectorSearchStepConfig, type WaitUntilStepConfig as RuntypeWaitUntilStepConfig, type SearchStepConfig$1 as SearchStepConfig, type SendEmailStepConfig$1 as SendEmailStepConfig, type SendEventStepConfig$1 as SendEventStepConfig, type SendStreamStepConfig$1 as SendStreamStepConfig, type SendTextStepConfig$1 as SendTextStepConfig, type SetVariableStepConfig$1 as SetVariableStepConfig, type StepChunkEvent, type StepCompleteEvent, type StepDeltaEvent, type StepFallback, type StepStartEvent, type StepWaitingLocalEvent, type StreamCallbacks, type StreamEvent, type SubagentToolConfig, type TextContentPart, type Tool, type ToolConfig, type ToolExecution, type ToolsConfig, ToolsEndpoint, type TransformDataStepConfig$1 as TransformDataStepConfig, type UpdateClientTokenRequest, type UpdatePromptData, type UpdateProviderKeyRequest, type UpdateToolRequest, type UpsertFlowConfig$1 as UpsertFlowConfig, type UpsertOptions$2 as UpsertOptions, type UpsertRecordStepConfig$1 as UpsertRecordStepConfig, type UserProfile, UsersEndpoint, type VectorSearchStepConfig$1 as VectorSearchStepConfig, type WaitUntilStepConfig$1 as WaitUntilStepConfig, type WorkflowContext, type WorkflowDefinition, type WorkflowPhase, applyGeneratedRuntimeToolProposalToDispatchRequest, attachRuntimeToolsToDispatchRequest, buildGeneratedRuntimeToolGateOutput, createClient, createExternalTool, defaultWorkflow, deployWorkflow, evaluateGeneratedRuntimeToolProposal, gameWorkflow, getDefaultPlanPath, getLikelySupportingCandidatePaths, isDiscoveryToolName, isMarathonArtifactPath, isPreservationSensitiveTask, normalizeCandidatePath, parseFinalBuffer, parseSSEChunk, processStream, sanitizeTaskSlug, streamEvents };

package/dist/index.d.ts

@@ -367,14 +367,14 @@ interface Tool {
     organizationId?: string;
     name: string;
     description: string;
-    toolType: 'flow' | 'custom' | 'external' | 'local';
+    toolType: 'flow' | 'custom' | 'external' | 'local' | 'subagent';
     parametersSchema: JSONSchema;
     config: ToolConfig;
     isActive: boolean;
     createdAt: string;
     updatedAt: string;
 }
-type ToolConfig = FlowToolConfig | CustomToolConfig | ExternalToolConfig | LocalToolConfig;
+type ToolConfig = FlowToolConfig | CustomToolConfig | ExternalToolConfig | LocalToolConfig | SubagentToolConfig;
 interface FlowToolConfig {
     flowId: string;
     parameterMapping: Record<string, string>;
@@ -395,6 +395,35 @@ interface ExternalToolConfig {
 interface LocalToolConfig {
     [key: string]: JsonValue;
 }
+/**
+ * Subagent tool configuration (surfaces A + B in the subagent design plan).
+ *
+ * Surface A — saved subagent: set `agentId` to a saved agent in the same org.
+ * Surface B — inline subagent: set `agent` to a full exported agent JSON shape
+ *   validated by the API at dispatch time.
+ *
+ * Exactly one of `agentId` / `agent` must be present; the API validator enforces this.
+ */
+interface SubagentToolConfig {
+    /** (A) Saved agent — org-scoped, ownership-checked at dispatch. */
+    agentId?: string;
+    /** (B) Inline agent definition. Full exported-agent JSON shape. */
+    agent?: JsonObject;
+    /** Tool subset granted to the child. REQUIRED. Must be a subset of the parent's resolved tools. */
+    allowedTools: string[];
+    /** Override the child agent's loop maxTurns. Default 5. */
+    maxTurns?: number;
+    /** Optional cap on the child's running cost. Default: inherits parent budget. */
+    maxCost?: number;
+    /** Per-invocation timeout in ms. Default 300_000 (5 min). */
+    timeoutMs?: number;
+    /** How the child's result is returned. Default 'text'. */
+    outputFormat?: 'text' | 'json' | 'last_message';
+    /** If true, prepend the parent's current messages to the child's initial context. Default false. */
+    inheritMessages?: boolean;
+    /** Optional template rendering the child's initial user message from the tool-call `parameters`. */
+    taskTemplate?: string;
+}
 interface BuiltInTool {
     id: string;
     name: string;
@@ -421,7 +450,7 @@ interface ToolExecution {
 interface CreateToolRequest {
     name: string;
     description: string;
-    toolType: 'flow' | 'custom' | 'external';
+    toolType: 'flow' | 'custom' | 'external' | 'subagent';
     parametersSchema: JSONSchema;
     config: ToolConfig;
 }
@@ -555,14 +584,14 @@ interface ModelUsageResponse {
 interface RuntimeTool {
     name: string;
     description: string;
-    toolType: 'flow' | 'custom' | 'external' | 'local';
+    toolType: 'flow' | 'custom' | 'external' | 'local' | 'subagent';
     parametersSchema: JSONSchema;
     config?: RuntimeToolConfig;
 }
 /**
  * Config options for runtime tools
  */
-type RuntimeToolConfig = RuntimeFlowToolConfig | RuntimeCustomToolConfig | RuntimeExternalToolConfig | RuntimeLocalToolConfig;
+type RuntimeToolConfig = RuntimeFlowToolConfig | RuntimeCustomToolConfig | RuntimeExternalToolConfig | RuntimeLocalToolConfig | RuntimeSubagentToolConfig;
 interface RuntimeLocalToolConfig {
     [key: string]: JsonValue;
 }
@@ -583,6 +612,41 @@ interface RuntimeExternalToolConfig {
     headers?: Record<string, string>;
     body?: string;
 }
+/**
+ * Runtime subagent tool config — inline form used when passing a subagent
+ * tool via `runtimeTools[]` rather than saving it.
+ *
+ * Structurally identical to `SubagentToolConfig`: the API validates the same
+ * fields on both paths, so keeping a single source of truth avoids silent
+ * divergence if a field is added on one side only. Kept as a named alias for
+ * readability at call sites that deal with runtime-only tools.
+ */
+type RuntimeSubagentToolConfig = SubagentToolConfig;
+/**
+ * Opt-in configuration for agent-driven dynamic subagent spawning (surface C
+ * of the subagent design).
+ *
+ * When present on a prompt step's `tools.subagentConfig`, the API synthesizes
+ * a `spawn_subagent` tool that the parent LLM can call at runtime to spin off
+ * a focused child agent. The child's tools are drawn from `toolPool`, which
+ * must be a subset of the parent step's resolved tools.
+ */
+interface AgentSubagentConfig {
+    /** Pool of tool IDs the parent is permitted to grant. Supports wildcards (e.g. `mcp:*`). */
+    toolPool: string[];
+    /** Default iteration cap for spawned subagents. Default 5. */
+    defaultMaxTurns?: number;
+    /** Hard ceiling a subagent may request via maxTurns. Default 10. */
+    maxTurnsLimit?: number;
+    /** Total spawns per top-level parent run. Default 5. */
+    maxSpawnsPerRun?: number;
+    /** Default model for spawned subagents. Defaults to parent's model. */
+    defaultModel?: string;
+    /** Whether spawned subagents can themselves spawn. Default false. */
+    allowNesting?: boolean;
+    /** Default per-spawn timeout. Default 300_000. */
+    defaultTimeoutMs?: number;
+}
 /**
  * Tools configuration for prompt steps.
  * Supports both saved tools (by ID) and runtime tools (inline definitions).
@@ -677,6 +741,12 @@ interface ToolsConfig {
     toolIds?: string[];
     /** Inline runtime tool definitions (not persisted) */
     runtimeTools?: RuntimeTool[];
+    /**
+     * Opt-in agent-driven subagent spawning. When set, the API synthesizes a
+     * `spawn_subagent` tool that the step's model can call at runtime. Pool
+     * entries must be a subset of the parent step's resolved tools.
+     */
+    subagentConfig?: AgentSubagentConfig;
     /**
      * Custom MCP servers with credentials passed at runtime.
      * Maximum 5 servers per step.
@@ -1425,6 +1495,64 @@ declare class FlowBuilder {
      * Add a fetch GitHub step
      */
     fetchGitHub(config: FetchGitHubStepConfig$1): this;
+    /**
+     * Attach a subagent runtime tool to the most recent prompt step.
+     *
+     * A subagent tool spawns a focused child agent in its own context window
+     * when the parent's model calls it. The child runs with a whitelisted tool
+     * subset drawn from `allowedTools` (every entry must be available on the
+     * parent step). The parent only sees the child's final result.
+     *
+     * Pass either `agentId` (for a saved agent in the same org) or `agent`
+     * (an inline exported-agent JSON shape) — exactly one is required.
+     *
+     * @example
+     * ```typescript
+     * new FlowBuilder()
+     *   .createFlow({ name: 'Research' })
+     *   .prompt({ name: 'Plan', model: 'claude-sonnet-4-5', userPrompt: '...' })
+     *   .withSubagentTool('research_topic', {
+     *     agentId: 'agent_01h...',
+     *     allowedTools: ['builtin:exa_search'],
+     *     outputFormat: 'text',
+     *   })
+     * ```
+     */
+    withSubagentTool(name: string, opts: {
+        description?: string;
+        agentId?: string;
+        agent?: JsonObject;
+        allowedTools: string[];
+        parametersSchema?: JSONSchema;
+        maxTurns?: number;
+        maxCost?: number;
+        timeoutMs?: number;
+        outputFormat?: 'text' | 'json' | 'last_message';
+        inheritMessages?: boolean;
+        taskTemplate?: string;
+    }): this;
+    /**
+     * Enable agent-driven dynamic subagent spawning on the most recent prompt
+     * step (surface C of the subagent design).
+     *
+     * When set, the API synthesizes a `spawn_subagent` tool the parent's model
+     * can call at runtime to spin off a focused child agent. The child's tools
+     * are drawn from `toolPool`, which must be a subset of the parent step's
+     * resolved tools. The API validates pool entries and rejects escalation.
+     *
+     * @example
+     * ```typescript
+     * new FlowBuilder()
+     *   .createFlow({ name: 'Explore' })
+     *   .prompt({ name: 'Research', model: 'claude-sonnet-4-5', userPrompt: '...' })
+     *   .withSubagents({
+     *     toolPool: ['builtin:exa_search', 'mcp:*'],
+     *     maxSpawnsPerRun: 3,
+     *     allowNesting: false,
+     *   })
+     * ```
+     */
+    withSubagents(opts: AgentSubagentConfig): this;
     /**
      * Build the final dispatch request configuration
      */
@@ -4065,7 +4193,7 @@ interface AgentToolStartEvent extends BaseAgentEvent {
     iteration: number;
     toolCallId: string;
     toolName: string;
-    toolType: 'flow' | 'mcp' | 'builtin' | 'custom' | 'external';
+    toolType: 'flow' | 'mcp' | 'builtin' | 'custom' | 'external' | 'advisor' | 'subagent';
     parameters?: Record<string, unknown>;
 }
 /**
@@ -4283,7 +4411,7 @@ interface LocalToolDefinition {
 interface AgentRuntimeToolDefinition {
     name: string;
     description: string;
-    toolType: 'flow' | 'custom' | 'external' | 'local';
+    toolType: 'flow' | 'custom' | 'external' | 'local' | 'subagent';
     parametersSchema: Record<string, unknown>;
     config?: Record<string, unknown>;
 }
@@ -5518,4 +5646,4 @@ declare function getLikelySupportingCandidatePaths(bestCandidatePath: string | u
 declare function getDefaultPlanPath(taskName: string): string;
 declare function sanitizeTaskSlug(taskName: string): string;
 
-export { type Agent, type AgentCompleteEvent, type AgentErrorEvent, type AgentEvent, type AgentEventType, type AgentExecuteRequest, type AgentExecuteResponse, type AgentIterationCompleteEvent, type AgentIterationStartEvent, type AgentMessage, type AgentPausedEvent, type AgentPingEvent, type AgentReflectionEvent, type AgentRuntimeToolDefinition, type AgentStartEvent, type AgentStreamCallbacks, type AgentToolCompleteEvent, type AgentToolDeltaEvent, type AgentToolInputCompleteEvent, type AgentToolInputDeltaEvent, type AgentToolStartEvent, type AgentTurnCompleteEvent, type AgentTurnDeltaEvent, type AgentTurnStartEvent, AgentsEndpoint, AnalyticsEndpoint, type ApiClient, type ApiKey, ApiKeysEndpoint, type ApiResponse, type ApplyGeneratedProposalOptions, type ApplyGeneratedProposalResult, type AttachRuntimeToolsOptions, type BaseAgentEvent, BatchBuilder, type BatchClient, type BatchListParams, type BatchOptions, type BatchRequest, type BatchResult, type BatchScheduleConfig, type BatchStatus, BatchesNamespace, type BuiltInTool, type BulkEditCondition, type BulkEditRequest, type BulkEditResponse, type BulkEditResult, ChatEndpoint, ClientBatchBuilder, type ClientConfig, type ClientConversation, ClientEvalBuilder, ClientFlowBuilder, type ClientToken, type ClientTokenConfig, type ClientTokenEnvironment, type ClientTokenVersionPin, ClientTokensEndpoint, type ClientWidgetTheme, type ConditionalStepConfig$1 as ConditionalStepConfig, type ContextErrorHandling, type ContextFallback, ContextTemplatesEndpoint, type CreateApiKeyRequest, type CreateClientTokenRequest, type CreateClientTokenResponse, type CreateFlowRequest, type CreateModelConfigRequest, type CreatePromptData, type CreatePromptRequest, type CreateProviderKeyRequest, type CreateRecordRequest, type CreateToolRequest, type CustomMCPServer, type CustomMCPServerAuth, type CustomToolConfig, type DeployCfSandboxRequest, type DeployCfSandboxResponse, type DeploySandboxRequest, type DeploySandboxResponse, type DispatchClient, DispatchEndpoint, type DispatchEnvironment, type DispatchOptions$1 as DispatchOptions, type DispatchRequest, type ErrorHandlingMode, EvalBuilder, type EvalClient, EvalEndpoint, type EvalListParams, type EvalOptions, type EvalRecord, type EvalRequest, type EvalResult, type EvalRunConfig, EvalRunner, type EvalStatus, EvalsNamespace, type ExecuteToolRequest, type ExecuteToolResponse, type ExternalToolConfig, type FallbackFailEvent, type FallbackStartEvent, type FallbackSuccessEvent, type FallbacksExhaustedEvent, type FallbacksInitiatedEvent, type FetchGitHubStepConfig$1 as FetchGitHubStepConfig, type FetchUrlStepConfig$1 as FetchUrlStepConfig, type FileContentPart, type Flow, type FlowAttachment, FlowBuilder, type FlowCompleteEvent, type FlowConfig$1 as FlowConfig, type FlowErrorEvent, type FlowFallback, type FlowPausedEvent, FlowResult, type FlowStartEvent, type FlowStep, FlowStepsEndpoint, type FlowSummary, type FlowToolConfig, FlowsEndpoint, FlowsNamespace, type GenerateEmbeddingStepConfig$1 as GenerateEmbeddingStepConfig, type GeneratedRuntimeToolGateDecision, type GeneratedRuntimeToolGateOptions, type ImageContentPart, type JSONSchema, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, type ListConversationsResponse, type ListParams, type LocalToolConfig, type LocalToolDefinition, type LocalToolExecutionCompleteEvent, type LocalToolExecutionLoopSnapshotSlice, type LocalToolExecutionStartEvent, type Message$1 as Message, type MessageContent, type Metadata, type ModelConfig, ModelConfigsEndpoint, type ModelFallback, type ModelOverride, type ModelUsageDetail, type ModelUsageQueryParams, type ModelUsageResponse, type ModelUsageSummary, type ModelUsageTimeSeries, type PaginationResponse, type Prompt$1 as Prompt, type PromptErrorHandling, type PromptFallback, type PromptListParams, type PromptRunOptions, PromptRunner, type PromptStepConfig$1 as PromptStepConfig, PromptsEndpoint, PromptsNamespace, type ProviderApiKey, type ReasoningConfig, type ReasoningValue, type RecordConfig$1 as RecordConfig, type RecordListParams, RecordsEndpoint, type RetrieveRecordStepConfig$1 as RetrieveRecordStepConfig, type RetryFallback, type RunTaskContextBudgetBreakdown, type RunTaskContextCompactionEvent, type RunTaskContextCompactionStrategy, type RunTaskContextNoticeEvent, type RunTaskContinuation, type RunTaskOnContextCompaction, type RunTaskOnContextNotice, type RunTaskOnSession, type RunTaskOptions, type RunTaskResult, type RunTaskResumeState, type RunTaskSessionSummary, type RunTaskState, type RunTaskStateSlice, type RunTaskStatus, type RunTaskToolTraceSlice, type RuntimeCustomToolConfig, type RuntimeExternalToolConfig, type RuntimeFlowToolConfig, type RuntimeLocalToolConfig, type RuntimeTool, type RuntimeToolConfig, Runtype, RuntypeApiError, RuntypeClient, type ConditionalStepConfig as RuntypeConditionalStepConfig, type RuntypeConfig, type FetchGitHubStepConfig as RuntypeFetchGitHubStepConfig, type FetchUrlStepConfig as RuntypeFetchUrlStepConfig, RuntypeFlowBuilder, type FlowConfig as RuntypeFlowConfig, type GenerateEmbeddingStepConfig as RuntypeGenerateEmbeddingStepConfig, type Message as RuntypeMessage, type ModelOverride$1 as RuntypeModelOverride, type Prompt as RuntypePrompt, type PromptStepConfig as RuntypePromptStepConfig, type RuntypeRecord, type RecordConfig as RuntypeRecordConfig, type RetrieveRecordStepConfig as RuntypeRetrieveRecordStepConfig, type SearchStepConfig as RuntypeSearchStepConfig, type SendEmailStepConfig as RuntypeSendEmailStepConfig, type SendEventStepConfig as RuntypeSendEventStepConfig, type SendStreamStepConfig as RuntypeSendStreamStepConfig, type SendTextStepConfig as RuntypeSendTextStepConfig, type SetVariableStepConfig as RuntypeSetVariableStepConfig, type TransformDataStepConfig as RuntypeTransformDataStepConfig, type UpsertFlowConfig as RuntypeUpsertFlowConfig, type UpsertRecordStepConfig as RuntypeUpsertRecordStepConfig, type VectorSearchStepConfig as RuntypeVectorSearchStepConfig, type WaitUntilStepConfig as RuntypeWaitUntilStepConfig, type SearchStepConfig$1 as SearchStepConfig, type SendEmailStepConfig$1 as SendEmailStepConfig, type SendEventStepConfig$1 as SendEventStepConfig, type SendStreamStepConfig$1 as SendStreamStepConfig, type SendTextStepConfig$1 as SendTextStepConfig, type SetVariableStepConfig$1 as SetVariableStepConfig, type StepChunkEvent, type StepCompleteEvent, type StepDeltaEvent, type StepFallback, type StepStartEvent, type StepWaitingLocalEvent, type StreamCallbacks, type StreamEvent, type TextContentPart, type Tool, type ToolConfig, type ToolExecution, type ToolsConfig, ToolsEndpoint, type TransformDataStepConfig$1 as TransformDataStepConfig, type UpdateClientTokenRequest, type UpdatePromptData, type UpdateProviderKeyRequest, type UpdateToolRequest, type UpsertFlowConfig$1 as UpsertFlowConfig, type UpsertOptions$2 as UpsertOptions, type UpsertRecordStepConfig$1 as UpsertRecordStepConfig, type UserProfile, UsersEndpoint, type VectorSearchStepConfig$1 as VectorSearchStepConfig, type WaitUntilStepConfig$1 as WaitUntilStepConfig, type WorkflowContext, type WorkflowDefinition, type WorkflowPhase, applyGeneratedRuntimeToolProposalToDispatchRequest, attachRuntimeToolsToDispatchRequest, buildGeneratedRuntimeToolGateOutput, createClient, createExternalTool, defaultWorkflow, deployWorkflow, evaluateGeneratedRuntimeToolProposal, gameWorkflow, getDefaultPlanPath, getLikelySupportingCandidatePaths, isDiscoveryToolName, isMarathonArtifactPath, isPreservationSensitiveTask, normalizeCandidatePath, parseFinalBuffer, parseSSEChunk, processStream, sanitizeTaskSlug, streamEvents };
+export { type Agent, type AgentCompleteEvent, type AgentErrorEvent, type AgentEvent, type AgentEventType, type AgentExecuteRequest, type AgentExecuteResponse, type AgentIterationCompleteEvent, type AgentIterationStartEvent, type AgentMessage, type AgentPausedEvent, type AgentPingEvent, type AgentReflectionEvent, type AgentRuntimeToolDefinition, type AgentStartEvent, type AgentStreamCallbacks, type AgentSubagentConfig, type AgentToolCompleteEvent, type AgentToolDeltaEvent, type AgentToolInputCompleteEvent, type AgentToolInputDeltaEvent, type AgentToolStartEvent, type AgentTurnCompleteEvent, type AgentTurnDeltaEvent, type AgentTurnStartEvent, AgentsEndpoint, AnalyticsEndpoint, type ApiClient, type ApiKey, ApiKeysEndpoint, type ApiResponse, type ApplyGeneratedProposalOptions, type ApplyGeneratedProposalResult, type AttachRuntimeToolsOptions, type BaseAgentEvent, BatchBuilder, type BatchClient, type BatchListParams, type BatchOptions, type BatchRequest, type BatchResult, type BatchScheduleConfig, type BatchStatus, BatchesNamespace, type BuiltInTool, type BulkEditCondition, type BulkEditRequest, type BulkEditResponse, type BulkEditResult, ChatEndpoint, ClientBatchBuilder, type ClientConfig, type ClientConversation, ClientEvalBuilder, ClientFlowBuilder, type ClientToken, type ClientTokenConfig, type ClientTokenEnvironment, type ClientTokenVersionPin, ClientTokensEndpoint, type ClientWidgetTheme, type ConditionalStepConfig$1 as ConditionalStepConfig, type ContextErrorHandling, type ContextFallback, ContextTemplatesEndpoint, type CreateApiKeyRequest, type CreateClientTokenRequest, type CreateClientTokenResponse, type CreateFlowRequest, type CreateModelConfigRequest, type CreatePromptData, type CreatePromptRequest, type CreateProviderKeyRequest, type CreateRecordRequest, type CreateToolRequest, type CustomMCPServer, type CustomMCPServerAuth, type CustomToolConfig, type DeployCfSandboxRequest, type DeployCfSandboxResponse, type DeploySandboxRequest, type DeploySandboxResponse, type DispatchClient, DispatchEndpoint, type DispatchEnvironment, type DispatchOptions$1 as DispatchOptions, type DispatchRequest, type ErrorHandlingMode, EvalBuilder, type EvalClient, EvalEndpoint, type EvalListParams, type EvalOptions, type EvalRecord, type EvalRequest, type EvalResult, type EvalRunConfig, EvalRunner, type EvalStatus, EvalsNamespace, type ExecuteToolRequest, type ExecuteToolResponse, type ExternalToolConfig, type FallbackFailEvent, type FallbackStartEvent, type FallbackSuccessEvent, type FallbacksExhaustedEvent, type FallbacksInitiatedEvent, type FetchGitHubStepConfig$1 as FetchGitHubStepConfig, type FetchUrlStepConfig$1 as FetchUrlStepConfig, type FileContentPart, type Flow, type FlowAttachment, FlowBuilder, type FlowCompleteEvent, type FlowConfig$1 as FlowConfig, type FlowErrorEvent, type FlowFallback, type FlowPausedEvent, FlowResult, type FlowStartEvent, type FlowStep, FlowStepsEndpoint, type FlowSummary, type FlowToolConfig, FlowsEndpoint, FlowsNamespace, type GenerateEmbeddingStepConfig$1 as GenerateEmbeddingStepConfig, type GeneratedRuntimeToolGateDecision, type GeneratedRuntimeToolGateOptions, type ImageContentPart, type JSONSchema, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, type ListConversationsResponse, type ListParams, type LocalToolConfig, type LocalToolDefinition, type LocalToolExecutionCompleteEvent, type LocalToolExecutionLoopSnapshotSlice, type LocalToolExecutionStartEvent, type Message$1 as Message, type MessageContent, type Metadata, type ModelConfig, ModelConfigsEndpoint, type ModelFallback, type ModelOverride, type ModelUsageDetail, type ModelUsageQueryParams, type ModelUsageResponse, type ModelUsageSummary, type ModelUsageTimeSeries, type PaginationResponse, type Prompt$1 as Prompt, type PromptErrorHandling, type PromptFallback, type PromptListParams, type PromptRunOptions, PromptRunner, type PromptStepConfig$1 as PromptStepConfig, PromptsEndpoint, PromptsNamespace, type ProviderApiKey, type ReasoningConfig, type ReasoningValue, type RecordConfig$1 as RecordConfig, type RecordListParams, RecordsEndpoint, type RetrieveRecordStepConfig$1 as RetrieveRecordStepConfig, type RetryFallback, type RunTaskContextBudgetBreakdown, type RunTaskContextCompactionEvent, type RunTaskContextCompactionStrategy, type RunTaskContextNoticeEvent, type RunTaskContinuation, type RunTaskOnContextCompaction, type RunTaskOnContextNotice, type RunTaskOnSession, type RunTaskOptions, type RunTaskResult, type RunTaskResumeState, type RunTaskSessionSummary, type RunTaskState, type RunTaskStateSlice, type RunTaskStatus, type RunTaskToolTraceSlice, type RuntimeCustomToolConfig, type RuntimeExternalToolConfig, type RuntimeFlowToolConfig, type RuntimeLocalToolConfig, type RuntimeSubagentToolConfig, type RuntimeTool, type RuntimeToolConfig, Runtype, RuntypeApiError, RuntypeClient, type ConditionalStepConfig as RuntypeConditionalStepConfig, type RuntypeConfig, type FetchGitHubStepConfig as RuntypeFetchGitHubStepConfig, type FetchUrlStepConfig as RuntypeFetchUrlStepConfig, RuntypeFlowBuilder, type FlowConfig as RuntypeFlowConfig, type GenerateEmbeddingStepConfig as RuntypeGenerateEmbeddingStepConfig, type Message as RuntypeMessage, type ModelOverride$1 as RuntypeModelOverride, type Prompt as RuntypePrompt, type PromptStepConfig as RuntypePromptStepConfig, type RuntypeRecord, type RecordConfig as RuntypeRecordConfig, type RetrieveRecordStepConfig as RuntypeRetrieveRecordStepConfig, type SearchStepConfig as RuntypeSearchStepConfig, type SendEmailStepConfig as RuntypeSendEmailStepConfig, type SendEventStepConfig as RuntypeSendEventStepConfig, type SendStreamStepConfig as RuntypeSendStreamStepConfig, type SendTextStepConfig as RuntypeSendTextStepConfig, type SetVariableStepConfig as RuntypeSetVariableStepConfig, type TransformDataStepConfig as RuntypeTransformDataStepConfig, type UpsertFlowConfig as RuntypeUpsertFlowConfig, type UpsertRecordStepConfig as RuntypeUpsertRecordStepConfig, type VectorSearchStepConfig as RuntypeVectorSearchStepConfig, type WaitUntilStepConfig as RuntypeWaitUntilStepConfig, type SearchStepConfig$1 as SearchStepConfig, type SendEmailStepConfig$1 as SendEmailStepConfig, type SendEventStepConfig$1 as SendEventStepConfig, type SendStreamStepConfig$1 as SendStreamStepConfig, type SendTextStepConfig$1 as SendTextStepConfig, type SetVariableStepConfig$1 as SetVariableStepConfig, type StepChunkEvent, type StepCompleteEvent, type StepDeltaEvent, type StepFallback, type StepStartEvent, type StepWaitingLocalEvent, type StreamCallbacks, type StreamEvent, type SubagentToolConfig, type TextContentPart, type Tool, type ToolConfig, type ToolExecution, type ToolsConfig, ToolsEndpoint, type TransformDataStepConfig$1 as TransformDataStepConfig, type UpdateClientTokenRequest, type UpdatePromptData, type UpdateProviderKeyRequest, type UpdateToolRequest, type UpsertFlowConfig$1 as UpsertFlowConfig, type UpsertOptions$2 as UpsertOptions, type UpsertRecordStepConfig$1 as UpsertRecordStepConfig, type UserProfile, UsersEndpoint, type VectorSearchStepConfig$1 as VectorSearchStepConfig, type WaitUntilStepConfig$1 as WaitUntilStepConfig, type WorkflowContext, type WorkflowDefinition, type WorkflowPhase, applyGeneratedRuntimeToolProposalToDispatchRequest, attachRuntimeToolsToDispatchRequest, buildGeneratedRuntimeToolGateOutput, createClient, createExternalTool, defaultWorkflow, deployWorkflow, evaluateGeneratedRuntimeToolProposal, gameWorkflow, getDefaultPlanPath, getLikelySupportingCandidatePaths, isDiscoveryToolName, isMarathonArtifactPath, isPreservationSensitiveTask, normalizeCandidatePath, parseFinalBuffer, parseSSEChunk, processStream, sanitizeTaskSlug, streamEvents };

package/dist/index.mjs

@@ -7383,6 +7383,103 @@ var FlowBuilder = class {
     return this;
   }
   // ============================================================================
+  // Subagent Helpers
+  // ============================================================================
+  /**
+   * Attach a subagent runtime tool to the most recent prompt step.
+   *
+   * A subagent tool spawns a focused child agent in its own context window
+   * when the parent's model calls it. The child runs with a whitelisted tool
+   * subset drawn from `allowedTools` (every entry must be available on the
+   * parent step). The parent only sees the child's final result.
+   *
+   * Pass either `agentId` (for a saved agent in the same org) or `agent`
+   * (an inline exported-agent JSON shape) — exactly one is required.
+   *
+   * @example
+   * ```typescript
+   * new FlowBuilder()
+   *   .createFlow({ name: 'Research' })
+   *   .prompt({ name: 'Plan', model: 'claude-sonnet-4-5', userPrompt: '...' })
+   *   .withSubagentTool('research_topic', {
+   *     agentId: 'agent_01h...',
+   *     allowedTools: ['builtin:exa_search'],
+   *     outputFormat: 'text',
+   *   })
+   * ```
+   */
+  withSubagentTool(name, opts) {
+    const lastStep = this.steps[this.steps.length - 1];
+    if (!lastStep || lastStep.type !== "prompt") {
+      throw new Error(
+        "withSubagentTool() must be called after a .prompt() step \u2014 it attaches a runtime tool to the last prompt step."
+      );
+    }
+    const config = {
+      agentId: opts.agentId,
+      agent: opts.agent,
+      allowedTools: opts.allowedTools,
+      maxTurns: opts.maxTurns,
+      maxCost: opts.maxCost,
+      timeoutMs: opts.timeoutMs,
+      outputFormat: opts.outputFormat,
+      inheritMessages: opts.inheritMessages,
+      taskTemplate: opts.taskTemplate
+    };
+    const tool = {
+      name,
+      description: opts.description ?? `Spawn the ${name} subagent for a focused sub-task. Returns only the subagent's final result.`,
+      toolType: "subagent",
+      parametersSchema: opts.parametersSchema ?? {
+        type: "object",
+        properties: {
+          task: {
+            type: "string",
+            description: "Self-contained task for the subagent. The subagent cannot see this conversation."
+          }
+        },
+        required: ["task"]
+      },
+      config
+    };
+    const existingTools = lastStep.config.tools ?? {};
+    const runtimeTools = [...existingTools.runtimeTools ?? [], tool];
+    lastStep.config.tools = { ...existingTools, runtimeTools };
+    return this;
+  }
+  /**
+   * Enable agent-driven dynamic subagent spawning on the most recent prompt
+   * step (surface C of the subagent design).
+   *
+   * When set, the API synthesizes a `spawn_subagent` tool the parent's model
+   * can call at runtime to spin off a focused child agent. The child's tools
+   * are drawn from `toolPool`, which must be a subset of the parent step's
+   * resolved tools. The API validates pool entries and rejects escalation.
+   *
+   * @example
+   * ```typescript
+   * new FlowBuilder()
+   *   .createFlow({ name: 'Explore' })
+   *   .prompt({ name: 'Research', model: 'claude-sonnet-4-5', userPrompt: '...' })
+   *   .withSubagents({
+   *     toolPool: ['builtin:exa_search', 'mcp:*'],
+   *     maxSpawnsPerRun: 3,
+   *     allowNesting: false,
+   *   })
+   * ```
+   */
+  withSubagents(opts) {
+    const lastStep = this.steps[this.steps.length - 1];
+    if (!lastStep || lastStep.type !== "prompt") {
+      throw new Error(
+        "withSubagents() must be called after a .prompt() step \u2014 it configures subagent spawning on the last prompt step."
+      );
+    }
+    const existingTools = lastStep.config.tools ?? {};
+    lastStep.config.tools = { ...existingTools, subagentConfig: opts };
+    return this;
+  }
+  // ============================================================================
   // Build Method
   // ============================================================================
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/sdk",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "type": "module",
   "description": "TypeScript SDK for the Runtype API with fluent methods. Use it to quickly realize AI products, agents, and workflows.",
   "main": "dist/index.cjs",