@promptbook/javascript 0.110.0-5 → 0.110.0-8

package/esm/index.es.js

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

package/esm/typings/src/_packages/openai.index.d.ts

@@ -3,6 +3,8 @@ import { createOpenAiAssistantExecutionTools } from '../llm-providers/openai/cre
 import { createOpenAiCompatibleExecutionTools } from '../llm-providers/openai/createOpenAiCompatibleExecutionTools';
 import { createOpenAiExecutionTools } from '../llm-providers/openai/createOpenAiExecutionTools';
 import { OPENAI_MODELS } from '../llm-providers/openai/openai-models';
+import { OpenAiAgentKitExecutionTools } from '../llm-providers/openai/OpenAiAgentKitExecutionTools';
+import type { OpenAiAgentKitExecutionToolsOptions } from '../llm-providers/openai/OpenAiAgentKitExecutionToolsOptions';
 import { OpenAiAssistantExecutionTools } from '../llm-providers/openai/OpenAiAssistantExecutionTools';
 import type { OpenAiAssistantExecutionToolsOptions } from '../llm-providers/openai/OpenAiAssistantExecutionToolsOptions';
 import { OpenAiCompatibleExecutionTools } from '../llm-providers/openai/OpenAiCompatibleExecutionTools';
@@ -11,6 +13,8 @@ import type { OpenAiCompatibleExecutionToolsNonProxiedOptions } from '../llm-pro
 import type { OpenAiCompatibleExecutionToolsProxiedOptions } from '../llm-providers/openai/OpenAiCompatibleExecutionToolsOptions';
 import { OpenAiExecutionTools } from '../llm-providers/openai/OpenAiExecutionTools';
 import type { OpenAiExecutionToolsOptions } from '../llm-providers/openai/OpenAiExecutionToolsOptions';
+import type { OpenAiVectorStoreHandlerOptions } from '../llm-providers/openai/OpenAiVectorStoreHandler';
+import { OpenAiVectorStoreHandler } from '../llm-providers/openai/OpenAiVectorStoreHandler';
 import { _OpenAiRegistration } from '../llm-providers/openai/register-constructor';
 import { _OpenAiAssistantRegistration } from '../llm-providers/openai/register-constructor';
 import { _OpenAiCompatibleRegistration } from '../llm-providers/openai/register-constructor';
@@ -19,6 +23,8 @@ export { createOpenAiAssistantExecutionTools };
 export { createOpenAiCompatibleExecutionTools };
 export { createOpenAiExecutionTools };
 export { OPENAI_MODELS };
+export { OpenAiAgentKitExecutionTools };
+export type { OpenAiAgentKitExecutionToolsOptions };
 export { OpenAiAssistantExecutionTools };
 export type { OpenAiAssistantExecutionToolsOptions };
 export { OpenAiCompatibleExecutionTools };
@@ -27,6 +33,8 @@ export type { OpenAiCompatibleExecutionToolsNonProxiedOptions };
 export type { OpenAiCompatibleExecutionToolsProxiedOptions };
 export { OpenAiExecutionTools };
 export type { OpenAiExecutionToolsOptions };
+export type { OpenAiVectorStoreHandlerOptions };
+export { OpenAiVectorStoreHandler };
 export { _OpenAiRegistration };
 export { _OpenAiAssistantRegistration };
 export { _OpenAiCompatibleRegistration };

package/esm/typings/src/_packages/types.index.d.ts

@@ -138,11 +138,13 @@ import type { AzureOpenAiExecutionToolsOptions } from '../llm-providers/azure-op
 import type { DeepseekExecutionToolsOptions } from '../llm-providers/deepseek/DeepseekExecutionToolsOptions';
 import type { GoogleExecutionToolsOptions } from '../llm-providers/google/GoogleExecutionToolsOptions';
 import type { OllamaExecutionToolsOptions } from '../llm-providers/ollama/OllamaExecutionToolsOptions';
+import type { OpenAiAgentKitExecutionToolsOptions } from '../llm-providers/openai/OpenAiAgentKitExecutionToolsOptions';
 import type { OpenAiAssistantExecutionToolsOptions } from '../llm-providers/openai/OpenAiAssistantExecutionToolsOptions';
 import type { OpenAiCompatibleExecutionToolsOptions } from '../llm-providers/openai/OpenAiCompatibleExecutionToolsOptions';
 import type { OpenAiCompatibleExecutionToolsNonProxiedOptions } from '../llm-providers/openai/OpenAiCompatibleExecutionToolsOptions';
 import type { OpenAiCompatibleExecutionToolsProxiedOptions } from '../llm-providers/openai/OpenAiCompatibleExecutionToolsOptions';
 import type { OpenAiExecutionToolsOptions } from '../llm-providers/openai/OpenAiExecutionToolsOptions';
+import type { OpenAiVectorStoreHandlerOptions } from '../llm-providers/openai/OpenAiVectorStoreHandler';
 import type { VercelExecutionToolsOptions } from '../llm-providers/vercel/VercelExecutionToolsOptions';
 import type { VercelProvider } from '../llm-providers/vercel/VercelProvider';
 import type { IsPipelineImplementingInterfaceOptions } from '../pipeline/PipelineInterface/isPipelineImplementingInterface';
@@ -539,11 +541,13 @@ export type { AzureOpenAiExecutionToolsOptions };
 export type { DeepseekExecutionToolsOptions };
 export type { GoogleExecutionToolsOptions };
 export type { OllamaExecutionToolsOptions };
+export type { OpenAiAgentKitExecutionToolsOptions };
 export type { OpenAiAssistantExecutionToolsOptions };
 export type { OpenAiCompatibleExecutionToolsOptions };
 export type { OpenAiCompatibleExecutionToolsNonProxiedOptions };
 export type { OpenAiCompatibleExecutionToolsProxiedOptions };
 export type { OpenAiExecutionToolsOptions };
+export type { OpenAiVectorStoreHandlerOptions };
 export type { VercelExecutionToolsOptions };
 export type { VercelProvider };
 export type { IsPipelineImplementingInterfaceOptions };

package/esm/typings/src/book-components/Chat/AgentChip/AgentChip.d.ts

@@ -45,6 +45,10 @@ export type AgentChipProps = {
      * Additional CSS class name
      */
     className?: string;
+    /**
+     * Optional suffix appended to the agent label (e.g., " (2x)").
+     */
+    labelSuffix?: string;
 };
 /**
  * AgentChip component - displays a chip with agent avatar and name
@@ -64,4 +68,4 @@ export type AgentChipProps = {
  *
  * @private utility of `ChatMessageItem` component
  */
-export declare function AgentChip({ agent, isOngoing, isClickable, onClick, className }: AgentChipProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentChip({ agent, isOngoing, isClickable, onClick, className, labelSuffix, }: AgentChipProps): import("react/jsx-runtime").JSX.Element;

package/esm/typings/src/book-components/Chat/LlmChat/LlmChatProps.d.ts

@@ -69,5 +69,8 @@ export type LlmChatProps = Omit<ChatProps, 'messages' | 'onMessage' | 'onChange'
      * @param error - The error that occurred
      * @param retry - Function to retry the last failed message
      */
-    onError?(error: unknown, retry: () => void): void;
+    onError?(error: unknown, retry: () => void, failedMessage: {
+        content: string;
+        attachments: ChatMessage['attachments'];
+    }): void;
 };

package/esm/typings/src/collection/agent-collection/constructors/agent-collection-in-supabase/AgentsDatabaseSchema.d.ts

@@ -36,7 +36,6 @@ export type AgentsDatabaseSchema = {
                     promptbookEngineVersion: string;
                     usage: Json | null;
                     preparedModelRequirements: Json | null;
-                    preparedExternals: Json | null;
                     folderId: number | null;
                     sortOrder: number;
                     deletedAt: string | null;
@@ -54,7 +53,6 @@ export type AgentsDatabaseSchema = {
                     promptbookEngineVersion: string;
                     usage?: Json | null;
                     preparedModelRequirements?: Json | null;
-                    preparedExternals?: Json | null;
                     folderId?: number | null;
                     sortOrder?: number;
                     deletedAt?: string | null;
@@ -72,7 +70,6 @@ export type AgentsDatabaseSchema = {
                     promptbookEngineVersion?: string;
                     usage?: Json | null;
                     preparedModelRequirements?: Json | null;
-                    preparedExternals?: Json | null;
                     folderId?: number | null;
                     sortOrder?: number;
                     deletedAt?: string | null;

package/esm/typings/src/execution/LlmExecutionTools.d.ts

@@ -13,7 +13,8 @@ import type { ChatPromptResult, CompletionPromptResult, EmbeddingPromptResult, I
  * - `Agent` - which represents an AI Agent with its source, memories, actions, etc. Agent is a higher-level abstraction which is internally using:
  * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
  * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
- * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
+ * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
+ * - `OpenAiAgentKitExecutionTools` - which is a specific implementation of `LlmExecutionTools` backed by OpenAI AgentKit
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
  * @see https://github.com/webgptorg/promptbook#llm-execution-tools

package/esm/typings/src/llm-providers/agent/Agent.d.ts

@@ -15,6 +15,7 @@ import type { AgentOptions } from './AgentOptions';
  * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
  * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
  * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
+ * - `OpenAiAgentKitExecutionTools` - which is a specific implementation of `LlmExecutionTools` backed by OpenAI AgentKit
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
  * @public exported from `@promptbook/core`

package/esm/typings/src/llm-providers/agent/AgentLlmExecutionTools.d.ts

@@ -17,12 +17,17 @@ import type { CreateAgentLlmExecutionToolsOptions } from './CreateAgentLlmExecut
  * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
  * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
  * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
+ * - `OpenAiAgentKitExecutionTools` - which is a specific implementation of `LlmExecutionTools` backed by OpenAI AgentKit
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
  * @public exported from `@promptbook/core`
  */
 export declare class AgentLlmExecutionTools implements LlmExecutionTools {
     protected readonly options: CreateAgentLlmExecutionToolsOptions;
+    /**
+     * Cached AgentKit agents to avoid rebuilding identical instances.
+     */
+    private static agentKitAgentCache;
     /**
      * Cache of OpenAI assistants to avoid creating duplicates
      */

package/esm/typings/src/llm-providers/agent/AgentOptions.d.ts

@@ -14,10 +14,11 @@ export type AgentOptions = CommonToolsOptions & {
      */
     executionTools: ExecutionTools;
     /**
-     * How to manage OpenAI assistant preparation when using OpenAiAssistantExecutionTools.
+     * How to manage OpenAI assistant/AgentKit preparation when using OpenAiAssistantExecutionTools
+     * or OpenAiAgentKitExecutionTools.
      *
-     * Use `external` when an external cache manager already created the assistant and
-     * the agent should use it as-is.
+     * Use `external` when an external cache manager already created the assistant/AgentKit agent
+     * and the agent should use it as-is.
      *
      * @default internal
      */

package/esm/typings/src/llm-providers/agent/CreateAgentLlmExecutionToolsOptions.d.ts

@@ -1,7 +1,8 @@
 import type { string_book } from '../../book-2.0/agent-source/string_book';
 import type { CommonToolsOptions } from '../../execution/CommonToolsOptions';
 import type { LlmExecutionTools } from '../../execution/LlmExecutionTools';
-import { OpenAiAssistantExecutionTools } from '../openai/OpenAiAssistantExecutionTools';
+import type { OpenAiAgentKitExecutionTools } from '../openai/OpenAiAgentKitExecutionTools';
+import type { OpenAiAssistantExecutionTools } from '../openai/OpenAiAssistantExecutionTools';
 /**
  * Options for creating AgentLlmExecutionTools
  */
@@ -9,12 +10,13 @@ export type CreateAgentLlmExecutionToolsOptions = CommonToolsOptions & {
     /**
      * The underlying LLM execution tools to wrap
      */
-    llmTools: LlmExecutionTools | OpenAiAssistantExecutionTools;
+    llmTools: LlmExecutionTools | OpenAiAssistantExecutionTools | OpenAiAgentKitExecutionTools;
     /**
-     * How to manage OpenAI assistant preparation when using OpenAiAssistantExecutionTools.
+     * How to manage OpenAI assistant/AgentKit preparation when using OpenAiAssistantExecutionTools
+     * or OpenAiAgentKitExecutionTools.
      *
-     * Use `external` when an external cache manager already created the assistant and
-     * the agent should use it as-is.
+     * Use `external` when an external cache manager already created the assistant/AgentKit agent
+     * and the agent should use it as-is.
      *
      * @default internal
      */

package/esm/typings/src/llm-providers/agent/RemoteAgent.d.ts

@@ -10,7 +10,8 @@ import type { RemoteAgentOptions } from './RemoteAgentOptions';
  * - `Agent` - which represents an AI Agent with its source, memories, actions, etc. Agent is a higher-level abstraction which is internally using:
  * - `LlmExecutionTools` - which wraps one or more LLM models and provides an interface to execute them
  * - `AgentLlmExecutionTools` - which is a specific implementation of `LlmExecutionTools` that wraps another LlmExecutionTools and applies agent-specific system prompts and requirements
- * - `OpenAiAssistantExecutionTools` - which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities, recommended for usage in `Agent` or `AgentLlmExecutionTools`
+ * - `OpenAiAssistantExecutionTools` - (Deprecated) which is a specific implementation of `LlmExecutionTools` for OpenAI models with assistant capabilities
+ * - `OpenAiAgentKitExecutionTools` - which is a specific implementation of `LlmExecutionTools` backed by OpenAI AgentKit
  * - `RemoteAgent` - which is an `Agent` that connects to a Promptbook Agents Server
  *
  * @public exported from `@promptbook/core`

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

@@ -0,0 +1,111 @@
+import { Agent as AgentFromKit } from '@openai/agents';
+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';
+/**
+ * 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;
+    }): 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,9 +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`
  */
-export declare class OpenAiAssistantExecutionTools extends OpenAiExecutionTools implements LlmExecutionTools {
+export declare class OpenAiAssistantExecutionTools extends OpenAiVectorStoreHandler implements LlmExecutionTools {
     readonly assistantId: string_token;
     private readonly isCreatingNewAssistantsAllowed;
     /**
@@ -42,46 +43,6 @@ export declare class OpenAiAssistantExecutionTools extends OpenAiExecutionTools
      * Get an existing assistant tool wrapper
      */
     getAssistant(assistantId: string_token): OpenAiAssistantExecutionTools;
-    /**
-     * Returns the per-knowledge-source download timeout in milliseconds.
-     */
-    private getKnowledgeSourceDownloadTimeoutMs;
-    /**
-     * Returns the max concurrency for knowledge source uploads.
-     */
-    private getKnowledgeSourceUploadMaxConcurrency;
-    /**
-     * Returns the polling interval in milliseconds for vector store uploads.
-     */
-    private getKnowledgeSourceUploadPollIntervalMs;
-    /**
-     * Returns the overall upload timeout in milliseconds for vector store uploads.
-     */
-    private getKnowledgeSourceUploadTimeoutMs;
-    /**
-     * Returns true if we should continue even if vector store ingestion stalls.
-     */
-    private shouldContinueOnVectorStoreStall;
-    /**
-     * Returns assistant-specific options with extended settings.
-     */
-    private get assistantOptions();
-    /**
-     * Downloads a knowledge source URL into a File for vector store upload.
-     */
-    private downloadKnowledgeSourceFile;
-    /**
-     * Logs vector store file batch diagnostics to help trace ingestion stalls or failures.
-     */
-    private logVectorStoreFileBatchDiagnostics;
-    /**
-     * Uploads knowledge source files to the vector store and polls until processing completes.
-     */
-    private uploadKnowledgeSourceFilesToVectorStore;
-    /**
-     * Creates a vector store and uploads knowledge sources, returning its ID.
-     */
-    private createVectorStoreWithKnowledgeSources;
     createNewAssistant(options: {
         /**
          * Name of the new assistant

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

@@ -1,12 +1,11 @@
-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
      *
@@ -17,34 +16,4 @@ export type OpenAiAssistantExecutionToolsOptions = OpenAiCompatibleExecutionTool
      * Which assistant to use
      */
     readonly assistantId: string_token;
-    /**
-     * Per-knowledge-source download timeout in milliseconds when preparing assistants.
-     *
-     * @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;
 };

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/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-4`).
+ * It follows semantic versioning (e.g., `0.110.0-7`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/javascript",
-    "version": "0.110.0-5",
+    "version": "0.110.0-8",
     "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-5"
+        "@promptbook/core": "0.110.0-8"
     },
     "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-5';
+    const PROMPTBOOK_ENGINE_VERSION = '0.110.0-8';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name