@promptbook/cli 0.113.0-1 → 0.113.0-11

package/apps/agents-server/src/app/agents/[agentName]/export-as-transpiled-code/useAgentCodeExportState.ts

@@ -0,0 +1,478 @@
+'use client';
+
+import type { AgentBasicInformation } from '@promptbook-local/types';
+import { useCallback, useEffect, useState } from 'react';
+import { downloadBlob, parseFilenameFromContentDisposition } from '../../../../utils/download/browserFileDownload';
+import type { Transpiler } from './Transpiler';
+
+/**
+ * Minimal payload returned by the transpiler-list endpoint.
+ *
+ * @private type of `useAgentCodeExportState`
+ */
+type TranspilerListResponse = {
+    readonly transpilers?: Array<Transpiler>;
+};
+
+/**
+ * Result returned by the transpilation endpoint.
+ *
+ * @private type of `useAgentCodeExportState`
+ */
+type TranspilationResult = {
+    readonly code: string;
+    readonly transpiler: Transpiler;
+};
+
+/**
+ * Minimal API error payload accepted from export endpoints.
+ *
+ * @private type of `useAgentCodeExportState`
+ */
+type TranspiledCodeApiErrorPayload = {
+    readonly error?: string;
+    readonly message?: string;
+};
+
+/**
+ * State and actions used by the export-as-transpiled-code page client.
+ *
+ * @private type of `<AgentCodePageClient/>`
+ */
+export type AgentCodeExportState = {
+    readonly agentProfile: AgentBasicInformation | null;
+    readonly transpilers: Array<Transpiler>;
+    readonly selectedTranspilerName: string;
+    readonly selectedTranspiler: Transpiler | null;
+    readonly transpiledCode: string;
+    readonly isPageLoading: boolean;
+    readonly isTranspiling: boolean;
+    readonly isDownloading: boolean;
+    readonly pageErrorMessage: string | null;
+    readonly transpileErrorMessage: string | null;
+    readonly downloadErrorMessage: string | null;
+    readonly downloadButtonLabel: string;
+    readonly isDownloadButtonDisabled: boolean;
+    readonly selectTranspiler: (transpilerName: string) => void;
+    readonly downloadTranspiledCode: () => Promise<void>;
+};
+
+/**
+ * Collects the export-as-transpiled-code page state, data loading, and download action behind one focused hook.
+ *
+ * @param agentName - Routed agent name.
+ * @returns State and actions needed to render `<AgentCodePageClient/>`.
+ *
+ * @private hook of `<AgentCodePageClient/>`
+ */
+export function useAgentCodeExportState(agentName: string): AgentCodeExportState {
+    const agentProfile = useAgentProfile(agentName);
+    const { transpilers, selectedTranspilerName, selectTranspiler, isPageLoading, pageErrorMessage } =
+        useAgentTranspilers(agentName);
+    const { transpiledCode, isTranspiling, transpileErrorMessage } = useTranspiledCode({
+        agentName,
+        selectedTranspilerName,
+    });
+    const { isDownloading, downloadErrorMessage, downloadTranspiledCode } = useTranspiledCodeDownload({
+        agentName,
+        selectedTranspilerName,
+    });
+
+    const selectedTranspiler = transpilers.find((transpiler) => transpiler.name === selectedTranspilerName) || null;
+    const downloadButtonLabel = isDownloading ? 'Preparing ZIP...' : 'Download ZIP';
+    const isDownloadButtonDisabled = !selectedTranspilerName || isPageLoading || isTranspiling || isDownloading;
+
+    return {
+        agentProfile,
+        transpilers,
+        selectedTranspilerName,
+        selectedTranspiler,
+        transpiledCode,
+        isPageLoading,
+        isTranspiling,
+        isDownloading,
+        pageErrorMessage,
+        transpileErrorMessage,
+        downloadErrorMessage,
+        downloadButtonLabel,
+        isDownloadButtonDisabled,
+        selectTranspiler,
+        downloadTranspiledCode,
+    };
+}
+
+/**
+ * Loads the agent profile shown in the export page header.
+ *
+ * @param agentName - Routed agent name.
+ * @returns Loaded agent profile, or `null` while loading or when unavailable.
+ *
+ * @private hook of `useAgentCodeExportState`
+ */
+function useAgentProfile(agentName: string): AgentBasicInformation | null {
+    const [agentProfile, setAgentProfile] = useState<AgentBasicInformation | null>(null);
+
+    useEffect(() => {
+        const abortController = new AbortController();
+        let isDisposed = false;
+
+        setAgentProfile(null);
+
+        void (async () => {
+            try {
+                const profile = await fetchAgentProfile(agentName, abortController.signal);
+                if (profile && !isDisposed) {
+                    setAgentProfile(profile);
+                }
+            } catch (error) {
+                if (!abortController.signal.aborted) {
+                    console.error('Error fetching agent profile:', error);
+                }
+            }
+        })();
+
+        return () => {
+            isDisposed = true;
+            abortController.abort();
+        };
+    }, [agentName]);
+
+    return agentProfile;
+}
+
+/**
+ * Loads the list of transpilers and tracks which one is selected for the current agent.
+ *
+ * @param agentName - Routed agent name.
+ * @returns Transpiler list, selection state, and page-level loading/error state.
+ *
+ * @private hook of `useAgentCodeExportState`
+ */
+function useAgentTranspilers(agentName: string): {
+    readonly transpilers: Array<Transpiler>;
+    readonly selectedTranspilerName: string;
+    readonly selectTranspiler: (transpilerName: string) => void;
+    readonly isPageLoading: boolean;
+    readonly pageErrorMessage: string | null;
+} {
+    const [transpilers, setTranspilers] = useState<Array<Transpiler>>([]);
+    const [selectedTranspilerName, setSelectedTranspilerName] = useState('');
+    const [isPageLoading, setIsPageLoading] = useState(true);
+    const [pageErrorMessage, setPageErrorMessage] = useState<string | null>(null);
+
+    useEffect(() => {
+        const abortController = new AbortController();
+        let isDisposed = false;
+
+        setIsPageLoading(true);
+        setPageErrorMessage(null);
+        setTranspilers([]);
+        setSelectedTranspilerName('');
+
+        void (async () => {
+            try {
+                const nextTranspilers = await fetchTranspilerList(agentName, abortController.signal);
+                if (isDisposed) {
+                    return;
+                }
+
+                setTranspilers(nextTranspilers);
+                setSelectedTranspilerName(nextTranspilers[0]?.name || '');
+            } catch (error) {
+                if (abortController.signal.aborted || isDisposed) {
+                    return;
+                }
+
+                setPageErrorMessage(getErrorMessage(error, 'Failed to load transpilers'));
+            } finally {
+                if (!isDisposed) {
+                    setIsPageLoading(false);
+                }
+            }
+        })();
+
+        return () => {
+            isDisposed = true;
+            abortController.abort();
+        };
+    }, [agentName]);
+
+    const selectTranspiler = useCallback((transpilerName: string) => {
+        setSelectedTranspilerName(transpilerName);
+    }, []);
+
+    return { transpilers, selectedTranspilerName, selectTranspiler, isPageLoading, pageErrorMessage };
+}
+
+/**
+ * Generates the transpiled code for the selected transpiler.
+ *
+ * @param options - Routed agent name and selected transpiler name.
+ * @returns Generated code plus its loading/error state.
+ *
+ * @private hook of `useAgentCodeExportState`
+ */
+function useTranspiledCode(options: { readonly agentName: string; readonly selectedTranspilerName: string }): {
+    readonly transpiledCode: string;
+    readonly isTranspiling: boolean;
+    readonly transpileErrorMessage: string | null;
+} {
+    const { agentName, selectedTranspilerName } = options;
+    const [transpiledCode, setTranspiledCode] = useState('');
+    const [isTranspiling, setIsTranspiling] = useState(false);
+    const [transpileErrorMessage, setTranspileErrorMessage] = useState<string | null>(null);
+
+    useEffect(() => {
+        // Note: Without a selected transpiler there is nothing to generate, so clear any previous result.
+        if (!selectedTranspilerName) {
+            setIsTranspiling(false);
+            setTranspiledCode('');
+            setTranspileErrorMessage(null);
+            return;
+        }
+
+        const abortController = new AbortController();
+        let isDisposed = false;
+
+        setIsTranspiling(true);
+        setTranspileErrorMessage(null);
+        setTranspiledCode('');
+
+        void (async () => {
+            try {
+                const code = await fetchTranspiledCode(agentName, selectedTranspilerName, abortController.signal);
+                if (!isDisposed) {
+                    setTranspiledCode(code);
+                }
+            } catch (error) {
+                if (abortController.signal.aborted || isDisposed) {
+                    return;
+                }
+
+                setTranspileErrorMessage(getErrorMessage(error, 'Failed to transpile code'));
+            } finally {
+                if (!isDisposed) {
+                    setIsTranspiling(false);
+                }
+            }
+        })();
+
+        return () => {
+            isDisposed = true;
+            abortController.abort();
+        };
+    }, [agentName, selectedTranspilerName]);
+
+    return { transpiledCode, isTranspiling, transpileErrorMessage };
+}
+
+/**
+ * Handles the ZIP download of the selected transpiled harness.
+ *
+ * @param options - Routed agent name and selected transpiler name.
+ * @returns Download state and the action that triggers the browser download.
+ *
+ * @private hook of `useAgentCodeExportState`
+ */
+function useTranspiledCodeDownload(options: {
+    readonly agentName: string;
+    readonly selectedTranspilerName: string;
+}): {
+    readonly isDownloading: boolean;
+    readonly downloadErrorMessage: string | null;
+    readonly downloadTranspiledCode: () => Promise<void>;
+} {
+    const { agentName, selectedTranspilerName } = options;
+    const [isDownloading, setIsDownloading] = useState(false);
+    const [downloadErrorMessage, setDownloadErrorMessage] = useState<string | null>(null);
+
+    useEffect(() => {
+        // Note: A previous download error no longer applies once the agent or selected transpiler changes.
+        setDownloadErrorMessage(null);
+    }, [agentName, selectedTranspilerName]);
+
+    const downloadTranspiledCode = useCallback(async () => {
+        if (!selectedTranspilerName || isDownloading) {
+            return;
+        }
+
+        setIsDownloading(true);
+        setDownloadErrorMessage(null);
+
+        try {
+            const { blob, filename } = await fetchTranspiledCodeDownload(agentName, selectedTranspilerName);
+            downloadBlob(blob, filename);
+        } catch (error) {
+            setDownloadErrorMessage(getErrorMessage(error, 'Failed to download ZIP export'));
+        } finally {
+            setIsDownloading(false);
+        }
+    }, [agentName, isDownloading, selectedTranspilerName]);
+
+    return { isDownloading, downloadErrorMessage, downloadTranspiledCode };
+}
+
+/**
+ * Creates the JSON export API path for one agent.
+ *
+ * @param agentName - Routed agent name.
+ * @returns Relative API path used for transpiler listing and code generation.
+ *
+ * @private function of `useAgentCodeExportState`
+ */
+function createTranspiledCodeApiPath(agentName: string): string {
+    return `/agents/${encodeURIComponent(agentName)}/export-as-transpiled-code/api`;
+}
+
+/**
+ * Creates the ZIP download API path for one agent and selected transpiler.
+ *
+ * @param agentName - Routed agent name.
+ * @param transpilerName - Selected transpiler identifier.
+ * @returns Relative download URL with the selected transpiler encoded in the query string.
+ *
+ * @private function of `useAgentCodeExportState`
+ */
+function createTranspiledCodeDownloadApiPath(agentName: string, transpilerName: string): string {
+    const searchParams = new URLSearchParams({ transpilerName });
+    return `${createTranspiledCodeApiPath(agentName)}/download?${searchParams.toString()}`;
+}
+
+/**
+ * Reads a user-facing API error from a failed export response.
+ *
+ * @param response - Failed HTTP response.
+ * @param fallbackMessage - Fallback message when the body has no structured error.
+ * @returns Friendly error message suitable for rendering in the UI.
+ *
+ * @private function of `useAgentCodeExportState`
+ */
+async function resolveTranspiledCodeApiErrorMessage(response: Response, fallbackMessage: string): Promise<string> {
+    try {
+        const payload = (await response.json()) as TranspiledCodeApiErrorPayload;
+        const message = payload.message || payload.error;
+
+        if (message && message.trim().length > 0) {
+            return message.trim();
+        }
+    } catch {
+        // Keep the fallback message when the error body is not valid JSON.
+    }
+
+    return fallbackMessage;
+}
+
+/**
+ * Loads the list of transpilers available for the agent export.
+ *
+ * @param agentName - Routed agent name.
+ * @param signal - Abort signal cancelling the request when the effect is disposed.
+ * @returns Available transpilers, or an empty list when none are returned.
+ *
+ * @private function of `useAgentCodeExportState`
+ */
+async function fetchTranspilerList(agentName: string, signal: AbortSignal): Promise<Array<Transpiler>> {
+    const response = await fetch(createTranspiledCodeApiPath(agentName), {
+        method: 'GET',
+        signal,
+    });
+
+    if (!response.ok) {
+        throw new Error(await resolveTranspiledCodeApiErrorMessage(response, 'Failed to load transpilers'));
+    }
+
+    const payload = (await response.json()) as TranspilerListResponse;
+    return payload.transpilers || [];
+}
+
+/**
+ * Generates the transpiled code for one agent and transpiler.
+ *
+ * @param agentName - Routed agent name.
+ * @param transpilerName - Selected transpiler identifier.
+ * @param signal - Abort signal cancelling the request when the effect is disposed.
+ * @returns Generated harness code.
+ *
+ * @private function of `useAgentCodeExportState`
+ */
+async function fetchTranspiledCode(agentName: string, transpilerName: string, signal: AbortSignal): Promise<string> {
+    const response = await fetch(createTranspiledCodeApiPath(agentName), {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ transpilerName }),
+        signal,
+    });
+
+    if (!response.ok) {
+        throw new Error(await resolveTranspiledCodeApiErrorMessage(response, 'Failed to transpile code'));
+    }
+
+    const result = (await response.json()) as TranspilationResult;
+    return result.code;
+}
+
+/**
+ * Downloads the ZIP export for one agent and transpiler.
+ *
+ * @param agentName - Routed agent name.
+ * @param transpilerName - Selected transpiler identifier.
+ * @returns Download blob and its resolved filename.
+ *
+ * @private function of `useAgentCodeExportState`
+ */
+async function fetchTranspiledCodeDownload(
+    agentName: string,
+    transpilerName: string,
+): Promise<{ readonly blob: Blob; readonly filename: string }> {
+    const response = await fetch(createTranspiledCodeDownloadApiPath(agentName, transpilerName), {
+        method: 'GET',
+    });
+
+    if (!response.ok) {
+        throw new Error(await resolveTranspiledCodeApiErrorMessage(response, 'Failed to download ZIP export'));
+    }
+
+    const filename =
+        parseFilenameFromContentDisposition(response.headers.get('Content-Disposition')) ||
+        'promptbook-agent-export.zip';
+    const blob = await response.blob();
+
+    return { blob, filename };
+}
+
+/**
+ * Loads the agent profile for the export header, returning `null` when unavailable.
+ *
+ * @param agentName - Routed agent name.
+ * @param signal - Abort signal cancelling the request when the effect is disposed.
+ * @returns Loaded agent profile, or `null` when the profile endpoint responds with an error status.
+ *
+ * @private function of `useAgentCodeExportState`
+ */
+async function fetchAgentProfile(agentName: string, signal: AbortSignal): Promise<AgentBasicInformation | null> {
+    const response = await fetch(`/agents/${encodeURIComponent(agentName)}/api/profile`, {
+        method: 'GET',
+        signal,
+    });
+
+    if (!response.ok) {
+        return null;
+    }
+
+    return (await response.json()) as AgentBasicInformation;
+}
+
+/**
+ * Extracts a user-facing message from an unknown caught value.
+ *
+ * @param error - Unknown caught value.
+ * @param fallbackMessage - Message used when the caught value is not an `Error`.
+ * @returns Human-readable error message.
+ *
+ * @private function of `useAgentCodeExportState`
+ */
+function getErrorMessage(error: unknown, fallbackMessage: string): string {
+    return error instanceof Error ? error.message : fallbackMessage;
+}

package/apps/agents-server/src/app/api/admin/chat-tasks/[taskId]/terminal/route.ts

@@ -0,0 +1,52 @@
+import { NextResponse } from 'next/server';
+import { createInteractiveTerminalEventStream } from '@/src/utils/createInteractiveTerminalEventStream';
+import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
+import { resolveAdminTaskTerminalSession } from '@/src/utils/taskTerminal/resolveAdminTaskTerminalSession';
+
+/**
+ * Forces fresh terminal snapshots and live streams for every request.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Reads or live-streams the read-only CLI terminal of one background task.
+ *
+ * Restricted to the super-admin because raw task console output can contain
+ * internal infrastructure details that regular administrators must not see.
+ *
+ * Query parameters:
+ * - `stream=1` — switches from a JSON snapshot to a Server-Sent-Events live stream
+ */
+export async function GET(request: Request, { params }: { params: Promise<{ taskId: string }> }) {
+    if (!(await isUserGlobalAdmin())) {
+        return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+    }
+
+    const { taskId: rawTaskId } = await params;
+    const taskId = decodeURIComponent(rawTaskId);
+
+    try {
+        const terminalResolution = await resolveAdminTaskTerminalSession(taskId);
+        if (!terminalResolution) {
+            return NextResponse.json({ error: 'Task not found.' }, { status: 404 });
+        }
+
+        const { searchParams } = new URL(request.url);
+        if (searchParams.get('stream') === '1') {
+            return createInteractiveTerminalEventStream(
+                request,
+                taskId,
+                terminalResolution.session,
+                terminalResolution.subscribe,
+            );
+        }
+
+        return NextResponse.json({ session: terminalResolution.session });
+    } catch (error) {
+        console.error('[admin-chat-task] terminal failed', { taskId, error });
+        return NextResponse.json(
+            { error: error instanceof Error ? error.message : 'Failed to load the task terminal.' },
+            { status: 500 },
+        );
+    }
+}

package/apps/agents-server/src/app/api/admin/{code-runners → harness-auth}/authentication/route.ts

@@ -1,34 +1,34 @@
 import {
-    getCodeRunnerAuthenticationSession,
-    getLatestCodeRunnerAuthenticationSession,
-    startCodeRunnerAuthenticationSession,
-    stopCodeRunnerAuthenticationSession,
-    subscribeToCodeRunnerAuthenticationSession,
-    writeCodeRunnerAuthenticationSessionInput,
-} from '@/src/utils/codeRunnerAuthentication';
+    getHarnessAuthenticationSession,
+    getLatestHarnessAuthenticationSession,
+    startHarnessAuthenticationSession,
+    stopHarnessAuthenticationSession,
+    subscribeToHarnessAuthenticationSession,
+    writeHarnessAuthenticationSessionInput,
+} from '@/src/utils/harnessAuthentication';
 import { createAdminTerminalRouteHandlers } from '@/src/utils/createAdminTerminalRouteHandlers';
-import { readConfiguredCodeRunner } from '@/src/utils/codeRunnerConfiguration';
+import { readConfiguredHarness } from '@/src/utils/harnessConfiguration';
 
 export const runtime = 'nodejs';
 export const dynamic = 'force-dynamic';
 
 /**
- * Shared route handlers for the code-runner authentication terminal.
+ * Shared route handlers for the harness authentication terminal.
  */
 const authenticationTerminalRouteHandlers = createAdminTerminalRouteHandlers(
     {
         async getLatestSession() {
-            const { agent } = await readConfiguredCodeRunner();
-            return getLatestCodeRunnerAuthenticationSession(agent);
+            const { harness } = await readConfiguredHarness();
+            return getLatestHarnessAuthenticationSession(harness);
         },
-        getSession: getCodeRunnerAuthenticationSession,
+        getSession: getHarnessAuthenticationSession,
         async startSession() {
-            const { agent } = await readConfiguredCodeRunner();
-            return startCodeRunnerAuthenticationSession(agent);
+            const { harness } = await readConfiguredHarness();
+            return startHarnessAuthenticationSession(harness);
         },
-        writeSessionInput: writeCodeRunnerAuthenticationSessionInput,
-        stopSession: stopCodeRunnerAuthenticationSession,
-        subscribeToSession: subscribeToCodeRunnerAuthenticationSession,
+        writeSessionInput: writeHarnessAuthenticationSessionInput,
+        stopSession: stopHarnessAuthenticationSession,
+        subscribeToSession: subscribeToHarnessAuthenticationSession,
     },
     {
         loadErrorMessage: 'Failed to load the authentication session.',

package/apps/agents-server/src/app/api/admin/{code-runners → harness-auth}/route.ts

@@ -1,13 +1,13 @@
 import { NextResponse } from 'next/server';
 import { isUserGlobalAdmin } from '@/src/utils/isUserGlobalAdmin';
-import { readConfiguredCodeRunner, resolveCodeRunnerStatus } from '@/src/utils/codeRunnerConfiguration';
+import { readConfiguredHarness, resolveHarnessStatus } from '@/src/utils/harnessConfiguration';
 import {
-    applyVpsCodeRunnerConfiguration,
+    applyVpsHarnessConfiguration,
     updateVpsEnvironmentVariables,
 } from '@/src/utils/vpsConfiguration';
 
 /**
- * Loads configured code-runner settings from the editable VPS environment.
+ * Loads configured harness settings from the editable VPS environment.
  */
 export async function GET() {
     if (!(await isUserGlobalAdmin())) {
@@ -15,22 +15,22 @@ export async function GET() {
     }
 
     try {
-        const configuredCodeRunner = await readConfiguredCodeRunner();
+        const configuredHarness = await readConfiguredHarness();
 
         return NextResponse.json({
-            ...configuredCodeRunner,
-            status: await resolveCodeRunnerStatus(configuredCodeRunner.agent),
+            ...configuredHarness,
+            status: await resolveHarnessStatus(configuredHarness.harness),
         });
     } catch (error) {
         return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to load code-runner configuration.' },
+            { error: error instanceof Error ? error.message : 'Failed to load harness configuration.' },
             { status: 500 },
         );
     }
 }
 
 /**
- * Updates code-runner environment variables.
+ * Updates harness environment variables.
  */
 export async function PATCH(request: Request) {
     if (!(await isUserGlobalAdmin())) {
@@ -40,7 +40,7 @@ export async function PATCH(request: Request) {
     try {
         const body = (await request.json().catch(() => null)) as
             | {
-                  readonly agent?: string;
+                  readonly harness?: string;
                   readonly model?: string;
                   readonly thinkingLevel?: string;
                   readonly applyRuntimeConfiguration?: boolean;
@@ -48,11 +48,11 @@ export async function PATCH(request: Request) {
             | null;
 
         if (!body) {
-            return NextResponse.json({ error: 'Code-runner payload is required.' }, { status: 400 });
+            return NextResponse.json({ error: 'Harness payload is required.' }, { status: 400 });
         }
 
         await updateVpsEnvironmentVariables({
-            PTBK_HARNESS: body.agent || '',
+            PTBK_HARNESS: body.harness || '',
             PTBK_MODEL: body.model || '',
             PTBK_THINKING_LEVEL: body.thinkingLevel || '',
         });
@@ -62,11 +62,11 @@ export async function PATCH(request: Request) {
 
         return NextResponse.json({
             ...payload,
-            applyResult: body.applyRuntimeConfiguration ? await applyVpsCodeRunnerConfiguration() : null,
+            applyResult: body.applyRuntimeConfiguration ? await applyVpsHarnessConfiguration() : null,
         });
     } catch (error) {
         return NextResponse.json(
-            { error: error instanceof Error ? error.message : 'Failed to update code-runner configuration.' },
+            { error: error instanceof Error ? error.message : 'Failed to update harness configuration.' },
             { status: 500 },
         );
     }