@blazingagents/sdk 0.15.0 → 0.16.0

package/dist/approvals.d.ts

@@ -0,0 +1,15 @@
+import { type UIMessage } from "ai";
+import type { BlazingAgents } from "./client.ts";
+interface ApprovalTarget {
+    abortSignal?: AbortSignal;
+    agentId: string;
+    sessionId: string;
+}
+/**
+ * Records each approval response in the assistant message's last step and
+ * returns the continuation they decide, or `undefined` when there are none.
+ */
+export declare function decideApprovalResponses(client: Pick<BlazingAgents, "sessions">, { message, ...target }: ApprovalTarget & {
+    message: UIMessage;
+}): Promise<string | undefined>;
+export {};

package/dist/approvals.js

@@ -0,0 +1,20 @@
+import { isToolUIPart } from "ai";
+/**
+ * Records each approval response in the assistant message's last step and
+ * returns the continuation they decide, or `undefined` when there are none.
+ */
+export async function decideApprovalResponses(client, { message, ...target }) {
+    const lastStep = message.parts.findLastIndex((part) => part.type === "step-start");
+    let continuationId;
+    for (const part of message.parts.slice(lastStep + 1)) {
+        if (isToolUIPart(part) && part.state === "approval-responded") {
+            ({ continuationId } = await client.sessions.decideToolApproval({
+                ...target,
+                approvalId: part.approval.id,
+                approved: part.approval.approved,
+                reason: part.approval.reason,
+            }));
+        }
+    }
+    return continuationId;
+}

package/dist/chat-transport.js

@@ -1,4 +1,4 @@
-import { DefaultChatTransport, } from "ai";
+import { DefaultChatTransport, lastAssistantMessageIsCompleteWithApprovalResponses, } from "ai";
 import { sessionIdSchema } from "./contracts/ids.js";
 /**
  * Adapts AI SDK chat requests to the Blazing Agents backend-relay shape and
@@ -31,7 +31,14 @@ export class BlazingAgentsChatTransport {
                 return response;
             },
             prepareSendMessagesRequest: ({ body, messageId, messages, trigger }) => {
-                const message = messages.findLast((candidate) => candidate.role === "user");
+                const approvals = messages.at(-1)?.role === "assistant" &&
+                    lastAssistantMessageIsCompleteWithApprovalResponses({ messages });
+                if (approvals && this.#sessionId === undefined) {
+                    throw new Error("Tool approval requires an existing Session.");
+                }
+                const message = approvals
+                    ? messages.at(-1)
+                    : messages.findLast((candidate) => candidate.role === "user");
                 if (!message) {
                     throw new Error("Chat submission requires a user message.");
                 }

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AgentClient, AgentsResource, ArtifactsResource, BlazingAgentsOptions, BlazingAgentsRequestOptions, ChatConnectionsResource, ChatDeliveriesResource, ChatInput, ChatResult, CompletionInput, CompletionResult, McpConnectionsResource, MemoriesResource, MerchantBindingsResource, MerchantConnectionResource, MerchantUsageEventsResource, ObjectInput, ObjectResult, PromptsResource, ProvidersResource, SessionsResource, TasksResource, TenantResource, UsageResource, UserClient, WorkspacesResource } from "./types.ts";
+import type { AgentClient, AgentsResource, ArtifactsResource, BlazingAgentsOptions, BlazingAgentsRequestOptions, ChatConnectionsResource, ChatDeliveriesResource, ChatInput, ChatResult, CompletionInput, CompletionResult, McpConnectionsResource, MemoriesResource, MerchantBindingsResource, MerchantConnectionResource, MerchantUsageEventsResource, ObjectInput, ObjectResult, PromptsResource, ProvidersResource, ResumeChatInput, SessionsResource, TasksResource, TenantResource, UsageResource, UserClient, WorkspacesResource } from "./types.ts";
 export declare class BlazingAgents {
     private readonly config;
     readonly chatConnections: ChatConnectionsResource;
@@ -29,6 +29,11 @@ export declare class BlazingAgents {
      * session id and a byte-compatible SSE relay for `useChat`.
      */
     chat(input: ChatInput): Promise<ChatResult>;
+    /**
+     * Reattaches function handlers after human tool approval and starts or
+     * joins the Session's continuation. Returns the continuation SSE relay.
+     */
+    resumeChat(input: ResumeChatInput): Promise<ChatResult>;
     /**
      * `POST /v1/agents/:agentId/generation` — stateless one-shot text
      * stream. Returns `textStream` + `await result.text` + `toResponse()`.

package/dist/client.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { chat, completion, objectGeneration } from "./generation.js";
+import { chat, completion, objectGeneration, resumeChat, } from "./generation.js";
 import { createAgentsResource } from "./resources/agents.js";
 import { createArtifactsResource } from "./resources/artifacts.js";
 import { createChatConnectionsResource } from "./resources/chat-connections.js";
@@ -40,6 +40,7 @@ function createUserClient(config) {
         chat: (input) => chat(config, input),
         completion: (input) => completion(config, input),
         object: (input) => objectGeneration(config, input),
+        resumeChat: (input) => resumeChat(config, input),
         withOptions: (options) => createUserClient({ ...config, clientRequestId: options.clientRequestId }),
     };
 }
@@ -106,6 +107,13 @@ export class BlazingAgents {
     chat(input) {
         return chat(this.config, input);
     }
+    /**
+     * Reattaches function handlers after human tool approval and starts or
+     * joins the Session's continuation. Returns the continuation SSE relay.
+     */
+    resumeChat(input) {
+        return resumeChat(this.config, input);
+    }
     /**
      * `POST /v1/agents/:agentId/generation` — stateless one-shot text
      * stream. Returns `textStream` + `await result.text` + `toResponse()`.

package/dist/contracts/api.d.ts

@@ -30,6 +30,7 @@ export declare const apiErrorCodeSchema: z.ZodEnum<{
     chat_webhook_registration_failed: "chat_webhook_registration_failed";
     checkout_evidence_mismatch: "checkout_evidence_mismatch";
     forbidden: "forbidden";
+    function_call_conflict: "function_call_conflict";
     idempotency_conflict: "idempotency_conflict";
     internal: "internal";
     invalid_cursor: "invalid_cursor";
@@ -108,6 +109,7 @@ export declare const apiErrorSchema: z.ZodObject<{
         chat_webhook_registration_failed: "chat_webhook_registration_failed";
         checkout_evidence_mismatch: "checkout_evidence_mismatch";
         forbidden: "forbidden";
+        function_call_conflict: "function_call_conflict";
         idempotency_conflict: "idempotency_conflict";
         internal: "internal";
         invalid_cursor: "invalid_cursor";
@@ -191,6 +193,7 @@ export declare const apiErrorResponseSchema: z.ZodObject<{
             chat_webhook_registration_failed: "chat_webhook_registration_failed";
             checkout_evidence_mismatch: "checkout_evidence_mismatch";
             forbidden: "forbidden";
+            function_call_conflict: "function_call_conflict";
             idempotency_conflict: "idempotency_conflict";
             internal: "internal";
             invalid_cursor: "invalid_cursor";

package/dist/contracts/api.js

@@ -65,6 +65,7 @@ export const apiErrorCodeSchema = z.enum([
     "session_version_mismatch",
     "tool_approval_continuation_not_found",
     "tool_approval_decision_conflict",
+    "function_call_conflict",
     "skill_invalid_archive",
     "skill_invalid_markdown",
     "skill_limit_reached",

package/dist/contracts/entities/agent-approval.d.ts

@@ -28,6 +28,37 @@ export declare const toolReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     connectionId: z.ZodString;
     name: z.ZodString;
 }, z.core.$strict>], "type">;
+/**
+ * Identifies the tool behind one execution or approval record. Caller-local
+ * functions appear here for display and audit only; approval policies keep
+ * `toolReferenceSchema`, so function names never become Agent configuration.
+ */
+export declare const toolExecutionReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"builtin">;
+    name: z.ZodEnum<{
+        activate_skill: "activate_skill";
+        bash: "bash";
+        delete_memory: "delete_memory";
+        edit: "edit";
+        get_memory: "get_memory";
+        glob: "glob";
+        grep: "grep";
+        publish_artifacts: "publish_artifacts";
+        read: "read";
+        save_memory: "save_memory";
+        search_memories: "search_memories";
+        update_memory: "update_memory";
+        write: "write";
+        write_todos: "write_todos";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"mcp">;
+    connectionId: z.ZodString;
+    name: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"function">;
+    name: z.ZodString;
+}, z.core.$strict>], "type">;
 export declare const approvalPolicySchema: z.ZodObject<{
     default: z.ZodEnum<{
         auto: "auto";
@@ -69,4 +100,5 @@ export declare const approvalPolicySchema: z.ZodObject<{
 }, z.core.$strict>;
 export type ApprovalPolicy = z.infer<typeof approvalPolicySchema>;
 export type ToolReference = z.infer<typeof toolReferenceSchema>;
+export type ToolExecutionReference = z.infer<typeof toolExecutionReferenceSchema>;
 export type ApprovalDecision = z.infer<typeof approvalDecisionSchema>;

package/dist/contracts/entities/agent-approval.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { mcpConnectionIdSchema } from "../ids.js";
-import { AGENT_TOOL_CATALOG } from "./agent-tools.js";
+import { AGENT_TOOL_CATALOG, chatFunctionNameSchema } from "./agent-tools.js";
 export const approvalDecisionSchema = z.enum([
     "full",
     "deny",
@@ -25,6 +25,17 @@ export const toolReferenceSchema = z.discriminatedUnion("type", [
     })
         .strict(),
 ]);
+/**
+ * Identifies the tool behind one execution or approval record. Caller-local
+ * functions appear here for display and audit only; approval policies keep
+ * `toolReferenceSchema`, so function names never become Agent configuration.
+ */
+export const toolExecutionReferenceSchema = z.discriminatedUnion("type", [
+    ...toolReferenceSchema.options,
+    z
+        .object({ type: z.literal("function"), name: chatFunctionNameSchema })
+        .strict(),
+]);
 export const approvalPolicySchema = z
     .object({
     default: approvalDecisionSchema,

package/dist/contracts/entities/agent-tools.d.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /** Tool groups an Agent can attach. File operations use its durable Workspace. */
 export declare const agentToolGroupIds: readonly ["workspace", "write_todos", "memory"];
 export type AgentToolGroupId = (typeof agentToolGroupIds)[number];
@@ -24,3 +25,8 @@ export declare const AGENT_TOOL_CATALOG: readonly [{
     readonly tools: readonly ["save_memory", "get_memory", "search_memories", "update_memory", "delete_memory"];
 }];
 export declare function expandToolGroups(ids: Iterable<string>): Set<string>;
+/**
+ * A model-facing tool name. Built-in tool names and the `mcp__` prefix used
+ * for MCP tools are reserved so a caller function never shadows them.
+ */
+export declare const chatFunctionNameSchema: z.ZodString;

package/dist/contracts/entities/agent-tools.js

@@ -1,3 +1,4 @@
+import { z } from "zod";
 /** Tool groups an Agent can attach. File operations use its durable Workspace. */
 export const agentToolGroupIds = [
     "workspace",
@@ -50,3 +51,15 @@ export function expandToolGroups(ids) {
     }
     return result;
 }
+const RESERVED_CHAT_FUNCTION_NAMES = new Set([
+    ...AGENT_TOOL_CATALOG.flatMap((group) => group.tools),
+    "activate_skill",
+]);
+/**
+ * A model-facing tool name. Built-in tool names and the `mcp__` prefix used
+ * for MCP tools are reserved so a caller function never shadows them.
+ */
+export const chatFunctionNameSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_-]{0,63}$/)
+    .refine((name) => !(RESERVED_CHAT_FUNCTION_NAMES.has(name) || name.startsWith("mcp__")), { message: "Function name is reserved for a built-in or MCP tool." });

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

@@ -97,6 +97,75 @@ type ExclusivePromptInput<Literal extends object> = (Literal & {
     promptId: string;
     variables?: z.infer<typeof promptVariablesSchema>;
 });
+/**
+ * The JSON Schema accepted by structured generation. Zod's JSON Schema
+ * compiler (`z.fromJSONSchema`) is the single authority for the supported
+ * feature set: anything it can convert is accepted, anything it cannot
+ * (unresolvable references, unsupported keywords, …) is rejected at this
+ * untrusted boundary. The only product restriction on top is the documented
+ * "at least a schema root" rule, which keeps the empty match-anything schema
+ * out of object mode. Composition roots are needed for schemas derived from
+ * unions (for example, Pydantic's `int | None` TypeAdapter schema), and local
+ * `$ref` roots are needed for recursive Pydantic models.
+ */
+export declare const jsonSchemaShapeSchema: z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>;
+export declare const MAX_CHAT_FUNCTIONS = 32;
+export declare const MAX_CHAT_FUNCTION_DEFINITIONS_BYTES: number;
+export declare const MAX_CHAT_FUNCTION_PAYLOAD_BYTES: number;
+export declare const jsonByteLength: (value: unknown) => number;
+/** One caller-local function as sent to Blazing Agents: description and JSON Schema only. */
+export declare const chatFunctionDefinitionSchema: z.ZodObject<{
+    description: z.ZodString;
+    inputSchema: z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>;
+}, z.core.$strict>;
+export declare const chatFunctionDefinitionsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    description: z.ZodString;
+    inputSchema: z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>;
+}, z.core.$strict>>;
+/**
+ * Transient UI data part that authorizes one claim attempt for a function
+ * call. The SDK consumes it and never forwards it to the browser.
+ */
+export declare const chatFunctionCallEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"data-ba-function-call">;
+    data: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        input: z.ZodJSONSchema;
+        deadlineAt: z.ZodISODateTime;
+    }, z.core.$strip>;
+    transient: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export declare const chatFunctionOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"output">;
+    value: z.ZodJSONSchema;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"error">;
+    message: z.ZodString;
+}, z.core.$strict>], "kind">;
+/** `POST .../function-calls/{functionCallId}/claim` body. */
+export declare const claimChatFunctionBodySchema: z.ZodObject<{
+    claimRequestId: z.ZodUUID;
+}, z.core.$strict>;
+export declare const claimChatFunctionResponseSchema: z.ZodObject<{
+    claimed: z.ZodLiteral<true>;
+}, z.core.$strip>;
+/** `POST .../function-calls/{functionCallId}/result` body. */
+export declare const resolveChatFunctionBodySchema: z.ZodObject<{
+    claimRequestId: z.ZodUUID;
+    outcome: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"output">;
+        value: z.ZodJSONSchema;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"error">;
+        message: z.ZodString;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export declare const resolveChatFunctionResponseSchema: z.ZodObject<{
+    accepted: z.ZodLiteral<true>;
+}, z.core.$strip>;
+/** `POST .../tool-approval-continuations/{continuationId}/resume` body. */
+export declare const resumeToolApprovalContinuationBodySchema: z.ZodObject<{}, z.core.$strict>;
 /**
  * `POST /v1/agents/{agentId}/sessions` (create) and
  * `POST /v1/agents/{agentId}/sessions/{sessionId}` (resume) request body.
@@ -117,6 +186,10 @@ export declare const chatRequestBodySchema: z.ZodObject<{
     version: z.ZodOptional<z.ZodNumber>;
     userId: z.ZodDefault<z.ZodString>;
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    functions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodString;
+        inputSchema: z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>;
+    }, z.core.$strict>>>;
 }, z.core.$strict> & z.ZodType<{
     message?: unknown;
     promptId?: string | undefined;
@@ -126,6 +199,10 @@ export declare const chatRequestBodySchema: z.ZodObject<{
     version?: number | undefined;
     userId: string;
     metadata: Record<string, unknown>;
+    functions?: Record<string, {
+        description: string;
+        inputSchema: z.core.JSONSchema.JSONSchema;
+    }> | undefined;
 } & ExclusivePromptInput<{
     message: null | NonNullable<unknown>;
 }>, {
@@ -137,6 +214,10 @@ export declare const chatRequestBodySchema: z.ZodObject<{
     version?: number | undefined;
     userId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
+    functions?: Record<string, {
+        description: string;
+        inputSchema: z.core.JSONSchema.JSONSchema;
+    }> | undefined;
 }, z.core.$ZodTypeInternals<{
     message?: unknown;
     promptId?: string | undefined;
@@ -146,6 +227,10 @@ export declare const chatRequestBodySchema: z.ZodObject<{
     version?: number | undefined;
     userId: string;
     metadata: Record<string, unknown>;
+    functions?: Record<string, {
+        description: string;
+        inputSchema: z.core.JSONSchema.JSONSchema;
+    }> | undefined;
 } & ExclusivePromptInput<{
     message: null | NonNullable<unknown>;
 }>, {
@@ -157,19 +242,11 @@ export declare const chatRequestBodySchema: z.ZodObject<{
     version?: number | undefined;
     userId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
+    functions?: Record<string, {
+        description: string;
+        inputSchema: z.core.JSONSchema.JSONSchema;
+    }> | undefined;
 }>>;
-/**
- * The JSON Schema accepted by structured generation. Zod's JSON Schema
- * compiler (`z.fromJSONSchema`) is the single authority for the supported
- * feature set: anything it can convert is accepted, anything it cannot
- * (unresolvable references, unsupported keywords, …) is rejected at this
- * untrusted boundary. The only product restriction on top is the documented
- * "at least a schema root" rule, which keeps the empty match-anything schema
- * out of object mode. Composition roots are needed for schemas derived from
- * unions (for example, Pydantic's `int | None` TypeAdapter schema), and local
- * `$ref` roots are needed for recursive Pydantic models.
- */
-export declare const jsonSchemaShapeSchema: z.ZodCustom<z.core.JSONSchema.JSONSchema, z.core.JSONSchema.JSONSchema>;
 /**
  * `POST /v1/agents/{agentId}/generation` — the single stateless generation
  * boundary. Output selection is explicit on the wire while prompt selection
@@ -264,3 +341,9 @@ export type ChatRequestBody = z.infer<typeof chatRequestBodySchema>;
 export type GenerationRequestBody = z.infer<typeof generationRequestBodySchema>;
 export type ChatStreamErrorChunk = z.infer<typeof chatStreamErrorChunkSchema>;
 export type PromptVariables = z.infer<typeof promptVariablesSchema>;
+export type ChatFunctionDefinition = z.infer<typeof chatFunctionDefinitionSchema>;
+export type ChatFunctionDefinitions = z.infer<typeof chatFunctionDefinitionsSchema>;
+export type ChatFunctionCallEvent = z.infer<typeof chatFunctionCallEventSchema>;
+export type ChatFunctionOutcome = z.infer<typeof chatFunctionOutcomeSchema>;
+export type ClaimChatFunctionBody = z.infer<typeof claimChatFunctionBodySchema>;
+export type ResolveChatFunctionBody = z.infer<typeof resolveChatFunctionBodySchema>;

package/dist/contracts/entities/chat.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { agentIdSchema, promptIdSchema, sessionIdSchema, tenantIdSchema, turnIdSchema, } from "../ids.js";
+import { agentIdSchema, functionCallIdSchema, promptIdSchema, sessionIdSchema, tenantIdSchema, turnIdSchema, } from "../ids.js";
+import { chatFunctionNameSchema } from "./agent-tools.js";
 import { agentModelIdSchema, agentVersionNumberSchema } from "./agents.js";
 import { metadataSchema, userIdSchema } from "./attribution.js";
 export const chatModeSchema = z.enum(["create", "resume"]);
@@ -60,41 +61,6 @@ export const blazingAgentsChatMessageMetadataSchema = z
  * against the template (missing or unknown variable → 400 invalid_request).
  */
 export const promptVariablesSchema = z.record(z.string(), z.string());
-/**
- * `POST /v1/agents/{agentId}/sessions` (create) and
- * `POST /v1/agents/{agentId}/sessions/{sessionId}` (resume) request body.
- * The URL selects the mode; on create the platform mints the `ss_` id and
- * returns it in `Location`. Exactly one of `message` or `promptId` is
- * required, and `variables` requires `promptId`. Regenerate is resume-only,
- * enforced by the route layer rather than this schema.
- */
-export const chatRequestBodySchema = z
-    .object({
-    /**
-     * AI SDK owns the runtime UIMessage schema. Core keeps this wire field
-     * unknown; the HTTP boundary validates it with `safeValidateUIMessages`
-     * before treating it as a UIMessage.
-     */
-    message: z.unknown().optional(),
-    promptId: promptIdSchema.optional(),
-    variables: promptVariablesSchema.optional(),
-    trigger: chatTriggerSchema.default("submit-message"),
-    messageId: z.string().min(1).optional(),
-    version: agentVersionNumberSchema.optional(),
-    /**
-     * End-user attribution (ADR-0001), stamped on the Session at lazy
-     * materialization and on every usage row this Turn records.
-     */
-    userId: userIdSchema.default(""),
-    metadata: metadataSchema.default({}),
-})
-    .strict()
-    .refine((body) => body.message === undefined
-    ? body.promptId !== undefined
-    : body.promptId === undefined && body.variables === undefined, {
-    message: "Provide either `message` or `promptId` (+`variables`); they are mutually exclusive, and `variables` is only allowed with `promptId`.",
-    path: ["message"],
-});
 const JSON_SCHEMA_COMPOSITION_KEYS = ["allOf", "anyOf", "oneOf"];
 function hasMeaningfulSchemaRoot(value, definitions, seenReferences) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
@@ -152,6 +118,109 @@ export const jsonSchemaShapeSchema = z.custom((value) => {
         return false;
     }
 }, { message: "schema contains an unsupported or invalid JSON Schema feature" });
+export const MAX_CHAT_FUNCTIONS = 32;
+export const MAX_CHAT_FUNCTION_DEFINITIONS_BYTES = 64 * 1024;
+export const MAX_CHAT_FUNCTION_PAYLOAD_BYTES = 256 * 1024;
+export const jsonByteLength = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength;
+/** One caller-local function as sent to Blazing Agents: description and JSON Schema only. */
+export const chatFunctionDefinitionSchema = z
+    .object({
+    description: z.string().trim().min(1),
+    inputSchema: jsonSchemaShapeSchema.refine((schema) => typeof schema === "object" && schema.type === "object", { message: "Function input schema must describe a JSON object." }),
+})
+    .strict();
+export const chatFunctionDefinitionsSchema = z
+    .record(chatFunctionNameSchema, chatFunctionDefinitionSchema)
+    .refine((functions) => Object.keys(functions).length <= MAX_CHAT_FUNCTIONS, {
+    message: `At most ${MAX_CHAT_FUNCTIONS} functions are allowed.`,
+})
+    .refine((functions) => jsonByteLength(functions) <= MAX_CHAT_FUNCTION_DEFINITIONS_BYTES, {
+    message: `Function definitions must not exceed ${MAX_CHAT_FUNCTION_DEFINITIONS_BYTES} bytes.`,
+});
+/**
+ * Transient UI data part that authorizes one claim attempt for a function
+ * call. The SDK consumes it and never forwards it to the browser.
+ */
+export const chatFunctionCallEventSchema = z
+    .object({
+    type: z.literal("data-ba-function-call"),
+    data: z
+        .object({
+        id: functionCallIdSchema,
+        name: chatFunctionNameSchema,
+        input: z.json(),
+        deadlineAt: z.iso.datetime({ offset: true }),
+    })
+        .strip(),
+    transient: z.literal(true),
+})
+    .strip();
+export const chatFunctionOutcomeSchema = z
+    .discriminatedUnion("kind", [
+    z.object({ kind: z.literal("output"), value: z.json() }).strict(),
+    z
+        .object({
+        kind: z.literal("error"),
+        message: z.string().min(1).max(4096),
+    })
+        .strict(),
+])
+    .refine((outcome) => jsonByteLength(outcome) <= MAX_CHAT_FUNCTION_PAYLOAD_BYTES, {
+    message: `Function outcome must not exceed ${MAX_CHAT_FUNCTION_PAYLOAD_BYTES} bytes.`,
+});
+/** `POST .../function-calls/{functionCallId}/claim` body. */
+export const claimChatFunctionBodySchema = z
+    .object({ claimRequestId: z.uuid() })
+    .strict();
+export const claimChatFunctionResponseSchema = z
+    .object({ claimed: z.literal(true) })
+    .strip();
+/** `POST .../function-calls/{functionCallId}/result` body. */
+export const resolveChatFunctionBodySchema = z
+    .object({ claimRequestId: z.uuid(), outcome: chatFunctionOutcomeSchema })
+    .strict();
+export const resolveChatFunctionResponseSchema = z
+    .object({ accepted: z.literal(true) })
+    .strip();
+/** `POST .../tool-approval-continuations/{continuationId}/resume` body. */
+export const resumeToolApprovalContinuationBodySchema = z.object({}).strict();
+/**
+ * `POST /v1/agents/{agentId}/sessions` (create) and
+ * `POST /v1/agents/{agentId}/sessions/{sessionId}` (resume) request body.
+ * The URL selects the mode; on create the platform mints the `ss_` id and
+ * returns it in `Location`. Exactly one of `message` or `promptId` is
+ * required, and `variables` requires `promptId`. Regenerate is resume-only,
+ * enforced by the route layer rather than this schema.
+ */
+export const chatRequestBodySchema = z
+    .object({
+    /**
+     * AI SDK owns the runtime UIMessage schema. Core keeps this wire field
+     * unknown; the HTTP boundary validates it with `safeValidateUIMessages`
+     * before treating it as a UIMessage.
+     */
+    message: z.unknown().optional(),
+    promptId: promptIdSchema.optional(),
+    variables: promptVariablesSchema.optional(),
+    trigger: chatTriggerSchema.default("submit-message"),
+    messageId: z.string().min(1).optional(),
+    version: agentVersionNumberSchema.optional(),
+    /**
+     * End-user attribution (ADR-0001), stamped on the Session at lazy
+     * materialization and on every usage row this Turn records.
+     */
+    userId: userIdSchema.default(""),
+    metadata: metadataSchema.default({}),
+    /** Caller-local functions for this invocation; handlers stay in the caller's backend. */
+    functions: chatFunctionDefinitionsSchema.optional(),
+})
+    .strict()
+    .refine((body) => body.message === undefined
+    ? body.promptId !== undefined
+    : body.promptId === undefined && body.variables === undefined, {
+    message: "Provide either `message` or `promptId` (+`variables`); they are mutually exclusive, and `variables` is only allowed with `promptId`.",
+    path: ["message"],
+});
 /**
  * `POST /v1/agents/{agentId}/generation` — the single stateless generation
  * boundary. Output selection is explicit on the wire while prompt selection

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

@@ -151,6 +151,9 @@ export declare const toolApprovalStateSchema: z.ZodObject<{
         type: z.ZodLiteral<"mcp">;
         connectionId: z.ZodString;
         name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        name: z.ZodString;
     }, z.core.$strict>], "type">>>;
     assistantMessageId: z.ZodOptional<z.ZodString>;
     createdAt: z.ZodOptional<z.ZodISODateTime>;
@@ -200,6 +203,9 @@ export declare const toolApprovalsResponseSchema: z.ZodObject<{
             type: z.ZodLiteral<"mcp">;
             connectionId: z.ZodString;
             name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"function">;
+            name: z.ZodString;
         }, z.core.$strict>], "type">>>;
         assistantMessageId: z.ZodOptional<z.ZodString>;
         createdAt: z.ZodOptional<z.ZodISODateTime>;

package/dist/contracts/entities/sessions.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { paginatedResponseSchema } from "../api.js";
 import { agentIdSchema, sessionIdSchema } from "../ids.js";
 import { DEFAULT_SESSION_MESSAGES_LIMIT, MAX_SESSION_MESSAGES_LIMIT, } from "../limitations.js";
-import { toolReferenceSchema } from "./agent-approval.js";
+import { toolExecutionReferenceSchema } from "./agent-approval.js";
 import { agentSchema, agentVersionNumberSchema } from "./agents.js";
 import { metadataSchema, userIdSchema } from "./attribution.js";
 /**
@@ -104,7 +104,7 @@ export const toolApprovalContinuationStateSchema = z.enum([
 ]);
 export const toolApprovalStateSchema = z
     .object({
-    tool: toolReferenceSchema.nullable().optional(),
+    tool: toolExecutionReferenceSchema.nullable().optional(),
     assistantMessageId: z.string().min(1).optional(),
     createdAt: z.iso.datetime({ offset: true }).optional(),
     decidedAt: z.iso.datetime({ offset: true }).nullable().optional(),

package/dist/contracts/ids.d.ts

@@ -46,6 +46,7 @@ export declare const promptIdSchema: z.ZodString;
 export declare const requestIdSchema: z.ZodString;
 export declare const checkoutAttemptIdSchema: z.ZodString;
 export declare const turnIdSchema: z.ZodString;
+export declare const functionCallIdSchema: z.ZodString;
 export declare const skillIdSchema: z.ZodString;
 /**
  * API key token + digest helpers. The digest is sha256 hex (64 chars); the

package/dist/contracts/ids.js

@@ -72,6 +72,7 @@ export const promptIdSchema = z.string().regex(/^prompt_[0-9A-Za-z]{16}$/);
 export const requestIdSchema = z.string().regex(/^req_[0-9A-Za-z]{16}$/);
 export const checkoutAttemptIdSchema = z.string().regex(/^ca_[0-9A-Za-z]{16}$/);
 export const turnIdSchema = z.string().regex(/^turn_[0-9A-Za-z]{16}$/);
+export const functionCallIdSchema = z.string().regex(/^fc_[0-9A-Za-z]{16}$/);
 export const skillIdSchema = z.string().regex(/^skill_[0-9A-Za-z]{16}$/);
 /**
  * API key token + digest helpers. The digest is sha256 hex (64 chars); the

package/dist/contracts/index.d.ts

@@ -1,12 +1,13 @@
 /** Public runtime schemas for the Blazing Agents HTTP API. */
 export { receivedApiErrorResponseSchema } from "./api.ts";
-export type { ApprovalDecision, ApprovalPolicy, ToolReference, } from "./entities/agent-approval.ts";
-export { approvalDecisionSchema, approvalPolicySchema, toolReferenceSchema, } from "./entities/agent-approval.ts";
+export type { ApprovalDecision, ApprovalPolicy, ToolExecutionReference, ToolReference, } from "./entities/agent-approval.ts";
+export { approvalDecisionSchema, approvalPolicySchema, toolExecutionReferenceSchema, toolReferenceSchema, } from "./entities/agent-approval.ts";
+export { chatFunctionNameSchema } from "./entities/agent-tools.ts";
 export { agentResponseSchema, agentSchema, agentStatusSchema, agentsListQuerySchema, agentsResponseSchema, agentVersionSchema, agentVersionsResponseSchema, createAgentBodySchema, updateAgentBodySchema, } from "./entities/agents.ts";
 export { artifactDownloadUrlResponseSchema, artifactListItemSchema, artifactsListResponseSchema, } from "./entities/artifacts.ts";
 export { attributionCreateInputSchema, metadataSchema, } from "./entities/attribution.ts";
-export type { PromptVariables, UsageSummary } from "./entities/chat.ts";
-export { blazingAgentsChatMessageMetadataSchema, chatModeSchema, chatRequestBodySchema, chatTriggerSchema, generationRequestBodySchema, jsonSchemaShapeSchema, promptVariablesSchema, usageSummarySchema, } from "./entities/chat.ts";
+export type { ChatFunctionCallEvent, ChatFunctionDefinition, ChatFunctionDefinitions, ChatFunctionOutcome, ClaimChatFunctionBody, PromptVariables, ResolveChatFunctionBody, UsageSummary, } from "./entities/chat.ts";
+export { blazingAgentsChatMessageMetadataSchema, chatFunctionCallEventSchema, chatFunctionDefinitionSchema, chatFunctionDefinitionsSchema, chatFunctionOutcomeSchema, chatModeSchema, chatRequestBodySchema, chatTriggerSchema, claimChatFunctionBodySchema, claimChatFunctionResponseSchema, generationRequestBodySchema, jsonSchemaShapeSchema, MAX_CHAT_FUNCTION_DEFINITIONS_BYTES, MAX_CHAT_FUNCTION_PAYLOAD_BYTES, MAX_CHAT_FUNCTIONS, promptVariablesSchema, resolveChatFunctionBodySchema, resolveChatFunctionResponseSchema, resumeToolApprovalContinuationBodySchema, usageSummarySchema, } from "./entities/chat.ts";
 export { chatConfigurationSchema, chatConnectionSchema, chatConnectionsResponseSchema, chatCredentialsSchema, chatDeliveriesResponseSchema, chatDeliveryListStatusSchema, chatDeliverySchema, chatDeliveryStatusSchema, chatHealthCheckSchema, chatHealthSchema, chatIdentitySchema, createChatConnectionBodySchema, rotateChatConnectionBodySchema, tenantChatDeliverySchema, updateChatConnectionBodySchema, } from "./entities/chat-connections.ts";
 export { approveMcpOauthAuthorizationBodySchema, createMcpConnectionBodySchema, mcpAttachmentResponseSchema, mcpAttachmentsResponseSchema, mcpConnectionAuthTypeSchema, mcpConnectionOauthConnectResponseSchema, mcpConnectionReconnectResultSchema, mcpConnectionResponseSchema, mcpConnectionStatusSchema, mcpConnectionsResponseSchema, mcpConnectionTestErrorCodeSchema, mcpConnectionTestResponseSchema, mcpOauthAuthorizationLaunchResponseSchema, reconnectMcpConnectionBodySchema, updateMcpAttachmentBodySchema, updateMcpConnectionBodySchema, } from "./entities/mcp-connections.ts";
 export { createMemoryBodySchema, memoriesListResponseSchema, memoryResponseSchema, memorySchema, updateMemoryBodySchema, } from "./entities/memories.ts";
@@ -21,4 +22,4 @@ export { quotaSchema, subscriptionStatusSchema, tenantDeletionSchema, tenantResp
 export type { SessionUsageQuery, SessionUsageResponse, UsageBucket, UsageOverviewQuery, UsageOverviewResponse, UsageResponse, UsageTotals, } from "./entities/usage.ts";
 export { sessionUsageQuerySchema, sessionUsageResponseSchema, usageOverviewQuerySchema, usageOverviewResponseSchema, usageResponseSchema, } from "./entities/usage.ts";
 export { createWorkspaceBodySchema, updateWorkspaceBodySchema, workspaceSchema, workspacesListResponseSchema, } from "./entities/workspaces.ts";
-export { agentIdSchema, apiKeyTokenSchema, isAdminAgentId, promptIdSchema, sessionIdSchema, } from "./ids.ts";
+export { agentIdSchema, apiKeyTokenSchema, functionCallIdSchema, isAdminAgentId, promptIdSchema, sessionIdSchema, } from "./ids.ts";