@promptbook/cli 0.113.0-9 → 0.114.0-0

package/apps/agents-server/src/utils/manGoOnboarding/manGoOnboardingAgentRuntime.ts

@@ -0,0 +1,426 @@
+import { extractOneBlockFromMarkdown } from '../../../../../src/utils/markdown/extractOneBlockFromMarkdown';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+import { PipelineExecutionError } from '../../../../../src/errors/PipelineExecutionError';
+import { LiteAgent } from '../../../../../src/book-3.0/LiteAgent';
+import type { string_markdown } from '../../../../../src/types/string_markdown';
+import { validateBook } from '../../../../../src/book-2.0/agent-source/string_book';
+import { spaceTrim } from 'spacetrim';
+import {
+    MAN_GO_BOOK_EXPERT_BOOK,
+    MAN_GO_DRAFT_EXPERT_BOOK,
+    MAN_GO_REPLY_REVIEWER_BOOK,
+} from './manGoOnboardingAgentBooks';
+
+/**
+ * Chat message accepted by the manGo onboarding test runner.
+ */
+export type ManGoOnboardingTestMessage = {
+    readonly role: 'user' | 'agent';
+    readonly content: string;
+};
+
+/**
+ * Reply returned by the manGo onboarding test runner.
+ */
+export type ManGoOnboardingTestReply = {
+    readonly role: 'agent';
+    readonly content: string;
+};
+
+/**
+ * One AI-generated check for the step 4 test reply.
+ */
+export type ManGoOnboardingReplyCheck = {
+    readonly status: 'ok' | 'warn';
+    readonly text: string;
+};
+
+/**
+ * Inputs used to generate the first editable Book draft.
+ */
+export type GenerateManGoBookDraftInput = {
+    readonly agentName: string;
+    readonly agentBrief: string;
+};
+
+/**
+ * Input used by the Book language conversion panel.
+ */
+export type ConvertManGoDraftToBookInput = {
+    readonly input: string;
+};
+
+/**
+ * Input used by the step 4 live agent test.
+ */
+export type RunManGoAgentTestInput = {
+    readonly bookSource: string;
+    readonly knowledge: readonly string[];
+    readonly messages: readonly ManGoOnboardingTestMessage[];
+};
+
+/**
+ * Input used by the step 4 reply evaluator.
+ */
+export type EvaluateManGoAgentReplyInput = {
+    readonly bookSource: string;
+    readonly customerEmail: string;
+    readonly reply: string;
+};
+
+/**
+ * Fallback source used when step 4 is called before the draft exists.
+ *
+ * @private internal constant of manGo onboarding agent utilities
+ */
+const MAN_GO_TEST_FALLBACK_BOOK = spaceTrim(`
+    Agent
+
+    PERSONA Jste užitečný asistent.
+    RULE Odpovídejte stručně a prakticky.
+    CLOSED
+`);
+
+/**
+ * Runs one lightweight Promptbook agent from an inline Book source.
+ *
+ * @param bookSource - Book source defining the helper agent.
+ * @param message - Message sent to the helper agent.
+ * @param context - Optional extra context.
+ * @returns Final text generated by the helper agent.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+async function runManGoLiteAgent(options: {
+    readonly bookSource: string;
+    readonly message: string;
+    readonly context?: string;
+}): Promise<string> {
+    const agent = new LiteAgent({
+        book: options.bookSource,
+        isVerbose: true,
+    });
+
+    return agent.run(options.message, options.context ? { context: options.context } : undefined);
+}
+
+/**
+ * Extracts the only fenced code block from a model response, falling back to trimmed text.
+ *
+ * @param response - Raw model response.
+ * @returns Code-block content, or the raw response when no single block exists.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+function extractSingleBlockContent(response: string): string {
+    try {
+        return extractOneBlockFromMarkdown(response as string_markdown).content.trim();
+    } catch {
+        return response.trim();
+    }
+}
+
+/**
+ * Creates a prompt that asks the imported draft expert for a real Book-language draft.
+ *
+ * @param input - Wizard name and brief.
+ * @returns Prompt for the draft expert agent.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+function createBookDraftPrompt(input: GenerateManGoBookDraftInput): string {
+    return spaceTrim(`
+        Write an editable Promptbook Book-language draft for an AI agent.
+
+        Return only one \`book\` code block. Do not include any explanation outside the block.
+
+        Requirements:
+        - Use the provided name as the agent title.
+        - Write natural-language commitments in Czech unless the brief clearly asks for another language.
+        - Include a useful PERSONA, GOAL, and practical RULE commitments derived from the brief.
+        - Keep commitment keywords in English.
+        - End the book with CLOSED.
+
+        Name: ${input.agentName}
+        Description: ${input.agentBrief}
+    `);
+}
+
+/**
+ * Creates a first editable Book draft through the imported manGo onboarding AI agent.
+ *
+ * @param input - Agent name and brief captured by the entry step.
+ * @returns Editable Book source for the next wizard steps.
+ */
+export async function generateManGoBookDraft(input: GenerateManGoBookDraftInput): Promise<string> {
+    const agentName = input.agentName.trim();
+    const agentBrief = input.agentBrief.trim();
+
+    if (!agentName || !agentBrief) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Cannot generate a manGo Book draft without both \`agentName\` and \`agentBrief\`.
+
+                Fill in the onboarding assignment before generating the draft.
+            `),
+        );
+    }
+
+    const response = await runManGoLiteAgent({
+        bookSource: MAN_GO_DRAFT_EXPERT_BOOK,
+        message: createBookDraftPrompt({ agentName, agentBrief }),
+    });
+    const book = extractSingleBlockContent(response);
+
+    if (!book) {
+        throw new PipelineExecutionError(
+            spaceTrim(`
+                The manGo draft expert returned an empty Book draft.
+
+                Try regenerating the draft from the onboarding step.
+            `),
+        );
+    }
+
+    return book;
+}
+
+/**
+ * Converts free-form draft text into canonical Book language through the imported book expert.
+ *
+ * @param input - Free-form editor content.
+ * @returns Generated Book source and validation flag.
+ */
+export async function convertManGoDraftToBook(
+    input: ConvertManGoDraftToBookInput,
+): Promise<{ readonly book: string; readonly isValid: boolean }> {
+    const normalizedInput = input.input.trim();
+
+    if (!normalizedInput) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Cannot convert an empty draft to Book language.
+
+                Add draft content before running the manGo Book conversion.
+            `),
+        );
+    }
+
+    const response = await runManGoLiteAgent({
+        bookSource: MAN_GO_BOOK_EXPERT_BOOK,
+        message: spaceTrim(`
+            Create a book that defines an agent with the following input:
+
+            Wrap the output in a single \`book\` code block.
+
+            Input:
+            ${normalizedInput}
+        `),
+    });
+    const book = extractSingleBlockContent(response);
+
+    let isValid = true;
+    try {
+        validateBook(book);
+    } catch {
+        isValid = false;
+    }
+
+    return { book, isValid };
+}
+
+/**
+ * Resolves the most recent user message from a step 4 test conversation.
+ *
+ * @param messages - Test conversation history.
+ * @returns Index and content for the latest user message.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+function findLastUserMessage(messages: readonly ManGoOnboardingTestMessage[]): {
+    readonly lastUserIndex: number;
+    readonly message: string;
+} {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        if (messages[index]?.role === 'user') {
+            return {
+                lastUserIndex: index,
+                message: messages[index]!.content.trim(),
+            };
+        }
+    }
+
+    return {
+        lastUserIndex: -1,
+        message: '',
+    };
+}
+
+/**
+ * Returns only HTTP(S) knowledge URLs ready for insertion into a Book source.
+ *
+ * @param knowledge - Raw knowledge source URLs from the wizard client.
+ * @returns Valid HTTP(S) knowledge URLs.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+function normalizeKnowledgeUrls(knowledge: readonly string[]): readonly string[] {
+    return knowledge.map((url) => url.trim()).filter((url) => /^https?:\/\//i.test(url));
+}
+
+/**
+ * Builds a testable Book source by appending ready knowledge commitments.
+ *
+ * @param bookSource - Current editor source.
+ * @param knowledge - Raw knowledge source URLs.
+ * @returns Book source passed to the tested agent.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+function createAgentTestBook(bookSource: string, knowledge: readonly string[]): string {
+    const baseBook = bookSource.trim() || MAN_GO_TEST_FALLBACK_BOOK;
+    const knowledgeCommitments = normalizeKnowledgeUrls(knowledge)
+        .filter((url) => !baseBook.includes(`KNOWLEDGE ${url}`))
+        .map((url) => `KNOWLEDGE ${url}`);
+
+    if (knowledgeCommitments.length === 0) {
+        return baseBook;
+    }
+
+    return `${baseBook}\n\n${knowledgeCommitments.join('\n')}\n`;
+}
+
+/**
+ * Formats prior test turns as plain context for the tested agent.
+ *
+ * @param messages - Test conversation history.
+ * @param lastUserIndex - Index of the latest user message.
+ * @returns Context string for the agent.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+function createAgentTestContext(messages: readonly ManGoOnboardingTestMessage[], lastUserIndex: number): string {
+    const priorMessages = messages.slice(0, lastUserIndex);
+
+    if (priorMessages.length === 0) {
+        return '';
+    }
+
+    return spaceTrim(`
+        Předchozí konverzace:
+        ${priorMessages.map((entry) => `${entry.role === 'user' ? 'Uživatel' : 'Agent'}: ${entry.content}`).join('\n')}
+    `);
+}
+
+/**
+ * Runs the currently edited agent through the real Promptbook LiteAgent runtime for step 4.
+ *
+ * @param input - Current source, knowledge URLs, and test messages.
+ * @returns Agent reply.
+ */
+export async function runManGoAgentTest(input: RunManGoAgentTestInput): Promise<ManGoOnboardingTestReply> {
+    const { lastUserIndex, message } = findLastUserMessage(input.messages);
+
+    if (!message) {
+        return { role: 'agent', content: 'Zadejte prosím testovací zprávu.' };
+    }
+
+    const response = await runManGoLiteAgent({
+        bookSource: createAgentTestBook(input.bookSource, input.knowledge),
+        message,
+        context: createAgentTestContext(input.messages, lastUserIndex),
+    });
+
+    return { role: 'agent', content: response };
+}
+
+/**
+ * Parses reviewer JSON output into checks shown in step 4.
+ *
+ * @param response - Raw reviewer response.
+ * @returns Parsed checks, capped to five items.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+function parseReplyChecks(response: string): ManGoOnboardingReplyCheck[] {
+    const candidates: string[] = [];
+
+    try {
+        candidates.push(extractOneBlockFromMarkdown(response as string_markdown).content);
+    } catch {
+        // Continue with raw response candidates below.
+    }
+
+    candidates.push(response);
+
+    const bracketedJson = response.match(/\[[\s\S]*\]/);
+    if (bracketedJson) {
+        candidates.push(bracketedJson[0]);
+    }
+
+    for (const candidate of candidates) {
+        try {
+            const parsed: unknown = JSON.parse(candidate);
+
+            if (!Array.isArray(parsed)) {
+                continue;
+            }
+
+            return parsed.filter(isReplyCheck).slice(0, 5);
+        } catch {
+            // Try the next candidate.
+        }
+    }
+
+    return [];
+}
+
+/**
+ * Checks whether an unknown JSON item is a supported step 4 reply check.
+ *
+ * @param item - Unknown JSON item.
+ * @returns Whether the item is a reply check.
+ *
+ * @private internal utility of manGo onboarding agent utilities
+ */
+function isReplyCheck(item: unknown): item is ManGoOnboardingReplyCheck {
+    return (
+        typeof item === 'object' &&
+        item !== null &&
+        ((item as ManGoOnboardingReplyCheck).status === 'ok' ||
+            (item as ManGoOnboardingReplyCheck).status === 'warn') &&
+        typeof (item as ManGoOnboardingReplyCheck).text === 'string'
+    );
+}
+
+/**
+ * Evaluates one generated step 4 reply against the current Book through the imported reviewer agent.
+ *
+ * @param input - Current source, customer email, and generated reply.
+ * @returns Reviewer checks for the UI.
+ */
+export async function evaluateManGoAgentReply(
+    input: EvaluateManGoAgentReplyInput,
+): Promise<{ readonly checks: ManGoOnboardingReplyCheck[] }> {
+    const response = await runManGoLiteAgent({
+        bookSource: MAN_GO_REPLY_REVIEWER_BOOK,
+        message: spaceTrim(`
+            Zhodnoťte návrh odpovědi proti definici agenta (book).
+
+            # Book (definice agenta)
+            ${input.bookSource}
+
+            # E-mail zákazníka
+            ${input.customerEmail}
+
+            # Návrh odpovědi
+            ${input.reply}
+
+            Vraťte JSON pole kontrol. Každá položka: { "status": "ok" | "warn", "text": "<krátká česká věta>" }.
+            Zahrňte 2-5 kontrol - co odpovídá booku (ok) i případná porušení pravidel, tonality, délky či jazyka (warn).
+            Výstup zabalte do jednoho \`json\` bloku.
+        `),
+    });
+
+    return { checks: parseReplyChecks(response) };
+}

package/apps/agents-server/src/utils/manGoOnboarding/manGoOnboardingApiRequest.ts

@@ -0,0 +1,100 @@
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+import { spaceTrim } from 'spacetrim';
+import type { ManGoOnboardingTestMessage } from './manGoOnboardingAgentRuntime';
+
+/**
+ * Reads one string property from an unknown manGo onboarding JSON body.
+ *
+ * @param body - Unknown request body.
+ * @param propertyName - Required property name.
+ * @returns String property value.
+ */
+export function readManGoOnboardingStringProperty(body: unknown, propertyName: string): string {
+    if (!body || typeof body !== 'object' || typeof (body as Record<string, unknown>)[propertyName] !== 'string') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Request body must include string property \`${propertyName}\`.
+            `),
+        );
+    }
+
+    return (body as Record<string, string>)[propertyName];
+}
+
+/**
+ * Reads one string-array property from an unknown manGo onboarding JSON body.
+ *
+ * @param body - Unknown request body.
+ * @param propertyName - Required property name.
+ * @returns String array property value.
+ */
+export function readManGoOnboardingStringArrayProperty(body: unknown, propertyName: string): readonly string[] {
+    if (!body || typeof body !== 'object') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Request body must include array property \`${propertyName}\`.
+            `),
+        );
+    }
+
+    const value = (body as Record<string, unknown>)[propertyName];
+
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string')) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Request body property \`${propertyName}\` must be an array of strings.
+            `),
+        );
+    }
+
+    return value;
+}
+
+/**
+ * Reads and validates test messages from an unknown manGo onboarding JSON body.
+ *
+ * @param body - Unknown request body.
+ * @returns Test messages.
+ */
+export function readManGoOnboardingTestMessages(body: unknown): readonly ManGoOnboardingTestMessage[] {
+    if (!body || typeof body !== 'object' || !Array.isArray((body as Record<string, unknown>).messages)) {
+        throw new NotAllowed(
+            spaceTrim(`
+                Request body must include array property \`messages\`.
+            `),
+        );
+    }
+
+    return ((body as Record<string, unknown>).messages as unknown[]).map(readManGoOnboardingTestMessage);
+}
+
+/**
+ * Reads one test message object from an unknown JSON item.
+ *
+ * @param message - Unknown message item.
+ * @returns Test message.
+ *
+ * @private internal utility of manGo onboarding API request parsing
+ */
+function readManGoOnboardingTestMessage(message: unknown): ManGoOnboardingTestMessage {
+    if (!message || typeof message !== 'object') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Every \`messages\` item must be an object.
+            `),
+        );
+    }
+
+    const role = (message as Record<string, unknown>).role;
+    const content = (message as Record<string, unknown>).content;
+
+    if ((role !== 'user' && role !== 'agent') || typeof content !== 'string') {
+        throw new NotAllowed(
+            spaceTrim(`
+                Every \`messages\` item must include \`role\` and string \`content\`.
+            `),
+        );
+    }
+
+    return { role, content };
+}

package/apps/agents-server/src/utils/manGoOnboarding/manGoOnboardingApiResponses.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+import { assertsError } from '../../../../../src/errors/assertsError';
+import { NotAllowed } from '../../../../../src/errors/NotAllowed';
+
+/**
+ * Creates a JSON response for manGo onboarding API failures.
+ *
+ * @param error - Error caught by the route handler.
+ * @returns JSON response with a stable error shape.
+ */
+export function createManGoOnboardingApiErrorResponse(error: unknown): NextResponse {
+    assertsError(error);
+
+    const status = error instanceof NotAllowed ? 400 : 500;
+
+    if (status >= 500) {
+        console.error('[manGo onboarding] AI agent request failed', error);
+    }
+
+    return NextResponse.json(
+        {
+            error: {
+                message: error.message,
+            },
+        },
+        { status },
+    );
+}

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

@@ -29,6 +29,20 @@ export type MessageSendAttemptRow = {
     raw: Json;
 };
 
+/**
+ * Message list sort fields supported by the admin API.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type MessageSortField = 'createdAt' | 'channel' | 'direction' | 'content';
+
+/**
+ * Message list sort direction supported by the admin API.
+ *
+ * @private internal admin utility of Agents Server
+ */
+export type MessageSortOrder = 'asc' | 'desc';
+
 /**
  * Response for messages list.
  */
@@ -37,6 +51,8 @@ export type MessagesListResponse = {
     total: number;
     page: number;
     pageSize: number;
+    sortBy: MessageSortField;
+    sortOrder: MessageSortOrder;
 };
 
 /**
@@ -48,6 +64,8 @@ export type MessagesListParams = {
     search?: string;
     channel?: string;
     direction?: string;
+    sortBy?: MessageSortField;
+    sortOrder?: MessageSortOrder;
 };
 
 /**
@@ -61,6 +79,8 @@ function buildQuery(params: MessagesListParams): string {
     if (params.search) searchParams.set('search', params.search);
     if (params.channel) searchParams.set('channel', params.channel);
     if (params.direction) searchParams.set('direction', params.direction);
+    if (params.sortBy) searchParams.set('sortBy', params.sortBy);
+    if (params.sortOrder) searchParams.set('sortOrder', params.sortOrder);
 
     const qs = searchParams.toString();
     return qs ? `?${qs}` : '';

package/apps/agents-server/src/utils/mockedChats/$saveMockedChatPresetFromMessages.ts

@@ -0,0 +1,61 @@
+import type { MockedChatPreset } from '@/src/utils/mockedChatsSchema';
+import {
+    createMockedChatPresetFromChatMessages,
+    type MockedChatSourceMessage,
+} from './createMockedChatPresetFromChatMessages';
+
+/**
+ * API endpoint shared with the mocked-chat editor.
+ *
+ * @private constant of `$saveMockedChatPresetFromMessages`
+ */
+const MOCKED_CHATS_API_ENDPOINT = '/api/system/mocked-chats';
+
+/**
+ * Route of the mocked-chat editor utility page.
+ */
+export const MOCKED_CHATS_EDITOR_ROUTE = '/system/utilities/mocked-chats';
+
+/**
+ * API payload returned by mocked-chat routes.
+ *
+ * @private type of `$saveMockedChatPresetFromMessages`
+ */
+type MockedChatsApiPayload = {
+    mockedChats?: Array<MockedChatPreset>;
+    error?: string;
+};
+
+/**
+ * Builds one mocked-chat preset from recorded messages and persists it for the current user.
+ *
+ * Used by the "Create mock" buttons in the admin chat history and the external-chat view.
+ *
+ * @returns The persisted preset so callers can navigate to the editor.
+ */
+export async function $saveMockedChatPresetFromMessages(options: {
+    name: string;
+    messages: ReadonlyArray<MockedChatSourceMessage>;
+}): Promise<MockedChatPreset> {
+    const preset = createMockedChatPresetFromChatMessages(options);
+
+    const currentResponse = await fetch(MOCKED_CHATS_API_ENDPOINT, { method: 'GET' });
+    const currentPayload = (await currentResponse.json().catch(() => ({}))) as MockedChatsApiPayload;
+    if (!currentResponse.ok || !Array.isArray(currentPayload.mockedChats)) {
+        throw new Error(currentPayload.error || 'Failed to load existing mocked chats.');
+    }
+
+    const saveResponse = await fetch(MOCKED_CHATS_API_ENDPOINT, {
+        method: 'PUT',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ mockedChats: [...currentPayload.mockedChats, preset] }),
+    });
+    const savePayload = (await saveResponse.json().catch(() => ({}))) as MockedChatsApiPayload;
+    if (!saveResponse.ok || !Array.isArray(savePayload.mockedChats)) {
+        throw new Error(savePayload.error || 'Failed to save the mocked chat.');
+    }
+
+    return savePayload.mockedChats.find((mockedChat) => mockedChat.id === preset.id) || preset;
+}