@promptbook/utils 0.112.0-62 → 0.112.0-64

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.112.0-62';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-64';
 /**
  * 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/src/_packages/components.index.d.ts

@@ -34,6 +34,7 @@ import type { ChatEffect } from '../book-components/Chat/effects/types/ChatEffec
 import type { ChatEffectConfig } from '../book-components/Chat/effects/types/ChatEffectConfig';
 import type { ChatEffectsSystemProps } from '../book-components/Chat/effects/types/ChatEffectsSystemProps';
 import type { ChatEffectType } from '../book-components/Chat/effects/types/ChatEffectType';
+import type { ChatAutoScrollConfig } from '../book-components/Chat/hooks/useChatAutoScroll';
 import { useChatAutoScroll } from '../book-components/Chat/hooks/useChatAutoScroll';
 import type { SendMessageToLlmChatFunction } from '../book-components/Chat/hooks/useSendMessageToLlmChat';
 import { useSendMessageToLlmChat } from '../book-components/Chat/hooks/useSendMessageToLlmChat';
@@ -61,6 +62,7 @@ import { reactSaveFormatDefinition } from '../book-components/Chat/save/react/re
 import { txtSaveFormatDefinition } from '../book-components/Chat/save/text/txtSaveFormatDefinition';
 import type { ChatProgressItem } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressCard } from '../book-components/Chat/types/ChatMessage';
+import type { ChatMessageSource } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessageReplyingTo } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
@@ -116,6 +118,7 @@ export type { ChatEffect };
 export type { ChatEffectConfig };
 export type { ChatEffectsSystemProps };
 export type { ChatEffectType };
+export type { ChatAutoScrollConfig };
 export { useChatAutoScroll };
 export type { SendMessageToLlmChatFunction };
 export { useSendMessageToLlmChat };
@@ -143,6 +146,7 @@ export { reactSaveFormatDefinition };
 export { txtSaveFormatDefinition };
 export type { ChatProgressItem };
 export type { ChatProgressCard };
+export type { ChatMessageSource };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };

package/esm/src/_packages/core.index.d.ts

@@ -28,6 +28,7 @@ import { getAllCommitmentTypes } from '../commitments/_common/getAllCommitmentTy
 import { getCommitmentDefinition } from '../commitments/_common/getCommitmentDefinition';
 import { getGroupedCommitmentDefinitions } from '../commitments/_common/getGroupedCommitmentDefinitions';
 import { isCommitmentSupported } from '../commitments/_common/isCommitmentSupported';
+import { KNOWLEDGE_SEARCH_TOOL_NAME } from '../commitments/KNOWLEDGE/KNOWLEDGE';
 import { NAME } from '../config';
 import { ADMIN_EMAIL } from '../config';
 import { PROMPTBOOK_LEGAL_ENTITY } from '../config';
@@ -252,6 +253,7 @@ export { getAllCommitmentTypes };
 export { getCommitmentDefinition };
 export { getGroupedCommitmentDefinitions };
 export { isCommitmentSupported };
+export { KNOWLEDGE_SEARCH_TOOL_NAME };
 export { NAME };
 export { ADMIN_EMAIL };
 export { PROMPTBOOK_LEGAL_ENTITY };

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

@@ -44,6 +44,7 @@ import type { SourceChipProps } from '../book-components/Chat/SourceChip/SourceC
 import type { ChatToolCall } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressItem } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressCard } from '../book-components/Chat/types/ChatMessage';
+import type { ChatMessageSource } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessageReplyingTo } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
@@ -477,6 +478,7 @@ export type { SourceChipProps };
 export type { ChatToolCall };
 export type { ChatProgressItem };
 export type { ChatProgressCard };
+export type { ChatMessageSource };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };

package/esm/src/book-components/Chat/Chat/TeamToolCallModalContent.d.ts

@@ -25,8 +25,6 @@ type TeamToolCallModalContentOptions = {
 /**
  * Renders TEAM conversation details, nested actions, and citations.
  *
- * @param options - TEAM modal rendering options.
- *
  * @private function of ChatToolCallModal
  */
 export declare function TeamToolCallModalContent(options: TeamToolCallModalContentOptions): ReactElement;

package/esm/src/book-components/Chat/Chat/renderTimeoutToolCallDetails.d.ts

@@ -1,5 +1,11 @@
 import { type ReactElement } from 'react';
 import type { TODO_any } from '../../../utils/organization/TODO_any';
+/**
+ * Translation overrides used by timeout detail rendering.
+ *
+ * @private function of ChatToolCallModal
+ */
+type TimeoutToolCallTranslations = import('./ChatProps').ChatUiTranslations;
 /**
  * Rendering options for timeout tool calls.
  *
@@ -33,7 +39,7 @@ type RenderTimeoutToolCallDetailsOptions = {
     /**
      * Optional translation overrides.
      */
-    chatUiTranslations?: import('./ChatProps').ChatUiTranslations;
+    chatUiTranslations?: TimeoutToolCallTranslations;
 };
 /**
  * Renders the timeout-specific tool call detail view.

package/esm/src/book-components/Chat/Chat/useChatInputAreaComposer.d.ts

@@ -32,7 +32,7 @@ export declare function useChatInputAreaComposer(props: UseChatInputAreaComposer
     messageContent: string;
     messageContentRef: import("react").RefObject<string>;
     applyMessageContent: (nextContent: string) => void;
-    handleTextInputChange: (event: ChangeEvent<HTMLTextAreaElement>) => void;
+    handleTextInputChange: (event: ChangeEvent<HTMLTextAreaElement, Element>) => void;
     handleComposerKeyDown: (event: ReactKeyboardEvent<HTMLTextAreaElement>) => void;
     handleSend: () => Promise<void>;
 };

package/esm/src/book-components/Chat/Chat/useChatInputAreaDictation.d.ts

@@ -1,4 +1,4 @@
-import { type MutableRefObject } from 'react';
+import { type Dispatch, type MutableRefObject, type SetStateAction } from 'react';
 import type { SpeechRecognitionErrorCode } from '../../../types/SpeechRecognition';
 import type { ChatProps } from './ChatProps';
 import { type DictationRefinementSettings } from './refineFinalDictationChunk';
@@ -38,7 +38,7 @@ export declare function useChatInputAreaDictation({ speechRecognition, speechRec
     dictationError: DictationError | null;
     dictationLastFinalChunk: string;
     dictationEditableChunk: string;
-    setDictationEditableChunk: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setDictationEditableChunk: Dispatch<SetStateAction<string>>;
     canBacktrack: boolean;
     dictationSettings: DictationRefinementSettings;
     handleDictationSettingChange: (settingName: keyof DictationRefinementSettings, checked: boolean) => void;

package/esm/src/book-components/Chat/hooks/useChatAutoScroll.d.ts

@@ -1,5 +1,8 @@
+import { type UIEvent } from 'react';
 /**
- * Configuration for the auto-scroll behavior
+ * Configuration for the auto-scroll behavior.
+ *
+ * @public exported from `@promptbook/components`
  */
 export type ChatAutoScrollConfig = {
     /**
@@ -32,8 +35,8 @@ export type ChatAutoScrollConfig = {
 export declare function useChatAutoScroll(config?: ChatAutoScrollConfig): {
     isAutoScrolling: boolean;
     chatMessagesRef: (element: HTMLDivElement | null) => void;
-    handleScroll: (event: React.UIEvent<HTMLDivElement>) => void;
-    handleMessagesChange: (isStreaming?: boolean) => void;
+    handleScroll: (event: UIEvent<HTMLDivElement, globalThis.UIEvent>) => void;
+    handleMessagesChange: (isStreaming?: boolean | undefined) => void;
     scrollToBottom: () => void;
     enableAutoScroll: () => void;
     disableAutoScroll: () => void;

package/esm/src/book-components/Chat/types/ChatMessage.d.ts

@@ -58,6 +58,36 @@ export type ChatProgressCard = {
      */
     readonly isVisible?: boolean;
 };
+/**
+ * Source used by an assistant message.
+ *
+ * This is used for knowledge-search results and other RAG systems that can
+ * attach structured source metadata independently of inline citation markers.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatMessageSource = {
+    /**
+     * The unique identifier for the source citation (e.g., "0:0")
+     */
+    readonly id: string;
+    /**
+     * The source document name (e.g., "document.pdf")
+     */
+    readonly source: string;
+    /**
+     * Optional URL to the source document
+     */
+    readonly url?: string;
+    /**
+     * Optional preview/excerpt from the source
+     */
+    readonly excerpt?: string;
+    /**
+     * Optional retrieval score.
+     */
+    readonly score?: number;
+};
 /**
  * Serialized reference to an earlier chat message quoted by a reply bubble.
  *
@@ -255,6 +285,10 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
          */
         excerpt?: string;
     }>;
+    /**
+     * Optional structured sources used to produce this message.
+     */
+    readonly sources?: ReadonlyArray<ChatMessageSource>;
     /**
      * Optional structured progress-card payload shown while a response is still in progress.
      */

package/esm/src/cli/cli-commands/agent/agentProjectPaths.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Relative path to the local agent source initialized by `ptbk agent init`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_BOOK_FILE_PATH = "agent.book";
+/**
+ * Relative path to the message queue root initialized by `ptbk agent init`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_MESSAGES_DIRECTORY_PATH = "messages";
+/**
+ * Relative path to queued user messages consumed by `ptbk agent tick`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to answered messages written by `ptbk agent tick`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to local knowledge files referenced by the default agent prompt.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_KNOWLEDGE_DIRECTORY_PATH = "knowledge";
+/**
+ * Relative path to local agent documentation initialized by `ptbk agent init`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_DOCS_DIRECTORY_PATH = "docs";
+/**
+ * Relative path to the local Book language manual used by the coding runner prompt.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH: string;
+/**
+ * Returns the default local agent book content.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function getDefaultAgentBookContent(): string;
+/**
+ * Returns the default local Book language manual content.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function getDefaultBookLanguageManualContent(): string;

package/esm/src/cli/cli-commands/agent/agentRunCliOptions.d.ts

@@ -0,0 +1,13 @@
+import type { NormalizedPromptRunnerCliOptions, PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
+/**
+ * Options passed from `ptbk agent` CLI commands to the message runner.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export type AgentRunCliOptions = PromptRunnerCliOptions;
+/**
+ * Converts Commander options into the `scripts/run-agent-messages` option shape.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function createAgentRunOptionsFromCliOptions(cliOptions: AgentRunCliOptions): NormalizedPromptRunnerCliOptions;

package/esm/src/cli/cli-commands/agent/init.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent init` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentInitCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/agent/initializeAgentProjectConfiguration.d.ts

@@ -0,0 +1,21 @@
+import type { InitializationStatus } from '../coder/boilerplateTemplates';
+/**
+ * Result summary returned after local agent configuration initialization.
+ *
+ * @private internal utility of `ptbk agent init`
+ */
+export type AgentInitializationSummary = {
+    readonly messagesDirectoryStatus: InitializationStatus;
+    readonly queuedMessagesDirectoryStatus: InitializationStatus;
+    readonly finishedMessagesDirectoryStatus: InitializationStatus;
+    readonly knowledgeDirectoryStatus: InitializationStatus;
+    readonly docsDirectoryStatus: InitializationStatus;
+    readonly agentBookFileStatus: InitializationStatus;
+    readonly bookLanguageManualFileStatus: InitializationStatus;
+};
+/**
+ * Creates local agent queue, knowledge, and instruction files in the current project.
+ *
+ * @private internal utility of `ptbk agent init`
+ */
+export declare function initializeAgentProjectConfiguration(projectPath: string): Promise<AgentInitializationSummary>;

package/esm/src/cli/cli-commands/agent/printAgentInitializationSummary.d.ts

@@ -0,0 +1,7 @@
+import type { AgentInitializationSummary } from './initializeAgentProjectConfiguration';
+/**
+ * Prints a readable summary of initialized local agent files.
+ *
+ * @private internal utility of `ptbk agent init`
+ */
+export declare function printAgentInitializationSummary(summary: AgentInitializationSummary): void;

package/esm/src/cli/cli-commands/agent/run.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent run` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentRunCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/agent/run.test.d.ts

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

package/esm/src/cli/cli-commands/agent/tick.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent tick` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentTickCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/agent.d.ts

@@ -0,0 +1,15 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Initializes `agent` command with subcommands for Promptbook CLI utilities.
+ *
+ * The agent command provides utilities for repository-backed message queues:
+ * - init: Initialize local agent queue and instruction files
+ * - tick: Answer one queued message and exit
+ * - run: Watch the queue and answer messages one by one
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/common/promptRunnerCliOptions.d.ts

@@ -0,0 +1,86 @@
+import { Command as Program } from 'commander';
+import { type ThinkingLevel } from '../coder/ThinkingLevel';
+/**
+ * Runner identifiers supported by Promptbook CLI agent orchestration commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_AGENT_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+/**
+ * Runner identifier supported by Promptbook CLI agent orchestration commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptRunnerAgentName = (typeof PROMPT_RUNNER_AGENT_NAMES)[number];
+/**
+ * Commander option bag for shared runner flags.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptRunnerCliOptions = {
+    readonly agent?: string;
+    readonly model?: string;
+    readonly ui: boolean;
+    readonly thinkingLevel?: ThinkingLevel;
+    readonly commit: boolean;
+    readonly ignoreGitChanges: boolean;
+    readonly allowCredits: boolean;
+    readonly normalizeLineEndings: boolean;
+    readonly autoPush: boolean;
+    readonly autoPull: boolean;
+};
+/**
+ * Normalized runner options used by runner-backed CLI commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedPromptRunnerCliOptions = {
+    readonly agentName?: PromptRunnerAgentName;
+    readonly model?: string;
+    readonly noUi: boolean;
+    readonly thinkingLevel?: ThinkingLevel;
+    readonly noCommit: boolean;
+    readonly ignoreGitChanges: boolean;
+    readonly allowCredits: boolean;
+    readonly normalizeLineEndings: boolean;
+    readonly autoPush: boolean;
+    readonly autoPull: boolean;
+};
+/**
+ * Description block shared by runner-backed CLI commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_DESCRIPTION: string;
+/**
+ * Commander description for the `--agent` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_AGENT_OPTION_DESCRIPTION = "Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)";
+/**
+ * Commander description for the `--model` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION: string;
+/**
+ * Registers runner selection flags on a command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptRunnerSelectionOptions(command: Program): void;
+/**
+ * Registers shared runner execution flags on a command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptRunnerExecutionOptions(command: Program): void;
+/**
+ * Converts Commander runner flags into normalized runner options.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizePromptRunnerCliOptions(cliOptions: PromptRunnerCliOptions, options: {
+    readonly isAgentRequired: boolean;
+}): NormalizedPromptRunnerCliOptions;

package/esm/src/commitments/KNOWLEDGE/KNOWLEDGE.d.ts

@@ -1,5 +1,12 @@
+import type { string_javascript_name } from '../../_packages/types.index';
 import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
 import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+/**
+ * Name of the tool used by agents to search configured `KNOWLEDGE` sources.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const KNOWLEDGE_SEARCH_TOOL_NAME: string;
 /**
  * KNOWLEDGE commitment definition
  *
@@ -37,4 +44,8 @@ export declare class KnowledgeCommitmentDefinition extends BaseCommitmentDefinit
      */
     get documentation(): string;
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+    /**
+     * Gets human-readable titles for tool functions provided by this commitment.
+     */
+    getToolTitles(): Record<string_javascript_name, string>;
 }

package/esm/src/commitments/KNOWLEDGE/KNOWLEDGE.test.d.ts

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

package/esm/src/commitments/_common/toolRuntimeContext.d.ts

@@ -98,6 +98,12 @@ export type ToolRuntimeContext = {
         localServerUrl?: string;
         teamInternalAccessToken?: string;
     };
+    knowledge?: {
+        /**
+         * Final materialized knowledge sources available to the current agent.
+         */
+        sources?: string[];
+    };
     spawn?: {
         depth?: number;
         parentRunId?: string;

package/esm/src/commitments/index.d.ts

@@ -50,6 +50,7 @@ import { UseSpawnCommitmentDefinition } from './USE_SPAWN/USE_SPAWN';
 import { UseTimeoutCommitmentDefinition } from './USE_TIMEOUT/USE_TIMEOUT';
 import { UseTimeCommitmentDefinition } from './USE_TIME/USE_TIME';
 import { UseUserLocationCommitmentDefinition } from './USE_USER_LOCATION/USE_USER_LOCATION';
+import { WalletCommitmentDefinition } from './WALLET/WALLET';
 import { WritingRulesCommitmentDefinition } from './WRITING_RULES/WRITING_RULES';
 import { WritingSampleCommitmentDefinition } from './WRITING_SAMPLE/WRITING_SAMPLE';
 import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplementedCommitmentDefinition';
@@ -60,4 +61,4 @@ import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplemented
  *
  * @private Use functions to access commitments instead of this array directly
  */
-export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, MemoryCommitmentDefinition, MemoryCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, ComponentCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseBrowserCommitmentDefinition, UseDeepSearchCommitmentDefinition, UseSearchEngineCommitmentDefinition, UseSpawnCommitmentDefinition, UseTimeoutCommitmentDefinition, UseTimeCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UseEmailCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];
+export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, MemoryCommitmentDefinition, MemoryCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, ComponentCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, WalletCommitmentDefinition, WalletCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseBrowserCommitmentDefinition, UseDeepSearchCommitmentDefinition, UseSearchEngineCommitmentDefinition, UseSpawnCommitmentDefinition, UseTimeoutCommitmentDefinition, UseTimeCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UseEmailCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];

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

@@ -1,4 +1,3 @@
-import type { Tool as AgentKitTool } from '@openai/agents';
 import { Agent as AgentFromKit } from '@openai/agents';
 import OpenAI from 'openai';
 import { TODO_any } from '../../_packages/types.index';
@@ -110,7 +109,6 @@ export declare class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandl
         readonly instructions: string_markdown;
         readonly knowledgeSources?: ReadonlyArray<string>;
         readonly tools?: ModelRequirements['tools'];
-        readonly nativeAgentKitTools?: ReadonlyArray<AgentKitTool>;
         readonly vectorStoreId?: string;
         readonly storeAsPrepared?: boolean;
     }): Promise<OpenAiAgentKitPreparedAgent>;
@@ -180,6 +178,10 @@ export declare class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandl
      * Returns AgentKit-specific options.
      */
     private get agentKitOptions();
+    /**
+     * Returns true when hosted OpenAI vector-store search should back `knowledgeSources`.
+     */
+    private get isNativeKnowledgeSearchEnabled();
     /**
      * Discriminant for type guards.
      */

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

@@ -12,4 +12,13 @@ export type OpenAiAgentKitExecutionToolsOptions = OpenAiVectorStoreHandlerOption
      * @default gpt-5.2
      */
     readonly agentKitModelName?: string_model_name;
+    /**
+     * Enables OpenAI hosted vector-store file search for `knowledgeSources`.
+     *
+     * Agents Server sets this to `false` because it uses a DB-backed LlamaIndex
+     * implementation exposed through the `knowledge_search` tool instead.
+     *
+     * @default true
+     */
+    readonly isNativeKnowledgeSearchEnabled?: boolean;
 };

package/esm/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.112.0-61`).
+ * It follows semantic versioning (e.g., `0.112.0-63`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/utils",
-    "version": "0.112.0-62",
+    "version": "0.112.0-64",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-62';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-64';
     /**
      * 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/umd/src/_packages/components.index.d.ts

@@ -34,6 +34,7 @@ import type { ChatEffect } from '../book-components/Chat/effects/types/ChatEffec
 import type { ChatEffectConfig } from '../book-components/Chat/effects/types/ChatEffectConfig';
 import type { ChatEffectsSystemProps } from '../book-components/Chat/effects/types/ChatEffectsSystemProps';
 import type { ChatEffectType } from '../book-components/Chat/effects/types/ChatEffectType';
+import type { ChatAutoScrollConfig } from '../book-components/Chat/hooks/useChatAutoScroll';
 import { useChatAutoScroll } from '../book-components/Chat/hooks/useChatAutoScroll';
 import type { SendMessageToLlmChatFunction } from '../book-components/Chat/hooks/useSendMessageToLlmChat';
 import { useSendMessageToLlmChat } from '../book-components/Chat/hooks/useSendMessageToLlmChat';
@@ -61,6 +62,7 @@ import { reactSaveFormatDefinition } from '../book-components/Chat/save/react/re
 import { txtSaveFormatDefinition } from '../book-components/Chat/save/text/txtSaveFormatDefinition';
 import type { ChatProgressItem } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressCard } from '../book-components/Chat/types/ChatMessage';
+import type { ChatMessageSource } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessageReplyingTo } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
@@ -116,6 +118,7 @@ export type { ChatEffect };
 export type { ChatEffectConfig };
 export type { ChatEffectsSystemProps };
 export type { ChatEffectType };
+export type { ChatAutoScrollConfig };
 export { useChatAutoScroll };
 export type { SendMessageToLlmChatFunction };
 export { useSendMessageToLlmChat };
@@ -143,6 +146,7 @@ export { reactSaveFormatDefinition };
 export { txtSaveFormatDefinition };
 export type { ChatProgressItem };
 export type { ChatProgressCard };
+export type { ChatMessageSource };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };

package/umd/src/_packages/core.index.d.ts

@@ -28,6 +28,7 @@ import { getAllCommitmentTypes } from '../commitments/_common/getAllCommitmentTy
 import { getCommitmentDefinition } from '../commitments/_common/getCommitmentDefinition';
 import { getGroupedCommitmentDefinitions } from '../commitments/_common/getGroupedCommitmentDefinitions';
 import { isCommitmentSupported } from '../commitments/_common/isCommitmentSupported';
+import { KNOWLEDGE_SEARCH_TOOL_NAME } from '../commitments/KNOWLEDGE/KNOWLEDGE';
 import { NAME } from '../config';
 import { ADMIN_EMAIL } from '../config';
 import { PROMPTBOOK_LEGAL_ENTITY } from '../config';
@@ -252,6 +253,7 @@ export { getAllCommitmentTypes };
 export { getCommitmentDefinition };
 export { getGroupedCommitmentDefinitions };
 export { isCommitmentSupported };
+export { KNOWLEDGE_SEARCH_TOOL_NAME };
 export { NAME };
 export { ADMIN_EMAIL };
 export { PROMPTBOOK_LEGAL_ENTITY };

package/umd/src/_packages/types.index.d.ts

@@ -44,6 +44,7 @@ import type { SourceChipProps } from '../book-components/Chat/SourceChip/SourceC
 import type { ChatToolCall } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressItem } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressCard } from '../book-components/Chat/types/ChatMessage';
+import type { ChatMessageSource } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessageReplyingTo } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
@@ -477,6 +478,7 @@ export type { SourceChipProps };
 export type { ChatToolCall };
 export type { ChatProgressItem };
 export type { ChatProgressCard };
+export type { ChatMessageSource };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };

package/umd/src/book-components/Chat/Chat/TeamToolCallModalContent.d.ts

@@ -25,8 +25,6 @@ type TeamToolCallModalContentOptions = {
 /**
  * Renders TEAM conversation details, nested actions, and citations.
  *
- * @param options - TEAM modal rendering options.
- *
  * @private function of ChatToolCallModal
  */
 export declare function TeamToolCallModalContent(options: TeamToolCallModalContentOptions): ReactElement;

package/umd/src/book-components/Chat/Chat/renderTimeoutToolCallDetails.d.ts

@@ -1,5 +1,11 @@
 import { type ReactElement } from 'react';
 import type { TODO_any } from '../../../utils/organization/TODO_any';
+/**
+ * Translation overrides used by timeout detail rendering.
+ *
+ * @private function of ChatToolCallModal
+ */
+type TimeoutToolCallTranslations = import('./ChatProps').ChatUiTranslations;
 /**
  * Rendering options for timeout tool calls.
  *
@@ -33,7 +39,7 @@ type RenderTimeoutToolCallDetailsOptions = {
     /**
      * Optional translation overrides.
      */
-    chatUiTranslations?: import('./ChatProps').ChatUiTranslations;
+    chatUiTranslations?: TimeoutToolCallTranslations;
 };
 /**
  * Renders the timeout-specific tool call detail view.

package/umd/src/book-components/Chat/Chat/useChatInputAreaComposer.d.ts

@@ -32,7 +32,7 @@ export declare function useChatInputAreaComposer(props: UseChatInputAreaComposer
     messageContent: string;
     messageContentRef: import("react").RefObject<string>;
     applyMessageContent: (nextContent: string) => void;
-    handleTextInputChange: (event: ChangeEvent<HTMLTextAreaElement>) => void;
+    handleTextInputChange: (event: ChangeEvent<HTMLTextAreaElement, Element>) => void;
     handleComposerKeyDown: (event: ReactKeyboardEvent<HTMLTextAreaElement>) => void;
     handleSend: () => Promise<void>;
 };

package/umd/src/book-components/Chat/Chat/useChatInputAreaDictation.d.ts

@@ -1,4 +1,4 @@
-import { type MutableRefObject } from 'react';
+import { type Dispatch, type MutableRefObject, type SetStateAction } from 'react';
 import type { SpeechRecognitionErrorCode } from '../../../types/SpeechRecognition';
 import type { ChatProps } from './ChatProps';
 import { type DictationRefinementSettings } from './refineFinalDictationChunk';
@@ -38,7 +38,7 @@ export declare function useChatInputAreaDictation({ speechRecognition, speechRec
     dictationError: DictationError | null;
     dictationLastFinalChunk: string;
     dictationEditableChunk: string;
-    setDictationEditableChunk: import("react").Dispatch<import("react").SetStateAction<string>>;
+    setDictationEditableChunk: Dispatch<SetStateAction<string>>;
     canBacktrack: boolean;
     dictationSettings: DictationRefinementSettings;
     handleDictationSettingChange: (settingName: keyof DictationRefinementSettings, checked: boolean) => void;

package/umd/src/book-components/Chat/hooks/useChatAutoScroll.d.ts

@@ -1,5 +1,8 @@
+import { type UIEvent } from 'react';
 /**
- * Configuration for the auto-scroll behavior
+ * Configuration for the auto-scroll behavior.
+ *
+ * @public exported from `@promptbook/components`
  */
 export type ChatAutoScrollConfig = {
     /**
@@ -32,8 +35,8 @@ export type ChatAutoScrollConfig = {
 export declare function useChatAutoScroll(config?: ChatAutoScrollConfig): {
     isAutoScrolling: boolean;
     chatMessagesRef: (element: HTMLDivElement | null) => void;
-    handleScroll: (event: React.UIEvent<HTMLDivElement>) => void;
-    handleMessagesChange: (isStreaming?: boolean) => void;
+    handleScroll: (event: UIEvent<HTMLDivElement, globalThis.UIEvent>) => void;
+    handleMessagesChange: (isStreaming?: boolean | undefined) => void;
     scrollToBottom: () => void;
     enableAutoScroll: () => void;
     disableAutoScroll: () => void;

package/umd/src/book-components/Chat/types/ChatMessage.d.ts

@@ -58,6 +58,36 @@ export type ChatProgressCard = {
      */
     readonly isVisible?: boolean;
 };
+/**
+ * Source used by an assistant message.
+ *
+ * This is used for knowledge-search results and other RAG systems that can
+ * attach structured source metadata independently of inline citation markers.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatMessageSource = {
+    /**
+     * The unique identifier for the source citation (e.g., "0:0")
+     */
+    readonly id: string;
+    /**
+     * The source document name (e.g., "document.pdf")
+     */
+    readonly source: string;
+    /**
+     * Optional URL to the source document
+     */
+    readonly url?: string;
+    /**
+     * Optional preview/excerpt from the source
+     */
+    readonly excerpt?: string;
+    /**
+     * Optional retrieval score.
+     */
+    readonly score?: number;
+};
 /**
  * Serialized reference to an earlier chat message quoted by a reply bubble.
  *
@@ -255,6 +285,10 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
          */
         excerpt?: string;
     }>;
+    /**
+     * Optional structured sources used to produce this message.
+     */
+    readonly sources?: ReadonlyArray<ChatMessageSource>;
     /**
      * Optional structured progress-card payload shown while a response is still in progress.
      */

package/umd/src/cli/cli-commands/agent/agentProjectPaths.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Relative path to the local agent source initialized by `ptbk agent init`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_BOOK_FILE_PATH = "agent.book";
+/**
+ * Relative path to the message queue root initialized by `ptbk agent init`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_MESSAGES_DIRECTORY_PATH = "messages";
+/**
+ * Relative path to queued user messages consumed by `ptbk agent tick`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to answered messages written by `ptbk agent tick`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to local knowledge files referenced by the default agent prompt.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_KNOWLEDGE_DIRECTORY_PATH = "knowledge";
+/**
+ * Relative path to local agent documentation initialized by `ptbk agent init`.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_DOCS_DIRECTORY_PATH = "docs";
+/**
+ * Relative path to the local Book language manual used by the coding runner prompt.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare const AGENT_BOOK_LANGUAGE_MANUAL_FILE_PATH: string;
+/**
+ * Returns the default local agent book content.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function getDefaultAgentBookContent(): string;
+/**
+ * Returns the default local Book language manual content.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function getDefaultBookLanguageManualContent(): string;

package/umd/src/cli/cli-commands/agent/agentRunCliOptions.d.ts

@@ -0,0 +1,13 @@
+import type { NormalizedPromptRunnerCliOptions, PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
+/**
+ * Options passed from `ptbk agent` CLI commands to the message runner.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export type AgentRunCliOptions = PromptRunnerCliOptions;
+/**
+ * Converts Commander options into the `scripts/run-agent-messages` option shape.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function createAgentRunOptionsFromCliOptions(cliOptions: AgentRunCliOptions): NormalizedPromptRunnerCliOptions;

package/umd/src/cli/cli-commands/agent/init.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent init` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentInitCommand(program: Program): $side_effect;

package/umd/src/cli/cli-commands/agent/initializeAgentProjectConfiguration.d.ts

@@ -0,0 +1,21 @@
+import type { InitializationStatus } from '../coder/boilerplateTemplates';
+/**
+ * Result summary returned after local agent configuration initialization.
+ *
+ * @private internal utility of `ptbk agent init`
+ */
+export type AgentInitializationSummary = {
+    readonly messagesDirectoryStatus: InitializationStatus;
+    readonly queuedMessagesDirectoryStatus: InitializationStatus;
+    readonly finishedMessagesDirectoryStatus: InitializationStatus;
+    readonly knowledgeDirectoryStatus: InitializationStatus;
+    readonly docsDirectoryStatus: InitializationStatus;
+    readonly agentBookFileStatus: InitializationStatus;
+    readonly bookLanguageManualFileStatus: InitializationStatus;
+};
+/**
+ * Creates local agent queue, knowledge, and instruction files in the current project.
+ *
+ * @private internal utility of `ptbk agent init`
+ */
+export declare function initializeAgentProjectConfiguration(projectPath: string): Promise<AgentInitializationSummary>;

package/umd/src/cli/cli-commands/agent/printAgentInitializationSummary.d.ts

@@ -0,0 +1,7 @@
+import type { AgentInitializationSummary } from './initializeAgentProjectConfiguration';
+/**
+ * Prints a readable summary of initialized local agent files.
+ *
+ * @private internal utility of `ptbk agent init`
+ */
+export declare function printAgentInitializationSummary(summary: AgentInitializationSummary): void;

package/umd/src/cli/cli-commands/agent/run.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent run` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentRunCommand(program: Program): $side_effect;

package/umd/src/cli/cli-commands/agent/run.test.d.ts

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

package/umd/src/cli/cli-commands/agent/tick.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent tick` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentTickCommand(program: Program): $side_effect;

package/umd/src/cli/cli-commands/agent.d.ts

@@ -0,0 +1,15 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../utils/organization/$side_effect';
+/**
+ * Initializes `agent` command with subcommands for Promptbook CLI utilities.
+ *
+ * The agent command provides utilities for repository-backed message queues:
+ * - init: Initialize local agent queue and instruction files
+ * - tick: Answer one queued message and exit
+ * - run: Watch the queue and answer messages one by one
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentCommand(program: Program): $side_effect;

package/umd/src/cli/cli-commands/common/promptRunnerCliOptions.d.ts

@@ -0,0 +1,86 @@
+import { Command as Program } from 'commander';
+import { type ThinkingLevel } from '../coder/ThinkingLevel';
+/**
+ * Runner identifiers supported by Promptbook CLI agent orchestration commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_AGENT_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+/**
+ * Runner identifier supported by Promptbook CLI agent orchestration commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptRunnerAgentName = (typeof PROMPT_RUNNER_AGENT_NAMES)[number];
+/**
+ * Commander option bag for shared runner flags.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type PromptRunnerCliOptions = {
+    readonly agent?: string;
+    readonly model?: string;
+    readonly ui: boolean;
+    readonly thinkingLevel?: ThinkingLevel;
+    readonly commit: boolean;
+    readonly ignoreGitChanges: boolean;
+    readonly allowCredits: boolean;
+    readonly normalizeLineEndings: boolean;
+    readonly autoPush: boolean;
+    readonly autoPull: boolean;
+};
+/**
+ * Normalized runner options used by runner-backed CLI commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export type NormalizedPromptRunnerCliOptions = {
+    readonly agentName?: PromptRunnerAgentName;
+    readonly model?: string;
+    readonly noUi: boolean;
+    readonly thinkingLevel?: ThinkingLevel;
+    readonly noCommit: boolean;
+    readonly ignoreGitChanges: boolean;
+    readonly allowCredits: boolean;
+    readonly normalizeLineEndings: boolean;
+    readonly autoPush: boolean;
+    readonly autoPull: boolean;
+};
+/**
+ * Description block shared by runner-backed CLI commands.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_DESCRIPTION: string;
+/**
+ * Commander description for the `--agent` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_AGENT_OPTION_DESCRIPTION = "Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)";
+/**
+ * Commander description for the `--model` option.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare const PROMPT_RUNNER_MODEL_OPTION_DESCRIPTION: string;
+/**
+ * Registers runner selection flags on a command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptRunnerSelectionOptions(command: Program): void;
+/**
+ * Registers shared runner execution flags on a command.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function addPromptRunnerExecutionOptions(command: Program): void;
+/**
+ * Converts Commander runner flags into normalized runner options.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export declare function normalizePromptRunnerCliOptions(cliOptions: PromptRunnerCliOptions, options: {
+    readonly isAgentRequired: boolean;
+}): NormalizedPromptRunnerCliOptions;

package/umd/src/commitments/KNOWLEDGE/KNOWLEDGE.d.ts

@@ -1,5 +1,12 @@
+import type { string_javascript_name } from '../../_packages/types.index';
 import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
 import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+/**
+ * Name of the tool used by agents to search configured `KNOWLEDGE` sources.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const KNOWLEDGE_SEARCH_TOOL_NAME: string;
 /**
  * KNOWLEDGE commitment definition
  *
@@ -37,4 +44,8 @@ export declare class KnowledgeCommitmentDefinition extends BaseCommitmentDefinit
      */
     get documentation(): string;
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+    /**
+     * Gets human-readable titles for tool functions provided by this commitment.
+     */
+    getToolTitles(): Record<string_javascript_name, string>;
 }

package/umd/src/commitments/KNOWLEDGE/KNOWLEDGE.test.d.ts

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

package/umd/src/commitments/_common/toolRuntimeContext.d.ts

@@ -98,6 +98,12 @@ export type ToolRuntimeContext = {
         localServerUrl?: string;
         teamInternalAccessToken?: string;
     };
+    knowledge?: {
+        /**
+         * Final materialized knowledge sources available to the current agent.
+         */
+        sources?: string[];
+    };
     spawn?: {
         depth?: number;
         parentRunId?: string;

package/umd/src/commitments/index.d.ts

@@ -50,6 +50,7 @@ import { UseSpawnCommitmentDefinition } from './USE_SPAWN/USE_SPAWN';
 import { UseTimeoutCommitmentDefinition } from './USE_TIMEOUT/USE_TIMEOUT';
 import { UseTimeCommitmentDefinition } from './USE_TIME/USE_TIME';
 import { UseUserLocationCommitmentDefinition } from './USE_USER_LOCATION/USE_USER_LOCATION';
+import { WalletCommitmentDefinition } from './WALLET/WALLET';
 import { WritingRulesCommitmentDefinition } from './WRITING_RULES/WRITING_RULES';
 import { WritingSampleCommitmentDefinition } from './WRITING_SAMPLE/WRITING_SAMPLE';
 import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplementedCommitmentDefinition';
@@ -60,4 +61,4 @@ import { NotYetImplementedCommitmentDefinition } from './_base/NotYetImplemented
  *
  * @private Use functions to access commitments instead of this array directly
  */
-export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, MemoryCommitmentDefinition, MemoryCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, ComponentCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseBrowserCommitmentDefinition, UseDeepSearchCommitmentDefinition, UseSearchEngineCommitmentDefinition, UseSpawnCommitmentDefinition, UseTimeoutCommitmentDefinition, UseTimeCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UseEmailCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];
+export declare const COMMITMENT_REGISTRY: readonly [PersonaCommitmentDefinition, PersonaCommitmentDefinition, KnowledgeCommitmentDefinition, MemoryCommitmentDefinition, MemoryCommitmentDefinition, StyleCommitmentDefinition, StyleCommitmentDefinition, RuleCommitmentDefinition, RuleCommitmentDefinition, LanguageCommitmentDefinition, LanguageCommitmentDefinition, WritingSampleCommitmentDefinition, WritingRulesCommitmentDefinition, SampleCommitmentDefinition, SampleCommitmentDefinition, FormatCommitmentDefinition, FormatCommitmentDefinition, TemplateCommitmentDefinition, TemplateCommitmentDefinition, FromCommitmentDefinition, ImportCommitmentDefinition, ImportCommitmentDefinition, ModelCommitmentDefinition, ModelCommitmentDefinition, ActionCommitmentDefinition, ActionCommitmentDefinition, ComponentCommitmentDefinition, MetaAvatarCommitmentDefinition, MetaImageCommitmentDefinition, MetaColorCommitmentDefinition, MetaFontCommitmentDefinition, MetaLinkCommitmentDefinition, MetaDomainCommitmentDefinition, MetaDisclaimerCommitmentDefinition, MetaInputPlaceholderCommitmentDefinition, MetaCommitmentDefinition, MetaVoiceCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, NoteCommitmentDefinition, GoalCommitmentDefinition, GoalCommitmentDefinition, InitialMessageCommitmentDefinition, UserMessageCommitmentDefinition, InternalMessageCommitmentDefinition, AgentMessageCommitmentDefinition, MessageSuffixCommitmentDefinition, MessageCommitmentDefinition, MessageCommitmentDefinition, WalletCommitmentDefinition, WalletCommitmentDefinition, ScenarioCommitmentDefinition, ScenarioCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DeleteCommitmentDefinition, DictionaryCommitmentDefinition, OpenCommitmentDefinition, ClosedCommitmentDefinition, TeamCommitmentDefinition, UseBrowserCommitmentDefinition, UseDeepSearchCommitmentDefinition, UseSearchEngineCommitmentDefinition, UseSpawnCommitmentDefinition, UseTimeoutCommitmentDefinition, UseTimeCommitmentDefinition, UseUserLocationCommitmentDefinition, UseCalendarCommitmentDefinition, UseEmailCommitmentDefinition, UsePopupCommitmentDefinition, UseImageGeneratorCommitmentDefinition, UseMcpCommitmentDefinition, UsePrivacyCommitmentDefinition, UseProjectCommitmentDefinition, NotYetImplementedCommitmentDefinition<"EXPECT">, NotYetImplementedCommitmentDefinition<"BEHAVIOUR">, NotYetImplementedCommitmentDefinition<"BEHAVIOURS">, NotYetImplementedCommitmentDefinition<"AVOID">, NotYetImplementedCommitmentDefinition<"AVOIDANCE">, NotYetImplementedCommitmentDefinition<"CONTEXT">];

package/umd/src/llm-providers/openai/OpenAiAgentKitExecutionTools.d.ts

@@ -1,4 +1,3 @@
-import type { Tool as AgentKitTool } from '@openai/agents';
 import { Agent as AgentFromKit } from '@openai/agents';
 import OpenAI from 'openai';
 import { TODO_any } from '../../_packages/types.index';
@@ -110,7 +109,6 @@ export declare class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandl
         readonly instructions: string_markdown;
         readonly knowledgeSources?: ReadonlyArray<string>;
         readonly tools?: ModelRequirements['tools'];
-        readonly nativeAgentKitTools?: ReadonlyArray<AgentKitTool>;
         readonly vectorStoreId?: string;
         readonly storeAsPrepared?: boolean;
     }): Promise<OpenAiAgentKitPreparedAgent>;
@@ -180,6 +178,10 @@ export declare class OpenAiAgentKitExecutionTools extends OpenAiVectorStoreHandl
      * Returns AgentKit-specific options.
      */
     private get agentKitOptions();
+    /**
+     * Returns true when hosted OpenAI vector-store search should back `knowledgeSources`.
+     */
+    private get isNativeKnowledgeSearchEnabled();
     /**
      * Discriminant for type guards.
      */

package/umd/src/llm-providers/openai/OpenAiAgentKitExecutionToolsOptions.d.ts

@@ -12,4 +12,13 @@ export type OpenAiAgentKitExecutionToolsOptions = OpenAiVectorStoreHandlerOption
      * @default gpt-5.2
      */
     readonly agentKitModelName?: string_model_name;
+    /**
+     * Enables OpenAI hosted vector-store file search for `knowledgeSources`.
+     *
+     * Agents Server sets this to `false` because it uses a DB-backed LlamaIndex
+     * implementation exposed through the `knowledge_search` tool instead.
+     *
+     * @default true
+     */
+    readonly isNativeKnowledgeSearchEnabled?: boolean;
 };

package/umd/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.112.0-61`).
+ * It follows semantic versioning (e.g., `0.112.0-63`).
  *
  * @generated
  */