@blazingagents/sdk 0.20.0 → 0.21.0

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, 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>;
+/**
+ * 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>;

package/dist/generation.js

@@ -3,6 +3,12 @@ import { sessionIdSchema } from "./contracts/ids.js";
 import { BlazingAgentsError } from "./errors.js";
 import { dispatchChatFunctions, toChatFunctionDefinitions, } from "./functions.js";
 import { requestStream } from "./http.js";
+/**
+ * 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 async function chat(config, input) {
     const body = buildChatBody(input);
     if (input.functions && Object.keys(input.functions).length > 0) {
@@ -29,6 +35,12 @@ export async function chat(config, input) {
         abortSignal: input.abortSignal,
     });
 }
+/**
+ * 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 async function continueChat(config, input) {
     const response = await requestStream(config, `/v1/agents/${input.agentId}/sessions/${input.sessionId}/tool-approvals/continue`, {
         json: {
@@ -50,6 +62,8 @@ export async function continueChat(config, input) {
 /**
  * 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 function withFilteredBody(response, filter) {
     if (!response.body || response.body.locked) {
@@ -61,6 +75,9 @@ export function withFilteredBody(response, filter) {
         statusText: response.statusText,
     });
 }
+/**
+ * Builds a chat request body from messages or a stored Prompt.
+ */
 function buildChatBody(input) {
     const base = {};
     // Stryker disable next-line ConditionalExpression: JSON serialization omits an undefined trigger.
@@ -122,6 +139,9 @@ function sessionIdFromLocation(response, requestId) {
     }
     return parsed.data;
 }
+/**
+ * Combines the Session ID promise with a single-owner SSE result.
+ */
 function buildChatResult(config, response, resumeSessionId, dispatch) {
     /**
      * `sessionId` resolves from the `Location` header on create, or to the
@@ -154,10 +174,20 @@ function buildChatResult(config, response, resumeSessionId, dispatch) {
         ...buildTerminalStreamResult(streamResponse, "chat"),
     };
 }
+/**
+ * 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 function buildTerminalStreamResult(response, resourceName, filter) {
     const requestId = response.headers.get("x-request-id") ?? undefined;
     const location = response.headers.get("location");
     let bodyClaimed = false;
+    /**
+     * Claims the response body once and normalizes stream failures.
+     * @throws BlazingAgentsError - If the response body has already been claimed.
+     */
     const claimBody = () => {
         if (bodyClaimed) {
             const message = `The ${resourceName} response body has already been claimed.`;
@@ -175,6 +205,7 @@ export function buildTerminalStreamResult(response, resourceName, filter) {
     return {
         requestId,
         toStream: claimBody,
+        /** Claims the response relay once. */
         toResponse: () => {
             const headers = replacementResponseHeaders(requestId, location);
             headers.set("content-type", "text/event-stream");
@@ -195,6 +226,9 @@ export function buildTerminalStreamResult(response, resourceName, filter) {
         },
     };
 }
+/**
+ * Preserves a matching stream error or wraps a failure with request correlation.
+ */
 function toStreamError(cause, requestId, fallbackMessage) {
     if (BlazingAgentsError.isInstance(cause) &&
         cause.code === "stream_error" &&
@@ -217,6 +251,9 @@ function toStreamError(cause, requestId, fallbackMessage) {
         requestId,
     }, { cause });
 }
+/**
+ * Wraps reads and cancellation failures as correlated SDK stream errors.
+ */
 function normalizeStreamErrors(stream, requestId, fallbackMessage) {
     let reader;
     try {
@@ -226,6 +263,9 @@ function normalizeStreamErrors(stream, requestId, fallbackMessage) {
         throw toStreamError(cause, requestId, fallbackMessage);
     }
     return new ReadableStream({
+        /**
+         * Reads one upstream chunk and normalizes stream failures.
+         */
         async pull(controller) {
             try {
                 const { done, value } = await reader.read();
@@ -239,6 +279,9 @@ function normalizeStreamErrors(stream, requestId, fallbackMessage) {
                 controller.error(toStreamError(cause, requestId, fallbackMessage));
             }
         },
+        /**
+         * Cancels the upstream reader with the consumer reason.
+         */
         async cancel(reason) {
             try {
                 await reader.cancel(reason);
@@ -249,6 +292,9 @@ function normalizeStreamErrors(stream, requestId, fallbackMessage) {
         },
     });
 }
+/**
+ * Returns the response body or a stream that fails when the body is missing.
+ */
 function responseBodyStream(response, requestId, resourceName) {
     if (response.body) {
         return response.body;
@@ -261,11 +307,17 @@ function responseBodyStream(response, requestId, resourceName) {
         requestId,
     }, { cause });
     return new ReadableStream({
+        /**
+         * Initializes the stream controller.
+         */
         start(controller) {
             controller.error(error);
         },
     });
 }
+/**
+ * Copies request correlation and Session location into relay response headers.
+ */
 function replacementResponseHeaders(requestId, location) {
     const headers = new Headers();
     if (requestId !== undefined) {
@@ -276,6 +328,9 @@ function replacementResponseHeaders(requestId, location) {
     }
     return headers;
 }
+/**
+ * Builds a stateless prompt request with the selected output format.
+ */
 function buildStatelessGenerationBody(input, output) {
     const body = { output };
     if ("prompt" in input) {
@@ -298,6 +353,12 @@ function buildStatelessGenerationBody(input, output) {
     }
     return body;
 }
+/**
+ * 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 async function completion(config, input) {
     const body = buildStatelessGenerationBody(input, { type: "text" });
     const path = `/v1/agents/${input.agentId}/generation`;
@@ -309,6 +370,9 @@ export async function completion(config, input) {
     });
     return buildCompletionResult(response);
 }
+/**
+ * Splits text output into a final promise, incremental stream, and response relay.
+ */
 function buildCompletionResult(response) {
     const { finalStream, outputStream, requestId, toResponse } = buildStatelessGenerationStreams(response, "completion");
     const textPromise = (async () => {
@@ -328,6 +392,12 @@ function buildCompletionResult(response) {
         toResponse,
     };
 }
+/**
+ * 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 async function objectGeneration(config, input) {
     const body = buildStatelessGenerationBody(input, {
         type: "object",
@@ -342,10 +412,16 @@ export async function objectGeneration(config, input) {
     });
     return buildObjectResult(response);
 }
+/**
+ * Parses partial and final JSON from independent text-stream branches.
+ */
 function buildObjectResult(response) {
     const { finalStream, outputStream, requestId, toResponse } = buildStatelessGenerationStreams(response, "object");
     let accumulatedText = "";
     const partialObjectStream = outputStream.pipeThrough(new TransformStream({
+        /**
+         * Accumulates generated text and emits each available partial JSON value.
+         */
         async transform(chunk, controller) {
             accumulatedText += chunk;
             const { value } = await parsePartialJson(accumulatedText);
@@ -353,6 +429,9 @@ function buildObjectResult(response) {
                 controller.enqueue(value);
             }
         },
+        /**
+         * Rejects malformed final JSON when the text stream ends.
+         */
         flush() {
             try {
                 JSON.parse(accumulatedText);
@@ -392,6 +471,9 @@ function buildObjectResult(response) {
         toResponse,
     };
 }
+/**
+ * Splits decoded text into final, public, and response-relay branches.
+ */
 function buildStatelessGenerationStreams(response, resourceName) {
     const requestId = response.headers.get("x-request-id") ?? undefined;
     const location = response.headers.get("location");
@@ -408,6 +490,7 @@ function buildStatelessGenerationStreams(response, resourceName) {
         finalStream,
         outputStream,
         requestId,
+        /** Claims the response relay once. */
         toResponse: () => {
             if (responseBodyClaimed) {
                 const message = `The ${resourceName} response body has already been claimed.`;

package/dist/http.d.ts

@@ -4,20 +4,46 @@ import type { HttpConfig, RequestOptions } from "./types.ts";
  * Performs a request and returns the parsed JSON body for success (status
  * 2xx). API errors preserve the tolerant wire envelope; malformed responses
  * become `invalid_response`.
+ * @param config - Authentication, base URL, and transport configuration.
+ * @param path - Endpoint path relative to the base URL.
+ * @param options - Configuration for this operation.
+ * @param schema - Schema used to validate the value.
  */
 export declare function requestJson<T>(config: HttpConfig, path: string, options?: RequestOptions, schema?: {
+    /**
+     * Validates the decoded response value.
+     * @param value - Value to inspect.
+     */
     parse(value: unknown): T;
 }): Promise<T>;
 /**
  * Performs a request and returns the raw `Response` for streaming paths.
  * Non-2xx bodies are decoded before a caller can observe a streaming body.
+ * @param config - Authentication, base URL, and transport configuration.
+ * @param path - Endpoint path relative to the base URL.
+ * @param options - Configuration for this operation.
  */
 export declare function requestStream(config: HttpConfig, path: string, options?: RequestOptions): Promise<Response>;
+/**
+ * Checks whether the signal aborted or the cause names an AbortError.
+ * @param cause - Original failure to retain.
+ * @param signal - Signal that cancels the operation.
+ * @returns Whether the request signal or cause indicates cancellation.
+ */
 export declare function isRequestAborted(cause: unknown, signal?: AbortSignal): boolean;
+/**
+ * Wraps an abort cause as a request_aborted SDK error.
+ * @param cause - Original failure to retain.
+ * @returns A request_aborted error retaining the cause.
+ */
 export declare function requestAbortedError(cause: unknown): BlazingAgentsError;
 /**
  * Decodes a response body with the tolerant consumer schema. Unknown future
  * codes and fields remain valid; malformed responses never infer a domain
  * code from HTTP status.
+ * @param bodyText - Response body as text.
+ * @param status - HTTP response status.
+ * @param headers - Response headers to preserve or inspect.
+ * @returns The server error, or invalid_response when the envelope is malformed.
  */
 export declare function parseErrorEnvelope(bodyText: string, status: number, headers?: Headers): BlazingAgentsError;