@blazingagents/sdk 0.42.1 → 0.43.1

package/README.md

@@ -10,19 +10,24 @@
   </p>
 </div>
 
-The official resource-style client SDK for the Blazing Agents `/v1` API. It
-requires Node.js 24 or newer.
+The official TypeScript SDK is a client for the Blazing Agents `/v1` API that
+your backend uses to manage Agents and run them for your users. It requires
+Node.js 24 or newer.
 
 ## Features
 
-- Typed clients for Agents, Workspaces, Skills, Providers, Prompts, Tasks,
-  Sessions, Artifacts, Slack and Telegram Chat Connections, usage, Tenant settings, and merchant monetization.
-- Stateful chat with explicit message batches, steer receipts, and one-call Tool approvals.
-- Stateless text or structured-object generation.
-- Public Zod contracts for validating API requests and responses.
-- Cursor pagination and binary transfers.
-- Request correlation and a typed, forward-compatible error model.
-- End-user scoped clients for user-owned resources and generation.
+- A typed method for every `/v1` operation an API key can call: Agents,
+  Skills, Sessions, Memories, Prompts, Tasks, Workspaces, Artifacts,
+  Providers, MCP Connections, Chat Connections, usage, spending limits, Tenant
+  settings, and merchant monetization.
+- Chat streams in the AI SDK UI message stream format, with steering, Tool
+  approvals, and backend functions that run in your process.
+- Text and structured-object generation.
+- End-user scoped clients through `forUser`.
+- Cursor pagination, uploads, and downloads.
+- Request IDs and typed errors.
+- `BlazingAgentsChatTransport` and `createChatRelay` connect AI SDK `useChat`
+  to your backend.
 
 ## Installation
 
@@ -30,19 +35,21 @@ requires Node.js 24 or newer.
 npm install @blazingagents/sdk ai@^7.0.84 zod@^4.5.4
 ```
 
-`ai` (`^7.0.84`) and `zod` (`^4.5.4`) are peer dependencies. The SDK
-re-exports AI SDK message types and Zod schemas, so consumers share these
-dependencies with the SDK.
+`ai` and `zod` are required peer dependencies. The SDK re-exports AI SDK
+message types and Zod schemas, so your app and the SDK share one copy of each.
 
 ## Quick start
 
-Create a Tenant API key in the Blazing Agents dashboard, then pass it to the
-client or read it from your server environment.
+Create a Full API key in the Blazing Agents dashboard and set
+`BLAZING_AGENTS_API_KEY` in your server environment. The key acts for your
+whole Tenant, so keep it on your backend and never send it to a browser.
 
 ```ts
 import { BlazingAgents } from "@blazingagents/sdk";
 
-const client = new BlazingAgents({ apiKey: "ba_..." });
+const client = new BlazingAgents({
+  apiKey: process.env.BLAZING_AGENTS_API_KEY!,
+});
 
 const result = await client.completion({
   agentId: "ag_...",
@@ -52,31 +59,59 @@ const result = await client.completion({
 console.log(await result.text);
 ```
 
-For stateful chat, pass one user message or an ordered batch.
+Replace `ag_...` with an Agent ID from the dashboard.
 
-```ts
-const chat = await client.chat({
-  agentId: "ag_...",
-  messages: [
-    { id: "first", role: "user", parts: [{ type: "text", text: "Compare the plans." }] },
-    { id: "second", role: "user", parts: [{ type: "text", text: "Include annual pricing." }] },
-  ],
-});
+For requests from your users, scope the client to the user ID that your
+backend verified at sign-in, never to an ID from the request body. A scoped
+client reaches only that End-user's Agents, Sessions, and Workspace. An
+unscoped Agent shares one Workspace across all your users, so give each user
+an Agent of their own:
 
-const sessionId = await chat.sessionId;
-return chat.toResponse();
+```ts
+export async function createAgentForUser(userId: string): Promise<string> {
+  const agent = await client.forUser(userId).agents.create({
+    name: "Assistant",
+    providerId: "prv_...",
+    model: "openai/gpt-6-luna",
+  });
+  return agent.id;
+}
+
+export async function chatAsUser(
+  userId: string,
+  agentId: string,
+  text: string
+): Promise<Response> {
+  const chat = await client.forUser(userId).chat({
+    agentId,
+    message: {
+      id: crypto.randomUUID(),
+      role: "user",
+      parts: [{ type: "text", text }],
+    },
+  });
+  return chat.toResponse();
+}
 ```
 
-Keep API keys on the server. For browser chat applications, relay `chat()`
-through your backend and use `BlazingAgentsChatTransport` with AI SDK
-`useChat`.
+Call `createAgentForUser` once per user and store the Agent ID with the user.
+A scoped chat with an Agent created without the scope fails with `404`.
+`chatAsUser` returns the chat as a streaming `Response`. To chat from the
+browser with `useChat`, serve `createChatRelay` from your backend and use
+`BlazingAgentsChatTransport`. The relay scopes each request to the user that
+your `resolveContext` returns.
+
+## Examples
+
+The [examples repository](https://github.com/blazingagents/examples) has
+complete TypeScript and Python apps built on the Blazing Agents SDKs.
 
 ## Documentation
 
 Read the
 [TypeScript SDK documentation](https://docs.blazingagents.com/sdk/typescript)
-for authentication, resource guides, generation and streaming, React
-integration, error handling, and the complete API reference.
+for client setup, End-user scoping, chat and generation, a guide to each
+resource, and error handling.
 
 ## Development
 

package/dist/contracts/entities/mcp-connections.js

@@ -74,7 +74,7 @@ const mcpConnectionUrlSchema = z
     message: "URL must use http(s) without credentials, query, or fragment",
 })
     .transform((value) => new URL(value).toString());
-const mcpConnectionUrlInputSchema = mcpConnectionUrlSchema.describe("Streamable HTTP URL of the MCP server. Use `http` or `https`, with no credentials, query, or fragment.");
+const mcpConnectionUrlInputSchema = mcpConnectionUrlSchema.describe("Streamable HTTP URL of the MCP server. Use `https`, with no credentials, query, or fragment.");
 const authTypeDescription = "How Blazing Agents authenticates to the MCP server: `none`, `bearer`, `oauth_client_credentials`, or `oauth_authorization_code`. The other fields you send depend on it.";
 export const mcpConnectionResponseSchema = z
     .object({

package/dist/contracts/entities/memories.js

@@ -41,7 +41,7 @@ export const createMemoryBodySchema = z
     text: memoryTextSchema.describe("The note to remember, up to 10 KiB."),
     userId: userIdSchema
         .default("")
-        .describe("The end user this memory belongs to. Only turns that pass the same `userId` see it. Leave it out or send an empty string for a general memory that every turn of the agent sees. It cannot change after creation."),
+        .describe("The end user this memory belongs to. Turns for that end user see it. Leave it out or send an empty string for a general memory, which unscoped turns see; a turn made through `forUser` sees only its end user's memories. It cannot change after creation."),
 })
     .strict();
 export const updateMemoryBodySchema = z

package/dist/contracts/entities/merchant.d.ts

@@ -129,11 +129,6 @@ export declare const merchantUsageEventStatusSchema: z.ZodEnum<{
     pending: "pending";
 }>;
 export type MerchantUsageEventStatus = z.infer<typeof merchantUsageEventStatusSchema>;
-export declare const merchantWorkflowIssueSchema: z.ZodEnum<{
-    cancelled: "cancelled";
-    error: "error";
-    recovery_exhausted: "recovery_exhausted";
-}>;
 export declare const merchantUsageEventNextActionSchema: z.ZodEnum<{
     discard: "discard";
     investigate: "investigate";
@@ -186,11 +181,6 @@ export declare const merchantUsageEventSchema: z.ZodObject<{
     lastAttemptAt: z.ZodNullable<z.ZodISODateTime>;
     lastErrorCode: z.ZodNullable<z.ZodString>;
     acceptedAt: z.ZodNullable<z.ZodISODateTime>;
-    workflowIssue: z.ZodNullable<z.ZodEnum<{
-        cancelled: "cancelled";
-        error: "error";
-        recovery_exhausted: "recovery_exhausted";
-    }>>;
     nextAction: z.ZodEnum<{
         discard: "discard";
         investigate: "investigate";
@@ -246,11 +236,6 @@ export declare const merchantUsageEventResponseSchema: z.ZodObject<{
         lastAttemptAt: z.ZodNullable<z.ZodISODateTime>;
         lastErrorCode: z.ZodNullable<z.ZodString>;
         acceptedAt: z.ZodNullable<z.ZodISODateTime>;
-        workflowIssue: z.ZodNullable<z.ZodEnum<{
-            cancelled: "cancelled";
-            error: "error";
-            recovery_exhausted: "recovery_exhausted";
-        }>>;
         nextAction: z.ZodEnum<{
             discard: "discard";
             investigate: "investigate";
@@ -307,11 +292,6 @@ export declare const merchantUsageEventsResponseSchema: z.ZodObject<{
         lastAttemptAt: z.ZodNullable<z.ZodISODateTime>;
         lastErrorCode: z.ZodNullable<z.ZodString>;
         acceptedAt: z.ZodNullable<z.ZodISODateTime>;
-        workflowIssue: z.ZodNullable<z.ZodEnum<{
-            cancelled: "cancelled";
-            error: "error";
-            recovery_exhausted: "recovery_exhausted";
-        }>>;
         nextAction: z.ZodEnum<{
             discard: "discard";
             investigate: "investigate";
@@ -386,10 +366,10 @@ export declare const merchantUsageSummaryResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type MerchantUsageSummaryResponse = z.infer<typeof merchantUsageSummaryResponseSchema>;
 /**
- * The operator-facing action derived from event state — computed at the
- * service seam, never persisted.
+ * The action a Tenant takes on an event. `automaticDeliveryStopped` is true
+ * when automatic delivery has given up on a `pending` event.
  */
 export declare function merchantUsageEventNextAction(event: {
+    automaticDeliveryStopped: boolean;
     status: MerchantUsageEventStatus;
-    workflowIssue: z.infer<typeof merchantWorkflowIssueSchema> | null;
 }): z.infer<typeof merchantUsageEventNextActionSchema>;

package/dist/contracts/entities/merchant.js

@@ -99,11 +99,6 @@ export const merchantUsageEventStatusSchema = z.enum([
     "discarded",
     "expired",
 ]);
-export const merchantWorkflowIssueSchema = z.enum([
-    "error",
-    "cancelled",
-    "recovery_exhausted",
-]);
 export const merchantUsageEventNextActionSchema = z.enum([
     "none",
     "wait",
@@ -136,7 +131,6 @@ export const merchantUsageEventSchema = z
     lastAttemptAt: z.iso.datetime({ offset: true }).nullable(),
     lastErrorCode: z.string().nullable(),
     acceptedAt: z.iso.datetime({ offset: true }).nullable(),
-    workflowIssue: merchantWorkflowIssueSchema.nullable(),
     nextAction: merchantUsageEventNextActionSchema,
 })
     .strip();
@@ -195,8 +189,8 @@ export const merchantUsageSummaryResponseSchema = z
     .object({ summary: merchantUsageSummarySchema })
     .strip();
 /**
- * The operator-facing action derived from event state — computed at the
- * service seam, never persisted.
+ * The action a Tenant takes on an event. `automaticDeliveryStopped` is true
+ * when automatic delivery has given up on a `pending` event.
  */
 export function merchantUsageEventNextAction(event) {
     switch (event.status) {
@@ -204,7 +198,7 @@ export function merchantUsageEventNextAction(event) {
         case "discarded":
             return "none";
         case "pending":
-            return event.workflowIssue === null ? "wait" : "retry";
+            return event.automaticDeliveryStopped ? "retry" : "wait";
         case "failed":
             return "retry";
         case "incomplete":

package/dist/contracts/index.d.ts

@@ -15,7 +15,7 @@ export type { McpConnectionLiveDetails, McpConnectionTestErrorCode, } from "./en
 export { createMcpConnectionBodySchema, forwardedMetadataKeysSchema, mcpAttachmentResponseSchema, mcpAttachmentsResponseSchema, mcpConnectionAuthTypeSchema, mcpConnectionLiveDetailsSchema, mcpConnectionReconnectResultSchema, mcpConnectionResponseSchema, mcpConnectionStatusSchema, mcpConnectionsResponseSchema, mcpConnectionTestErrorCodeSchema, mcpConnectionTestResponseSchema, mcpOauthAuthorizationLaunchResponseSchema, reconnectMcpConnectionBodySchema, updateMcpAttachmentBodySchema, updateMcpConnectionBodySchema, } from "./entities/mcp-connections.ts";
 export type { CreateMemoryBody, Memory, UpdateMemoryBody, } from "./entities/memories.ts";
 export { createMemoryBodySchema, memoriesListResponseSchema, memoryResponseSchema, memorySchema, memoryTextSchema, updateMemoryBodySchema, } from "./entities/memories.ts";
-export { createMerchantConnectionBodySchema, merchantBindingResponseSchema, merchantBindingsResponseSchema, merchantConnectionResponseSchema, merchantConnectionSchema, merchantCustomerBindingSchema, merchantEnvironmentSchema, merchantGuardSchema, merchantProviderSchema, merchantUsageEventNextAction, merchantUsageEventNextActionSchema, merchantUsageEventResponseSchema, merchantUsageEventSchema, merchantUsageEventStatusSchema, merchantUsageEventsResponseSchema, merchantUsageSummaryQuerySchema, merchantUsageSummaryResponseSchema, merchantUsageSummarySchema, merchantWorkflowIssueSchema, updateMerchantConnectionBodySchema, upsertMerchantBindingBodySchema, } from "./entities/merchant.ts";
+export { createMerchantConnectionBodySchema, merchantBindingResponseSchema, merchantBindingsResponseSchema, merchantConnectionResponseSchema, merchantConnectionSchema, merchantCustomerBindingSchema, merchantEnvironmentSchema, merchantGuardSchema, merchantProviderSchema, merchantUsageEventNextAction, merchantUsageEventNextActionSchema, merchantUsageEventResponseSchema, merchantUsageEventSchema, merchantUsageEventStatusSchema, merchantUsageEventsResponseSchema, merchantUsageSummaryQuerySchema, merchantUsageSummaryResponseSchema, merchantUsageSummarySchema, updateMerchantConnectionBodySchema, upsertMerchantBindingBodySchema, } from "./entities/merchant.ts";
 export { createPromptBodySchema, parsePromptVariables, promptResponseSchema, promptsListQuerySchema, promptsResponseSchema, promptTemplateSchema, renderPromptTemplate, updatePromptBodySchema, } from "./entities/prompts.ts";
 export { createProviderBodySchema, providerListItemSchema, providerModelsResponseSchema, providerResponseSchema, providersResponseSchema, providerTypeSchema, thinkingLevelsResponseSchema, updateProviderBodySchema, } from "./entities/providers.ts";
 export type { ChatSteerConsumedEvent, SessionActivity, SessionInput, SessionInputResponse, SessionInputState, SessionInputsQuery, SessionInputsResponse, StopSessionBody, StopSessionResponse, SubmitSessionInputBody, } from "./entities/session-inputs.ts";

package/dist/contracts/index.js

@@ -10,7 +10,7 @@ export { blazingAgentsChatMessageMetadataSchema, chatFunctionCallEventSchema, ch
 export { chatConfigurationSchema, chatConnectionSchema, chatConnectionsResponseSchema, chatCredentialsSchema, chatHealthCheckSchema, chatHealthSchema, chatIdentitySchema, createChatConnectionBodySchema, rotateChatConnectionBodySchema, updateChatConnectionBodySchema, } from "./entities/chat-connections.js";
 export { createMcpConnectionBodySchema, forwardedMetadataKeysSchema, mcpAttachmentResponseSchema, mcpAttachmentsResponseSchema, mcpConnectionAuthTypeSchema, mcpConnectionLiveDetailsSchema, mcpConnectionReconnectResultSchema, mcpConnectionResponseSchema, mcpConnectionStatusSchema, mcpConnectionsResponseSchema, mcpConnectionTestErrorCodeSchema, mcpConnectionTestResponseSchema, mcpOauthAuthorizationLaunchResponseSchema, reconnectMcpConnectionBodySchema, updateMcpAttachmentBodySchema, updateMcpConnectionBodySchema, } from "./entities/mcp-connections.js";
 export { createMemoryBodySchema, memoriesListResponseSchema, memoryResponseSchema, memorySchema, memoryTextSchema, updateMemoryBodySchema, } from "./entities/memories.js";
-export { createMerchantConnectionBodySchema, merchantBindingResponseSchema, merchantBindingsResponseSchema, merchantConnectionResponseSchema, merchantConnectionSchema, merchantCustomerBindingSchema, merchantEnvironmentSchema, merchantGuardSchema, merchantProviderSchema, merchantUsageEventNextAction, merchantUsageEventNextActionSchema, merchantUsageEventResponseSchema, merchantUsageEventSchema, merchantUsageEventStatusSchema, merchantUsageEventsResponseSchema, merchantUsageSummaryQuerySchema, merchantUsageSummaryResponseSchema, merchantUsageSummarySchema, merchantWorkflowIssueSchema, updateMerchantConnectionBodySchema, upsertMerchantBindingBodySchema, } from "./entities/merchant.js";
+export { createMerchantConnectionBodySchema, merchantBindingResponseSchema, merchantBindingsResponseSchema, merchantConnectionResponseSchema, merchantConnectionSchema, merchantCustomerBindingSchema, merchantEnvironmentSchema, merchantGuardSchema, merchantProviderSchema, merchantUsageEventNextAction, merchantUsageEventNextActionSchema, merchantUsageEventResponseSchema, merchantUsageEventSchema, merchantUsageEventStatusSchema, merchantUsageEventsResponseSchema, merchantUsageSummaryQuerySchema, merchantUsageSummaryResponseSchema, merchantUsageSummarySchema, updateMerchantConnectionBodySchema, upsertMerchantBindingBodySchema, } from "./entities/merchant.js";
 export { createPromptBodySchema, parsePromptVariables, promptResponseSchema, promptsListQuerySchema, promptsResponseSchema, promptTemplateSchema, renderPromptTemplate, updatePromptBodySchema, } from "./entities/prompts.js";
 export { createProviderBodySchema, providerListItemSchema, providerModelsResponseSchema, providerResponseSchema, providersResponseSchema, providerTypeSchema, thinkingLevelsResponseSchema, updateProviderBodySchema, } from "./entities/providers.js";
 export { chatSteerConsumedEventSchema, sessionActivitySchema, sessionInputRequestIdSchema, sessionInputResponseSchema, sessionInputSchema, sessionInputStateSchema, sessionInputsQuerySchema, sessionInputsResponseSchema, stopSessionBodySchema, stopSessionResponseSchema, submitSessionInputBodySchema, } from "./entities/session-inputs.js";

package/dist/index.d.ts

@@ -27,7 +27,7 @@ export type { CreateWorkspaceBody, UpdateWorkspaceBody, Workspace, WorkspaceNetw
 export { BlazingAgentsDirectChatTransport, type BlazingAgentsDirectChatTransportOptions, } from "./direct-chat-transport.ts";
 export { BlazingAgentsError } from "./errors.ts";
 export { type ChatFunction, type ChatFunctionContext, type ChatFunctions, defineFunction, } from "./functions.ts";
-export { createChatRelay, createCompletionRelay, type RelayContext, type SessionOwnershipStore, } from "./relay.ts";
+export { createChatRelay, createCompletionRelay, type RelayContext, } from "./relay.ts";
 export type { AgentsListOptions, AgentsResource, UserAgentsResource, } from "./resources/agents.ts";
 export type { ArtifactsResource } from "./resources/artifacts.ts";
 export type { ChatConnectionsResource } from "./resources/chat-connections.ts";

package/dist/relay.d.ts

@@ -1,29 +1,26 @@
-import type { BlazingAgents } from "./client.ts";
 import type { ChatFunctions } from "./functions.ts";
+import type { UserClient } from "./types.ts";
 export interface RelayContext {
+    /**
+     * Agent that serves this request. It must be owned by `userId`, and its
+     * Workspace must be owned by the same End-user; otherwise the API answers 404.
+     */
     agentId: string;
     /** Handlers for this authenticated request and its approved continuation. */
     functions?: ChatFunctions;
     metadata?: Record<string, unknown>;
-    userId: string;
-}
-export interface SessionOwnershipStore {
     /**
-     * Looks up the end user who owns the Session.
-     * @param sessionId - Session to look up or record.
-     * @returns The owner ID, or undefined when no owner is recorded.
+     * The signed-in End-user. The relay scopes every API request to this
+     * End-user with `client.forUser(userId)`, so the API only reaches that
+     * End-user's Agents, Sessions, and Workspaces. Follows the `forUser` rules:
+     * printable ASCII, at most 256 characters, no surrounding spaces.
      */
-    ownerOf(sessionId: string): Promise<string | undefined>;
-    /**
-     * Records ownership of a newly created Session.
-     * @param sessionId - Session to look up or record.
-     * @param userId - End-user ID for request scope.
-     * @returns Resolves after ownership is stored.
-     */
-    recordOwner(sessionId: string, userId: string): Promise<void>;
+    userId: string;
 }
-interface RelayOptions<Method extends keyof BlazingAgents> {
-    client: Pick<BlazingAgents, Method>;
+interface RelayOptions<Method extends keyof UserClient> {
+    client: {
+        forUser(userId: string): Pick<UserClient, Method>;
+    };
     /**
      * Resolves authenticated Agent and end-user context, or null for an unauthenticated request.
      * @param request - Incoming HTTP request.
@@ -32,18 +29,17 @@ interface RelayOptions<Method extends keyof BlazingAgents> {
     resolveContext(request: Request): Promise<RelayContext | null>;
 }
 /**
- * Relays useChat submissions. An assistant message carrying approval
- * responses submits the complete round and streams the continuation.
+ * Relays useChat submissions as the signed-in End-user. An assistant message
+ * carrying approval responses submits the complete round and streams the
+ * continuation.
  * @param options - Configuration for this operation.
- * @returns An HTTP handler that checks Session ownership before resuming.
+ * @returns An HTTP handler that runs each request through `client.forUser(context.userId)`, so the API answers 404 for a Session outside that End-user's scope.
  */
-export declare function createChatRelay(options: RelayOptions<"chat" | "continueChat"> & {
-    sessions: SessionOwnershipStore;
-}): (request: Request) => Promise<Response>;
+export declare function createChatRelay(options: RelayOptions<"chat" | "continueChat">): (request: Request) => Promise<Response>;
 /**
- * Creates an authenticated HTTP handler that validates prompts and relays text generation.
+ * Creates an authenticated HTTP handler that validates prompts and relays text generation as the signed-in End-user.
  * @param options - Configuration for this operation.
- * @returns An HTTP handler that validates prompts and relays text generation.
+ * @returns An HTTP handler that runs each request through `client.forUser(context.userId)`.
  */
 export declare function createCompletionRelay(options: RelayOptions<"completion">): (request: Request) => Promise<Response>;
 export {};

package/dist/relay.js

@@ -13,10 +13,11 @@ const chatBodySchema = z.object({
 });
 const completionBodySchema = z.object({ prompt: z.string().trim().min(1) });
 /**
- * Relays useChat submissions. An assistant message carrying approval
- * responses submits the complete round and streams the continuation.
+ * Relays useChat submissions as the signed-in End-user. An assistant message
+ * carrying approval responses submits the complete round and streams the
+ * continuation.
  * @param options - Configuration for this operation.
- * @returns An HTTP handler that checks Session ownership before resuming.
+ * @returns An HTTP handler that runs each request through `client.forUser(context.userId)`, so the API answers 404 for a Session outside that End-user's scope.
  */
 export function createChatRelay(options) {
     return async (request) => {
@@ -25,6 +26,7 @@ export function createChatRelay(options) {
             if (!context) {
                 return errorResponse(401, "unauthorized", "Authentication required.");
             }
+            const client = scopeTo(options.client, context.userId);
             const body = chatBodySchema.parse(await request.json());
             const validated = await safeValidateUIMessages({
                 messages: [body.message],
@@ -32,13 +34,9 @@ export function createChatRelay(options) {
             if (!validated.success) {
                 return errorResponse(400, "invalid_request", "Invalid chat message.");
             }
-            if (body.sessionId !== undefined &&
-                (await options.sessions.ownerOf(body.sessionId)) !== context.userId) {
-                return errorResponse(403, "forbidden", "Session is not available.");
-            }
             const message = validated.data[0];
             if (message.role === "assistant") {
-                return await relayApprovalResponses(options.client, {
+                return await relayApprovalResponses(client, {
                     agentId: context.agentId,
                     functions: context.functions,
                     message,
@@ -56,9 +54,8 @@ export function createChatRelay(options) {
                 messageId: body.messageId,
                 metadata: context.metadata,
                 abortSignal: request.signal,
-                userId: context.userId,
             };
-            const result = await options.client.chat(body.sessionId === undefined
+            const result = await client.chat(body.sessionId === undefined
                 ? {
                     ...chatInput,
                     trigger: "submit-message",
@@ -68,19 +65,6 @@ export function createChatRelay(options) {
                     sessionId: body.sessionId,
                     trigger: body.trigger,
                 });
-            const sessionId = await result.sessionId;
-            if (body.sessionId === undefined) {
-                try {
-                    await options.sessions.recordOwner(sessionId, context.userId);
-                }
-                catch (error) {
-                    await result
-                        .toResponse()
-                        .body?.cancel(error)
-                        .catch(() => undefined);
-                    throw error;
-                }
-            }
             return result.toResponse();
         }
         catch (error) {
@@ -89,7 +73,7 @@ export function createChatRelay(options) {
     };
 }
 /**
- * Validates the Session and forwards the last assistant approval round.
+ * Forwards the last assistant approval round to its Session.
  */
 async function relayApprovalResponses(client, { functions, message, request, ...input }) {
     if (input.sessionId === undefined) {
@@ -112,9 +96,9 @@ async function relayApprovalResponses(client, { functions, message, request, ...
     return continuation.toResponse();
 }
 /**
- * Creates an authenticated HTTP handler that validates prompts and relays text generation.
+ * Creates an authenticated HTTP handler that validates prompts and relays text generation as the signed-in End-user.
  * @param options - Configuration for this operation.
- * @returns An HTTP handler that validates prompts and relays text generation.
+ * @returns An HTTP handler that runs each request through `client.forUser(context.userId)`.
  */
 export function createCompletionRelay(options) {
     return async (request) => {
@@ -123,13 +107,13 @@ export function createCompletionRelay(options) {
             if (!context) {
                 return errorResponse(401, "unauthorized", "Authentication required.");
             }
+            const client = scopeTo(options.client, context.userId);
             const body = completionBodySchema.parse(await request.json());
-            const result = await options.client.completion({
+            const result = await client.completion({
                 agentId: context.agentId,
                 metadata: context.metadata,
                 prompt: body.prompt,
                 abortSignal: request.signal,
-                userId: context.userId,
             });
             return result.toResponse();
         }
@@ -138,6 +122,19 @@ export function createCompletionRelay(options) {
         }
     };
 }
+/**
+ * Scopes the client to the resolved End-user. An ID that `forUser` rejects is a
+ * Tenant resolver bug, not a browser error, so it becomes a plain error that
+ * the generic 500 response answers without the validation message.
+ */
+function scopeTo(client, userId) {
+    try {
+        return client.forUser(userId);
+    }
+    catch (cause) {
+        throw new Error("The relay context has an invalid userId.", { cause });
+    }
+}
 /**
  * Maps validation and SDK failures to safe public error responses.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blazingagents/sdk",
-  "version": "0.42.1",
+  "version": "0.43.1",
   "description": "TypeScript SDK for the Blazing Agents API",
   "homepage": "https://docs.blazingagents.com",
   "bugs": {