@promptbook/documents 0.112.0-111 → 0.112.0-113

package/README.md

@@ -443,11 +443,11 @@ npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompt
 
 npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompts/templates/agents-server.md
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --ignore-git-changes --no-wait
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --ignore-git-changes --no-wait
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -469,11 +469,11 @@ ptbk coder generate-boilerplates
 
 ptbk coder generate-boilerplates --template prompts/templates/common.md
 
-ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test
 
-ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --auto-push
 
-ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test --ignore-git-changes --no-wait
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --test npm run test --ignore-git-changes --no-wait
 
 ptbk coder find-refactor-candidates
 
@@ -498,7 +498,7 @@ ptbk coder verify
 
 | Flag                       | Purpose                                                                                            |
 | -------------------------- | -------------------------------------------------------------------------------------------------- |
-| `--agent <name>`           | Selects the coding backend.                                                                        |
+| `--harness <name>`         | Selects the coding harness.                                                                        |
 | `--model <model>`          | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`. |
 | `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                 |
 | `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.   |

package/esm/index.es.js

@@ -26,7 +26,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-111';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-113';
 /**
  * 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/node.index.d.ts

@@ -1,4 +1,14 @@
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../version';
+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 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 +22,16 @@ 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 type { BookNodeAgentSource };
+export type { BookNodeAgentSourceOptions };
+export type { CliAgentHarness };
+export type { CliAgentThinkingLevel };
+export type { CliAgentRunOptions };
+export type { CliAgentOptions };
+export { CliAgent };
+export type { LiteAgentOptions };
+export type { LiteAgentRunOptions };
+export { LiteAgent };
 export { createPipelineCollectionFromDirectory };
 export { getAllCommitmentsToolFunctionsForNode };
 export { $provideExecutablesForNode };

package/esm/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';
@@ -437,6 +445,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 };

package/esm/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?: 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/esm/src/book-3.0/CliAgent.d.ts

@@ -0,0 +1,68 @@
+import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
+/**
+ * CLI harness names supported by `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentHarness = 'openai-codex' | 'github-copilot' | 'cline' | 'claude-code' | 'opencode' | 'gemini';
+/**
+ * Thinking levels supported by CLI coding harnesses.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentThinkingLevel = 'low' | 'medium' | 'high' | 'xhigh';
+/**
+ * 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 model?: string;
+    readonly noUi?: boolean;
+    readonly thinkingLevel?: CliAgentThinkingLevel;
+};
+/**
+ * Constructor options for `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions & {
+    /**
+     * Executable used for the wrapper command.
+     *
+     * @default ptbk
+     */
+    readonly command?: string;
+};
+/**
+ * Lightweight JavaScript wrapper around `ptbk agent exec`.
+ *
+ * It uses the same CLI harnesses as Promptbook's agent command, making it the most faithful
+ * way to run a local Book agent from Node.js when you want the CLI execution flow.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare class CliAgent {
+    private readonly options;
+    private temporaryAgentPath;
+    constructor(options: CliAgentOptions);
+    /**
+     * Runs one non-interactive agent turn through `ptbk agent exec`.
+     *
+     * @param message - User message sent to the agent.
+     * @param options - Optional per-run CLI overrides.
+     * @returns Raw stdout emitted by the CLI command.
+     */
+    run(message: string, options?: CliAgentRunOptions): Promise<string>;
+    /**
+     * Resolves the agent path passed to the CLI, materializing one temporary `.book` file when needed.
+     *
+     * @private internal utility of `CliAgent`
+     */
+    private resolveExecutableAgentPath;
+}

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

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

package/esm/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/esm/src/book-3.0/LiteAgent.test.d.ts

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

package/esm/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/esm/src/cli/cli-commands/agent/agentCliOptions.d.ts

@@ -0,0 +1,29 @@
+import type { NormalizedPromptRunnerSelectionCliOptions, PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
+/**
+ * Commander option bag shared by `ptbk agent` subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export type AgentCommandCliOptions = PromptRunnerSelectionCliOptions & {
+    readonly agent?: string;
+    readonly context?: string;
+    readonly message?: string;
+};
+/**
+ * Normalizes shared runner flags for local agent subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function normalizeAgentCommandRunnerOptions(cliOptions: AgentCommandCliOptions): NormalizedPromptRunnerSelectionCliOptions;
+/**
+ * Returns the required agent book path from Commander options.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function resolveRequiredAgentPath(cliOptions: AgentCommandCliOptions): string;
+/**
+ * Returns the required single-turn user message from Commander options.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function resolveRequiredAgentMessage(cliOptions: AgentCommandCliOptions): string;

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

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

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

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent exec` 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 $initializeAgentExecCommand(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.d.ts

@@ -0,0 +1,14 @@
+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 runs one `.book` source directly through a selected CLI harness:
+ * - chat: Run an interactive terminal chat session
+ * - exec: Send one message and print the response
+ *
+ * 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/agents-server/startAgentsServer.d.ts

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
-import type { PromptRunnerAgentName } from '../common/promptRunnerCliOptions';
+import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import type { number_port } from '../../../types/number_positive';
 /**
  * Next runtime mode supported by the local Agents Server foreground launcher.
@@ -14,7 +14,7 @@ export type AgentsServerNextRuntimeMode = 'start' | 'dev';
  */
 export type StartAgentsServerOptions = {
     readonly port: number_port;
-    readonly agentName: PromptRunnerAgentName;
+    readonly agentName: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;

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

@@ -5,13 +5,13 @@ import type { ThinkingLevel } from '../coder/ThinkingLevel';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare const PROMPT_RUNNER_AGENT_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+export declare const PROMPT_RUNNER_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
 /**
- * Environment variable used as the default runner identifier when `--agent` is omitted.
+ * Environment variable used as the default runner identifier when `--harness` is omitted.
  *
  * @private internal utility of `promptbookCli`
  */
-export declare const PTBK_AGENT_ENV = "PTBK_AGENT";
+export declare const PTBK_HARNESS_ENV = "PTBK_HARNESS";
 /**
  * Environment variable used as the default runner model when `--model` is omitted.
  *
@@ -29,14 +29,14 @@ export declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";
  *
  * @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 +52,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 +83,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/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-110`).
+ * It follows semantic versioning (e.g., `0.112.0-112`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/documents",
-    "version": "0.112.0-111",
+    "version": "0.112.0-113",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -99,7 +99,7 @@
     "types": "./esm/src/_packages/documents.index.d.ts",
     "typings": "./esm/src/_packages/documents.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.112.0-111"
+        "@promptbook/core": "0.112.0-113"
     },
     "dependencies": {
         "colors": "1.4.0",

package/umd/index.umd.js

@@ -24,7 +24,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-111';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-113';
     /**
      * 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/node.index.d.ts

@@ -1,4 +1,14 @@
 import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../version';
+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 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 +22,16 @@ 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 type { BookNodeAgentSource };
+export type { BookNodeAgentSourceOptions };
+export type { CliAgentHarness };
+export type { CliAgentThinkingLevel };
+export type { CliAgentRunOptions };
+export type { CliAgentOptions };
+export { CliAgent };
+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';
@@ -437,6 +445,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 };

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?: 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,68 @@
+import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
+/**
+ * CLI harness names supported by `ptbk agent exec`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentHarness = 'openai-codex' | 'github-copilot' | 'cline' | 'claude-code' | 'opencode' | 'gemini';
+/**
+ * Thinking levels supported by CLI coding harnesses.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentThinkingLevel = 'low' | 'medium' | 'high' | 'xhigh';
+/**
+ * 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 model?: string;
+    readonly noUi?: boolean;
+    readonly thinkingLevel?: CliAgentThinkingLevel;
+};
+/**
+ * Constructor options for `CliAgent`.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export type CliAgentOptions = BookNodeAgentSourceOptions & CliAgentRunOptions & {
+    /**
+     * Executable used for the wrapper command.
+     *
+     * @default ptbk
+     */
+    readonly command?: string;
+};
+/**
+ * Lightweight JavaScript wrapper around `ptbk agent exec`.
+ *
+ * It uses the same CLI harnesses as Promptbook's agent command, making it the most faithful
+ * way to run a local Book agent from Node.js when you want the CLI execution flow.
+ *
+ * @public exported from `@promptbook/node`
+ */
+export declare class CliAgent {
+    private readonly options;
+    private temporaryAgentPath;
+    constructor(options: CliAgentOptions);
+    /**
+     * Runs one non-interactive agent turn through `ptbk agent exec`.
+     *
+     * @param message - User message sent to the agent.
+     * @param options - Optional per-run CLI overrides.
+     * @returns Raw stdout emitted by the CLI command.
+     */
+    run(message: string, options?: CliAgentRunOptions): Promise<string>;
+    /**
+     * Resolves the agent path passed to the CLI, 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-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/cli/cli-commands/agent/agentCliOptions.d.ts

@@ -0,0 +1,29 @@
+import type { NormalizedPromptRunnerSelectionCliOptions, PromptRunnerSelectionCliOptions } from '../common/promptRunnerCliOptions';
+/**
+ * Commander option bag shared by `ptbk agent` subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export type AgentCommandCliOptions = PromptRunnerSelectionCliOptions & {
+    readonly agent?: string;
+    readonly context?: string;
+    readonly message?: string;
+};
+/**
+ * Normalizes shared runner flags for local agent subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function normalizeAgentCommandRunnerOptions(cliOptions: AgentCommandCliOptions): NormalizedPromptRunnerSelectionCliOptions;
+/**
+ * Returns the required agent book path from Commander options.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function resolveRequiredAgentPath(cliOptions: AgentCommandCliOptions): string;
+/**
+ * Returns the required single-turn user message from Commander options.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function resolveRequiredAgentMessage(cliOptions: AgentCommandCliOptions): string;

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

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

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

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent exec` 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 $initializeAgentExecCommand(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.d.ts

@@ -0,0 +1,14 @@
+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 runs one `.book` source directly through a selected CLI harness:
+ * - chat: Run an interactive terminal chat session
+ * - exec: Send one message and print the response
+ *
+ * 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/agents-server/startAgentsServer.d.ts

@@ -1,5 +1,5 @@
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
-import type { PromptRunnerAgentName } from '../common/promptRunnerCliOptions';
+import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
 import type { number_port } from '../../../types/number_positive';
 /**
  * Next runtime mode supported by the local Agents Server foreground launcher.
@@ -14,7 +14,7 @@ export type AgentsServerNextRuntimeMode = 'start' | 'dev';
  */
 export type StartAgentsServerOptions = {
     readonly port: number_port;
-    readonly agentName: PromptRunnerAgentName;
+    readonly agentName: PromptRunnerHarnessName;
     readonly model?: string;
     readonly noUi: boolean;
     readonly thinkingLevel?: ThinkingLevel;

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

@@ -5,13 +5,13 @@ import type { ThinkingLevel } from '../coder/ThinkingLevel';
  *
  * @private internal utility of `promptbookCli`
  */
-export declare const PROMPT_RUNNER_AGENT_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
+export declare const PROMPT_RUNNER_HARNESS_NAMES: readonly ["openai-codex", "github-copilot", "cline", "claude-code", "opencode", "gemini"];
 /**
- * Environment variable used as the default runner identifier when `--agent` is omitted.
+ * Environment variable used as the default runner identifier when `--harness` is omitted.
  *
  * @private internal utility of `promptbookCli`
  */
-export declare const PTBK_AGENT_ENV = "PTBK_AGENT";
+export declare const PTBK_HARNESS_ENV = "PTBK_HARNESS";
 /**
  * Environment variable used as the default runner model when `--model` is omitted.
  *
@@ -29,14 +29,14 @@ export declare const PTBK_THINKING_LEVEL_ENV = "PTBK_THINKING_LEVEL";
  *
  * @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 +52,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 +83,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/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-110`).
+ * It follows semantic versioning (e.g., `0.112.0-112`).
  *
  * @generated
  */