@runtypelabs/sdk 2.0.1 → 2.1.1

package/dist/index.cjs

@@ -7808,6 +7808,10 @@ function createExternalTool(config) {
 function isObjectRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function hasToolEntryShape(value) {
+  if (!isObjectRecord(value)) return false;
+  return typeof value.execute === "function" && typeof value.description === "string" && typeof value.parametersSchema === "object" && value.parametersSchema !== null;
+}
 function isPausedLocalActionResult(value) {
   if (!isObjectRecord(value) || value.status !== "paused") {
     return false;
@@ -7867,7 +7871,7 @@ var RuntypeClient2 = class {
     return new ClientFlowBuilder(
       {
         dispatch: (config) => this.dispatch.executeStream(config),
-        runWithLocalTools: (config, tools) => this.runWithLocalTools(config, tools)
+        runWithLocalTools: (config, tools, callbacks, opts) => this.runWithLocalTools(config, tools, callbacks, opts)
       },
       name
     );
@@ -7878,18 +7882,26 @@ var RuntypeClient2 = class {
   clearApiKey() {
     delete this.headers.Authorization;
   }
-  /**
-   * Run a flow with client-side tools (automatic pause/resume loop)
-   *
-   * @param request - The dispatch request configuration
-   * @param clientTools - Map of tool names to async functions that execute the tool logic
-   * @param callbacks - Optional callbacks for streaming events
-   * @returns The final result of the flow execution or summary if streaming
-   */
-  async runWithLocalTools(request, localTools, callbacks) {
+  async runWithLocalTools(request, localTools, arg3, arg4) {
+    const isOptionsObject = (val) => typeof val === "object" && val !== null && "scope" in val;
+    const callbacks = isOptionsObject(arg3) ? void 0 : arg3;
+    const options = (isOptionsObject(arg3) ? arg3 : arg4) ?? {};
+    const scope = options.scope ?? "session";
     const isStreaming = !!callbacks;
+    const derivedClientTools = scope === "turn" ? Object.entries(localTools).filter(
+      (entry) => hasToolEntryShape(entry[1])
+    ).map(([name, entry]) => ({
+      name,
+      description: entry.description,
+      parametersSchema: entry.parametersSchema,
+      ...entry.origin ? { origin: entry.origin } : {},
+      ...entry.pageOrigin ? { pageOrigin: entry.pageOrigin } : {}
+    })) : [];
     const modifiedRequest = {
       ...request,
+      ...derivedClientTools.length > 0 ? {
+        clientTools: [...request.clientTools ?? [], ...derivedClientTools]
+      } : {},
       options: {
         ...request.options || {},
         streamResponse: isStreaming
@@ -7991,11 +8003,21 @@ var RuntypeClient2 = class {
       }
       if (isPausedLocalActionResult(result) && result.pausedReason?.type === "local_action") {
         const { toolName, parameters, executionId } = result.pausedReason;
-        if (!localTools[toolName]) {
+        const BARE_NAME_NAMESPACES = ["webmcp:"];
+        const lookupCandidates = [toolName];
+        for (const ns of BARE_NAME_NAMESPACES) {
+          if (toolName.startsWith(ns)) {
+            lookupCandidates.push(toolName.slice(ns.length));
+          }
+        }
+        const matchedKey = lookupCandidates.find((key) => localTools[key]);
+        const toolEntry = matchedKey ? localTools[matchedKey] : void 0;
+        if (!toolEntry) {
           throw new Error(`Local tool "${toolName}" required but not provided in localTools map`);
         }
+        const handler = hasToolEntryShape(toolEntry) ? toolEntry.execute : toolEntry;
         try {
-          const toolResult = await localTools[toolName](parameters);
+          const toolResult = await handler(parameters);
           const resumeData = {
             executionId,
             toolOutputs: { [toolName]: toolResult },

package/dist/index.d.cts

@@ -973,9 +973,14 @@ interface DispatchClient {
      * @param config - The dispatch request configuration
      * @param localTools - Map of tool names to async functions that execute the tool logic
      * @param callbacks - Optional callbacks for streaming events
+     * @param options - Optional behavior tweaks (e.g. `{ scope: 'turn' }` to
+     *   inject the schema as `dispatch.clientTools[]` instead of the legacy
+     *   step-level `runtimeTools` path)
      * @returns The final result of the flow execution or summary if streaming
      */
-    runWithLocalTools(config: DispatchRequest, localTools: Record<string, (args: any) => Promise<any>>, callbacks?: StreamCallbacks): Promise<FlowResult | FlowSummary>;
+    runWithLocalTools(config: DispatchRequest, localTools: Record<string, (args: any) => Promise<any>>, callbacks?: StreamCallbacks, options?: {
+        scope?: 'turn' | 'session';
+    }): Promise<FlowResult | FlowSummary>;
     dispatch(config: DispatchRequest): Promise<Response>;
 }
 /**
@@ -1389,6 +1394,35 @@ interface UpsertOptions {
  * Environment type for dispatch requests
  */
 type DispatchEnvironment = 'development' | 'production';
+/**
+ * Inline tool definition that executes on the dispatching client.
+ *
+ * The wire shape matches the server-side `InlineClientToolSchema` in
+ * `@runtypelabs/shared/api-schemas/dispatch`. Two flavors share the wire:
+ *
+ * - `origin: 'sdk'` (default) — caller-defined locals. No name-prefix rule.
+ * - `origin: 'webmcp'` — page-discovered tools via
+ *   `document.modelContext.registerTool(...)`. The server applies a
+ *   `webmcp:` name prefix before merge so audit logs are filterable.
+ *
+ * Use {@link runWithLocalTools} with `{ scope: 'turn' }` to ship these in
+ * the dispatch envelope; with `{ scope: 'session' }` (default) the SDK
+ * still injects them as step-level runtimeTools for back-compat.
+ */
+interface ClientToolDefinition {
+    name: string;
+    description: string;
+    /**
+     * JSON Schema for the tool's input. Type is intentionally
+     * `Record<string, unknown>` (matching {@link LocalToolDefinition} in
+     * `endpoints.ts`) so callers can pass JSON Schema fragments built with
+     * any helper library (Zod-to-JSON-Schema, ajv, hand-written, etc.)
+     * without fighting the strict {@link JSONSchema} surface.
+     */
+    parametersSchema: Record<string, unknown>;
+    origin?: 'webmcp' | 'sdk';
+    pageOrigin?: string;
+}
 interface DispatchRequest {
     record?: {
         id?: number | string;
@@ -1408,6 +1442,16 @@ interface DispatchRequest {
         role: 'system' | 'user' | 'assistant';
         content: MessageContent;
     }>;
+    /**
+     * Per-dispatch client tools. The SDK populates this when
+     * `runWithLocalTools` is invoked with `{ scope: 'turn' }` (or when
+     * Persona snapshots the host page's WebMCP registry). Tool execution
+     * happens client-side; the server pauses the agent with
+     * `step_await` / `agent_await` and resumes once the client posts the
+     * result. Complementary to the in-engine `resolveTools` callback —
+     * `clientTools[]` is per-dispatch, `resolveTools` is per-iteration.
+     */
+    clientTools?: ClientToolDefinition[];
     secrets?: Record<string, string>;
     inputs?: Record<string, unknown>;
     options?: {
@@ -3934,8 +3978,16 @@ interface AgentToolStartEvent extends BaseAgentEvent {
     iteration: number;
     toolCallId: string;
     toolName: string;
-    toolType: 'flow' | 'mcp' | 'builtin' | 'custom' | 'external' | 'advisor' | 'subagent';
+    toolType: 'flow' | 'mcp' | 'builtin' | 'custom' | 'external' | 'advisor' | 'subagent' | 'local';
     parameters?: Record<string, unknown>;
+    /**
+     * Provenance for client-executed tools (entered via
+     * `dispatch.clientTools[]`). `'webmcp'` marks page-discovered tools
+     * via the WebMCP polyfill; `'sdk'` marks SDK-provided locals.
+     */
+    origin?: 'webmcp' | 'sdk';
+    /** `window.location.origin` of the page that registered a WebMCP tool. */
+    pageOrigin?: string;
 }
 /**
  * Agent tool delta event (reserved for future execution progress)
@@ -4136,6 +4188,10 @@ interface AgentPausedEvent extends BaseAgentEvent {
     toolName: string;
     parameters?: Record<string, unknown>;
     awaitedAt: string;
+    /** Provenance for tools registered via `dispatch.clientTools[]`. */
+    origin?: 'webmcp' | 'sdk';
+    /** `window.location.origin` of the page that registered a WebMCP tool. */
+    pageOrigin?: string;
 }
 /**
  * Synthetic SDK event fired when client-side local tool execution begins.
@@ -4902,6 +4958,43 @@ declare class AgentsEndpoint {
  */
 
 type LocalToolHandler = (args: unknown) => Promise<unknown>;
+/**
+ * Richer local tool entry that pairs a handler with the wire schema the
+ * server should announce to the model. Required when running with
+ * `scope: 'turn'` — the SDK reads the handler's `description` /
+ * `parametersSchema` to build the dispatch envelope's `clientTools[]`.
+ * Optional otherwise (a bare handler still works under `scope: 'session'`
+ * because the caller is expected to have stamped the schema into the
+ * step's `tools.runtimeTools` already).
+ */
+interface LocalToolEntry {
+    description: string;
+    parametersSchema: Record<string, unknown>;
+    execute: (args: unknown) => Promise<unknown>;
+    origin?: 'webmcp' | 'sdk';
+    pageOrigin?: string;
+}
+/**
+ * Options accepted by {@link RuntypeClient.runWithLocalTools}.
+ *
+ * `scope` controls how the SDK delivers the schema for caller-supplied
+ * local tools to the server:
+ *
+ * - `'session'` (default) — back-compat. The caller has already injected
+ *   the schema into the flow's step-level `tools.runtimeTools`; the SDK
+ *   only handles the pause/resume loop with the matching handlers.
+ * - `'turn'` — the SDK auto-builds `dispatch.clientTools[]` from the
+ *   handler map and ships them in the dispatch envelope. The tools live
+ *   for one user turn (one dispatch). Use this for page-side WebMCP
+ *   tools or any per-turn snapshot pattern.
+ *
+ * `'session'` is named for the FlowBuilder use case where the tool config
+ * is stamped once on the flow definition. `'turn'` aligns with the
+ * WebMCP "snapshot at the start of every model turn" refresh model.
+ */
+interface RunWithLocalToolsOptions {
+    scope?: 'turn' | 'session';
+}
 /**
  * RuntypeClient - The main entry point for interacting with the Runtype API
  *
@@ -4955,11 +5048,16 @@ declare class RuntypeClient implements ApiClient {
      * Run a flow with client-side tools (automatic pause/resume loop)
      *
      * @param request - The dispatch request configuration
-     * @param clientTools - Map of tool names to async functions that execute the tool logic
-     * @param callbacks - Optional callbacks for streaming events
+     * @param localTools - Map of tool names to async functions (or full
+     *   `LocalToolEntry` objects) that execute the tool logic
+     * @param callbacksOrOptions - Either {@link StreamCallbacks} (legacy) or
+     *   {@link RunWithLocalToolsOptions}. To pass both, use the 4-arg
+     *   overload.
+     * @param options - Per-call options when callbacks are also supplied
      * @returns The final result of the flow execution or summary if streaming
      */
-    runWithLocalTools(request: DispatchRequest, localTools: Record<string, LocalToolHandler>, callbacks?: StreamCallbacks): Promise<FlowResult | FlowSummary>;
+    runWithLocalTools(request: DispatchRequest, localTools: Record<string, LocalToolHandler | LocalToolEntry>, callbacks?: StreamCallbacks, options?: RunWithLocalToolsOptions): Promise<FlowResult | FlowSummary>;
+    runWithLocalTools(request: DispatchRequest, localTools: Record<string, LocalToolHandler | LocalToolEntry>, options: RunWithLocalToolsOptions): Promise<FlowResult | FlowSummary>;
     /**
      * Generic GET request
      */
@@ -5535,4 +5633,4 @@ declare function getLikelySupportingCandidatePaths(bestCandidatePath: string | u
 declare function getDefaultPlanPath(taskName: string): string;
 declare function sanitizeTaskSlug(taskName: string): string;
 
-export { type Agent, type AgentApprovalCompleteEvent, type AgentApprovalStartEvent, type AgentCompleteEvent, type AgentErrorEvent, type AgentEvent, type AgentEventType, type AgentExecuteRequest, type AgentExecuteResponse, type AgentIterationCompleteEvent, type AgentIterationStartEvent, type AgentMediaEvent, 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 ExternalAgentContext, type ExternalToolConfig, type FallbackFailEvent, type FallbackStartEvent, type FallbackSuccessEvent, type FallbacksExhaustedEvent, type FallbacksInitiatedEvent, type FetchGitHubStepConfig$1 as FetchGitHubStepConfig, type FetchUrlStepConfig$1 as FetchUrlStepConfig, type FieldFormat, 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 ReasoningContentPart, type ReasoningValue, type RecordConfig$1 as RecordConfig, type RecordFilter, type RecordFilterCondition, type RecordFilterGroup, type RecordFilterOperator, 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, STEP_FIELD_REGISTRY, STEP_TYPE_TO_METHOD, 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 StepCompleteEvent, type StepDeltaEvent, type StepFallback, type StepFieldMeta, 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, 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 AgentApprovalCompleteEvent, type AgentApprovalStartEvent, type AgentCompleteEvent, type AgentErrorEvent, type AgentEvent, type AgentEventType, type AgentExecuteRequest, type AgentExecuteResponse, type AgentIterationCompleteEvent, type AgentIterationStartEvent, type AgentMediaEvent, 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 ClientToolDefinition, 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 ExternalAgentContext, type ExternalToolConfig, type FallbackFailEvent, type FallbackStartEvent, type FallbackSuccessEvent, type FallbacksExhaustedEvent, type FallbacksInitiatedEvent, type FetchGitHubStepConfig$1 as FetchGitHubStepConfig, type FetchUrlStepConfig$1 as FetchUrlStepConfig, type FieldFormat, 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 ReasoningContentPart, type ReasoningValue, type RecordConfig$1 as RecordConfig, type RecordFilter, type RecordFilterCondition, type RecordFilterGroup, type RecordFilterOperator, 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, STEP_FIELD_REGISTRY, STEP_TYPE_TO_METHOD, 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 StepCompleteEvent, type StepDeltaEvent, type StepFallback, type StepFieldMeta, 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, 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

@@ -973,9 +973,14 @@ interface DispatchClient {
      * @param config - The dispatch request configuration
      * @param localTools - Map of tool names to async functions that execute the tool logic
      * @param callbacks - Optional callbacks for streaming events
+     * @param options - Optional behavior tweaks (e.g. `{ scope: 'turn' }` to
+     *   inject the schema as `dispatch.clientTools[]` instead of the legacy
+     *   step-level `runtimeTools` path)
      * @returns The final result of the flow execution or summary if streaming
      */
-    runWithLocalTools(config: DispatchRequest, localTools: Record<string, (args: any) => Promise<any>>, callbacks?: StreamCallbacks): Promise<FlowResult | FlowSummary>;
+    runWithLocalTools(config: DispatchRequest, localTools: Record<string, (args: any) => Promise<any>>, callbacks?: StreamCallbacks, options?: {
+        scope?: 'turn' | 'session';
+    }): Promise<FlowResult | FlowSummary>;
     dispatch(config: DispatchRequest): Promise<Response>;
 }
 /**
@@ -1389,6 +1394,35 @@ interface UpsertOptions {
  * Environment type for dispatch requests
  */
 type DispatchEnvironment = 'development' | 'production';
+/**
+ * Inline tool definition that executes on the dispatching client.
+ *
+ * The wire shape matches the server-side `InlineClientToolSchema` in
+ * `@runtypelabs/shared/api-schemas/dispatch`. Two flavors share the wire:
+ *
+ * - `origin: 'sdk'` (default) — caller-defined locals. No name-prefix rule.
+ * - `origin: 'webmcp'` — page-discovered tools via
+ *   `document.modelContext.registerTool(...)`. The server applies a
+ *   `webmcp:` name prefix before merge so audit logs are filterable.
+ *
+ * Use {@link runWithLocalTools} with `{ scope: 'turn' }` to ship these in
+ * the dispatch envelope; with `{ scope: 'session' }` (default) the SDK
+ * still injects them as step-level runtimeTools for back-compat.
+ */
+interface ClientToolDefinition {
+    name: string;
+    description: string;
+    /**
+     * JSON Schema for the tool's input. Type is intentionally
+     * `Record<string, unknown>` (matching {@link LocalToolDefinition} in
+     * `endpoints.ts`) so callers can pass JSON Schema fragments built with
+     * any helper library (Zod-to-JSON-Schema, ajv, hand-written, etc.)
+     * without fighting the strict {@link JSONSchema} surface.
+     */
+    parametersSchema: Record<string, unknown>;
+    origin?: 'webmcp' | 'sdk';
+    pageOrigin?: string;
+}
 interface DispatchRequest {
     record?: {
         id?: number | string;
@@ -1408,6 +1442,16 @@ interface DispatchRequest {
         role: 'system' | 'user' | 'assistant';
         content: MessageContent;
     }>;
+    /**
+     * Per-dispatch client tools. The SDK populates this when
+     * `runWithLocalTools` is invoked with `{ scope: 'turn' }` (or when
+     * Persona snapshots the host page's WebMCP registry). Tool execution
+     * happens client-side; the server pauses the agent with
+     * `step_await` / `agent_await` and resumes once the client posts the
+     * result. Complementary to the in-engine `resolveTools` callback —
+     * `clientTools[]` is per-dispatch, `resolveTools` is per-iteration.
+     */
+    clientTools?: ClientToolDefinition[];
     secrets?: Record<string, string>;
     inputs?: Record<string, unknown>;
     options?: {
@@ -3934,8 +3978,16 @@ interface AgentToolStartEvent extends BaseAgentEvent {
     iteration: number;
     toolCallId: string;
     toolName: string;
-    toolType: 'flow' | 'mcp' | 'builtin' | 'custom' | 'external' | 'advisor' | 'subagent';
+    toolType: 'flow' | 'mcp' | 'builtin' | 'custom' | 'external' | 'advisor' | 'subagent' | 'local';
     parameters?: Record<string, unknown>;
+    /**
+     * Provenance for client-executed tools (entered via
+     * `dispatch.clientTools[]`). `'webmcp'` marks page-discovered tools
+     * via the WebMCP polyfill; `'sdk'` marks SDK-provided locals.
+     */
+    origin?: 'webmcp' | 'sdk';
+    /** `window.location.origin` of the page that registered a WebMCP tool. */
+    pageOrigin?: string;
 }
 /**
  * Agent tool delta event (reserved for future execution progress)
@@ -4136,6 +4188,10 @@ interface AgentPausedEvent extends BaseAgentEvent {
     toolName: string;
     parameters?: Record<string, unknown>;
     awaitedAt: string;
+    /** Provenance for tools registered via `dispatch.clientTools[]`. */
+    origin?: 'webmcp' | 'sdk';
+    /** `window.location.origin` of the page that registered a WebMCP tool. */
+    pageOrigin?: string;
 }
 /**
  * Synthetic SDK event fired when client-side local tool execution begins.
@@ -4902,6 +4958,43 @@ declare class AgentsEndpoint {
  */
 
 type LocalToolHandler = (args: unknown) => Promise<unknown>;
+/**
+ * Richer local tool entry that pairs a handler with the wire schema the
+ * server should announce to the model. Required when running with
+ * `scope: 'turn'` — the SDK reads the handler's `description` /
+ * `parametersSchema` to build the dispatch envelope's `clientTools[]`.
+ * Optional otherwise (a bare handler still works under `scope: 'session'`
+ * because the caller is expected to have stamped the schema into the
+ * step's `tools.runtimeTools` already).
+ */
+interface LocalToolEntry {
+    description: string;
+    parametersSchema: Record<string, unknown>;
+    execute: (args: unknown) => Promise<unknown>;
+    origin?: 'webmcp' | 'sdk';
+    pageOrigin?: string;
+}
+/**
+ * Options accepted by {@link RuntypeClient.runWithLocalTools}.
+ *
+ * `scope` controls how the SDK delivers the schema for caller-supplied
+ * local tools to the server:
+ *
+ * - `'session'` (default) — back-compat. The caller has already injected
+ *   the schema into the flow's step-level `tools.runtimeTools`; the SDK
+ *   only handles the pause/resume loop with the matching handlers.
+ * - `'turn'` — the SDK auto-builds `dispatch.clientTools[]` from the
+ *   handler map and ships them in the dispatch envelope. The tools live
+ *   for one user turn (one dispatch). Use this for page-side WebMCP
+ *   tools or any per-turn snapshot pattern.
+ *
+ * `'session'` is named for the FlowBuilder use case where the tool config
+ * is stamped once on the flow definition. `'turn'` aligns with the
+ * WebMCP "snapshot at the start of every model turn" refresh model.
+ */
+interface RunWithLocalToolsOptions {
+    scope?: 'turn' | 'session';
+}
 /**
  * RuntypeClient - The main entry point for interacting with the Runtype API
  *
@@ -4955,11 +5048,16 @@ declare class RuntypeClient implements ApiClient {
      * Run a flow with client-side tools (automatic pause/resume loop)
      *
      * @param request - The dispatch request configuration
-     * @param clientTools - Map of tool names to async functions that execute the tool logic
-     * @param callbacks - Optional callbacks for streaming events
+     * @param localTools - Map of tool names to async functions (or full
+     *   `LocalToolEntry` objects) that execute the tool logic
+     * @param callbacksOrOptions - Either {@link StreamCallbacks} (legacy) or
+     *   {@link RunWithLocalToolsOptions}. To pass both, use the 4-arg
+     *   overload.
+     * @param options - Per-call options when callbacks are also supplied
      * @returns The final result of the flow execution or summary if streaming
      */
-    runWithLocalTools(request: DispatchRequest, localTools: Record<string, LocalToolHandler>, callbacks?: StreamCallbacks): Promise<FlowResult | FlowSummary>;
+    runWithLocalTools(request: DispatchRequest, localTools: Record<string, LocalToolHandler | LocalToolEntry>, callbacks?: StreamCallbacks, options?: RunWithLocalToolsOptions): Promise<FlowResult | FlowSummary>;
+    runWithLocalTools(request: DispatchRequest, localTools: Record<string, LocalToolHandler | LocalToolEntry>, options: RunWithLocalToolsOptions): Promise<FlowResult | FlowSummary>;
     /**
      * Generic GET request
      */
@@ -5535,4 +5633,4 @@ declare function getLikelySupportingCandidatePaths(bestCandidatePath: string | u
 declare function getDefaultPlanPath(taskName: string): string;
 declare function sanitizeTaskSlug(taskName: string): string;
 
-export { type Agent, type AgentApprovalCompleteEvent, type AgentApprovalStartEvent, type AgentCompleteEvent, type AgentErrorEvent, type AgentEvent, type AgentEventType, type AgentExecuteRequest, type AgentExecuteResponse, type AgentIterationCompleteEvent, type AgentIterationStartEvent, type AgentMediaEvent, 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 ExternalAgentContext, type ExternalToolConfig, type FallbackFailEvent, type FallbackStartEvent, type FallbackSuccessEvent, type FallbacksExhaustedEvent, type FallbacksInitiatedEvent, type FetchGitHubStepConfig$1 as FetchGitHubStepConfig, type FetchUrlStepConfig$1 as FetchUrlStepConfig, type FieldFormat, 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 ReasoningContentPart, type ReasoningValue, type RecordConfig$1 as RecordConfig, type RecordFilter, type RecordFilterCondition, type RecordFilterGroup, type RecordFilterOperator, 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, STEP_FIELD_REGISTRY, STEP_TYPE_TO_METHOD, 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 StepCompleteEvent, type StepDeltaEvent, type StepFallback, type StepFieldMeta, 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, 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 AgentApprovalCompleteEvent, type AgentApprovalStartEvent, type AgentCompleteEvent, type AgentErrorEvent, type AgentEvent, type AgentEventType, type AgentExecuteRequest, type AgentExecuteResponse, type AgentIterationCompleteEvent, type AgentIterationStartEvent, type AgentMediaEvent, 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 ClientToolDefinition, 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 ExternalAgentContext, type ExternalToolConfig, type FallbackFailEvent, type FallbackStartEvent, type FallbackSuccessEvent, type FallbacksExhaustedEvent, type FallbacksInitiatedEvent, type FetchGitHubStepConfig$1 as FetchGitHubStepConfig, type FetchUrlStepConfig$1 as FetchUrlStepConfig, type FieldFormat, 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 ReasoningContentPart, type ReasoningValue, type RecordConfig$1 as RecordConfig, type RecordFilter, type RecordFilterCondition, type RecordFilterGroup, type RecordFilterOperator, 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, STEP_FIELD_REGISTRY, STEP_TYPE_TO_METHOD, 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 StepCompleteEvent, type StepDeltaEvent, type StepFallback, type StepFieldMeta, 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, 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

@@ -7736,6 +7736,10 @@ function createExternalTool(config) {
 function isObjectRecord(value) {
   return typeof value === "object" && value !== null;
 }
+function hasToolEntryShape(value) {
+  if (!isObjectRecord(value)) return false;
+  return typeof value.execute === "function" && typeof value.description === "string" && typeof value.parametersSchema === "object" && value.parametersSchema !== null;
+}
 function isPausedLocalActionResult(value) {
   if (!isObjectRecord(value) || value.status !== "paused") {
     return false;
@@ -7795,7 +7799,7 @@ var RuntypeClient2 = class {
     return new ClientFlowBuilder(
       {
         dispatch: (config) => this.dispatch.executeStream(config),
-        runWithLocalTools: (config, tools) => this.runWithLocalTools(config, tools)
+        runWithLocalTools: (config, tools, callbacks, opts) => this.runWithLocalTools(config, tools, callbacks, opts)
       },
       name
     );
@@ -7806,18 +7810,26 @@ var RuntypeClient2 = class {
   clearApiKey() {
     delete this.headers.Authorization;
   }
-  /**
-   * Run a flow with client-side tools (automatic pause/resume loop)
-   *
-   * @param request - The dispatch request configuration
-   * @param clientTools - Map of tool names to async functions that execute the tool logic
-   * @param callbacks - Optional callbacks for streaming events
-   * @returns The final result of the flow execution or summary if streaming
-   */
-  async runWithLocalTools(request, localTools, callbacks) {
+  async runWithLocalTools(request, localTools, arg3, arg4) {
+    const isOptionsObject = (val) => typeof val === "object" && val !== null && "scope" in val;
+    const callbacks = isOptionsObject(arg3) ? void 0 : arg3;
+    const options = (isOptionsObject(arg3) ? arg3 : arg4) ?? {};
+    const scope = options.scope ?? "session";
     const isStreaming = !!callbacks;
+    const derivedClientTools = scope === "turn" ? Object.entries(localTools).filter(
+      (entry) => hasToolEntryShape(entry[1])
+    ).map(([name, entry]) => ({
+      name,
+      description: entry.description,
+      parametersSchema: entry.parametersSchema,
+      ...entry.origin ? { origin: entry.origin } : {},
+      ...entry.pageOrigin ? { pageOrigin: entry.pageOrigin } : {}
+    })) : [];
     const modifiedRequest = {
       ...request,
+      ...derivedClientTools.length > 0 ? {
+        clientTools: [...request.clientTools ?? [], ...derivedClientTools]
+      } : {},
       options: {
         ...request.options || {},
         streamResponse: isStreaming
@@ -7919,11 +7931,21 @@ var RuntypeClient2 = class {
       }
       if (isPausedLocalActionResult(result) && result.pausedReason?.type === "local_action") {
         const { toolName, parameters, executionId } = result.pausedReason;
-        if (!localTools[toolName]) {
+        const BARE_NAME_NAMESPACES = ["webmcp:"];
+        const lookupCandidates = [toolName];
+        for (const ns of BARE_NAME_NAMESPACES) {
+          if (toolName.startsWith(ns)) {
+            lookupCandidates.push(toolName.slice(ns.length));
+          }
+        }
+        const matchedKey = lookupCandidates.find((key) => localTools[key]);
+        const toolEntry = matchedKey ? localTools[matchedKey] : void 0;
+        if (!toolEntry) {
           throw new Error(`Local tool "${toolName}" required but not provided in localTools map`);
         }
+        const handler = hasToolEntryShape(toolEntry) ? toolEntry.execute : toolEntry;
         try {
-          const toolResult = await localTools[toolName](parameters);
+          const toolResult = await handler(parameters);
           const resumeData = {
             executionId,
             toolOutputs: { [toolName]: toolResult },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runtypelabs/sdk",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "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",