@promptbook/cli 0.112.0-125 → 0.112.0-127

package/README.md

@@ -543,7 +543,7 @@ Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treate
 -   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`
 -   **Context injection:** `--agent agents/coding/developer.book --context AGENTS.md` or inline extra instructions
 -   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
--   **Interactive or unattended runs:** default wait mode, or `--no-wait` for batch execution
+-   **Unattended or interactive runs:** default auto mode, or `--no-auto` to wait for user confirmation before each prompt
 -   **Git safety:** clean working tree check by default, optional `--ignore-git-changes`
 -   **Opt-in remote pushes:** commits stay local unless you explicitly pass `--auto-push`
 -   **Prompt triage:** `--priority` to process only more important tasks first
@@ -565,7 +565,7 @@ npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gp
 
 npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
 
-npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes --no-wait
+npx ts-node ./src/cli/test/ptbk.ts coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --ignore-git-changes
 
 npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
 
@@ -591,7 +591,7 @@ ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh -
 
 ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --auto-push
 
-ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes --no-wait
+ptbk coder run --harness github-copilot --model gpt-5.4 --thinking-level xhigh --agent agents/coding/developer.book --context AGENTS.md --test npm run test --ignore-git-changes
 
 ptbk coder find-refactor-candidates
 
@@ -621,7 +621,7 @@ ptbk coder verify
 | `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`.                                 |
 | `--test <command>`         | Runs a verification command after each prompt attempt and feeds failing output back for retries.   |
 | `--thinking-level <level>` | Sets reasoning effort for supported runners.                                                       |
-| `--no-wait`                | Skips interactive pauses between prompts for unattended execution.                                 |
+| `--no-auto`                | Waits for user confirmation before each prompt instead of running automatically through the queue. |
 | `--ignore-git-changes`     | Disables the clean-working-tree guard.                                                             |
 | `--priority <n>`           | Runs only prompts at or above the given priority.                                                  |
 | `--dry-run`                | Prints which prompts are ready instead of executing them.                                          |
@@ -634,7 +634,7 @@ ptbk coder verify
 1. Initialize once with `ptbk coder init`.
 2. Customize `prompts/templates/*.md` if needed, then create or write prompt files in `prompts/`.
 3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--agent agents/coding/developer.book --context AGENTS.md`.
-4. Run one prompt at a time interactively, or use `--no-wait` for unattended batches.
+4. Run unattended batches by default, or pass `--no-auto` to confirm each prompt interactively.
 5. Finish with `ptbk coder verify` so resolved prompts are archived and broken ones get explicit repair follow-ups.
 
 

package/apps/agents-server/README.md

@@ -41,6 +41,9 @@ ptbk agents-server start --harness github-copilot --model gpt-5.4 --thinking-lev
 <a id="agents-server-env-admin-password"></a>
 -   `ADMIN_PASSWORD`: Password for the built-in `admin` login on a self-hosted Agents Server. Choose a private value before using the admin UI.
 
+<a id="agents-server-env-session-secret"></a>
+-   `SESSION_SECRET`: HMAC signing key used to sign the session cookie. Must be set explicitly in production — the server refuses to start session signing when missing instead of falling back to a hardcoded default. Use a long random string, for example the output of `openssl rand -hex 32`. Keep it separate from `ADMIN_PASSWORD` so a leak of either credential cannot forge the other.
+
 ## Creating servers
 
 When creating new Agents server, search across the repository for [☁]

package/apps/agents-server/playwright.config.ts

@@ -26,6 +26,7 @@ const APP_URL = `http://127.0.0.1:${APP_PORT}`;
  */
 const APP_E2E_ENV = {
     ADMIN_PASSWORD: 'e2e-admin-password',
+    SESSION_SECRET: 'e2e-session-secret-must-differ-from-admin-password',
     NEXT_DIST_DIR: '.next-e2e',
     NEXT_PUBLIC_SITE_URL: APP_URL,
     PTBK_AGENTS_SERVER_DATABASE: 'supabase',

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

@@ -0,0 +1 @@
+export { default, generateMetadata } from '../agents/[agentName]/layout';

package/apps/agents-server/src/app/actions.ts

@@ -5,7 +5,7 @@ import { string_agent_name, string_book } from '@promptbook-local/types';
 import { revalidatePath } from 'next/cache';
 import { string_agent_permanent_id } from '../../../../src/types/typeAliases';
 import { DEFAULT_NAME_POOL, NAME_POOL_METADATA_KEY, parseNamePool } from '../constants/namePool';
-import { NEW_AGENT_WIZZARD_METADATA_KEY, parseNewAgentWizardMode } from '../constants/newAgentWizard';
+import { NEW_AGENT_WIZARD_METADATA_KEY, parseNewAgentWizardMode } from '../constants/newAgentWizard';
 import { getMetadata } from '../database/getMetadata';
 import { $provideAgentCollectionForServer } from '../tools/$provideAgentCollectionForServer';
 import { invalidateCachedActiveOrganizationSnapshots } from '../utils/agentOrganization/loadAgentOrganizationState';
@@ -73,7 +73,7 @@ export async function $getNewAgentCreationSettingsAction(): Promise<{
     defaultVisibility: AgentVisibility;
 }> {
     return {
-        mode: parseNewAgentWizardMode(await getMetadata(NEW_AGENT_WIZZARD_METADATA_KEY)),
+        mode: parseNewAgentWizardMode(await getMetadata(NEW_AGENT_WIZARD_METADATA_KEY)),
         defaultVisibility: parseAgentVisibility(await getMetadata('DEFAULT_VISIBILITY')),
     };
 }

package/apps/agents-server/src/app/admin/update/UpdateClient.tsx

@@ -67,32 +67,44 @@ export function UpdateClient() {
     /**
      * Loads the latest self-update overview from the server.
      */
-    const loadOverview = useCallback(async (options?: { readonly isSilent?: boolean }): Promise<void> => {
-        try {
-            if (!options?.isSilent) {
-                setIsLoading(true);
-            }
-            setErrorMessage(null);
-
-            const response = await fetch('/api/admin/update', { cache: 'no-store' });
-            const payload = (await response.json()) as UpdateOverview;
-
-            if (!response.ok) {
-                throw new Error(payload.error || 'Failed to load the update overview.');
+    const loadOverview = useCallback(
+        async (options?: { readonly isSilent?: boolean; readonly isRestartExpected?: boolean }): Promise<void> => {
+            try {
+                if (!options?.isSilent) {
+                    setIsLoading(true);
+                }
+                setErrorMessage(null);
+
+                const response = await fetch('/api/admin/update', { cache: 'no-store' });
+                const payload = (await response.json()) as UpdateOverview;
+
+                if (!response.ok) {
+                    throw new Error(payload.error || 'Failed to load the update overview.');
+                }
+
+                setOverview(payload);
+                setSelectedEnvironmentId(
+                    (currentSelectedEnvironmentId) => currentSelectedEnvironmentId || payload.currentEnvironment.id,
+                );
+                if (payload.job.status === 'succeeded') {
+                    setSuccessMessage(getUpdateJobSuccessMessage(payload.job));
+                } else if (payload.job.status === 'failed') {
+                    setSuccessMessage(null);
+                }
+            } catch (error) {
+                if (options?.isRestartExpected) {
+                    return;
+                }
+
+                setErrorMessage(error instanceof Error ? error.message : 'Failed to load the update overview.');
+            } finally {
+                if (!options?.isSilent) {
+                    setIsLoading(false);
+                }
             }
-
-            setOverview(payload);
-            setSelectedEnvironmentId((currentSelectedEnvironmentId) =>
-                currentSelectedEnvironmentId || payload.currentEnvironment.id,
-            );
-        } catch (error) {
-            setErrorMessage(error instanceof Error ? error.message : 'Failed to load the update overview.');
-        } finally {
-            if (!options?.isSilent) {
-                setIsLoading(false);
-            }
-        }
-    }, []);
+        },
+        [],
+    );
 
     useEffect(() => {
         void loadOverview();
@@ -104,7 +116,7 @@ export function UpdateClient() {
         }
 
         const interval = window.setInterval(() => {
-            void loadOverview({ isSilent: true });
+            void loadOverview({ isSilent: true, isRestartExpected: true });
         }, 4000);
 
         return () => {
@@ -365,10 +377,10 @@ export function UpdateClient() {
                                 overview?.job.status === 'running'
                                     ? 'border-blue-200 bg-blue-50 text-blue-700'
                                     : overview?.job.status === 'failed'
-                                      ? 'border-rose-200 bg-rose-50 text-rose-700'
-                                      : overview?.job.status === 'succeeded'
-                                        ? 'border-emerald-200 bg-emerald-50 text-emerald-700'
-                                        : 'border-slate-200 bg-slate-50 text-slate-500'
+                                    ? 'border-rose-200 bg-rose-50 text-rose-700'
+                                    : overview?.job.status === 'succeeded'
+                                    ? 'border-emerald-200 bg-emerald-50 text-emerald-700'
+                                    : 'border-slate-200 bg-slate-50 text-slate-500'
                             }`}
                         >
                             {overview?.job.status || 'idle'}
@@ -394,14 +406,14 @@ export function UpdateClient() {
                         </div>
                     </dl>
 
-                    {overview?.job.errorMessage && (
-                        <div className="rounded-xl border border-rose-200 bg-rose-50 px-4 py-3 text-sm text-rose-700">
-                            {overview.job.errorMessage}
+                    {overview?.job.status === 'succeeded' && (
+                        <div className="rounded-xl border border-emerald-200 bg-emerald-50 px-4 py-3 text-sm text-emerald-700">
+                            {getUpdateJobSuccessMessage(overview.job)}
                         </div>
                     )}
-                    {overview?.job.isStale && (
-                        <div className="rounded-xl border border-amber-200 bg-amber-50 px-4 py-3 text-sm text-amber-800">
-                            The previous background update process stopped unexpectedly. You can start the update again.
+                    {overview?.job.status === 'failed' && (
+                        <div className="rounded-xl border border-rose-200 bg-rose-50 px-4 py-3 text-sm text-rose-700">
+                            {getUpdateJobFailureMessage(overview.job)}
                         </div>
                     )}
                     {overview?.job.logFilePath && (
@@ -424,6 +436,26 @@ export function UpdateClient() {
     );
 }
 
+/**
+ * Builds the success message for a finished standalone VPS update.
+ *
+ * @param job - Completed update job snapshot.
+ * @returns Human-readable success message.
+ */
+function getUpdateJobSuccessMessage(job: UpdateJobSnapshot): string {
+    return job.currentStep || 'Standalone VPS update finished successfully.';
+}
+
+/**
+ * Builds the failure message for a failed standalone VPS update.
+ *
+ * @param job - Failed update job snapshot.
+ * @returns Human-readable failure message.
+ */
+function getUpdateJobFailureMessage(job: UpdateJobSnapshot): string {
+    return job.errorMessage || 'The standalone VPS update failed. Review the installer log for details.';
+}
+
 /**
  * Formats optional timestamps for the status cards.
  *

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

@@ -0,0 +1,30 @@
+'use client';
+
+import {
+    useRegisterActiveAgentBreadcrumbInfo,
+    type ActiveAgentBreadcrumbInfo,
+} from '../../../components/Header/ActiveAgentBreadcrumbContext';
+
+/**
+ * Props for the active-agent breadcrumb binder.
+ *
+ * @private type of agent routes
+ */
+type ActiveAgentBreadcrumbBinderProps = {
+    /**
+     * Resolved active agent that should be shown in the Header breadcrumb.
+     */
+    readonly agent: ActiveAgentBreadcrumbInfo;
+};
+
+/**
+ * Registers the active agent with the Header breadcrumb context while the agent route is mounted.
+ * Renders nothing on its own; its sole purpose is to make sure the Header can render the agent's
+ * human-readable name instead of falling back to its URL identifier.
+ *
+ * @private function of agent routes
+ */
+export function ActiveAgentBreadcrumbBinder({ agent }: ActiveAgentBreadcrumbBinderProps) {
+    useRegisterActiveAgentBreadcrumbInfo(agent);
+    return null;
+}

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

@@ -21,6 +21,7 @@ import { useSoundSystem } from '../../../components/SoundSystemProvider/SoundSys
 import { fetchCalendarOAuthStatus, type CalendarOAuthStatusResponse } from '../../../utils/calendarOAuthClient';
 import { createDefaultChatEffects } from '../../../utils/chat/createDefaultChatEffects';
 import { executeQuickActionButton } from '../../../utils/chat/executeQuickActionButton';
+import { resolveAgentsServerCitationLabel } from '../../../utils/chat/resolveAgentsServerCitationLabel';
 import {
     isChatFeedbackEnabled,
     toChatComponentFeedbackMode,
@@ -458,6 +459,7 @@ export function AgentChatWrapper(props: AgentChatWrapperProps) {
             onReset={onStartNewChat}
             resetMode={onStartNewChat ? 'delegate' : undefined}
             teamAgentProfiles={teamAgentProfiles}
+            resolveCitationLabel={resolveAgentsServerCitationLabel}
         >
             {allowFileAttachments && !fileUploadAvailability.isUploadAvailable && (
                 <FileUploadUnavailableNotice className="mx-4 mt-4" />

package/apps/agents-server/src/app/agents/[agentName]/chat/AgentChatHistoryPayloadState.ts

@@ -34,6 +34,7 @@ export const AgentChatHistoryPayloadState = {
     applySnapshotStateUpdate,
     clearActiveChatRuntimeState,
     replaceChatInList,
+    sortUserChatSummariesByTimeDescending,
 };
 
 /**
@@ -175,7 +176,7 @@ function applySnapshotStateUpdate(params: {
     } = params;
 
     const reason = options.reason || 'snapshot-update';
-    setChats(snapshot.chats);
+    setChats(sortUserChatSummariesByTimeDescending(snapshot.chats));
     if (!snapshot.activeChatId) {
         if (options.allowSelectionAdoption !== true) {
             logChatSelection('selection_skip_snapshot_missing_active_chat', {
@@ -616,11 +617,44 @@ function applyResolvedChatPayload(params: {
 }
 
 /**
- * Moves one chat summary to the top of the sidebar list.
+ * Inserts or updates one chat summary in the sidebar list while keeping the list ordered
+ * by latest activity time (newest first), so the currently selected chat stays in its
+ * chronological position instead of being hoisted to the top.
  *
  * @private function of useAgentChatHistoryClientState
  */
 function replaceChatInList(chats: ReadonlyArray<UserChatSummary>, targetChat: UserChatSummary): Array<UserChatSummary> {
-    const remainingChats = chats.filter((chat) => chat.id !== targetChat.id);
-    return [targetChat, ...remainingChats];
+    const hasExistingEntry = chats.some((chat) => chat.id === targetChat.id);
+    const updatedChats = hasExistingEntry
+        ? chats.map((chat) => (chat.id === targetChat.id ? targetChat : chat))
+        : [...chats, targetChat];
+    return sortUserChatSummariesByTimeDescending(updatedChats);
+}
+
+/**
+ * Resolves the timestamp used to order one chat summary in the sidebar tray.
+ *
+ * Prefers the latest message timestamp, falls back to the chat's last update time, and finally
+ * to its creation time. This mirrors the timestamp displayed next to each chat row.
+ *
+ * @private function of useAgentChatHistoryClientState
+ */
+function resolveUserChatSummaryOrderTime(chat: UserChatSummary): number {
+    const timestamp = chat.lastMessageAt || chat.updatedAt || chat.createdAt;
+    const parsedTime = new Date(timestamp).getTime();
+    return Number.isFinite(parsedTime) ? parsedTime : 0;
+}
+
+/**
+ * Returns one new array of chat summaries sorted by latest activity time, newest first.
+ *
+ * @private function of useAgentChatHistoryClientState
+ */
+function sortUserChatSummariesByTimeDescending(
+    chats: ReadonlyArray<UserChatSummary>,
+): Array<UserChatSummary> {
+    return [...chats].sort(
+        (leftChat, rightChat) =>
+            resolveUserChatSummaryOrderTime(rightChat) - resolveUserChatSummaryOrderTime(leftChat),
+    );
 }

package/apps/agents-server/src/app/agents/[agentName]/chat/AgentChatHistorySyncOperations.ts

@@ -90,7 +90,10 @@ async function createBootstrapChatFromSnapshot(params: {
                   currentInitialOptimisticChatBootstrap.optimisticChatId,
                   createdChat.chat,
               )
-            : [createdChat.chat, ...snapshot.chats.filter((chat) => chat.id !== createdChat.chat.id)],
+            : AgentChatHistoryPayloadState.sortUserChatSummariesByTimeDescending([
+                  createdChat.chat,
+                  ...snapshot.chats.filter((chat) => chat.id !== createdChat.chat.id),
+              ]),
     );
 }
 

package/apps/agents-server/src/app/agents/[agentName]/chat/CanonicalAgentChatSurface.tsx

@@ -15,8 +15,9 @@ import { ChatThreadLoadingSkeleton } from '../../../../components/Skeleton/ChatT
 import { useSoundSystem } from '../../../../components/SoundSystemProvider/SoundSystemProvider';
 import { usePromptbookTheme } from '../../../../components/ThemeMode/usePromptbookTheme';
 import { createDefaultChatEffects } from '../../../../utils/chat/createDefaultChatEffects';
-import { downloadChatPdfFromServer } from '../../../../utils/chatExport/downloadChatPdfFromServer';
 import { executeQuickActionButton } from '../../../../utils/chat/executeQuickActionButton';
+import { resolveAgentsServerCitationLabel } from '../../../../utils/chat/resolveAgentsServerCitationLabel';
+import { downloadChatPdfFromServer } from '../../../../utils/chatExport/downloadChatPdfFromServer';
 import {
     isChatFeedbackEnabled,
     toChatComponentFeedbackMode,
@@ -127,6 +128,7 @@ export function CanonicalAgentChatSurface({
                 agentAvatarSrc: state.agentAvatarSrc,
                 agentAvatarVisualId: state.agentAvatarVisualId,
                 agentDisplayName: state.agentDisplayName,
+                agentKnowledgeSources: state.agentKnowledgeSources,
                 brandColorHex,
             }),
         [
@@ -135,6 +137,7 @@ export function CanonicalAgentChatSurface({
             state.agentAvatarSrc,
             state.agentAvatarVisualId,
             state.agentDisplayName,
+            state.agentKnowledgeSources,
         ],
     );
     const { language, t: translateText } = useServerLanguage();
@@ -181,20 +184,17 @@ export function CanonicalAgentChatSurface({
             </button>
         );
     }, [cancellableJob, isReadOnly, onCancelActiveJob, translateText]);
-    const handlePdfSaveFormat = useCallback(
-        async ({ title, messages, participants }: ChatSaveFormatHandlerOptions) => {
-            try {
-                await downloadChatPdfFromServer({
-                    title,
-                    messages,
-                    participants,
-                });
-            } catch (error) {
-                notifyError(error instanceof Error ? error.message : 'Failed to export chat as PDF.');
-            }
-        },
-        [],
-    );
+    const handlePdfSaveFormat = useCallback(async ({ title, messages, participants }: ChatSaveFormatHandlerOptions) => {
+        try {
+            await downloadChatPdfFromServer({
+                title,
+                messages,
+                participants,
+            });
+        } catch (error) {
+            notifyError(error instanceof Error ? error.message : 'Failed to export chat as PDF.');
+        }
+    }, []);
     const saveFormatHandlers = useMemo(
         () => ({
             pdf: handlePdfSaveFormat,
@@ -266,6 +266,7 @@ export function CanonicalAgentChatSurface({
             teamAgentProfiles={state.teamAgentProfiles}
             extraActions={extraActionNodes}
             saveFormatHandlers={saveFormatHandlers}
+            resolveCitationLabel={resolveAgentsServerCitationLabel}
             theme={promptbookTheme}
         >
             {!isReadOnly && areFileAttachmentsEnabled && !fileUploadAvailability.isUploadAvailable && (
@@ -322,12 +323,14 @@ function createCanonicalAgentChatParticipants({
     agentAvatarDefinition,
     agentAvatarSrc,
     agentAvatarVisualId,
+    agentKnowledgeSources,
     brandColorHex,
 }: {
     agentDisplayName: string;
     agentAvatarDefinition: CanonicalAgentChatPanelState['surface']['agentAvatarDefinition'];
     agentAvatarSrc: CanonicalAgentChatPanelState['surface']['agentAvatarSrc'];
     agentAvatarVisualId: CanonicalAgentChatPanelState['surface']['agentAvatarVisualId'];
+    agentKnowledgeSources: CanonicalAgentChatPanelState['surface']['agentKnowledgeSources'];
     brandColorHex: string;
 }): ReadonlyArray<ChatParticipant> {
     return [
@@ -339,6 +342,7 @@ function createCanonicalAgentChatParticipants({
             avatarVisualId: agentAvatarVisualId || undefined,
             color: brandColorHex,
             isMe: false,
+            knowledgeSources: agentKnowledgeSources,
         },
         {
             name: 'USER',

package/apps/agents-server/src/app/agents/[agentName]/chat/useCanonicalAgentChatPanelState.ts

@@ -60,6 +60,23 @@ type CanonicalAgentChatFeedback = {
     url: string;
 };
 
+/**
+ * Knowledge source metadata passed from the remote agent profile into Chat participants.
+ *
+ * @private type of CanonicalAgentChatPanel
+ */
+type CanonicalAgentKnowledgeSource = {
+    /**
+     * Fetchable source URL.
+     */
+    readonly url: string;
+
+    /**
+     * Filename used by model citations.
+     */
+    readonly filename: string;
+};
+
 /**
  * Inputs required to orchestrate the canonical durable-chat panel state.
  *
@@ -109,6 +126,7 @@ export type CanonicalAgentChatPanelState = {
         readonly agentAvatarSrc: string | null;
         readonly agentAvatarVisualId: AvatarVisualId | null;
         readonly agentDisplayName: string;
+        readonly agentKnowledgeSources: ReadonlyArray<CanonicalAgentKnowledgeSource>;
         readonly elevenLabsVoiceId: string | undefined;
         readonly initialMessage: string | undefined;
         readonly isSpeechPlaybackEnabled: boolean;
@@ -343,6 +361,7 @@ export function useCanonicalAgentChatPanelState(
     });
 
     const agentDisplayName = useMemo(() => resolveAgentDisplayName(agent, agentName), [agent, agentName]);
+    const agentKnowledgeSources = useMemo(() => resolveAgentKnowledgeSources(agent), [agent]);
     const resolvedAgentAvatar = useMemo(
         () => resolveResolvedAgentAvatar(agent, agentName, agentUrl),
         [agent, agentName, agentUrl],
@@ -400,11 +419,11 @@ export function useCanonicalAgentChatPanelState(
 
     return {
         surface: {
-            agentAvatarDefinition:
-                resolvedAgentAvatar?.type === 'visual' ? resolvedAgentAvatar.avatarDefinition : null,
+            agentAvatarDefinition: resolvedAgentAvatar?.type === 'visual' ? resolvedAgentAvatar.avatarDefinition : null,
             agentAvatarSrc: resolvedAgentAvatar?.type === 'image' ? resolvedAgentAvatar.imageUrl : null,
             agentAvatarVisualId: resolvedAgentAvatar?.type === 'visual' ? resolvedAgentAvatar.visualId : null,
             agentDisplayName,
+            agentKnowledgeSources,
             elevenLabsVoiceId: agent?.meta.voice,
             initialMessage,
             isSpeechPlaybackEnabled: agent?.isVoiceTtsSttEnabled ?? false,
@@ -658,15 +677,47 @@ function resolveAgentDisplayName(agent: RemoteAgent | null | undefined, agentNam
 }
 
 /**
- * Resolves the avatar shown for the agent participant in the chat thread.
+ * Resolves valid knowledge sources exposed by the remote agent profile.
+ *
+ * @param agent - Connected remote agent.
+ * @returns Knowledge sources usable by the shared Chat citation URL resolver.
  *
  * @private function of CanonicalAgentChatPanel
  */
-function resolveResolvedAgentAvatar(
+function resolveAgentKnowledgeSources(
     agent: RemoteAgent | null | undefined,
-    agentName: string,
-    agentUrl: string,
-) {
+): ReadonlyArray<CanonicalAgentKnowledgeSource> {
+    const knowledgeSources = (agent as { knowledgeSources?: unknown } | null | undefined)?.knowledgeSources;
+    if (!Array.isArray(knowledgeSources)) {
+        return [];
+    }
+
+    return knowledgeSources.filter(isCanonicalAgentKnowledgeSource);
+}
+
+/**
+ * Checks whether one remote profile value is a usable knowledge source.
+ *
+ * @param value - Candidate knowledge source.
+ * @returns True when the candidate has URL and filename strings.
+ *
+ * @private function of CanonicalAgentChatPanel
+ */
+function isCanonicalAgentKnowledgeSource(value: unknown): value is CanonicalAgentKnowledgeSource {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        typeof (value as CanonicalAgentKnowledgeSource).url === 'string' &&
+        typeof (value as CanonicalAgentKnowledgeSource).filename === 'string'
+    );
+}
+
+/**
+ * Resolves the avatar shown for the agent participant in the chat thread.
+ *
+ * @private function of CanonicalAgentChatPanel
+ */
+function resolveResolvedAgentAvatar(agent: RemoteAgent | null | undefined, agentName: string, agentUrl: string) {
     return resolveAgentAvatar({
         agent: {
             agentName: agent?.agentName || agentName,

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

@@ -1,7 +1,11 @@
 'use server';
 
 import type { Metadata } from 'next';
+import { resolveAgentRouteTarget } from '../../../utils/agentRouting/resolveAgentRouteTarget';
+import { ActiveAgentBreadcrumbBinder } from './ActiveAgentBreadcrumbBinder';
+import { getAgentName, getAgentProfile } from './_utils';
 import { generateAgentMetadata } from './generateAgentMetadata';
+import type { ActiveAgentBreadcrumbInfo } from '../../../components/Header/ActiveAgentBreadcrumbContext';
 
 /**
  * Generates shared branded metadata for all pages under `/agents/[agentName]`.
@@ -13,13 +17,55 @@ export async function generateMetadata({ params }: { params: Promise<{ agentName
     return generateAgentMetadata({ params });
 }
 
+/**
+ * Resolves the breadcrumb info for the route's active agent so the Header can show its name
+ * instead of falling back to the URL identifier. Failures are swallowed because the layout
+ * must keep rendering even when the agent cannot be resolved (the page will handle the error).
+ *
+ * @param rawAgentIdentifier - Decoded route parameter for the active agent.
+ * @returns Breadcrumb info for the active agent or `null` when unavailable.
+ *
+ * @private function of agent routes
+ */
+async function tryResolveActiveAgentBreadcrumbInfo(
+    rawAgentIdentifier: string,
+): Promise<ActiveAgentBreadcrumbInfo | null> {
+    try {
+        const routeTarget = await resolveAgentRouteTarget(rawAgentIdentifier);
+        if (!routeTarget || routeTarget.kind !== 'local') {
+            return null;
+        }
+
+        const agentProfile = await getAgentProfile(routeTarget.canonicalAgentId);
+
+        return {
+            agentName: agentProfile.agentName,
+            agentHash: agentProfile.agentHash,
+            permanentId: agentProfile.permanentId,
+            meta: agentProfile.meta,
+        };
+    } catch {
+        return null;
+    }
+}
+
 /**
  * Shared route layout for all pages under `/agents/[agentName]`.
  */
 export default async function AgentLayout({
     children,
+    params,
 }: Readonly<{
     children: React.ReactNode;
+    params: Promise<{ agentName: string }>;
 }>) {
-    return <>{children}</>;
+    const rawAgentIdentifier = await getAgentName(params);
+    const activeAgentBreadcrumbInfo = await tryResolveActiveAgentBreadcrumbInfo(rawAgentIdentifier);
+
+    return (
+        <>
+            {activeAgentBreadcrumbInfo && <ActiveAgentBreadcrumbBinder agent={activeAgentBreadcrumbInfo} />}
+            {children}
+        </>
+    );
 }