@promptbook/cli 0.112.0-69 → 0.112.0-71

package/esm/scripts/run-agent-messages/main/listLocalAgentRunnerProjects.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One local direct-child repository that looks like a Promptbook agent runner project.
+ */
+export type LocalAgentRunnerProject = {
+    readonly directoryName: string;
+    readonly projectPath: string;
+};
+/**
+ * Lists local agent runner repositories from direct child directories of the given root.
+ */
+export declare function listLocalAgentRunnerProjects(rootPath: string): Promise<ReadonlyArray<LocalAgentRunnerProject>>;

package/esm/scripts/run-agent-messages/main/loadAgentMessageQueueSnapshot.d.ts

@@ -0,0 +1,25 @@
+import type { AgentMessageFile } from '../messages/AgentMessageFile';
+/**
+ * Queue counts and files used to render the agent-run dashboard.
+ */
+export type AgentMessageQueueSnapshot = {
+    readonly queuedMessages: ReadonlyArray<AgentMessageFile>;
+    readonly finishedMessageCount: number;
+};
+/**
+ * Reads current queued and finished message counts for the agent dashboard.
+ */
+export declare function loadAgentMessageQueueSnapshot(projectPath: string): Promise<AgentMessageQueueSnapshot>;
+/**
+ * Converts agent queue counts into the prompt-style snapshot used by the shared rich UI state.
+ */
+export declare function createAgentQueueProgressSnapshot(queueSnapshot: AgentMessageQueueSnapshot): {
+    done: number;
+    forAgent: number;
+    belowMinimumPriority: number;
+    toBeWritten: number;
+};
+/**
+ * Returns the normalized queued-messages path shown in the UI.
+ */
+export declare function getQueuedAgentMessagesDirectoryLabel(): string;

package/esm/scripts/run-agent-messages/main/pullLatestChangesForAgentQueueIfEnabled.d.ts

@@ -5,5 +5,5 @@ import type { AgentRunOptions } from '../AgentRunOptions';
 export declare function pullLatestChangesForAgentQueueIfEnabled(options: {
     readonly projectPath: string;
     readonly runOptions: AgentRunOptions;
-    readonly logMessage: string;
+    readonly logMessage?: string;
 }): Promise<number | undefined>;

package/esm/scripts/run-agent-messages/main/runAgentMessages.d.ts

@@ -2,4 +2,6 @@ import type { AgentRunOptions } from '../AgentRunOptions';
 /**
  * Watches the queued message directory and answers messages one by one.
  */
-export declare function runAgentMessages(options: AgentRunOptions): Promise<void>;
+export declare function runAgentMessages(options: AgentRunOptions, controls?: {
+    readonly shouldContinue?: () => boolean;
+}): Promise<void>;

package/esm/scripts/run-agent-messages/main/runMultipleAgentMessages.d.ts

@@ -0,0 +1,7 @@
+import type { AgentRunOptions } from '../AgentRunOptions';
+/**
+ * Watches all direct child agent repositories from the current directory in one shared session.
+ */
+export declare function runMultipleAgentMessages(options: AgentRunOptions, controls?: {
+    readonly shouldContinue?: () => boolean;
+}): Promise<void>;

package/esm/scripts/run-agent-messages/main/shouldRunPeriodicTask.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns true when one periodic background task should run now.
+ */
+export declare function shouldRunPeriodicTask(options: {
+    readonly lastRunTimestamp: number | undefined;
+    readonly intervalMs: number;
+}): boolean;

package/esm/scripts/run-agent-messages/main/synchronizeGithubAgentRunnerRepositories.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Environment variable carrying the GitHub token used to discover and clone agent repositories.
+ */
+export declare const PROMPTBOOK_AGENT_RUNNER_GITHUB_TOKEN_ENV = "PROMPTBOOK_AGENT_RUNNER_GITHUB_TOKEN";
+/**
+ * Environment variable carrying the GitHub owner whose `agent-*` repositories should be mirrored locally.
+ */
+export declare const PROMPTBOOK_AGENT_RUNNER_GITHUB_OWNER_ENV = "PROMPTBOOK_AGENT_RUNNER_GITHUB_OWNER";
+/**
+ * Result of one GitHub synchronization round.
+ */
+export type GithubAgentRunnerRepositoriesSynchronizationResult = {
+    readonly clonedRepositoryNames: ReadonlyArray<string>;
+    readonly owner?: string;
+    readonly synchronizedAt?: number;
+};
+/**
+ * Loads the optional GitHub repository-mirroring configuration for multi-agent runs.
+ */
+export declare function loadAgentRunnerGithubConfiguration(): {
+    readonly token: string;
+    readonly owner: string;
+} | null;
+/**
+ * Clones missing `agent-*` repositories from the configured GitHub owner into the direct child directories of `rootPath`.
+ */
+export declare function synchronizeGithubAgentRunnerRepositories(rootPath: string): Promise<GithubAgentRunnerRepositoriesSynchronizationResult>;

package/esm/scripts/run-agent-messages/main/tickAgentMessages.d.ts

@@ -1,8 +1,9 @@
+import { type CoderRunUiHandle } from '../../run-codex-prompts/ui/renderCoderRunUi';
 import type { AgentRunOptions } from '../AgentRunOptions';
 import type { AgentMessageFile } from '../messages/AgentMessageFile';
 import { type FinishedAgentMessageFile } from '../messages/moveAgentMessageToFinished';
 /**
- * Result of one `ptbk agent tick` invocation.
+ * Result of one `ptbk agent run-once` invocation.
  */
 export type AgentTickResult = {
     readonly isMessageProcessed: boolean;
@@ -15,6 +16,7 @@ export type AgentTickResult = {
  */
 export type TickAgentMessagesOptions = {
     readonly isQuietWhenIdle?: boolean;
+    readonly uiHandle?: CoderRunUiHandle;
 };
 /**
  * Answers one queued `.book` message thread and moves it to `messages/finished`.

package/esm/scripts/run-agent-messages/main/validateAgentWatchOptions.d.ts

@@ -0,0 +1,5 @@
+import type { AgentRunOptions } from '../AgentRunOptions';
+/**
+ * Validates constraints specific to never-ending agent watch loops.
+ */
+export declare function validateAgentWatchOptions(commandDisplayName: string, options: AgentRunOptions): void;

package/esm/scripts/run-agent-messages/main/withCurrentWorkingDirectory.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Runs one async callback from a temporary current working directory and always restores the previous directory.
+ */
+export declare function withCurrentWorkingDirectory<T>(directoryPath: string, callback: () => Promise<T>): Promise<T>;

package/esm/scripts/run-agent-messages/ui/buildAgentRunInitialsVisual.d.ts

@@ -1,4 +1,4 @@
 /**
- * Builds a compact centered initials banner for `ptbk agent run`.
+ * Builds a compact centered banner that shows the local agent name.
  */
 export declare function buildAgentRunInitialsVisual(agentName: string, totalWidth: number): readonly string[];

package/esm/scripts/run-agent-messages/ui/initializeAgentRunUi.d.ts

@@ -0,0 +1,15 @@
+import type { AgentRunOptions } from '../AgentRunOptions';
+import { type AgentMessageQueueSnapshot } from '../main/loadAgentMessageQueueSnapshot';
+import { type CoderRunUiHandle } from '../../run-codex-prompts/ui/renderCoderRunUi';
+/**
+ * Creates and seeds the persistent rich terminal UI used by `ptbk agent run`.
+ */
+export declare function initializeAgentRunUi(projectPath: string, options: AgentRunOptions, queueSnapshot: AgentMessageQueueSnapshot): Promise<CoderRunUiHandle | undefined>;
+/**
+ * Updates the persistent rich UI to the idle watch state.
+ */
+export declare function updateAgentRunUiForWatching(uiHandle: CoderRunUiHandle, queueSnapshot: AgentMessageQueueSnapshot, statusMessage?: string): void;
+/**
+ * Updates the persistent rich UI while the runner refreshes the queue repository.
+ */
+export declare function updateAgentRunUiForPulling(uiHandle: CoderRunUiHandle, queueSnapshot: AgentMessageQueueSnapshot, statusMessage: string): void;

package/esm/scripts/run-agent-messages/ui/loadAgentRunUiMetadata.d.ts

@@ -10,6 +10,10 @@ export type AgentRunUiMetadata = {
  * Reads the local agent title and latest queued user message for the rich agent dashboard.
  */
 export declare function loadAgentRunUiMetadata(projectPath: string, queuedMessage: AgentMessageFile): Promise<AgentRunUiMetadata>;
+/**
+ * Reads the local `agent.book` title and falls back to a stable generic name when unavailable.
+ */
+export declare function readLocalAgentName(projectPath: string): Promise<string>;
 /**
  * Extracts the latest `MESSAGE @User` block while preserving the original line breaks.
  */

package/esm/scripts/run-codex-prompts/git/agentGitIdentity.d.ts

@@ -25,3 +25,7 @@ export declare function buildAgentGitSigningFlag(identity?: AgentGitIdentity | u
  * Prints a one-time style tip when coding-agent commits fall back to the user's default Git configuration.
  */
 export declare function printAgentGitIdentityTipIfNeeded(): void;
+/**
+ * Defers the coding-agent Git identity tip until process shutdown so long-running UIs stay uninterrupted.
+ */
+export declare function printAgentGitIdentityTipAtProcessExitIfNeeded(): void;

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -7,7 +7,7 @@ import type { AvatarDefinition } from './AvatarDefinition';
  *
  * @private shared contract for the avatar rendering system
  */
-export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
+export type AvatarVisualId = 'pixel-art' | 'octopus' | 'octopus2' | 'octopus3' | 'octopus3d' | 'ascii-octopus' | 'minecraft' | 'minecraft2' | 'fractal' | 'orb';
 /**
  * Derived color palette used by avatar visuals.
  *

package/esm/src/avatars/visuals/avatar3dProjectionShared.d.ts

@@ -0,0 +1,141 @@
+/**
+ * One 3D point used by the shared avatar projection helpers.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export type Point3D = {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+};
+/**
+ * One projected 2D point derived from scene-space 3D coordinates.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export type ProjectedPoint = {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+};
+/**
+ * Default camera distance ratio shared by the proper-3D avatar visuals.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare const DEFAULT_3D_CAMERA_DISTANCE_RATIO = 1.4;
+/**
+ * Clamps one number into the provided range.
+ *
+ * @param value Input value.
+ * @param minimumValue Inclusive lower bound.
+ * @param maximumValue Inclusive upper bound.
+ * @returns Clamped value.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function clampNumber(value: number, minimumValue: number, maximumValue: number): number;
+/**
+ * Rotates one point around the local Y axis.
+ *
+ * @param point Source point.
+ * @param angle Rotation angle in radians.
+ * @returns Rotated point.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function rotatePointAroundY(point: Point3D, angle: number): Point3D;
+/**
+ * Rotates one point around the local X axis.
+ *
+ * @param point Source point.
+ * @param angle Rotation angle in radians.
+ * @returns Rotated point.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function rotatePointAroundX(point: Point3D, angle: number): Point3D;
+/**
+ * Applies the local rotations and translation to one scene point.
+ *
+ * @param localPoint Point in local object space.
+ * @param center Object center in scene space.
+ * @param rotationX Object pitch in radians.
+ * @param rotationY Object yaw in radians.
+ * @returns Transformed scene-space point.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function transformScenePoint(localPoint: Point3D, center: Point3D, rotationX: number, rotationY: number): Point3D;
+/**
+ * Projects one scene point into canvas coordinates.
+ *
+ * @param point Scene-space point.
+ * @param size Canvas size in CSS pixels.
+ * @param sceneCenterX Horizontal scene center.
+ * @param sceneCenterY Vertical scene center.
+ * @param cameraDistanceRatio Optional camera distance ratio.
+ * @returns Projected point.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function projectScenePoint(point: Point3D, size: number, sceneCenterX: number, sceneCenterY: number, cameraDistanceRatio?: number): ProjectedPoint;
+/**
+ * Interpolates between two projected points.
+ *
+ * @param startPoint Start point.
+ * @param endPoint End point.
+ * @param ratio Interpolation ratio in the range `[0, 1]`.
+ * @returns Interpolated projected point.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function interpolateProjectedPoint(startPoint: ProjectedPoint, endPoint: ProjectedPoint, ratio: number): ProjectedPoint;
+/**
+ * Subtracts one 3D point from another.
+ *
+ * @param leftPoint Left point.
+ * @param rightPoint Right point.
+ * @returns Difference vector.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function subtractPoint3D(leftPoint: Point3D, rightPoint: Point3D): Point3D;
+/**
+ * Computes the 3D cross product of two vectors.
+ *
+ * @param leftVector Left vector.
+ * @param rightVector Right vector.
+ * @returns Cross product.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function crossProduct3D(leftVector: Point3D, rightVector: Point3D): Point3D;
+/**
+ * Computes the 3D dot product of two vectors.
+ *
+ * @param leftVector Left vector.
+ * @param rightVector Right vector.
+ * @returns Dot product.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function dotProduct3D(leftVector: Point3D, rightVector: Point3D): number;
+/**
+ * Normalizes one 3D vector while keeping zero vectors stable.
+ *
+ * @param vector Source vector.
+ * @returns Normalized vector.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function normalizeVector3(vector: Point3D): Point3D;
+/**
+ * Measures the perimeter of one projected quad.
+ *
+ * @param corners Quad corners.
+ * @returns Perimeter length.
+ *
+ * @private helper of the 3D avatar visuals
+ */
+export declare function getProjectedQuadPerimeter(corners: readonly [ProjectedPoint, ProjectedPoint, ProjectedPoint, ProjectedPoint]): number;

package/esm/src/avatars/visuals/octopus3dAvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Proper 3D Octopus visual built from projected organic meshes and tentacles.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopus3dAvatarVisual: AvatarVisualDefinition;

package/esm/src/cli/cli-commands/agent/agentProjectPaths.d.ts

@@ -11,13 +11,13 @@ export declare const AGENT_BOOK_FILE_PATH = "agent.book";
  */
 export declare const AGENT_MESSAGES_DIRECTORY_PATH = "messages";
 /**
- * Relative path to queued user messages consumed by `ptbk agent tick`.
+ * Relative path to queued user messages consumed by `ptbk agent run-once`.
  *
  * @private internal utility of `ptbk agent`
  */
 export declare const AGENT_QUEUED_MESSAGES_DIRECTORY_PATH: string;
 /**
- * Relative path to answered messages written by `ptbk agent tick`.
+ * Relative path to answered messages written by `ptbk agent run-once`.
  *
  * @private internal utility of `ptbk agent`
  */

package/esm/src/cli/cli-commands/agent/initializeAgentRunnerCommand.d.ts

@@ -0,0 +1,22 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { createAgentRunOptionsFromCliOptions } from './agentRunCliOptions';
+/**
+ * Shared command-registration options for `ptbk agent` runner subcommands.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+type InitializeAgentRunnerCommandOptions = {
+    readonly commandName: string;
+    readonly aliases?: ReadonlyArray<string>;
+    readonly summary: string;
+    readonly featureLines: ReadonlyArray<string>;
+    readonly loadExecutor: () => Promise<(runOptions: ReturnType<typeof createAgentRunOptionsFromCliOptions>) => Promise<unknown>>;
+};
+/**
+ * Registers one runner-backed `ptbk agent` subcommand with the shared option and error handling flow.
+ *
+ * @private internal utility of `ptbk agent`
+ */
+export declare function $initializeAgentRunnerCommand(program: Program, options: InitializeAgentRunnerCommandOptions): $side_effect;
+export {};

package/esm/src/cli/cli-commands/agent/runMultiple.d.ts

@@ -0,0 +1,10 @@
+import type { Command as Program } from 'commander';
+import type { $side_effect } from '../../../utils/organization/$side_effect';
+/**
+ * Initializes `agent run-multiple` command for Promptbook CLI utilities.
+ *
+ * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
+ *
+ * @private internal function of `promptbookCli`
+ */
+export declare function $initializeAgentRunMultipleCommand(program: Program): $side_effect;

package/esm/src/cli/cli-commands/agent.d.ts

@@ -5,8 +5,9 @@ import type { $side_effect } from '../../utils/organization/$side_effect';
  *
  * The agent command provides utilities for repository-backed message queues:
  * - init: Initialize local agent queue and instruction files
- * - tick: Answer one queued message and exit
- * - run: Watch the queue and answer messages one by one
+ * - run-once (alias: tick): Answer one queued message and exit
+ * - run-agent (alias: run): Watch one queue and answer messages one by one
+ * - run-multiple: Watch direct child agent repositories in one shared session
  *
  * Note: `$` is used to indicate that this function is not a pure function - it registers a command in the CLI.
  *

package/esm/src/cli/other/install.test.d.ts

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

package/esm/src/commitments/USE_TIMEOUT/USE_TIMEOUT.d.ts

@@ -3,7 +3,7 @@ import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutio
 import type { string_javascript_name } from '../../types/string_person_fullname';
 import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 export { setTimeoutToolRuntimeAdapter } from './setTimeoutToolRuntimeAdapter';
-export type { CancelTimeoutToolResult, ListTimeoutsToolResult, SetTimeoutToolResult, TimeoutToolListItem, TimeoutToolRuntimeAdapter, TimeoutToolRuntimeContext, UpdateTimeoutToolResult } from './TimeoutToolRuntimeAdapter';
+export type { CancelTimeoutToolResult, ListTimeoutsToolResult, SetTimeoutToolResult, TimeoutToolListItem, TimeoutToolRuntimeAdapter, TimeoutToolRuntimeContext, UpdateTimeoutToolResult, } from './TimeoutToolRuntimeAdapter';
 /**
  * `USE TIMEOUT` commitment definition.
  *

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

@@ -3,7 +3,7 @@ import type { ToolFunction } from '../../scripting/javascript/JavascriptExecutio
 import type { string_javascript_name } from '../../types/string_person_fullname';
 import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 export { setWalletToolRuntimeAdapter } from './setWalletToolRuntimeAdapter';
-export type { WalletRecordType, WalletToolRecord, WalletToolRuntimeAdapter, WalletToolRuntimeContext } from './WalletToolRuntimeAdapter';
+export type { WalletRecordType, WalletToolRecord, WalletToolRuntimeAdapter, WalletToolRuntimeContext, } from './WalletToolRuntimeAdapter';
 /**
  * WALLET commitment definition.
  *

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-68`).
+ * It follows semantic versioning (e.g., `0.112.0-70`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/cli",
-    "version": "0.112.0-69",
+    "version": "0.112.0-71",
     "description": "Promptbook: Create persistent AI agents that turn your company's scattered knowledge into action",
     "private": false,
     "sideEffects": false,