@promptbook/javascript 0.111.0-7 → 0.112.0-11

package/umd/src/commitments/USE_TIMEOUT/createTimeoutTools.d.ts

@@ -0,0 +1,7 @@
+import type { LlmToolDefinition } from '../../types/LlmToolDefinition';
+/**
+ * Adds `USE TIMEOUT` tool definitions while preserving already registered tools.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+export declare function createTimeoutTools(existingTools?: ReadonlyArray<LlmToolDefinition>): Array<LlmToolDefinition>;

package/umd/src/commitments/USE_TIMEOUT/getTimeoutToolRuntimeAdapterOrDisabledResult.d.ts

@@ -0,0 +1,17 @@
+import type { CancelTimeoutToolResult, SetTimeoutToolResult, TimeoutToolAction, TimeoutToolRuntimeAdapter, TimeoutToolRuntimeContext } from './TimeoutToolRuntimeAdapter';
+/**
+ * Return type of timeout adapter resolution helper.
+ *
+ * @private type of UseTimeoutCommitmentDefinition
+ */
+type TimeoutToolRuntimeAdapterResolution = {
+    adapter: TimeoutToolRuntimeAdapter | null;
+    disabledResult: SetTimeoutToolResult | CancelTimeoutToolResult | null;
+};
+/**
+ * Resolves the runtime adapter for timeout tools or returns disabled payload when unavailable.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+export declare function getTimeoutToolRuntimeAdapterOrDisabledResult(action: TimeoutToolAction, runtimeContext: TimeoutToolRuntimeContext): TimeoutToolRuntimeAdapterResolution;
+export {};

package/umd/src/commitments/USE_TIMEOUT/parseTimeoutToolArgs.d.ts

@@ -0,0 +1,34 @@
+import type { CancelTimeoutToolArgs, SetTimeoutToolArgs } from './TimeoutToolRuntimeAdapter';
+/**
+ * Parsed arguments for `set_timeout`.
+ *
+ * @private type of UseTimeoutCommitmentDefinition
+ */
+type ParsedSetTimeoutToolArgs = {
+    milliseconds: number;
+    message?: string;
+};
+/**
+ * Parsed arguments for `cancel_timeout`.
+ *
+ * @private type of UseTimeoutCommitmentDefinition
+ */
+type ParsedCancelTimeoutToolArgs = {
+    timeoutId: string;
+};
+/**
+ * Parses and validates `USE TIMEOUT` tool arguments.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+export declare const parseTimeoutToolArgs: {
+    /**
+     * Parses `set_timeout` input.
+     */
+    set(args: SetTimeoutToolArgs): ParsedSetTimeoutToolArgs;
+    /**
+     * Parses `cancel_timeout` input.
+     */
+    cancel(args: CancelTimeoutToolArgs): ParsedCancelTimeoutToolArgs;
+};
+export {};

package/umd/src/commitments/USE_TIMEOUT/resolveTimeoutRuntimeContext.d.ts

@@ -0,0 +1,8 @@
+import type { TODO_any } from '../../_packages/types.index';
+import type { TimeoutToolRuntimeContext } from './TimeoutToolRuntimeAdapter';
+/**
+ * Resolves timeout runtime context from hidden tool arguments.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+export declare function resolveTimeoutRuntimeContext(args: Record<string, TODO_any>): TimeoutToolRuntimeContext;

package/umd/src/commitments/USE_TIMEOUT/setTimeoutToolRuntimeAdapter.d.ts

@@ -0,0 +1,13 @@
+import type { TimeoutToolRuntimeAdapter } from './TimeoutToolRuntimeAdapter';
+/**
+ * Sets runtime adapter used by `USE TIMEOUT` tools.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+export declare function setTimeoutToolRuntimeAdapter(adapter: TimeoutToolRuntimeAdapter | null): void;
+/**
+ * Gets runtime adapter used by `USE TIMEOUT` tools.
+ *
+ * @private internal utility of USE TIMEOUT
+ */
+export declare function getTimeoutToolRuntimeAdapter(): TimeoutToolRuntimeAdapter | null;

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

@@ -0,0 +1,24 @@
+import type { string_javascript_name } from '../../_packages/types.index';
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+export { setWalletToolRuntimeAdapter } from './setWalletToolRuntimeAdapter';
+export type { WalletRecordType, WalletToolRecord, WalletToolRuntimeAdapter, WalletToolRuntimeContext, } from './WalletToolRuntimeAdapter';
+/**
+ * WALLET commitment definition.
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+export declare class WalletCommitmentDefinition extends BaseCommitmentDefinition<'WALLET' | 'WALLETS'> {
+    constructor(type?: 'WALLET' | 'WALLETS');
+    get requiresContent(): boolean;
+    get description(): string;
+    get icon(): string;
+    get documentation(): string;
+    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+    getToolTitles(): Record<string_javascript_name, string>;
+    getToolFunctions(): Record<string_javascript_name, ToolFunction>;
+}
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

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

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

package/umd/src/commitments/WALLET/WalletToolNames.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Names of tools used by the WALLET commitment.
+ *
+ * @private constant of WalletCommitmentDefinition
+ */
+export declare const WalletToolNames: {
+    readonly retrieve: string;
+    readonly store: string;
+    readonly update: string;
+    readonly delete: string;
+    readonly request: string;
+};

package/umd/src/commitments/WALLET/WalletToolRuntimeAdapter.d.ts

@@ -0,0 +1,163 @@
+import type { TODO_any } from '../../_packages/types.index';
+/**
+ * Supported wallet record types.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type WalletRecordType = 'USERNAME_PASSWORD' | 'SESSION_COOKIE' | 'ACCESS_TOKEN';
+/**
+ * Normalized wallet record payload used by runtime adapters.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type WalletToolRecord = {
+    id?: string;
+    recordType: WalletRecordType;
+    service: string;
+    key: string;
+    username?: string | null;
+    password?: string | null;
+    secret?: string | null;
+    cookies?: string | null;
+    isUserScoped: boolean;
+    isGlobal: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+};
+/**
+ * Runtime context for wallet operations.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type WalletToolRuntimeContext = {
+    readonly enabled: boolean;
+    readonly userId?: number;
+    readonly username?: string;
+    readonly agentId?: string;
+    readonly agentName?: string;
+    readonly isTeamConversation: boolean;
+    readonly isPrivateMode: boolean;
+};
+/**
+ * Runtime adapter interface used by wallet tools.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type WalletToolRuntimeAdapter = {
+    retrieveWalletRecords(args: {
+        query?: string;
+        recordType?: WalletRecordType;
+        service?: string;
+        key?: string;
+        limit?: number;
+    }, runtimeContext: WalletToolRuntimeContext): Promise<WalletToolRecord[]>;
+    storeWalletRecord(args: WalletToolRecord & {
+        username?: string | null;
+        password?: string | null;
+        secret?: string | null;
+        cookies?: string | null;
+    }, runtimeContext: WalletToolRuntimeContext): Promise<WalletToolRecord>;
+    updateWalletRecord(args: WalletToolRecord & {
+        walletId: string;
+        username?: string | null;
+        password?: string | null;
+        secret?: string | null;
+        cookies?: string | null;
+    }, runtimeContext: WalletToolRuntimeContext): Promise<WalletToolRecord>;
+    deleteWalletRecord(args: {
+        walletId: string;
+    }, runtimeContext: WalletToolRuntimeContext): Promise<{
+        id?: string;
+    }>;
+};
+/**
+ * Arguments accepted by `retrieve_wallet_records`.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type RetrieveWalletRecordsToolArgs = {
+    query?: string;
+    recordType?: WalletRecordType;
+    service?: string;
+    key?: string;
+    limit?: number;
+    [key: string]: TODO_any;
+};
+/**
+ * Arguments accepted by `store_wallet_record`.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type StoreWalletRecordToolArgs = {
+    recordType?: WalletRecordType;
+    service?: string;
+    key?: string;
+    username?: string;
+    password?: string;
+    secret?: string;
+    cookies?: string;
+    isUserScoped?: boolean;
+    isGlobal?: boolean;
+    [key: string]: TODO_any;
+};
+/**
+ * Arguments accepted by `update_wallet_record`.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type UpdateWalletRecordToolArgs = StoreWalletRecordToolArgs & {
+    walletId?: string;
+};
+/**
+ * Arguments accepted by `delete_wallet_record`.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type DeleteWalletRecordToolArgs = {
+    walletId?: string;
+    [key: string]: TODO_any;
+};
+/**
+ * Arguments accepted by `request_wallet_record`.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type RequestWalletRecordToolArgs = {
+    recordType?: WalletRecordType;
+    service?: string;
+    key?: string;
+    message?: string;
+    isUserScoped?: boolean;
+    isGlobal?: boolean;
+    [key: string]: TODO_any;
+};
+/**
+ * Parsed request payload for `request_wallet_record`.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type WalletRequestRecord = {
+    recordType: WalletRecordType;
+    service: string;
+    key: string;
+    message?: string;
+    isUserScoped: boolean;
+    isGlobal: boolean;
+};
+/**
+ * Runtime wallet-tool action name.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type WalletRuntimeToolAction = 'retrieve' | 'store' | 'update' | 'delete';
+/**
+ * Result payload returned when a runtime wallet action is disabled.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+export type WalletDisabledToolResult = {
+    action: WalletRuntimeToolAction;
+    status: 'disabled';
+    records?: Array<never>;
+    message: string;
+};

package/umd/src/commitments/WALLET/createWalletSystemMessage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Creates WALLET system-message instructions.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function createWalletSystemMessage(extraInstructions: string): string;

package/umd/src/commitments/WALLET/createWalletToolFunctions.d.ts

@@ -0,0 +1,8 @@
+import type { string_javascript_name } from '../../_packages/types.index';
+import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
+/**
+ * Creates runtime wallet tool function implementations.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function createWalletToolFunctions(): Record<string_javascript_name, ToolFunction>;

package/umd/src/commitments/WALLET/createWalletTools.d.ts

@@ -0,0 +1,7 @@
+import type { LlmToolDefinition } from '../../types/LlmToolDefinition';
+/**
+ * Creates tool definitions required by WALLET commitment.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function createWalletTools(existingTools: ReadonlyArray<LlmToolDefinition> | undefined): LlmToolDefinition[];

package/umd/src/commitments/WALLET/getWalletCommitmentDocumentation.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Gets markdown documentation for WALLET commitment.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function getWalletCommitmentDocumentation(type: 'WALLET' | 'WALLETS'): string;

package/umd/src/commitments/WALLET/getWalletToolRuntimeAdapterOrDisabledResult.d.ts

@@ -0,0 +1,16 @@
+import type { WalletDisabledToolResult, WalletRuntimeToolAction, WalletToolRuntimeAdapter, WalletToolRuntimeContext } from './WalletToolRuntimeAdapter';
+/**
+ * Resolves disabled message for wallet runtime context.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function resolveWalletDisabledMessage(runtimeContext: WalletToolRuntimeContext): string | null;
+/**
+ * Resolves runtime adapter for wallet tools or returns disabled payload when unavailable.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function getWalletToolRuntimeAdapterOrDisabledResult(action: WalletRuntimeToolAction, runtimeContext: WalletToolRuntimeContext): {
+    adapter: WalletToolRuntimeAdapter | null;
+    disabledResult?: WalletDisabledToolResult;
+};

package/umd/src/commitments/WALLET/getWalletToolTitles.d.ts

@@ -0,0 +1,7 @@
+import type { string_javascript_name } from '../../_packages/types.index';
+/**
+ * Gets human-readable titles for WALLET tool functions.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function getWalletToolTitles(): Record<string_javascript_name, string>;

package/umd/src/commitments/WALLET/parseWalletToolArgs.d.ts

@@ -0,0 +1,51 @@
+import type { DeleteWalletRecordToolArgs, RequestWalletRecordToolArgs, RetrieveWalletRecordsToolArgs, StoreWalletRecordToolArgs, UpdateWalletRecordToolArgs, WalletRecordType, WalletRequestRecord, WalletToolRecord } from './WalletToolRuntimeAdapter';
+/**
+ * Parsed payload for retrieving wallet records.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+type ParsedRetrieveWalletRecordsArgs = {
+    query?: string;
+    recordType?: WalletRecordType;
+    service?: string;
+    key?: string;
+    limit?: number;
+};
+/**
+ * Parsed payload for updating an existing wallet record.
+ *
+ * @private type of WalletCommitmentDefinition
+ */
+type ParsedUpdateWalletRecordArgs = WalletToolRecord & {
+    walletId: string;
+};
+/**
+ * Collection of WALLET tool argument parsers.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare const parseWalletToolArgs: {
+    /**
+     * Parses retrieve arguments.
+     */
+    retrieve(args: RetrieveWalletRecordsToolArgs): ParsedRetrieveWalletRecordsArgs;
+    /**
+     * Parses store payload.
+     */
+    store(args: StoreWalletRecordToolArgs): WalletToolRecord;
+    /**
+     * Parses update payload.
+     */
+    update(args: UpdateWalletRecordToolArgs): ParsedUpdateWalletRecordArgs;
+    /**
+     * Parses delete payload.
+     */
+    delete(args: DeleteWalletRecordToolArgs): {
+        walletId: string;
+    };
+    /**
+     * Parses request payload for user wallet input prompt.
+     */
+    request(args: RequestWalletRecordToolArgs): WalletRequestRecord;
+};
+export {};

package/umd/src/commitments/WALLET/resolveWalletRuntimeContext.d.ts

@@ -0,0 +1,8 @@
+import type { TODO_any } from '../../_packages/types.index';
+import type { WalletToolRuntimeContext } from './WalletToolRuntimeAdapter';
+/**
+ * Resolves runtime context from hidden tool arguments.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function resolveWalletRuntimeContext(args: Record<string, TODO_any>): WalletToolRuntimeContext;

package/umd/src/commitments/WALLET/setWalletToolRuntimeAdapter.d.ts

@@ -0,0 +1,13 @@
+import type { WalletToolRuntimeAdapter } from './WalletToolRuntimeAdapter';
+/**
+ * Sets runtime adapter used by WALLET tools.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function setWalletToolRuntimeAdapter(adapter: WalletToolRuntimeAdapter | null): void;
+/**
+ * Gets runtime adapter used by WALLET tools.
+ *
+ * @private function of WalletCommitmentDefinition
+ */
+export declare function getWalletToolRuntimeAdapter(): WalletToolRuntimeAdapter | null;

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

@@ -0,0 +1,29 @@
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+/**
+ * `WRITING RULES` commitment definition.
+ *
+ * It adds constraints that apply strictly to writing style and presentation
+ * rather than task-solving behavior.
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+export declare class WritingRulesCommitmentDefinition extends BaseCommitmentDefinition<'WRITING RULES'> {
+    constructor();
+    /**
+     * Short one-line description of `WRITING RULES`.
+     */
+    get description(): string;
+    /**
+     * Icon for `WRITING RULES`.
+     */
+    get icon(): string;
+    /**
+     * Markdown documentation for `WRITING RULES`.
+     */
+    get documentation(): string;
+    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+}
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

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

@@ -0,0 +1,29 @@
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+/**
+ * `WRITING SAMPLE` commitment definition.
+ *
+ * It provides explicit sample-only text that demonstrates how the agent should
+ * sound, without adding meta commentary or behavioral rules.
+ *
+ * @private [🪔] Maybe export the commitments through some package
+ */
+export declare class WritingSampleCommitmentDefinition extends BaseCommitmentDefinition<'WRITING SAMPLE'> {
+    constructor();
+    /**
+     * Short one-line description of `WRITING SAMPLE`.
+     */
+    get description(): string;
+    /**
+     * Icon for `WRITING SAMPLE`.
+     */
+    get icon(): string;
+    /**
+     * Markdown documentation for `WRITING SAMPLE`.
+     */
+    get documentation(): string;
+    applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements;
+}
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/umd/src/commitments/_base/BaseCommitmentDefinition.d.ts

@@ -33,6 +33,10 @@ export declare abstract class BaseCommitmentDefinition<TBookCommitment extends s
      * Must be implemented by each concrete commitment.
      */
     abstract get documentation(): string;
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation(): CommitmentDefinition['deprecation'];
     /**
      * Creates a regex pattern to match this commitment in agent source
      * Uses the existing createCommitmentRegex function as internal helper
@@ -57,6 +61,14 @@ export declare abstract class BaseCommitmentDefinition<TBookCommitment extends s
      * Helper method to append content to the system message
      */
     protected appendToSystemMessage(requirements: AgentModelRequirements, content: string, separator?: string): AgentModelRequirements;
+    /**
+     * Helper method to format one system-message section with an H2 heading.
+     *
+     * @param title - Section title without markdown prefix.
+     * @param content - Section body content.
+     * @returns Formatted section text using `##` heading.
+     */
+    protected createSystemMessageSection(title: string, content: string): string;
     /**
      * Helper method to create a new requirements object with updated prompt suffix
      */

package/umd/src/commitments/_base/CommitmentDefinition.d.ts

@@ -1,6 +1,21 @@
 import { string_javascript_name } from '../../_packages/types.index';
 import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
 import { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
+/**
+ * Optional UI/docs-only deprecation metadata for one commitment keyword.
+ *
+ * @private internal type of `CommitmentDefinition`
+ */
+type CommitmentDeprecation = {
+    /**
+     * Human-readable deprecation note shown in editors and documentation.
+     */
+    readonly message: string;
+    /**
+     * Preferred replacement commitments, when applicable.
+     */
+    readonly replacedBy?: ReadonlyArray<string>;
+};
 /**
  * Definition of a commitment that can be applied to agent model requirements
  *
@@ -29,6 +44,13 @@ export type CommitmentDefinition = {
      * This is available at runtime for UIs, docs, and tooling.
      */
     readonly documentation: string;
+    /**
+     * Optional deprecation metadata for backward-compatible commitment aliases.
+     *
+     * This is intentionally UI/docs metadata only. It must not change runtime
+     * model requirements on its own.
+     */
+    readonly deprecation?: CommitmentDeprecation;
     /**
      * Creates a regex pattern to match this commitment in agent source
      * This regex should capture the commitment content in a 'contents' named group
@@ -65,3 +87,4 @@ export type CommitmentDefinition = {
      */
     getToolTitles(): Record<string_javascript_name, string>;
 };
+export {};

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

@@ -0,0 +1,19 @@
+/**
+ * Creates the canonical system-message body for one writing-sample commitment.
+ *
+ * @param content - Explicit 1:1 sample text.
+ * @returns Writing-sample guidance ready for one system-message section.
+ * @private internal utility of writing commitments
+ */
+export declare function createWritingSampleSection(content: string): string;
+/**
+ * Creates the canonical system-message body for one writing-rules commitment.
+ *
+ * @param content - Writing-only instructions.
+ * @returns Writing-rules guidance ready for one system-message section.
+ * @private internal utility of writing commitments
+ */
+export declare function createWritingRulesSection(content: string): string;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */

package/umd/src/commitments/_common/getGroupedCommitmentDefinitions.writing.test.d.ts

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

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

@@ -0,0 +1,22 @@
+import type { TODO_any } from '../../_packages/types.index';
+/**
+ * Creates one serialized tool-execution envelope.
+ *
+ * @private internal tool-execution transport
+ */
+export declare function createToolExecutionEnvelope(options: {
+    readonly assistantMessage: string;
+    readonly toolResult: TODO_any;
+}): string;
+/**
+ * Parses one serialized tool-execution envelope when present.
+ *
+ * @private internal tool-execution transport
+ */
+export declare function parseToolExecutionEnvelope(rawValue: unknown): {
+    assistantMessage: string;
+    toolResult: TODO_any;
+} | null;
+/**
+ * Note: [💞] Ignore a discrepancy between file name and entity name
+ */