@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/book-components/Chat/MarkdownContent/MarkdownContent.module.css

@@ -229,6 +229,57 @@
     transform: translateY(0.03em);
 }
 
+.MarkdownContent
+    :is(
+        a.inlineReferenceChip:global(.inlineReferenceChip--with-icon),
+        details.inlineReferenceChip:global(.inlineReferenceChip--with-icon) > summary
+    )::before {
+    display: none;
+}
+
+.MarkdownContent :global(.inlineReferenceIcon) {
+    position: relative;
+    display: inline-flex;
+    width: 1.1em;
+    height: 1.1em;
+    flex: 0 0 auto;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+    border: 1px solid color-mix(in srgb, var(--md-link-color) 22%, transparent);
+    border-radius: 0.24em;
+    background: color-mix(in srgb, var(--md-link-color) 10%, white);
+    font-size: 0.86em;
+    line-height: 1;
+}
+
+.MarkdownContent :global(.inlineReferenceIconFallback) {
+    overflow: hidden;
+    max-width: 100%;
+    color: var(--md-link-color);
+    font-size: 0.48em;
+    font-weight: 750;
+    letter-spacing: -0.04em;
+    white-space: nowrap;
+}
+
+.MarkdownContent :global(.inlineReferenceIcon) img {
+    position: absolute;
+    inset: 0;
+    display: block;
+    width: 100%;
+    height: 100%;
+    max-width: none;
+    margin: 0;
+    border-radius: 0;
+    background: color-mix(in srgb, var(--md-link-color) 7%, white);
+    object-fit: contain;
+}
+
+.MarkdownContent :global(.inlineReferenceIcon) img[hidden] {
+    display: none;
+}
+
 .MarkdownContent :is(a.inlineReferenceChip, details.inlineReferenceChip > summary):hover,
 .MarkdownContent :is(a.inlineReferenceChip, details.inlineReferenceChip > summary):focus-visible {
     border-color: color-mix(in srgb, var(--md-link-color) 52%, rgba(148, 163, 184, 0.35));
@@ -254,7 +305,7 @@
     display: inline-flex;
     align-items: center;
     gap: 0.38em;
-    color: var(--md-muted-color);
+    color: #b91c1c;
     font-size: 0.78em;
     font-weight: 650;
 }
@@ -264,7 +315,8 @@
     height: 0.52em;
     margin-left: 0.05em;
     border-radius: 999px;
-    background: color-mix(in srgb, var(--md-muted-color) 55%, transparent);
+    background: #ef4444;
+    box-shadow: 0 0 0 0.16em color-mix(in srgb, #ef4444 18%, transparent);
 }
 
 .MarkdownContent :global(.inlineReferenceMenuStatus--active) {
@@ -290,21 +342,37 @@
 
 .MarkdownContent :global(.inlineReferenceMenuOption) {
     display: block;
+    width: 100%;
     padding: 0.45rem 0.55rem;
+    border: 0;
     border-radius: 0.4rem;
+    background: transparent;
     color: var(--md-link-color);
+    font-family: inherit;
     font-size: 0.82em;
     font-weight: 650;
     line-height: 1.35;
+    text-align: left;
     text-decoration: none;
 }
 
 .MarkdownContent a:global(.inlineReferenceMenuOption):hover,
-.MarkdownContent a:global(.inlineReferenceMenuOption):focus-visible {
+.MarkdownContent a:global(.inlineReferenceMenuOption):focus-visible,
+.MarkdownContent button:global(.inlineReferenceMenuOption):hover,
+.MarkdownContent button:global(.inlineReferenceMenuOption):focus-visible {
     background: color-mix(in srgb, var(--md-link-color) 10%, transparent);
     text-decoration: none;
 }
 
+.MarkdownContent button:global(.inlineReferenceMenuOption) {
+    cursor: pointer;
+}
+
+.MarkdownContent button:global(.inlineReferenceMenuOption):disabled {
+    cursor: wait;
+    opacity: 0.55;
+}
+
 .MarkdownContent :global(.inlineReferenceMenuOption--disabled) {
     cursor: not-allowed;
     color: var(--md-muted-color);
@@ -445,7 +513,7 @@
     opacity: 0.8;
 }
 
-.MarkdownContent details {
+.MarkdownContent details:not(.inlineReferenceChip) {
     margin: 0.95em 0;
     border: 1px solid var(--md-table-border);
     border-radius: 16px;
@@ -455,13 +523,13 @@
     transition: border-color 0.18s ease, box-shadow 0.18s ease, transform 0.18s ease;
 }
 
-.MarkdownContent details:hover,
-.MarkdownContent details:focus-within {
+.MarkdownContent details:not(.inlineReferenceChip):hover,
+.MarkdownContent details:not(.inlineReferenceChip):focus-within {
     border-color: color-mix(in srgb, var(--md-link-color) 24%, var(--md-table-border) 76%);
     box-shadow: 0 12px 28px rgba(15, 23, 42, 0.12);
 }
 
-.MarkdownContent details > summary {
+.MarkdownContent details:not(.inlineReferenceChip) > summary {
     display: flex;
     align-items: center;
     gap: 0.72rem;
@@ -479,7 +547,7 @@
     transition: background 0.18s ease, color 0.18s ease;
 }
 
-.MarkdownContent details > summary::before {
+.MarkdownContent details:not(.inlineReferenceChip) > summary::before {
     content: '';
     width: 0.62rem;
     height: 0.62rem;
@@ -492,8 +560,8 @@
     transition: transform 0.18s ease, opacity 0.18s ease;
 }
 
-.MarkdownContent details > summary:hover,
-.MarkdownContent details > summary:focus-visible {
+.MarkdownContent details:not(.inlineReferenceChip) > summary:hover,
+.MarkdownContent details:not(.inlineReferenceChip) > summary:focus-visible {
     background: linear-gradient(
         180deg,
         color-mix(in srgb, var(--md-table-head-bg) 76%, rgba(255, 255, 255, 0.95) 24%),
@@ -501,34 +569,34 @@
     );
 }
 
-.MarkdownContent details > summary:focus-visible {
+.MarkdownContent details:not(.inlineReferenceChip) > summary:focus-visible {
     outline: 2px solid color-mix(in srgb, var(--md-link-color) 52%, transparent);
     outline-offset: -2px;
 }
 
-.MarkdownContent details > summary::-webkit-details-marker {
+.MarkdownContent details:not(.inlineReferenceChip) > summary::-webkit-details-marker {
     display: none;
 }
 
-.MarkdownContent details[open] > summary {
+.MarkdownContent details:not(.inlineReferenceChip)[open] > summary {
     border-bottom: 1px solid color-mix(in srgb, var(--md-table-border) 88%, transparent);
 }
 
-.MarkdownContent details[open] > summary::before {
+.MarkdownContent details:not(.inlineReferenceChip)[open] > summary::before {
     transform: rotate(45deg);
     opacity: 1;
 }
 
-.MarkdownContent details > :not(summary) {
+.MarkdownContent details:not(.inlineReferenceChip) > :not(summary) {
     margin-left: 1.05em;
     margin-right: 1.05em;
 }
 
-.MarkdownContent details > summary + * {
+.MarkdownContent details:not(.inlineReferenceChip) > summary + * {
     margin-top: 0.95em;
 }
 
-.MarkdownContent details > :last-child {
+.MarkdownContent details:not(.inlineReferenceChip) > :last-child {
     margin-bottom: 1.05em;
 }
 

package/src/book-components/Chat/MarkdownContent/MarkdownContent.tsx

@@ -6,7 +6,12 @@ import type { string_markdown } from '../../../types/string_markdown';
 import { classNames } from '../../_common/react-utils/classNames';
 import { CodeBlock } from '../CodeBlock/CodeBlock';
 import type { MarkdownInlineReference } from '../utils/renderMarkdown';
-import { renderMarkdown } from '../utils/renderMarkdown';
+import {
+    MARKDOWN_INLINE_REFERENCE_ICON_ATTRIBUTE,
+    MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE,
+    MARKDOWN_INLINE_REFERENCE_MENU_ACTION_REFERENCE_ATTRIBUTE,
+    renderMarkdown,
+} from '../utils/renderMarkdown';
 import styles from './MarkdownContent.module.css';
 
 /**
@@ -16,6 +21,20 @@ import styles from './MarkdownContent.module.css';
  */
 const DETAILS_SUMMARY_SELECTOR = 'summary';
 
+/**
+ * Selector matching client-action buttons rendered inside inline-reference menus.
+ *
+ * @private utility of `MarkdownContent` component
+ */
+const INLINE_REFERENCE_MENU_ACTION_SELECTOR = `[${MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE}]`;
+
+/**
+ * Selector matching inline-reference favicon images which need a broken-image fallback.
+ *
+ * @private utility of `MarkdownContent` component
+ */
+const INLINE_REFERENCE_ICON_SELECTOR = `img[${MARKDOWN_INLINE_REFERENCE_ICON_ATTRIBUTE}]`;
+
 /**
  * Props for markdown content.
  */
@@ -110,6 +129,45 @@ function resolveClickedDetailsElement(target: EventTarget | null, container: HTM
     return details instanceof HTMLDetailsElement ? details : null;
 }
 
+/**
+ * Resolves the configured callback for one rendered inline-reference menu action.
+ *
+ * @param actionButton - Clicked menu action button.
+ * @param inlineReferences - References available to the markdown content.
+ * @returns Matching action callback, or `null` when the rendered marker is stale.
+ *
+ * @private utility of `MarkdownContent` component
+ */
+function resolveInlineReferenceMenuAction(
+    actionButton: HTMLButtonElement,
+    inlineReferences: ReadonlyArray<MarkdownInlineReference> | undefined,
+): (() => void | Promise<void>) | null {
+    const actionId = actionButton.getAttribute(MARKDOWN_INLINE_REFERENCE_MENU_ACTION_ATTRIBUTE);
+    const referenceId = actionButton.getAttribute(MARKDOWN_INLINE_REFERENCE_MENU_ACTION_REFERENCE_ATTRIBUTE);
+
+    if (!actionId || !referenceId || !inlineReferences) {
+        return null;
+    }
+
+    const reference = inlineReferences.find((candidateReference) => candidateReference.reference === referenceId);
+    const option = reference?.menu?.options.find((candidateOption) => candidateOption.action?.id === actionId);
+
+    return option?.action?.onSelect || null;
+}
+
+/**
+ * Hides a favicon when it has completed without loading any pixels.
+ *
+ * @param faviconImage - Inline-reference favicon to inspect.
+ *
+ * @private utility of `MarkdownContent` component
+ */
+function hideBrokenInlineReferenceIcon(faviconImage: HTMLImageElement): void {
+    if (faviconImage.complete && faviconImage.naturalWidth === 0) {
+        faviconImage.hidden = true;
+    }
+}
+
 /**
  * Renders markdown content with support for code highlighting, math, and tables.
  *
@@ -215,8 +273,59 @@ export const MarkdownContent = memo(function MarkdownContent(props: MarkdownCont
             pendingToggleFallbackTimeoutIds.add(fallbackTimeoutId);
         };
 
+        /**
+         * Executes one delegated inline-reference menu action without allowing the click to reach
+         * surrounding chat message handlers.
+         */
+        const handleInlineReferenceMenuActionClick = (event: MouseEvent) => {
+            const targetElement = event.target instanceof Element ? event.target : null;
+            const actionButton = targetElement?.closest(INLINE_REFERENCE_MENU_ACTION_SELECTOR);
+
+            if (!(actionButton instanceof HTMLButtonElement) || !containerElement.contains(actionButton)) {
+                return;
+            }
+
+            const action = resolveInlineReferenceMenuAction(actionButton, inlineReferences);
+            if (!action || actionButton.disabled) {
+                return;
+            }
+
+            event.preventDefault();
+            event.stopPropagation();
+            actionButton.disabled = true;
+            actionButton.setAttribute('aria-busy', 'true');
+
+            void Promise.resolve()
+                .then(action)
+                .catch((error) => {
+                    console.error('Inline reference menu action failed:', error);
+                })
+                .finally(() => {
+                    if (!actionButton.isConnected) {
+                        return;
+                    }
+
+                    actionButton.disabled = false;
+                    actionButton.removeAttribute('aria-busy');
+                });
+        };
+
         containerElement.addEventListener('toggle', handleToggle, true);
         containerElement.addEventListener('click', handleSummaryClick);
+        containerElement.addEventListener('click', handleInlineReferenceMenuActionClick);
+
+        const inlineReferenceIconImages =
+            containerElement.querySelectorAll<HTMLImageElement>(INLINE_REFERENCE_ICON_SELECTOR);
+        const handleInlineReferenceIconError = (event: Event) => {
+            if (event.currentTarget instanceof HTMLImageElement) {
+                event.currentTarget.hidden = true;
+            }
+        };
+
+        inlineReferenceIconImages.forEach((faviconImage) => {
+            hideBrokenInlineReferenceIcon(faviconImage);
+            faviconImage.addEventListener('error', handleInlineReferenceIconError);
+        });
 
         const preElements = containerElement.querySelectorAll('pre');
 
@@ -261,12 +370,16 @@ export const MarkdownContent = memo(function MarkdownContent(props: MarkdownCont
         return () => {
             containerElement.removeEventListener('toggle', handleToggle, true);
             containerElement.removeEventListener('click', handleSummaryClick);
+            containerElement.removeEventListener('click', handleInlineReferenceMenuActionClick);
+            inlineReferenceIconImages.forEach((faviconImage) => {
+                faviconImage.removeEventListener('error', handleInlineReferenceIconError);
+            });
             pendingToggleFallbackTimeoutIds.forEach((timeoutId) => window.clearTimeout(timeoutId));
             pendingToggleFallbackTimeoutIds.clear();
             rootsRef.current.forEach((root) => root.unmount());
             rootsRef.current = [];
         };
-    }, [htmlContent, resolvedTheme]);
+    }, [htmlContent, inlineReferences, resolvedTheme]);
 
     return (
         <div

package/src/book-components/Chat/MockedChat/MockedChat.tsx

@@ -155,6 +155,28 @@ type SimulateMockedChatPlaybackProps = {
     readonly isCancelledRef: () => boolean;
 };
 
+/**
+ * Provides stable identifiers for mocked messages that omit them.
+ *
+ * Incremental typing changes the message content on every word. A stable id
+ * lets the chat renderer preserve the message element instead of treating
+ * every content update as a new message.
+ *
+ * @private function of `MockedChat`
+ */
+function ensureMockedChatMessageIds(messages: ReadonlyArray<ChatMessage>): ReadonlyArray<ChatMessage> {
+    return messages.map((message, messageIndex) => {
+        if (message.id) {
+            return message;
+        }
+
+        return {
+            ...message,
+            id: `mocked-chat-message-${messageIndex}`,
+        };
+    });
+}
+
 /**
  * Resolves one delay value, including random ranges.
  *
@@ -560,7 +582,7 @@ async function simulateMockedChatPlayback(props: SimulateMockedChatPlaybackProps
 export function MockedChat(props: MockedChatProps) {
     const {
         delayConfig,
-        messages: originalMessages,
+        messages: sourceMessages,
         isResettable = true,
         isPausable = true,
         messageOffsetsMs,
@@ -570,6 +592,8 @@ export function MockedChat(props: MockedChatProps) {
         ...chatProps
     } = props;
 
+    const originalMessages = useMemo(() => ensureMockedChatMessageIds(sourceMessages), [sourceMessages]);
+
     const delays = {
         ...MOCKED_CHAT_DELAY_CONFIGS.NORMAL_FLOW,
         ...delayConfig,

package/src/book-components/Chat/save/react/exports/chat-preview-2025-10-13 (1).jsx

@@ -1,3 +1,4 @@
+import { spaceTrim } from 'spacetrim';
 import { Chat } from '@promptbook/components';
 
 export function ChatPreviewChatComponent() {
@@ -43,7 +44,47 @@ export function ChatPreviewChatComponent() {
                     createdAt: '2025-10-12T23:13:15.925Z',
                     sender: 'ASSISTANT_1',
                     content:
-                        "**Absolutely!** Here’s a quick overview:\n\n- **Bold**\n- _Italic_\n- __Underline__\n- ~~Strikethrough~~\n- `Inline code`\n- Code block:\n\n```js\nconsole.log('Hello, world!');\n```\n> Blockquote\n> With\n> Multiple lines\n\n\n- Some text with [Link](https://example.com)\n- ![image](https://img.youtube.com/vi/nD1v9dMvnLY/maxresdefault.jpg)\n- Lists:\n  - Item 1\n    - Nested item\n- Numbered list:\n  1. First\n     1. Nested\n- Table:\n\n| Syntax | Description |\n|--------|-------------|\n| Header | Title       |\n| Cell   | Data        |\n\n- Emoji: 😄 🎉\n- Mention: @user\n- Hashtag: #demo\n- Math: $E=mc^2$\n- Horizontal rule:\n\n---",
+                        spaceTrim(`
+                            **Absolutely!** Here’s a quick overview:
+
+                            - **Bold**
+                            - _Italic_
+                            - __Underline__
+                            - ~~Strikethrough~~
+                            - \`Inline code\`
+                            - Code block:
+
+                            \`\`\`js
+                            console.log('Hello, world!');
+                            \`\`\`
+                            > Blockquote
+                            > With
+                            > Multiple lines
+
+
+                            - Some text with [Link](https://example.com)
+                            - ![image](https://img.youtube.com/vi/nD1v9dMvnLY/maxresdefault.jpg)
+                            - Lists:
+                              - Item 1
+                                - Nested item
+                            - Numbered list:
+                              1. First
+                                 1. Nested
+                            - Table:
+
+                            | Syntax | Description |
+                            |--------|-------------|
+                            | Header | Title       |
+                            | Cell   | Data        |
+
+                            - Emoji: 😄 🎉
+                            - Mention: @user
+                            - Hashtag: #demo
+                            - Math: $E=mc^2$
+                            - Horizontal rule:
+
+                            ---
+                        `),
                     isComplete: true,
                 },
                 {
@@ -51,7 +92,22 @@ export function ChatPreviewChatComponent() {
                     createdAt: '2025-10-12T23:13:15.925Z',
                     sender: 'USER',
                     content:
-                        "Wow, that's a lot! Can you combine some of them?\n\n**Bold _italic_ and `inline code`**\n\nOr maybe:\n> _Blockquote with a [link](https://example.com)_\n\nAnd a table:\n\n| Name | Value |\n|------|-------|\n| Pi   | $\\pi$ |\n\n---",
+                        spaceTrim(`
+                            Wow, that's a lot! Can you combine some of them?
+
+                            **Bold _italic_ and \`inline code\`**
+
+                            Or maybe:
+                            > _Blockquote with a [link](https://example.com)_
+
+                            And a table:
+
+                            | Name | Value |
+                            |------|-------|
+                            | Pi   | $\\pi$ |
+
+                            ---
+                        `),
                     isComplete: true,
                 },
                 {
@@ -59,7 +115,19 @@ export function ChatPreviewChatComponent() {
                     createdAt: '2025-10-12T23:13:15.925Z',
                     sender: 'ASSISTANT_1',
                     content:
-                        'Of course! Here’s a creative mix:\n\n- ~~Strikethrough~~ and __underline__\n- 1. Numbered with *italic* and emoji 🚀\n- - Nested `inline code`\n\n> Blockquote with math: $a^2 + b^2 = c^2$\n\n---\n\nLet me know if you want to see more! #rich #features',
+                        spaceTrim(`
+                            Of course! Here’s a creative mix:
+
+                            - ~~Strikethrough~~ and __underline__
+                            - 1. Numbered with *italic* and emoji 🚀
+                            - - Nested \`inline code\`
+
+                            > Blockquote with math: $a^2 + b^2 = c^2$
+
+                            ---
+
+                            Let me know if you want to see more! #rich #features
+                        `),
                     isComplete: true,
                 },
                 {
@@ -67,7 +135,15 @@ export function ChatPreviewChatComponent() {
                     createdAt: '2025-10-12T23:13:15.925Z',
                     sender: 'ASSISTANT_1',
                     content:
-                        'And here are some more emojis:\n\n😄🎉🚀💡📊📝🔥🌟✅❌\n❤🧡💙💚💛🧡❤️🤎🖤💜\n🐱‍👤🐱‍💻🐱🚀🐱‍🏍💫🎞🎫🎠🎏\n😀😀😁😂🤣😃😄😆😅🤩\n➿🛂🛃🛄🛅♿📶🚻🚹🚾',
+                        spaceTrim(`
+                            And here are some more emojis:
+
+                            😄🎉🚀💡📊📝🔥🌟✅❌
+                            ❤🧡💙💚💛🧡❤️🤎🖤💜
+                            🐱‍👤🐱‍💻🐱🚀🐱‍🏍💫🎞🎫🎠🎏
+                            😀😀😁😂🤣😃😄😆😅🤩
+                            ➿🛂🛃🛄🛅♿📶🚻🚹🚾
+                        `),
                     isComplete: true,
                 },
                 {
@@ -75,7 +151,21 @@ export function ChatPreviewChatComponent() {
                     createdAt: '2025-10-12T23:13:15.925Z',
                     sender: 'ASSISTANT_1',
                     content:
-                        '## And lists:\n\n- Item 1\n- Item 2\n    - Nested Item 2a\n    - Nested Item 2b\n- Item 3\n\n1. First item\n2. Second item\n   1. Nested second item a\n   2. Nested second item b\n3. Third item',
+                        spaceTrim(`
+                            ## And lists:
+
+                            - Item 1
+                            - Item 2
+                                - Nested Item 2a
+                                - Nested Item 2b
+                            - Item 3
+
+                            1. First item
+                            2. Second item
+                               1. Nested second item a
+                               2. Nested second item b
+                            3. Third item
+                        `),
                     isComplete: true,
                 },
             ]}

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

@@ -0,0 +1,151 @@
+import type { AgentMessageProjectChange } from '../../../utils/agent-message-runtime/AgentMessageProjectChange';
+import { normalizeAgentMessageProjectChange } from '../../../utils/agent-message-runtime/AgentMessageProjectChange';
+
+/**
+ * Synthetic tool name used for agent-project chips in chat UI.
+ *
+ * The Agents Server emits one such tool call per project an answer viewed or edited, so the chat
+ * shows which projects the agent worked with below the message that touched them.
+ *
+ * @private internal chat-ui marker for touched agent projects
+ */
+export const AGENT_PROJECT_TOOL_CALL_NAME = 'agent_project_touched';
+
+/**
+ * Safe, user-facing metadata shown in agent-project chips.
+ *
+ * Everything besides the project name is optional, because a chip written by an older server — or
+ * one whose project has meanwhile been deleted — still has to render.
+ *
+ * @private internal chat-ui type for touched agent projects
+ */
+export type AgentProjectToolCallResult = {
+    /**
+     * Directory name of the project.
+     */
+    readonly projectName: string;
+
+    /**
+     * Human-readable project name shown in the chip.
+     */
+    readonly displayName?: string;
+
+    /**
+     * Short project description, resolved the same way as on the project page.
+     */
+    readonly description?: string;
+
+    /**
+     * Link to the project page, when the chat knows where the project lives.
+     */
+    readonly projectHref?: string;
+
+    /**
+     * Address the running project itself is served on, when it has one.
+     */
+    readonly projectUrl?: string;
+
+    /**
+     * Whether the project was running when the answer finished.
+     */
+    readonly isRunning?: boolean;
+
+    /**
+     * Runtime status label, the same one the project page shows.
+     */
+    readonly runtimeStatusLabel?: string;
+
+    /**
+     * Total size of the project, already formatted for display.
+     */
+    readonly sizeLabel?: string;
+
+    /**
+     * Count of files inside the project.
+     */
+    readonly fileCount?: number;
+
+    /**
+     * Whether the project folder is a git repository.
+     */
+    readonly isGitRepository?: boolean;
+
+    /**
+     * What this very message changed in the project, when it changed anything.
+     *
+     * Its `projectName` repeats the one above because the change is reported by the agent runner
+     * in exactly this shape, and reusing it keeps the two descriptions from drifting apart.
+     */
+    readonly change?: AgentMessageProjectChange;
+};
+
+/**
+ * Parses the project-chip payload from one tool result.
+ *
+ * @param result - Raw tool result payload.
+ * @returns Parsed project metadata, or `null` when the result describes no project.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export function parseAgentProjectToolCallResult(result: unknown): AgentProjectToolCallResult | null {
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        return null;
+    }
+
+    const candidate = result as Partial<AgentProjectToolCallResult>;
+    if (typeof candidate.projectName !== 'string' || candidate.projectName.trim().length === 0) {
+        return null;
+    }
+
+    const change = normalizeAgentMessageProjectChange(candidate.change);
+
+    return {
+        projectName: candidate.projectName.trim(),
+        ...pickTrimmedText('displayName', candidate.displayName),
+        ...pickTrimmedText('description', candidate.description),
+        ...pickTrimmedText('projectHref', candidate.projectHref),
+        ...pickTrimmedText('projectUrl', candidate.projectUrl),
+        ...pickTrimmedText('runtimeStatusLabel', candidate.runtimeStatusLabel),
+        ...pickTrimmedText('sizeLabel', candidate.sizeLabel),
+        ...(typeof candidate.isRunning === 'boolean' ? { isRunning: candidate.isRunning } : {}),
+        ...(typeof candidate.isGitRepository === 'boolean' ? { isGitRepository: candidate.isGitRepository } : {}),
+        ...(typeof candidate.fileCount === 'number' && Number.isFinite(candidate.fileCount) && candidate.fileCount >= 0
+            ? { fileCount: candidate.fileCount }
+            : {}),
+        ...(change ? { change } : {}),
+    };
+}
+
+/**
+ * Keeps one optional text field only when it carries content.
+ *
+ * @param fieldName - Name of the payload field.
+ * @param value - Raw field value.
+ * @returns Object holding the trimmed field, or an empty object.
+ *
+ * @private internal helper of `parseAgentProjectToolCallResult`
+ */
+function pickTrimmedText<TFieldName extends string>(
+    fieldName: TFieldName,
+    value: unknown,
+): Partial<Record<TFieldName, string>> {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        return {};
+    }
+
+    return { [fieldName]: value.trim() } as Record<TFieldName, string>;
+}
+
+/**
+ * Resolves the chip label of one touched agent project.
+ *
+ * @param projectResult - Parsed project metadata.
+ * @returns Human-readable project name.
+ *
+ * @private internal helper reused by chip and modal rendering
+ */
+export function resolveAgentProjectToolCallLabel(projectResult: AgentProjectToolCallResult): string {
+    return projectResult.displayName || projectResult.projectName;
+}
+
+// Note: [💞] Ignore a discrepancy between file name and entity name