@promptbook/types 0.112.0-99 → 0.112.0

package/esm/src/cli/cli-commands/coder/find-unwritten.d.ts

@@ -0,0 +1,10 @@
+import { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder find-unwritten` 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 $initializeCoderFindUnwrittenCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/coder/initializeCoderProjectConfiguration.d.ts

@@ -9,6 +9,8 @@ export type CoderInitializationSummary = {
     readonly promptsDoneDirectoryStatus: InitializationStatus;
     readonly promptsTemplatesDirectoryStatus: InitializationStatus;
     readonly promptTemplateFileStatuses: ReadonlyArray<EnsuredCoderPromptTemplateFile>;
+    readonly agentsDirectoryStatus: InitializationStatus;
+    readonly developerAgentFileStatus: InitializationStatus;
     readonly agentsFileStatus: InitializationStatus;
     readonly agentCodingFileStatus: InitializationStatus;
     readonly envFileStatus: InitializationStatus;

package/esm/src/cli/cli-commands/coder/server.d.ts

@@ -0,0 +1,13 @@
+import { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `coder server` command for Promptbook CLI utilities.
+ *
+ * Runs the same prompt processing logic as `ptbk coder run` but keeps the process alive
+ * and serves a kanban web UI on the configured port.
+ *
+ * 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 $initializeCoderServerCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/coder/waitOptions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Default wait duration applied before retrying a prompt round after an error (10 minutes).
+ *
+ * @private internal constant of `ptbk coder` wait handling
+ */
+export declare const DEFAULT_WAIT_AFTER_ERROR_MS: number;
+/**
+ * Parses an optional Commander duration string and returns the resolved milliseconds.
+ *
+ * Returns `defaultMs` when the flag was not provided or was provided without a non-empty value.
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export declare function parseOptionalWaitDuration(value: string | undefined, defaultMs: number): number;

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

@@ -1,42 +1,26 @@
 import { Command as Program } from 'commander';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
+import { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV } from '../../../book-3.0/cliAgentEnv';
+export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 /**
  * 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"];
-/**
- * Environment variable used as the default runner identifier when `--agent` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare const PTBK_AGENT_ENV = "PTBK_AGENT";
-/**
- * Environment variable used as the default runner model when `--model` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare const PTBK_MODEL_ENV = "PTBK_MODEL";
-/**
- * Environment variable used as the default runner thinking level when `--thinking-level` is omitted.
- *
- * @private internal utility of `promptbookCli`
- */
-export declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";
+export declare const PROMPT_RUNNER_HARNESS_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];
+export type PromptRunnerHarnessName = (typeof PROMPT_RUNNER_HARNESS_NAMES)[number];
 /**
  * Commander option bag for shared runner flags.
  *
  * @private internal utility of `promptbookCli`
  */
 export type PromptRunnerCliOptions = {
-    readonly agent?: string;
+    readonly harness?: string;
     readonly model?: string;
     readonly ui: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -52,14 +36,14 @@ export type PromptRunnerCliOptions = {
  *
  * @private internal utility of `promptbookCli`
  */
-export type PromptRunnerSelectionCliOptions = Pick<PromptRunnerCliOptions, 'agent' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'>;
+export type PromptRunnerSelectionCliOptions = Pick<PromptRunnerCliOptions, 'harness' | 'model' | 'ui' | 'thinkingLevel' | 'allowCredits'>;
 /**
  * Normalized runner options used by runner-backed CLI commands.
  *
  * @private internal utility of `promptbookCli`
  */
 export type NormalizedPromptRunnerCliOptions = {
-    readonly agentName?: PromptRunnerAgentName;
+    readonly agentName?: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;
@@ -83,11 +67,11 @@ export type NormalizedPromptRunnerSelectionCliOptions = Pick<NormalizedPromptRun
  */
 export declare const PROMPT_RUNNER_DESCRIPTION: string;
 /**
- * Commander description for the `--agent` option.
+ * Commander description for the `--harness` 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)";
+export declare const PROMPT_RUNNER_HARNESS_OPTION_DESCRIPTION = "Select runner: openai-codex, github-copilot, cline, claude-code, opencode, gemini (required for non-dry-run)";
 /**
  * Commander description for the `--model` option.
  *

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

@@ -60,6 +60,28 @@ export declare class AgentCollectionInSupabase {
      * Gets all agents in the collection
      */
     listAgents(): Promise<ReadonlyArray<AgentBasicInformation>>;
+    /**
+     * Finds one active agent profile by its human-readable name or permanent id.
+     *
+     * This keeps route-level lookups from loading the whole agent collection when only
+     * one canonical route identifier is needed.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier.
+     * @returns Matching active agent profile or `null` when not found.
+     *
+     * @public exported from `@promptbook/core`
+     */
+    findAgentBasicInformation(agentNameOrPermanentId: string_agent_name | string_agent_permanent_id): Promise<AgentBasicInformation | null>;
+    /**
+     * Converts one database row into public agent information.
+     *
+     * @param row - Database row carrying the persisted profile snapshot.
+     * @param isVerbose - Whether profile-name mismatches should be logged.
+     * @returns Agent profile with canonical database name and permanent id.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private mapAgentBasicInformationRow;
     /**
      * Retrieves the permanent ID of an agent by its name or permanent ID.
      */

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

@@ -26,7 +26,15 @@ export type TeamInternalAgentAccessHeadersOptions = {
 /**
  * Resolves the internal token used by same-server TEAM calls.
  *
- * @returns Hashed token, or `null` when the server does not have a private secret.
+ * `PROMPTBOOK_TEAM_AGENT_ACCESS_TOKEN` must be a dedicated secret — falling
+ * back to `ADMIN_PASSWORD`, `SUPABASE_SERVICE_ROLE_KEY`, or any other shared
+ * credential would let a leak of one secret compromise both authentication
+ * boundaries (admin login and same-server teammate-agent access). When the
+ * dedicated variable is missing, this function returns `null` so the calling
+ * server fails closed — same-server TEAM access is disabled and no header is
+ * sent — instead of silently authorizing requests with the wrong secret.
+ *
+ * @returns Hashed token, or `null` when the dedicated secret is not configured.
  *
  * @private internal Agents Server access wiring
  */

package/esm/src/llm-providers/_common/register/$provideLlmToolsConfigurationFromEnv.d.ts

@@ -6,7 +6,7 @@ import type { LlmToolsConfiguration } from './LlmToolsConfiguration';
  *
  * It looks for environment variables:
  * - `process.env.OPENAI_API_KEY`
- * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
+ * - `process.env.ANTHROPIC_API_KEY` (or the deprecated `process.env.ANTHROPIC_CLAUDE_API_KEY`)
  * - ...
  *
  * @see Environment variables documentation or .env file for required variables.

package/esm/src/llm-providers/_common/register/$provideLlmToolsFromEnv.d.ts

@@ -13,7 +13,7 @@ import type { CreateLlmToolsFromConfigurationOptions } from './createLlmToolsFro
  *
  * It looks for environment variables:
  * - `process.env.OPENAI_API_KEY`
- * - `process.env.ANTHROPIC_CLAUDE_API_KEY`
+ * - `process.env.ANTHROPIC_API_KEY` (or the deprecated `process.env.ANTHROPIC_CLAUDE_API_KEY`)
  * - ...
  *
  * @param options Configuration options for the LLM tools

package/esm/src/scrapers/website/utils/createShowdownConverter.d.ts

@@ -1,7 +1,7 @@
-import { Converter as ShowdownConverter } from 'showdown';
+import showdown from 'showdown';
 /**
  * Create a new showdown converter instance
  *
  * @private utility of `WebsiteScraper`
  */
-export declare function createShowdownConverter(): ShowdownConverter;
+export declare function createShowdownConverter(): showdown.Converter;

package/esm/src/utils/isTimingSafeEqualString.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Compares two strings in constant time to prevent timing attacks.
+ *
+ * Plain JavaScript `===` / `!==` string comparisons short-circuit on the first
+ * byte that differs, which lets a remote attacker who can measure response
+ * timing recover the expected value one byte at a time. This helper performs
+ * the comparison through Node's `timingSafeEqual`, which always inspects every
+ * byte of the equal-length buffers.
+ *
+ * Returning `false` early when the byte lengths differ does not expose
+ * character content — only length — which is an acceptable trade-off, since
+ * `timingSafeEqual` requires equal-length buffers and length is typically not
+ * secret.
+ *
+ * `null` and `undefined` inputs are treated as non-matching so callers can
+ * forward raw request values (for example `request.headers.get(name)`) without
+ * an extra guard.
+ *
+ * @param candidate - Value supplied by the caller (for example a request header or cookie).
+ * @param expected - Value to compare against (for example a configured secret).
+ * @returns `true` when both values are strings of equal length with identical bytes.
+ *
+ * @private internal helper function
+ */
+export declare function isTimingSafeEqualString(candidate: string | null | undefined, expected: string | null | undefined): boolean;

package/esm/src/utils/validators/url/isValidAgentUrl.d.ts

@@ -8,6 +8,11 @@ import type { really_unknown } from '../../organization/really_unknown';
  * - `isValidAgentUrl` *(this one)* which tests just agent URL
  * - `isValidPipelineUrl` which tests just pipeline URL
  *
+ * Note: This is a pure structural validator and does not block private/internal network
+ * addresses. Callers that fetch the URL server-side from an untrusted network context must
+ * additionally apply the `assertSafeUrl` SSRF guard from the Agents Server before any
+ * outbound request.
+ *
  * @public exported from `@promptbook/utils`
  */
 export declare function isValidAgentUrl(url: really_unknown): url is string_agent_url;

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/types",
-    "version": "0.112.0-99",
+    "version": "0.112.0",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -96,6 +96,6 @@
     "types": "./esm/src/_packages/types.index.d.ts",
     "typings": "./esm/src/_packages/types.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.112.0-99"
+        "@promptbook/core": "0.112.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

@@ -221,7 +221,6 @@ 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 };
@@ -447,6 +446,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

@@ -4,6 +4,14 @@ import type { AgentBasicInformation } from '../book-2.0/agent-source/AgentBasicI
 import type { AgentModelRequirements } from '../book-2.0/agent-source/AgentModelRequirements';
 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 +55,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';
@@ -437,6 +446,14 @@ export type { AgentBasicInformation };
 export type { AgentModelRequirements };
 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 +497,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-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 {};