@blazingagents/sdk 0.14.0 → 0.16.0

package/dist/contracts/entities/agents.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { cursorSchema, paginatedResponseSchema } from "../api.js";
 import { agentIdSchema, mcpConnectionIdSchema, providerIdSchema, tenantIdSchema, workspaceIdSchema, } from "../ids.js";
-import { DEFAULT_AGENT_VERSIONS_LIST_LIMIT, MAX_AGENT_INSTRUCTIONS_LENGTH, MAX_AGENT_NAME_LENGTH, MAX_AGENT_VERSIONS_LIST_LIMIT, MAX_MCP_CONNECTIONS_PER_AGENT, } from "../limitations.js";
+import { DEFAULT_AGENT_VERSIONS_LIST_LIMIT, DEFAULT_AGENTS_LIST_LIMIT, MAX_AGENT_INSTRUCTIONS_LENGTH, MAX_AGENT_NAME_LENGTH, MAX_AGENT_VERSIONS_LIST_LIMIT, MAX_AGENTS_LIST_LIMIT, MAX_MCP_CONNECTIONS_PER_AGENT, } from "../limitations.js";
 import { atLeastOneFieldMessage, hasObjectKeys, hasUniqueValues, } from "../utils.js";
 import { approvalPolicySchema } from "./agent-approval.js";
 import { agentToolGroupIds } from "./agent-tools.js";
@@ -77,14 +77,17 @@ export const agentSchema = z
     message: providerModelPairMessage,
     path: ["providerId"],
 });
-export const agentsResponseSchema = z
-    .object({
-    agents: z.array(agentSchema),
-})
-    .strip();
+export const agentsResponseSchema = paginatedResponseSchema(agentSchema);
 export const agentResponseSchema = agentSchema;
 export const agentsListQuerySchema = z
     .object({
+    cursor: cursorSchema.optional(),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_AGENTS_LIST_LIMIT)
+        .default(DEFAULT_AGENTS_LIST_LIMIT),
     userId: userIdSchema.optional(),
     workspaceId: workspaceIdSchema.optional(),
 })

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/prompts.d.ts

@@ -20,7 +20,7 @@ export declare const promptSchema: z.ZodObject<{
     updatedAt: z.ZodISODateTime;
 }, z.core.$strip>;
 export declare const promptsResponseSchema: z.ZodObject<{
-    prompts: z.ZodArray<z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         tenantId: z.ZodString;
         agentId: z.ZodNullable<z.ZodString>;
@@ -32,7 +32,14 @@ export declare const promptsResponseSchema: z.ZodObject<{
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
     }, z.core.$strip>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+export declare const promptsListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    userId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 export declare const promptResponseSchema: z.ZodObject<{
     id: z.ZodString;
     tenantId: z.ZodString;
@@ -61,6 +68,7 @@ export declare const updatePromptBodySchema: z.ZodObject<{
 export declare function renderPromptTemplate(template: string, values: Record<string, string>): string;
 export type Prompt = z.infer<typeof promptSchema>;
 export type PromptsResponse = z.infer<typeof promptsResponseSchema>;
+export type PromptsListQuery = z.infer<typeof promptsListQuerySchema>;
 export type PromptResponse = z.infer<typeof promptResponseSchema>;
 export type CreatePromptBody = z.input<typeof createPromptBodySchema>;
 export type UpdatePromptBody = z.infer<typeof updatePromptBodySchema>;

package/dist/contracts/entities/prompts.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { cursorSchema, paginatedResponseSchema } from "../api.js";
 import { agentIdSchema, promptIdSchema, tenantIdSchema } from "../ids.js";
-import { MAX_PROMPT_NAME_LENGTH, MAX_PROMPT_TEMPLATE_BYTES, MAX_PROMPT_VARIABLES, } from "../limitations.js";
+import { DEFAULT_PROMPTS_LIST_LIMIT, MAX_PROMPT_NAME_LENGTH, MAX_PROMPT_TEMPLATE_BYTES, MAX_PROMPT_VARIABLES, MAX_PROMPTS_LIST_LIMIT, } from "../limitations.js";
 import { atLeastOneFieldMessage, hasObjectKeys } from "../utils.js";
 import { metadataSchema, userIdSchema } from "./attribution.js";
 export const promptVariableTokenPattern = /{{([\s\S]*?)}}/g;
@@ -59,11 +60,20 @@ export const promptSchema = z
     updatedAt: z.iso.datetime({ offset: true }),
 })
     .strip();
-export const promptsResponseSchema = z
+export const promptsResponseSchema = paginatedResponseSchema(promptSchema);
+export const promptsListQuerySchema = z
     .object({
-    prompts: z.array(promptSchema),
+    cursor: cursorSchema.optional(),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PROMPTS_LIST_LIMIT)
+        .default(DEFAULT_PROMPTS_LIST_LIMIT),
+    userId: userIdSchema.optional(),
+    agentId: agentIdSchema.optional(),
 })
-    .strip();
+    .strict();
 export const promptResponseSchema = promptSchema;
 export const createPromptBodySchema = z
     .object({

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/entities/tasks.d.ts

@@ -44,12 +44,9 @@ export declare const taskScheduleInputSchema: z.ZodDiscriminatedUnion<[z.ZodObje
 export type TaskScheduleInput = z.infer<typeof taskScheduleInputSchema>;
 /**
  * `POST /v1/tasks` — schedule present = scheduled task; absent = on-demand.
- * `submit: true` enqueues a run immediately (on-demand's only trigger
- * alongside creation) with a server-minted random run id. This path is
- * NOT idempotent — each call creates a new task + new run. For run-level
- * idempotency, use `POST /v1/tasks/{taskId}/runs` with an idempotency key
- * (the task must already exist so the deterministic run id is stable
- * across replays).
+ * `submit: true` enqueues a run immediately. An optional `idempotencyKey`
+ * makes retries return the original Task and initial run id. Without a key,
+ * each call creates a new Task. Run creation has its own idempotency key.
  */
 export declare const createTaskBodySchema: z.ZodObject<{
     agentId: z.ZodString;
@@ -76,6 +73,7 @@ export declare const createTaskBodySchema: z.ZodObject<{
     }, z.core.$strict>], "kind">>>;
     enabled: z.ZodDefault<z.ZodBoolean>;
     submit: z.ZodDefault<z.ZodBoolean>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
     userId: z.ZodDefault<z.ZodString>;
     metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>;

package/dist/contracts/entities/tasks.js

@@ -106,12 +106,9 @@ const taskNameSchema = z.string().trim().min(1).max(MAX_TASK_NAME_LENGTH);
 const taskPromptSchema = z.string().trim().min(1).max(MAX_TASK_PROMPT_LENGTH);
 /**
  * `POST /v1/tasks` — schedule present = scheduled task; absent = on-demand.
- * `submit: true` enqueues a run immediately (on-demand's only trigger
- * alongside creation) with a server-minted random run id. This path is
- * NOT idempotent — each call creates a new task + new run. For run-level
- * idempotency, use `POST /v1/tasks/{taskId}/runs` with an idempotency key
- * (the task must already exist so the deterministic run id is stable
- * across replays).
+ * `submit: true` enqueues a run immediately. An optional `idempotencyKey`
+ * makes retries return the original Task and initial run id. Without a key,
+ * each call creates a new Task. Run creation has its own idempotency key.
  */
 export const createTaskBodySchema = z
     .object({
@@ -122,6 +119,7 @@ export const createTaskBodySchema = z
     schedule: taskScheduleInputSchema.nullable().default(null),
     enabled: z.boolean().default(true),
     submit: z.boolean().default(false),
+    idempotencyKey: z.string().trim().min(1).optional(),
     userId: userIdSchema.default(""),
     metadata: metadataSchema.default({}),
 })

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

@@ -77,6 +77,22 @@ export declare const usageTotalsSchema: z.ZodObject<{
     requestCount: z.ZodNumber;
     durationMs: z.ZodNumber;
 }, z.core.$strip>;
+export declare const sessionUsageQuerySchema: z.ZodObject<{
+    sessionIds: z.ZodArray<z.ZodString>;
+    from: z.ZodOptional<z.ZodISODate>;
+    to: z.ZodOptional<z.ZodISODate>;
+}, z.core.$strict>;
+export declare const sessionUsageResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        sessionId: z.ZodString;
+        totals: z.ZodObject<{
+            inputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            requestCount: z.ZodNumber;
+            durationMs: z.ZodNumber;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export declare const usageResponseSchema: z.ZodObject<{
     buckets: z.ZodArray<z.ZodObject<{
         day: z.ZodNullable<z.ZodString>;
@@ -224,3 +240,5 @@ export type UsageTotals = z.infer<typeof usageTotalsSchema>;
 export type UsageResponse = z.infer<typeof usageResponseSchema>;
 export type UsageOverviewQuery = z.infer<typeof usageOverviewQuerySchema>;
 export type UsageOverviewResponse = z.infer<typeof usageOverviewResponseSchema>;
+export type SessionUsageQuery = z.infer<typeof sessionUsageQuerySchema>;
+export type SessionUsageResponse = z.infer<typeof sessionUsageResponseSchema>;

package/dist/contracts/entities/usage.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { agentIdSchema, sessionIdSchema } from "../ids.js";
 import { DEFAULT_USAGE_OVERVIEW_TOP_N, DEFAULT_USAGE_RANGE_DAYS, DEFAULT_USAGE_SESSION_TOP_N, MAX_USAGE_OVERVIEW_TOP_N, MAX_USAGE_RANGE_DAYS, MAX_USAGE_SESSION_TOP_N, } from "../limitations.js";
+import { hasUniqueValues } from "../utils.js";
 import { userIdSchema } from "./attribution.js";
 function validateUsageRange(value, ctx) {
     if ((value.from === undefined) !== (value.to === undefined)) {
@@ -122,6 +123,33 @@ export const usageTotalsSchema = z
     durationMs: z.number().int().nonnegative(),
 })
     .strip();
+export const sessionUsageQuerySchema = z
+    .object({
+    sessionIds: z
+        .array(sessionIdSchema)
+        .min(1)
+        .max(100)
+        .refine(hasUniqueValues, {
+        message: "Session ids must be unique.",
+    }),
+    from: z.iso.date().optional(),
+    to: z.iso.date().optional(),
+})
+    .strict()
+    .superRefine(validateUsageRange);
+export const sessionUsageResponseSchema = z
+    .object({
+    data: z
+        .array(z
+        .object({
+        sessionId: sessionIdSchema,
+        totals: usageTotalsSchema,
+    })
+        .strip())
+        .min(1)
+        .max(100),
+})
+    .strip();
 export const usageResponseSchema = z
     .object({
     buckets: z.array(usageBucketSchema),

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,24 +1,25 @@
 /** 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 { agentResponseSchema, agentSchema, agentStatusSchema, agentsResponseSchema, agentVersionSchema, agentVersionsResponseSchema, createAgentBodySchema, updateAgentBodySchema, } from "./entities/agents.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";
 export { createMerchantConnectionBodySchema, merchantBindingResponseSchema, merchantBindingsResponseSchema, merchantConnectionResponseSchema, merchantConnectionSchema, merchantConnectionStatusSchema, merchantCustomerBindingSchema, merchantEnvironmentSchema, merchantGuardSchema, merchantProviderSchema, merchantUsageEventNextAction, merchantUsageEventNextActionSchema, merchantUsageEventSchema, merchantUsageEventStatusSchema, merchantUsageEventsResponseSchema, merchantUsageSummaryQuerySchema, merchantUsageSummaryResponseSchema, merchantUsageSummarySchema, merchantWorkflowIssueSchema, updateMerchantConnectionBodySchema, upsertMerchantBindingBodySchema, } from "./entities/merchant.ts";
-export { createPromptBodySchema, parsePromptVariables, promptResponseSchema, promptSchema, promptsResponseSchema, promptTemplateSchema, renderPromptTemplate, updatePromptBodySchema, } from "./entities/prompts.ts";
+export { createPromptBodySchema, parsePromptVariables, promptResponseSchema, promptSchema, promptsListQuerySchema, promptsResponseSchema, promptTemplateSchema, renderPromptTemplate, updatePromptBodySchema, } from "./entities/prompts.ts";
 export { createProviderBodySchema, providerListItemSchema, providerModelsResponseSchema, providerResponseSchema, providersResponseSchema, providerTypeSchema, thinkingLevelsResponseSchema, updateProviderBodySchema, } from "./entities/providers.ts";
 export type { ToolApprovalDecisionResponse, ToolApprovalsResponse, } from "./entities/sessions.ts";
 export { decideToolApprovalBodySchema, latestSessionListItemSchema, latestSessionsListResponseSchema, sessionListItemSchema, sessionMessageSchema, sessionMessagesResponseSchema, sessionsListResponseSchema, toolApprovalContinuationStateSchema, toolApprovalDecisionResponseSchema, toolApprovalStateSchema, toolApprovalsResponseSchema, } from "./entities/sessions.ts";
 export { copySkillBodySchema, createSkillBodySchema, skillCopyResultsSchema, skillDetailSchema, skillsListResponseSchema, } from "./entities/skills.ts";
-export { createTaskBodySchema, createTaskResponseSchema, createTaskRunBodySchema, createTaskRunResponseSchema, taskListItemSchema, taskResponseSchema, taskRunMessagesResponseSchema, taskRunResponseSchema, taskRunSchema, taskRunStatusSchema, taskRunsListResponseSchema, taskScheduleKindSchema, taskSchema, tasksListResponseSchema, updateTaskBodySchema, } from "./entities/tasks.ts";
+export { createTaskBodySchema, createTaskResponseSchema, createTaskRunBodySchema, createTaskRunResponseSchema, taskCronConfigSchema, taskIntervalConfigSchema, taskListItemSchema, taskOnceConfigSchema, taskResponseSchema, taskRunMessagesResponseSchema, taskRunResponseSchema, taskRunSchema, taskRunStatusSchema, taskRunsListResponseSchema, taskScheduleInputSchema, taskScheduleKindSchema, taskSchema, tasksListResponseSchema, updateTaskBodySchema, } from "./entities/tasks.ts";
 export { quotaSchema, subscriptionStatusSchema, tenantDeletionSchema, tenantResponseSchema, tenantSchema, tenantSettingsResponseSchema, updateTenantSettingsBodySchema, } from "./entities/tenants.ts";
-export type { UsageBucket, UsageOverviewQuery, UsageOverviewResponse, UsageResponse, UsageTotals, } from "./entities/usage.ts";
-export { usageOverviewQuerySchema, usageOverviewResponseSchema, usageResponseSchema, } from "./entities/usage.ts";
+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";