@blazingagents/sdk 0.20.0 → 0.22.0

package/dist/approvals.d.ts

@@ -1,3 +1,7 @@
 import { type UIMessage } from "ai";
 import type { ToolApprovalDecision } from "./contracts/entities/sessions.ts";
+/**
+ * Extracts approval decisions from the last assistant step without changing the message.
+ * @returns Decisions after the last step-start part, or an empty array.
+ */
 export declare function extractApprovalDecisions(message: UIMessage): ToolApprovalDecision[];

package/dist/approvals.js

@@ -1,4 +1,8 @@
 import { isToolUIPart } from "ai";
+/**
+ * Extracts approval decisions from the last assistant step without changing the message.
+ * @returns Decisions after the last step-start part, or an empty array.
+ */
 export function extractApprovalDecisions(message) {
     const lastStep = message.parts.findLastIndex((part) => part.type === "step-start");
     return message.parts.slice(lastStep + 1).flatMap((part) => isToolUIPart(part) && part.state === "approval-responded"

package/dist/chat-stream-transport.d.ts

@@ -0,0 +1,5 @@
+import { DefaultChatTransport, type UIMessage } from "ai";
+export declare class ChatStreamTransport<UI_MESSAGE extends UIMessage = UIMessage> extends DefaultChatTransport<UI_MESSAGE> {
+    /** Native Chat rejects an update job for error chunks, so fail the stream before that job runs. */
+    protected processResponseStream(stream: ReadableStream<Uint8Array>): ReadableStream<any>;
+}

package/dist/chat-stream-transport.js

@@ -0,0 +1,15 @@
+import { DefaultChatTransport } from "ai";
+export class ChatStreamTransport extends DefaultChatTransport {
+    /** Native Chat rejects an update job for error chunks, so fail the stream before that job runs. */
+    processResponseStream(stream) {
+        return super.processResponseStream(stream).pipeThrough(new TransformStream({
+            transform(chunk, controller) {
+                if (chunk.type === "error") {
+                    controller.error(new Error(chunk.errorText));
+                    return;
+                }
+                controller.enqueue(chunk);
+            },
+        }));
+    }
+}

package/dist/chat-transport.d.ts

@@ -1,6 +1,9 @@
 import { type ChatTransport, type HttpChatTransportInitOptions, type UIMessage } from "ai";
 export type BlazingAgentsChatTransportOptions<UI_MESSAGE extends UIMessage = UIMessage> = Omit<HttpChatTransportInitOptions<UI_MESSAGE>, "prepareReconnectToStreamRequest" | "prepareSendMessagesRequest"> & {
-    /** Receives the Session ID minted by the first successful response. */
+    /**
+     * Receives the Session ID minted by the first successful response.
+     * @param sessionId - Session to look up or record.
+     */
     onSessionId?: (sessionId: string) => Promise<void> | void;
     /** An authorized Session ID used to resume after a remount or reload. */
     sessionId?: string;
@@ -11,7 +14,21 @@ export type BlazingAgentsChatTransportOptions<UI_MESSAGE extends UIMessage = UIM
  */
 export declare class BlazingAgentsChatTransport<UI_MESSAGE extends UIMessage = UIMessage> implements ChatTransport<UI_MESSAGE> {
     #private;
+    /**
+     * Creates a chat transport and validates any supplied Session ID.
+     * @param options - Configuration for this operation.
+     */
     constructor(options?: BlazingAgentsChatTransportOptions<UI_MESSAGE>);
+    /**
+     * Submits the latest user message or complete assistant approval round to the chat.
+     * @param input - Operation input and optional cancellation signal.
+     * @returns The decoded AI SDK message-chunk stream.
+     */
     sendMessages(input: Parameters<ChatTransport<UI_MESSAGE>["sendMessages"]>[0]): Promise<ReadableStream<import("ai").UIMessageChunk>>;
+    /**
+     * Returns null because reconnecting to an existing stream is unsupported.
+     * @param _input - Unused reconnect request.
+     * @returns A promise resolving to null.
+     */
     reconnectToStream(_input: Parameters<ChatTransport<UI_MESSAGE>["reconnectToStream"]>[0]): Promise<null>;
 }

package/dist/chat-transport.js

@@ -1,4 +1,5 @@
-import { DefaultChatTransport, lastAssistantMessageIsCompleteWithApprovalResponses, } from "ai";
+import { lastAssistantMessageIsCompleteWithApprovalResponses, } from "ai";
+import { ChatStreamTransport } from "./chat-stream-transport.js";
 import { sessionIdSchema } from "./contracts/ids.js";
 /**
  * Adapts AI SDK chat requests to the Blazing Agents backend-relay shape and
@@ -7,13 +8,18 @@ import { sessionIdSchema } from "./contracts/ids.js";
 export class BlazingAgentsChatTransport {
     #transport;
     #sessionId;
+    /**
+     * Creates a chat transport and validates any supplied Session ID.
+     * @param options - Configuration for this operation.
+     */
     constructor(options = {}) {
         const { onSessionId, sessionId, ...transportOptions } = options;
         const transportFetch = transportOptions.fetch ?? globalThis.fetch;
         this.#sessionId =
             sessionId === undefined ? undefined : sessionIdSchema.parse(sessionId);
-        this.#transport = new DefaultChatTransport({
+        this.#transport = new ChatStreamTransport({
             ...transportOptions,
+            /** Reads the first Session ID from Location before returning the response. */
             fetch: async (input, init) => {
                 const response = await transportFetch(input, init);
                 if (response.ok && this.#sessionId === undefined) {
@@ -30,6 +36,7 @@ export class BlazingAgentsChatTransport {
                 }
                 return response;
             },
+            /** Selects the user message or complete approval round for the relay request. */
             prepareSendMessagesRequest: ({ body, messageId, messages, trigger }) => {
                 const approvals = messages.at(-1)?.role === "assistant" &&
                     lastAssistantMessageIsCompleteWithApprovalResponses({ messages });
@@ -56,9 +63,19 @@ export class BlazingAgentsChatTransport {
             },
         });
     }
+    /**
+     * Submits the latest user message or complete assistant approval round to the chat.
+     * @param input - Operation input and optional cancellation signal.
+     * @returns The decoded AI SDK message-chunk stream.
+     */
     sendMessages(input) {
         return this.#transport.sendMessages(input);
     }
+    /**
+     * Returns null because reconnecting to an existing stream is unsupported.
+     * @param _input - Unused reconnect request.
+     * @returns A promise resolving to null.
+     */
     reconnectToStream(_input) {
         return Promise.resolve(null);
     }

package/dist/client.d.ts

@@ -17,36 +17,59 @@ export declare class BlazingAgents {
     readonly merchantConnection: MerchantConnectionResource;
     readonly merchantBindings: MerchantBindingsResource;
     readonly merchantUsageEvents: MerchantUsageEventsResource;
+    /**
+     * Creates a client. Defaults to the hosted API and removes trailing base URL slashes.
+     * @param options - Configuration for this operation.
+     */
     constructor(options: BlazingAgentsOptions);
+    /**
+     * Returns the Skill operations for the selected Agent.
+     * @returns The selected Agent Skill client.
+     */
     agent({ agentId }: {
         agentId: string;
     }): AgentClient;
-    /** Scope requests to one end user. IDs use printable ASCII, at most 256 characters, without leading or trailing spaces. */
+    /**
+     * 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.
+     */
     forUser(userId: string): UserClient;
     /**
      * `POST /v1/agents/:agentId/sessions` (create, no `sessionId`) or
      * `POST /v1/agents/:agentId/sessions/:sessionId` (resume). Returns the
      * session id and a byte-compatible SSE relay for `useChat`.
+     * @param input - Agent, message or stored Prompt, and optional existing Session.
+     * @returns The Session ID promise and single-owner SSE accessors.
      */
     chat(input: ChatInput): Promise<ChatResult>;
     /**
      * Records a complete Tool approval round and streams its continuation.
      * Caller-local function handlers apply only to this invocation.
+     * @param input - Agent, Session, and decisions for the complete approval round.
+     * @returns The Session ID promise and continuation SSE accessors.
      */
     continueChat(input: ContinueChatInput): Promise<ChatResult>;
     /**
      * `POST /v1/agents/:agentId/generation` — stateless one-shot text
      * stream. Returns `textStream` + `await result.text` + `toResponse()`.
+     * @param input - Agent and literal prompt or stored Prompt reference.
+     * @returns Independent text stream, final text promise, and response relay.
      */
     completion(input: CompletionInput): Promise<CompletionResult>;
     /**
      * `POST /v1/agents/:agentId/generation` — stateless structured output.
      * Returns `partialObjectStream` + `await result.object` + `toResponse()`.
+     * @param input - Agent, prompt source, and JSON output schema.
+     * @returns Partial JSON objects, a final JSON promise, and a text response relay.
      */
     object(input: ObjectInput): Promise<ObjectResult>;
     /**
      * Returns a lightweight client view whose resource and generation calls
      * carry caller-owned correlation without raw header manipulation.
+     * @param options - Caller-owned request correlation ID for subsequent calls.
+     * @returns A new client carrying the supplied correlation ID.
      */
     withOptions(options: BlazingAgentsRequestOptions): BlazingAgents;
 }

package/dist/client.js

@@ -23,6 +23,9 @@ const scopedUserIdSchema = z
     .string()
     .max(256)
     .regex(/^[\x21-\x7E](?:[\x20-\x7E]*[\x21-\x7E])?$/);
+/**
+ * Builds a client whose requests share the configured user scope.
+ */
 function createUserClient(config) {
     const usage = createUsageResource(config);
     return {
@@ -34,13 +37,19 @@ function createUserClient(config) {
         workspaces: createWorkspacesResource(config),
         memories: createMemoriesResource(config),
         usage: { get: usage.get, sessions: usage.sessions },
+        /** Returns Skill operations for the selected Agent. */
         agent: ({ agentId }) => ({
             skills: createAgentSkillsResource(config, agentId),
         }),
+        /** Starts a chat using the scoped client configuration. */
         chat: (input) => chat(config, input),
+        /** Starts text generation using the scoped client configuration. */
         completion: (input) => completion(config, input),
+        /** Starts JSON generation using the scoped client configuration. */
         object: (input) => objectGeneration(config, input),
+        /** Continues an approval round using the scoped client configuration. */
         continueChat: (input) => continueChat(config, input),
+        /** Creates a scoped client view with the supplied correlation ID. */
         withOptions: (options) => createUserClient({ ...config, clientRequestId: options.clientRequestId }),
     };
 }
@@ -62,6 +71,10 @@ export class BlazingAgents {
     merchantConnection;
     merchantBindings;
     merchantUsageEvents;
+    /**
+     * Creates a client. Defaults to the hosted API and removes trailing base URL slashes.
+     * @param options - Configuration for this operation.
+     */
     constructor(options) {
         this.config = {
             apiKey: options.apiKey,
@@ -89,10 +102,19 @@ export class BlazingAgents {
         this.merchantBindings = createMerchantBindingsResource(this.config);
         this.merchantUsageEvents = createMerchantUsageEventsResource(this.config);
     }
+    /**
+     * Returns the Skill operations for the selected Agent.
+     * @returns The selected Agent Skill client.
+     */
     agent({ agentId }) {
         return { skills: createAgentSkillsResource(this.config, agentId) };
     }
-    /** Scope requests to one end user. IDs use printable ASCII, at most 256 characters, without leading or trailing spaces. */
+    /**
+     * 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.
+     */
     forUser(userId) {
         return createUserClient({
             ...this.config,
@@ -103,6 +125,8 @@ export class BlazingAgents {
      * `POST /v1/agents/:agentId/sessions` (create, no `sessionId`) or
      * `POST /v1/agents/:agentId/sessions/:sessionId` (resume). Returns the
      * session id and a byte-compatible SSE relay for `useChat`.
+     * @param input - Agent, message or stored Prompt, and optional existing Session.
+     * @returns The Session ID promise and single-owner SSE accessors.
      */
     chat(input) {
         return chat(this.config, input);
@@ -110,6 +134,8 @@ export class BlazingAgents {
     /**
      * Records a complete Tool approval round and streams its continuation.
      * Caller-local function handlers apply only to this invocation.
+     * @param input - Agent, Session, and decisions for the complete approval round.
+     * @returns The Session ID promise and continuation SSE accessors.
      */
     continueChat(input) {
         return continueChat(this.config, input);
@@ -117,6 +143,8 @@ export class BlazingAgents {
     /**
      * `POST /v1/agents/:agentId/generation` — stateless one-shot text
      * stream. Returns `textStream` + `await result.text` + `toResponse()`.
+     * @param input - Agent and literal prompt or stored Prompt reference.
+     * @returns Independent text stream, final text promise, and response relay.
      */
     completion(input) {
         return completion(this.config, input);
@@ -124,6 +152,8 @@ export class BlazingAgents {
     /**
      * `POST /v1/agents/:agentId/generation` — stateless structured output.
      * Returns `partialObjectStream` + `await result.object` + `toResponse()`.
+     * @param input - Agent, prompt source, and JSON output schema.
+     * @returns Partial JSON objects, a final JSON promise, and a text response relay.
      */
     object(input) {
         return objectGeneration(this.config, input);
@@ -131,6 +161,8 @@ export class BlazingAgents {
     /**
      * Returns a lightweight client view whose resource and generation calls
      * carry caller-owned correlation without raw header manipulation.
+     * @param options - Caller-owned request correlation ID for subsequent calls.
+     * @returns A new client carrying the supplied correlation ID.
      */
     withOptions(options) {
         return new BlazingAgents({

package/dist/contracts/api.d.ts

@@ -56,9 +56,11 @@ export declare const apiErrorCodeSchema: z.ZodEnum<{
     merchant_event_state_conflict: "merchant_event_state_conflict";
     merchant_provider_unavailable: "merchant_provider_unavailable";
     merchant_subscription_required: "merchant_subscription_required";
+    message_id_conflict: "message_id_conflict";
     message_not_found: "message_not_found";
     model_discovery_unsupported: "model_discovery_unsupported";
     model_not_found: "model_not_found";
+    model_spending_limit_exceeded: "model_spending_limit_exceeded";
     model_validation_unavailable: "model_validation_unavailable";
     not_found: "not_found";
     prompt_variable_missing: "prompt_variable_missing";
@@ -73,6 +75,8 @@ export declare const apiErrorCodeSchema: z.ZodEnum<{
     rate_limited: "rate_limited";
     service_unavailable: "service_unavailable";
     session_busy: "session_busy";
+    session_fork_deleted: "session_fork_deleted";
+    session_fork_unavailable: "session_fork_unavailable";
     session_version_mismatch: "session_version_mismatch";
     skill_invalid_archive: "skill_invalid_archive";
     skill_invalid_markdown: "skill_invalid_markdown";
@@ -136,9 +140,11 @@ export declare const apiErrorSchema: z.ZodObject<{
         merchant_event_state_conflict: "merchant_event_state_conflict";
         merchant_provider_unavailable: "merchant_provider_unavailable";
         merchant_subscription_required: "merchant_subscription_required";
+        message_id_conflict: "message_id_conflict";
         message_not_found: "message_not_found";
         model_discovery_unsupported: "model_discovery_unsupported";
         model_not_found: "model_not_found";
+        model_spending_limit_exceeded: "model_spending_limit_exceeded";
         model_validation_unavailable: "model_validation_unavailable";
         not_found: "not_found";
         prompt_variable_missing: "prompt_variable_missing";
@@ -153,6 +159,8 @@ export declare const apiErrorSchema: z.ZodObject<{
         rate_limited: "rate_limited";
         service_unavailable: "service_unavailable";
         session_busy: "session_busy";
+        session_fork_deleted: "session_fork_deleted";
+        session_fork_unavailable: "session_fork_unavailable";
         session_version_mismatch: "session_version_mismatch";
         skill_invalid_archive: "skill_invalid_archive";
         skill_invalid_markdown: "skill_invalid_markdown";
@@ -221,9 +229,11 @@ export declare const apiErrorResponseSchema: z.ZodObject<{
             merchant_event_state_conflict: "merchant_event_state_conflict";
             merchant_provider_unavailable: "merchant_provider_unavailable";
             merchant_subscription_required: "merchant_subscription_required";
+            message_id_conflict: "message_id_conflict";
             message_not_found: "message_not_found";
             model_discovery_unsupported: "model_discovery_unsupported";
             model_not_found: "model_not_found";
+            model_spending_limit_exceeded: "model_spending_limit_exceeded";
             model_validation_unavailable: "model_validation_unavailable";
             not_found: "not_found";
             prompt_variable_missing: "prompt_variable_missing";
@@ -238,6 +248,8 @@ export declare const apiErrorResponseSchema: z.ZodObject<{
             rate_limited: "rate_limited";
             service_unavailable: "service_unavailable";
             session_busy: "session_busy";
+            session_fork_deleted: "session_fork_deleted";
+            session_fork_unavailable: "session_fork_unavailable";
             session_version_mismatch: "session_version_mismatch";
             skill_invalid_archive: "skill_invalid_archive";
             skill_invalid_markdown: "skill_invalid_markdown";
@@ -284,17 +296,29 @@ export interface ApiErrorOptions {
     details?: Record<string, unknown>;
     param?: string;
 }
+/**
+ * Builds an API error envelope with optional parameter and detail fields.
+ * @param code - API error code for programmatic handling.
+ * @param message - Human-readable error description.
+ * @param options - Configuration for this operation.
+ */
 export declare function apiError(code: ApiErrorCode, message: string, options?: ApiErrorOptions): ApiErrorResponse;
 /**
  * Cursor pagination — `{ data, nextCursor }` on unbounded list surfaces,
  * including sessions, transcripts, artifacts, and memories.
  * `nextCursor` is opaque (base64 of the keyset); `null` means no more pages.
+ * @param data - Response data to wrap in the success envelope.
+ * @param nextCursor - Next Cursor.
  */
 export declare function paginatedResponse<T>(data: T[], nextCursor: string | null): {
     data: T[];
     nextCursor: string | null;
 };
 export declare const cursorSchema: z.ZodString;
+/**
+ * Creates a schema for a data page and nullable next cursor.
+ * @param itemSchema - Item Schema.
+ */
 export declare function paginatedResponseSchema<T extends z.ZodTypeAny>(itemSchema: T): z.ZodObject<{
     data: z.ZodArray<T>;
     nextCursor: z.ZodNullable<z.ZodString>;
@@ -309,8 +333,21 @@ export declare function paginatedResponseSchema<T extends z.ZodTypeAny>(itemSche
 export declare class CursorDecodeError extends Error {
     readonly errorCode = "INVALID_CURSOR";
     readonly statusCode = 400;
+    /**
+     * Creates the error with the supplied message.
+     * @param message - Human-readable error description.
+     * @param options - Configuration for this operation.
+     */
     constructor(message: string, options?: ErrorOptions);
 }
+/**
+ * Encodes a cursor payload as URL-safe base64 JSON.
+ * @param payload - JSON-serializable cursor fields. This function does not validate them.
+ */
 export declare function encodeCursor(payload: Record<string, unknown>): string;
+/**
+ * Decodes and validates a URL-safe base64 JSON cursor.
+ * @param cursor - URL-safe base64 JSON cursor to decode.
+ */
 export declare function decodeCursor(cursor: string): Record<string, unknown>;
 export {};

package/dist/contracts/api.js

@@ -19,6 +19,8 @@ export const apiErrorIssueSchema = z
 export const apiErrorCodeSchema = z.enum([
     "invalid_request",
     "idempotency_conflict",
+    "session_fork_deleted",
+    "session_fork_unavailable",
     "input_idempotency_conflict",
     "steer_not_available",
     "validation_failed",
@@ -26,6 +28,7 @@ export const apiErrorCodeSchema = z.enum([
     "forbidden",
     "not_found",
     "quota_exceeded",
+    "model_spending_limit_exceeded",
     "subscription_required",
     "usage_credit_required",
     "rate_limited",
@@ -41,6 +44,7 @@ export const apiErrorCodeSchema = z.enum([
     "artifact_session_cap_reached",
     "invalid_cursor",
     "message_not_found",
+    "message_id_conflict",
     "prompt_variable_missing",
     "prompt_variable_unknown",
     "provider_in_use",
@@ -125,6 +129,12 @@ export const receivedApiErrorResponseSchema = z
     error: receivedApiErrorSchema,
 })
     .passthrough();
+/**
+ * Builds an API error envelope with optional parameter and detail fields.
+ * @param code - API error code for programmatic handling.
+ * @param message - Human-readable error description.
+ * @param options - Configuration for this operation.
+ */
 export function apiError(code, message, options = {}) {
     return {
         error: {
@@ -141,11 +151,17 @@ export function apiError(code, message, options = {}) {
  * Cursor pagination — `{ data, nextCursor }` on unbounded list surfaces,
  * including sessions, transcripts, artifacts, and memories.
  * `nextCursor` is opaque (base64 of the keyset); `null` means no more pages.
+ * @param data - Response data to wrap in the success envelope.
+ * @param nextCursor - Next Cursor.
  */
 export function paginatedResponse(data, nextCursor) {
     return { data, nextCursor };
 }
 export const cursorSchema = z.string().trim().min(1);
+/**
+ * Creates a schema for a data page and nullable next cursor.
+ * @param itemSchema - Item Schema.
+ */
 export function paginatedResponseSchema(itemSchema) {
     return z
         .object({
@@ -164,6 +180,11 @@ export function paginatedResponseSchema(itemSchema) {
 export class CursorDecodeError extends Error {
     errorCode = "INVALID_CURSOR";
     statusCode = 400;
+    /**
+     * Creates the error with the supplied message.
+     * @param message - Human-readable error description.
+     * @param options - Configuration for this operation.
+     */
     constructor(message, options) {
         super(message, options);
         this.name = "CursorDecodeError";
@@ -174,6 +195,10 @@ const BASE64_SLASH = /\//g;
 const BASE64_PADDING = /[=]+$/;
 const BASE64_DASH = /-/g;
 const BASE64_UNDERSCORE = /_/g;
+/**
+ * Encodes a cursor payload as URL-safe base64 JSON.
+ * @param payload - JSON-serializable cursor fields. This function does not validate them.
+ */
 export function encodeCursor(payload) {
     const json = JSON.stringify(payload);
     const bytes = new TextEncoder().encode(json);
@@ -186,6 +211,10 @@ export function encodeCursor(payload) {
         .replace(BASE64_SLASH, "_")
         .replace(BASE64_PADDING, "");
 }
+/**
+ * Decodes and validates a URL-safe base64 JSON cursor.
+ * @param cursor - URL-safe base64 JSON cursor to decode.
+ */
 export function decodeCursor(cursor) {
     let json;
     try {

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-/** Tool groups an Agent can attach. File operations use its durable Workspace. */
+/** Tool groups an Agent can attach. File operations use its Workspace. */
 export declare const agentToolGroupIds: readonly ["workspace", "write_todos", "memory"];
 export type AgentToolGroupId = (typeof agentToolGroupIds)[number];
 export interface AgentToolGroup {
@@ -11,7 +11,7 @@ export interface AgentToolGroup {
 export declare const AGENT_TOOL_CATALOG: readonly [{
     readonly id: "workspace";
     readonly name: "File operations";
-    readonly description: "Read, write, edit, search, and run shell commands in the attached durable Workspace.";
+    readonly description: "Read, write, edit, search, and run shell commands in the attached Workspace.";
     readonly tools: readonly ["read", "write", "edit", "grep", "glob", "bash", "publish_artifacts"];
 }, {
     readonly id: "write_todos";
@@ -24,6 +24,9 @@ export declare const AGENT_TOOL_CATALOG: readonly [{
     readonly description: "Save, recall, search, update, and delete durable notes owned by this Agent.";
     readonly tools: readonly ["save_memory", "get_memory", "search_memories", "update_memory", "delete_memory"];
 }];
+/**
+ * Expands tool group names into their individual tool names.
+ */
 export declare function expandToolGroups(ids: Iterable<string>): Set<string>;
 /**
  * A model-facing tool name. Built-in tool names and the `mcp__` prefix used

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-/** Tool groups an Agent can attach. File operations use its durable Workspace. */
+/** Tool groups an Agent can attach. File operations use its Workspace. */
 export const agentToolGroupIds = [
     "workspace",
     "write_todos",
@@ -9,7 +9,7 @@ export const AGENT_TOOL_CATALOG = [
     {
         id: "workspace",
         name: "File operations",
-        description: "Read, write, edit, search, and run shell commands in the attached durable Workspace.",
+        description: "Read, write, edit, search, and run shell commands in the attached Workspace.",
         tools: [
             "read",
             "write",
@@ -39,6 +39,9 @@ export const AGENT_TOOL_CATALOG = [
         ],
     },
 ];
+/**
+ * Expands tool group names into their individual tool names.
+ */
 export function expandToolGroups(ids) {
     const result = new Set();
     for (const id of ids) {

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

@@ -518,6 +518,10 @@ 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>;

package/dist/contracts/entities/agents.js

@@ -6,6 +6,7 @@ import { atLeastOneFieldMessage, hasObjectKeys, hasUniqueValues, } from "../util
 import { approvalPolicySchema } from "./agent-approval.js";
 import { agentToolGroupIds } from "./agent-tools.js";
 import { metadataSchema, userIdSchema } from "./attribution.js";
+import { workspaceTierSchema } from "./workspaces.js";
 const approvalFields = {
     approvalInChat: approvalPolicySchema.default({
         default: "full",
@@ -35,6 +36,9 @@ export const agentMcpConnectionIdsSchema = z
 });
 export const agentStatusSchema = z.enum(["active", "disabled"]);
 const providerModelPairMessage = "Provider and model must either both be set or both be null.";
+/**
+ * Checks that provider and model selections are both present or both absent.
+ */
 function hasProviderModelPair(input) {
     return (input.model === null) === (input.providerId === null);
 }
@@ -114,6 +118,7 @@ export const createAgentBodySchema = z
     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: agentSchema.shape.compactionReserveTokens.default(16_384),
     memoryInjectionEnabled: z.boolean().default(false),
@@ -124,6 +129,10 @@ export const createAgentBodySchema = z
     mcpConnectionIds: agentMcpConnectionIdsSchema.default([]),
 })
     .strict()
+    .refine((input) => input.workspaceId === undefined || input.workspaceTier === undefined, {
+    message: "workspaceId and workspaceTier are mutually exclusive.",
+    path: ["workspaceTier"],
+})
     .refine(hasProviderModelPair, {
     message: providerModelPairMessage,
     path: ["providerId"],

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

@@ -110,6 +110,9 @@ export declare const jsonSchemaShapeSchema: z.ZodCustom<z.core.JSONSchema.JSONSc
 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;
+/**
+ * Measures the UTF-8 byte length of a JSON-serialized value.
+ */
 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<{

package/dist/contracts/entities/chat.js

@@ -61,6 +61,9 @@ export const blazingAgentsChatMessageMetadataSchema = z
  */
 export const promptVariablesSchema = z.record(z.string(), z.string());
 const JSON_SCHEMA_COMPOSITION_KEYS = ["allOf", "anyOf", "oneOf"];
+/**
+ * Checks whether the JSON Schema root contains a meaningful schema keyword.
+ */
 function hasMeaningfulSchemaRoot(value, definitions, seenReferences) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         return false;
@@ -120,6 +123,9 @@ export const jsonSchemaShapeSchema = z.custom((value) => {
 export const MAX_CHAT_FUNCTIONS = 32;
 export const MAX_CHAT_FUNCTION_DEFINITIONS_BYTES = 64 * 1024;
 export const MAX_CHAT_FUNCTION_PAYLOAD_BYTES = 256 * 1024;
+/**
+ * Measures the UTF-8 byte length of a JSON-serialized value.
+ */
 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

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

@@ -16,7 +16,9 @@ export declare const mcpConnectionTestErrorCodeSchema: z.ZodEnum<{
     MCP_CONNECTION_INVALID: "MCP_CONNECTION_INVALID";
     MCP_CONNECTION_UNREACHABLE: "MCP_CONNECTION_UNREACHABLE";
 }>;
-/** Mirrors the MCP SDK's SEP-2352 issuer-identity comparison. */
+/**
+ * Mirrors the MCP SDK's SEP-2352 issuer-identity comparison.
+ */
 export declare function mcpOauthIssuersMatch(a: string, b: string): boolean;
 export declare const mcpOauthClientCredentialsBundleSchema: z.ZodObject<{
     clientInformation: z.ZodObject<{

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

@@ -75,7 +75,9 @@ const oauthIssuerSchema = z
 })
     .transform((value) => new URL(value).toString());
 const credentialFragmentSchema = z.string().min(1).max(4).nullable();
-/** Mirrors the MCP SDK's SEP-2352 issuer-identity comparison. */
+/**
+ * Mirrors the MCP SDK's SEP-2352 issuer-identity comparison.
+ */
 export function mcpOauthIssuersMatch(a, b) {
     return (a === b ||
         (a.endsWith("/") && a.slice(0, -1) === b) ||