@blazingagents/sdk 0.19.0 → 0.21.0

package/README.md

@@ -17,7 +17,8 @@ requires Node.js 24 or newer.
 
 - Typed clients for Agents, Workspaces, Skills, Providers, Prompts, Tasks,
   Sessions, Artifacts, Slack and Telegram Chat Connections, usage, Tenant settings, and merchant monetization.
-- Stateful chat and stateless text or structured-object generation.
+- Stateful chat with explicit message batches, steer receipts, and one-call Tool approvals.
+- Stateless text or structured-object generation.
 - Public Zod contracts for validating API requests and responses.
 - Cursor pagination and binary transfers.
 - Request correlation and a typed, forward-compatible error model.
@@ -51,6 +52,21 @@ const result = await client.completion({
 console.log(await result.text);
 ```
 
+For stateful chat, pass one user message or an ordered batch.
+
+```ts
+const chat = await client.chat({
+  agentId: "ag_...",
+  messages: [
+    { id: "first", role: "user", parts: [{ type: "text", text: "Compare the plans." }] },
+    { id: "second", role: "user", parts: [{ type: "text", text: "Include annual pricing." }] },
+  ],
+});
+
+const sessionId = await chat.sessionId;
+return chat.toResponse();
+```
+
 Keep API keys on the server. For browser chat applications, relay `chat()`
 through your backend and use `BlazingAgentsChatTransport` with AI SDK
 `useChat`.

package/dist/approvals.d.ts

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

package/dist/approvals.js

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

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

@@ -7,6 +7,10 @@ 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;
@@ -14,6 +18,7 @@ export class BlazingAgentsChatTransport {
             sessionId === undefined ? undefined : sessionIdSchema.parse(sessionId);
         this.#transport = new DefaultChatTransport({
             ...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 +35,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 +62,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

@@ -1,4 +1,4 @@
-import type { AgentClient, AgentsResource, ArtifactsResource, BlazingAgentsOptions, BlazingAgentsRequestOptions, ChatConnectionsResource, ChatDeliveriesResource, ChatInput, ChatResult, CompletionInput, CompletionResult, McpConnectionsResource, MemoriesResource, MerchantBindingsResource, MerchantConnectionResource, MerchantUsageEventsResource, ObjectInput, ObjectResult, PromptsResource, ProvidersResource, ResumeChatInput, SessionsResource, TasksResource, TenantResource, UsageResource, UserClient, WorkspacesResource } from "./types.ts";
+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";
 export declare class BlazingAgents {
     private readonly config;
     readonly chatConnections: ChatConnectionsResource;
@@ -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>;
     /**
-     * Reattaches function handlers after human tool approval and starts or
-     * joins the Session's continuation. Returns the continuation SSE relay.
+     * 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.
      */
-    resumeChat(input: ResumeChatInput): Promise<ChatResult>;
+    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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { chat, completion, objectGeneration, resumeChat, } from "./generation.js";
+import { chat, completion, continueChat, objectGeneration, } from "./generation.js";
 import { createAgentsResource } from "./resources/agents.js";
 import { createArtifactsResource } from "./resources/artifacts.js";
 import { createChatConnectionsResource } from "./resources/chat-connections.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),
-        resumeChat: (input) => resumeChat(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,20 +125,26 @@ 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);
     }
     /**
-     * Reattaches function handlers after human tool approval and starts or
-     * joins the Session's continuation. Returns the continuation SSE relay.
+     * 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.
      */
-    resumeChat(input) {
-        return resumeChat(this.config, input);
+    continueChat(input) {
+        return continueChat(this.config, input);
     }
     /**
      * `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

@@ -32,7 +32,6 @@ export declare const apiErrorCodeSchema: z.ZodEnum<{
     function_call_conflict: "function_call_conflict";
     idempotency_conflict: "idempotency_conflict";
     input_idempotency_conflict: "input_idempotency_conflict";
-    input_not_pending: "input_not_pending";
     internal: "internal";
     invalid_cursor: "invalid_cursor";
     invalid_request: "invalid_request";
@@ -57,6 +56,7 @@ 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";
@@ -74,6 +74,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";
@@ -82,13 +84,14 @@ export declare const apiErrorCodeSchema: z.ZodEnum<{
     skill_not_found: "skill_not_found";
     skill_too_many_files: "skill_too_many_files";
     skill_uncompressed_too_large: "skill_uncompressed_too_large";
+    steer_not_available: "steer_not_available";
     subscription_required: "subscription_required";
     task_active_run_exists: "task_active_run_exists";
     tenant_deleting: "tenant_deleting";
     tenant_deletion_in_progress: "tenant_deletion_in_progress";
     tenant_deletion_not_ready: "tenant_deletion_not_ready";
     tenant_not_deleting: "tenant_not_deleting";
-    tool_approval_continuation_not_found: "tool_approval_continuation_not_found";
+    tool_approval_continuation_settled: "tool_approval_continuation_settled";
     tool_approval_decision_conflict: "tool_approval_decision_conflict";
     unauthorized: "unauthorized";
     usage_credit_required: "usage_credit_required";
@@ -112,7 +115,6 @@ export declare const apiErrorSchema: z.ZodObject<{
         function_call_conflict: "function_call_conflict";
         idempotency_conflict: "idempotency_conflict";
         input_idempotency_conflict: "input_idempotency_conflict";
-        input_not_pending: "input_not_pending";
         internal: "internal";
         invalid_cursor: "invalid_cursor";
         invalid_request: "invalid_request";
@@ -137,6 +139,7 @@ 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";
@@ -154,6 +157,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";
@@ -162,13 +167,14 @@ export declare const apiErrorSchema: z.ZodObject<{
         skill_not_found: "skill_not_found";
         skill_too_many_files: "skill_too_many_files";
         skill_uncompressed_too_large: "skill_uncompressed_too_large";
+        steer_not_available: "steer_not_available";
         subscription_required: "subscription_required";
         task_active_run_exists: "task_active_run_exists";
         tenant_deleting: "tenant_deleting";
         tenant_deletion_in_progress: "tenant_deletion_in_progress";
         tenant_deletion_not_ready: "tenant_deletion_not_ready";
         tenant_not_deleting: "tenant_not_deleting";
-        tool_approval_continuation_not_found: "tool_approval_continuation_not_found";
+        tool_approval_continuation_settled: "tool_approval_continuation_settled";
         tool_approval_decision_conflict: "tool_approval_decision_conflict";
         unauthorized: "unauthorized";
         usage_credit_required: "usage_credit_required";
@@ -197,7 +203,6 @@ export declare const apiErrorResponseSchema: z.ZodObject<{
             function_call_conflict: "function_call_conflict";
             idempotency_conflict: "idempotency_conflict";
             input_idempotency_conflict: "input_idempotency_conflict";
-            input_not_pending: "input_not_pending";
             internal: "internal";
             invalid_cursor: "invalid_cursor";
             invalid_request: "invalid_request";
@@ -222,6 +227,7 @@ 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";
@@ -239,6 +245,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";
@@ -247,13 +255,14 @@ export declare const apiErrorResponseSchema: z.ZodObject<{
             skill_not_found: "skill_not_found";
             skill_too_many_files: "skill_too_many_files";
             skill_uncompressed_too_large: "skill_uncompressed_too_large";
+            steer_not_available: "steer_not_available";
             subscription_required: "subscription_required";
             task_active_run_exists: "task_active_run_exists";
             tenant_deleting: "tenant_deleting";
             tenant_deletion_in_progress: "tenant_deletion_in_progress";
             tenant_deletion_not_ready: "tenant_deletion_not_ready";
             tenant_not_deleting: "tenant_not_deleting";
-            tool_approval_continuation_not_found: "tool_approval_continuation_not_found";
+            tool_approval_continuation_settled: "tool_approval_continuation_settled";
             tool_approval_decision_conflict: "tool_approval_decision_conflict";
             unauthorized: "unauthorized";
             usage_credit_required: "usage_credit_required";
@@ -284,17 +293,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 +330,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,8 +19,10 @@ export const apiErrorIssueSchema = z
 export const apiErrorCodeSchema = z.enum([
     "invalid_request",
     "idempotency_conflict",
+    "session_fork_deleted",
+    "session_fork_unavailable",
     "input_idempotency_conflict",
-    "input_not_pending",
+    "steer_not_available",
     "validation_failed",
     "unauthorized",
     "forbidden",
@@ -41,6 +43,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",
@@ -64,7 +67,7 @@ export const apiErrorCodeSchema = z.enum([
     "workspace_busy",
     "session_busy",
     "session_version_mismatch",
-    "tool_approval_continuation_not_found",
+    "tool_approval_continuation_settled",
     "tool_approval_decision_conflict",
     "function_call_conflict",
     "skill_invalid_archive",
@@ -125,6 +128,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 +150,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 +179,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 +194,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 +210,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