@promptbook/cli 0.112.0 → 0.113.0-0

package/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.ts

@@ -61,6 +61,7 @@ const PROFILE_COMMITMENT_TYPES = new Set([
     'META DESCRIPTION',
     'META DISCLAIMER',
     'META INPUT PLACEHOLDER',
+    'META VISIBILITY',
     'META COLOR',
     'META FONT',
     'META VOICE',

package/src/book-components/BookEditor/BookEditorMonacoTokenization.ts

@@ -21,6 +21,16 @@ const AGENT_REFERENCE_AT_PATTERN = '(?<!\\S)@[A-Za-z0-9_-]+';
  */
 const AGENT_REFERENCE_BRACED_PATTERN = '\\{[^{}\\r\\n]+\\}';
 
+/**
+ * Pattern matching plain inline `@` tokens, for example email addresses.
+ *
+ * Monaco tokenizes from the current offset, so `team@foo.bar` can otherwise reach
+ * the `@foo` suffix and look like a standalone compact reference.
+ *
+ * @private function of BookEditorMonaco
+ */
+const NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX = /[^\s{}]*[^\s@{}]@[^\s{}]+/;
+
 /**
  * Commitment types where compact agent references are supported.
  *
@@ -334,6 +344,7 @@ export const BookEditorMonacoTokenization = {
     AGENT_URL_REFERENCE_REGEX,
     AGENT_REFERENCE_TOKEN_REGEX,
     AGENT_REFERENCE_BRACED_REGEX,
+    NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX,
     AGENT_REFERENCE_HIGHLIGHT_REGEXES,
     extractAgentReferenceValue,
     resolveAgentReferenceToUrl,

package/src/book-components/BookEditor/useBookEditorMonacoLanguage.ts

@@ -312,14 +312,17 @@ export function ensureBookEditorMonacoLanguage(
         commitmentRegex,
     );
 
-    const parameterRegex = /@([a-zA-Z0-9_á-žÁ-Žč-řČ-Řš-žŠ-Žа-яА-ЯёЁ]+)/;
+    const PARAMETER_REGEX = /@([a-zA-Z0-9_á-žÁ-Žč-řČ-Řš-žŠ-Žа-яА-ЯёЁ]+)/;
+    const NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX =
+        BookEditorMonacoTokenization.NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX;
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const defaultBodyRules: any = [
         [/^---[-]*$/, ''],
         [CODE_BLOCK_FENCE_REGEX, 'code-block', '@codeblock'],
         ...commitmentTransitionRules,
-        [parameterRegex, 'parameter'],
+        [NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX, ''],
+        [PARAMETER_REGEX, 'parameter'],
         [/\{[^}]+\}/, 'parameter'],
     ];
 
@@ -329,7 +332,8 @@ export function ensureBookEditorMonacoLanguage(
         [CODE_BLOCK_FENCE_REGEX, 'code-block', '@codeblock'],
         ...commitmentTransitionRules,
         ...BookEditorMonacoTokenization.AGENT_REFERENCE_HIGHLIGHT_REGEXES.map((regex) => [regex, 'agent-reference']),
-        [parameterRegex, 'parameter'],
+        [NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX, ''],
+        [PARAMETER_REGEX, 'parameter'],
         [/\{[^}]+\}/, 'parameter'],
     ];
 

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

@@ -45,6 +45,31 @@ const DEFAULT_AGENTS_SERVER_NEXT_DIST_DIRECTORY_NAME = '.next';
  */
 const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
 
+/**
+ * Conservative Next.js build worker count used by CLI-owned Agents Server production builds.
+ *
+ * Standalone VPS self-updates build the replacement server while the current pm2 process is
+ * still serving traffic. Keeping Next's static workers serial avoids CPU-count-based memory
+ * spikes that can make the OS kill the build child with no normal exit code.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_WORKER_COUNT = 1;
+
+/**
+ * Maximum attempts for a Next.js build that was killed by the operating system.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const AGENTS_SERVER_BUILD_MAX_ATTEMPTS = 2;
+
+/**
+ * Signals that indicate the Next.js build may have been terminated by resource pressure.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+const RETRYABLE_NEXT_BUILD_SIGNALS = new Set<NodeJS.Signals | null>(['SIGKILL', null]);
+
 /**
  * Environment variable passed to the bundled Next app so webpack can resolve dependencies
  * installed beside `ptbk` even when the app sources are materialized into a project cache.
@@ -53,6 +78,13 @@ const AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB = 4096;
  */
 export const PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV = 'PTBK_AGENTS_SERVER_NODE_MODULES_PATH';
 
+/**
+ * Environment variable consumed by `apps/agents-server/next.config.ts` to throttle build workers.
+ *
+ * @private internal constant of `ptbk agents-server`
+ */
+export const PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV = 'PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT';
+
 /**
  * Environment variable used only by the CLI-owned production build.
  *
@@ -206,6 +238,16 @@ type AgentsServerBuildCacheOptions = {
     readonly environment?: NodeJS.ProcessEnv;
 };
 
+/**
+ * Exit status reported by one spawned Next.js build child process.
+ *
+ * @private internal type of `ptbk agents-server`
+ */
+type NextBuildExitStatus = {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+};
+
 /**
  * Ensures that the local Agents Server production build exists and matches its source fingerprint.
  *
@@ -358,6 +400,8 @@ export function createAgentsServerRuntimeEnvironment(
         ...environment,
         NODE_PATH: mergeNodePath(nodeModulesPath, environment.NODE_PATH),
         [PTBK_AGENTS_SERVER_NODE_MODULES_PATH_ENV]: nodeModulesPath,
+        [PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV]:
+            environment[PTBK_AGENTS_SERVER_BUILD_WORKER_COUNT_ENV] || String(AGENTS_SERVER_BUILD_WORKER_COUNT),
         ...(options.isNextValidationIgnored
             ? {
                   [PTBK_AGENTS_SERVER_IGNORE_NEXT_VALIDATION_ENV]: 'true',
@@ -626,16 +670,35 @@ async function runNextBuild(options: {
     readonly nextCliPath: string;
     readonly onBuildOutput?: (chunk: string) => void;
 }): Promise<void> {
-    await new Promise<void>((resolveBuild, rejectBuild) => {
+    for (let attempt = 1; attempt <= AGENTS_SERVER_BUILD_MAX_ATTEMPTS; attempt++) {
+        const exitStatus = await runNextBuildAttempt(options);
+
+        if (exitStatus.code === 0) {
+            return;
+        }
+
+        if (attempt < AGENTS_SERVER_BUILD_MAX_ATTEMPTS && isNextBuildTerminationRetryable(exitStatus)) {
+            forwardBuildOutput(createNextBuildRetryMessage(exitStatus, attempt + 1), options.onBuildOutput);
+            continue;
+        }
+
+        throw createNextBuildExitError(exitStatus, attempt);
+    }
+}
+
+/**
+ * Runs one Next.js production build attempt and returns its exit status.
+ */
+async function runNextBuildAttempt(options: {
+    readonly appPath: string;
+    readonly environment: NodeJS.ProcessEnv;
+    readonly nextCliPath: string;
+    readonly onBuildOutput?: (chunk: string) => void;
+}): Promise<NextBuildExitStatus> {
+    return await new Promise<NextBuildExitStatus>((resolveBuild, rejectBuild) => {
         const buildProcess = spawn(process.execPath, [options.nextCliPath, 'build'], {
             cwd: options.appPath,
-            env: {
-                ...options.environment,
-                NODE_OPTIONS: mergeNodeOptionsWithHeapSize(
-                    options.environment.NODE_OPTIONS,
-                    AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB,
-                ),
-            },
+            env: createNextBuildProcessEnvironment(options.environment),
             stdio: ['ignore', 'pipe', 'pipe'],
         });
 
@@ -646,18 +709,83 @@ async function runNextBuild(options: {
             forwardBuildOutput(chunk.toString(), options.onBuildOutput);
         });
 
-        buildProcess.once('error', rejectBuild);
-        buildProcess.once('exit', (code) => {
-            if (code === 0) {
-                resolveBuild();
-                return;
-            }
-
-            rejectBuild(new Error(`next-build exited with code ${String(code)}.`));
+        buildProcess.once('error', (error) => {
+            rejectBuild(createNextBuildSpawnError(error));
+        });
+        buildProcess.once('close', (code, signal) => {
+            resolveBuild({ code, signal });
         });
     });
 }
 
+/**
+ * Creates the environment passed to the spawned Next.js build process.
+ */
+function createNextBuildProcessEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+    return {
+        ...environment,
+        NODE_OPTIONS: mergeNodeOptionsWithHeapSize(environment.NODE_OPTIONS, AGENTS_SERVER_BUILD_MAX_OLD_SPACE_MIB),
+    };
+}
+
+/**
+ * Returns true when one failed build attempt is worth retrying.
+ */
+function isNextBuildTerminationRetryable(exitStatus: NextBuildExitStatus): boolean {
+    return exitStatus.code === null && RETRYABLE_NEXT_BUILD_SIGNALS.has(exitStatus.signal);
+}
+
+/**
+ * Creates one visible retry message for a killed Next.js build attempt.
+ */
+function createNextBuildRetryMessage(exitStatus: NextBuildExitStatus, nextAttempt: number): string {
+    return `\nAgents Server Next build was terminated by ${describeNextBuildExitStatus(exitStatus)}. Retrying attempt ${nextAttempt}/${AGENTS_SERVER_BUILD_MAX_ATTEMPTS}.\n`;
+}
+
+/**
+ * Creates a branded error for a failed Next.js build child process.
+ */
+function createNextBuildExitError(exitStatus: NextBuildExitStatus, attemptCount: number): NotAllowed {
+    const lowMemoryHint = isNextBuildTerminationRetryable(exitStatus)
+        ? '\n\nThe build process was terminated by the operating system. On standalone VPS self-updates this usually means the host ran out of memory while Next.js was compiling or prerendering the app.'
+        : '';
+
+    return new NotAllowed(
+        spaceTrim(`
+            Agents Server Next production build failed.
+
+            - Exit code: \`${String(exitStatus.code)}\`
+            - Signal: \`${String(exitStatus.signal)}\`
+            - Attempts: \`${String(attemptCount)}\`
+            ${lowMemoryHint}
+        `),
+    );
+}
+
+/**
+ * Creates a branded error for failures to start the Next.js build child process.
+ */
+function createNextBuildSpawnError(error: Error): NotAllowed {
+    return new NotAllowed(
+        spaceTrim(`
+            Cannot start the Agents Server Next production build.
+
+            ${error.message}
+        `),
+    );
+}
+
+/**
+ * Formats one Next.js build exit status for foreground logs.
+ */
+function describeNextBuildExitStatus(exitStatus: NextBuildExitStatus): string {
+    if (exitStatus.signal) {
+        return `signal \`${exitStatus.signal}\``;
+    }
+
+    return `exit code \`${String(exitStatus.code)}\``;
+}
+
 /**
  * Prepends `--max-old-space-size=<mib>` to `NODE_OPTIONS` unless the caller already set one.
  */

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

@@ -21,7 +21,10 @@ import {
     type PreparedAgentsServerRuntime,
     resolveAgentsServerAppPath,
 } from './buildAgentsServer';
-import { DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS } from '../../../../apps/agents-server/src/constants/serverLimits';
+import {
+    DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+    DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
+} from '../../../../apps/agents-server/src/constants/serverLimits';
 
 /**
  * Local worker-pump delay while the Agents Server foreground process stays active.
@@ -206,6 +209,7 @@ type PreparedAgentsServerLaunch = {
  */
 type LocalAgentRunnerLimits = {
     readonly maxFailedAttempts: number;
+    readonly maxParallelMessages: number;
 };
 
 /**
@@ -537,6 +541,7 @@ function createLocalAgentRunOptions(
         autoPull: false,
         autoClone: false,
         maxMessageProcessingFailures: localAgentRunnerLimits.maxFailedAttempts,
+        maxParallelMessages: localAgentRunnerLimits.maxParallelMessages,
     };
 }
 
@@ -557,7 +562,7 @@ async function waitForLocalAgentRunnerLimits(options: {
             const limits = await fetchLocalAgentRunnerLimits(options);
             logRunnerEvent(
                 options.logStreams.runner,
-                `Local agent runner max failed attempts: ${limits.maxFailedAttempts}.`,
+                `Local agent runner limits: ${limits.maxFailedAttempts} failed attempt(s), ${limits.maxParallelMessages} parallel message(s).`,
             );
             return limits;
         } catch (error) {
@@ -569,6 +574,7 @@ async function waitForLocalAgentRunnerLimits(options: {
     if (!options.state.isContinuing) {
         return {
             maxFailedAttempts: DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS,
+            maxParallelMessages: DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES,
         };
     }
 
@@ -604,6 +610,7 @@ async function fetchLocalAgentRunnerLimits(options: {
     const payload = (await response.json()) as Partial<LocalAgentRunnerLimits>;
     return {
         maxFailedAttempts: normalizeLocalAgentRunnerMaxFailedAttempts(payload.maxFailedAttempts),
+        maxParallelMessages: normalizeLocalAgentRunnerMaxParallelMessages(payload.maxParallelMessages),
     };
 }
 
@@ -620,6 +627,19 @@ function normalizeLocalAgentRunnerMaxFailedAttempts(rawValue: unknown): number {
     return Math.floor(parsedValue);
 }
 
+/**
+ * Normalizes the local runner parallel message cap returned by the internal server route.
+ */
+function normalizeLocalAgentRunnerMaxParallelMessages(rawValue: unknown): number {
+    const parsedValue = Number(rawValue);
+
+    if (!Number.isFinite(parsedValue) || parsedValue <= 0) {
+        return DEFAULT_LOCAL_AGENT_RUNNER_MAX_PARALLEL_MESSAGES;
+    }
+
+    return Math.floor(parsedValue);
+}
+
 /**
  * Starts periodic internal worker calls that queue and reconcile local message-folder jobs.
  */

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

@@ -4,7 +4,7 @@
 const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
     'coder:generate-boilerplates': 'ptbk coder generate-boilerplates --template ./prompts/templates/common.md',
     'coder:run':
-        'ptbk coder run --harness openai-codex --model gpt-5.4 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
+        'ptbk coder run --harness openai-codex --model gpt-5.5 --thinking-level xhigh --agent agents/developer.book --context AGENTS.md',
     // 'coder:find-refactor-candidates': 'ptbk coder find-refactor-candidates',
     'coder:verify': 'ptbk coder verify',
 } as const satisfies Readonly<Record<string, string>>;

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

@@ -1,6 +1,7 @@
 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 { handleActionErrors } from '../common/handleActionErrors';
@@ -65,6 +66,11 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
     );
     addPromptRunnerExecutionOptions(command);
     command.option('--priority <minimum-priority>', 'Filter prompts by minimum priority level', parseIntOption, 0);
+    command.option(
+        '--limit <run-count>',
+        'Stop after processing this many prompt runs',
+        parsePositiveIntegerOption,
+    );
     command.option(
         '--wait-after-prompt <duration>',
         spaceTrim(`
@@ -110,6 +116,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 test,
                 preserveLogs,
                 priority,
+                limit,
                 waitAfterPrompt: waitAfterPromptValue,
                 waitBetweenPrompts: waitBetweenPromptsValue,
                 waitAfterError: waitAfterErrorValue,
@@ -123,6 +130,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 readonly test?: string | string[];
                 readonly preserveLogs: boolean;
                 readonly priority: number;
+                readonly limit?: number;
                 readonly waitAfterPrompt?: string;
                 readonly waitBetweenPrompts?: string;
                 readonly waitAfterError?: string;
@@ -165,6 +173,7 @@ export function $initializeCoderRunCommand(program: Program): $side_effect {
                 noUi: runnerOptions.noUi,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 priority,
+                limit,
                 normalizeLineEndings: runnerOptions.normalizeLineEndings,
                 allowCredits: runnerOptions.allowCredits,
                 autoMigrate,
@@ -204,6 +213,27 @@ 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/collection/agent-collection/CreateAgentInput.ts

@@ -1,4 +1,9 @@
 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';
@@ -9,14 +14,14 @@ import { spaceTrim } from '../../utils/organization/spaceTrim';
  *
  * @private shared create-agent contract
  */
-export const CREATE_AGENT_VISIBILITY_VALUES = ['PRIVATE', 'UNLISTED', 'PUBLIC'] as const;
+export const CREATE_AGENT_VISIBILITY_VALUES = AGENT_VISIBILITY_VALUES;
 
 /**
  * Supported visibility options for agent creation.
  *
  * @private shared create-agent contract
  */
-export type CreateAgentVisibility = (typeof CREATE_AGENT_VISIBILITY_VALUES)[number];
+export type CreateAgentVisibility = AgentVisibility;
 
 /**
  * Canonical input payload for creating one persisted agent entity.
@@ -244,8 +249,8 @@ function parseOptionalVisibility(rawValue: unknown): CreateAgentVisibility | und
         );
     }
 
-    const isSupportedVisibility = CREATE_AGENT_VISIBILITY_VALUES.includes(rawValue as CreateAgentVisibility);
-    if (!isSupportedVisibility) {
+    const visibility = normalizeAgentVisibility(rawValue);
+    if (!visibility) {
         throw new ParseError(
             spaceTrim(`
                 Invalid create-agent payload.
@@ -255,5 +260,5 @@ function parseOptionalVisibility(rawValue: unknown): CreateAgentVisibility | und
         );
     }
 
-    return rawValue as CreateAgentVisibility;
+    return visibility;
 }

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

@@ -322,7 +322,7 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
     ): Promise<void> {
         const selectPreviousAgentResult = await this.supabaseClient
             .from(this.getTableName('Agent'))
-            .select('agentHash,agentName,permanentId')
+            .select('agentHash,agentName,permanentId,visibility')
             .eq('permanentId', permanentId)
             .single();
 
@@ -343,9 +343,12 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
         const previousAgentName = selectPreviousAgentResult.data.agentName;
         const previousAgentHash = selectPreviousAgentResult.data.agentHash;
         const previousPermanentId = selectPreviousAgentResult.data.permanentId;
+        const previousVisibility = selectPreviousAgentResult.data.visibility;
 
-        const preparedAgentSource = prepareAgentSourceForPersistence(agentSource);
-        const { agentProfile, agentSource: normalizedAgentSource } = preparedAgentSource;
+        const preparedAgentSource = prepareAgentSourceForPersistence(agentSource, {
+            visibility: previousVisibility,
+        });
+        const { agentProfile, agentSource: normalizedAgentSource, visibility } = preparedAgentSource;
         let { permanentId: newPermanentId } = preparedAgentSource;
 
         const { agentHash, agentName } = agentProfile;
@@ -380,6 +383,7 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
                 updatedAt: new Date().toISOString(),
                 agentHash: agentProfile.agentHash,
                 agentSource: normalizedAgentSource,
+                visibility: visibility ?? previousVisibility,
                 promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
             })
             .eq('permanentId', permanentId);

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

@@ -51,8 +51,11 @@ export function createAgentPersistenceRecords(
     options: CreateAgentPersistenceRecordsOptions = {},
     createdAt: string = new Date().toISOString(),
 ): CreateAgentPersistenceRecordsResult {
-    const preparedAgentSource = prepareAgentSourceForPersistence(agentSource);
-    const { agentProfile, agentSource: normalizedAgentSource } = preparedAgentSource;
+    const preparedAgentSource = prepareAgentSourceForPersistence(agentSource, {
+        visibility: options.visibility,
+        isVisibilityOverride: options.visibility !== undefined,
+    });
+    const { agentProfile, agentSource: normalizedAgentSource, visibility } = preparedAgentSource;
     const permanentId = preparedAgentSource.permanentId || $randomBase58(14);
     const { agentName, agentHash } = agentProfile;
 
@@ -74,8 +77,8 @@ export function createAgentPersistenceRecords(
     if (options.sortOrder !== undefined) {
         agentInsertRecord.sortOrder = options.sortOrder;
     }
-    if (options.visibility !== undefined) {
-        agentInsertRecord.visibility = options.visibility;
+    if (visibility !== undefined) {
+        agentInsertRecord.visibility = visibility;
     }
 
     return {

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

@@ -1,8 +1,30 @@
 import type { AgentBasicInformation } from '../../../../book-2.0/agent-source/AgentBasicInformation';
+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';
 import type { string_agent_permanent_id } from '../../../../types/string_agent_name';
 
+/**
+ * Options used while preparing a source for persistence.
+ *
+ * @private shared persistence helper for `AgentCollectionInSupabase`
+ */
+export type PrepareAgentSourceForPersistenceOptions = {
+    /**
+     * Visibility value that should be written into the book when present.
+     */
+    readonly visibility?: AgentVisibility | null;
+    /**
+     * Whether `visibility` should replace an existing `META VISIBILITY` commitment.
+     */
+    readonly isVisibilityOverride?: boolean;
+};
+
 /**
  * Prepared agent source payload ready for database persistence.
  *
@@ -24,6 +46,10 @@ export type PreparedAgentSourceForPersistence = {
      * Permanent id extracted from the original source before stripping `META ID`.
      */
     readonly permanentId: string_agent_permanent_id | undefined;
+    /**
+     * Visibility parsed from the normalized source.
+     */
+    readonly visibility: AgentVisibility | undefined;
 };
 
 /**
@@ -36,20 +62,30 @@ export type PreparedAgentSourceForPersistence = {
  *
  * @private shared persistence helper for `AgentCollectionInSupabase`
  */
-export function prepareAgentSourceForPersistence(agentSource: string_book): PreparedAgentSourceForPersistence {
-    let agentProfile = parseAgentSource(agentSource);
-    const permanentId = agentProfile.permanentId;
+export function prepareAgentSourceForPersistence(
+    agentSource: string_book,
+    options: PrepareAgentSourceForPersistenceOptions = {},
+): PreparedAgentSourceForPersistence {
+    const originalAgentProfile = parseAgentSource(agentSource);
+    const permanentId = originalAgentProfile.permanentId;
 
-    const strippedAgentSource = stripMetaIdLines(agentSource);
-    if (strippedAgentSource !== agentSource) {
-        agentSource = strippedAgentSource;
-        agentProfile = parseAgentSource(agentSource);
-    }
+    agentSource = stripMetaIdLines(agentSource);
+    const sourceVisibility = parseAgentSourceVisibility(agentSource, { isStrict: true });
+    const resolvedVisibility =
+        options.isVisibilityOverride || !sourceVisibility
+            ? options.visibility ?? sourceVisibility ?? DEFAULT_AGENT_VISIBILITY
+            : sourceVisibility;
+
+    agentSource = setAgentSourceVisibility(agentSource, resolvedVisibility);
+
+    const agentProfile = parseAgentSource(agentSource);
+    const visibility = parseAgentSourceVisibility(agentSource, { isStrict: true }) ?? undefined;
 
     return {
         agentProfile,
         agentSource,
         permanentId,
+        visibility,
     };
 }