@promptbook/node 0.112.0-46 → 0.112.0-48

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

@@ -0,0 +1,49 @@
+import type { CSSProperties } from 'react';
+import type { string_css_class, string_url_image } from '../types/typeAliases';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarSurfaceStyle, AvatarVisualId } from './types/AvatarVisualDefinition';
+/**
+ * Shared avatar-rendering props for places that may receive either an image URL or a deterministic avatar visual.
+ *
+ * @private shared component for avatar media rendering
+ */
+export type AvatarOrImageProps = {
+    /**
+     * Explicit image URL to render.
+     */
+    readonly imageUrl?: string_url_image | null;
+    /**
+     * Deterministic avatar definition used by built-in visuals.
+     */
+    readonly avatarDefinition?: AvatarDefinition | null;
+    /**
+     * Selected built-in visual id used with `avatarDefinition`.
+     */
+    readonly visualId?: AvatarVisualId | null;
+    /**
+     * Surface used to composite a built-in visual in its parent shell.
+     */
+    readonly surface?: AvatarSurfaceStyle;
+    /**
+     * Output size in CSS pixels.
+     */
+    readonly size: number;
+    /**
+     * Accessible label used for the rendered media.
+     */
+    readonly alt: string;
+    /**
+     * Optional CSS class name applied to the rendered element.
+     */
+    readonly className?: string_css_class;
+    /**
+     * Optional inline styles forwarded to the rendered element.
+     */
+    readonly style?: CSSProperties;
+};
+/**
+ * Renders either a static image or a deterministic canvas avatar using one common prop shape.
+ *
+ * @private shared component for avatar media rendering
+ */
+export declare function AvatarOrImage(props: AvatarOrImageProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,81 @@
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarInteractionState, AvatarPointerType } from './types/AvatarVisualDefinition';
+/**
+ * Internal interaction state kept between animation frames.
+ *
+ * @private utility of the avatar rendering system
+ */
+export type AvatarInteractionRuntimeState = AvatarInteractionState & {
+    readonly lastFrameMs: number | null;
+};
+/**
+ * Raw shared pointer sample used to derive one avatar-local gaze target.
+ *
+ * @private utility of the avatar rendering system
+ */
+export type AvatarPointerSnapshot = {
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly isPointerActive: boolean;
+    readonly pointerType: Exclude<AvatarPointerType, 'idle'>;
+};
+/**
+ * Avatar-local pointer target resolved from viewport coordinates.
+ *
+ * @private utility of the avatar rendering system
+ */
+export type AvatarPointerTarget = {
+    readonly gazeX: number;
+    readonly gazeY: number;
+    readonly bodyOffsetX: number;
+    readonly bodyOffsetY: number;
+    readonly intensity: number;
+    readonly isPointerActive: boolean;
+    readonly pointerType: AvatarPointerType;
+};
+/**
+ * Creates one stable cache key from the meaningful avatar-definition fields.
+ *
+ * @param avatarDefinition Normalized or raw avatar definition.
+ * @returns Stable cache key that ignores object identity churn.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function createAvatarDefinitionKey(avatarDefinition: AvatarDefinition): string;
+/**
+ * Returns the neutral interaction state used by static/server-side renders.
+ *
+ * @returns Zeroed interaction state.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function createIdleAvatarInteractionState(): AvatarInteractionState;
+/**
+ * Creates a fresh runtime state for the interactive animation loop.
+ *
+ * @returns Runtime interaction state with neutral values.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function createAvatarInteractionRuntimeState(): AvatarInteractionRuntimeState;
+/**
+ * Converts the shared viewport pointer state into one avatar-local gaze target.
+ *
+ * @param avatarBounds Canvas bounds in viewport coordinates.
+ * @param pointerSnapshot Latest shared pointer sample.
+ * @returns Local target used to steer eyes and subtle body lean.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function resolveAvatarPointerTarget(avatarBounds: Pick<DOMRectReadOnly, 'left' | 'top' | 'width' | 'height'>, pointerSnapshot: AvatarPointerSnapshot | null): AvatarPointerTarget;
+/**
+ * Advances the smoothed interaction state toward the latest pointer target.
+ *
+ * @param runtimeState Previous animation-frame state.
+ * @param pointerTarget Latest local pointer target.
+ * @param nowMs Current animation-frame timestamp.
+ * @returns Next runtime state to keep in the animation loop.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function stepAvatarInteractionRuntimeState(runtimeState: AvatarInteractionRuntimeState, pointerTarget: AvatarPointerTarget, nowMs: number): AvatarInteractionRuntimeState;

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

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

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

@@ -0,0 +1,17 @@
+import type { AvatarPointerSnapshot } from './avatarInteractionUtils';
+/**
+ * Starts the shared pointer tracker and returns a disposer for the caller.
+ *
+ * @returns Cleanup function that releases one consumer.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function retainAvatarPointerTracking(): () => void;
+/**
+ * Returns the latest shared viewport pointer sample when available.
+ *
+ * @returns Shared pointer snapshot or `null`.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function getAvatarPointerSnapshot(): AvatarPointerSnapshot | null;

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

@@ -1,7 +1,7 @@
 import type { AgentBasicInformation } from '../book-2.0/agent-source/AgentBasicInformation';
 import type { string_color } from '../types/typeAliases';
 import type { AvatarDefinition } from './types/AvatarDefinition';
-import type { AvatarPalette } from './types/AvatarVisualDefinition';
+import type { AvatarPalette, AvatarSurfaceStyle } from './types/AvatarVisualDefinition';
 /**
  * Default square size used by avatar renderers.
  *
@@ -48,11 +48,12 @@ export declare function createAvatarDefinitionFromAgentBasicInformation(agentBas
  * Creates the shared derived palette used by every avatar visual.
  *
  * @param avatarDefinition Stable avatar definition.
+ * @param surface Surface style used by the parent UI.
  * @returns Derived palette.
  *
  * @private utility of the avatar rendering system
  */
-export declare function createAvatarPalette(avatarDefinition: AvatarDefinition): AvatarPalette;
+export declare function createAvatarPalette(avatarDefinition: AvatarDefinition, surface?: AvatarSurfaceStyle): AvatarPalette;
 /**
  * Draws the common rounded background frame used by most visuals.
  *

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

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

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

@@ -1,6 +1,7 @@
 export { Avatar } from './Avatar';
+export { AvatarOrImage } from './AvatarOrImage';
 export { renderAvatarVisual } from './renderAvatarVisual';
 export { createAvatarDefinitionFromAgentBasicInformation } from './avatarRenderingUtils';
 export { AVATAR_VISUALS, getAvatarVisualById } from './visuals/avatarVisualRegistry';
 export type { AvatarDefinition } from './types/AvatarDefinition';
-export type { AvatarPalette, AvatarProps, AvatarVisual, AvatarVisualDefinition, AvatarVisualId, AvatarVisualRenderContext, RenderAvatarVisualOptions, } from './types/AvatarVisualDefinition';
+export type { AvatarInteractionState, AvatarPalette, AvatarPointerType, AvatarProps, AvatarVisual, AvatarVisualDefinition, AvatarVisualId, AvatarVisualRenderContext, RenderAvatarVisualOptions, } from './types/AvatarVisualDefinition';

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

@@ -1,3 +1,4 @@
+import type { CSSProperties } from 'react';
 import type { string_color, string_css_class } from '../../types/typeAliases';
 import type { AvatarDefinition } from './AvatarDefinition';
 /**
@@ -5,7 +6,7 @@ import type { AvatarDefinition } from './AvatarDefinition';
  *
  * @private shared contract for the avatar rendering system
  */
-export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'minecraft' | 'fractal';
+export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'ascii-octopus' | 'minecraft' | 'fractal';
 /**
  * Derived color palette used by avatar visuals.
  *
@@ -21,6 +22,32 @@ export type AvatarPalette = {
     readonly shadow: string_color;
     readonly ink: string_color;
 };
+/**
+ * Surface style used when placing the avatar into different UI shells.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarSurfaceStyle = 'framed' | 'transparent';
+/**
+ * Pointer source currently driving avatar interaction.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarPointerType = 'idle' | 'mouse' | 'touch' | 'pen';
+/**
+ * Smoothed interaction state forwarded to animated avatar visuals.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarInteractionState = {
+    readonly gazeX: number;
+    readonly gazeY: number;
+    readonly bodyOffsetX: number;
+    readonly bodyOffsetY: number;
+    readonly intensity: number;
+    readonly isPointerActive: boolean;
+    readonly pointerType: AvatarPointerType;
+};
 /**
  * Rendering context forwarded to a single avatar visual.
  *
@@ -35,6 +62,8 @@ export type AvatarVisualRenderContext = {
     readonly avatarDefinition: AvatarDefinition;
     readonly palette: AvatarPalette;
     readonly createRandom: (salt: string) => () => number;
+    readonly surface: AvatarSurfaceStyle;
+    readonly interaction: AvatarInteractionState;
 };
 /**
  * Signature of one canvas-based avatar visual renderer.
@@ -52,6 +81,7 @@ export type AvatarVisualDefinition = {
     readonly title: string;
     readonly description: string;
     readonly isAnimated: boolean;
+    readonly supportsPointerTracking?: boolean;
     readonly render: AvatarVisual;
 };
 /**
@@ -68,6 +98,10 @@ export type AvatarProps = {
      * Selected visual style.
      */
     readonly visualId: AvatarVisualId;
+    /**
+     * Surface used to composite the avatar in its parent UI.
+     */
+    readonly surface?: AvatarSurfaceStyle;
     /**
      * Output size in CSS pixels.
      */
@@ -80,6 +114,10 @@ export type AvatarProps = {
      * Optional CSS class name applied to the canvas.
      */
     readonly className?: string_css_class;
+    /**
+     * Optional inline style applied to the canvas.
+     */
+    readonly style?: CSSProperties;
 };
 /**
  * Low-level rendering options for a single canvas frame.
@@ -90,7 +128,9 @@ export type RenderAvatarVisualOptions = {
     readonly canvas: HTMLCanvasElement;
     readonly avatarDefinition: AvatarDefinition;
     readonly visualId: AvatarVisualId;
+    readonly surface?: AvatarSurfaceStyle;
     readonly size: number;
     readonly timeMs: number;
     readonly devicePixelRatio?: number;
+    readonly interaction?: AvatarInteractionState;
 };

package/umd/src/avatars/visuals/asciiOctopusAvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * AsciiOctopus avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const asciiOctopusAvatarVisual: AvatarVisualDefinition;

package/umd/src/avatars/visuals/octopus3AvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Octopus3 avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopus3AvatarVisual: AvatarVisualDefinition;

package/umd/src/avatars/visuals/octopusAvatarVisualShared.d.ts

@@ -0,0 +1,159 @@
+import type { AvatarInteractionState } from '../types/AvatarVisualDefinition';
+/**
+ * One 2D point used by the shared organic octopus geometry helpers.
+ *
+ * @private helper of octopus avatar visuals
+ */
+type Point = {
+    readonly x: number;
+    readonly y: number;
+};
+/**
+ * Shape parameters for the smooth octopus silhouette generator.
+ *
+ * @private helper of octopus avatar visuals
+ */
+type CreateOrganicOctopusBodyPointsOptions = {
+    readonly centerX: number;
+    readonly centerY: number;
+    readonly bodyRadius: number;
+    readonly horizontalStretch: number;
+    readonly verticalStretch: number;
+    readonly mantleLift: number;
+    readonly lowerDrop: number;
+    readonly tentacleDepth: number;
+    readonly wobbleAmplitude: number;
+    readonly lobeCount: number;
+    readonly shapePhase: number;
+    readonly timeMs: number;
+    readonly pointCount?: number;
+};
+/**
+ * One deterministic ribbon tentacle attached to an organic octopus mantle.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+export type OrganicTentacleShape = {
+    readonly startPoint: Point;
+    readonly controlPointOne: Point;
+    readonly controlPointTwo: Point;
+    readonly endPoint: Point;
+    readonly baseWidth: number;
+    readonly tipWidth: number;
+    readonly colorBias: number;
+    readonly highlightBias: number;
+    readonly sampleCount: number;
+};
+/**
+ * Options for generating deterministic organic octopus tentacles.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+type CreateOrganicOctopusTentacleShapesOptions = {
+    readonly size: number;
+    readonly centerX: number;
+    readonly centerY: number;
+    readonly bodyRadius: number;
+    readonly horizontalStretch: number;
+    readonly tentacleCount: number;
+    readonly shapePhase: number;
+    readonly createRandom: (salt: string) => () => number;
+    readonly timeMs: number;
+    readonly saltPrefix: string;
+    readonly bodyPoints?: ReadonlyArray<Point>;
+};
+/**
+ * One sampled ribbon point on an organic octopus tentacle.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+export type OrganicTentacleRibbonPoint = {
+    readonly x: number;
+    readonly y: number;
+    readonly normalX: number;
+    readonly normalY: number;
+    readonly width: number;
+    readonly progress: number;
+};
+/**
+ * One resolved eye-motion sample shared by the octopus-family renderers.
+ *
+ * @private shared geometry helper of octopus avatar visuals
+ */
+export type OrganicEyeMotion = {
+    readonly pupilOffsetX: number;
+    readonly pupilOffsetY: number;
+};
+/**
+ * Minimal interaction subset needed to steer octopus-eye pupils.
+ *
+ * @private shared geometry helper of octopus avatar visuals
+ */
+type OrganicEyeInteraction = Pick<AvatarInteractionState, 'gazeX' | 'gazeY' | 'intensity'>;
+/**
+ * Builds a smoothly morphing octopus-like silhouette from deterministic parameters.
+ *
+ * @param options Shape construction options.
+ * @returns Closed-loop body points.
+ *
+ * @private shared geometry helper of `octopus2AvatarVisual` and `octopus3AvatarVisual`
+ */
+export declare function createOrganicOctopusBodyPoints(options: CreateOrganicOctopusBodyPointsOptions): Array<Point>;
+/**
+ * Traces a smooth closed path through the provided points.
+ *
+ * @param context Canvas 2D context.
+ * @param points Closed-loop points.
+ *
+ * @private shared geometry helper of `octopus2AvatarVisual` and `octopus3AvatarVisual`
+ */
+export declare function traceSmoothClosedPath(context: CanvasRenderingContext2D, points: ReadonlyArray<Point>): void;
+/**
+ * Creates deterministic ribbon tentacles for the organic octopus visuals.
+ *
+ * @param options Tentacle construction options.
+ * @returns Tentacle descriptors.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+export declare function createOrganicOctopusTentacleShapes(options: CreateOrganicOctopusTentacleShapesOptions): Array<OrganicTentacleShape>;
+/**
+ * Samples the cubic tentacle centerline and offsets normals to build a filled ribbon.
+ *
+ * @param tentacleShape Deterministic tentacle descriptor.
+ * @returns Sampled ribbon points.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual` and `asciiOctopusAvatarVisual`
+ */
+export declare function sampleOrganicTentacleRibbonPoints(tentacleShape: OrganicTentacleShape): Array<OrganicTentacleRibbonPoint>;
+/**
+ * Resolves smooth pupil offsets that blend autonomous idle drift with live viewer tracking.
+ *
+ * @param options Eye motion options.
+ * @returns Resolved pupil offsets.
+ *
+ * @private shared geometry helper of octopus avatar visuals
+ */
+export declare function resolveOrganicEyeMotion(options: {
+    readonly radiusX: number;
+    readonly radiusY: number;
+    readonly timeMs: number;
+    readonly phase: number;
+    readonly interaction: OrganicEyeInteraction;
+    readonly autonomousDriftRatioX?: number;
+    readonly autonomousDriftRatioY?: number;
+}): OrganicEyeMotion;
+/**
+ * Samples one point on a cubic Bezier curve.
+ *
+ * @param startPoint Curve start point.
+ * @param controlPointOne First control point.
+ * @param controlPointTwo Second control point.
+ * @param endPoint Curve end point.
+ * @param progress Sampling progress in the range `[0, 1]`.
+ * @returns Sampled point.
+ *
+ * @private shared geometry helper of `octopus3AvatarVisual`
+ */
+export declare function getCubicBezierPoint(startPoint: Point, controlPointOne: Point, controlPointTwo: Point, endPoint: Point, progress: number): Point;
+export {};

package/umd/src/avatars/visuals/octopusAvatarVisualShared.test.d.ts

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

package/umd/src/book-components/Chat/Chat/ChatMessageItem.d.ts

@@ -75,7 +75,7 @@ type ChatMessageItemProps = Pick<ChatProps, 'onMessage' | 'onActionButton' | 'on
     /**
      * Controls whether assistant replies render as bubbles or article blocks.
      */
-    CHAT_VISUAL_MODE?: ChatProps['CHAT_VISUAL_MODE'];
+    visualMode?: ChatProps['visualMode'];
     /**
      * Called when a tool call chiplet is clicked.
      */

package/umd/src/book-components/Chat/Chat/ChatMessageList.d.ts

@@ -46,7 +46,7 @@ export type ChatMessageListProps = {
     toolTitles?: Record<string, string>;
     teammates?: ChatProps['teammates'];
     teamAgentProfiles?: ChatProps['teamAgentProfiles'];
-    CHAT_VISUAL_MODE?: ChatProps['CHAT_VISUAL_MODE'];
+    visualMode?: ChatProps['visualMode'];
     onToolCallClick?: (toolCall: NonNullable<ChatMessage['toolCalls']>[number]) => void;
     onCitationClick?: (citation: ParsedCitation) => void;
     soundSystem?: ChatProps['soundSystem'];

package/umd/src/book-components/Chat/Chat/ChatProps.d.ts

@@ -747,7 +747,7 @@ export type ChatProps = {
      *
      * @default 'ARTICLE_MODE'
      */
-    readonly CHAT_VISUAL_MODE?: ChatVisualMode;
+    readonly visualMode?: ChatVisualMode;
     /**
      * Visual style of the chat component
      */

package/umd/src/book-components/Chat/Chat/ChatToolCallModalComponents.d.ts

@@ -1,4 +1,6 @@
 import { type ReactNode } from 'react';
+import type { AvatarDefinition } from '../../../avatars/types/AvatarDefinition';
+import type { AvatarVisualId } from '../../../avatars/types/AvatarVisualDefinition';
 /**
  * Props for a team modal header profile badge.
  *
@@ -7,6 +9,8 @@ import { type ReactNode } from 'react';
 export type TeamHeaderProfileProps = {
     label: string;
     avatarSrc?: string | null;
+    avatarDefinition?: AvatarDefinition;
+    avatarVisualId?: AvatarVisualId;
     href?: string;
     fallbackColor?: string;
 };
@@ -15,7 +19,7 @@ export type TeamHeaderProfileProps = {
  *
  * @private component of `<Chat/>`
  */
-export declare function TeamHeaderProfile({ label, avatarSrc, href, fallbackColor }: TeamHeaderProfileProps): import("react/jsx-runtime").JSX.Element;
+export declare function TeamHeaderProfile({ label, avatarSrc, avatarDefinition, avatarVisualId, href, fallbackColor, }: TeamHeaderProfileProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Props for a self-learning modal avatar.
  *
@@ -24,6 +28,8 @@ export declare function TeamHeaderProfile({ label, avatarSrc, href, fallbackColo
 export type SelfLearningAvatarProps = {
     label: string;
     avatarSrc?: string | null;
+    avatarDefinition?: AvatarDefinition;
+    avatarVisualId?: AvatarVisualId;
     fallbackColor?: string;
     className?: string;
     children?: ReactNode;
@@ -33,4 +39,4 @@ export type SelfLearningAvatarProps = {
  *
  * @private component of `<Chat/>`
  */
-export declare function SelfLearningAvatar({ label, avatarSrc, fallbackColor, className, children, }: SelfLearningAvatarProps): import("react/jsx-runtime").JSX.Element;
+export declare function SelfLearningAvatar({ label, avatarSrc, avatarDefinition, avatarVisualId, fallbackColor, className, children, }: SelfLearningAvatarProps): import("react/jsx-runtime").JSX.Element;

package/umd/src/book-components/Chat/Chat/TeamToolCallModalContent.test.d.ts

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

package/umd/src/book-components/Chat/hooks/useChatCompleteNotification.d.ts

@@ -8,6 +8,8 @@ import type { ChatMessage } from '../types/ChatMessage';
  * - Every streaming chunk / intermediate content update
  * - `message_typing` lifecycle events before the message is finalized
  * - Re-renders of an already-notified completed message (idempotent)
+ * - Initial mount hydration with preloaded completed chat history
+ * - Switching to another chat thread that already contains completed history
  * - User-originated messages
  *
  * @param messages - Current list of chat messages

package/umd/src/book-components/Chat/types/ChatParticipant.d.ts

@@ -1,6 +1,8 @@
 import type { string_book } from '../../../book-2.0/agent-source/string_book';
 import type { id, string_color, string_person_fullname, string_url_image } from '../../../types/typeAliases';
 import { Color } from '../../../utils/color/Color';
+import type { AvatarDefinition } from '../../../avatars/types/AvatarDefinition';
+import type { AvatarVisualId } from '../../../avatars/types/AvatarVisualDefinition';
 /**
  * A participant in the chat
  *
@@ -23,6 +25,14 @@ export type ChatParticipant = {
      * Profile picture
      */
     avatarSrc?: string_url_image;
+    /**
+     * Deterministic avatar definition used when no static image should be shown.
+     */
+    avatarDefinition?: AvatarDefinition;
+    /**
+     * Built-in avatar visual id used with `avatarDefinition`.
+     */
+    avatarVisualId?: AvatarVisualId;
     /**
      * Color associated with the participant
      */

package/umd/src/cli/cli-commands/coder/ensureCoderGitignoreFile.d.ts

@@ -1,6 +1,6 @@
 import type { InitializationStatus } from './boilerplateTemplates';
 /**
- * Ensures `.gitignore` contains the standalone Promptbook coder cache entry.
+ * Ensures `.gitignore` contains the standalone Promptbook coder temp and cache entries.
  *
  * @private function of `initializeCoderProjectConfiguration`
  */

package/umd/src/commitments/USE/USE.d.ts

@@ -9,6 +9,7 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  * Supported USE types:
  * - USE BROWSER: Enables the agent to use a web browser tool
  * - USE SEARCH ENGINE (future): Enables search engine access
+ * - USE DEEPSEARCH: Enables deeper research-oriented search access
  * - USE FILE SYSTEM (future): Enables file system operations
  * - USE MCP (future): Enables MCP server connections
  *

package/umd/src/commitments/USE/aggregateUseCommitmentSystemMessages.d.ts

@@ -6,7 +6,7 @@ import type { ParsedCommitment } from '../_base/ParsedCommitment';
  *
  * @private internal utility of `createAgentModelRequirementsWithCommitments`
  */
-type AggregatedUseCommitmentType = 'USE BROWSER' | 'USE SEARCH ENGINE' | 'USE TIME';
+type AggregatedUseCommitmentType = 'USE BROWSER' | 'USE DEEPSEARCH' | 'USE SEARCH ENGINE' | 'USE TIME';
 /**
  * Adds the placeholder for an aggregated `USE` system-message section only once, preserving the section position from the first occurrence.
  *

package/umd/src/commitments/USE_DEEPSEARCH/USE_DEEPSEARCH.d.ts

@@ -0,0 +1,47 @@
+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 DEEPSEARCH commitment definition
+ *
+ * The `USE DEEPSEARCH` commitment indicates that the agent should use a deeper research-oriented
+ * search workflow instead of lightweight web search when it needs fresh information from the internet.
+ *
+ * The content following `USE DEEPSEARCH` is an arbitrary text that the agent should know
+ * (e.g. search scope or research instructions).
+ *
+ * Example usage in agent source:
+ *
+ * ```book
+ * USE DEEPSEARCH
+ * USE DEEPSEARCH Compare official vendor documentation with independent benchmarks.
+ * ```
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+export declare class UseDeepSearchCommitmentDefinition extends BaseCommitmentDefinition<'USE DEEPSEARCH'> {
+    constructor();
+    get requiresContent(): boolean;
+    /**
+     * Short one-line description of USE DEEPSEARCH.
+     */
+    get description(): string;
+    /**
+     * Icon for this commitment.
+     */
+    get icon(): string;
+    /**
+     * Markdown documentation for USE DEEPSEARCH 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 the local fallback implementation for the `deep_search` tool.
+     */
+    getToolFunctions(): Record<string_javascript_name, ToolFunction>;
+}

package/umd/src/commitments/USE_DEEPSEARCH/USE_DEEPSEARCH.test.d.ts

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

package/umd/src/commitments/_common/createSerpSearchToolFunction.d.ts

@@ -0,0 +1,12 @@
+import { string_javascript_name } from '../../_packages/types.index';
+import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
+/**
+ * Creates one SERP-backed tool function used as a local fallback for search-like commitments.
+ *
+ * @param toolName - Technical tool name used for validation messages.
+ * @param resultLabel - Human-readable label used in formatted results.
+ * @returns Async tool function compatible with commitment tool registration.
+ *
+ * @private internal helper for search-like commitments
+ */
+export declare function createSerpSearchToolFunction(toolName: string_javascript_name, resultLabel: string): ToolFunction;