@promptbook/cli 0.103.0-55 → 0.103.0-56

package/apps/agents-server/src/app/globals.css

@@ -54,6 +54,11 @@ body {
     font-family: var(--font-barlow-condensed), 'OpenMojiBlack', Arial, Helvetica, sans-serif;
 }
 
+/* Poppins font for agent names and headings */
+.font-poppins {
+    font-family: var(--font-poppins), 'Poppins', system-ui, -apple-system, sans-serif;
+}
+
 /* Custom utilities */
 .line-clamp-2 {
     display: -webkit-box;
@@ -135,6 +140,53 @@ textarea:focus-visible {
     animation: spin 1s linear infinite;
 }
 
+/* Tailwind CSS animation utilities */
+@keyframes fade-in {
+    from {
+        opacity: 0;
+    }
+    to {
+        opacity: 1;
+    }
+}
+
+@keyframes slide-in-from-top-2 {
+    from {
+        transform: translateY(-0.5rem);
+    }
+    to {
+        transform: translateY(0);
+    }
+}
+
+@keyframes zoom-in-95 {
+    from {
+        opacity: 0;
+        transform: scale(0.95);
+    }
+    to {
+        opacity: 1;
+        transform: scale(1);
+    }
+}
+
+.animate-in {
+    animation-duration: 200ms;
+    animation-fill-mode: both;
+}
+
+.fade-in {
+    animation-name: fade-in;
+}
+
+.slide-in-from-top-2 {
+    animation-name: slide-in-from-top-2;
+}
+
+.zoom-in-95 {
+    animation-name: zoom-in-95;
+}
+
 /* Gradient backgrounds */
 .bg-gradient-to-br {
     background-image: linear-gradient(to bottom right, var(--tw-gradient-stops));
@@ -145,3 +197,80 @@ textarea:focus-visible {
     background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%);
     border: 1px solid #e2e8f0;
 }
+
+/* Print styles */
+@media print {
+    @page {
+        margin: 2cm;
+    }
+
+    /* Hide UI elements */
+    header,
+    footer,
+    nav,
+    aside,
+    button:not(.print:block),
+    .no-print,
+    [role="complementary"],
+    #portal-root {
+        display: none !important;
+    }
+
+    /* Reset layout */
+    body,
+    main {
+        padding: 0 !important;
+        margin: 0 !important;
+        background: white !important;
+        min-height: auto !important;
+        width: 100% !important;
+        color: black !important;
+    }
+
+    /* Remove shadows and backgrounds for clean print */
+    * {
+        box-shadow: none !important;
+        text-shadow: none !important;
+        background-color: transparent !important;
+        background-image: none !important;
+    }
+
+    /* Ensure text visibility */
+    h1, h2, h3, h4, h5, h6, p, li, span, div {
+        color: black !important;
+    }
+
+    /* Links */
+    a {
+        text-decoration: underline;
+        color: black !important;
+    }
+
+    /* Preserve borders */
+    .border, .border-b, .border-t, .border-l, .border-r {
+        border-color: #ddd !important;
+    }
+
+    /* Page break control */
+    h1, h2 {
+        break-after: avoid;
+        page-break-after: avoid;
+    }
+
+    p, li, pre, code {
+        break-inside: avoid;
+        page-break-inside: avoid;
+    }
+
+    /* Specific component overrides */
+    .card, .bg-white {
+        border: none !important;
+    }
+
+    /* Code blocks */
+    pre, code {
+        background-color: #f5f5f5 !important;
+        border: 1px solid #ddd !important;
+        white-space: pre-wrap !important;
+    }
+}

package/apps/agents-server/src/app/layout.tsx

@@ -1,7 +1,7 @@
 import faviconLogoImage from '@/public/favicon.ico';
 import { LayoutWrapper } from '@/src/components/LayoutWrapper/LayoutWrapper';
 import type { Metadata } from 'next';
-import { Barlow_Condensed } from 'next/font/google';
+import { Barlow_Condensed, Poppins } from 'next/font/google';
 import { getMetadata } from '../database/getMetadata';
 import { $provideAgentCollectionForServer } from '../tools/$provideAgentCollectionForServer';
 import { $provideServer } from '../tools/$provideServer';
@@ -15,6 +15,12 @@ const barlowCondensed = Barlow_Condensed({
     variable: '--font-barlow-condensed',
 });
 
+const poppins = Poppins({
+    subsets: ['latin'],
+    weight: ['400', '500', '600', '700', '800'],
+    variable: '--font-poppins',
+});
+
 export async function generateMetadata(): Promise<Metadata> {
     const { publicUrl } = await $provideServer();
     const serverName = (await getMetadata('SERVER_NAME')) || 'Promptbook Agents Server';
@@ -98,7 +104,7 @@ export default async function RootLayout({
                 {/* Default favicon as a fallback */}
                 <link rel="icon" href={serverFaviconUrl} type="image/x-icon" />
             </head>
-            <body className={`${barlowCondensed.variable} antialiased bg-white text-gray-900`}>
+            <body className={`${barlowCondensed.variable} ${poppins.variable} antialiased bg-white text-gray-900`}>
                 <LayoutWrapper
                     isAdmin={isAdmin}
                     currentUser={currentUser}

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

@@ -41,7 +41,7 @@ export default async function manifest(): Promise<MetadataRoute.Manifest> {
         const description = agentProfile.meta.description || agentProfile.personaDescription || `Agent ${name}`;
 
         // Extract brand color from meta
-        const brandColor = Color.from(agentProfile.meta.color || PROMPTBOOK_COLOR);
+        const brandColor = Color.fromSafe(agentProfile.meta.color || PROMPTBOOK_COLOR);
         const theme_color = brandColor.toHex();
         const background_color = '#ffffff';
 

package/apps/agents-server/src/components/DocumentationContent/DocumentationContent.tsx

@@ -0,0 +1,87 @@
+import ReactMarkdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { string_book } from '../../../../../src/book-2.0/agent-source/string_book';
+import { BookEditor } from '../../../../../src/book-components/BookEditor/BookEditor';
+import { OpenMojiIcon } from '../OpenMojiIcon/OpenMojiIcon';
+
+type DocumentationContentProps = {
+    primary: {
+        type: string;
+        icon: string;
+        description?: string;
+        documentation: string;
+    };
+    aliases?: string[];
+    isPrintOnly?: boolean;
+};
+
+export function DocumentationContent({ primary, aliases = [], isPrintOnly = false }: DocumentationContentProps) {
+    return (
+        <div className={`bg-white rounded-xl shadow-lg border border-gray-200 overflow-hidden ${isPrintOnly ? 'shadow-none border-none' : ''}`}>
+            <div className={`p-8 border-b border-gray-100 bg-gray-50/50 ${isPrintOnly ? 'border-none bg-white p-0 mb-4' : ''}`}>
+                <div className="flex items-center gap-4 mb-4">
+                    <h1 className="text-4xl font-bold text-gray-900 tracking-tight">
+                        <OpenMojiIcon icon={primary.icon} className="mr-3" />
+                        {primary.type}
+                        {aliases.length > 0 && (
+                            <span className="text-gray-400 font-normal ml-4 text-2xl">
+                                / {aliases.join(' / ')}
+                            </span>
+                        )}
+                    </h1>
+                    {!isPrintOnly && (
+                        <span className="px-3 py-1 rounded-full text-xs font-medium bg-blue-100 text-blue-700">
+                            Commitment
+                        </span>
+                    )}
+                </div>
+                {primary.description && (
+                    <p className="text-xl text-gray-600 leading-relaxed max-w-3xl">
+                        {primary.description}
+                    </p>
+                )}
+            </div>
+            
+            <div className={`p-8 ${isPrintOnly ? 'p-0' : ''}`}>
+                <article className="prose prose-lg prose-slate max-w-none prose-headings:font-bold prose-headings:tracking-tight prose-headings:text-gray-900 prose-h1:text-4xl prose-h1:mb-8 prose-h2:text-2xl prose-h2:mt-12 prose-h2:mb-6 prose-h2:pb-2 prose-h2:border-b prose-h2:border-gray-200 prose-h3:text-xl prose-h3:mt-8 prose-h3:mb-4 prose-h3:text-gray-800 prose-p:text-gray-600 prose-p:leading-relaxed prose-p:mb-6 prose-a:text-blue-600 prose-a:no-underline hover:prose-a:text-blue-700 hover:prose-a:underline prose-a:transition-colors prose-strong:font-bold prose-strong:text-gray-900 prose-code:text-blue-600 prose-code:bg-blue-50 prose-code:px-1.5 prose-code:py-0.5 prose-code:rounded-md prose-code:before:content-none prose-code:after:content-none prose-code:font-medium prose-pre:bg-gray-900 prose-pre:text-gray-100 prose-pre:shadow-lg prose-pre:rounded-xl prose-pre:p-6 prose-ul:list-disc prose-ul:pl-6 prose-li:marker:text-gray-400 prose-li:mb-2 prose-ol:list-decimal prose-ol:pl-6 prose-li:mb-2 prose-blockquote:border-l-4 prose-blockquote:border-blue-500 prose-blockquote:bg-blue-50/50 prose-blockquote:py-2 prose-blockquote:px-4 prose-blockquote:rounded-r-lg prose-blockquote:not-italic prose-blockquote:text-gray-700 prose-blockquote:my-8 prose-img:rounded-xl prose-img:shadow-md prose-img:my-8 prose-hr:border-gray-200 prose-hr:my-10 prose-table:w-full prose-th:text-left prose-th:py-2 prose-th:px-3 prose-th:bg-gray-100 prose-th:font-semibold prose-th:text-gray-900 prose-td:py-2 prose-td:px-3 prose-td:border-b prose-td:border-gray-200 prose-tr:hover:bg-gray-50">
+                    <ReactMarkdown
+                        remarkPlugins={[remarkGfm]}
+                        components={{
+                            code(props) {
+                                const { children, className, node, ...rest } = props;
+                                const match = /language-(\w+)/.exec(className || '');
+                                if (match && match[1] === 'book') {
+                                    const value = String(children).replace(/\n$/, '');
+                                    // Estimate height: lines * 30px + padding
+                                    const lineCount = value.split('\n').length;
+                                    const height = lineCount * 30 + 40; // 30px per line + 40px buffer
+
+                                    return (
+                                        <div className="not-prose my-6 rounded-lg overflow-hidden border border-gray-200 shadow-sm print:border-gray-300">
+                                            <BookEditor
+                                                value={value as string_book}
+                                                isReadonly={true}
+                                                isVerbose={false}
+                                                height={`${height}px`}
+                                                isDownloadButtonShown={false}
+                                                isAboutButtonShown={false}
+                                                isFullscreenButtonShown={true}
+                                            />
+                                        </div>
+                                    );
+                                }
+                                return (
+                                    <code className={className} {...rest}>
+                                        {children}
+                                    </code>
+                                );
+                            },
+                        }}
+                    >
+                        {primary.documentation}
+                    </ReactMarkdown>
+                </article>
+            </div>
+        </div>
+    );
+}

package/apps/agents-server/src/components/OpenMojiIcon/OpenMojiIcon.tsx

@@ -0,0 +1,20 @@
+import { DetailedHTMLProps, HTMLAttributes } from 'react';
+
+type OpenMojiIconProps = DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement> & {
+    icon: string;
+};
+
+/**
+ * Renders an emoji using the OpenMoji black and white font
+ */
+export function OpenMojiIcon({ icon, className, style, ...rest }: OpenMojiIconProps) {
+    return (
+        <span
+            className={className}
+            style={{ ...style, fontFamily: '"OpenMojiBlack", sans-serif' }}
+            {...rest}
+        >
+            {icon}
+        </span>
+    );
+}

package/apps/agents-server/src/components/PrintButton/PrintButton.tsx

@@ -0,0 +1,18 @@
+'use client';
+
+import { OpenMojiIcon } from '../OpenMojiIcon/OpenMojiIcon';
+
+export function PrintButton() {
+    return (
+        <button
+            onClick={() => window.print()}
+            className="fixed bottom-8 right-8 bg-blue-600 hover:bg-blue-700 text-white rounded-full p-4 shadow-lg transition-all hover:scale-105 print:hidden z-50 flex items-center justify-center gap-2 group"
+            title="Print documentation"
+        >
+            <OpenMojiIcon icon="🖨️" className="text-2xl" />
+            <span className="max-w-0 overflow-hidden group-hover:max-w-xs transition-all duration-300 ease-in-out whitespace-nowrap">
+                Print
+            </span>
+        </button>
+    );
+}

package/apps/agents-server/src/components/PrintHeader/PrintHeader.tsx

@@ -0,0 +1,18 @@
+export function PrintHeader({ title }: { title?: string }) {
+    return (
+        <div className="hidden print:block mb-8 border-b-2 border-blue-600 pb-4">
+            <div className="flex justify-between items-end">
+                <div>
+                    <h1 className="text-3xl font-bold text-gray-900 font-poppins">Agents Server</h1>
+                    <div className="text-sm text-gray-500 mt-1 flex items-center gap-1">
+                        Powered by <span className="font-semibold text-blue-600">Promptbook</span>
+                    </div>
+                </div>
+                {title && <h2 className="text-xl font-semibold text-gray-700">{title}</h2>}
+            </div>
+            <div className="text-xs text-gray-400 mt-2 text-right">
+                {new Date().toLocaleDateString()}
+            </div>
+        </div>
+    );
+}

package/apps/agents-server/src/database/migrations/2025-12-0070-chat-history-source.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "ChatHistory" ADD COLUMN "source" TEXT CHECK ("source" IN ('AGENT_PAGE_CHAT', 'OPENAI_API_COMPATIBILITY'));
+ALTER TABLE "ChatHistory" ADD COLUMN "apiKey" TEXT;

package/apps/agents-server/src/database/schema.ts

@@ -128,6 +128,8 @@ export type AgentsServerDatabase = {
                     userAgent: string | null;
                     language: string | null;
                     platform: string | null;
+                    source: 'AGENT_PAGE_CHAT' | 'OPENAI_API_COMPATIBILITY' | null;
+                    apiKey: string | null;
                 };
                 Insert: {
                     id?: number;
@@ -143,6 +145,8 @@ export type AgentsServerDatabase = {
                     userAgent?: string | null;
                     language?: string | null;
                     platform?: string | null;
+                    source?: 'AGENT_PAGE_CHAT' | 'OPENAI_API_COMPATIBILITY' | null;
+                    apiKey?: string | null;
                 };
                 Update: {
                     id?: number;
@@ -158,6 +162,8 @@ export type AgentsServerDatabase = {
                     userAgent?: string | null;
                     language?: string | null;
                     platform?: string | null;
+                    source?: 'AGENT_PAGE_CHAT' | 'OPENAI_API_COMPATIBILITY' | null;
+                    apiKey?: string | null;
                 };
                 Relationships: [];
             };

package/apps/agents-server/src/utils/handleChatCompletion.ts

@@ -1,23 +1,53 @@
+import { $getTableName } from '@/src/database/$getTableName';
+import { $provideSupabaseForServer } from '@/src/database/$provideSupabaseForServer';
 import { $provideAgentCollectionForServer } from '@/src/tools/$provideAgentCollectionForServer';
-import { $provideExecutionToolsForServer } from '@/src/tools/$provideExecutionToolsForServer';
-import { Agent } from '@promptbook-local/core';
-import { ChatMessage, ChatPromptResult, Prompt, TODO_any } from '@promptbook-local/types';
+import { $provideOpenAiAssistantExecutionToolsForServer } from '@/src/tools/$provideOpenAiAssistantExecutionToolsForServer';
+import { Agent, computeAgentHash, PROMPTBOOK_ENGINE_VERSION } from '@promptbook-local/core';
+import { ChatMessage, ChatPromptResult, Prompt, string_book, TODO_any } from '@promptbook-local/types';
+import { computeHash } from '@promptbook-local/utils';
 import { NextRequest, NextResponse } from 'next/server';
+import { validateApiKey } from './validateApiKey';
 
 export async function handleChatCompletion(
     request: NextRequest,
-    params: { agentName: string },
-    title: string = 'API Chat Completion'
+    params: { agentName?: string },
+    title: string = 'API Chat Completion',
 ) {
-    const { agentName } = params;
+    const { agentName: agentNameFromParams } = params;
 
-    // Note: Authentication is handled by middleware
-    // If we are here, the request is either authenticated or public access is allowed (but middleware blocks it if not)
+    // Validate API key explicitly (in addition to middleware)
+    const apiKeyValidation = await validateApiKey(request);
+    if (!apiKeyValidation.isValid) {
+        return NextResponse.json(
+            {
+                error: {
+                    message: apiKeyValidation.error || 'Invalid API key',
+                    type: 'authentication_error',
+                },
+            },
+            { status: 401 },
+        );
+    }
+    const apiKey = apiKeyValidation.token || null;
 
     try {
         const body = await request.json();
         const { messages, stream, model } = body;
 
+        const agentName = agentNameFromParams || model;
+
+        if (!agentName) {
+            return NextResponse.json(
+                {
+                    error: {
+                        message: 'Agent name is required. Please provide it in the URL or as the "model" parameter.',
+                        type: 'invalid_request_error',
+                    },
+                },
+                { status: 400 },
+            );
+        }
+
         if (!messages || !Array.isArray(messages) || messages.length === 0) {
             return NextResponse.json(
                 {
@@ -31,7 +61,7 @@ export async function handleChatCompletion(
         }
 
         const collection = await $provideAgentCollectionForServer();
-        let agentSource;
+        let agentSource: string_book;
         try {
             agentSource = await collection.getAgentSource(agentName);
         } catch (error) {
@@ -48,16 +78,51 @@ export async function handleChatCompletion(
             );
         }
 
-        const executionTools = await $provideExecutionToolsForServer();
+        // Note: Handle system messages as CONTEXT
+        const systemMessages = messages.filter((msg: TODO_any) => msg.role === 'system');
+        if (systemMessages.length > 0) {
+            const contextString = systemMessages.map((msg: TODO_any) => `CONTEXT ${msg.content}`).join('\n');
+            agentSource = `${agentSource}\n\n${contextString}` as string_book;
+        }
+
+        const threadMessages = messages.filter((msg: TODO_any) => msg.role !== 'system');
+
+        if (threadMessages.length === 0) {
+            return NextResponse.json(
+                {
+                    error: {
+                        message: 'Messages array must contain at least one non-system message.',
+                        type: 'invalid_request_error',
+                    },
+                },
+                { status: 400 },
+            );
+        }
+
+        const openAiAssistantExecutionTools = await $provideOpenAiAssistantExecutionToolsForServer();
         const agent = new Agent({
             agentSource,
-            executionTools,
+            executionTools: {
+                llm: openAiAssistantExecutionTools, // Note: Use the same OpenAI Assistant LLM tools as the chat route
+            },
             isVerbose: true, // or false
         });
 
+        const agentHash = computeAgentHash(agentSource);
+        const userAgent = request.headers.get('user-agent');
+        const ip =
+            request.headers.get('x-forwarded-for') ||
+            request.headers.get('x-real-ip') ||
+            request.headers.get('x-client-ip');
+
+        // Note: Capture language and platform information
+        const language = request.headers.get('accept-language');
+        // Simple platform extraction from userAgent parentheses content (e.g., Windows NT 10.0; Win64; x64)
+        const platform = userAgent ? userAgent.match(/\(([^)]+)\)/)?.[1] : undefined; // <- TODO: [🧠] Improve platform parsing
+
         // Prepare thread and content
-        const lastMessage = messages[messages.length - 1];
-        const previousMessages = messages.slice(0, -1);
+        const lastMessage = threadMessages[threadMessages.length - 1];
+        const previousMessages = threadMessages.slice(0, -1);
 
         const thread: ChatMessage[] = previousMessages.map((msg: TODO_any, index: number) => ({
             id: `msg-${index}`, // Placeholder ID
@@ -67,6 +132,30 @@ export async function handleChatCompletion(
             date: new Date(), // We don't have the real date, using current
         }));
 
+        // Note: Identify the user message
+        const userMessageContent = {
+            role: 'USER',
+            content: lastMessage.content,
+        };
+
+        const supabase = $provideSupabaseForServer();
+        await supabase.from(await $getTableName('ChatHistory')).insert({
+            createdAt: new Date().toISOString(),
+            messageHash: computeHash(userMessageContent),
+            previousMessageHash: null,
+            agentName,
+            agentHash,
+            message: userMessageContent,
+            promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
+            url: request.url,
+            ip,
+            userAgent,
+            language,
+            platform,
+            source: 'OPENAI_API_COMPATIBILITY',
+            apiKey,
+        });
+
         const prompt: Prompt = {
             title,
             content: lastMessage.content,
@@ -86,10 +175,29 @@ export async function handleChatCompletion(
                     const runId = `chatcmpl-${Math.random().toString(36).substring(2, 15)}`;
                     const created = Math.floor(Date.now() / 1000);
 
+                    // Note: Send the initial chunk with role
+                    const initialChunkData = {
+                        id: runId,
+                        object: 'chat.completion.chunk',
+                        created,
+                        model: model || 'promptbook-agent',
+                        choices: [
+                            {
+                                index: 0,
+                                delta: {
+                                    role: 'assistant',
+                                    content: '',
+                                },
+                                finish_reason: null,
+                            },
+                        ],
+                    };
+                    controller.enqueue(encoder.encode(`data: ${JSON.stringify(initialChunkData)}\n\n`));
+
                     let previousContent = '';
 
                     try {
-                        await agent.callChatModelStream(prompt, (chunk: ChatPromptResult) => {
+                        const result = await agent.callChatModelStream(prompt, (chunk: ChatPromptResult) => {
                             const fullContent = chunk.content;
                             const deltaContent = fullContent.substring(previousContent.length);
                             previousContent = fullContent;
@@ -114,6 +222,36 @@ export async function handleChatCompletion(
                             }
                         });
 
+                        // Note: Identify the agent message
+                        const agentMessageContent = {
+                            role: 'MODEL',
+                            content: result.content,
+                        };
+
+                        // Record the agent message
+                        await supabase.from(await $getTableName('ChatHistory')).insert({
+                            createdAt: new Date().toISOString(),
+                            messageHash: computeHash(agentMessageContent),
+                            previousMessageHash: computeHash(userMessageContent),
+                            agentName,
+                            agentHash,
+                            message: agentMessageContent,
+                            promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
+                            url: request.url,
+                            ip,
+                            userAgent,
+                            language,
+                            platform,
+                            source: 'OPENAI_API_COMPATIBILITY',
+                            apiKey,
+                        });
+
+                        // Note: [🐱‍🚀] Save the learned data
+                        const newAgentSource = agent.agentSource.value;
+                        if (newAgentSource !== agentSource) {
+                            await collection.updateAgentSource(agentName, newAgentSource);
+                        }
+
                         const doneChunkData = {
                             id: runId,
                             object: 'chat.completion.chunk',
@@ -149,6 +287,36 @@ export async function handleChatCompletion(
         } else {
             const result = await agent.callChatModel(prompt);
 
+            // Note: Identify the agent message
+            const agentMessageContent = {
+                role: 'MODEL',
+                content: result.content,
+            };
+
+            // Record the agent message
+            await supabase.from(await $getTableName('ChatHistory')).insert({
+                createdAt: new Date().toISOString(),
+                messageHash: computeHash(agentMessageContent),
+                previousMessageHash: computeHash(userMessageContent),
+                agentName,
+                agentHash,
+                message: agentMessageContent,
+                promptbookEngineVersion: PROMPTBOOK_ENGINE_VERSION,
+                url: request.url,
+                ip,
+                userAgent,
+                language,
+                platform,
+                source: 'OPENAI_API_COMPATIBILITY',
+                apiKey,
+            });
+
+            // Note: [🐱‍🚀] Save the learned data
+            const newAgentSource = agent.agentSource.value;
+            if (newAgentSource !== agentSource) {
+                await collection.updateAgentSource(agentName, newAgentSource);
+            }
+
             return NextResponse.json({
                 id: `chatcmpl-${Math.random().toString(36).substring(2, 15)}`,
                 object: 'chat.completion',
@@ -181,3 +349,7 @@ export async function handleChatCompletion(
         );
     }
 }
+
+/**
+ * TODO: [🈹] Maybe move chat thread handling here
+ */

package/apps/agents-server/src/utils/resolveInheritedAgentSource.ts

@@ -35,13 +35,20 @@ export async function resolveInheritedAgentSource(
         // So we might need to parse the URL to extract agent name if it matches expected pattern.
         // For now, let's rely on fetch for external and check collection if it looks like a local reference (though FROM expects URL)
 
-        // If the URL is valid, we try to fetch it
-        // TODO: Handle authentication/tokens for private agents if needed
-        const response = await fetch(parentUrl);
+    // If the URL is valid, we try to fetch it
+    // TODO: Handle authentication/tokens for private agents if needed
 
-        if (!response.ok) {
-            throw new Error(`Failed to fetch parent agent from ${parentUrl}: ${response.status} ${response.statusText}`);
-        }
+    // TODO: [🧠] Do this logic more robustly
+    let fetchUrl = parentUrl;
+    if (!fetchUrl.endsWith('/api/book') && !fetchUrl.endsWith('.book') && !fetchUrl.endsWith('.md')) {
+        fetchUrl = `${fetchUrl.replace(/\/$/, '')}/api/book`;
+    }
+
+    const response = await fetch(fetchUrl);
+
+    if (!response.ok) {
+        throw new Error(`Failed to fetch parent agent from ${fetchUrl}: ${response.status} ${response.statusText}`);
+    }
 
         // We assume the response is the agent source text
         // TODO: Handle content negotiation or JSON responses if the server returns JSON