@promptbook/utils 0.112.0-99 → 0.113.0-0

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

@@ -12,6 +12,7 @@ import type { BookEditorUploadProgressCallback } from '../book-components/BookEd
 import type { BookEditorUploadOptions } from '../book-components/BookEditor/BookEditor';
 import type { BookEditorProps } from '../book-components/BookEditor/BookEditor';
 import { BookEditor } from '../book-components/BookEditor/BookEditor';
+import { BookEditorForClient } from '../book-components/BookEditor/BookEditorForClient';
 import { AgentChat } from '../book-components/Chat/AgentChat/AgentChat';
 import type { AgentChatProps } from '../book-components/Chat/AgentChat/AgentChatProps';
 import { Chat } from '../book-components/Chat/Chat/Chat';
@@ -65,6 +66,7 @@ import type { ChatProgressCard } 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';
+import type { CitationLabelResolver } from '../book-components/Chat/types/CitationLabelResolver';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
@@ -95,6 +97,7 @@ export type { BookEditorUploadProgressCallback };
 export type { BookEditorUploadOptions };
 export type { BookEditorProps };
 export { BookEditor };
+export { BookEditorForClient };
 export { AgentChat };
 export type { AgentChatProps };
 export { Chat };
@@ -148,6 +151,7 @@ export type { ChatProgressCard };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };
+export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export { ArrowIcon };

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

@@ -1,4 +1,15 @@
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../version';
+import { AGENT_VISIBILITY_VALUES } from '../book-2.0/agent-source/agentSourceVisibility';
+import type { AgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
+import { DEFAULT_AGENT_VISIBILITY } from '../book-2.0/agent-source/agentSourceVisibility';
+import { isAgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
+import { normalizeAgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
+import { parseAgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
+import { parseAgentVisibilityStrict } from '../book-2.0/agent-source/agentSourceVisibility';
+import { parseAgentSourceVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
+import { isPublicAgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
+import { getNextAgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
+import { setAgentSourceVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
 import { computeAgentHash } from '../book-2.0/agent-source/computeAgentHash';
 import { createAgentModelRequirements } from '../book-2.0/agent-source/createAgentModelRequirements';
 import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
@@ -221,10 +232,20 @@ import { normalizeChatAttachments } from '../utils/chat/chatAttachments/normaliz
 import { resolveChatAttachmentContents } from '../utils/chat/chatAttachments/resolveChatAttachmentContents';
 import { aboutPromptbookInformation } from '../utils/misc/aboutPromptbookInformation';
 import { $generateBookBoilerplate } from '../utils/random/$generateBookBoilerplate';
-import { CORE_AGENTS_SERVER } from '../../servers';
 import { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES } from '../../servers';
 import { PUBLIC_AGENTS_SERVERS } from '../../servers';
 export { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION };
+export { AGENT_VISIBILITY_VALUES };
+export type { AgentVisibility };
+export { DEFAULT_AGENT_VISIBILITY };
+export { isAgentVisibility };
+export { normalizeAgentVisibility };
+export { parseAgentVisibility };
+export { parseAgentVisibilityStrict };
+export { parseAgentSourceVisibility };
+export { isPublicAgentVisibility };
+export { getNextAgentVisibility };
+export { setAgentSourceVisibility };
 export { computeAgentHash };
 export { createAgentModelRequirements };
 export type { CreateAgentModelRequirementsOptions };
@@ -447,6 +468,5 @@ export { normalizeChatAttachments };
 export { resolveChatAttachmentContents };
 export { aboutPromptbookInformation };
 export { $generateBookBoilerplate };
-export { CORE_AGENTS_SERVER };
 export { CORE_AGENTS_SERVER_WELL_KNOWN_AGENT_NAMES };
 export { PUBLIC_AGENTS_SERVERS };

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

@@ -1,4 +1,24 @@
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../version';
+import { AGENT_BOOK_FILE_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_QUEUED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import { AGENT_FAILED_MESSAGES_DIRECTORY_PATH } from '../book-3.0/agentFolderPaths';
+import type { BookNodeAgentSource } from '../book-3.0/BookNodeAgentSource';
+import type { BookNodeAgentSourceOptions } from '../book-3.0/BookNodeAgentSource';
+import type { CliAgentHarness } from '../book-3.0/CliAgent';
+import type { CliAgentThinkingLevel } from '../book-3.0/CliAgent';
+import type { CliAgentRunOptions } from '../book-3.0/CliAgent';
+import type { CliAgentOptions } from '../book-3.0/CliAgent';
+import { CliAgent } from '../book-3.0/CliAgent';
+import { CLI_AGENT_HARNESS_NAMES } from '../book-3.0/cliAgentEnv';
+import { CLI_AGENT_THINKING_LEVEL_VALUES } from '../book-3.0/cliAgentEnv';
+import { PTBK_HARNESS_ENV } from '../book-3.0/cliAgentEnv';
+import { PTBK_MODEL_ENV } from '../book-3.0/cliAgentEnv';
+import { PTBK_THINKING_LEVEL_ENV } from '../book-3.0/cliAgentEnv';
+import type { LiteAgentOptions } from '../book-3.0/LiteAgent';
+import type { LiteAgentRunOptions } from '../book-3.0/LiteAgent';
+import { LiteAgent } from '../book-3.0/LiteAgent';
 import { createPipelineCollectionFromDirectory } from '../collection/pipeline-collection/constructors/createPipelineCollectionFromDirectory';
 import { getAllCommitmentsToolFunctionsForNode } from '../commitments/_common/getAllCommitmentsToolFunctionsForNode';
 import { $provideExecutablesForNode } from '../executables/$provideExecutablesForNode';
@@ -12,6 +32,26 @@ import { FileCacheStorage } from '../storage/file-cache-storage/FileCacheStorage
 import { $execCommand } from '../utils/execCommand/$execCommand';
 import { $execCommands } from '../utils/execCommand/$execCommands';
 export { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION };
+export { AGENT_BOOK_FILE_PATH };
+export { AGENT_MESSAGES_DIRECTORY_PATH };
+export { AGENT_QUEUED_MESSAGES_DIRECTORY_PATH };
+export { AGENT_FINISHED_MESSAGES_DIRECTORY_PATH };
+export { AGENT_FAILED_MESSAGES_DIRECTORY_PATH };
+export type { BookNodeAgentSource };
+export type { BookNodeAgentSourceOptions };
+export type { CliAgentHarness };
+export type { CliAgentThinkingLevel };
+export type { CliAgentRunOptions };
+export type { CliAgentOptions };
+export { CliAgent };
+export { CLI_AGENT_HARNESS_NAMES };
+export { CLI_AGENT_THINKING_LEVEL_VALUES };
+export { PTBK_HARNESS_ENV };
+export { PTBK_MODEL_ENV };
+export { PTBK_THINKING_LEVEL_ENV };
+export type { LiteAgentOptions };
+export type { LiteAgentRunOptions };
+export { LiteAgent };
 export { createPipelineCollectionFromDirectory };
 export { getAllCommitmentsToolFunctionsForNode };
 export { $provideExecutablesForNode };

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

@@ -2,8 +2,17 @@ import type { BookParameter } from '../book-2.0/agent-source/AgentBasicInformati
 import type { AgentCapability } from '../book-2.0/agent-source/AgentBasicInformation';
 import type { AgentBasicInformation } from '../book-2.0/agent-source/AgentBasicInformation';
 import type { AgentModelRequirements } from '../book-2.0/agent-source/AgentModelRequirements';
+import type { AgentVisibility } from '../book-2.0/agent-source/agentSourceVisibility';
 import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
 import type { string_book } from '../book-2.0/agent-source/string_book';
+import type { BookNodeAgentSource } from '../book-3.0/BookNodeAgentSource';
+import type { BookNodeAgentSourceOptions } from '../book-3.0/BookNodeAgentSource';
+import type { CliAgentHarness } from '../book-3.0/CliAgent';
+import type { CliAgentThinkingLevel } from '../book-3.0/CliAgent';
+import type { CliAgentRunOptions } from '../book-3.0/CliAgent';
+import type { CliAgentOptions } from '../book-3.0/CliAgent';
+import type { LiteAgentOptions } from '../book-3.0/LiteAgent';
+import type { LiteAgentRunOptions } from '../book-3.0/LiteAgent';
 import type { AvatarChipProps } from '../book-components/AvatarProfile/AvatarChip/AvatarChip';
 import type { AvatarChipFromSourceProps } from '../book-components/AvatarProfile/AvatarChip/AvatarChipFromSource';
 import type { AvatarProfileProps } from '../book-components/AvatarProfile/AvatarProfile/AvatarProfile';
@@ -47,6 +56,7 @@ import type { ChatProgressCard } 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';
+import type { CitationLabelResolver } from '../book-components/Chat/types/CitationLabelResolver';
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
@@ -435,8 +445,17 @@ export type { BookParameter };
 export type { AgentCapability };
 export type { AgentBasicInformation };
 export type { AgentModelRequirements };
+export type { AgentVisibility };
 export type { CreateAgentModelRequirementsOptions };
 export type { string_book };
+export type { BookNodeAgentSource };
+export type { BookNodeAgentSourceOptions };
+export type { CliAgentHarness };
+export type { CliAgentThinkingLevel };
+export type { CliAgentRunOptions };
+export type { CliAgentOptions };
+export type { LiteAgentOptions };
+export type { LiteAgentRunOptions };
 export type { AvatarChipProps };
 export type { AvatarChipFromSourceProps };
 export type { AvatarProfileProps };
@@ -480,6 +499,7 @@ export type { ChatProgressCard };
 export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };
+export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { TeamToolResult };

package/umd/src/avatars/avatarAnimationScheduler.d.ts

@@ -7,6 +7,10 @@ type AvatarAnimationListener = (now: number) => void;
 /**
  * Registers one avatar animation callback in the shared animation loop.
  *
+ * Each listener is staggered at registration time so it does not fire on the same animation
+ * frame as the existing listeners, and the shared loop further caps how many listeners run
+ * per frame, keeping the main thread responsive when many avatars are mounted.
+ *
  * @param avatarAnimationListener Frame callback invoked on every animation frame.
  * @returns Cleanup function that unregisters the callback.
  *

package/umd/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -7,7 +7,7 @@ import type { AvatarDefinition } from './AvatarDefinition';
  *
  * @private shared contract for the avatar rendering system
  */
-export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'octopus3d' | 'octopus3d2' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
+export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'octopus3d' | 'octopus3d2' | 'octopus3d3' | 'octopus3d4' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
 /**
  * Derived color palette used by avatar visuals.
  *

package/umd/src/avatars/visuals/octopus3d3AvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Octopus 3D 3 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopus3d3AvatarVisual: AvatarVisualDefinition;

package/umd/src/avatars/visuals/octopus3d4AvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Octopus 3D 4 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopus3d4AvatarVisual: AvatarVisualDefinition;

package/umd/src/book-2.0/agent-source/AgentBasicInformation.d.ts

@@ -4,6 +4,7 @@ import type { string_agent_url } from '../../types/string_agent_url';
 import type { string_fonts } from '../../types/string_markdown';
 import type { string_color } from '../../types/string_person_fullname';
 import type { string_url_image } from '../../types/string_url_image';
+import type { AgentVisibility } from './agentSourceVisibility';
 /**
  * Unified parameter representation that supports two different notations:
  * 1. @Parameter - single word parameter starting with @
@@ -97,6 +98,7 @@ export type AgentBasicInformation = {
         font?: string_fonts;
         color?: string_color;
         voice?: string;
+        visibility?: AgentVisibility;
         [key: string]: string | undefined;
     };
     /**

package/umd/src/book-2.0/agent-source/agentSourceVisibility.d.ts

@@ -0,0 +1,97 @@
+import type { string_book } from './string_book';
+/**
+ * Supported visibility states for persisted agents.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const AGENT_VISIBILITY_VALUES: readonly ["PRIVATE", "UNLISTED", "PUBLIC"];
+/**
+ * Canonical visibility union for agents.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export type AgentVisibility = (typeof AGENT_VISIBILITY_VALUES)[number];
+/**
+ * Fallback visibility used when no valid value is configured.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare const DEFAULT_AGENT_VISIBILITY: AgentVisibility;
+/**
+ * Returns `true` when the value is one of supported visibility states.
+ *
+ * @param value - Raw value to validate.
+ * @returns Whether the value is a valid `AgentVisibility`.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function isAgentVisibility(value: unknown): value is AgentVisibility;
+/**
+ * Normalizes raw visibility text into a supported value.
+ *
+ * @param value - Raw visibility value.
+ * @returns Normalized visibility, or `null` when invalid.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function normalizeAgentVisibility(value: unknown): AgentVisibility | null;
+/**
+ * Parses visibility from an unknown value with a safe fallback.
+ *
+ * @param value - Raw visibility value.
+ * @param fallback - Fallback when the value is invalid.
+ * @returns Parsed visibility.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function parseAgentVisibility(value: unknown, fallback?: AgentVisibility): AgentVisibility;
+/**
+ * Parses visibility and throws when the value is not supported.
+ *
+ * @param value - Raw visibility value.
+ * @param sourceLabel - Human-readable source used in the error message.
+ * @returns Parsed visibility.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function parseAgentVisibilityStrict(value: unknown, sourceLabel?: string): AgentVisibility;
+/**
+ * Extracts the last `META VISIBILITY` value from an agent source.
+ *
+ * @param agentSource - Raw book source.
+ * @param options - Strict parsing options.
+ * @returns Normalized visibility, or `null` when no commitment is present.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function parseAgentSourceVisibility(agentSource: string_book, options?: {
+    readonly isStrict?: boolean;
+}): AgentVisibility | null;
+/**
+ * Returns whether an agent should be listed publicly in anonymous views.
+ *
+ * @param visibility - Agent visibility to evaluate.
+ * @returns `true` for publicly listed agents.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function isPublicAgentVisibility(visibility: AgentVisibility | null | undefined): boolean;
+/**
+ * Returns the next visibility in UI rotation order.
+ *
+ * @param visibility - Current visibility.
+ * @returns Next visibility value.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function getNextAgentVisibility(visibility: AgentVisibility | null | undefined): AgentVisibility;
+/**
+ * Inserts or replaces the `META VISIBILITY` commitment in a book source.
+ *
+ * @param agentSource - Raw book source.
+ * @param visibility - Visibility to persist.
+ * @returns Source with exactly one normalized `META VISIBILITY` line.
+ *
+ * @public exported from `@promptbook/core`
+ */
+export declare function setAgentSourceVisibility(agentSource: string_book, visibility: AgentVisibility): string_book;

package/umd/src/book-2.0/agent-source/agentSourceVisibility.test.d.ts

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

package/umd/src/book-3.0/BookNodeAgentSource.d.ts

@@ -0,0 +1,38 @@
+import type { string_book } from '../book-2.0/agent-source/string_book';
+import { Book } from './Book';
+/**
+ * Book source value accepted by Node-backed Book agents.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type BookNodeAgentSource = Book | string_book;
+/**
+ * Common source options shared by Node-backed Book agents.
+ *
+ * Provide either `agentPath` or `book`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type BookNodeAgentSourceOptions = {
+    readonly agentPath?: string;
+    readonly book?: string | BookNodeAgentSource;
+    readonly currentWorkingDirectory?: string;
+};
+/**
+ * Normalized source snapshot used internally by Node-backed Book agents.
+ *
+ * @private internal utility of `CliAgent` and `LiteAgent`
+ */
+export type ResolvedBookNodeAgentSource = {
+    readonly agentName: string;
+    readonly agentPath: string | null;
+    readonly agentSource: string_book;
+    readonly currentWorkingDirectory: string;
+    readonly sourceDirectoryPath: string;
+};
+/**
+ * Resolves shared Node-backed Book source options into one normalized source snapshot.
+ *
+ * @private internal utility of `CliAgent` and `LiteAgent`
+ */
+export declare function resolveBookNodeAgentSource(options: BookNodeAgentSourceOptions): Promise<ResolvedBookNodeAgentSource>;

package/umd/src/book-3.0/CliAgent.d.ts

@@ -0,0 +1,66 @@
+import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
+import { CLI_AGENT_HARNESS_NAMES, CLI_AGENT_THINKING_LEVEL_VALUES } from './cliAgentEnv';
+/**
+ * CLI harness names supported by `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentHarness = (typeof CLI_AGENT_HARNESS_NAMES)[number];
+/**
+ * Thinking levels supported by CLI coding harnesses.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentThinkingLevel = (typeof CLI_AGENT_THINKING_LEVEL_VALUES)[number];
+/**
+ * Per-run CLI options exposed by `CliAgent`.
+ *
+ * `noUi` defaults to `true` so command output stays suitable for JavaScript callers.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentRunOptions = {
+    readonly allowCredits?: boolean;
+    readonly context?: string;
+    readonly harness?: CliAgentHarness;
+    readonly isVerbose?: boolean;
+    readonly model?: string;
+    readonly noUi?: boolean;
+    readonly thinkingLevel?: CliAgentThinkingLevel;
+};
+/**
+ * Constructor options for `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions;
+/**
+ * Lightweight JavaScript wrapper around the Promptbook agent execution pipeline.
+ *
+ * It uses the same harnesses and execution path as `ptbk agent exec`, running the runner
+ * in-process instead of spawning a separate CLI process.
+ *
+ * When no `harness` is provided in the constructor or per-run options, `CliAgent` falls back
+ * to the `PTBK_HARNESS` environment variable, mirroring `ptbk agent exec` behavior.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare class CliAgent {
+    private readonly options;
+    private temporaryAgentPath;
+    constructor(options: CliAgentOptions);
+    /**
+     * Runs one non-interactive agent turn through the selected harness.
+     *
+     * @param message - User message sent to the agent.
+     * @param options - Optional per-run overrides.
+     * @returns Final agent answer.
+     */
+    run(message: string, options?: CliAgentRunOptions): Promise<string>;
+    /**
+     * Resolves the agent path passed to the runner, materializing one temporary `.book` file when needed.
+     *
+     * @private internal utility of `CliAgent`
+     */
+    private resolveExecutableAgentPath;
+}

package/umd/src/book-3.0/CliAgent.test.d.ts

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

package/umd/src/book-3.0/LiteAgent.d.ts

@@ -0,0 +1,68 @@
+import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
+import type { ScriptExecutionTools } from '../execution/ScriptExecutionTools';
+import type { string_model_name } from '../types/string_model_name';
+import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
+/**
+ * Options for constructing one `LiteAgent`.
+ *
+ * `LiteAgent` is intentionally smaller than the CLI harnesses. It runs the Book through the
+ * OpenAI Agents SDK directly, while keeping Promptbook tool definitions and hosted knowledge
+ * whenever those features fit inside the lighter runtime.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type LiteAgentOptions = BookNodeAgentSourceOptions & {
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+    readonly createAgentModelRequirementsOptions?: CreateAgentModelRequirementsOptions;
+    readonly isVerbose?: boolean;
+    readonly maxRequestsPerMinute?: number;
+    readonly modelName?: string_model_name;
+    readonly organization?: string;
+    readonly project?: string;
+    readonly scriptExecutionTools?: ScriptExecutionTools | ReadonlyArray<ScriptExecutionTools>;
+    readonly userId?: string;
+};
+/**
+ * Per-run options for `LiteAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type LiteAgentRunOptions = {
+    readonly context?: string;
+    readonly signal?: AbortSignal;
+};
+/**
+ * Lightweight Node.js wrapper around the OpenAI Agents SDK for Promptbook Books.
+ *
+ * This path is intentionally simpler than `ptbk agent exec`: it prepares one SDK agent in-process
+ * and reuses it across calls, which keeps JavaScript integration small while still honoring the
+ * compiled Promptbook system message, prompt suffix, tools, and hosted knowledge when supported.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare class LiteAgent {
+    private readonly options;
+    private preparedAgentPromise;
+    constructor(options: LiteAgentOptions);
+    /**
+     * Runs one user message through the prepared OpenAI Agents SDK agent.
+     *
+     * @param message - User message sent to the agent.
+     * @param options - Optional context and cancellation signal.
+     * @returns Final text returned by the SDK agent.
+     */
+    run(message: string, options?: LiteAgentRunOptions): Promise<string>;
+    /**
+     * Lazily prepares and caches the underlying OpenAI Agents SDK runtime.
+     *
+     * @private internal utility of `LiteAgent`
+     */
+    private prepareAgent;
+    /**
+     * Builds the in-process OpenAI Agents SDK runtime from the Book source.
+     *
+     * @private internal utility of `LiteAgent`
+     */
+    private createPreparedAgent;
+}

package/umd/src/book-3.0/LiteAgent.test.d.ts

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

package/umd/src/book-3.0/agentFolderPaths.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Relative path to the local agent source used by the agent folder convention.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_BOOK_FILE_PATH = "agent.book";
+/**
+ * Relative path to the message queue root used by the agent folder convention.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_MESSAGES_DIRECTORY_PATH = "messages";
+/**
+ * Relative path to queued user messages consumed by the agent runner.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to answered messages written by the agent runner.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_FINISHED_MESSAGES_DIRECTORY_PATH: string;
+/**
+ * Relative path to messages that the agent runner stopped retrying.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const AGENT_FAILED_MESSAGES_DIRECTORY_PATH: string;

package/umd/src/book-3.0/cliAgentEnv.d.ts

@@ -0,0 +1,33 @@
+/**
+ * All CLI harness names supported by `CliAgent` and `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const CLI_AGENT_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+/**
+ * All supported thinking-level values for CLI coding-agent runners.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const CLI_AGENT_THINKING_LEVEL_VALUES: readonly ["low", "medium", "high", "xhigh", "max"];
+/**
+ * Environment variable used as the default runner identifier when `--harness` is omitted or not set in `CliAgent`.
+ *
+ * Set this to one of the harness names (`openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`)
+ * so that `CliAgent` and `ptbk agent exec` can run without an explicit `harness` option.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const PTBK_HARNESS_ENV = "PTBK_HARNESS";
+/**
+ * Environment variable used as the default runner model when `--model` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const PTBK_MODEL_ENV = "PTBK_MODEL";
+/**
+ * Environment variable used as the default thinking level when `--thinking-level` is omitted or not set in `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";

package/umd/src/book-components/BookEditor/BookEditor.d.ts

@@ -1,4 +1,4 @@
-import { CSSProperties } from 'react';
+import { type CSSProperties } from 'react';
 import type { Promisable } from 'type-fest';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
 import type { number_percent } from '../../types/number_percent';
@@ -6,6 +6,7 @@ import type { number_positive } from '../../types/number_positive';
 import type { string_knowledge_source_content } from '../../types/string_knowledge_source_content';
 import type { string_css_value } from '../../types/string_markdown';
 import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContext';
+import type { BookEditorTheme } from './BookEditorTheme';
 /**
  * Monaco diagnostic shown inside `BookEditor`.
  *
@@ -94,14 +95,14 @@ export type BookEditorProps = {
      */
     readonly style?: CSSProperties;
     /**
-     * Resolved visual theme used for the editor wrapper and Monaco instance.
+     * Resolved host application theme.
      *
-     * Host applications should pass the final light/dark theme instead of relying on
-     * browser media-query inference inside `<BookEditor/>`.
+     * `<BookEditor/>` accepts this for integration compatibility, but the notebook
+     * editor itself is intentionally rendered as light paper in every app theme.
      *
      * @default 'LIGHT'
      */
-    readonly theme?: 'LIGHT' | 'DARK';
+    readonly theme?: BookEditorTheme;
     /**
      * Height of the `BookEditor` component
      *

package/umd/src/book-components/BookEditor/BookEditorAboutPromptbookInformation.d.ts

@@ -0,0 +1,12 @@
+import type { AboutPromptbookInformationOptions } from '../../utils/misc/aboutPromptbookInformation';
+/**
+ * Browser-safe Promptbook information used by `BookEditor`.
+ *
+ * The shared `AboutPromptbookInformation` component renders markdown through the
+ * chat markdown pipeline, which has a server-side JSDOM sanitizer path. Keeping
+ * this component plain JSX prevents BookEditor from pulling JSDOM into client
+ * bundles.
+ *
+ * @private Internal component used by `BookEditorActionbar`
+ */
+export declare function BookEditorAboutPromptbookInformation(props?: AboutPromptbookInformationOptions): import("react/jsx-runtime").JSX.Element;

package/umd/src/book-components/BookEditor/BookEditorBrowserConfig.d.ts

@@ -0,0 +1,2 @@
+export { NAME, CLAIM, PROMPTBOOK_LEGAL_ENTITY, IS_COST_PREVENTED, DEFAULT_IS_VERBOSE, DEFAULT_MAX_CONCURRENT_UPLOADS, PROMPTBOOK_SYNTAX_COLORS, } from '../../config';
+export { PUBLIC_AGENTS_SERVERS } from '../../../servers';

package/umd/src/book-components/BookEditor/BookEditorForClient.d.ts

@@ -0,0 +1,7 @@
+import type { BookEditorProps } from './BookEditor';
+/**
+ * Renders a book editor
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function BookEditorForClient(props: BookEditorProps): import("react/jsx-runtime").JSX.Element;

package/umd/src/book-components/BookEditor/BookEditorMonacoTokenization.d.ts

@@ -15,9 +15,11 @@ type AgentReferenceMatch = {
  * @private function of BookEditorMonaco
  */
 export declare const BookEditorMonacoTokenization: {
+    DYNAMIC_COMMITMENT_REGEX: RegExp;
     AGENT_URL_REFERENCE_REGEX: RegExp;
     AGENT_REFERENCE_TOKEN_REGEX: RegExp;
     AGENT_REFERENCE_BRACED_REGEX: RegExp;
+    NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX: RegExp;
     AGENT_REFERENCE_HIGHLIGHT_REGEXES: readonly [RegExp, RegExp, RegExp];
     extractAgentReferenceValue: (token: string) => string;
     resolveAgentReferenceToUrl: (referenceValue: string) => string | null;