@promptbook/cli 0.114.0-13 → 0.114.0-18

package/src/book-components/Chat/utils/externalSourceToolCall.ts

@@ -0,0 +1,65 @@
+import type {
+    AgentMessageTouchedExternalSource,
+    AgentMessageTouchedExternalSourceKind,
+} from '../../../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+import { normalizeAgentMessageTouchedExternalSource } from '../../../utils/agent-message-runtime/AgentMessageTouchedExternalSource';
+
+/**
+ * Synthetic tool name used for external-source chips in chat UI.
+ *
+ * The Agents Server emits one such tool call per source outside the agent an answer viewed or
+ * edited, so the chat shows which services, websites and searches the agent really reached below
+ * the message that touched them. Work the agent does inside itself emits nothing.
+ *
+ * @private internal chat-ui marker for touched external sources
+ */
+export const EXTERNAL_SOURCE_TOOL_CALL_NAME = 'external_source_touched';
+
+/**
+ * Emoji shown in the chip of each external source category.
+ *
+ * @private internal chat-ui constant for touched external sources
+ */
+const EXTERNAL_SOURCE_EMOJI_BY_KIND: Readonly<Record<AgentMessageTouchedExternalSourceKind, string>> = {
+    integration: '🔌',
+    website: '🌐',
+    search: '🔎',
+};
+
+/**
+ * Parses the external-source chip payload from one tool result.
+ *
+ * @param result - Raw tool result payload.
+ * @returns Parsed source metadata, or `null` when the result describes no external source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export function parseExternalSourceToolCallResult(result: unknown): AgentMessageTouchedExternalSource | null {
+    return normalizeAgentMessageTouchedExternalSource(result);
+}
+
+/**
+ * Resolves the chip label of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns User-facing name of the source.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export function resolveExternalSourceToolCallLabel(externalSource: AgentMessageTouchedExternalSource): string {
+    return externalSource.name;
+}
+
+/**
+ * Resolves the chip emoji of one touched external source.
+ *
+ * @param externalSource - Parsed source metadata.
+ * @returns Emoji telling apart an integration, a website and a search.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export function resolveExternalSourceToolCallEmoji(externalSource: AgentMessageTouchedExternalSource): string {
+    return EXTERNAL_SOURCE_EMOJI_BY_KIND[externalSource.kind];
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name

package/src/book-components/Chat/utils/getToolCallChipletInfo.ts

@@ -6,6 +6,12 @@ import {
     parseAgentProjectToolCallResult,
     resolveAgentProjectToolCallLabel,
 } from './agentProjectToolCall';
+import {
+    EXTERNAL_SOURCE_TOOL_CALL_NAME,
+    parseExternalSourceToolCallResult,
+    resolveExternalSourceToolCallEmoji,
+    resolveExternalSourceToolCallLabel,
+} from './externalSourceToolCall';
 import { formatToolCallLocalTime } from './formatToolCallLocalTime';
 import { formatToolCallTranslationTemplate } from './formatToolCallTranslationTemplate';
 import {
@@ -118,6 +124,7 @@ type ToolCallChipletResolver = (context: ToolCallChipletContext) => ToolCallChip
 const SPECIALIZED_TOOL_CALL_CHIPLET_RESOLVERS: ReadonlyArray<ToolCallChipletResolver> = [
     resolveWalletCredentialChipletInfo,
     resolveAgentProjectToolCallChipletInfo,
+    resolveExternalSourceToolCallChipletInfo,
     resolveTeamToolCallChipletInfo,
     resolveTimeToolCallChipletInfo,
     resolveEmailToolCallChipletInfo,
@@ -147,6 +154,7 @@ export const TOOL_TITLES: Record<string, { title: string; emoji: string }> = {
     [ASSISTANT_PREPARATION_TOOL_CALL_NAME]: { title: 'Preparing agent', emoji: '✨' },
     [WALLET_CREDENTIAL_TOOL_CALL_NAME]: { title: 'Credential used', emoji: '🔐' },
     [AGENT_PROJECT_TOOL_CALL_NAME]: { title: 'Project', emoji: '📁' },
+    [EXTERNAL_SOURCE_TOOL_CALL_NAME]: { title: 'External source', emoji: '🌐' },
     'self-learning': { title: 'self-learning', emoji: '🧠' },
     retrieve_user_memory: { title: 'Reading memory', emoji: '🧠' },
     store_user_memory: { title: 'Storing memory', emoji: '🧠' },
@@ -348,6 +356,34 @@ function resolveAgentProjectToolCallChipletInfo(context: ToolCallChipletContext)
     return createEmojiToolCallChipletInfo(context, resolveAgentProjectToolCallLabel(projectResult));
 }
 
+/**
+ * Resolves the source-name chip label for touched external sources.
+ *
+ * The emoji tells apart an integration, a website and a search, so it overrides the single emoji
+ * registered for the tool name itself.
+ *
+ * @param context - Shared chiplet resolution context.
+ * @returns Chiplet info when the tool call marks a touched external source, otherwise `null`.
+ *
+ * @private utility of `<Chat/>`
+ */
+function resolveExternalSourceToolCallChipletInfo(context: ToolCallChipletContext): ToolCallChipletInfo | null {
+    if (context.toolCall.name !== EXTERNAL_SOURCE_TOOL_CALL_NAME) {
+        return null;
+    }
+
+    const externalSource = parseExternalSourceToolCallResult(context.resultRaw);
+    if (!externalSource) {
+        return null;
+    }
+
+    return {
+        text: `${resolveExternalSourceToolCallEmoji(externalSource)} ${resolveExternalSourceToolCallLabel(
+            externalSource,
+        )}`,
+    };
+}
+
 /**
  * Resolves a chip label and agent metadata for TEAM tool calls.
  *

package/src/book-components/Chat/utils/renderMarkdown.ts

@@ -162,8 +162,7 @@ const INLINE_REFERENCE_MENU_OPTION_MARKER_ATTRIBUTE = 'data-promptbook-inline-re
  *
  * @private utility shared with `MarkdownContent`
  */
-export const MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE =
-    'data-promptbook-inline-reference-menu-action';
+export const MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE = 'data-promptbook-inline-reference-menu-action';
 
 /**
  * Attribute identifying the inline reference which owns a client menu action.
@@ -1159,9 +1158,7 @@ function createMarkdownInlineReferenceTextAliasRegex(
     const escapedAlias = escapeRegularExpression(sourceTextAlias);
     const boundaryCharacterClass = '\\p{L}\\p{N}_-';
     const boundaryPattern = `[^${boundaryCharacterClass}]`;
-    const aliasPattern = isMarkdownFormattingMatched
-        ? `(?:\\*\\*|__)${escapedAlias}(?:\\*\\*|__)`
-        : escapedAlias;
+    const aliasPattern = isMarkdownFormattingMatched ? `(?:\\*\\*|__)${escapedAlias}(?:\\*\\*|__)` : escapedAlias;
 
     return new RegExp(`(^|${boundaryPattern})${aliasPattern}(?=$|${boundaryPattern})`, 'giu');
 }
@@ -1645,11 +1642,7 @@ function applyMarkdownInlineReferences(markdown: string_markdown, options?: Rend
         const { masked: markdownWithMaskedLinksAndUrls, restore: restoreLinksAndUrls } =
             maskMarkdownLinksAndBareUrls(referencedMarkdown);
         referencedMarkdown = restoreLinksAndUrls(
-            replaceMarkdownInlineReferenceTextAliases(
-                markdownWithMaskedLinksAndUrls,
-                textMatchers,
-                createPlaceholder,
-            ),
+            replaceMarkdownInlineReferenceTextAliases(markdownWithMaskedLinksAndUrls, textMatchers, createPlaceholder),
         );
     }
 

package/src/book-components/Chat/utils/timeoutToolCallPresentation.ts

@@ -9,6 +9,13 @@ import { formatToolCallTranslationTemplate } from './formatToolCallTranslationTe
  */
 export const SET_TIMEOUT_TOOL_CALL_NAME = 'set_timeout';
 
+/**
+ * Tool name of one re-planned wake-up, used by every producer of timeout chips.
+ *
+ * @private internal timeout-chat constant
+ */
+export const UPDATE_TIMEOUT_TOOL_CALL_NAME = 'update_timeout';
+
 /**
  * Tool name of one cancelled wake-up, used by every producer of timeout chips.
  *
@@ -21,7 +28,11 @@ export const CANCEL_TIMEOUT_TOOL_CALL_NAME = 'cancel_timeout';
  *
  * @private internal timeout-chat constant
  */
-const TIMEOUT_TOOL_NAMES = [SET_TIMEOUT_TOOL_CALL_NAME, CANCEL_TIMEOUT_TOOL_CALL_NAME] as const;
+const TIMEOUT_TOOL_NAMES = [
+    SET_TIMEOUT_TOOL_CALL_NAME,
+    UPDATE_TIMEOUT_TOOL_CALL_NAME,
+    CANCEL_TIMEOUT_TOOL_CALL_NAME,
+] as const;
 
 /**
  * Milliseconds in one second.

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

@@ -17,6 +17,7 @@ import {
     normalizePromptRunnerSelectionCliOptions,
     PROMPT_RUNNER_DESCRIPTION,
 } from '../common/promptRunnerCliOptions';
+import { parseOptionalPeriodDuration } from './waitOptions';
 
 /**
  * Initializes `coder ping` command for Promptbook CLI utilities
@@ -37,6 +38,7 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
             - Verifies that the selected harness, model, thinking level and authentication really work
             - Reports the answer of the harness, the response time and the reported usage
             - Starts the hourly/weekly quota window before you need it, so it is already refreshing when you do
+            - Optional --period keeps the quota window refreshing by pinging once per period until stopped
             - Leaves the project exactly as it was — nothing is read, written, changed or committed
             - Checks that the selected harness is installed globally and up to date unless --no-harness-update is used
             - Use --no-ui to stream the raw harness output instead of only the compact result
@@ -46,9 +48,20 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
     addPromptRunnerSelectionOptions(command);
     addHarnessUpdateOption(command);
     addPromptRunnerRuntimeOptions(command);
+    command.option(
+        '--period <duration>',
+        spaceTrim(`
+            Keep pinging once per period instead of pinging only once.
+            Accepts durations like 5h, 30m, 1h30m and repeats until it is stopped with CTRL+C.
+        `),
+    );
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const { period: periodValue } = cliOptions as {
+                readonly period?: string;
+            } & PromptRunnerSelectionCliOptions;
+
             const runnerOptions = normalizePromptRunnerSelectionCliOptions(
                 cliOptions as PromptRunnerSelectionCliOptions,
                 { isAgentRequired: true },
@@ -57,23 +70,36 @@ export function $initializeCoderPingCommand(program: Program): $side_effect {
                 cliOptions as HarnessUpdateCliOptions,
             );
 
-            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
+            // Note: The period is validated before the harness installation check, so a mistyped duration fails fast
+            const periodMs = parseOptionalPeriodDuration('--period', periodValue);
 
-            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
-            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
-            const { printCoderPingResult } = await import(
-                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
-            );
+            await $ensureHarnessInstallations([runnerOptions.agentName], isHarnessUpdateCheckEnabled);
 
-            const result = await pingCoderHarness({
+            const pingOptions = {
                 agentName: runnerOptions.agentName,
                 model: runnerOptions.model,
                 thinkingLevel: runnerOptions.thinkingLevel,
                 allowCredits: runnerOptions.allowCredits,
                 shouldPrintLiveOutput: runnerOptions.noUi,
-            });
+            };
+
+            // Note: Import the ping dynamically to avoid loading heavy dependencies until needed
+            if (periodMs !== undefined) {
+                const { pingCoderHarnessPeriodically } = await import(
+                    '../../../../scripts/run-codex-prompts/ping/pingCoderHarnessPeriodically'
+                );
+
+                // Note: This never returns - it keeps pinging until the user stops the process
+                await pingCoderHarnessPeriodically({ ...pingOptions, periodMs });
+                return;
+            }
+
+            const { pingCoderHarness } = await import('../../../../scripts/run-codex-prompts/ping/pingCoderHarness');
+            const { printCoderPingResult } = await import(
+                '../../../../scripts/run-codex-prompts/ping/printCoderPingResult'
+            );
 
-            printCoderPingResult(result);
+            printCoderPingResult(await pingCoderHarness(pingOptions));
         }),
     );
 }

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

@@ -1,4 +1,6 @@
+import { spaceTrim } from 'spacetrim';
 import { parseDuration } from '../../../../scripts/run-codex-prompts/common/parseDuration';
+import { NotAllowed } from '../../../errors/NotAllowed';
 
 /**
  * Default wait duration applied before retrying a prompt round after an error (10 minutes).
@@ -21,4 +23,35 @@ export function parseOptionalWaitDuration(value: string | undefined, defaultMs:
     return parseDuration(value);
 }
 
+/**
+ * Parses an optional Commander period duration string and returns the resolved milliseconds.
+ *
+ * Returns `undefined` when the flag was not provided or was provided without a non-empty value,
+ * which means the command runs only once instead of repeating itself.
+ *
+ * @throws {NotAllowed} When the duration is not a positive one, because a non-positive period
+ *                      would repeat the command without ever pausing between two rounds
+ *
+ * @private internal utility of `ptbk coder` wait handling
+ */
+export function parseOptionalPeriodDuration(optionName: string, value: string | undefined): number | undefined {
+    if (typeof value !== 'string' || value === '') {
+        return undefined;
+    }
+
+    const periodMs = parseDuration(value);
+
+    if (periodMs <= 0) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Invalid value for \`${optionName}\`: \`${value}\`.
+
+                Use a **positive** duration like \`5h\`, \`30m\` or \`1h30m\`.
+            `),
+        );
+    }
+
+    return periodMs;
+}
+
 // Note: [💞] Ignore a discrepancy between file name and entity name

package/src/cli/cli-commands/common/harness/$applyHarnessInstallationStatus.ts

@@ -21,7 +21,9 @@ export async function $applyHarnessInstallationStatus(status: HarnessInstallatio
     }
 
     if (installationState === 'installed') {
-        console.info(colors.gray(`✔ ${definition.label} ${installedVersion} is installed. Skipped checking for updates.`));
+        console.info(
+            colors.gray(`✔ ${definition.label} ${installedVersion} is installed. Skipped checking for updates.`),
+        );
         return;
     }
 

package/src/cli/cli-commands/common/harness/$checkHarnessInstallation.ts

@@ -17,7 +17,9 @@ export async function $checkHarnessInstallation(
 ): Promise<HarnessInstallationStatus> {
     const [installedVersion, latestVersion] = await Promise.all([
         $resolveInstalledHarnessVersion(definition),
-        isHarnessUpdateCheckEnabled ? $resolveLatestNpmPackageVersion(definition.npmPackageName) : Promise.resolve(null),
+        isHarnessUpdateCheckEnabled
+            ? $resolveLatestNpmPackageVersion(definition.npmPackageName)
+            : Promise.resolve(null),
     ]);
 
     return {

package/src/cli/cli-commands/common/harnessUpdateCliOptions.ts

@@ -26,10 +26,7 @@ export type NormalizedHarnessUpdateCliOptions = {
  * @private internal utility of `promptbookCli`
  */
 export function addHarnessUpdateOption(command: Program): void {
-    command.option(
-        '--no-harness-update',
-        'Skip checking whether globally installed coding harnesses are up to date',
-    );
+    command.option('--no-harness-update', 'Skip checking whether globally installed coding harnesses are up to date');
 }
 
 /**

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

@@ -214,20 +214,64 @@ export class AgentCollectionInSupabase /* TODO: [🌈][🐱‍🚀] implements A
 
     /**
      * Retrieves the permanent ID of an agent by its name or permanent ID.
+     *
+     * An agent that still exists always wins over a soft-deleted one, so a name that was deleted and
+     * later created again resolves to the agent that is live now instead of to the recycle-bin leftover.
+     * Soft-deleted agents stay resolvable as a fallback because the recycle bin restores them by name
+     * or permanent id.
      */
     public async getAgentPermanentId(
         agentNameOrPermanentId: string_agent_name | string_agent_permanent_id,
     ): Promise<string_agent_permanent_id> {
-        const selectResult = await this.supabaseClient
+        const activeAgentPermanentId = await this.findAgentPermanentId(agentNameOrPermanentId, {
+            isDeletedAgentIncluded: false,
+        });
+
+        if (activeAgentPermanentId !== null) {
+            return activeAgentPermanentId;
+        }
+
+        const deletedAgentPermanentId = await this.findAgentPermanentId(agentNameOrPermanentId, {
+            isDeletedAgentIncluded: true,
+        });
+
+        if (deletedAgentPermanentId !== null) {
+            return deletedAgentPermanentId;
+        }
+
+        throw new NotFoundError(`Agent with name or id "${agentNameOrPermanentId}" not found`);
+    }
+
+    /**
+     * Looks up the permanent id of the oldest agent matching one name or permanent id.
+     *
+     * @param agentNameOrPermanentId - Agent name or stable permanent identifier to match.
+     * @param options - Whether soft-deleted agents may be matched as well.
+     * @returns Permanent id of the matched agent, or `null` when nothing matches.
+     *
+     * @private internal helper of `AgentCollectionInSupabase`
+     */
+    private async findAgentPermanentId(
+        agentNameOrPermanentId: string_agent_name | string_agent_permanent_id,
+        options: { readonly isDeletedAgentIncluded: boolean },
+    ): Promise<string_agent_permanent_id | null> {
+        const selectQuery = this.supabaseClient
             .from(this.getTableName('Agent'))
             .select('permanentId')
-            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId))
+            .or(buildAgentNameOrPermanentIdFilter(agentNameOrPermanentId));
+
+        if (!options.isDeletedAgentIncluded) {
+            selectQuery.is('deletedAt', null);
+        }
+
+        const selectResult = await selectQuery
             .order('createdAt', { ascending: true }) // Pick oldest if multiple match by name
             .limit(1);
 
         if (selectResult.error || !selectResult.data || selectResult.data.length === 0) {
-            throw new NotFoundError(`Agent with name or id "${agentNameOrPermanentId}" not found`);
+            return null;
         }
+
         return selectResult.data[0]!.permanentId as string_agent_permanent_id;
     }
 

package/src/commands/FORMAT/formatCommandParser.ts

@@ -70,8 +70,10 @@ export const formatCommandParser: PipelineTaskCommandParser<FormatCommand> = {
      */
     $applyToTaskJson(command: FormatCommand, $taskJson: $TaskJson): $side_effect {
         if ($taskJson.format !== undefined && command.format !== $taskJson.format) {
-            throw new ParseError(spaceTrim(`Format format is already defined to "${$taskJson.format}".
-                Now you try to redefine it by "${command.format}"`));
+            throw new ParseError(
+                spaceTrim(`Format format is already defined to "${$taskJson.format}".
+                Now you try to redefine it by "${command.format}"`),
+            );
         }
         $taskJson.format = command.format;
     },

package/src/commitments/FROM/FROM.ts

@@ -46,6 +46,12 @@ export class FromCommitmentDefinition extends BaseCommitmentDefinition<'FROM'> {
 
             Inherits agent source from another agent.
 
+            Every agent inherits from the core agent \`@Adam\` unless it says otherwise, so writing no ${this.type} at all
+            is the same as writing \`${this.type} @Adam\`. Write \`${this.type} @Null\` to inherit from nothing.
+
+            An agent has exactly one parent, so when ${this.type} is written more than once, the last one wins and
+            overrides every earlier one.
+
             ## Examples
 
             \`\`\`book
@@ -54,6 +60,13 @@ export class FromCommitmentDefinition extends BaseCommitmentDefinition<'FROM'> {
             FROM https://s6.ptbk.io/benjamin-white
             RULE Speak only in English.
             \`\`\`
+
+            \`\`\`book
+            My Standalone Agent
+
+            FROM @Null
+            RULE Speak only in English.
+            \`\`\`
         `);
     }