@promptbook/types 0.112.0-99 → 0.113.0-0

package/README.md

@@ -27,6 +27,25 @@ Create persistent AI agents that turn your company's scattered knowledge into ac
 
 
 
+### Standalone VPS
+
+Run the standalone VPS installer only on a fresh server. Interactive mode asks for the installation values:
+
+```bash
+sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash
+```
+
+Non-interactive mode takes defaults from command-line options. When `--openai-api-key` is provided with the default OpenAI Codex runner, the installer installs and configures Codex automatically; other runner authentication can be configured later from the UI or SSH:
+
+```bash
+sudo curl -fsSL https://raw.githubusercontent.com/webgptorg/promptbook/refs/heads/main/other/vps/install.sh | bash -s -- \
+    --non-interactive \
+    --yes-i-understand-that-script-should-be-run-on-fresh-server \
+    --domain my-server.com \
+    --openai-api-key sk-proj-xxx \
+    --admin-password xxx
+```
+
 
 
 <blockquote style="color: #ff8811">
@@ -308,7 +327,7 @@ Rest of the documentation is common for **entire promptbook ecosystem**:
 
 Promptbook lets you create **persistent AI agents** that work on real goals for your company. The [**Agents Server**](https://gallery.ptbk.io/) is the heart of the project - a place where your AI agents live, remember context, collaborate in teams, and get things done.
 
-Nowadays, the biggest challenge for most business applications isn't the raw capabilities of AI models. Large language models such as GPT-5.2 and Claude-4.5 are incredibly capable.
+Nowadays, the biggest challenge for most business applications isn't the raw capabilities of AI models. Large language models such as Claude Mythos, GPT-5.6 or Kimi K2.7 are incredibly capable.
 
 The main challenge lies in **managing the context**, providing rules and knowledge, and narrowing the personality.
 
@@ -316,17 +335,20 @@ In Promptbook, you define your agents **using simple Books** - a human-readable
 
 <table style="border: 1px solid #777; border-radius: 10px;"><tr><td>
 
-**<ins>Paul Smith</ins>**<br/>
+**<ins>Lawyer</ins>**<br/>
 <br/>
-**PERSONA** You are a company lawyer.<br/>
+GOAL You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email and keep the company website updated with the latest legal policies.<br/>
+Respond to incoming legal inquiries via email and keep the company website updated with the latest legal policies.<br/>
+<br/>
 **RULE** You are knowledgeable, professional, and detail-oriented.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-**USE EMAIL**<br/>
-**USE BROWSER**<br/>
-**TEAM** You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
+<br/>
+USE EMAIL<br/>
+USE BROWSER<br/>
+<br/>
+TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
 </td></tr></table>
 
@@ -359,12 +381,12 @@ Goals define what the agent should actively work toward. Unlike a chatbot that o
 
 <table style="border: 1px solid #777; border-radius: 10px;"><tr><td>
 
-**<ins>Paul Smith & Associés</ins>**<br/>
+**<ins>Company Lawyer</ins>**<br/>
 <br/>
-**PERSONA** You are a company lawyer.<br/>
+GOAL<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 
 </td></tr></table>
 
@@ -382,8 +404,8 @@ Promptbook Engine will automatically enforce this knowledge during interactions.
 <br/>
 **PERSONA** You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
 
@@ -401,8 +423,8 @@ Depending on rule strictness, Promptbook will either propagate it to the prompt
 <br/>
 **PERSONA** You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 **RULE** Always ensure compliance with local laws and regulations.<br/>
 **RULE** Never provide legal advice outside your area of expertise.<br/>
 **RULE** Never provide legal advice about criminal law.<br/>
@@ -423,16 +445,16 @@ These are what turn a chatbot into a persistent agent that actually does work.
 <br/>
 **PERSONA** You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 **RULE** Always ensure compliance with local laws and regulations.<br/>
 **RULE** Never provide legal advice outside your area of expertise.<br/>
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-**USE EMAIL**<br/>
-**USE BROWSER**<br/>
-**USE SEARCH ENGINE**<br/>
+USE EMAIL<br/>
+USE BROWSER<br/>
+USE SEARCH ENGINE<br/>
 
 </td></tr></table>
 
@@ -446,20 +468,22 @@ Team commitment allows you to define the team structure and advisory fellow memb
 <br/>
 **PERSONA** You are a company lawyer.<br/>
 Your job is to provide legal advice and support to the company and its employees.<br/>
-**GOAL** Respond to incoming legal inquiries via email within 24 hours.<br/>
-**GOAL** Keep the company website updated with the latest legal policies and compliance information.<br/>
+GOAL Respond to incoming legal inquiries via email within 24 hours.<br/>
+GOAL Keep the company website updated with the latest legal policies and compliance information.<br/>
 **RULE** Always ensure compliance with local laws and regulations.<br/>
 **RULE** Never provide legal advice outside your area of expertise.<br/>
 **RULE** Never provide legal advice about criminal law.<br/>
 **KNOWLEDGE** https://company.com/company-policies.pdf<br/>
 **KNOWLEDGE** https://company.com/internal-documents/employee-handbook.docx<br/>
-**USE EMAIL**<br/>
-**USE BROWSER**<br/>
-**USE SEARCH ENGINE**<br/>
-**TEAM** You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
+USE EMAIL<br/>
+USE BROWSER<br/>
+USE SEARCH ENGINE<br/>
+TEAM You are part of the legal team of Paul Smith & Associés, you discuss with {Emily White}, the head of the compliance department. {George Brown} is expert in corporate law and {Sophia Black} is expert in labor law.<br/>
 
 </td></tr></table>
 
+
+
 ### Promptbook Ecosystem
 
 Promptbook is an ecosystem of tools centered around the **Agents Server** - a production-ready platform for running persistent AI agents.
@@ -482,6 +506,8 @@ The [Promptbook Engine](https://github.com/webgptorg/promptbook) is the open-sou
 
 
 
+
+
 ## 💜 The Promptbook Project
 
 Promptbook project is an ecosystem centered around the **Agents Server** - a platform for creating, deploying, and running persistent AI agents. Following is a list of the most important pieces of the project:
@@ -519,6 +545,8 @@ Promptbook project is an ecosystem centered around the **Agents Server** - a pla
   </tbody>
 </table>
 
+
+
 ### 🌐 Community & Social Media
 
 Join our growing community of developers and users:
@@ -575,6 +603,8 @@ Join our growing community of developers and users:
 
 
 
+
+
 ## 📚 Documentation
 
 See detailed guides and API reference in the [docs](https://github.com/webgptorg/promptbook/discussions/categories/concepts) or [online](https://discord.gg/x3QWNaa89N).
@@ -666,9 +696,9 @@ Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treate
 #### Features
 
 -   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`
--   **Context injection:** `--context AGENTS.md` or inline extra instructions
+-   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
--   **Interactive or unattended runs:** default wait mode, or `--no-wait` for batch execution
+-   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
 -   **Git safety:** clean working tree check by default, optional `--ignore-git-changes`
 -   **Opt-in remote pushes:** commits stay local unless you explicitly pass `--auto-push`
 -   **Prompt triage:** `--priority` to process only more important tasks first
@@ -686,11 +716,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 --agent agents/coding/developer.book --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 --agent agents/coding/developer.book --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 --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -712,11 +742,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 --agent agents/coding/developer.book --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 --agent agents/coding/developer.book --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 --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes
 
 ptbk coder find-refactor-candidates
 
@@ -729,24 +759,24 @@ ptbk coder verify
 
 #### What each command does
 
-| Command                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
+| Command                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | ---- | ----- | ------------------------------------------------------------------------ |
 | `ptbk coder init`                     | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.promptbook`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
-| `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                  |
-| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                           |
-| `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                  | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
-| `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                             |
+| `ptbk coder generate-boilerplates`    | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root.                                                                                                                                                                                                                                                                         |
+| `ptbk coder run`                      | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, can optionally verify each attempt with a shell test command and feed failing output back for retries, then marks success or failure, commits the result, and pushes only when `--auto-push` is enabled.                                                                                                                                                                  |
+| `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <xlow                                                                                                                                                                                                                                                                                                                                                         | low | medium | high | xhigh | extreme>` ranges from a very benevolent scan to a very aggressive sweep. |
+| `ptbk coder verify`                   | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results.                                                                                                                                                                                                                                                                                                                                                    |
 
 #### Most useful `ptbk coder run` flags
 
 | 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.   |
 | `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                       |
-| `--no-wait`                | Skips interactive pauses between prompts for unattended execution.                                 |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue. |
 | `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                             |
 | `--priority <n>`           | Runs only prompts at or above the given priority.                                                  |
 | `--dry-run`                | Prints which prompts are ready instead of executing them.                                          |
@@ -758,8 +788,8 @@ ptbk coder verify
 
 1. Initialize once with `ptbk coder init`.
 2. Customize `prompts/templates/*.md` if needed, then create or write prompt files in `prompts/`.
-3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--context AGENTS.md`.
-4. Run one prompt at a time interactively, or use `--no-wait` for unattended batches.
+3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--agent agents/coding/developer.book --context AGENTS.md`.
+4. Run unattended batches by default, or pass `--no-auto` to confirm each prompt interactively.
 5. Finish with `ptbk coder verify` so resolved prompts are archived and broken ones get explicit repair follow-ups.
 
 
@@ -782,6 +812,8 @@ The following glossary is used to clarify certain concepts:
 
 _Note: This section is not a complete dictionary, more list of general AI / LLM terms that has connection with Promptbook_
 
+
+
 ### 💯 Core concepts
 
 -   [📚 Collection of pipelines](https://github.com/webgptorg/promptbook/discussions/65)

package/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/src/book-2.0/agent-source/agentSourceVisibility.test.d.ts

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