@blazingagents/sdk 0.19.0 → 0.21.0

package/dist/direct-chat-transport.js

@@ -1,10 +1,14 @@
 import { DefaultChatTransport, lastAssistantMessageIsCompleteWithApprovalResponses, } from "ai";
-import { decideApprovalResponses } from "./approvals.js";
+import { extractApprovalDecisions } from "./approvals.js";
 import { sessionIdSchema } from "./contracts/ids.js";
 /** Connects useChat directly to the SDK, including native streaming fetch clients. */
 export class BlazingAgentsDirectChatTransport extends DefaultChatTransport {
     #options;
     #sessionId;
+    /**
+     * Creates a chat transport and validates any supplied Session ID.
+     * @param options - Configuration for this operation.
+     */
     constructor(options) {
         super();
         this.#options = options;
@@ -13,19 +17,28 @@ export class BlazingAgentsDirectChatTransport extends DefaultChatTransport {
                 ? undefined
                 : sessionIdSchema.parse(options.sessionId);
     }
-    async runInputs(input = {}) {
-        if (this.#sessionId === undefined) {
-            throw new Error("Input batch admission requires an existing Session.");
-        }
+    /**
+     * Submits the supplied user messages directly to the SDK chat endpoint.
+     * @param input - Operation input and optional cancellation signal.
+     * @returns The decoded AI SDK message-chunk stream.
+     */
+    async sendUserMessages(input) {
         const client = await this.#options.getClient();
-        const result = await client.sessions.runInputs({
+        const result = await client.chat({
             ...input,
             agentId: this.#options.agentId,
             sessionId: this.#sessionId,
             functions: this.#options.functions,
+            userId: this.#options.userId,
+            metadata: this.#options.metadata,
         });
-        return this.processResponseStream(result.toStream());
+        return this.#processChatResult(result);
     }
+    /**
+     * 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.
+     */
     async sendMessages(input) {
         if (input.trigger === "regenerate-message" && !this.#sessionId) {
             throw new Error("Regeneration requires an existing Session.");
@@ -79,6 +92,12 @@ export class BlazingAgentsDirectChatTransport extends DefaultChatTransport {
                 trigger: input.trigger,
             });
         }
+        return this.#processChatResult(result);
+    }
+    /**
+     * Claims the chat stream and records the first Session ID before decoding chunks.
+     */
+    async #processChatResult(result) {
         const stream = result.toStream();
         try {
             const sessionId = await result.sessionId;
@@ -93,26 +112,18 @@ export class BlazingAgentsDirectChatTransport extends DefaultChatTransport {
         }
         return this.processResponseStream(stream);
     }
-    async reconnectToStream(_input) {
-        if (this.#sessionId === undefined) {
-            return null;
-        }
-        const client = await this.#options.getClient();
-        const { continuation } = await client.sessions.toolApprovals({
-            agentId: this.#options.agentId,
-            sessionId: this.#sessionId,
-        });
-        if (continuation?.state !== "queued" && continuation?.state !== "running") {
-            return null;
-        }
-        const result = await client.resumeChat({
-            agentId: this.#options.agentId,
-            sessionId: this.#sessionId,
-            continuationId: continuation.id,
-            functions: this.#options.functions ?? {},
-        });
-        return this.processResponseStream(result.toStream());
+    /**
+     * 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);
     }
+    /**
+     * Submits the last assistant approval round for the existing Session.
+     * @param input - Operation input and optional cancellation signal.
+     */
     async #sendApprovalContinuation(input, last) {
         if (this.#sessionId === undefined) {
             throw new Error("Tool approval requires an existing Session.");
@@ -123,16 +134,10 @@ export class BlazingAgentsDirectChatTransport extends DefaultChatTransport {
             sessionId: this.#sessionId,
             abortSignal: input.abortSignal,
         };
-        const continuationId = await decideApprovalResponses(client, {
-            ...target,
-            message: last,
-        });
-        if (continuationId === undefined) {
-            throw new Error("Tool approval response is missing an approval.");
-        }
-        const continuation = await client.resumeChat({
+        const decisions = extractApprovalDecisions(last);
+        const continuation = await client.continueChat({
             ...target,
-            continuationId,
+            decisions,
             functions: this.#options.functions ?? {},
         });
         return this.processResponseStream(continuation.toStream());

package/dist/errors.d.ts

@@ -17,6 +17,10 @@ export declare class BlazingAgentsError extends Error {
      * biome-ignore lint/correctness/noUnusedPrivateClassMembers: marker pattern
      */
     private readonly [BLAZING_AGENTS_ERROR_SYMBOL];
+    /**
+     * Creates an SDK error with its code, diagnostics, and optional cause.
+     * @param options - Configuration for this operation.
+     */
     constructor({ code, details, headers, message, param, requestId, responseBody, responseBodyTruncated, status, }: {
         code: BlazingAgentsErrorCode;
         details?: Record<string, unknown>;
@@ -28,6 +32,11 @@ export declare class BlazingAgentsError extends Error {
         responseBodyTruncated?: boolean;
         status?: number;
     }, options?: ErrorOptions);
+    /**
+     * Checks the shared symbol marker, including errors from duplicated SDK packages.
+     * @param error - Value to inspect or handle.
+     * @returns Whether the value carries the SDK error marker.
+     */
     static isInstance(error: unknown): error is BlazingAgentsError;
 }
 export {};

package/dist/errors.js

@@ -27,6 +27,10 @@ export class BlazingAgentsError extends Error {
      */
     [BLAZING_AGENTS_ERROR_SYMBOL] = true;
     // Stryker restore BooleanLiteral
+    /**
+     * Creates an SDK error with its code, diagnostics, and optional cause.
+     * @param options - Configuration for this operation.
+     */
     constructor({ code, details, headers, message, param, requestId, responseBody, responseBodyTruncated, status, }, options) {
         super(`[${code}] ${message}`, options);
         this.name = BLAZING_AGENTS_ERROR_NAME;
@@ -39,6 +43,11 @@ export class BlazingAgentsError extends Error {
         this.responseBodyTruncated = responseBodyTruncated;
         this.status = status;
     }
+    /**
+     * Checks the shared symbol marker, including errors from duplicated SDK packages.
+     * @param error - Value to inspect or handle.
+     * @returns Whether the value carries the SDK error marker.
+     */
     static isInstance(error) {
         if (error === null || typeof error !== "object") {
             return false;

package/dist/functions.d.ts

@@ -9,12 +9,28 @@ export interface ChatFunctionContext {
 }
 export interface ChatFunction<Schema extends z.ZodType = z.ZodType, Output = unknown> {
     description: string;
+    /**
+     * Runs a caller-local function with validated input and deadline cancellation.
+     * @param input - Input parsed by inputSchema.
+     * @param context - Function-call idempotency key and cancellation signal.
+     * @returns The function output, synchronously or as a promise.
+     */
     execute(input: z.output<Schema>, context: ChatFunctionContext): Output | Promise<Output>;
     inputSchema: Schema;
 }
 export type ChatFunctions = Record<string, ChatFunction>;
-/** Declares a caller-local function whose handler input is inferred from its Zod schema. */
+/**
+ * Declares a caller-local function whose handler input is inferred from its Zod schema.
+ * @param definition - Description, input schema, and local handler.
+ * @returns The unchanged definition with inferred handler types.
+ */
 export declare function defineFunction<Schema extends z.ZodType, Output>(definition: ChatFunction<Schema, Output>): ChatFunction<Schema, Output>;
+/**
+ * Converts caller-local Zod input schemas to validated JSON Schema definitions.
+ * @param functions - Caller-local function handlers keyed by name.
+ * @returns Validated function descriptions and JSON input schemas.
+ * @throws BlazingAgentsError - If a definition cannot be represented as a valid JSON Schema.
+ */
 export declare function toChatFunctionDefinitions(functions: ChatFunctions): ChatFunctionDefinitions;
 export interface FunctionDispatchTarget {
     abortSignal?: AbortSignal;
@@ -23,16 +39,33 @@ export interface FunctionDispatchTarget {
     sessionId: string;
 }
 interface FunctionEventHandlers {
+    /**
+     * Dispatches a function call without blocking the stream reader.
+     * @param call - Private function-call event payload.
+     * @param fail - Reports a dispatch failure to the stream reader.
+     */
     onCall?(call: ChatFunctionCallEvent["data"], fail: (error: unknown) => void): void;
+    /**
+     * Handles consumer cancellation.
+     */
     onCancel?(): void;
+    /**
+     * Stops function handlers when the upstream stream ends.
+     */
     onEnd?(): void;
 }
 /**
  * Reads native SSE eagerly and returns it without private function events,
  * so slow consumers never delay a call. A recognized but malformed event
  * fails the stream.
+ * @param body - Upstream SSE byte stream.
  */
 export declare function stripFunctionEvents(body: ReadableStream<Uint8Array>, { onCall, onCancel, onEnd }?: FunctionEventHandlers): ReadableStream<Uint8Array>;
-/** Strips private function events and executes claimed calls without blocking the read loop. */
+/**
+ * Strips private function events and executes claimed calls without blocking the read loop.
+ * @param config - Authentication, base URL, and transport configuration.
+ * @param target - Agent, Session, local handlers, and caller cancellation signal.
+ * @param body - Upstream SSE byte stream.
+ */
 export declare function dispatchChatFunctions(config: HttpConfig, target: FunctionDispatchTarget, body: ReadableStream<Uint8Array>): ReadableStream<Uint8Array>;
 export {};

package/dist/functions.js

@@ -2,10 +2,20 @@ import { z } from "zod";
 import { chatFunctionCallEventSchema, chatFunctionDefinitionsSchema, chatFunctionOutcomeSchema, claimChatFunctionResponseSchema, resolveChatFunctionResponseSchema, } from "./contracts/entities/chat.js";
 import { BlazingAgentsError } from "./errors.js";
 import { requestJson } from "./http.js";
-/** Declares a caller-local function whose handler input is inferred from its Zod schema. */
+/**
+ * Declares a caller-local function whose handler input is inferred from its Zod schema.
+ * @param definition - Description, input schema, and local handler.
+ * @returns The unchanged definition with inferred handler types.
+ */
 export function defineFunction(definition) {
     return definition;
 }
+/**
+ * Converts caller-local Zod input schemas to validated JSON Schema definitions.
+ * @param functions - Caller-local function handlers keyed by name.
+ * @returns Validated function descriptions and JSON input schemas.
+ * @throws BlazingAgentsError - If a definition cannot be represented as a valid JSON Schema.
+ */
 export function toChatFunctionDefinitions(functions) {
     try {
         return chatFunctionDefinitionsSchema.parse(Object.fromEntries(Object.entries(functions).map(([name, fn]) => {
@@ -54,6 +64,9 @@ function functionCallFrom(block) {
     }
     return chatFunctionCallEventSchema.safeParse(parsed).data ?? null;
 }
+/**
+ * Reads Retry-After as seconds or an HTTP date and clamps past dates to zero.
+ */
 function retryAfterMs(headers) {
     const value = headers?.get("retry-after");
     if (!value) {
@@ -64,6 +77,9 @@ function retryAfterMs(headers) {
         : Date.parse(value) - Date.now();
     return Number.isNaN(ms) ? undefined : Math.max(0, ms);
 }
+/**
+ * Returns the retry delay for transient transport or HTTP failures.
+ */
 function retryDelayMs({ code, headers, status }, attempt) {
     const retryable = status === undefined
         ? code === "network_error"
@@ -74,6 +90,9 @@ function retryDelayMs({ code, headers, status }, attempt) {
     return (retryAfterMs(headers) ??
         Math.min(RETRY_BASE_MS * 2 ** (attempt - 1), RETRY_MAX_MS));
 }
+/**
+ * Waits for the delay or resolves early when the signal aborts.
+ */
 function sleep(ms, signal) {
     return new Promise((resolve) => {
         const timer = setTimeout(resolve, ms);
@@ -111,7 +130,9 @@ async function postWithRetry(config, path, json, schema, until, signal) {
         }
     }
 }
-/** Classifies a failed attempt as a lost race, an exhausted budget, or the delay before retrying; permanent failures rethrow. */
+/**
+ * Classifies a failed attempt as a lost race, an exhausted budget, or the delay before retrying; permanent failures rethrow.
+ */
 function afterFailure(caught, attempt, until, signal) {
     const error = BlazingAgentsError.isInstance(caught) ? caught : undefined;
     if (error?.status === 409) {
@@ -130,7 +151,9 @@ const invalidResult = {
     kind: "error",
     message: "Function returned an invalid result.",
 };
-/** Resolves `undefined` when the call became late or aborted before customer code could start. */
+/**
+ * Resolves `undefined` when the call became late or aborted before customer code could start.
+ */
 async function execute(functions, { id, name, input }, deadline, signal) {
     const fn = Object.hasOwn(functions, name) ? functions[name] : undefined;
     if (fn === undefined) {
@@ -175,6 +198,7 @@ async function execute(functions, { id, name, input }, deadline, signal) {
  * Reads native SSE eagerly and returns it without private function events,
  * so slow consumers never delay a call. A recognized but malformed event
  * fails the stream.
+ * @param body - Upstream SSE byte stream.
  */
 export function stripFunctionEvents(body, { onCall, onCancel, onEnd } = {}) {
     const reader = body.getReader();
@@ -182,6 +206,9 @@ export function stripFunctionEvents(body, { onCall, onCancel, onEnd } = {}) {
     const encoder = new TextEncoder();
     let output;
     let finished = false;
+    /**
+     * Fails the output stream once and cancels its upstream reader.
+     */
     const fail = (error) => {
         if (finished) {
             return;
@@ -190,6 +217,9 @@ export function stripFunctionEvents(body, { onCall, onCancel, onEnd } = {}) {
         output.error(error);
         reader.cancel(error).catch(() => undefined);
     };
+    /**
+     * Forwards public SSE blocks and dispatches or rejects private function events.
+     */
     const handleBlock = (block, raw) => {
         const call = functionCallFrom(block);
         if (call === undefined) {
@@ -207,6 +237,9 @@ export function stripFunctionEvents(body, { onCall, onCancel, onEnd } = {}) {
             onCall?.(call.data, fail);
         }
     };
+    /**
+     * Reads SSE bytes eagerly and splits complete event blocks for dispatch.
+     */
     const pump = async () => {
         let buffer = "";
         try {
@@ -236,10 +269,16 @@ export function stripFunctionEvents(body, { onCall, onCancel, onEnd } = {}) {
         }
     };
     return new ReadableStream({
+        /**
+         * Initializes the stream controller.
+         */
         start(controller) {
             output = controller;
             pump();
         },
+        /**
+         * Cancels the upstream reader with the consumer reason.
+         */
         async cancel(reason) {
             finished = true;
             onCancel?.();
@@ -247,12 +286,20 @@ export function stripFunctionEvents(body, { onCall, onCancel, onEnd } = {}) {
         },
     });
 }
-/** Strips private function events and executes claimed calls without blocking the read loop. */
+/**
+ * Strips private function events and executes claimed calls without blocking the read loop.
+ * @param config - Authentication, base URL, and transport configuration.
+ * @param target - Agent, Session, local handlers, and caller cancellation signal.
+ * @param body - Upstream SSE byte stream.
+ */
 export function dispatchChatFunctions(config, target, body) {
     /** Caller abort or consumer cancellation: stops every retry. */
     const stop = new AbortController();
     /** Also aborted when the stream ends: stops claims and handlers. */
     const handlers = new AbortController();
+    /**
+     * Aborts pending function claims and retries.
+     */
     const abort = () => stop.abort();
     stop.signal.addEventListener("abort", () => handlers.abort(), {
         once: true,
@@ -262,6 +309,9 @@ export function dispatchChatFunctions(config, target, body) {
         abort();
     }
     const dispatched = new Set();
+    /**
+     * Claims a function call, runs its handler, and posts the result within its retry budget.
+     */
     const runCall = async (call) => {
         const path = `/v1/agents/${target.agentId}/sessions/${target.sessionId}/function-calls/${call.id}`;
         const claimRequestId = crypto.randomUUID();
@@ -284,6 +334,9 @@ export function dispatchChatFunctions(config, target, body) {
         await postWithRetry(config, `${path}/result`, { claimRequestId, outcome }, resolveChatFunctionResponseSchema, deadline + RESULT_RETRY_GRACE_MS, stop.signal);
     };
     return stripFunctionEvents(body, {
+        /**
+         * Dispatches a function call without blocking the stream reader.
+         */
         onCall(call, fail) {
             if (!dispatched.has(call.id)) {
                 dispatched.add(call.id);
@@ -291,6 +344,9 @@ export function dispatchChatFunctions(config, target, body) {
             }
         },
         onCancel: abort,
+        /**
+         * Stops function handlers when the upstream stream ends.
+         */
         onEnd() {
             handlers.abort();
             target.abortSignal?.removeEventListener("abort", abort);

package/dist/generation.d.ts

@@ -1,11 +1,43 @@
-import type { ChatInput, ChatResult, CompletionInput, CompletionResult, HttpConfig, ObjectInput, ObjectResult, ResumeChatInput, TerminalStreamResult } from "./types.ts";
+import type { ChatInput, ChatResult, CompletionInput, CompletionResult, ContinueChatInput, HttpConfig, ObjectInput, ObjectResult, TerminalStreamResult } from "./types.ts";
+/**
+ * Creates or resumes a Session and returns its SSE stream and Session ID.
+ * @param config - Authentication, base URL, and transport configuration.
+ * @param input - Agent, message or stored Prompt, and optional existing Session.
+ * @returns The Session ID promise and single-owner SSE accessors.
+ */
 export declare function chat(config: HttpConfig, input: ChatInput): Promise<ChatResult>;
-export declare function resumeChat(config: HttpConfig, input: ResumeChatInput): Promise<ChatResult>;
+/**
+ * Submits a complete Tool approval round and streams its continuation.
+ * @param config - Authentication, base URL, and transport configuration.
+ * @param input - Agent, Session, and decisions for the complete approval round.
+ * @returns The Session ID promise and continuation SSE accessors.
+ */
+export declare function continueChat(config: HttpConfig, input: ContinueChatInput): Promise<ChatResult>;
 /**
  * Keeps status and headers while filtering the SSE body. Missing or locked
  * bodies pass through so the stream result reports them as `stream_error`.
+ * @param response - Upstream HTTP response.
+ * @param filter - Transforms upstream SSE bytes before exposing them to the caller.
  */
 export declare function withFilteredBody(response: Response, filter: (body: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>): Response;
+/**
+ * Creates single-owner SSE response and byte-stream accessors.
+ * @param response - Upstream HTTP response.
+ * @param resourceName - Resource label used in stream errors.
+ * @param filter - Transforms upstream SSE bytes before exposing them to the caller.
+ */
 export declare function buildTerminalStreamResult(response: Response, resourceName: string, filter?: (body: ReadableStream<Uint8Array>) => ReadableStream<Uint8Array>): TerminalStreamResult;
+/**
+ * Starts stateless text generation with independent final, incremental, and response outputs.
+ * @param config - Authentication, base URL, and transport configuration.
+ * @param input - Agent and literal prompt or stored Prompt reference.
+ * @returns Independent text stream, final text promise, and response relay.
+ */
 export declare function completion(config: HttpConfig, input: CompletionInput): Promise<CompletionResult>;
+/**
+ * Starts stateless JSON generation with partial objects and a final parsed value.
+ * @param config - Authentication, base URL, and transport configuration.
+ * @param input - Agent, prompt source, and JSON output schema.
+ * @returns Partial JSON objects, a final JSON promise, and a text response relay.
+ */
 export declare function objectGeneration(config: HttpConfig, input: ObjectInput): Promise<ObjectResult>;