@promptbook/cli 0.113.0-7 → 0.113.0-9

package/src/cli/cli-commands/agents-server.ts

@@ -1,15 +1,11 @@
 import colors from 'colors';
 import type {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+  Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 import { $initializeAgentsServerInitCommand } from './agents-server/init';
-import {
-    $initializeAgentsServerBuildCommand,
-    $initializeAgentsServerDevCommand,
-    $initializeAgentsServerStartCommand,
-} from './agents-server/run';
+import { $initializeAgentsServerBuildCommand, $initializeAgentsServerDevCommand, $initializeAgentsServerStartCommand } from './agents-server/run';
 
 /**
  * Initializes `agents-server` command with subcommands for Promptbook CLI utilities.

package/src/cli/cli-commands/coder/agentCodingFile.ts

@@ -1,12 +1,6 @@
 import { spaceTrim } from 'spacetrim';
 import { AGENTS_FILE_PATH } from './agentsFile';
-import {
-    getDefaultCoderProjectPromptTemplateDefinitions,
-    getDefaultCoderPromptTemplateDefinitions,
-    PROMPTS_DIRECTORY_PATH,
-    PROMPTS_DONE_DIRECTORY_PATH,
-    PROMPTS_TEMPLATES_DIRECTORY_PATH,
-} from './boilerplateTemplates';
+import { getDefaultCoderProjectPromptTemplateDefinitions, getDefaultCoderPromptTemplateDefinitions, PROMPTS_DIRECTORY_PATH, PROMPTS_DONE_DIRECTORY_PATH, PROMPTS_TEMPLATES_DIRECTORY_PATH } from './boilerplateTemplates';
 import { formatDisplayPath } from './formatDisplayPath';
 
 /**

package/src/cli/cli-commands/coder/generate-boilerplates.ts

@@ -1,17 +1,13 @@
 import colors from 'colors';
 import type {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+  Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */
 } from 'commander';
 import { mkdirSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { spaceTrim } from 'spacetrim';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
 import { handleActionErrors } from '../common/handleActionErrors';
-import {
-    getDefaultCoderPromptTemplateDefinitions,
-    PROMPTS_DIRECTORY_PATH,
-    resolveCoderPromptTemplate,
-} from './boilerplateTemplates';
+import { getDefaultCoderPromptTemplateDefinitions, PROMPTS_DIRECTORY_PATH, resolveCoderPromptTemplate } from './boilerplateTemplates';
 
 /**
  * Initializes `coder generate-boilerplates` command for Promptbook CLI utilities

package/src/cli/cli-commands/coder/initializeCoderProjectConfiguration.ts

@@ -1,14 +1,9 @@
 import { AGENT_CODING_FILE_PATH, getDefaultCoderAgentCodingFileContent } from './agentCodingFile';
 import { AGENTS_FILE_PATH, getDefaultCoderAgentsFileContent } from './agentsFile';
 import type { EnsuredCoderPromptTemplateFile, InitializationStatus } from './boilerplateTemplates';
-import {
-    ensureDefaultCoderPromptTemplateFiles,
-    PROMPTS_DIRECTORY_PATH,
-    PROMPTS_DONE_DIRECTORY_PATH,
-    PROMPTS_TEMPLATES_DIRECTORY_PATH,
-} from './boilerplateTemplates';
-import { ensureCoderEnvFile } from './ensureCoderEnvFile';
+import { ensureDefaultCoderPromptTemplateFiles, PROMPTS_DIRECTORY_PATH, PROMPTS_DONE_DIRECTORY_PATH, PROMPTS_TEMPLATES_DIRECTORY_PATH } from './boilerplateTemplates';
 import { CODER_AGENTS_DIRECTORY_PATH, ensureCoderDeveloperAgentFile } from './ensureCoderDeveloperAgentFile';
+import { ensureCoderEnvFile } from './ensureCoderEnvFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';
 import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';

package/src/cli/cli-commands/coder/server.ts

@@ -1,6 +1,8 @@
 import colors from 'colors';
-import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
-import { Option } from 'commander';
+import {
+    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+    Option,
+} from 'commander';
 import { spaceTrim } from 'spacetrim';
 import { NETWORK_LIMITS } from '../../../constants';
 import { assertsError } from '../../../errors/assertsError';

package/src/cli/cli-commands/common/promptRunnerCliOptions.ts

@@ -1,17 +1,12 @@
 import colors from 'colors';
 import {
-    Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
-    Option,
+  Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
+  Option
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import { CLI_AGENT_HARNESS_NAMES, PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV } from '../../../book-3.0/cliAgentEnv';
 import type { ThinkingLevel } from '../coder/ThinkingLevel';
 import { THINKING_LEVEL_VALUES } from '../coder/ThinkingLevel';
-import {
-    CLI_AGENT_HARNESS_NAMES,
-    PTBK_HARNESS_ENV,
-    PTBK_MODEL_ENV,
-    PTBK_THINKING_LEVEL_ENV,
-} from '../../../book-3.0/cliAgentEnv';
 
 export { PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV };
 

package/src/cli/cli-commands/make.ts

@@ -23,8 +23,8 @@ import type { PipelineJson } from '../../pipeline/PipelineJson/PipelineJson';
 import { $provideFilesystemForNode } from '../../scrapers/_common/register/$provideFilesystemForNode';
 import { $provideScrapersForNode } from '../../scrapers/_common/register/$provideScrapersForNode';
 import { $provideScriptingForNode } from '../../scrapers/_common/register/$provideScriptingForNode';
-import type { string_file_extension } from '../../types/string_sha256';
 import type { string_promptbook_server_url } from '../../types/string_promptbook_server_url';
+import type { string_file_extension } from '../../types/string_sha256';
 import { stringifyPipelineJson } from '../../utils/editable/utils/stringifyPipelineJson';
 import type { $side_effect } from '../../utils/organization/$side_effect';
 import { keepTypeImported } from '../../utils/organization/keepTypeImported';

package/src/cli/cli-commands/run/runCommandAction.ts

@@ -1,8 +1,8 @@
 import colors from 'colors';
+import { jsonParse } from '../../../formats/json/utils/jsonParse';
 import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
 import type { PrepareAndScrapeOptions } from '../../../prepare/PrepareAndScrapeOptions';
 import type { string_parameter_name, string_parameter_value } from '../../../types/string_name';
-import { jsonParse } from '../../../formats/json/utils/jsonParse';
 import { normalizeToKebabCase } from '../../../utils/normalization/normalize-to-kebab-case';
 import { runInteractiveChatbot } from '../runInteractiveChatbot';
 import { prepareRunCommandResources } from './prepareRunCommandResources';

package/src/collection/agent-collection/CreateAgentInput.ts

@@ -1,9 +1,6 @@
+import type { AgentVisibility } from '../../book-2.0/agent-source/agentSourceVisibility';
+import { AGENT_VISIBILITY_VALUES, normalizeAgentVisibility } from '../../book-2.0/agent-source/agentSourceVisibility';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
-import {
-    AGENT_VISIBILITY_VALUES,
-    normalizeAgentVisibility,
-    type AgentVisibility,
-} from '../../book-2.0/agent-source/agentSourceVisibility';
 import { LimitReachedError } from '../../errors/LimitReachedError';
 import { ParseError } from '../../errors/ParseError';
 import type { LlmToolDefinition } from '../../types/LlmToolDefinition';

package/src/collection/agent-collection/constructors/agent-collection-in-supabase/prepareAgentSourceForPersistence.ts

@@ -1,9 +1,9 @@
 import type { AgentBasicInformation } from '../../../../book-2.0/agent-source/AgentBasicInformation';
+import type { AgentVisibility } from '../../../../book-2.0/agent-source/agentSourceVisibility';
 import {
     DEFAULT_AGENT_VISIBILITY,
     parseAgentSourceVisibility,
     setAgentSourceVisibility,
-    type AgentVisibility,
 } from '../../../../book-2.0/agent-source/agentSourceVisibility';
 import { parseAgentSource } from '../../../../book-2.0/agent-source/parseAgentSource';
 import type { string_book } from '../../../../book-2.0/agent-source/string_book';

package/src/commitments/MEMORY/createMemoryToolFunctions.ts

@@ -2,16 +2,7 @@ import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutio
 import type { string_javascript_name } from '../../types/string_person_fullname';
 import { getMemoryToolRuntimeAdapterOrDisabledResult } from './getMemoryToolRuntimeAdapterOrDisabledResult';
 import { MemoryToolNames } from './MemoryToolNames';
-import type {
-    DeleteMemoryToolArgs,
-    DeleteMemoryToolResult,
-    RetrieveMemoryToolArgs,
-    RetrieveMemoryToolResult,
-    StoreMemoryToolArgs,
-    StoreMemoryToolResult,
-    UpdateMemoryToolArgs,
-    UpdateMemoryToolResult,
-} from './MemoryToolRuntimeAdapter';
+import type { DeleteMemoryToolArgs, DeleteMemoryToolResult, RetrieveMemoryToolArgs, RetrieveMemoryToolResult, StoreMemoryToolArgs, StoreMemoryToolResult, UpdateMemoryToolArgs, UpdateMemoryToolResult } from './MemoryToolRuntimeAdapter';
 import { parseMemoryToolArgs } from './parseMemoryToolArgs';
 import { resolveMemoryRuntimeContext } from './resolveMemoryRuntimeContext';
 

package/src/commitments/MEMORY/getMemoryToolRuntimeAdapterOrDisabledResult.ts

@@ -1,13 +1,4 @@
-import type {
-    DeleteMemoryToolResult,
-    MemoryToolAction,
-    MemoryToolResult,
-    MemoryToolRuntimeAdapter,
-    MemoryToolRuntimeContext,
-    RetrieveMemoryToolResult,
-    StoreMemoryToolResult,
-    UpdateMemoryToolResult,
-} from './MemoryToolRuntimeAdapter';
+import type { DeleteMemoryToolResult, MemoryToolAction, MemoryToolResult, MemoryToolRuntimeAdapter, MemoryToolRuntimeContext, RetrieveMemoryToolResult, StoreMemoryToolResult, UpdateMemoryToolResult } from './MemoryToolRuntimeAdapter';
 import { getMemoryToolRuntimeAdapter } from './setMemoryToolRuntimeAdapter';
 
 /**

package/src/commitments/MEMORY/parseMemoryToolArgs.ts

@@ -1,9 +1,4 @@
-import type {
-    DeleteMemoryToolArgs,
-    RetrieveMemoryToolArgs,
-    StoreMemoryToolArgs,
-    UpdateMemoryToolArgs,
-} from './MemoryToolRuntimeAdapter';
+import type { DeleteMemoryToolArgs, RetrieveMemoryToolArgs, StoreMemoryToolArgs, UpdateMemoryToolArgs } from './MemoryToolRuntimeAdapter';
 
 /**
  * Parsed retrieve memory arguments.

package/src/commitments/META/META.ts

@@ -7,7 +7,7 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  * META commitment definition
  *
  * The META commitment handles all meta-information about the agent such as:
- * - META AVATAR: Sets the agent's built-in default avatar visual
+ * - META AVATAR / META VISUAL: Sets the agent's built-in default avatar visual
  * - META IMAGE: Sets the agent's avatar/profile image URL
  * - META LINK: Provides profile/source links for the person the agent models
  * - META DOMAIN: Sets the canonical custom domain/host of the agent
@@ -22,7 +22,7 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
  * Example usage in agent source:
  *
  * ```book
- * META AVATAR pixel-art
+ * META VISUAL pixel-art
  * META IMAGE https://example.com/avatar.jpg
  * META LINK https://twitter.com/username
  * META DOMAIN my-agent.com
@@ -65,7 +65,7 @@ export class MetaCommitmentDefinition extends BaseCommitmentDefinition<`META${st
 
             ## Supported META types
 
-            - **META AVATAR** - Sets the agent's built-in default avatar visual
+            - **META AVATAR** / **META VISUAL** - Sets the agent's built-in default avatar visual
             - **META IMAGE** - Sets the agent's avatar/profile image URL
             - **META LINK** - Provides profile/source links for the person the agent models
             - **META DOMAIN** - Sets the canonical custom domain/host of the agent
@@ -89,7 +89,7 @@ export class MetaCommitmentDefinition extends BaseCommitmentDefinition<`META${st
             \`\`\`book
             Professional Assistant
 
-            META AVATAR octopus3
+            META VISUAL octopus3
             META IMAGE https://example.com/professional-avatar.jpg
             META TITLE Senior Business Consultant
             META DESCRIPTION Specialized in strategic planning and project management

package/src/commitments/META_AVATAR/META_AVATAR.ts

@@ -4,17 +4,22 @@ import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentMo
 import { TODO_USE } from '../../utils/organization/TODO_USE';
 import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 
+/**
+ * META AVATAR / META VISUAL commitment type.
+ */
+type MetaAvatarCommitmentType = 'META AVATAR' | 'META VISUAL';
+
 /**
  * META AVATAR commitment definition
  *
- * The `META AVATAR` commitment sets the built-in default avatar visual used when
- * the agent does not provide an explicit `META IMAGE`.
+ * The `META AVATAR` and `META VISUAL` commitments set the built-in default avatar visual
+ * used when the agent does not provide an explicit `META IMAGE`.
  *
  * @private [🪔] Maybe export the commitments through some package
  */
-export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'META AVATAR'> {
-    public constructor() {
-        super('META AVATAR');
+export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<MetaAvatarCommitmentType> {
+    public constructor(type: MetaAvatarCommitmentType = 'META AVATAR') {
+        super(type);
     }
 
     /**
@@ -38,14 +43,15 @@ export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'ME
         const supportedVisuals = AVATAR_VISUALS.map((avatarVisual) => `\`${avatarVisual.id}\``).join(', ');
 
         return spaceTrim(`
-            # META AVATAR
+            # ${this.type}
 
             Sets the built-in avatar visual used for the agent when no explicit \`META IMAGE\` is provided.
+            \`META AVATAR\` and \`META VISUAL\` are equivalent.
 
             ## Key aspects
 
             - Does not modify the agent's behavior or responses.
-            - Only one \`META AVATAR\` should be used per agent.
+            - Only one \`META AVATAR\` or \`META VISUAL\` should be used per agent.
             - If multiple are specified, the last one takes precedence.
             - Values are matched case-insensitively and spaces, hyphens, and underscores are normalized.
             - Supported visuals are derived from the shared avatar registry: ${supportedVisuals}.
@@ -60,9 +66,9 @@ export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'ME
             \`\`\`
 
             \`\`\`book
-            Orb Assistant
+            Minecraft Assistant
 
-            META AVATAR orb
+            META VISUAL Minecraft2
             GOAL Answer in a calm and focused way.
             \`\`\`
         `);
@@ -71,7 +77,7 @@ export class MetaAvatarCommitmentDefinition extends BaseCommitmentDefinition<'ME
     applyToAgentModelRequirements(requirements: AgentModelRequirements, content: string): AgentModelRequirements {
         TODO_USE(content);
 
-        // META AVATAR doesn't modify the system message or model requirements.
+        // META AVATAR and META VISUAL don't modify the system message or model requirements.
         // It's handled separately in the parsing logic for profile avatar resolution.
         return requirements;
     }

package/src/commitments/USE_CALENDAR/createUseCalendarToolFunctions.ts

@@ -1,10 +1,7 @@
 import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
 import type { string_javascript_name } from '../../types/string_person_fullname';
 import { callGoogleCalendarApi } from './callGoogleCalendarApi';
-import type {
-    UseCalendarToolArgsBase,
-    UseCalendarToolRuntimeResolution,
-} from './resolveUseCalendarToolRuntimeOrWalletCredentialResult';
+import type { UseCalendarToolArgsBase, UseCalendarToolRuntimeResolution } from './resolveUseCalendarToolRuntimeOrWalletCredentialResult';
 import { resolveUseCalendarToolRuntimeOrWalletCredentialResult } from './resolveUseCalendarToolRuntimeOrWalletCredentialResult';
 import { UseCalendarToolNames } from './UseCalendarToolNames';
 

package/src/commitments/USE_PROJECT/createUseProjectToolFunctions.ts

@@ -4,18 +4,10 @@ import type { string_javascript_name } from '../../types/string_person_fullname'
 import { decodeAttachmentAsText, DEFAULT_ATTACHMENT_TEXT_DECODE_BYTES } from '../../utils/files/decodeAttachmentAsText';
 import { extensionToMimeType } from '../../utils/files/extensionToMimeType';
 import { getFileExtension } from '../../utils/files/getFileExtension';
-import type {
-    UseProjectGitHubContentsItem,
-    UseProjectGitHubGitRefResponse,
-    UseProjectGitHubPullRequestResponse,
-    UseProjectGitHubRepositoryResponse,
-} from './callGitHubApi';
+import type { UseProjectGitHubContentsItem, UseProjectGitHubGitRefResponse, UseProjectGitHubPullRequestResponse, UseProjectGitHubRepositoryResponse } from './callGitHubApi';
 import { callGitHubApi } from './callGitHubApi';
 import { normalizeOptionalToolText, normalizeRequiredToolText } from './normalizeOptionalToolText';
-import type {
-    UseProjectToolArgsBase,
-    UseProjectToolRuntimeResolution,
-} from './resolveUseProjectToolRuntimeOrWalletCredentialResult';
+import type { UseProjectToolArgsBase, UseProjectToolRuntimeResolution } from './resolveUseProjectToolRuntimeOrWalletCredentialResult';
 import { resolveUseProjectToolRuntimeOrWalletCredentialResult } from './resolveUseProjectToolRuntimeOrWalletCredentialResult';
 import { UseProjectToolNames } from './UseProjectToolNames';
 

package/src/commitments/USE_TIMEOUT/createTimeoutToolFunctions.ts

@@ -6,17 +6,7 @@ import { getTimeoutToolRuntimeAdapterOrDisabledResult } from './getTimeoutToolRu
 import { parseTimeoutToolArgs } from './parseTimeoutToolArgs';
 import { resolveTimeoutRuntimeContext } from './resolveTimeoutRuntimeContext';
 import { TimeoutToolNames } from './TimeoutToolNames';
-import type {
-    CancelTimeoutToolArgs,
-    CancelTimeoutToolResult,
-    ListTimeoutsToolArgs,
-    ListTimeoutsToolResult,
-    SetTimeoutToolArgs,
-    SetTimeoutToolResult,
-    TimeoutToolListItem,
-    UpdateTimeoutToolArgs,
-    UpdateTimeoutToolResult,
-} from './TimeoutToolRuntimeAdapter';
+import type { CancelTimeoutToolArgs, CancelTimeoutToolResult, ListTimeoutsToolArgs, ListTimeoutsToolResult, SetTimeoutToolArgs, SetTimeoutToolResult, TimeoutToolListItem, UpdateTimeoutToolArgs, UpdateTimeoutToolResult } from './TimeoutToolRuntimeAdapter';
 
 /**
  * Maximum number of timeout rows rendered into the assistant-visible `list_timeouts` message.

package/src/commitments/USE_TIMEOUT/getTimeoutToolRuntimeAdapterOrDisabledResult.ts

@@ -1,10 +1,5 @@
 import { getTimeoutToolRuntimeAdapter } from './setTimeoutToolRuntimeAdapter';
-import type {
-    TimeoutToolAction,
-    TimeoutToolResult,
-    TimeoutToolRuntimeAdapter,
-    TimeoutToolRuntimeContext,
-} from './TimeoutToolRuntimeAdapter';
+import type { TimeoutToolAction, TimeoutToolResult, TimeoutToolRuntimeAdapter, TimeoutToolRuntimeContext } from './TimeoutToolRuntimeAdapter';
 
 /**
  * Builds a disabled timeout-tool payload.

package/src/commitments/USE_TIMEOUT/parseTimeoutToolArgs.ts

@@ -1,11 +1,6 @@
 import { spaceTrim } from 'spacetrim';
 import { PipelineExecutionError } from '../../errors/PipelineExecutionError';
-import type {
-    CancelTimeoutToolArgs,
-    ListTimeoutsToolArgs,
-    SetTimeoutToolArgs,
-    UpdateTimeoutToolArgs,
-} from './TimeoutToolRuntimeAdapter';
+import type { CancelTimeoutToolArgs, ListTimeoutsToolArgs, SetTimeoutToolArgs, UpdateTimeoutToolArgs } from './TimeoutToolRuntimeAdapter';
 
 /**
  * Default number of rows returned by `list_timeouts`.

package/src/commitments/WALLET/createWalletToolFunctions.ts

@@ -1,19 +1,10 @@
 import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutionToolsOptions';
 import type { string_javascript_name } from '../../types/string_person_fullname';
-import {
-    getWalletToolRuntimeAdapterOrDisabledResult,
-    resolveWalletDisabledMessage,
-} from './getWalletToolRuntimeAdapterOrDisabledResult';
+import { getWalletToolRuntimeAdapterOrDisabledResult, resolveWalletDisabledMessage } from './getWalletToolRuntimeAdapterOrDisabledResult';
 import { parseWalletToolArgs } from './parseWalletToolArgs';
 import { resolveWalletRuntimeContext } from './resolveWalletRuntimeContext';
 import { WalletToolNames } from './WalletToolNames';
-import type {
-    DeleteWalletRecordToolArgs,
-    RequestWalletRecordToolArgs,
-    RetrieveWalletRecordsToolArgs,
-    StoreWalletRecordToolArgs,
-    UpdateWalletRecordToolArgs,
-} from './WalletToolRuntimeAdapter';
+import type { DeleteWalletRecordToolArgs, RequestWalletRecordToolArgs, RetrieveWalletRecordsToolArgs, StoreWalletRecordToolArgs, UpdateWalletRecordToolArgs } from './WalletToolRuntimeAdapter';
 
 /**
  * Creates runtime wallet tool function implementations.

package/src/commitments/WALLET/getWalletToolRuntimeAdapterOrDisabledResult.ts

@@ -1,10 +1,5 @@
 import { getWalletToolRuntimeAdapter } from './setWalletToolRuntimeAdapter';
-import type {
-    WalletDisabledToolResult,
-    WalletRuntimeToolAction,
-    WalletToolRuntimeAdapter,
-    WalletToolRuntimeContext,
-} from './WalletToolRuntimeAdapter';
+import type { WalletDisabledToolResult, WalletRuntimeToolAction, WalletToolRuntimeAdapter, WalletToolRuntimeContext } from './WalletToolRuntimeAdapter';
 
 /**
  * Resolves disabled message for wallet runtime context.

package/src/commitments/WALLET/parseWalletToolArgs.ts

@@ -1,13 +1,4 @@
-import type {
-    DeleteWalletRecordToolArgs,
-    RequestWalletRecordToolArgs,
-    RetrieveWalletRecordsToolArgs,
-    StoreWalletRecordToolArgs,
-    UpdateWalletRecordToolArgs,
-    WalletRecordType,
-    WalletRequestRecord,
-    WalletToolRecord,
-} from './WalletToolRuntimeAdapter';
+import type { DeleteWalletRecordToolArgs, RequestWalletRecordToolArgs, RetrieveWalletRecordsToolArgs, StoreWalletRecordToolArgs, UpdateWalletRecordToolArgs, WalletRecordType, WalletRequestRecord, WalletToolRecord } from './WalletToolRuntimeAdapter';
 
 /**
  * Parsed payload for retrieving wallet records.

package/src/commitments/index.ts

@@ -96,6 +96,7 @@ export const COMMITMENT_REGISTRY = [
     new ActionCommitmentDefinition('ACTIONS'),
     new ComponentCommitmentDefinition(),
     new MetaAvatarCommitmentDefinition(),
+    new MetaAvatarCommitmentDefinition('META VISUAL'),
     new MetaImageCommitmentDefinition(),
     new MetaColorCommitmentDefinition(),
     new MetaFontCommitmentDefinition(),

package/src/conversion/parsePipeline/applyPipelineHead.ts

@@ -4,10 +4,10 @@ import { parseCommand } from '../../commands/_common/parseCommand';
 import type { $PipelineJson, CommandBase, PipelineHeadCommandParser } from '../../commands/_common/types/CommandParser';
 import { ParseError } from '../../errors/ParseError';
 import { extractAllListItemsFromMarkdown } from '../../utils/markdown/extractAllListItemsFromMarkdown';
+import type { MarkdownSection } from '../../utils/markdown/parseMarkdownSection';
 import { defineParameter } from './defineParameter';
 import { extractPipelineDescription } from './extractPipelineDescription';
 import { getPipelineIdentification } from './getPipelineIdentification';
-import type { MarkdownSection } from '../../utils/markdown/parseMarkdownSection';
 
 /**
  * Applies the pipeline head title, description, and head-level commands.

package/src/conversion/parsePipeline/createUniqueSectionNameResolver.ts

@@ -1,7 +1,7 @@
 import type { number_integer, number_positive } from '../../types/number_positive';
 import type { string_name } from '../../types/string_name';
-import { titleToName } from '../../utils/normalization/titleToName';
 import type { MarkdownSection } from '../../utils/markdown/parseMarkdownSection';
+import { titleToName } from '../../utils/normalization/titleToName';
 
 /**
  * Resolves a unique task name for one parsed markdown section title.

package/src/conversion/parsePipeline/processPipelineSection.ts

@@ -13,8 +13,8 @@ import { DEFAULT_TASK_TITLE } from '../../config';
 import { ParseError } from '../../errors/ParseError';
 import type { ScriptTaskJson } from '../../pipeline/PipelineJson/ScriptTaskJson';
 import type { TaskJson } from '../../pipeline/PipelineJson/TaskJson';
-import { SUPPORTED_SCRIPT_LANGUAGES } from '../../types/ScriptLanguage';
 import type { ScriptLanguage } from '../../types/ScriptLanguage';
+import { SUPPORTED_SCRIPT_LANGUAGES } from '../../types/ScriptLanguage';
 import { extractAllListItemsFromMarkdown } from '../../utils/markdown/extractAllListItemsFromMarkdown';
 import { extractOneBlockFromMarkdown } from '../../utils/markdown/extractOneBlockFromMarkdown';
 import type { MarkdownSection } from '../../utils/markdown/parseMarkdownSection';

package/src/conversion/validation/validatePipeline/createPipelineValidationContext.ts

@@ -0,0 +1,43 @@
+import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
+
+/**
+ * Shared validation context for one pipeline validation pass.
+ *
+ * @private type of `validatePipeline`
+ */
+export type PipelineValidationContext = {
+    pipeline: PipelineJson;
+    pipelineIdentification: string;
+};
+
+/**
+ * Creates the shared validation context for one pipeline.
+ *
+ * @private function of `validatePipeline`
+ */
+export function createPipelineValidationContext(pipeline: PipelineJson): PipelineValidationContext {
+    return {
+        pipeline,
+        pipelineIdentification: getPipelineIdentification(pipeline),
+    };
+}
+
+/**
+ * Builds a short file/url identification block for validation errors.
+ *
+ * @private internal utility of `validatePipeline`
+ */
+function getPipelineIdentification(pipeline: Pick<PipelineJson, 'sourceFile' | 'pipelineUrl'>): string {
+    // Note: This is a 😐 implementation of [🚞]
+    const pipelineIdentificationParts: Array<string> = [];
+
+    if (pipeline.sourceFile !== undefined) {
+        pipelineIdentificationParts.push(`File: ${pipeline.sourceFile}`);
+    }
+
+    if (pipeline.pipelineUrl !== undefined) {
+        pipelineIdentificationParts.push(`Url: ${pipeline.pipelineUrl}`);
+    }
+
+    return pipelineIdentificationParts.join('\n');
+}

package/src/conversion/validation/validatePipeline/validatePipelineCollectionsStructure.ts

@@ -0,0 +1,72 @@
+import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../errors/ParseError';
+import type { PipelineJson } from '../../../pipeline/PipelineJson/PipelineJson';
+import type { PipelineValidationContext } from './createPipelineValidationContext';
+
+/**
+ * Validates that the expected top-level collections have array structure.
+ *
+ * @private function of `validatePipeline`
+ */
+export function validatePipelineCollectionsStructure({
+    pipeline,
+    pipelineIdentification,
+}: PipelineValidationContext): void {
+    validatePipelineParametersCollection(pipeline, pipelineIdentification);
+    validatePipelineTasksCollection(pipeline, pipelineIdentification);
+}
+
+/**
+ * Validates that `pipeline.parameters` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineParametersCollection(
+    pipeline: Pick<PipelineJson, 'parameters'>,
+    pipelineIdentification: string,
+): void {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.parameters)) {
+        return;
+    }
+
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(
+        spaceTrim(
+            (block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.parameters\` expected to be an array, but got ${typeof pipeline.parameters}
+
+                ${block(pipelineIdentification)}
+            `,
+        ),
+        // <- TODO: [🚞]
+    );
+}
+
+/**
+ * Validates that `pipeline.tasks` is an array.
+ *
+ * @private internal utility of `validatePipelineCollectionsStructure`
+ */
+function validatePipelineTasksCollection(pipeline: Pick<PipelineJson, 'tasks'>, pipelineIdentification: string): void {
+    // TODO: [🧠] Maybe do here some proper JSON-schema / ZOD checking
+    if (Array.isArray(pipeline.tasks)) {
+        return;
+    }
+
+    // TODO: [🧠] what is the correct error tp throw - maybe PromptbookSchemaError
+    throw new ParseError(
+        spaceTrim(
+            (block) => `
+                Pipeline is valid JSON but with wrong structure
+
+                \`PipelineJson.tasks\` expected to be an array, but got ${typeof pipeline.tasks}
+
+                ${block(pipelineIdentification)}
+            `,
+        ),
+        // <- TODO: [🚞]
+    );
+}