@blazingagents/sdk 0.34.0 → 0.36.0

package/dist/chat-transport.js

@@ -1,6 +1,7 @@
 import { lastAssistantMessageIsCompleteWithApprovalResponses, } from "ai";
 import { ChatStreamTransport } from "./chat-stream-transport.js";
 import { sessionIdSchema, turnIdSchema } from "./contracts/ids.js";
+import { parseClientInput } from "./errors.js";
 /**
  * Adapts AI SDK chat requests to the Blazing Agents backend-relay shape and
  * resumes with the server-minted Session ID returned in `Location`.
@@ -16,7 +17,9 @@ export class BlazingAgentsChatTransport {
         const { onSessionId, onTurnId, sessionId, ...transportOptions } = options;
         const transportFetch = transportOptions.fetch ?? globalThis.fetch;
         this.#sessionId =
-            sessionId === undefined ? undefined : sessionIdSchema.parse(sessionId);
+            sessionId === undefined
+                ? undefined
+                : parseClientInput(sessionIdSchema, sessionId, "sessionId");
         this.#transport = new ChatStreamTransport({
             ...transportOptions,
             /** Reads the first Session ID and each Turn ID before returning the response. */

package/dist/client.d.ts

@@ -1,4 +1,20 @@
-import type { AgentClient, AgentsResource, ArtifactsResource, BlazingAgentsOptions, BlazingAgentsRequestOptions, ChatConnectionsResource, ChatDeliveriesResource, ChatInput, ChatResult, CompletionInput, CompletionResult, ContinueChatInput, McpConnectionsResource, MemoriesResource, MerchantBindingsResource, MerchantConnectionResource, MerchantUsageEventsResource, ObjectInput, ObjectResult, PromptsResource, ProvidersResource, SessionsResource, TasksResource, TenantResource, UsageResource, UserClient, WorkspacesResource } from "./types.ts";
+import { type AgentsResource } from "./resources/agents.ts";
+import { type ArtifactsResource } from "./resources/artifacts.ts";
+import { type ChatConnectionsResource } from "./resources/chat-connections.ts";
+import { type ChatDeliveriesResource } from "./resources/chat-deliveries.ts";
+import { type McpConnectionsResource } from "./resources/mcp-connections.ts";
+import { type MemoriesResource } from "./resources/memories.ts";
+import { type MerchantBindingsResource } from "./resources/merchant-bindings.ts";
+import { type MerchantConnectionResource } from "./resources/merchant-connection.ts";
+import { type MerchantUsageEventsResource } from "./resources/merchant-usage-events.ts";
+import { type PromptsResource } from "./resources/prompts.ts";
+import { type ProvidersResource } from "./resources/providers.ts";
+import { type SessionsResource } from "./resources/sessions.ts";
+import { type TasksResource } from "./resources/tasks.ts";
+import { type TenantResource } from "./resources/tenant.ts";
+import { type UsageResource } from "./resources/usage.ts";
+import { type WorkspacesResource } from "./resources/workspaces.ts";
+import type { AgentClient, BlazingAgentsOptions, BlazingAgentsRequestOptions, ChatInput, ChatResult, CompletionInput, CompletionResult, ContinueChatInput, ObjectInput, ObjectResult, UserClient } from "./types.ts";
 export declare class BlazingAgents {
     #private;
     readonly chatConnections: ChatConnectionsResource;
@@ -33,7 +49,7 @@ export declare class BlazingAgents {
      * Scope requests to one end user. IDs use printable ASCII, at most 256 characters, without leading or trailing spaces.
      * @param userId - Printable ASCII end-user ID, at most 256 characters with no surrounding spaces.
      * @returns A client scoped to the validated end-user ID.
-     * @throws ZodError - If the user ID is invalid.
+     * @throws BlazingAgentsError - With code `invalid_request` if the user ID is invalid.
      */
     forUser(userId: string): UserClient;
     /**

package/dist/client.js

@@ -1,22 +1,23 @@
 import { z } from "zod";
+import { parseClientInput } from "./errors.js";
 import { chat, completion, continueChat, objectGeneration, } from "./generation.js";
 import { createAgentsResource, createUserAgentsResource, } from "./resources/agents.js";
-import { createArtifactsResource } from "./resources/artifacts.js";
-import { createChatConnectionsResource } from "./resources/chat-connections.js";
-import { createChatDeliveriesResource } from "./resources/chat-deliveries.js";
-import { createMcpConnectionsResource } from "./resources/mcp-connections.js";
-import { createMemoriesResource } from "./resources/memories.js";
-import { createMerchantBindingsResource } from "./resources/merchant-bindings.js";
-import { createMerchantConnectionResource } from "./resources/merchant-connection.js";
-import { createMerchantUsageEventsResource } from "./resources/merchant-usage-events.js";
-import { createPromptsResource } from "./resources/prompts.js";
-import { createProvidersResource } from "./resources/providers.js";
-import { createSessionsResource } from "./resources/sessions.js";
+import { createArtifactsResource, } from "./resources/artifacts.js";
+import { createChatConnectionsResource, } from "./resources/chat-connections.js";
+import { createChatDeliveriesResource, } from "./resources/chat-deliveries.js";
+import { createMcpConnectionsResource, } from "./resources/mcp-connections.js";
+import { createMemoriesResource, } from "./resources/memories.js";
+import { createMerchantBindingsResource, } from "./resources/merchant-bindings.js";
+import { createMerchantConnectionResource, } from "./resources/merchant-connection.js";
+import { createMerchantUsageEventsResource, } from "./resources/merchant-usage-events.js";
+import { createPromptsResource, } from "./resources/prompts.js";
+import { createProvidersResource, } from "./resources/providers.js";
+import { createSessionsResource, } from "./resources/sessions.js";
 import { createAgentSkillsResource } from "./resources/skills.js";
 import { createTasksResource } from "./resources/tasks.js";
-import { createTenantResource } from "./resources/tenant.js";
+import { createTenantResource, } from "./resources/tenant.js";
 import { createUsageResource } from "./resources/usage.js";
-import { createWorkspacesResource } from "./resources/workspaces.js";
+import { createWorkspacesResource, } from "./resources/workspaces.js";
 const DEFAULT_BASE_URL = "https://api.blazingagents.com";
 const TRAILING_SLASH_RE = /\/+$/;
 const scopedUserIdSchema = z
@@ -117,12 +118,12 @@ export class BlazingAgents {
      * Scope requests to one end user. IDs use printable ASCII, at most 256 characters, without leading or trailing spaces.
      * @param userId - Printable ASCII end-user ID, at most 256 characters with no surrounding spaces.
      * @returns A client scoped to the validated end-user ID.
-     * @throws ZodError - If the user ID is invalid.
+     * @throws BlazingAgentsError - With code `invalid_request` if the user ID is invalid.
      */
     forUser(userId) {
         return createUserClient({
             ...this.#config,
-            scopeUserId: scopedUserIdSchema.parse(userId),
+            scopeUserId: parseClientInput(scopedUserIdSchema, userId, "userId"),
         });
     }
     /**

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

@@ -265,10 +265,10 @@ export declare const agentsResponseSchema: z.ZodObject<{
     nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export declare const agentsListQuerySchema: z.ZodObject<{
-    cursor: z.ZodOptional<z.ZodString>;
-    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     userId: z.ZodOptional<z.ZodString>;
     workspaceId: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strict>;
 export declare const agentConfigSchema: z.ZodObject<{
     approvalInChat: z.ZodDefault<z.ZodObject<{
@@ -379,6 +379,10 @@ export declare const agentConfigSchema: z.ZodObject<{
     mcpConnectionIds: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
 export declare const createAgentBodySchema: z.ZodObject<{
+    workspaceTier: z.ZodOptional<z.ZodEnum<{
+        core: "core";
+        plus: "plus";
+    }>>;
     approvalInChat: z.ZodDefault<z.ZodObject<{
         default: z.ZodEnum<{
             auto: "auto";
@@ -464,10 +468,6 @@ export declare const createAgentBodySchema: z.ZodObject<{
     thinkingLevel: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     providerId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     workspaceId: z.ZodOptional<z.ZodString>;
-    workspaceTier: z.ZodOptional<z.ZodEnum<{
-        core: "core";
-        plus: "plus";
-    }>>;
     autoCompaction: z.ZodDefault<z.ZodBoolean>;
     compactionReserveTokens: z.ZodDefault<z.ZodNumber>;
     memoryInjectionEnabled: z.ZodDefault<z.ZodBoolean>;
@@ -605,6 +605,7 @@ export type Agent = z.infer<typeof agentResponseSchema>;
 export type AgentsResponse = z.infer<typeof agentsResponseSchema>;
 export type AgentResponse = z.infer<typeof agentResponseSchema>;
 export type AgentsListQuery = z.infer<typeof agentsListQuerySchema>;
+export type AgentStatus = z.infer<typeof agentStatusSchema>;
 export type AgentConfig = z.infer<typeof agentConfigSchema>;
 export type CreateAgentBody = z.input<typeof createAgentBodySchema>;
 export type UpdateAgentBody = z.input<typeof updateAgentBodySchema>;

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_AGENTS_LIST_LIMIT, MAX_AGENT_INSTRUCTIONS_LENGTH, MAX_AGENT_NAME_LENGTH, MAX_AGENTS_LIST_LIMIT, MAX_MCP_CONNECTIONS_PER_AGENT, } from "../limitations.js";
+import { DEFAULT_RESOURCES_LIST_LIMIT, MAX_AGENT_INSTRUCTIONS_LENGTH, MAX_AGENT_NAME_LENGTH, MAX_MCP_CONNECTIONS_PER_AGENT, MAX_RESOURCES_LIST_LIMIT, } from "../limitations.js";
 import { atLeastOneFieldMessage, hasObjectKeys, hasUniqueValues, } from "../utils.js";
 import { approvalPolicySchema } from "./agent-approval.js";
 import { agentToolNames } from "./agent-tools.js";
@@ -78,15 +78,22 @@ export const agentResponseSchema = z
 export const agentsResponseSchema = paginatedResponseSchema(agentResponseSchema);
 export const agentsListQuerySchema = z
     .object({
-    cursor: cursorSchema.optional(),
+    userId: userIdSchema
+        .optional()
+        .describe("Return only agents for this end user. Send an empty string for tenant-level agents, or leave it out for all agents."),
+    workspaceId: workspaceIdSchema
+        .optional()
+        .describe("Return only agents that use this workspace."),
+    cursor: cursorSchema
+        .optional()
+        .describe("`nextCursor` from the previous page."),
     limit: z.coerce
         .number()
         .int()
         .min(1)
-        .max(MAX_AGENTS_LIST_LIMIT)
-        .default(DEFAULT_AGENTS_LIST_LIMIT),
-    userId: userIdSchema.optional(),
-    workspaceId: workspaceIdSchema.optional(),
+        .max(MAX_RESOURCES_LIST_LIMIT)
+        .default(DEFAULT_RESOURCES_LIST_LIMIT)
+        .describe("Maximum number of agents to return."),
 })
     .strict();
 export const agentConfigSchema = z
@@ -109,27 +116,78 @@ export const agentConfigSchema = z
     message: providerModelPairMessage,
     path: ["providerId"],
 });
+const agentFieldDescriptions = {
+    approvalInChat: "Which tool calls need approval in sessions and stateless generation.",
+    approvalInTasks: "Which tool calls need approval in task runs.",
+    name: "Display name.",
+    model: "The provider's own model ID, such as `openai/gpt-6-luna`. Send it together with `providerId`.",
+    thinkingLevel: "How much reasoning to request from the model, such as `high`. Needs a provider and model, and must be a level the model supports.",
+    providerId: "ID of the provider whose key runs the model. Send it together with `model`.",
+    workspaceId: "ID of the workspace the agent reads and writes files in.",
+    autoCompaction: "Summarize older context automatically when a conversation nears the model's context limit.",
+    compactionReserveTokens: "Tokens to keep free for the model's reply when deciding whether to compact.",
+    memoryInjectionEnabled: "Add the agent's saved memories to every turn automatically.",
+    tools: "Built-in tools the agent can use. Each tool is enabled individually and is off until listed. File tools such as `read` and `bash` run in the attached workspace.",
+    instructions: "Instructions the agent follows on every turn.",
+    userId: "Your end user's ID, used for attribution. An empty string means a tenant-level agent. It cannot change after creation.",
+    metadata: "Your own key-value data, returned unchanged.",
+    mcpConnectionIds: "IDs of the MCP connections attached to the agent.",
+};
 export const createAgentBodySchema = z
     .object({
-    ...approvalFields,
-    name: agentNameSchema,
-    model: agentModelIdSchema.nullable().default(null),
-    thinkingLevel: z.string().min(1).nullable().default(null),
-    providerId: providerIdSchema.nullable().default(null),
-    workspaceId: workspaceIdSchema.optional(),
-    workspaceTier: workspaceTierSchema.optional(),
-    autoCompaction: z.boolean().default(true),
-    compactionReserveTokens: agentResponseSchema.shape.compactionReserveTokens.default(16_384),
-    memoryInjectionEnabled: z.boolean().default(false),
-    tools: agentToolsSchema.default([]),
-    instructions: agentInstructionsSchema.default(""),
-    userId: userIdSchema.default(""),
-    metadata: metadataSchema.default({}),
-    mcpConnectionIds: agentMcpConnectionIdsSchema.default([]),
+    workspaceTier: workspaceTierSchema
+        .optional()
+        .describe("Tier for a new Workspace. Defaults to Core. Cannot be combined with workspaceId."),
+    approvalInChat: approvalFields.approvalInChat.describe(agentFieldDescriptions.approvalInChat),
+    approvalInTasks: approvalFields.approvalInTasks.describe(agentFieldDescriptions.approvalInTasks),
+    name: agentNameSchema.describe(agentFieldDescriptions.name),
+    model: agentModelIdSchema
+        .nullable()
+        .default(null)
+        .describe(agentFieldDescriptions.model),
+    thinkingLevel: z
+        .string()
+        .min(1)
+        .nullable()
+        .default(null)
+        .describe(agentFieldDescriptions.thinkingLevel),
+    providerId: providerIdSchema
+        .nullable()
+        .default(null)
+        .describe(agentFieldDescriptions.providerId),
+    workspaceId: workspaceIdSchema
+        .optional()
+        .describe(`${agentFieldDescriptions.workspaceId} Leave it out to create a new workspace for the agent, or send an existing one to share it.`),
+    autoCompaction: z
+        .boolean()
+        .default(true)
+        .describe(agentFieldDescriptions.autoCompaction),
+    compactionReserveTokens: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(16_384)
+        .describe(agentFieldDescriptions.compactionReserveTokens),
+    memoryInjectionEnabled: z
+        .boolean()
+        .default(false)
+        .describe(agentFieldDescriptions.memoryInjectionEnabled),
+    tools: agentToolsSchema.default([]).describe(agentFieldDescriptions.tools),
+    instructions: agentInstructionsSchema
+        .default("")
+        .describe(agentFieldDescriptions.instructions),
+    userId: userIdSchema.default("").describe(agentFieldDescriptions.userId),
+    metadata: metadataSchema
+        .default({})
+        .describe(agentFieldDescriptions.metadata),
+    mcpConnectionIds: agentMcpConnectionIdsSchema
+        .default([])
+        .describe(agentFieldDescriptions.mcpConnectionIds),
 })
     .strict()
     .refine((input) => input.workspaceId === undefined || input.workspaceTier === undefined, {
-    message: "workspaceId and workspaceTier are mutually exclusive.",
+    message: "workspaceTier cannot be combined with workspaceId",
     path: ["workspaceTier"],
 })
     .refine(hasProviderModelPair, {
@@ -138,20 +196,55 @@ export const createAgentBodySchema = z
 });
 export const updateAgentBodySchema = z
     .object({
-    approvalInChat: approvalPolicySchema.optional(),
-    approvalInTasks: approvalPolicySchema.optional(),
-    name: agentNameSchema.optional(),
-    model: agentModelIdSchema.nullable().optional(),
-    thinkingLevel: z.string().min(1).nullable().optional(),
-    providerId: providerIdSchema.nullable().optional(),
-    workspaceId: workspaceIdSchema.optional(),
-    autoCompaction: z.boolean().optional(),
-    compactionReserveTokens: agentResponseSchema.shape.compactionReserveTokens.optional(),
-    memoryInjectionEnabled: z.boolean().optional(),
-    tools: agentToolsSchema.optional(),
-    instructions: agentInstructionsSchema.optional(),
-    metadata: metadataSchema.optional(),
-    mcpConnectionIds: agentMcpConnectionIdsSchema.optional(),
+    approvalInChat: approvalPolicySchema
+        .optional()
+        .describe(agentFieldDescriptions.approvalInChat),
+    approvalInTasks: approvalPolicySchema
+        .optional()
+        .describe(agentFieldDescriptions.approvalInTasks),
+    name: agentNameSchema.optional().describe(agentFieldDescriptions.name),
+    model: agentModelIdSchema
+        .nullable()
+        .optional()
+        .describe(agentFieldDescriptions.model),
+    thinkingLevel: z
+        .string()
+        .min(1)
+        .nullable()
+        .optional()
+        .describe(agentFieldDescriptions.thinkingLevel),
+    providerId: providerIdSchema
+        .nullable()
+        .optional()
+        .describe(agentFieldDescriptions.providerId),
+    workspaceId: workspaceIdSchema
+        .optional()
+        .describe(agentFieldDescriptions.workspaceId),
+    autoCompaction: z
+        .boolean()
+        .optional()
+        .describe(agentFieldDescriptions.autoCompaction),
+    compactionReserveTokens: z
+        .number()
+        .int()
+        .nonnegative()
+        .max(Number.MAX_SAFE_INTEGER)
+        .optional()
+        .describe(agentFieldDescriptions.compactionReserveTokens),
+    memoryInjectionEnabled: z
+        .boolean()
+        .optional()
+        .describe(agentFieldDescriptions.memoryInjectionEnabled),
+    tools: agentToolsSchema.optional().describe(agentFieldDescriptions.tools),
+    instructions: agentInstructionsSchema
+        .optional()
+        .describe(agentFieldDescriptions.instructions),
+    metadata: metadataSchema
+        .optional()
+        .describe(agentFieldDescriptions.metadata),
+    mcpConnectionIds: agentMcpConnectionIdsSchema
+        .optional()
+        .describe(agentFieldDescriptions.mcpConnectionIds),
 })
     .strict()
     .refine(hasObjectKeys, {

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

@@ -1,4 +1,5 @@
 import { z } from "zod";
+/** The credentials a client sends; the server never returns them. */
 export declare const chatCredentialsSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     platform: z.ZodLiteral<"slack">;
     botToken: z.ZodString;
@@ -103,7 +104,6 @@ export declare const chatConnectionSchema: z.ZodObject<{
         chatIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
         platform: z.ZodLiteral<"telegram">;
     }, z.core.$strip>], "platform">;
-    webhookUrl: z.ZodURL;
     identity: z.ZodObject<{
         botId: z.ZodString;
         botUserId: z.ZodString;
@@ -128,6 +128,7 @@ export declare const chatConnectionSchema: z.ZodObject<{
     credentialVersion: z.ZodNumber;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
+    webhookUrl: z.ZodURL;
 }, z.core.$strip>;
 export type CreateChatConnectionBody = z.input<typeof createChatConnectionBodySchema>;
 export type ChatCredentials = z.output<typeof chatCredentialsSchema>;
@@ -155,7 +156,6 @@ export declare const chatConnectionsResponseSchema: z.ZodObject<{
             chatIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
             platform: z.ZodLiteral<"telegram">;
         }, z.core.$strip>], "platform">;
-        webhookUrl: z.ZodURL;
         identity: z.ZodObject<{
             botId: z.ZodString;
             botUserId: z.ZodString;
@@ -180,6 +180,7 @@ export declare const chatConnectionsResponseSchema: z.ZodObject<{
         credentialVersion: z.ZodNumber;
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
+        webhookUrl: z.ZodURL;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ChatConnectionsResponse = z.output<typeof chatConnectionsResponseSchema>;
@@ -212,7 +213,7 @@ export declare const chatDeliverySchema: z.ZodObject<{
     credentialVersion: z.ZodNumber;
     representation: z.ZodString;
     diagnostic: z.ZodNullable<z.ZodString>;
-    receipts: z.ZodOptional<z.ZodUnknown>;
+    receipts: z.ZodUnknown;
     sessionId: z.ZodString;
     messageId: z.ZodNullable<z.ZodString>;
     approvalId: z.ZodNullable<z.ZodString>;
@@ -237,7 +238,7 @@ export declare const tenantChatDeliverySchema: z.ZodObject<{
     credentialVersion: z.ZodNumber;
     representation: z.ZodString;
     diagnostic: z.ZodNullable<z.ZodString>;
-    receipts: z.ZodOptional<z.ZodUnknown>;
+    receipts: z.ZodUnknown;
     sessionId: z.ZodString;
     messageId: z.ZodNullable<z.ZodString>;
     approvalId: z.ZodNullable<z.ZodString>;
@@ -250,7 +251,7 @@ export declare const tenantChatDeliverySchema: z.ZodObject<{
         slack: "slack";
         telegram: "telegram";
     }>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export type TenantChatDelivery = z.infer<typeof tenantChatDeliverySchema>;
 export declare const chatDeliveriesResponseSchema: z.ZodObject<{
     data: z.ZodArray<z.ZodObject<{
@@ -269,7 +270,7 @@ export declare const chatDeliveriesResponseSchema: z.ZodObject<{
         credentialVersion: z.ZodNumber;
         representation: z.ZodString;
         diagnostic: z.ZodNullable<z.ZodString>;
-        receipts: z.ZodOptional<z.ZodUnknown>;
+        receipts: z.ZodUnknown;
         sessionId: z.ZodString;
         messageId: z.ZodNullable<z.ZodString>;
         approvalId: z.ZodNullable<z.ZodString>;
@@ -282,7 +283,7 @@ export declare const chatDeliveriesResponseSchema: z.ZodObject<{
             slack: "slack";
             telegram: "telegram";
         }>;
-    }, z.core.$strip>>;
+    }, z.core.$strict>>;
     nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type ChatDeliveriesResponse = z.infer<typeof chatDeliveriesResponseSchema>;
@@ -303,7 +304,7 @@ export declare const chatDeliveryListSchema: z.ZodObject<{
         credentialVersion: z.ZodNumber;
         representation: z.ZodString;
         diagnostic: z.ZodNullable<z.ZodString>;
-        receipts: z.ZodOptional<z.ZodUnknown>;
+        receipts: z.ZodUnknown;
         sessionId: z.ZodString;
         messageId: z.ZodNullable<z.ZodString>;
         approvalId: z.ZodNullable<z.ZodString>;

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

@@ -1,90 +1,118 @@
 import { z } from "zod";
 import { agentIdSchema, chatConnectionIdSchema, chatDeliveryIdSchema, tenantIdSchema, } from "../ids.js";
-const secret = z
+const slackBotToken = z
     .string()
     .min(8)
     .max(8192)
     .regex(/^[!-~]+$/);
+const slackSigningSecret = z.string().regex(/^[0-9a-f]{32}$/);
+const telegramBotToken = z.string().regex(/^\d+:[A-Za-z0-9_-]+$/);
+const slackChannelIds = z.array(z.string().regex(/^[CG][A-Z0-9]+$/)).max(20);
+const telegramChatIds = z.array(z.string().regex(/^-?\d+$/)).max(20);
+/** The credentials a client sends; the server never returns them. */
 export const chatCredentialsSchema = z.discriminatedUnion("platform", [
     z
         .object({
         platform: z.literal("slack"),
-        botToken: secret,
-        signingSecret: z.string().regex(/^[0-9a-f]{32}$/),
+        botToken: slackBotToken,
+        signingSecret: slackSigningSecret,
     })
         .strict(),
     z
         .object({
         platform: z.literal("telegram"),
-        botToken: z.string().regex(/^\d+:[A-Za-z0-9_-]+$/),
+        botToken: telegramBotToken,
     })
         .strict(),
 ]);
 const slackConfiguration = z
     .object({
-    channelIds: z
-        .array(z.string().regex(/^[CG][A-Z0-9]+$/))
-        .max(20)
-        .default([]),
+    channelIds: slackChannelIds.default([]),
 })
     .strict();
 const telegramConfiguration = z
     .object({
     businessMode: z.boolean().default(false),
-    chatIds: z
-        .array(z.string().regex(/^-?\d+$/))
-        .max(20)
-        .default([]),
+    chatIds: telegramChatIds.default([]),
 })
     .strict();
 export const chatConfigurationSchema = z.discriminatedUnion("platform", [
     slackConfiguration.extend({ platform: z.literal("slack") }),
     telegramConfiguration.extend({ platform: z.literal("telegram") }),
 ]);
+const connectionName = z.string().trim().min(1).max(80);
 const common = {
-    agentId: agentIdSchema,
-    name: z.string().trim().min(1).max(80),
-    enabled: z.boolean().default(true),
+    agentId: agentIdSchema.describe("ID of the agent that answers messages on this connection. You cannot change it later."),
+    name: connectionName.describe("Display name, 1 to 80 characters."),
+    enabled: z
+        .boolean()
+        .default(true)
+        .describe("Whether the connection accepts messages. Defaults to `true`."),
 };
+const configurationDescription = "Optional platform settings. Destination IDs choose where health checks look; they do not restrict who can talk to the agent.";
+const platformDescription = "Chat platform: `slack` or `telegram`.";
 export const createChatConnectionBodySchema = z.discriminatedUnion("platform", [
     z
         .object({
         ...common,
-        platform: z.literal("slack"),
-        configuration: slackConfiguration.prefault({}),
-        credentials: chatCredentialsSchema.options[0].omit({ platform: true }),
+        platform: z.literal("slack").describe(platformDescription),
+        configuration: slackConfiguration
+            .prefault({})
+            .describe(configurationDescription),
+        credentials: z
+            .object({
+            botToken: slackBotToken,
+            signingSecret: slackSigningSecret,
+        })
+            .strict()
+            .describe("The Slack app's bot token and signing secret."),
     })
         .strict(),
     z
         .object({
         ...common,
-        platform: z.literal("telegram"),
-        configuration: telegramConfiguration.prefault({}),
-        credentials: chatCredentialsSchema.options[1].omit({ platform: true }),
+        platform: z.literal("telegram").describe(platformDescription),
+        configuration: telegramConfiguration
+            .prefault({})
+            .describe(configurationDescription),
+        credentials: z
+            .object({ botToken: telegramBotToken })
+            .strict()
+            .describe("The Telegram bot token from BotFather."),
     })
         .strict(),
 ]);
 export const rotateChatConnectionBodySchema = z.discriminatedUnion("platform", [
-    chatCredentialsSchema.options[0],
-    chatCredentialsSchema.options[1],
+    z
+        .object({
+        platform: z
+            .literal("slack")
+            .describe("Must match the connection's platform."),
+        botToken: slackBotToken.describe("The new Slack bot token."),
+        signingSecret: slackSigningSecret.describe("The Slack app's signing secret."),
+    })
+        .strict(),
+    z
+        .object({
+        platform: z
+            .literal("telegram")
+            .describe("Must match the connection's platform."),
+        botToken: telegramBotToken.describe("The new Telegram bot token."),
+    })
+        .strict(),
 ]);
 export const updateChatConnectionBodySchema = z
     .object({
-    name: common.name.optional(),
+    name: connectionName.optional().describe("New display name."),
     configuration: z
         .object({
         businessMode: z.boolean().optional(),
-        chatIds: z
-            .array(z.string().regex(/^-?\d+$/))
-            .max(20)
-            .optional(),
-        channelIds: z
-            .array(z.string().regex(/^[CG][A-Z0-9]+$/))
-            .max(20)
-            .optional(),
+        chatIds: telegramChatIds.optional(),
+        channelIds: slackChannelIds.optional(),
     })
         .strict()
-        .optional(),
+        .optional()
+        .describe("Fields to change. Slack connections accept `channelIds`; Telegram connections accept `chatIds` and `businessMode`. Fields you leave out keep their values."),
 })
     .strict()
     .refine((body) => body.name !== undefined ||
@@ -118,24 +146,24 @@ export const chatConnectionSchema = z
     id: chatConnectionIdSchema,
     tenantId: tenantIdSchema,
     agentId: agentIdSchema,
-    name: common.name,
+    name: connectionName,
     platform: z.enum(["slack", "telegram"]),
     enabled: z.boolean(),
     configuration: z.discriminatedUnion("platform", [
         chatConfigurationSchema.options[0].strip(),
         chatConfigurationSchema.options[1].strip(),
     ]),
-    webhookUrl: z.url(),
     identity: chatIdentitySchema,
     health: chatHealthSchema,
     credentialFragment: z.string().max(4),
     credentialVersion: z.number().int().nonnegative(),
     createdAt: z.string(),
     updatedAt: z.string(),
+    webhookUrl: z.url(),
 })
     .strip();
 export const chatConnectionsResponseSchema = z
-    .object({ chatConnections: z.array(chatConnectionSchema) })
+    .object({ chatConnections: chatConnectionSchema.array() })
     .strip();
 export const chatDeliveryStatusSchema = z.enum([
     "pending",
@@ -148,12 +176,12 @@ export const chatDeliverySchema = z
     .object({
     id: chatDeliveryIdSchema,
     kind: z.enum(["reply", "card"]),
-    status: chatDeliveryStatusSchema,
+    status: z.enum(["pending", "confirmed", "failed", "ambiguous"]),
     attempt: z.number().int().nonnegative(),
     credentialVersion: z.number().int().nonnegative(),
     representation: z.string(),
     diagnostic: z.string().nullable(),
-    receipts: z.unknown().optional(),
+    receipts: z.unknown(),
     sessionId: z.string(),
     messageId: z.string().nullable(),
     approvalId: z.string().nullable(),
@@ -162,11 +190,13 @@ export const chatDeliverySchema = z
     updatedAt: z.string(),
 })
     .strip();
-export const tenantChatDeliverySchema = chatDeliverySchema.extend({
+export const tenantChatDeliverySchema = chatDeliverySchema
+    .extend({
     connectionId: chatConnectionIdSchema,
     agentId: agentIdSchema,
     platform: z.enum(["slack", "telegram"]),
-});
+})
+    .strict();
 export const chatDeliveriesResponseSchema = z
     .object({
     data: z.array(tenantChatDeliverySchema),