@runtypelabs/sdk 6.3.6 → 6.5.0

package/dist/index.mjs

@@ -26,6 +26,8 @@ var UNIFIED_EVENT_TYPES = /* @__PURE__ */ new Set([
   "artifact_update",
   "artifact_complete",
   "source",
+  "state_snapshot",
+  "state_delta",
   "tool_start",
   "tool_input_delta",
   "tool_input_complete",
@@ -178,9 +180,10 @@ function createFlowEventTranslator() {
             pageOrigin: data.pageOrigin
           })
         ];
-      // Channels/markers/tool-family/approval/skip/source/custom/ping the flow
-      // consumer never read → no callback event. (A non-terminal `error` is only
-      // produced on agent streams; dropping it here avoids a false flow_error.)
+      // Channels/markers/tool-family/approval/skip/source/state/custom/ping the
+      // flow consumer never read → no callback event. (A non-terminal `error` is
+      // only produced on agent streams; dropping it here avoids a false
+      // flow_error.)
       default:
         return [];
     }
@@ -300,6 +303,7 @@ function createAgentEventTranslator() {
             toolName: data.toolName,
             toolType: data.toolType,
             parameters: data.parameters,
+            hiddenParameterNames: data.hiddenParameterNames,
             origin: data.origin,
             pageOrigin: data.pageOrigin
           })
@@ -482,8 +486,9 @@ function createAgentEventTranslator() {
       case "ping":
         return [compact({ type: "agent_ping", executionId, seq, timestamp: data.timestamp })];
       // turn/text/reasoning open+close markers, step_*, artifact_*, source,
-      // custom (fallback beat / routing), and the skill-fold result envelope
-      // the SDK never consumed → no callback event.
+      // state_snapshot/state_delta (agent-state channel with no stable SDK
+      // callback), custom (fallback beat / routing), and the skill-fold result
+      // envelope the SDK never consumed → no callback event.
       default:
         return [];
     }
@@ -1628,7 +1633,11 @@ var FlowBuilder = class {
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
     const request6 = { flow };
     if (this.recordConfig) {
-      request6.record = this.recordConfig;
+      const { id, ...record } = this.recordConfig;
+      request6.record = {
+        ...record,
+        ...id !== void 0 ? { id: String(id) } : {}
+      };
     }
     if (this.messagesConfig) {
       request6.messages = this.messagesConfig;
@@ -1771,8 +1780,7 @@ var ClientFlowBuilder = class extends FlowBuilder {
     let runCallbacks;
     let localTools;
     let dispatchClient = this.boundClient;
-    const isLocalTools = (obj) => obj && typeof obj === "object" && !isStreamCallbacks(obj) && !("streamResponse" in obj) && // Not options
-    !("dispatch" in obj);
+    const isLocalTools = (obj) => obj && typeof obj === "object" && !Array.isArray(obj) && !isStreamCallbacks(obj) && !("dispatch" in obj) && Object.keys(obj).length > 0 && Object.values(obj).every((value) => typeof value === "function");
     if (arg1) {
       if (typeof arg1 === "object" && "dispatch" in arg1) {
         if (arg2) {
@@ -3493,7 +3501,7 @@ var RuntypeFlowBuilder = class {
     if (isStreaming) {
       currentResponse = await client.dispatch(config);
     } else {
-      const data = await client.post("/dispatch", config);
+      const data = await client.dispatchJson(config);
       currentResponse = new Response(JSON.stringify(data), {
         headers: { "content-type": "application/json" }
       });
@@ -3562,7 +3570,11 @@ var RuntypeFlowBuilder = class {
     const flow = this.existingFlowId ? { id: this.existingFlowId } : { name: this.flowConfig.name, steps: this.steps };
     const request6 = { flow };
     if (this.recordConfig) {
-      request6.record = this.recordConfig;
+      const { id, ...record } = this.recordConfig;
+      request6.record = {
+        ...record,
+        ...id !== void 0 ? { id: String(id) } : {}
+      };
     }
     if (this.messagesConfig) {
       request6.messages = this.messagesConfig;
@@ -3634,6 +3646,9 @@ var RuntypeFlowBuilder = class {
     if (this.mode !== "upsert" || !this.steps.length) {
       return client.dispatch(config);
     }
+    if (!config.flow) {
+      throw new Error("Persisted flow dispatch requires a flow target");
+    }
     const contentHash = await this.computeContentHash();
     const hashOnlyConfig = {
       ...config,
@@ -5704,6 +5719,47 @@ function transformQueryParams(params) {
   return result;
 }
 
+// src/dispatch-request.ts
+function normalizeDispatchMessageContent(content) {
+  if (Array.isArray(content) && content.some(
+    (part) => typeof part === "object" && part !== null && "type" in part && part.type === "asset_ref"
+  )) {
+    throw new Error(
+      "Dispatch messages cannot submit persisted asset_ref content; provide the original image or file content instead"
+    );
+  }
+  return content;
+}
+function normalizeDispatchRequest(request6) {
+  if (!request6.flow && !request6.agent) {
+    throw new Error("Dispatch requires either a flow or an agent target");
+  }
+  const record = request6.record === void 0 ? void 0 : {
+    ...request6.record,
+    ...request6.record.id !== void 0 ? { id: String(request6.record.id) } : {}
+  };
+  const messages = request6.messages?.map((message) => ({
+    ...message,
+    content: normalizeDispatchMessageContent(message.content)
+  }));
+  const clientTools = request6.clientTools?.map((tool) => {
+    if (tool.parametersSchema.type !== "object") {
+      throw new Error(`Client tool "${tool.name}" parametersSchema.type must be "object"`);
+    }
+    return {
+      ...tool,
+      parametersSchema: tool.parametersSchema
+    };
+  });
+  const normalized = {
+    ...request6,
+    ...record !== void 0 ? { record } : {},
+    ...messages !== void 0 ? { messages } : {},
+    ...clientTools !== void 0 ? { clientTools } : {}
+  };
+  return request6.flow ? { ...normalized, flow: request6.flow } : { ...normalized, agent: request6.agent };
+}
+
 // src/runtype.ts
 var globalConfig = {};
 var globalClient = null;
@@ -5801,12 +5857,42 @@ var RuntypeClient = class {
     });
   }
   /**
-   * Dispatch flow execution (streaming)
+   * Dispatch flow execution (streaming).
+   *
+   * This is the sole streaming-dispatch chokepoint for the flow builders
+   * (`RuntypeFlowBuilder`), so it normalizes the request to the canonical
+   * `/v1/dispatch` wire contract here — every builder path inherits the same
+   * normalization the `DispatchEndpoint` applies, with no per-builder call.
    */
   async dispatch(config) {
+    const normalized = normalizeDispatchRequest(config);
+    const request6 = transformRequest({
+      ...normalized,
+      options: {
+        ...normalized.options,
+        streamResponse: true
+      }
+    });
     return this.requestStream("/dispatch", {
       method: "POST",
-      body: JSON.stringify(transformRequest(config))
+      body: JSON.stringify(request6)
+    });
+  }
+  /**
+   * Dispatch flow execution (non-streaming JSON).
+   *
+   * The non-streaming sibling of {@link dispatch}; it normalizes to the same
+   * canonical wire contract so builders never post a raw, un-normalized body,
+   * and pins `streamResponse: false` so the server returns buffered JSON.
+   */
+  async dispatchJson(config) {
+    const normalized = normalizeDispatchRequest(config);
+    return this.post("/dispatch", {
+      ...normalized,
+      options: {
+        ...normalized.options,
+        streamResponse: false
+      }
     });
   }
   /**
@@ -6175,7 +6261,7 @@ var Runtype = class {
 
 // src/version.ts
 var FALLBACK_VERSION = "0.0.0";
-var SDK_VERSION = "6.3.6".length > 0 ? "6.3.6" : FALLBACK_VERSION;
+var SDK_VERSION = "6.5.0".length > 0 ? "6.5.0" : FALLBACK_VERSION;
 var RUNTYPE_CLIENT_KIND = "sdk";
 var SDK_USER_AGENT = `runtype-sdk/${SDK_VERSION} (typescript)`;
 
@@ -6400,7 +6486,11 @@ function buildGeneratedRuntimeToolGateOutput(proposal, options = {}) {
   };
 }
 function attachRuntimeToolsToDispatchRequest(request6, runtimeTools, options = {}) {
-  const stepList = request6.flow.steps;
+  const flow = request6.flow;
+  if (!flow) {
+    throw new Error("Cannot attach runtime tools: dispatch request must include flow.steps");
+  }
+  const stepList = flow.steps;
   if (!stepList || !Array.isArray(stepList) || stepList.length === 0) {
     throw new Error("Cannot attach runtime tools: dispatch request must include flow.steps");
   }
@@ -6445,7 +6535,7 @@ function attachRuntimeToolsToDispatchRequest(request6, runtimeTools, options = {
   return {
     ...request6,
     flow: {
-      ...request6.flow,
+      ...flow,
       // `clonedSteps` is a structural clone of `request.flow.steps` (already
       // `FlowStepDefinition[]`); only the prompt step's `config.tools` was
       // merged, so every step's `type` discriminant is preserved. The clone is
@@ -8720,34 +8810,52 @@ var DispatchEndpoint = class {
    * Dispatch: create and/or execute flows on records atomically
    */
   async execute(data) {
-    return this.client.post("/dispatch", data);
+    const normalized = normalizeDispatchRequest(data);
+    return this.client.post("/dispatch", {
+      ...normalized,
+      options: {
+        ...normalized.options,
+        streamResponse: false
+      }
+    });
   }
   /**
    * Dispatch with streaming response
    */
   async executeStream(data) {
+    const normalized = normalizeDispatchRequest(data);
     return this.client.requestStream("/dispatch", {
       method: "POST",
-      body: JSON.stringify(data)
+      body: JSON.stringify({
+        ...normalized,
+        options: {
+          ...normalized.options,
+          streamResponse: true
+        }
+      })
     });
   }
   /**
    * Resume paused flow execution
-   * API expects snake_case field names
+   * Uses buffered JSON when streamResponse is omitted.
    *
-   * @param data.execution_id - The execution ID to resume
-   * @param data.tool_outputs - Tool outputs to inject into the flow
-   * @param data.stream_response - Whether to stream the response
+   * @param data.executionId - The execution ID to resume
+   * @param data.toolOutputs - Tool outputs to inject into the flow
+   * @param data.streamResponse - Whether to stream the response (defaults to false)
    * @param data.messages - Optional messages to override the original dispatch messages
    */
   async resume(data) {
-    if (data.streamResponse) {
+    const request6 = {
+      ...data,
+      streamResponse: data.streamResponse ?? false
+    };
+    if (request6.streamResponse) {
       return this.client.requestStream("/dispatch/resume", {
         method: "POST",
-        body: JSON.stringify(data)
+        body: JSON.stringify(request6)
       });
     }
-    return this.client.post("/dispatch/resume", data);
+    return this.client.post("/dispatch/resume", request6);
   }
   /**
    * Evaluate a model-proposed runtime tool against a configurable allowlist policy.
@@ -8843,6 +8951,12 @@ var AnalyticsEndpoint = class {
   async getModelUsage(params) {
     return this.client.get("/model-usage", params);
   }
+  /**
+   * Get execution and platform-spend usage grouped by projected product end user.
+   */
+  async getEndUserUsage(params) {
+    return this.client.get("/analytics/end-user-usage", params);
+  }
 };
 var FlowStepsEndpoint = class {
   constructor(client) {
@@ -12613,6 +12727,21 @@ 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 assertTurnScopedLocalTools(localTools) {
+  for (const [name, entry] of Object.entries(localTools)) {
+    if (typeof entry === "function") continue;
+    if (!hasToolEntryShape(entry)) {
+      throw new Error(
+        `Turn-scoped local tool "${name}" must be a function or an entry with description, parametersSchema, and execute`
+      );
+    }
+    if (entry.parametersSchema.type !== "object") {
+      throw new Error(
+        `Turn-scoped local tool "${name}" parametersSchema.type must be "object"`
+      );
+    }
+  }
+}
 function isPausedLocalActionResult(value) {
   return isObjectRecord(value) && value.status === "paused" && Array.isArray(value.pausedTools) && value.pausedTools.length > 0;
 }
@@ -12708,6 +12837,9 @@ var RuntypeClient2 = class {
     const options = (isOptionsObject(arg3) ? arg3 : arg4) ?? {};
     const scope = options.scope ?? "session";
     const isStreaming = !!callbacks;
+    if (scope === "turn") {
+      assertTurnScopedLocalTools(localTools);
+    }
     const derivedClientTools = scope === "turn" ? Object.entries(localTools).filter((entry) => hasToolEntryShape(entry[1])).map(([name, entry]) => ({
       name,
       description: entry.description,

package/package.json

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