@promptbook/cli 0.112.0 → 0.113.0-1

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,
     };
 }
 

package/src/commitments/META_VISIBILITY/META_VISIBILITY.ts

@@ -0,0 +1,78 @@
+import { spaceTrim } from 'spacetrim';
+import type { AgentModelRequirements } from '../../book-2.0/agent-source/AgentModelRequirements';
+import { TODO_USE } from '../../utils/organization/TODO_USE';
+import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
+
+/**
+ * META VISIBILITY commitment definition.
+ *
+ * The `META VISIBILITY` commitment stores whether an agent is public, private, or unlisted.
+ * Agents Server mirrors this value into the database for efficient filtering, but the book
+ * commitment remains the editable source of truth.
+ *
+ * @private Metadata-only commitment used by Agents Server.
+ */
+export class MetaVisibilityCommitmentDefinition extends BaseCommitmentDefinition<'META VISIBILITY'> {
+    public constructor() {
+        super('META VISIBILITY');
+    }
+
+    /**
+     * Short one-line description of META VISIBILITY.
+     */
+    get description(): string {
+        return 'Set whether the agent is private, unlisted, or public.';
+    }
+
+    /**
+     * Icon for this commitment.
+     */
+    get icon(): string {
+        return '👁️';
+    }
+
+    /**
+     * Markdown documentation for META VISIBILITY commitment.
+     */
+    get documentation(): string {
+        return spaceTrim(`
+            # META VISIBILITY
+
+            Sets the agent visibility used by Agents Server.
+
+            ## Allowed values
+
+            - \`PRIVATE\` - accessible only to signed-in users with access.
+            - \`UNLISTED\` - accessible by direct link but hidden from public listings.
+            - \`PUBLIC\` - visible in public listings and accessible by anyone.
+
+            ## Key aspects
+
+            - Does not modify the agent's behavior, system message, or tools.
+            - Whitespace and letter case are normalized when persisted.
+            - If multiple \`META VISIBILITY\` commitments are present, persistence keeps one normalized value.
+            - Agents Server mirrors the value into the database for filtering, but the book is the source of truth.
+
+            ## Example
+
+            \`\`\`book
+            Helpful Assistant
+
+            GOAL Be helpful and friendly.
+            META VISIBILITY PUBLIC
+            \`\`\`
+        `);
+    }
+
+    public applyToAgentModelRequirements(
+        requirements: AgentModelRequirements,
+        content: string,
+    ): AgentModelRequirements {
+        TODO_USE(content);
+
+        // META VISIBILITY is metadata only and does not alter model requirements.
+        return requirements;
+    }
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/commitments/index.ts

@@ -28,6 +28,7 @@ import { MetaFontCommitmentDefinition } from './META_FONT/META_FONT';
 import { MetaImageCommitmentDefinition } from './META_IMAGE/META_IMAGE';
 import { MetaInputPlaceholderCommitmentDefinition } from './META_INPUT_PLACEHOLDER/META_INPUT_PLACEHOLDER';
 import { MetaLinkCommitmentDefinition } from './META_LINK/META_LINK';
+import { MetaVisibilityCommitmentDefinition } from './META_VISIBILITY/META_VISIBILITY';
 import { MetaVoiceCommitmentDefinition } from './META_VOICE/META_VOICE';
 import { ModelCommitmentDefinition } from './MODEL/MODEL';
 import { NoteCommitmentDefinition } from './NOTE/NOTE';
@@ -102,6 +103,7 @@ export const COMMITMENT_REGISTRY = [
     new MetaDomainCommitmentDefinition(),
     new MetaDisclaimerCommitmentDefinition(),
     new MetaInputPlaceholderCommitmentDefinition(),
+    new MetaVisibilityCommitmentDefinition(),
     new MetaCommitmentDefinition(),
     new MetaVoiceCommitmentDefinition(),
     new NoteCommitmentDefinition('NOTE'),