@promptbook/javascript 0.110.0-1 → 0.110.0-11

package/esm/typings/src/llm-providers/openai/OpenAiAgentKitExecutionTools.d.ts

@@ -0,0 +1,150 @@
+import { Agent as AgentFromKit } from '@openai/agents';
+import OpenAI from 'openai';
+import { TODO_any } from '../../_packages/types.index';
+import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
+import type { ChatPromptResult } from '../../execution/PromptResult';
+import type { ModelRequirements } from '../../types/ModelRequirements';
+import type { Prompt } from '../../types/Prompt';
+import type { string_markdown, string_markdown_text, string_title } from '../../types/typeAliases';
+import type { OpenAiAgentKitExecutionToolsOptions } from './OpenAiAgentKitExecutionToolsOptions';
+import { OpenAiVectorStoreHandler } from './OpenAiVectorStoreHandler';
+/**
+ * Represents the AgentKit output configuration used to match OpenAI `response_format` expectations.
+ *
+ * @private utility of Open AI
+ */
+export type AgentOutputType = 'text' | JsonSchemaDefinition;
+type JsonSchemaDefinitionEntry = {
+    type?: string;
+    description?: string;
+    properties?: Record<string, JsonSchemaDefinitionEntry>;
+    required?: Array<string>;
+    items?: JsonSchemaDefinitionEntry;
+    [key: string]: TODO_any;
+};
+type JsonSchemaDefinition = {
+    type: 'json_schema';
+    name: string;
+    strict: boolean;
+    schema: {
+        type: 'object';
+        properties: Record<string, JsonSchemaDefinitionEntry>;
+        required: Array<string>;
+        additionalProperties: boolean;
+        description?: string;
+    };
+};
+type OpenAiChatResponseFormat = OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming['response_format'];
+/**
+ * Maps OpenAI `response_format` payloads to AgentKit output types so the runner can forward
+ * structured-output preferences to OpenAI while still reusing the same AgentKit agent instance.
+ *
+ * @param responseFormat - The OpenAI `response_format` payload from the user request.
+ * @returns An Agent output type compatible with the requested schema or `undefined` when no impact is required.
+ * @private utility of Open AI
+ */
+export declare function mapResponseFormatToAgentOutputType(responseFormat?: OpenAiChatResponseFormat): AgentOutputType | undefined;
+/**
+ * Alias for OpenAI AgentKit agent to avoid naming confusion with Promptbook agents.
+ */
+type OpenAiAgentKitAgent = AgentFromKit;
+/**
+ * Prepared AgentKit agent details.
+ */
+type OpenAiAgentKitPreparedAgent = {
+    readonly agent: OpenAiAgentKitAgent;
+    readonly vectorStoreId?: string;
+};
+/**
+ * Execution tools for OpenAI AgentKit (Agents SDK).
+ *
+ * @public exported from `@promptbook/openai`
+ */
+export declare class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandler implements LlmExecutionTools {
+    private preparedAgentKitAgent;
+    private readonly agentKitModelName;
+    /**
+     * Creates OpenAI AgentKit execution tools.
+     */
+    constructor(options: OpenAiAgentKitExecutionToolsOptions);
+    get title(): string_title & string_markdown_text;
+    get description(): string_markdown;
+    /**
+     * Calls OpenAI AgentKit with a chat prompt (non-streaming).
+     */
+    callChatModel(prompt: Prompt): Promise<ChatPromptResult>;
+    /**
+     * Calls OpenAI AgentKit with a chat prompt (streaming).
+     */
+    callChatModelStream(prompt: Prompt, onProgress: (chunk: ChatPromptResult) => void): Promise<ChatPromptResult>;
+    /**
+     * Returns a prepared AgentKit agent when the server wants to manage caching externally.
+     */
+    getPreparedAgentKitAgent(): OpenAiAgentKitPreparedAgent | null;
+    /**
+     * Stores a prepared AgentKit agent for later reuse by external cache managers.
+     */
+    setPreparedAgentKitAgent(preparedAgent: OpenAiAgentKitPreparedAgent): void;
+    /**
+     * Creates a new tools instance bound to a prepared AgentKit agent.
+     */
+    getPreparedAgentTools(preparedAgent: OpenAiAgentKitPreparedAgent): OpenAiAgentKitExecutionTools;
+    /**
+     * Prepares an AgentKit agent with optional knowledge sources and tool definitions.
+     */
+    prepareAgentKitAgent(options: {
+        readonly name: string_title;
+        readonly instructions: string_markdown;
+        readonly knowledgeSources?: ReadonlyArray<string>;
+        readonly tools?: ModelRequirements['tools'];
+        readonly vectorStoreId?: string;
+        readonly storeAsPrepared?: boolean;
+    }): Promise<OpenAiAgentKitPreparedAgent>;
+    /**
+     * Ensures the AgentKit SDK is wired to the OpenAI client and API key.
+     */
+    private ensureAgentKitDefaults;
+    /**
+     * Builds the tool list for AgentKit, including hosted file search when applicable.
+     */
+    private buildAgentKitTools;
+    /**
+     * Resolves the configured script tools for tool execution.
+     */
+    private resolveScriptTools;
+    /**
+     * Runs a prepared AgentKit agent and streams results back to the caller.
+     */
+    callChatModelStreamWithPreparedAgent(options: {
+        readonly openAiAgentKitAgent: OpenAiAgentKitAgent;
+        readonly prompt: Prompt;
+        readonly rawPromptContent?: string;
+        readonly onProgress: (chunk: ChatPromptResult) => void;
+        readonly responseFormatOutputType?: AgentOutputType;
+    }): Promise<ChatPromptResult>;
+    /**
+     * Builds AgentKit input items from the prompt and optional thread.
+     */
+    private buildAgentKitInputItems;
+    /**
+     * Builds the user message content for AgentKit runs, including file inputs when provided.
+     */
+    private buildAgentKitUserContent;
+    /**
+     * Normalizes AgentKit tool outputs into a string for Promptbook tool call results.
+     */
+    private formatAgentKitToolOutput;
+    /**
+     * Returns AgentKit-specific options.
+     */
+    private get agentKitOptions();
+    /**
+     * Discriminant for type guards.
+     */
+    protected get discriminant(): string;
+    /**
+     * Type guard to check if given `LlmExecutionTools` are instanceof `OpenAiAgentKitExecutionTools`.
+     */
+    static isOpenAiAgentKitExecutionTools(llmExecutionTools: LlmExecutionTools): llmExecutionTools is OpenAiAgentKitExecutionTools;
+}
+export {};

package/esm/typings/src/llm-providers/openai/OpenAiAgentKitExecutionToolsOptions.d.ts

@@ -0,0 +1,15 @@
+import type { string_model_name } from '../../types/typeAliases';
+import type { OpenAiVectorStoreHandlerOptions } from './OpenAiVectorStoreHandler';
+/**
+ * Options for `OpenAiAgentKitExecutionTools`.
+ *
+ * @public exported from `@promptbook/openai`
+ */
+export type OpenAiAgentKitExecutionToolsOptions = OpenAiVectorStoreHandlerOptions & {
+    /**
+     * Base model name used for AgentKit agents.
+     *
+     * @default gpt-5.2
+     */
+    readonly agentKitModelName?: string_model_name;
+};

package/esm/typings/src/llm-providers/openai/OpenAiAssistantExecutionTools.d.ts

@@ -4,7 +4,7 @@ import type { ModelRequirements } from '../../types/ModelRequirements';
 import type { Prompt } from '../../types/Prompt';
 import type { string_markdown, string_markdown_text, string_title, string_token } from '../../types/typeAliases';
 import type { OpenAiAssistantExecutionToolsOptions } from './OpenAiAssistantExecutionToolsOptions';
-import { OpenAiExecutionTools } from './OpenAiExecutionTools';
+import { OpenAiVectorStoreHandler } from './OpenAiVectorStoreHandler';
 /**
  * Execution Tools for calling OpenAI API Assistants
  *
@@ -17,10 +17,10 @@ import { OpenAiExecutionTools } from './OpenAiExecutionTools';
  * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
+ * @deprecated Use `OpenAiAgentKitExecutionTools` instead.
  * @public exported from `@promptbook/openai`
- * @deprecated Use `OpenAiAgentExecutionTools` instead which uses the new OpenAI Responses API
  */
-export declare class OpenAiAssistantExecutionTools extends OpenAiExecutionTools implements LlmExecutionTools {
+export declare class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler implements LlmExecutionTools {
     readonly assistantId: string_token;
     private readonly isCreatingNewAssistantsAllowed;
     /**

package/esm/typings/src/llm-providers/openai/OpenAiAssistantExecutionToolsOptions.d.ts

@@ -1,18 +1,17 @@
-import type { ClientOptions } from 'openai';
 import type { string_token } from '../../types/typeAliases';
-import type { OpenAiCompatibleExecutionToolsOptions } from './OpenAiCompatibleExecutionToolsOptions';
+import type { OpenAiVectorStoreHandlerOptions } from './OpenAiVectorStoreHandler';
 /**
  * Options for `createOpenAiAssistantExecutionTools` and `OpenAiAssistantExecutionTools`
  *
  * @public exported from `@promptbook/openai`
  */
-export type OpenAiAssistantExecutionToolsOptions = OpenAiCompatibleExecutionToolsOptions & ClientOptions & {
+export type OpenAiAssistantExecutionToolsOptions = OpenAiVectorStoreHandlerOptions & {
     /**
      * Whether creating new assistants is allowed
      *
      * @default false
      */
-    readonly isCreatingNewAssistantsAllowed?: boolean;
+    readonly isCreatingNewAssistantsAllowed: boolean;
     /**
      * Which assistant to use
      */

package/esm/typings/src/llm-providers/openai/OpenAiVectorStoreHandler.d.ts

@@ -0,0 +1,135 @@
+import type { ClientOptions } from 'openai';
+import OpenAI from 'openai';
+import { TODO_any } from '../../_packages/types.index';
+import type { string_title } from '../../types/typeAliases';
+import type { OpenAiCompatibleExecutionToolsOptions } from './OpenAiCompatibleExecutionToolsOptions';
+import { OpenAiExecutionTools } from './OpenAiExecutionTools';
+/**
+ * Metadata for uploaded knowledge source files used for vector store diagnostics.
+ */
+type KnowledgeSourceUploadMetadata = {
+    readonly fileId: string;
+    readonly filename: string;
+    readonly sizeBytes?: number;
+};
+/**
+ * Shared options for OpenAI vector store handling.
+ *
+ * @public exported from `@promptbook/openai`
+ */
+export type OpenAiVectorStoreHandlerOptions = OpenAiCompatibleExecutionToolsOptions & ClientOptions & {
+    /**
+     * Per-knowledge-source download timeout in milliseconds when preparing vector stores.
+     *
+     * @default 30000
+     */
+    readonly knowledgeSourceDownloadTimeoutMs?: number;
+    /**
+     * Max concurrency for uploading knowledge source files to the vector store.
+     *
+     * @default 5
+     */
+    readonly knowledgeSourceUploadMaxConcurrency?: number;
+    /**
+     * Poll interval in milliseconds when waiting for vector store file batch processing.
+     *
+     * @default 5000
+     */
+    readonly knowledgeSourceUploadPollIntervalMs?: number;
+    /**
+     * Overall timeout in milliseconds for vector store file batch processing.
+     *
+     * @default 900000
+     */
+    readonly knowledgeSourceUploadTimeoutMs?: number;
+    /**
+     * Whether we should continue even if vector store ingestion stalls.
+     *
+     * @default true
+     */
+    readonly shouldContinueOnVectorStoreStall?: boolean;
+};
+/**
+ * Base class for OpenAI execution tools that need hosted vector stores.
+ *
+ * @public exported from `@promptbook/openai`
+ */
+export declare abstract class OpenAiVectorStoreHandler extends OpenAiExecutionTools {
+    /**
+     * Returns the per-knowledge-source download timeout in milliseconds.
+     */
+    protected getKnowledgeSourceDownloadTimeoutMs(): number;
+    /**
+     * Returns the max concurrency for knowledge source uploads.
+     */
+    protected getKnowledgeSourceUploadMaxConcurrency(): number;
+    /**
+     * Returns the polling interval in milliseconds for vector store uploads.
+     */
+    protected getKnowledgeSourceUploadPollIntervalMs(): number;
+    /**
+     * Returns the overall upload timeout in milliseconds for vector store uploads.
+     */
+    protected getKnowledgeSourceUploadTimeoutMs(): number;
+    /**
+     * Returns true if we should continue even if vector store ingestion stalls.
+     */
+    protected shouldContinueOnVectorStoreStall(): boolean;
+    /**
+     * Returns vector-store-specific options with extended settings.
+     */
+    protected get vectorStoreOptions(): OpenAiVectorStoreHandlerOptions;
+    /**
+     * Returns the OpenAI vector stores API surface, supporting stable and beta SDKs.
+     */
+    protected getVectorStoresApi(client: OpenAI): TODO_any;
+    /**
+     * Downloads a knowledge source URL into a File for vector store upload.
+     */
+    protected downloadKnowledgeSourceFile(options: {
+        readonly source: string;
+        readonly timeoutMs: number;
+        readonly logLabel: string;
+    }): Promise<{
+        readonly file: File;
+        readonly sizeBytes: number;
+        readonly filename: string;
+        readonly elapsedMs: number;
+    } | null>;
+    /**
+     * Logs vector store file batch diagnostics to help trace ingestion stalls or failures.
+     */
+    protected logVectorStoreFileBatchDiagnostics(options: {
+        readonly client: OpenAI;
+        readonly vectorStoreId: string;
+        readonly batchId: string;
+        readonly uploadedFiles: ReadonlyArray<KnowledgeSourceUploadMetadata>;
+        readonly logLabel: string;
+        readonly reason: 'stalled' | 'timeout' | 'failed';
+    }): Promise<void>;
+    /**
+     * Uploads knowledge source files to the vector store and polls until processing completes.
+     */
+    protected uploadKnowledgeSourceFilesToVectorStore(options: {
+        readonly client: OpenAI;
+        readonly vectorStoreId: string;
+        readonly files: ReadonlyArray<File>;
+        readonly totalBytes: number;
+        readonly logLabel: string;
+    }): Promise<TODO_any | null>;
+    /**
+     * Creates a vector store and uploads knowledge sources, returning its ID.
+     */
+    protected createVectorStoreWithKnowledgeSources(options: {
+        readonly client: OpenAI;
+        readonly name: string_title;
+        readonly knowledgeSources: ReadonlyArray<string>;
+        readonly logLabel: string;
+    }): Promise<{
+        readonly vectorStoreId: string;
+        readonly uploadedFileCount: number;
+        readonly skippedCount: number;
+        readonly totalBytes: number;
+    }>;
+}
+export {};

package/esm/typings/src/llm-providers/openai/utils/mapToolsToOpenAi.d.ts

@@ -5,4 +5,4 @@ import type { LlmToolDefinition } from '../../../types/LlmToolDefinition';
  *
  * @private
  */
-export declare function mapToolsToOpenAi(tools: ReadonlyArray<LlmToolDefinition>): Array<OpenAI.Chat.Completions.ChatCompletionTool>;
+export declare function mapToolsToOpenAi(tools: ReadonlyArray<LlmToolDefinition>): Array<OpenAI.Chat.Completions.ChatCompletionTool & OpenAI.Beta.AssistantTool>;

package/esm/typings/src/types/LlmToolDefinition.d.ts

@@ -23,5 +23,6 @@ export type LlmToolDefinition = {
             description?: string;
         }>;
         readonly required?: string[];
+        readonly additionalProperties?: boolean;
     };
 };

package/esm/typings/src/types/ModelRequirements.d.ts

@@ -1,6 +1,7 @@
 import type { LlmToolDefinition } from './LlmToolDefinition';
 import type { ModelVariant } from './ModelVariant';
 import type { number_model_temperature, number_seed, string_model_name, string_system_message } from './typeAliases';
+import type OpenAI from 'openai';
 /**
  * Abstract way to specify the LLM.
  * It does not specify the LLM with concrete version itself, only the requirements for the LLM.
@@ -54,6 +55,14 @@ export type ChatModelRequirements = CommonModelRequirements & {
      * Maximum number of tokens that can be generated by the model
      */
     readonly maxTokens?: number;
+    /**
+     * Optional OpenAI `response_format` override that should be forwarded to compatible APIs.
+     */
+    readonly responseFormat?: OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming['response_format'];
+    /**
+     * Optional OpenAI `tool_choice` override that should be forwarded to compatible APIs.
+     */
+    readonly toolChoice?: OpenAI.Chat.Completions.ChatCompletionToolChoiceOption;
 };
 /**
  * Model requirements for the image generation variant

package/esm/typings/src/utils/DEFAULT_THINKING_MESSAGES.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Default placeholder variants shown when an agent is still composing a response.
+ *
+ * @private BUT maybe export via some package
+ */
+export declare const DEFAULT_THINKING_MESSAGES: readonly ["Thinking...", "Searching for information...", "Sorting information..."];
+/** @internal */
+export type ThinkingMessageVariant = (typeof DEFAULT_THINKING_MESSAGES)[number];

package/esm/typings/src/utils/agents/resolveAgentAvatarImageUrl.d.ts

@@ -0,0 +1,29 @@
+import type { AgentBasicInformation } from '../../book-2.0/agent-source/AgentBasicInformation';
+import type { string_url, string_url_image } from '../../types/typeAliases';
+/**
+ * Options for resolving agent avatar URLs.
+ *
+ * @private utility of `<Chat/>`
+ */
+export type ResolveAgentAvatarImageUrlOptions = {
+    /**
+     * Agent metadata used for avatar resolution.
+     */
+    readonly agent: Pick<AgentBasicInformation, 'agentName' | 'permanentId' | 'meta'>;
+    /**
+     * Optional base URL used to resolve relative meta images and placeholders.
+     */
+    readonly baseUrl?: string_url;
+};
+/**
+ * Resolve the fallback avatar URL for an agent.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function resolveAgentAvatarFallbackUrl(options: ResolveAgentAvatarImageUrlOptions): string_url_image | null;
+/**
+ * Resolve the best avatar URL for an agent, preferring META IMAGE and falling back to placeholders.
+ *
+ * @private utility of `<Chat/>`
+ */
+export declare function resolveAgentAvatarImageUrl(options: ResolveAgentAvatarImageUrlOptions): string_url_image | null;

package/esm/typings/src/utils/knowledge/inlineKnowledgeSource.d.ts

@@ -0,0 +1,38 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { string_data_url, string_filename } from '../../types/typeAliases';
+/**
+ * @@@
+ *
+ * @private thing of inline knowledge
+ */
+export type InlineKnowledgeSourceFile = {
+    readonly filename: string_filename;
+    readonly mimeType: string;
+    readonly url: string_data_url;
+};
+/**
+ * Creates a data URL that represents the inline knowledge content as a text file.
+ *
+ * @private thing of inline knowledge
+ */
+export declare function createInlineKnowledgeSourceFile(content: string): InlineKnowledgeSourceFile;
+/**
+ * Checks whether the provided source string is a data URL that can be decoded.
+ *
+ * @private thing of inline knowledge
+ */
+export declare function isDataUrlKnowledgeSource(source: string): source is string_data_url;
+/**
+ * Parses a data URL-based knowledge source into its raw buffer, filename, and MIME type.
+ *
+ * @private thing of inline knowledge
+ */
+export declare function parseDataUrlKnowledgeSource(source: string): {
+    readonly buffer: Buffer;
+    readonly filename: string_filename;
+    readonly mimeType: string;
+} | null;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/utils/knowledge/inlineKnowledgeSource.test.d.ts

@@ -0,0 +1 @@
+export {};

package/esm/typings/src/utils/language/getBrowserPreferredSpeechRecognitionLanguage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @@@
+ *
+ * @private function of Agents Server speech recognition language resolution, not a general-purpose utility
+ */
+type ResolveSpeechRecognitionLanguageOptions = {
+    /**
+     * Overrides the default language resolution when provided.
+     */
+    readonly overrideLanguage?: string | null;
+    /**
+     * Optional Accept-Language header string to derive the speaker language from server-side requests.
+     */
+    readonly acceptLanguageHeader?: string | null;
+};
+/**
+ * Parses the primary language out of an Accept-Language header value.
+ *
+ * @private function of Agents Server speech recognition language resolution, not a general-purpose utility
+ */
+export declare function parseSpeechRecognitionLanguageFromAcceptLanguageHeader(header?: string | null): string | undefined;
+/**
+ * Reads the browser-reported preferred language list and returns the first valid tag.
+ *
+ * @private function of Agents Server speech recognition language resolution, not a general-purpose utility
+ */
+export declare function getBrowserPreferredSpeechRecognitionLanguage(): string | undefined;
+/**
+ * Resolves a speech recognition language tag by checking an optional override, then the Accept-Language header,
+ * then the browser preferences, and finally falling back to a default of `en-US`.
+ *
+ * @private function of Agents Server speech recognition language resolution, not a general-purpose utility
+ */
+export declare function resolveSpeechRecognitionLanguage(options?: ResolveSpeechRecognitionLanguageOptions): string;
+export {};

package/esm/typings/src/utils/toolCalls/getToolCallIdentity.d.ts

@@ -0,0 +1,10 @@
+import type { ToolCall } from '../../types/ToolCall';
+/**
+ * Builds a stable identity string for tool calls across partial updates.
+ *
+ * @param toolCall - Tool call entry to identify.
+ * @returns Stable identity string for deduplication.
+ *
+ * @private function of <Chat/>
+ */
+export declare function getToolCallIdentity(toolCall: ToolCall): string;

package/esm/typings/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.110.0-0`).
+ * It follows semantic versioning (e.g., `0.110.0-10`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/javascript",
-    "version": "0.110.0-1",
+    "version": "0.110.0-11",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,
@@ -90,11 +90,14 @@
         "node": ">=18.18.0",
         "npm": ">=8.0.0"
     },
+    "overrides": {
+        "zod": "$zod"
+    },
     "main": "./umd/index.umd.js",
     "module": "./esm/index.es.js",
     "typings": "./esm/typings/src/_packages/javascript.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.110.0-1"
+        "@promptbook/core": "0.110.0-11"
     },
     "dependencies": {
         "crypto": "1.0.1",

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.110.0-1';
+    const PROMPTBOOK_ENGINE_VERSION = '0.110.0-11';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name