@promptbook/cli 0.114.0-2 → 0.114.0-21

package/umd/src/utils/agent-message-runtime/resolveAgentMessageTouchedExternalSources.test.d.ts

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

package/umd/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolves which projects one coding harness touched while answering a single message.
+ *
+ * The runtime log streams what the harness really did, so a project counts as touched when the
+ * harness named it in a tool invocation — reading, searching, running, or editing files inside
+ * `projects/<project-name>/`. Only tool payloads are inspected: tool results and assistant
+ * narration are ignored so a project merely mentioned in the conversation is never reported.
+ *
+ * Every candidate is matched against the projects that really exist, which both filters prompt
+ * placeholders such as `projects/<project-name>/` and keeps the reported names canonical.
+ *
+ * @param options - Raw runtime log content and the project directory names of the agent.
+ * @returns Touched project names in the canonical spelling, ordered by first appearance.
+ * @private internal utility of the agent-message runtime
+ */
+export declare function resolveAgentMessageTouchedProjectNames(options: {
+    readonly logText: string | null | undefined;
+    readonly knownProjectNames: ReadonlyArray<string>;
+}): ReadonlyArray<string>;

package/umd/src/utils/agent-message-runtime/resolveAgentMessageTouchedProjectNames.test.d.ts

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

package/umd/src/utils/agents/terminalAgentAvatarVisual.d.ts

@@ -75,9 +75,12 @@ export type CreateTerminalAgentAvatarVisualOptions = {
      */
     readonly colorDepth?: AsciiArtColorDepth;
     /**
-     * Platform-specific canvas factory used to rasterize the visual.
+     * Platform-specific canvas factory used to rasterize pixel-based visuals.
+     *
+     * Character-based visuals such as `AsciiOctopus` paint the terminal grid directly, so they
+     * render without any canvas; a pixel-based visual renders an empty frame when it is missing.
      */
-    readonly createCanvas: CreateCanvasForAsciiArt;
+    readonly createCanvas?: CreateCanvasForAsciiArt;
 };
 /**
  * Resolves the built-in avatar visual selected for terminal rendering of one agent source.

package/umd/src/utils/ascii-art/convertImageDataToAsciiArt.d.ts

@@ -62,6 +62,12 @@ export type ConvertImageDataToAsciiArtOptions = {
      */
     readonly alphaThreshold?: number;
 };
+/**
+ * Default alpha channel value below which a cell is rendered as terminal background.
+ *
+ * @private within the repository
+ */
+export declare const DEFAULT_ALPHA_THRESHOLD = 32;
 /**
  * Converts raw RGBA image pixels into colored ASCII art for ANSI terminals.
  *

package/umd/src/utils/ascii-art/createAnsiColorCode.d.ts

@@ -0,0 +1,46 @@
+import type { AsciiArtColorDepth } from './convertImageDataToAsciiArt';
+/**
+ * ANSI escape sequence that resets all colors and attributes.
+ *
+ * @private within the repository
+ */
+export declare const ANSI_RESET = "\u001B[0m";
+/**
+ * One opaque 24-bit color which should be written into an ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export type AnsiRgbColor = {
+    /**
+     * Red channel in the range `[0, 255]`.
+     */
+    readonly red: number;
+    /**
+     * Green channel in the range `[0, 255]`.
+     */
+    readonly green: number;
+    /**
+     * Blue channel in the range `[0, 255]`.
+     */
+    readonly blue: number;
+};
+/**
+ * Creates the ANSI escape code that sets the foreground color of following characters.
+ *
+ * @param color Color painted onto the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export declare function createAnsiForegroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;
+/**
+ * Creates the ANSI escape code that sets the background color of following characters.
+ *
+ * @param color Color painted behind the characters.
+ * @param colorDepth Color depth supported by the target terminal.
+ * @returns ANSI escape sequence.
+ *
+ * @private within the repository
+ */
+export declare function createAnsiBackgroundColorCode(color: AnsiRgbColor, colorDepth: AsciiArtColorDepth): string;

package/umd/src/utils/misc/createLazyModuleLoader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Creates a loader which imports one module on the first call and reuses the very same module afterwards
+ *
+ * Note: [🐌] Heavy third-party dependencies are imported lazily to keep the startup of the Promptbook CLI fast.
+ *       A statically imported dependency is loaded every single time the bundle is loaded, even when the running
+ *       command never touches it. A lazily imported dependency is loaded only when the feature is really used.
+ *
+ * @example
+ * const loadJsdomModule = createLazyModuleLoader(() => import('jsdom'));
+ * const { JSDOM } = await loadJsdomModule();
+ *
+ * @private internal utility of Promptbook
+ */
+export declare function createLazyModuleLoader<TModule>(importModule: () => Promise<TModule>): () => Promise<TModule>;

package/umd/src/utils/misc/debounce.d.ts

@@ -1,7 +1,9 @@
 import type { TODO_any } from '../organization/TODO_any';
 /**
- * Handles debounce.
+ * Creates a debounced function that runs after calls have been quiet for the given delay.
  *
  * @public exported from `@promptbook/utils`
  */
-export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): (...args: Parameters<T>) => void;
+export declare function debounce<T extends (...args: TODO_any[]) => void>(fn: T, delay: number): ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};

package/umd/src/utils/misc/debounce.test.d.ts

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

package/umd/src/utils/random/$generateBookBoilerplate.test.d.ts

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

package/umd/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.113.1-0`).
+ * It follows semantic versioning (e.g., `0.114.0-20`).
  *
  * @generated
  */

package/apps/agents-server/scripts/ignore-kill-eperm.js

@@ -1,31 +0,0 @@
-'use strict';
-
-/**
- * Best-effort Windows guard for child-process shutdown races during `next build`.
- *
- * Next.js and `jest-worker` can attempt to kill helper processes that are already
- * exiting, which intermittently throws `EPERM` on Windows. Treat those cleanup-only
- * failures as non-fatal so the build can finish normally.
- */
-const { ChildProcess } = require('node:child_process');
-
-/**
- * Original `ChildProcess.kill` implementation restored only when the process exits.
- */
-const originalKill = ChildProcess.prototype.kill;
-
-ChildProcess.prototype.kill = function patchedKill(signal) {
-    try {
-        return originalKill.call(this, signal);
-    } catch (error) {
-        if (
-            error instanceof Error &&
-            'code' in error &&
-            (error.code === 'EPERM' || error.code === 'ESRCH')
-        ) {
-            return false;
-        }
-
-        throw error;
-    }
-};

package/apps/agents-server/src/app/admin/task-manager/TaskManagerScopeTabs.tsx

@@ -1,74 +0,0 @@
-'use client';
-
-import { AdminRouteTabs, type AdminRouteTabItem } from '../_components/AdminRouteTabs';
-
-/**
- * Task-manager scope: one server, or the whole VPS.
- *
- * @private function of TaskManagerClient
- */
-export type TaskManagerScope = 'server' | 'vps';
-
-/**
- * Route of the per-server task manager.
- *
- * @private function of TaskManagerScopeTabs
- */
-export const SERVER_TASK_MANAGER_PATH = '/admin/task-manager';
-
-/**
- * Route of the VPS-wide (superadmin) task manager.
- *
- * @private function of TaskManagerScopeTabs
- */
-export const VPS_TASK_MANAGER_PATH = '/superadmin/task-manager';
-
-/**
- * Route-backed task-manager scope navigation.
- *
- * @private function of TaskManagerScopeTabs
- */
-const TASK_MANAGER_SCOPE_NAVIGATION_ITEMS: ReadonlyArray<AdminRouteTabItem<TaskManagerScope>> = [
-    {
-        id: 'server',
-        href: SERVER_TASK_MANAGER_PATH,
-        label: 'This server',
-    },
-    {
-        id: 'vps',
-        href: VPS_TASK_MANAGER_PATH,
-        label: 'All servers (VPS)',
-    },
-];
-
-/**
- * Props for the task-manager scope tabs.
- *
- * @private function of TaskManagerClient
- */
-type TaskManagerScopeTabsProps = {
-    /**
-     * Currently active scope.
-     */
-    activeScope: TaskManagerScope;
-    /**
-     * Whether the VPS-wide tab is available to the current user (superadmin only).
-     */
-    isSuperAdmin: boolean;
-};
-
-/**
- * Renders the tabs interlinking the per-server and VPS-wide task managers.
- *
- * The VPS-wide tab is superadmin-only, so ordinary admins keep the single per-server view with
- * no tab bar at all.
- *
- * @private function of TaskManagerClient
- */
-export function TaskManagerScopeTabs({ activeScope, isSuperAdmin }: TaskManagerScopeTabsProps) {
-    if (!isSuperAdmin) {
-        return null;
-    }
-
-    return <AdminRouteTabs activeTabId={activeScope} items={TASK_MANAGER_SCOPE_NAVIGATION_ITEMS} />;
-}

package/apps/agents-server/src/app/agents/[agentName]/api/timeouts/actions/route.ts

@@ -1,103 +0,0 @@
-import { NextResponse } from 'next/server';
-import { isPrivateModeEnabledFromRequest } from '@/src/utils/privateMode';
-import {
-    cancelAllActiveAgentScopedUserChatTimeouts,
-    pauseAllActiveAgentScopedUserChatTimeouts,
-    resumeAllPausedAgentScopedUserChatTimeouts,
-} from '@/src/utils/userChatTimeout';
-import { resolveUserChatScope } from '../../user-chats/resolveUserChatScope';
-
-/**
- * Supported bulk actions for one agent-scoped timeout manager request.
- */
-type AgentTimeoutBulkAction = 'cancel_all_active' | 'pause_all_active' | 'resume_all_paused';
-
-/**
- * Request payload accepted by timeout bulk-actions endpoint.
- */
-type AgentTimeoutBulkActionPayload = {
-    action?: unknown;
-};
-
-/**
- * Parses and validates one timeout bulk action payload.
- */
-function parseTimeoutBulkActionPayload(payload: AgentTimeoutBulkActionPayload): AgentTimeoutBulkAction | null {
-    if (payload.action === 'cancel_all_active') {
-        return payload.action;
-    }
-
-    if (payload.action === 'pause_all_active') {
-        return payload.action;
-    }
-
-    if (payload.action === 'resume_all_paused') {
-        return payload.action;
-    }
-
-    return null;
-}
-
-/**
- * Executes one bulk timeout action for current user+agent scope.
- */
-export async function POST(request: Request, { params }: { params: Promise<{ agentName: string }> }) {
-    if (isPrivateModeEnabledFromRequest(request)) {
-        return NextResponse.json({ error: 'Private mode is enabled.' }, { status: 403 });
-    }
-
-    const { agentName: rawAgentName } = await params;
-    const agentName = decodeURIComponent(rawAgentName);
-    const scopeResult = await resolveUserChatScope(agentName);
-
-    if (!scopeResult.ok) {
-        if (scopeResult.error === 'UNAUTHORIZED') {
-            return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
-        }
-
-        if (scopeResult.error === 'FORBIDDEN') {
-            return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
-        }
-
-        return NextResponse.json({ error: 'Agent not found.' }, { status: 404 });
-    }
-
-    try {
-        const payload = (await request.json().catch(() => ({}))) as AgentTimeoutBulkActionPayload;
-        const action = parseTimeoutBulkActionPayload(payload);
-        if (!action) {
-            return NextResponse.json({ error: 'Invalid timeout bulk action.' }, { status: 400 });
-        }
-        const scope = scopeResult.scope;
-
-        const summary =
-            action === 'cancel_all_active'
-                ? await cancelAllActiveAgentScopedUserChatTimeouts({
-                      userId: scope.userId,
-                      agentPermanentId: scope.agentPermanentId,
-                  })
-                : action === 'pause_all_active'
-                ? await pauseAllActiveAgentScopedUserChatTimeouts({
-                      userId: scope.userId,
-                      agentPermanentId: scope.agentPermanentId,
-                  })
-                : await resumeAllPausedAgentScopedUserChatTimeouts({
-                      userId: scope.userId,
-                      agentPermanentId: scope.agentPermanentId,
-                  });
-
-        return NextResponse.json({
-            action,
-            matchedCount: summary.matchedCount,
-            updatedCount: summary.updatedCount,
-            timeoutIds: summary.timeoutIds,
-            hasMore: summary.hasMore,
-            generatedAt: new Date().toISOString(),
-        });
-    } catch (error) {
-        return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to execute timeout bulk action.' },
-            { status: 400 },
-        );
-    }
-}

package/apps/agents-server/src/app/agents/[agentName]/timeouts/AgentTimeoutsClient.tsx

@@ -1,43 +0,0 @@
-'use client';
-
-import { useServerLanguage } from '@/src/components/ServerLanguage/ServerLanguageProvider';
-import { AgentTimeoutsEditDialog } from './AgentTimeoutsEditDialog';
-import { AgentTimeoutsFiltersCard } from './AgentTimeoutsFiltersCard';
-import { AgentTimeoutsHeader } from './AgentTimeoutsHeader';
-import { AgentTimeoutsSummaryMetrics } from './AgentTimeoutsSummaryMetrics';
-import { AgentTimeoutsTableCard } from './AgentTimeoutsTableCard';
-import { useAgentTimeoutsClientState } from './useAgentTimeoutsClientState';
-
-/**
- * Props for the agent timeout manager page.
- */
-type AgentTimeoutsClientProps = {
-    agentName: string;
-};
-
-/**
- * Displays all timeouts for one user+agent across chats and supports timeout edits.
- *
- * @private route component of AgentTimeoutsPage
- */
-export function AgentTimeoutsClient({ agentName }: AgentTimeoutsClientProps) {
-    const { language } = useServerLanguage();
-    const state = useAgentTimeoutsClientState({ agentName });
-
-    return (
-        <div className="container mx-auto mt-20 space-y-6 px-4 py-8">
-            <AgentTimeoutsHeader state={state} />
-            <AgentTimeoutsSummaryMetrics state={state} />
-            <AgentTimeoutsFiltersCard language={language} state={state} />
-
-            {state.errorMessage ? (
-                <div className="rounded-2xl border border-red-200 bg-red-50 p-4 text-sm text-red-700">
-                    {state.errorMessage}
-                </div>
-            ) : null}
-
-            <AgentTimeoutsTableCard agentName={agentName} language={language} state={state} />
-            <AgentTimeoutsEditDialog state={state} />
-        </div>
-    );
-}

package/apps/agents-server/src/app/agents/[agentName]/timeouts/AgentTimeoutsEditDialog.tsx

@@ -1,98 +0,0 @@
-import { Dialog } from '@/src/components/Portal/Dialog';
-import type { useAgentTimeoutsClientState } from './useAgentTimeoutsClientState';
-
-/**
- * Props for the timeout edit dialog.
- *
- * @private function of AgentTimeoutsClient
- */
-type AgentTimeoutsEditDialogProps = {
-    state: ReturnType<typeof useAgentTimeoutsClientState>;
-};
-
-/**
- * Renders the advanced timeout edit dialog.
- *
- * @private function of AgentTimeoutsClient
- */
-export function AgentTimeoutsEditDialog({ state }: AgentTimeoutsEditDialogProps) {
-    const editingTimeout = state.editingTimeout;
-
-    if (!editingTimeout) {
-        return null;
-    }
-
-    const isSaving = state.busyTimeoutId === editingTimeout.timeoutId && state.busyAction === 'save';
-
-    return (
-        <Dialog onClose={state.requestCloseEditDialog} className="w-full max-w-2xl p-5 sm:p-6">
-            <div className="space-y-4">
-                <div>
-                    <h2 className="text-lg font-semibold text-slate-900">Edit timeout</h2>
-                    <p className="text-sm text-slate-500">{editingTimeout.timeoutId}</p>
-                </div>
-
-                <label className="flex flex-col gap-1 text-sm">
-                    <span className="font-medium text-slate-700">Next run</span>
-                    <input
-                        type="datetime-local"
-                        value={state.editDraft.dueAtLocalValue}
-                        onChange={(event) => state.updateEditDueAtLocalValue(event.target.value)}
-                        className="rounded-md border border-gray-300 px-3 py-2"
-                    />
-                </label>
-
-                <label className="flex flex-col gap-1 text-sm">
-                    <span className="font-medium text-slate-700">Recurrence (minutes, leave empty for one-shot)</span>
-                    <input
-                        type="number"
-                        min="0"
-                        step="1"
-                        value={state.editDraft.recurrenceMinutesValue}
-                        onChange={(event) => state.updateEditRecurrenceMinutesValue(event.target.value)}
-                        className="rounded-md border border-gray-300 px-3 py-2"
-                    />
-                </label>
-
-                <label className="flex flex-col gap-1 text-sm">
-                    <span className="font-medium text-slate-700">Wake-up message</span>
-                    <input
-                        type="text"
-                        value={state.editDraft.messageValue}
-                        onChange={(event) => state.updateEditMessageValue(event.target.value)}
-                        className="rounded-md border border-gray-300 px-3 py-2"
-                    />
-                </label>
-
-                <label className="flex flex-col gap-1 text-sm">
-                    <span className="font-medium text-slate-700">Payload parameters (JSON object)</span>
-                    <textarea
-                        value={state.editDraft.parametersValue}
-                        onChange={(event) => state.updateEditParametersValue(event.target.value)}
-                        className="min-h-40 rounded-md border border-gray-300 px-3 py-2 font-mono text-xs"
-                    />
-                </label>
-
-                <div className="flex justify-end gap-2">
-                    <button
-                        type="button"
-                        onClick={state.requestCloseEditDialog}
-                        className="rounded-md border border-gray-300 px-3 py-2 text-sm font-semibold text-gray-700"
-                    >
-                        Close
-                    </button>
-                    <button
-                        type="button"
-                        onClick={() => {
-                            void state.saveEdits();
-                        }}
-                        disabled={isSaving}
-                        className="rounded-md border border-blue-200 bg-blue-50 px-3 py-2 text-sm font-semibold text-blue-700 disabled:opacity-60"
-                    >
-                        {isSaving ? 'Saving...' : 'Save'}
-                    </button>
-                </div>
-            </div>
-        </Dialog>
-    );
-}

package/apps/agents-server/src/app/agents/[agentName]/timeouts/AgentTimeoutsFiltersCard.tsx

@@ -1,75 +0,0 @@
-import type { ServerLanguageCode } from '@/src/languages/ServerLanguageRegistry';
-import { formatServerLanguageHumanReadableDate } from '@/src/utils/localization/formatServerLanguageHumanReadableDate';
-import type { useAgentTimeoutsClientState } from './useAgentTimeoutsClientState';
-
-/**
- * Props for the timeout filter card.
- *
- * @private function of AgentTimeoutsClient
- */
-type AgentTimeoutsFiltersCardProps = {
-    language: ServerLanguageCode;
-    state: ReturnType<typeof useAgentTimeoutsClientState>;
-};
-
-/**
- * One filter tab shown in the timeout-manager view switcher.
- *
- * @private function of AgentTimeoutsFiltersCard
- */
-type TimeoutManagerFilterOption = {
-    id: ReturnType<typeof useAgentTimeoutsClientState>['filter'];
-    label: string;
-};
-
-/**
- * Available timeout-manager filter tabs.
- *
- * @private function of AgentTimeoutsFiltersCard
- */
-const TIMEOUT_MANAGER_FILTER_OPTIONS: ReadonlyArray<TimeoutManagerFilterOption> = [
-    { id: 'active', label: 'Active' },
-    { id: 'paused', label: 'Paused' },
-    { id: 'history', label: 'History' },
-    { id: 'all', label: 'All' },
-];
-
-/**
- * Formats the refresh metadata shown below the filter tabs.
- *
- * @private function of AgentTimeoutsFiltersCard
- */
-function resolveLastRefreshedLabel(generatedAt: string | null, language: ServerLanguageCode): string {
-    return generatedAt
-        ? `Last refreshed ${formatServerLanguageHumanReadableDate(generatedAt, language)}`
-        : 'Waiting for first refresh...';
-}
-
-/**
- * Renders the timeout-manager filter tabs and refresh metadata.
- *
- * @private function of AgentTimeoutsClient
- */
-export function AgentTimeoutsFiltersCard({ language, state }: AgentTimeoutsFiltersCardProps) {
-    return (
-        <div className="rounded-2xl border border-gray-200 bg-white p-4 shadow-sm">
-            <div className="flex flex-wrap gap-2">
-                {TIMEOUT_MANAGER_FILTER_OPTIONS.map((filterOption) => (
-                    <button
-                        key={filterOption.id}
-                        type="button"
-                        onClick={() => state.selectFilter(filterOption.id)}
-                        className={`rounded-xl border px-3 py-1.5 text-sm font-semibold ${
-                            state.filter === filterOption.id
-                                ? 'border-blue-500 bg-blue-50 text-blue-700'
-                                : 'border-gray-200 bg-white text-gray-700 hover:border-gray-300 hover:bg-gray-50'
-                        }`}
-                    >
-                        {filterOption.label}
-                    </button>
-                ))}
-            </div>
-            <div className="mt-3 text-xs text-gray-500">{resolveLastRefreshedLabel(state.generatedAt, language)}</div>
-        </div>
-    );
-}

package/apps/agents-server/src/app/agents/[agentName]/timeouts/AgentTimeoutsHeader.tsx

@@ -1,53 +0,0 @@
-import type { useAgentTimeoutsClientState } from './useAgentTimeoutsClientState';
-
-/**
- * Props for the timeout-manager page header.
- *
- * @private function of AgentTimeoutsClient
- */
-type AgentTimeoutsHeaderProps = {
-    state: ReturnType<typeof useAgentTimeoutsClientState>;
-};
-
-/**
- * Renders the timeout-manager heading and top-level actions.
- *
- * @private function of AgentTimeoutsClient
- */
-export function AgentTimeoutsHeader({ state }: AgentTimeoutsHeaderProps) {
-    return (
-        <div className="flex flex-col gap-3 md:flex-row md:items-end md:justify-between">
-            <div>
-                <h1 className="text-3xl font-light text-gray-900">My timeouts</h1>
-                <p className="mt-1 max-w-3xl text-sm text-gray-500">
-                    Agent-scoped timeout manager across all your chats.
-                </p>
-            </div>
-            <div className="flex flex-wrap items-center gap-2">
-                {state.bulkActions.map((bulkAction) => (
-                    <button
-                        key={bulkAction.action}
-                        type="button"
-                        onClick={() => {
-                            void state.runBulkAction(bulkAction.action);
-                        }}
-                        disabled={state.busyBulkAction !== null}
-                        className={bulkAction.buttonClassName}
-                    >
-                        {state.busyBulkAction === bulkAction.action ? bulkAction.busyLabel : bulkAction.idleLabel}
-                    </button>
-                ))}
-                <button
-                    type="button"
-                    onClick={() => {
-                        void state.refreshNow();
-                    }}
-                    disabled={state.isRefreshing || state.busyBulkAction !== null}
-                    className="rounded-full border border-blue-200 bg-blue-50 px-3 py-1.5 text-xs font-semibold text-blue-700 disabled:cursor-not-allowed disabled:opacity-60"
-                >
-                    {state.isRefreshing ? 'Refreshing...' : 'Refresh'}
-                </button>
-            </div>
-        </div>
-    );
-}