@promptbook/cli 0.113.0-0 → 0.113.0-10

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/boilerplateTemplates.ts

@@ -120,26 +120,26 @@ const DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS = [
         id: 'common',
         relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'common.md'),
         slugPrefix: null,
-        content: buildCoderPromptTemplateContent([
-            '-   @@@',
-            "-   Keep in mind the DRY _(don't repeat yourself)_ principle.",
-            '-   Do a proper analysis of the current functionality before you start implementing.',
-            '-   Add the changes into the [changelog](changelog/_current-preversion.md)',
-        ]),
+        content: spaceTrim(`
+            -   @@@
+            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
+            -   Do a proper analysis of the current functionality before you start implementing.
+            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+        `),
         isDefaultProjectTemplate: true,
     },
     {
         id: 'agents-server',
         relativeFilePath: join(PROMPTS_TEMPLATES_DIRECTORY_PATH, 'agents-server.md'),
         slugPrefix: 'agents-server',
-        content: buildCoderPromptTemplateContent([
-            '-   @@@',
-            "-   Keep in mind the DRY _(don't repeat yourself)_ principle.",
-            '-   Do a proper analysis of the current functionality before you start implementing.',
-            '-   You are working with the [Agents Server](apps/agents-server)',
-            '-   If you need to do the database migration, do it',
-            '-   Add the changes into the [changelog](changelog/_current-preversion.md)',
-        ]),
+        content: spaceTrim(`
+            -   @@@
+            -   Keep in mind the DRY _(don't repeat yourself)_ principle.
+            -   Do a proper analysis of the current functionality before you start implementing.
+            -   You are working with the [Agents Server](apps/agents-server)
+            -   If you need to do the database migration, do it
+            -   Add the changes into the [changelog](changelog/_current-preversion.md)
+        `),
         isDefaultProjectTemplate: false,
     },
 ] as const satisfies ReadonlyArray<CoderPromptTemplateDefinition>;
@@ -288,13 +288,6 @@ function getDefaultCoderPromptTemplateDefinitionOrUndefined(
     return DEFAULT_CODER_PROMPT_TEMPLATE_DEFINITIONS.find((definition) => definition.id === template);
 }
 
-/**
- * Builds stable markdown content for one coder prompt template without indentation drift.
- */
-function buildCoderPromptTemplateContent(lines: ReadonlyArray<string>): string {
-    return lines.join('\n');
-}
-
 /**
  * Creates a fully resolved template payload from one built-in definition.
  */

package/src/cli/cli-commands/coder/find-refactor-candidates.ts

@@ -12,6 +12,7 @@ import {
 } from '../../../../scripts/find-refactor-candidates/RefactorCandidateLevel';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 
 /**
@@ -44,11 +45,17 @@ export function $initializeCoderFindRefactorCandidatesCommand(program: Program):
             .choices([...REFACTOR_CANDIDATE_LEVEL_VALUES])
             .default(DEFAULT_REFACTOR_CANDIDATE_LEVEL),
     );
+    command.option(
+        '--limit <candidate-count>',
+        'Create at most this many refactor prompts, keeping the most important candidates',
+        createPositiveIntegerOptionParser('--limit'),
+    );
 
     command.action(
         handleActionErrors(async (cliOptions) => {
-            const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL } = cliOptions as {
+            const { level = DEFAULT_REFACTOR_CANDIDATE_LEVEL, limit } = cliOptions as {
                 readonly level?: RefactorCandidateLevel;
+                readonly limit?: number;
             };
 
             // Note: Import the function dynamically to avoid loading heavy dependencies until needed
@@ -57,7 +64,7 @@ export function $initializeCoderFindRefactorCandidatesCommand(program: Program):
             );
 
             try {
-                await findRefactorCandidates({ level });
+                await findRefactorCandidates({ level, limit });
             } catch (error) {
                 assertsError(error);
                 console.error(colors.bgRed(`${error.name}`));

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,17 +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 { 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 {
-    CODER_AGENTS_DIRECTORY_PATH,
-    ensureCoderDeveloperAgentFile,
-} from './ensureCoderDeveloperAgentFile';
 import { ensureCoderGitignoreFile } from './ensureCoderGitignoreFile';
 import { ensureCoderMarkdownFile } from './ensureCoderMarkdownFile';
 import { ensureCoderPackageJsonFile } from './ensureCoderPackageJsonFile';

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

@@ -1,9 +1,9 @@
 import colors from 'colors';
 import { Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */ } from 'commander';
 import { spaceTrim } from 'spacetrim';
-import { NotAllowed } from '../../../errors/NotAllowed';
 import { assertsError } from '../../../errors/assertsError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { createPositiveIntegerOptionParser } from '../common/createPositiveIntegerOptionParser';
 import { handleActionErrors } from '../common/handleActionErrors';
 import type { PromptRunnerCliOptions } from '../common/promptRunnerCliOptions';
 import {
@@ -12,10 +12,7 @@ import {
     normalizePromptRunnerCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
-import {
-    DEFAULT_WAIT_AFTER_ERROR_MS,
-    parseOptionalWaitDuration,
-} from './waitOptions';
+import { DEFAULT_WAIT_AFTER_ERROR_MS, parseOptionalWaitDuration } from './waitOptions';
 
 /**
  * Initializes `coder run` command for Promptbook CLI utilities
@@ -69,7 +66,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     command.option(
         '--limit <run-count>',
         'Stop after processing this many prompt runs',
-        parsePositiveIntegerOption,
+        createPositiveIntegerOptionParser('--limit'),
     );
     command.option(
         '--wait-after-prompt <duration>',
@@ -213,27 +210,6 @@ function parseIntOption(value: string): number {
     return parsed;
 }
 
-/**
- * Parses a positive integer option value.
- *
- * @private internal utility of `coder run` command
- */
-function parsePositiveIntegerOption(value: string): number {
-    const parsed = Number(value);
-
-    if (!Number.isInteger(parsed) || parsed <= 0) {
-        throw new NotAllowed(
-            spaceTrim(`
-                Invalid value for \`--limit\`: \`${value}\`.
-
-                Use a positive integer.
-            `),
-        );
-    }
-
-    return parsed;
-}
-
 /**
  * Joins one Commander option that may be parsed either as a single string or a variadic token array.
  *

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/createPositiveIntegerOptionParser.ts

@@ -0,0 +1,31 @@
+import { spaceTrim } from 'spacetrim';
+import { NotAllowed } from '../../../errors/NotAllowed';
+
+/**
+ * Creates a Commander argument parser that accepts only positive integers.
+ *
+ * The returned parser is meant to be passed as the coercion callback of `command.option(...)`.
+ * It throws a branded `NotAllowed` error with a clear message referencing the given option name
+ * when the provided value is not a positive integer.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+export function createPositiveIntegerOptionParser(optionName: string): (value: string) => number {
+    return (value: string): number => {
+        const parsedValue = Number(value);
+
+        if (!Number.isInteger(parsedValue) || parsedValue <= 0) {
+            throw new NotAllowed(
+                spaceTrim(`
+                    Invalid value for \`${optionName}\`: \`${value}\`.
+
+                    Use a positive integer.
+                `),
+            );
+        }
+
+        return parsedValue;
+    };
+}
+
+// Note: [🟡] Code for CLI option parser [createPositiveIntegerOptionParser](src/cli/cli-commands/common/createPositiveIntegerOptionParser.ts) should never be published outside of `@promptbook/cli`

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/cli/promptbookCli.ts

@@ -48,6 +48,13 @@ const DEPRECATED_TOP_LEVEL_COMMAND_MESSAGES: Readonly<Record<string, string>> =
     'start-pipelines-server': OLD_PIPELINE_SYSTEM_DEPRECATION_MESSAGE,
 };
 
+/**
+ * Raw top-level CLI arguments that print the Promptbook version.
+ *
+ * @private internal constant of `promptbookCli`
+ */
+const VERSION_OPTION_ARGUMENTS: ReadonlySet<string> = new Set(['-v', '--version']);
+
 /**
  * Runs CLI utilities of Promptbook package
  *
@@ -65,8 +72,15 @@ export async function promptbookCli(): Promise<void> {
         );
     }
 
-    const cliArguments = process.argv.slice(2);
-    const isVerbose = cliArguments.some((arg) => arg === '--verbose' || arg === '-v');
+    const commandLineArguments = process.argv.slice(2);
+    const isVersionRequested = isTopLevelVersionRequested(commandLineArguments);
+
+    if (isVersionRequested) {
+        console.info(PROMPTBOOK_ENGINE_VERSION);
+        return process.exit(0);
+    }
+
+    const isVerbose = commandLineArguments.some((argument) => argument === '--verbose' || argument === '-v');
     //     <- TODO: Can be this be done with commander before the commander commands are initialized?
     if (isVerbose) {
         console.info(
@@ -104,7 +118,7 @@ export async function promptbookCli(): Promise<void> {
     // TODO: [🧠] Should it be here or not> $addGlobalOptionsToCommand(program);
     program.commands.forEach($addGlobalOptionsToCommand);
 
-    if (cliArguments.length === 0) {
+    if (commandLineArguments.length === 0) {
         program.outputHelp();
         return process.exit(0);
     }
@@ -112,6 +126,17 @@ export async function promptbookCli(): Promise<void> {
     program.parse(process.argv);
 }
 
+/**
+ * Checks whether the invocation asks for the root Promptbook CLI version.
+ *
+ * @private internal utility of `promptbookCli`
+ */
+function isTopLevelVersionRequested(commandLineArguments: ReadonlyArray<string>): boolean {
+    const firstCommandLineArgument = commandLineArguments[0];
+
+    return firstCommandLineArgument !== undefined && VERSION_OPTION_ARGUMENTS.has(firstCommandLineArgument);
+}
+
 /**
  * Adds one deprecation notice to each configured top-level legacy command.
  */

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/TEAM/TEAM.ts

@@ -113,10 +113,10 @@ const teamToolTitles: Record<string_javascript_name, string> = {};
  *
  * @private
  */
-const TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES = [
-    '-   If a teammate is relevant to the request, consult that teammate using the matching tool.',
-    '-   Do not ask the user for information that a listed teammate can provide directly.',
-] as const;
+const TEAM_SYSTEM_MESSAGE_GUIDANCE = spaceTrim(`
+    -   If a teammate is relevant to the request, consult that teammate using the matching tool.
+    -   Do not ask the user for information that a listed teammate can provide directly.
+`);
 /**
  * Constant for remote agents by Url.
  */
@@ -352,7 +352,7 @@ function buildTeamSystemMessageBody(teamEntries: ReadonlyArray<TeamToolEntry>):
 
     return spaceTrim(
         (block) => `
-            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE_LINES.join('\n'))}
+            ${block(TEAM_SYSTEM_MESSAGE_GUIDANCE)}
 
             ${block(teammateSections.join('\n\n'))}
         `,

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.