@promptbook/color 0.105.0-3 → 0.105.0-31

package/esm/typings/src/book-components/Chat/effects/components/HeartsEffect.d.ts

@@ -0,0 +1,18 @@
+type HeartsEffectProps = {
+    /**
+     * Unique identifier for this effect instance
+     */
+    effectId: string;
+    /**
+     * Callback when the effect completes
+     */
+    onComplete?: () => void;
+};
+/**
+ * Hearts effect component
+ * Renders floating hearts that rise from the bottom of the screen
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function HeartsEffect(props: HeartsEffectProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/esm/typings/src/book-components/Chat/effects/configs/defaultEffectConfigs.d.ts

@@ -0,0 +1,7 @@
+import type { ChatEffectConfig } from '../types/ChatEffectConfig';
+/**
+ * Default effect configurations for common chat emojis
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare const defaultEffectConfigs: ReadonlyArray<ChatEffectConfig>;

package/esm/typings/src/book-components/Chat/effects/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Chat effects system exports
+ *
+ * @packageDocumentation
+ */
+export { ChatEffectsSystem } from './ChatEffectsSystem';
+export { ConfettiEffect } from './components/ConfettiEffect';
+export { HeartsEffect } from './components/HeartsEffect';
+export { defaultEffectConfigs } from './configs/defaultEffectConfigs';
+export type { ChatEffect } from './types/ChatEffect';
+export type { ChatEffectConfig } from './types/ChatEffectConfig';
+export type { ChatEffectsSystemProps } from './types/ChatEffectsSystemProps';
+export type { ChatEffectType } from './types/ChatEffectType';
+export { detectEffects } from './utils/detectEffects';
+/**
+ * TODO: !!!!! To rules: Do not create index files that re-ex-port from multiple files, import directly instead or use full register
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/book-components/Chat/effects/types/ChatEffect.d.ts

@@ -0,0 +1,20 @@
+import type { ChatEffectType } from './ChatEffectType';
+/**
+ * Represents a chat effect instance
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatEffect = {
+    /**
+     * Unique identifier for this effect instance
+     */
+    id: string;
+    /**
+     * Type of effect
+     */
+    type: ChatEffectType;
+    /**
+     * Timestamp when the effect was triggered
+     */
+    timestamp: number;
+};

package/esm/typings/src/book-components/Chat/effects/types/ChatEffectConfig.d.ts

@@ -0,0 +1,21 @@
+import type { ChatEffectType } from './ChatEffectType';
+/**
+ * Configuration for a chat effect trigger
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatEffectConfig = {
+    /**
+     * Emoji or pattern that triggers this effect
+     */
+    trigger: string | RegExp;
+    /**
+     * Type of effect to trigger
+     */
+    effectType: ChatEffectType;
+    /**
+     * Whether to match all heart emojis (❤️, 💙, 💚, etc.)
+     * Only relevant for heart effects
+     */
+    matchAllHeartEmojis?: boolean;
+};

package/esm/typings/src/book-components/Chat/effects/types/ChatEffectType.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Types of chat effects that can be triggered
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatEffectType = 'CONFETTI' | 'HEARTS';

package/esm/typings/src/book-components/Chat/effects/types/ChatEffectsSystemProps.d.ts

@@ -0,0 +1,32 @@
+import type { ChatSoundSystem } from '../../Chat/ChatProps';
+import type { ChatMessage } from '../../types/ChatMessage';
+import type { ChatEffectConfig } from './ChatEffectConfig';
+/**
+ * Props for the ChatEffectsSystem component
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatEffectsSystemProps = {
+    /**
+     * Array of chat messages to monitor for effect triggers
+     */
+    messages: ReadonlyArray<ChatMessage>;
+    /**
+     * Array of effect configurations
+     * Defines which emojis/patterns trigger which effects
+     */
+    effectConfigs: ReadonlyArray<ChatEffectConfig>;
+    /**
+     * Optional filter function to determine if a message should trigger effects
+     * By default, only agent messages trigger effects
+     */
+    shouldTriggerEffect?: (message: ChatMessage) => boolean;
+    /**
+     * CSS class name for the effects container
+     */
+    className?: string;
+    /**
+     * Optional sound system to play sounds when effects are triggered
+     */
+    soundSystem?: ChatSoundSystem;
+};

package/esm/typings/src/book-components/Chat/effects/utils/detectEffects.d.ts

@@ -0,0 +1,12 @@
+import type { ChatMessage } from '../../types/ChatMessage';
+import type { ChatEffectConfig } from '../types/ChatEffectConfig';
+import type { ChatEffectType } from '../types/ChatEffectType';
+/**
+ * Detects which effects should be triggered based on message content
+ *
+ * @param message - The chat message to analyze
+ * @param effectConfigs - Array of effect configurations
+ * @returns Array of unique effect types to trigger
+ * @private utility function of Effects system
+ */
+export declare function detectEffects(message: ChatMessage, effectConfigs: ReadonlyArray<ChatEffectConfig>): ChatEffectType[];

package/esm/typings/src/book-components/Chat/types/ChatMessage.d.ts

@@ -1,5 +1,7 @@
 import { Message } from '../../../types/Message';
+import type { ToolCall } from '../../../types/ToolCall';
 import type { id, string_markdown } from '../../../types/typeAliases';
+export type ChatToolCall = ToolCall;
 /**
  * Represents a single message within a chat interface.
  *
@@ -33,6 +35,20 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
      * Indicates if the message was sent via a voice call
      */
     isVoiceCall?: boolean;
+    /**
+     * Optional tool calls made during the execution
+     */
+    readonly ongoingToolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Optional tool calls used to produce this message.
+     */
+    readonly toolCalls?: ReadonlyArray<ChatToolCall>;
+    /**
+     * Optional tool calls that have been completed
+     *
+     * @deprecated Use `toolCalls` instead.
+     */
+    readonly completedToolCalls?: ReadonlyArray<ChatToolCall>;
     /**
      * Optional file attachments
      */
@@ -50,6 +66,27 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
          */
         url: string;
     }>;
+    /**
+     * Optional source citations/annotations (from RAG systems like OpenAI Assistants)
+     */
+    readonly citations?: ReadonlyArray<{
+        /**
+         * The unique identifier for the citation (e.g., "5:13")
+         */
+        id: string;
+        /**
+         * The source document name (e.g., "document.pdf")
+         */
+        source: string;
+        /**
+         * Optional URL to the source document
+         */
+        url?: string;
+        /**
+         * Optional preview/excerpt from the source
+         */
+        excerpt?: string;
+    }>;
 };
 /**
  * TODO: Make all fields readonly

package/esm/typings/src/book-components/Chat/utils/createTeamToolNameFromUrl.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Builds a TEAM tool name from a teammate agent URL.
+ *
+ * @private utility of chat components
+ */
+export declare function createTeamToolNameFromUrl(url: string): string;
+/**
+ * Checks whether a tool name belongs to a TEAM tool.
+ *
+ * @private utility of chat components
+ */
+export declare function isTeamToolName(name: string): boolean;

package/esm/typings/src/book-components/Chat/utils/getToolCallChipletText.d.ts

@@ -0,0 +1,40 @@
+import type { ToolCall } from '../../../types/ToolCall';
+import type { AgentChipData } from '../AgentChip';
+/**
+ * Utility to format tool call information for user-friendly display.
+ */
+/**
+ * Tool call chiplet information including agent data for team tools
+ */
+export type ToolCallChipletInfo = {
+    /**
+     * Display text for the chiplet
+     */
+    text: string;
+    /**
+     * Agent data for team tools (if applicable)
+     */
+    agentData?: AgentChipData;
+};
+/**
+ * Technical to user-friendly tool names and emojis
+ *
+ * @private [🧠] Maybe public?
+ */
+export declare const TOOL_TITLES: Record<string, {
+    title: string;
+    emoji: string;
+}>;
+/**
+ * Gets the user-friendly text for a tool call chiplet.
+ *
+ * @deprecated Use getToolCallChipletInfo instead which returns both text and agent data
+ * @private [🧠] Maybe public?
+ */
+export declare function getToolCallChipletText(toolCall: ToolCall): string;
+/**
+ * Gets the chiplet information including text and agent data (for team tools).
+ *
+ * @private [🧠] Maybe public?
+ */
+export declare function getToolCallChipletInfo(toolCall: ToolCall): ToolCallChipletInfo;

package/esm/typings/src/book-components/Chat/utils/loadAgentProfile.d.ts

@@ -0,0 +1,69 @@
+import type { string_url, string_url_image } from '../../../types/typeAliases';
+/**
+ * Input data for resolving agent profiles.
+ * @private
+ */
+export type AgentProfileInput = {
+    url: string_url;
+    label?: string;
+    imageUrl?: string_url_image;
+    publicUrl?: string_url;
+};
+/**
+ * Resolved agent profile data for UI usage.
+ * @private
+ */
+export type AgentProfileData = {
+    label: string;
+    imageUrl: string_url_image | null;
+};
+/**
+ * Extracts agent name from URL.
+ * @private
+ */
+export declare function extractAgentNameFromUrl(url: string): string;
+/**
+ * Determines whether a label looks like an autogenerated identifier.
+ * @private
+ */
+export declare function isLikelyGeneratedId(label: string): boolean;
+/**
+ * Resolves the initial label for an agent without exposing generated IDs.
+ * @private
+ */
+export declare function resolveInitialAgentLabel(agent: AgentProfileInput): string;
+/**
+ * Picks the best available label from profile data without exposing IDs.
+ * @private
+ */
+export declare function resolvePreferredAgentLabel(candidates: Array<string | undefined>, fallback: string): string;
+/**
+ * Resolves the agents server base URL from the agent URL or provided public URL.
+ * @private
+ */
+export declare function resolveAgentsServerUrl(agentUrl: string, publicUrl?: string_url): string | null;
+/**
+ * Resolves the profile image URL, handling relative URLs when needed.
+ * @private
+ */
+export declare function resolveProfileImageUrl(profileImageUrl: string_url_image | undefined, agentUrl: string_url, publicUrl?: string_url): string_url_image | null;
+/**
+ * Builds a placeholder image URL for the agent when no profile image is available.
+ * @private
+ */
+export declare function resolvePlaceholderImageUrl(agent: AgentProfileInput): string_url_image | null;
+/**
+ * Returns true when a profile fetch would likely improve the label or image.
+ * @private
+ */
+export declare function shouldFetchAgentProfile(agent: AgentProfileInput): boolean;
+/**
+ * Resolves fallback profile data without fetching remote metadata.
+ * @private
+ */
+export declare function resolveAgentProfileFallback(agent: AgentProfileInput): AgentProfileData;
+/**
+ * Loads agent profile data from the agent profile endpoint when needed.
+ * @private
+ */
+export declare function loadAgentProfile(agent: AgentProfileInput): Promise<AgentProfileData>;

package/esm/typings/src/book-components/Chat/utils/parseCitationsFromContent.d.ts

@@ -0,0 +1,53 @@
+import type { ChatMessage } from '../types/ChatMessage';
+/**
+ * Type representing a parsed citation from RAG sources
+ */
+export type ParsedCitation = {
+    /**
+     * The unique identifier for the citation (e.g., "5:13")
+     */
+    id: string;
+    /**
+     * The source document name (e.g., "document.pdf")
+     */
+    source: string;
+    /**
+     * Optional URL to the source document
+     */
+    url?: string;
+    /**
+     * Optional preview/excerpt from the source
+     */
+    excerpt?: string;
+};
+/**
+ * Parses OpenAI Assistant-style citations from message content
+ * Matches patterns like: 【5:13†document.pdf】
+ *
+ * @param content - The markdown content that may contain citations
+ * @returns Array of parsed citations
+ *
+ * @private utility for internal use
+ */
+export declare function parseCitationsFromContent(content: string): ParsedCitation[];
+/**
+ * Removes citation markers from content and returns clean text
+ *
+ * @param content - The markdown content with citations
+ * @returns Content with citation markers removed
+ *
+ * @private utility for internal use
+ */
+export declare function stripCitationsFromContent(content: string): string;
+/**
+ * Extracts citations from a chat message if not already present
+ *
+ * @param message - The chat message to extract citations from
+ * @returns The message with citations array populated
+ *
+ * @private utility for internal use
+ */
+export declare function extractCitationsFromMessage(message: ChatMessage): ChatMessage;
+/**
+ * TODO: Maybe spread into multiple files
+ */

package/esm/typings/src/book-components/Chat/utils/resolveCitationUrl.d.ts

@@ -0,0 +1,11 @@
+import { ChatParticipant } from '../types/ChatParticipant';
+/**
+ * Resolves the URL for a citation source by looking up KNOWLEDGE commitments in the agent's source code.
+ *
+ * @param source - The source filename (e.g. "document.pdf")
+ * @param participants - List of chat participants to search in
+ * @returns The resolved URL if found, or null
+ *
+ * @private utility of <Chat/> component
+ */
+export declare function resolveCitationUrl(source: string, participants: ReadonlyArray<ChatParticipant>): string | null;

package/esm/typings/src/book-components/Chat/utils/toolCallParsing.d.ts

@@ -0,0 +1,64 @@
+import type { ToolCall } from '../../../types/ToolCall';
+import type { TODO_any } from '../../../utils/organization/TODO_any';
+/**
+ * @@@
+ *
+ * @private utility of `<Chat/>` component
+ */
+export declare function parseToolCallArguments(toolCall: Pick<ToolCall, 'arguments'>): Record<string, TODO_any>;
+/**
+ * @@@
+ *
+ * @private utility of `<Chat/>` component
+ */
+export declare function parseToolCallResult(result: ToolCall['result']): TODO_any;
+type SearchResultsExtraction = {
+    results: Array<TODO_any>;
+    rawText: string | null;
+};
+export type TeamToolResult = {
+    teammate?: {
+        url?: string;
+        label?: string;
+        instructions?: string;
+        toolName?: string;
+    };
+    request?: string;
+    response?: string;
+    error?: string | null;
+    conversation?: Array<{
+        sender?: string;
+        name?: string;
+        role?: string;
+        content?: string;
+    }>;
+};
+/**
+ * @@@
+ *
+ * @private utility of `<Chat/>` component
+ */
+export declare function extractSearchResults(resultRaw: TODO_any): SearchResultsExtraction;
+/**
+ * @@@
+ *
+ * @private utility of `<Chat/>` component
+ */
+export declare function parseTeamToolResult(resultRaw: TODO_any): TeamToolResult | null;
+/**
+ * @@@
+ *
+ * @private utility of `<Chat/>` component
+ */
+export declare function getToolCallTimestamp(toolCall: Pick<ToolCall, 'createdAt'>): Date | null;
+/**
+ * @@@
+ *
+ * @private utility of `<Chat/>` component
+ */
+export declare function getToolCallResultDate(result: ToolCall['result']): Date | null;
+export {};
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ *         <- TODO: But maybe split into multiple files later?
+ */

package/esm/typings/src/book-components/icons/EmailIcon.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Props for the EmailIcon component.
+ */
+type EmailIconProps = {
+    size?: number;
+    color?: string;
+};
+/**
+ * Renders an email/envelope icon.
+ *
+ * @param props - SVG properties augmented with an optional `size`
+ * @private internal subcomponent used by various components
+ */
+export declare function EmailIcon({ size, color }: EmailIconProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/esm/typings/src/commitments/NOTE/NOTE.d.ts

@@ -26,8 +26,8 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export declare class NoteCommitmentDefinition extends BaseCommitmentDefinition<'NOTE' | 'NOTES' | 'COMMENT' | 'NONCE'> {
-    constructor(type?: 'NOTE' | 'NOTES' | 'COMMENT' | 'NONCE');
+export declare class NoteCommitmentDefinition extends BaseCommitmentDefinition<'NOTE' | 'NOTES' | 'COMMENT' | 'NONCE' | 'TODO'> {
+    constructor(type?: 'NOTE' | 'NOTES' | 'COMMENT' | 'NONCE' | 'TODO');
     /**
      * Short one-line description of NOTE.
      */

package/esm/typings/src/commitments/TEAM/TEAM.d.ts

@@ -0,0 +1,45 @@
+import { string_javascript_name } from '../../_packages/types.index';
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+/**
+ * TEAM commitment definition
+ *
+ * The `TEAM` commitment defines teammates that the agent can consult via tools.
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * TEAM https://agents.ptbk.ik/agents/joe-green
+ * TEAM You can talk with http://localhost:4440/agents/GMw67JN8TXxN7y to discuss the legal aspects.
+ * ```
+ *
+ * @private [??] Maybe export the commitments through some package
+ */
+export declare class TeamCommitmentDefinition extends BaseCommitmentDefinition<'TEAM'> {
+    constructor();
+    /**
+     * Short one-line description of TEAM.
+     */
+    get description(): string;
+    /**
+     * Icon for this commitment.
+     */
+    get icon(): string;
+    /**
+     * Markdown documentation for TEAM commitment.
+     */
+    get documentation(): string;
+    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+    /**
+     * Gets human-readable titles for tool functions provided by this commitment.
+     */
+    getToolTitles(): Record<string_javascript_name, string>;
+    /**
+     * Gets tool function implementations for teammate tools.
+     */
+    getToolFunctions(): Record<string_javascript_name, ToolFunction>;
+}
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/commitments/TEMPLATE/TEMPLATE.d.ts

@@ -0,0 +1,44 @@
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+/**
+ * TEMPLATE commitment definition
+ *
+ * The TEMPLATE commitment enforces a specific response structure or template
+ * that the agent must follow when generating responses. This helps ensure
+ * consistent message formatting across all agent interactions.
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * TEMPLATE Always structure your response with: 1) Summary, 2) Details, 3) Next steps
+ * TEMPLATE Use the following format: **Question:** [user question] | **Answer:** [your answer]
+ * ```
+ *
+ * When used without content, it enables template mode which instructs the agent
+ * to follow any template patterns defined in other commitments or context.
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+export declare class TemplateCommitmentDefinition extends BaseCommitmentDefinition<'TEMPLATE' | 'TEMPLATES'> {
+    constructor(type?: 'TEMPLATE' | 'TEMPLATES');
+    /**
+     * Short one-line description of TEMPLATE.
+     */
+    get description(): string;
+    /**
+     * Icon for this commitment.
+     */
+    get icon(): string;
+    /**
+     * Markdown documentation for TEMPLATE commitment.
+     */
+    get documentation(): string;
+    /**
+     * TEMPLATE can be used with or without content.
+     */
+    get requiresContent(): boolean;
+    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+}
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/esm/typings/src/commitments/TEMPLATE/TEMPLATE.test.d.ts

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

package/esm/typings/src/commitments/USE_BROWSER/USE_BROWSER.d.ts

@@ -1,11 +1,17 @@
+import { string_javascript_name } from '../../_packages/types.index';
 import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
 import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * USE BROWSER commitment definition
  *
- * The `USE BROWSER` commitment indicates that the agent should utilize a web browser tool
+ * The `USE BROWSER` commitment indicates that the agent should utilize browser tools
  * to access and retrieve up-to-date information from the internet when necessary.
  *
+ * This commitment provides two levels of browser access:
+ * 1. One-shot URL fetching: Simple function to fetch and scrape URL content
+ * 2. Running browser: For complex tasks like scrolling, clicking, etc. (prepared but not active yet)
+ *
  * The content following `USE BROWSER` is ignored (similar to NOTE).
  *
  * Example usage in agent source:
@@ -35,7 +41,19 @@ export declare class UseBrowserCommitmentDefinition extends BaseCommitmentDefini
      * Markdown documentation for USE BROWSER commitment.
      */
     get documentation(): string;
+    /**
+     * Gets human-readable titles for tool functions provided by this commitment.
+     */
+    getToolTitles(): Record<string_javascript_name, string>;
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+    /**
+     * Gets the browser tool function implementations.
+     *
+     * This method automatically detects the environment and uses:
+     * - Server-side: Direct scraping via fetchUrlContent (Node.js)
+     * - Browser: Proxy through Agents Server API via fetchUrlContentViaBrowser
+     */
+    getToolFunctions(): Record<string_javascript_name, ToolFunction>;
 }
 /**
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/typings/src/commitments/USE_BROWSER/fetchUrlContent.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Fetches and scrapes content from a URL (SERVER-SIDE ONLY)
+ *
+ * This function:
+ * 1. Fetches the URL content using promptbookFetch
+ * 2. Determines the content type (HTML, PDF, etc.)
+ * 3. Uses the appropriate scraper to convert to markdown
+ * 4. Returns the scraped markdown content
+ *
+ * @param url The URL to fetch and scrape
+ * @returns Markdown content from the URL
+ *
+ * @private internal utility for USE BROWSER commitment
+ *
+ * WARNING: This function should NOT be used directly in browser environments.
+ * For browser environments, use fetchUrlContentViaBrowser which proxies through
+ * the Agents Server API endpoint at /api/scrape
+ */
+export declare function fetchUrlContent(url: string): Promise<string>;
+/**
+ * Note: [🟢] Code in this file should never be never released in packages that could be imported into browser environment
+ */

package/esm/typings/src/commitments/USE_BROWSER/fetchUrlContentViaBrowser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Client-side safe wrapper for fetching URL content
+ *
+ * This function proxies requests to the Agents Server API endpoint for scraping,
+ * making it safe to use in browser environments.
+ *
+ * @param url The URL to fetch and scrape
+ * @param agentsServerUrl The base URL of the agents server (defaults to current origin)
+ * @returns Markdown content from the URL
+ *
+ * @private internal utility for USE BROWSER commitment
+ */
+export declare function fetchUrlContentViaBrowser(url: string, agentsServerUrl?: string): Promise<string>;