@promptbook/types 0.114.0-4 → 0.114.0-41

package/esm/src/utils/ascii-art/createAnsiColorCode.d.ts

@@ -0,0 +1,46 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+/**
+ * ANSI escape sequence that resets all colors and attributes.
+ *
+ * @private within the repository
+ */
+export declare const ANSI_RESET = "\u001B[0m";
+/**
+ * One opaque 24-bit color which should be written into an ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export type AnsiRgbColor = {
+    /**
+     * Red channel in the range `[0, 255]`.
+     */
+    readonly red: number;
+    /**
+     * Green channel in the range `[0, 255]`.
+     */
+    readonly green: number;
+    /**
+     * Blue channel in the range `[0, 255]`.
+     */
+    readonly blue: number;
+};
+/**
+ * Creates the ANSI escape code that sets the foreground color of following characters.
+ *
+ * @param color Color painted onto the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export declare function createAnsiForegroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;
+/**
+ * Creates the ANSI escape code that sets the background color of following characters.
+ *
+ * @param color Color painted behind the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export declare function createAnsiBackgroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;

package/esm/src/utils/files/findFilesByGlob.d.ts

@@ -0,0 +1,28 @@
+import { type GlobOptionsWithFileTypesUnset } from 'glob';
+import type { string_filename } from '../../types/string_filename';
+/**
+ * Options of `findFilesByGlob`
+ *
+ * Note: These are the options of `glob` itself, only `ignore` also accepts a readonly array
+ *       @see https://www.npmjs.com/package/glob#options
+ *
+ * @private internal type of `findFilesByGlob`
+ */
+export type FindFilesByGlobOptions = Omit<GlobOptionsWithFileTypesUnset, 'ignore'> & {
+    /**
+     * Glob patterns which are excluded from the result
+     */
+    readonly ignore?: string | ReadonlyArray<string>;
+};
+/**
+ * Finds all filenames matching a glob pattern
+ *
+ * Note: This is the single place where `glob` is used, so that every caller gets the same shape of results
+ *       on every operating system - POSIX separators and a stable order - which `glob` itself does not guarantee
+ *
+ * @param pattern Glob pattern to match, for example `./src/**\/*.ts`
+ * @param options Options passed to `glob`
+ * @returns Matching filenames with `/` separators, sorted alphabetically
+ * @private within the repository
+ */
+export declare function findFilesByGlob(pattern: string, options?: FindFilesByGlobOptions): Promise<Array<string_filename>>;

package/esm/src/utils/misc/debounce.d.ts

@@ -1,7 +1,9 @@
 import type { TODO_any } from '../organization/TODO_any';
 /**
- * Handles debounce.
+ * Creates a debounced function that runs after calls have been quiet for the given delay.
  *
  * @public exported from `@promptbook/utils`
  */
-export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;
+export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};

package/esm/src/utils/misc/debounce.test.d.ts

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

package/esm/src/utils/misc/emojis.d.ts

@@ -10,9 +10,10 @@ import type { string_char_emoji } from '../../types/typeAliasEmoji';
  */
 export declare const EMOJIS_IN_CATEGORIES: Record<string, ReadonlyArray<string_char_emoji>>;
 /**
- * All possible emoji chars like "🍆", "🍡", "🍤"...
+ * Curated repository catalogue of emoji and legacy pictographic symbols.
  *
- * @deprecated Use /\p{Extended_Pictographic}/ instead
+ * Code that needs to generate a valid Unicode emoji should apply its own validation
+ * to this catalogue rather than assume every entry is an emoji.
  *
  * @private within the repository
  */

package/esm/src/utils/random/$generateBookBoilerplate.test.d.ts

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

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.114.0-3`).
+ * It follows semantic versioning (e.g., `0.114.0-40`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/types",
-    "version": "0.114.0-4",
+    "version": "0.114.0-41",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,
@@ -90,12 +90,9 @@
         "node": ">=18.18.0",
         "npm": ">=8.0.0"
     },
-    "overrides": {
-        "zod": "$zod"
-    },
     "types": "./esm/src/_packages/types.index.d.ts",
     "typings": "./esm/src/_packages/types.index.d.ts",
     "peerDependencies": {
-        "@promptbook/core": "0.114.0-4"
+        "@promptbook/core": "0.114.0-41"
     }
 }

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

@@ -70,8 +70,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import { parseMessageButtons } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import { ArrowIcon } from '../book-components/icons/ArrowIcon';
 import { MicIcon } from '../book-components/icons/MicIcon';
@@ -159,8 +161,10 @@ export type { CitationLabelResolver };
 export type { MessageButton };
 export { parseMessageButtons };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export { ArrowIcon };
 export { MicIcon };

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

@@ -62,8 +62,10 @@ import type { CitationLabelResolver } from '../book-components/Chat/types/Citati
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
 import type { MarkdownInlineReference } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceIcon } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuStatus } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenuOption } from '../book-components/Chat/utils/renderMarkdown';
+import type { MarkdownInlineReferenceMenuAction } from '../book-components/Chat/utils/renderMarkdown';
 import type { MarkdownInlineReferenceMenu } from '../book-components/Chat/utils/renderMarkdown';
 import type { TeamToolResult } from '../book-components/Chat/utils/toolCallParsing/TeamToolResult';
 import type { QrCodeOptions } from '../book-components/Qr/useQrCode';
@@ -511,8 +513,10 @@ export type { CitationLabelResolver };
 export type { ParsedCitation };
 export type { MessageButton };
 export type { MarkdownInlineReference };
+export type { MarkdownInlineReferenceIcon };
 export type { MarkdownInlineReferenceMenuStatus };
 export type { MarkdownInlineReferenceMenuOption };
+export type { MarkdownInlineReferenceMenuAction };
 export type { MarkdownInlineReferenceMenu };
 export type { TeamToolResult };
 export type { QrCodeOptions };

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

@@ -0,0 +1,80 @@
+import type { AsciiArtColorDepth } from '../utils/ascii-art/convertImageDataToAsciiArt';
+import type { ResolvedAvatarRenderDefinition } from './renderAvatarVisual';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarSurfaceStyle, AvatarVisualId, AvatarVisualTerminalTextGrid } from './types/AvatarVisualDefinition';
+/**
+ * Options shared by the terminal-text avatar renderers.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextOptions = {
+    /**
+     * Stable visual identity of the rendered agent avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+    /**
+     * Built-in avatar visual to render, the same one used on the website.
+     */
+    readonly visualId: AvatarVisualId;
+    /**
+     * Surface used to derive the avatar palette.
+     *
+     * @default 'framed'
+     */
+    readonly surface?: AvatarSurfaceStyle;
+    /**
+     * Output width in terminal character cells.
+     */
+    readonly columns: number;
+    /**
+     * Output height in terminal character cells.
+     */
+    readonly rows: number;
+    /**
+     * Animation timestamp for animated visuals.
+     */
+    readonly timeMs: number;
+    /**
+     * Optional stable render data reused across frames.
+     */
+    readonly resolvedAvatarRenderDefinition?: ResolvedAvatarRenderDefinition;
+};
+/**
+ * Options for `renderAvatarVisualTerminalTextLines`.
+ *
+ * @private within the repository
+ */
+export type RenderAvatarVisualTerminalTextLinesOptions = RenderAvatarVisualTerminalTextOptions & {
+    /**
+     * Color depth of the emitted ANSI escape codes.
+     *
+     * @default 'TRUE_COLOR'
+     */
+    readonly colorDepth?: AsciiArtColorDepth;
+};
+/**
+ * Renders one frame of a character-based avatar visual straight into terminal character cells.
+ *
+ * Visuals which are themselves made of characters, for example `AsciiOctopus`, lose their identity
+ * when they are rasterized onto a canvas and converted back into half-block ASCII art - every glyph
+ * is averaged away into a colored blob. Such visuals expose `renderTerminalText`, which paints the
+ * terminal grid directly and is used instead of the raster pipeline.
+ *
+ * The square avatar is centered inside the requested grid the same way `renderAvatarVisualAsciiArt`
+ * centers the avatar canvas inside a wider terminal frame.
+ *
+ * @param options Avatar identity, visual selection, and output grid size.
+ * @returns Grid of `rows` rows of `columns` cells, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualTerminalTextGrid(options: RenderAvatarVisualTerminalTextOptions): AvatarVisualTerminalTextGrid | null;
+/**
+ * Renders one frame of a character-based avatar visual into ANSI-colored terminal lines.
+ *
+ * @param options Avatar identity, visual selection, output grid size, and ANSI color depth.
+ * @returns One ANSI-colored string per output row, or `null` when the visual has no terminal renderer.
+ *
+ * @private within the repository
+ */
+export declare function renderAvatarVisualTerminalTextLines(options: RenderAvatarVisualTerminalTextLinesOptions): ReadonlyArray<string> | null;

package/umd/src/avatars/renderAvatarVisualTerminalText.test.d.ts

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

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

@@ -72,6 +72,52 @@ export type AvatarVisualRenderContext = {
  * @private shared contract for the avatar rendering system
  */
 export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
+/**
+ * One painted character cell of a terminal-text avatar frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextCell = {
+    /**
+     * Single character painted in the cell.
+     */
+    readonly character: string;
+    /**
+     * Color of the character as a CSS color string, optionally with an alpha channel.
+     */
+    readonly color: string_color;
+};
+/**
+ * One rendered terminal-text avatar frame as a grid of character cells.
+ *
+ * Rows are ordered top to bottom, cells left to right, and `null` leaves the terminal background visible.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextGrid = ReadonlyArray<ReadonlyArray<AvatarVisualTerminalTextCell | null>>;
+/**
+ * Rendering context forwarded to a terminal-text avatar visual.
+ *
+ * Unlike `AvatarVisualRenderContext` this carries no canvas, because the visual paints
+ * character cells of a fixed terminal grid instead of pixels.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalTextRenderContext = {
+    readonly columns: number;
+    readonly rows: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+    readonly interaction: AvatarInteractionState;
+};
+/**
+ * Signature of one terminal-text avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualTerminalText = (context: AvatarVisualTerminalTextRenderContext) => AvatarVisualTerminalTextGrid;
 /**
  * Metadata and renderer for one built-in avatar visual.
  *
@@ -84,6 +130,14 @@ export type AvatarVisualDefinition = {
     readonly isAnimated: boolean;
     readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
+    /**
+     * Optional native terminal renderer of visuals which are themselves made of characters.
+     *
+     * Character-based visuals lose their identity when they are rasterized onto a canvas and
+     * converted back into half-block ASCII art, so they paint the terminal character grid directly.
+     * Visuals without this renderer are rasterized through `renderAvatarVisualAsciiArt` instead.
+     */
+    readonly renderTerminalText?: AvatarVisualTerminalText;
 };
 /**
  * Props of the shared `<Avatar/>` component.

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

@@ -0,0 +1,45 @@
+import type { BookCommitment } from '../../commitments/_base/BookCommitment';
+import type { AgentReferenceResolver } from './AgentReferenceResolver';
+/**
+ * Structured issue captured when compact agent reference resolution fails.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceResolutionIssue = {
+    /**
+     * Commitment where the unresolved token appeared.
+     */
+    readonly commitmentType: BookCommitment;
+    /**
+     * Original token text (for example `{Unknown Agent}` or `@UnknownAgent`).
+     */
+    readonly token: string;
+    /**
+     * Normalized token payload used for lookup.
+     */
+    readonly reference: string;
+    /**
+     * Human-readable explanation of why the token could not be resolved.
+     */
+    readonly message: string;
+};
+/**
+ * Extension implemented by resolvers that can expose accumulated resolution issues.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type IssueTrackingAgentReferenceResolver = AgentReferenceResolver & {
+    /**
+     * Returns tracked issues and clears the internal queue.
+     */
+    consumeResolutionIssues(): Array<AgentReferenceResolutionIssue>;
+};
+/**
+ * Drains unresolved compact-reference issues from a resolver when supported.
+ *
+ * @param resolver - Resolver instance that may implement issue tracking.
+ * @returns Collected issues or an empty list.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export declare function consumeAgentReferenceResolutionIssues(resolver?: AgentReferenceResolver): Array<AgentReferenceResolutionIssue>;

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

@@ -1,5 +1,6 @@
 import type { ParsedCommitment } from '../../commitments/_base/ParsedCommitment';
 import type { string_agent_name } from '../../types/string_agent_name';
+import type { ParsedUnknownCommitment } from './ParsedUnknownCommitment';
 /**
  * Result of parsing agent source for commitments
  *
@@ -18,6 +19,10 @@ export type AgentSourceParseResult = {
      * All parsed commitments
      */
     commitments: ParsedCommitment[];
+    /**
+     * Uppercase commitment blocks whose types are not registered by Promptbook.
+     */
+    unknownCommitments: ParsedUnknownCommitment[];
     /**
      * Lines that are not commitments (for system message)
      */

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

@@ -0,0 +1,26 @@
+/**
+ * An uppercase Book commitment block whose keyword is not registered by Promptbook.
+ *
+ * Unknown commitments are retained as system-message context instead of being applied
+ * as executable commitments.
+ *
+ * @private internal type of `parseAgentSourceWithCommitments`
+ */
+export type ParsedUnknownCommitment = {
+    /**
+     * Uppercase unknown commitment type, for example `FOO` or `BAR BZZ`.
+     */
+    readonly type: string;
+    /**
+     * Original first line, retained for precise editor diagnostics.
+     */
+    readonly originalLine: string;
+    /**
+     * Line number in the agent source (1-based).
+     */
+    readonly lineNumber: number;
+    /**
+     * Complete unknown commitment block, including its keyword and continuation lines.
+     */
+    readonly source: string;
+};

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

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

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

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

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

@@ -0,0 +1,14 @@
+/**
+ * Removes duplicated instructions from a generated system message
+ *
+ * Commitments are applied one by one, so a commitment used multiple times in one book repeats its whole
+ * section, including the shared guidance preamble. For example two `WRITING RULES` commitments emit the
+ * `## Writing rules` heading and its guidance paragraph twice. This function merges all sections sharing
+ * one heading into the position of their first occurrence and keeps every identical block only once.
+ *
+ * @param systemMessage The assembled system message which may contain repeated sections and blocks
+ * @returns The system message where each section heading and each identical block appears exactly once
+ *
+ * @private internal utility of `createAgentModelRequirementsWithCommitments`
+ */
+export declare function deduplicateSystemMessage(systemMessage: string): string;

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

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

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

@@ -0,0 +1,62 @@
+import type { string_book } from './string_book';
+/**
+ * One explicit `FROM` commitment written in a book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export type ExplicitFromCommitment = {
+    /**
+     * Zero-based index of the line the commitment was found on, within the scanned lines.
+     */
+    readonly lineIndex: number;
+    /**
+     * Trimmed commitment content, empty string for a blank `FROM`.
+     */
+    readonly content: string;
+};
+/**
+ * Collects every explicit single-line `FROM` commitment of one book.
+ *
+ * This lightweight parser is intentionally limited to the subset needed by inheritance
+ * resolution so it stays safe to bundle into the Next.js proxy path.
+ *
+ * @param sourceLines - Book source already split into lines.
+ * @returns Found `FROM` commitments in source order, empty when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function collectExplicitFromCommitments(sourceLines: ReadonlyArray<string>): ReadonlyArray<ExplicitFromCommitment>;
+/**
+ * Returns the effective explicit `FROM` commitment of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns The last explicit `FROM` commitment, or `undefined` when the book declares no parent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function getEffectiveExplicitFromCommitment(agentSource: string_book): ExplicitFromCommitment | undefined;
+/**
+ * Returns the effective explicit `FROM` commitment content of one book.
+ *
+ * A book may repeat `FROM`, in which case the last one wins and overrides every earlier one.
+ *
+ * @param agentSource - Raw book source.
+ * @returns Trimmed commitment content, empty string for a blank explicit `FROM`, or `undefined` when `FROM` is absent.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function getExplicitFromCommitmentContent(agentSource: string_book): string | undefined;
+/**
+ * Returns true when one book declares no parent at all and therefore implicitly inherits from `@Adam`.
+ *
+ * Writing no `FROM` commitment is equivalent to writing `FROM @Adam`, so only an explicit
+ * `FROM @Null` / `FROM {Void}` turns the inheritance off.
+ *
+ * @param agentSource - Raw book source.
+ * @returns True when the implicit `@Adam` ancestor applies to this book.
+ *
+ * @private utility of Agents Server inheritance resolution
+ */
+export declare function isImplicitAdamInheritance(agentSource: string_book): boolean;

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

@@ -0,0 +1,32 @@
+/**
+ * Matched compact agent reference token inside commitment content.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export type AgentReferenceTokenMatch = {
+    /**
+     * Original token text, for example `{Agent Name}` or `@AgentId`.
+     */
+    readonly token: string;
+    /**
+     * Token payload used for lookup.
+     */
+    readonly reference: string;
+    /**
+     * Zero-based character offset of `token` in the scanned content.
+     */
+    readonly index: number;
+    /**
+     * Length of `token` in characters.
+     */
+    readonly length: number;
+};
+/**
+ * Extracts compact agent-reference tokens from commitment content.
+ *
+ * @param content - Commitment content to inspect.
+ * @returns Matched compact reference tokens.
+ *
+ * @private internal utility of agent reference resolution
+ */
+export declare function extractAgentReferenceTokens(content: string): Array<AgentReferenceTokenMatch>;

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

@@ -0,0 +1,19 @@
+/**
+ * Creates the regex used to recognize the uppercase commitment type at the beginning of a Book line.
+ *
+ * A fresh regular expression keeps Monaco tokenizer state isolated from parser calls.
+ *
+ * @returns Regular expression matching one Book commitment-like line.
+ *
+ * @private internal utility of Book parsing and `<BookEditor/>`
+ */
+export declare function createBookCommitmentLineTypeRegex(): RegExp;
+/**
+ * Extracts the uppercase commitment type from a Book line, including types not registered by Promptbook.
+ *
+ * @param line - One raw Book source line.
+ * @returns Matched commitment type or `null` when the line does not begin with commitment syntax.
+ *
+ * @private internal utility of Book parsing and `<BookEditor/>`
+ */
+export declare function getBookCommitmentLineType(line: string): string | null;

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

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

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

@@ -0,0 +1,73 @@
+import type { string_agent_url } from '../../types/string_agent_url';
+import type { string_book } from './string_book';
+import type { AgentReferenceResolver } from './AgentReferenceResolver';
+/**
+ * Shared options for resolving one agent source with inheritance and imports applied.
+ *
+ * @private internal utility of agent source resolution
+ */
+export type ResolveInheritedAgentSourceOptions = {
+    /** Current recursion depth, forwarded to the source importer. */
+    readonly recursionLevel?: number;
+    /**
+     * The URL of the Adam agent to use as the default ancestor
+     *
+     * @default 'https://core.ptbk.io/agents/adam'
+     */
+    readonly adamAgentUrl?: string_agent_url;
+    /**
+     * Custom resolver used to expand compact agent references.
+     */
+    readonly agentReferenceResolver?: AgentReferenceResolver;
+    /**
+     * Canonical URL of the currently resolved agent.
+     */
+    readonly currentAgentUrl?: string_agent_url;
+    /**
+     * Additional equivalent URLs that should be treated as the current agent while detecting cycles.
+     */
+    readonly currentAgentAliases?: ReadonlyArray<string_agent_url>;
+    /**
+     * Already visited agent URLs in the current resolution stack.
+     */
+    readonly inheritancePath?: ReadonlyArray<string_agent_url>;
+    /**
+     * Source importer supplied by the host application.
+     */
+    readonly agentSourceImporter: AgentSourceImporter;
+};
+/**
+ * Context passed to a custom agent source importer.
+ *
+ * @private internal utility of agent source resolution
+ */
+export type AgentSourceImporterContext = {
+    /**
+     * Commitment that requested the imported source.
+     */
+    readonly commitmentType: 'FROM' | 'IMPORT';
+    /**
+     * Import options propagated from the current resolution pass.
+     */
+    readonly importAgentOptions: {
+        readonly recursionLevel?: number;
+        readonly inheritancePath?: ReadonlyArray<string_agent_url>;
+    };
+};
+/**
+ * Loads and recursively resolves one referenced agent using the caller's transport.
+ *
+ * @private internal utility of agent source resolution
+ */
+export type AgentSourceImporter = (agentUrl: string_agent_url, context: AgentSourceImporterContext) => Promise<string_book>;
+/**
+ * Resolves agent source with inheritance (FROM commitment)
+ *
+ * It recursively fetches the parent agent source and merges it with the current source.
+ *
+ * @param agentSource The initial agent source
+ * @returns The resolved agent source with inheritance applied
+ *
+ * @private internal utility of agent source resolution
+ */
+export declare function resolveInheritedAgentSource(agentSource: string_book, options: ResolveInheritedAgentSourceOptions): Promise<string_book>;

package/umd/src/book-2.0/book-language-documentation/getSafeCodeBlock.d.ts

@@ -5,6 +5,6 @@
  * @param language - Optional info-string language label.
  * @returns Fenced code block.
  *
- * @private internal utility of `createStandaloneBookLanguageMarkdown`
+ * @private internal utility of `createStandaloneBookLanguageMarkdown` and of the `ptbk coder` run traces
  */
 export declare function getSafeCodeBlock(content: string, language?: string): string;