@promptbook/cli 0.114.0-14 → 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/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.
+            \`\`\`
         `);
     }