synthos 0.10.0 → 0.11.0

package/src/service/useApiRoutes.ts

@@ -1,6 +1,7 @@
 import path from "path";
+import * as fs from "fs/promises";
 import AdmZip from "adm-zip";
-import { listPages, loadPageMetadata, PageMetadata, savePageMetadata, deletePage, copyPage, savePageState, clearVersions, PAGE_VERSION } from "../pages";
+import { listPages, loadPageMetadata, PageMetadata, savePageMetadata, deletePage, copyPage, savePageState, clearChanges, PAGE_VERSION } from "../pages";
 import { checkIfExists, findFileInFolders, listFiles, listFolders, loadFile } from "../files";
 import {getModelEntry, loadSettings, saveSettings, ServicesConfig } from "../settings";
 import { Application } from 'express';
@@ -8,7 +9,7 @@ import express from 'express';
 import { SynthOSConfig } from "../init";
 import { createCompletePrompt, PROVIDERS } from "./createCompletePrompt";
 import { generateDefaultImage, generateImage } from "./generateImage";
-import { chainOfThought } from "../models";
+import { createMediaCache } from "./mediaCache";
 import { requiresSettings } from "./requiresSettings";
 import { executeScript } from "../scripts";
 import { listThemes, loadTheme, loadThemeInfo, loadThemeVersion } from "../themes";
@@ -35,6 +36,25 @@ interface ServiceDefinition {
     exclusive?: string;
 }
 
+/**
+ * Greeting text applied to any page upgraded by `/api/pages/:name/upgrade`
+ * when the page does not already carry a user-authored greeting. Shown as the
+ * first assistant message when the migrated page loads.
+ */
+const MIGRATED_PAGE_GREETING =
+    "This page was just migrated to v3. If anything looks off or stopped working, let me know what you see and I'll help fix it.";
+
+const BRAINSTORM_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['response', 'prompt', 'suggestions'],
+    properties: {
+        response: { type: 'string' },
+        prompt: { type: 'string' },
+        suggestions: { type: 'array', items: { type: 'string' } },
+    },
+} as const;
+
 const SERVICE_REGISTRY: ServiceDefinition[] = [
     {
         id: 'brave-search',
@@ -50,6 +70,10 @@ const SERVICE_REGISTRY: ServiceDefinition[] = [
 
 export function useApiRoutes(config: SynthOSConfig, app: Application, customizer?: Customizer): void {
     const sp = config.storageProvider;
+    const mediaCache = createMediaCache({
+        storage: sp,
+        cacheRoot: path.join(config.pagesFolder, 'cache'),
+    });
 
     // List pages
     app.get('/api/pages', async (req, res) => {
@@ -130,6 +154,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
             const existingMeta = await loadPageMetadata(config, finalName);
             const metadata: PageMetadata = {
                 title: existingMeta?.title ?? '',
+                description: existingMeta?.description ?? '',
                 categories: existingMeta?.categories ?? [],
                 pinned: existingMeta?.pinned ?? false,
                 showInAll: existingMeta?.showInAll ?? true,
@@ -137,6 +162,8 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
                 lastModified: now,
                 pageVersion: existingMeta?.pageVersion ?? PAGE_VERSION,
                 mode: existingMeta?.mode ?? 'unlocked',
+                greeting: existingMeta?.greeting ?? '',
+                firstRunGreeting: existingMeta?.firstRunGreeting ?? '',
             };
             await savePageMetadata(config, finalName, metadata);
 
@@ -157,6 +184,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
             } else {
                 const defaults: PageMetadata = {
                     title: '',
+                    description: '',
                     categories: [],
                     pinned: false,
                     showInAll: true,
@@ -164,6 +192,8 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
                     lastModified: '',
                     pageVersion: 0,
                     mode: 'unlocked',
+                    greeting: '',
+                    firstRunGreeting: '',
                 };
                 res.json(defaults);
             }
@@ -184,6 +214,10 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
                 res.status(400).json({ error: 'title must be a string' });
                 return;
             }
+            if ('description' in body && typeof body.description !== 'string') {
+                res.status(400).json({ error: 'description must be a string' });
+                return;
+            }
             if ('categories' in body && !Array.isArray(body.categories)) {
                 res.status(400).json({ error: 'categories must be an array' });
                 return;
@@ -205,6 +239,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
             const existing = await loadPageMetadata(config, name, config.requiredPagesFolders);
             const metadata: PageMetadata = {
                 title: existing?.title ?? '',
+                description: existing?.description ?? '',
                 categories: existing?.categories ?? [],
                 pinned: existing?.pinned ?? false,
                 showInAll: existing?.showInAll ?? true,
@@ -212,10 +247,13 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
                 lastModified: existing?.lastModified ?? '',
                 pageVersion: existing?.pageVersion ?? 0,
                 mode: existing?.mode ?? 'unlocked',
+                greeting: existing?.greeting ?? '',
+                firstRunGreeting: existing?.firstRunGreeting ?? '',
             };
 
             // Overlay provided fields
             if ('title' in body) metadata.title = body.title;
+            if ('description' in body) metadata.description = body.description;
             if ('categories' in body) metadata.categories = body.categories;
             if ('pinned' in body) metadata.pinned = body.pinned;
             if ('showInAll' in body) metadata.showInAll = body.showInAll;
@@ -266,6 +304,7 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
             if (!metadata) {
                 metadata = {
                     title: '',
+                    description: '',
                     categories: [],
                     pinned: false,
                     showInAll: true,
@@ -273,6 +312,8 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
                     lastModified: '',
                     pageVersion: 0,
                     mode: 'unlocked',
+                    greeting: '',
+                    firstRunGreeting: '',
                 };
             }
 
@@ -473,10 +514,46 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
             const { prompt, shape, style } = req.body;
             const builder = getModelEntry(settings, 'builder');
             const { configuration, imageQuality, provider } = builder;
-            const response = provider === 'OpenAI' ?
-                await generateImage({ apiKey: configuration.apiKey, prompt, shape, quality: imageQuality, style }) :
-                await generateDefaultImage();
+
+            // Only cache OpenAI image generations
+            if (provider !== 'OpenAI') {
+                const response = await generateDefaultImage();
+                if (response.completed) {
+                    res.json(response.value);
+                } else {
+                    res.status(500).send(response.error?.message);
+                }
+                return;
+            }
+
+            const cacheEnabled = settings.cache?.enabled !== false;
+            const noCache = req.headers['x-no-cache'] === 'true' || req.query.nocache === '1';
+            const cacheKey = `image:v1:${prompt}:${shape}:${imageQuality}:${style}`;
+
+            // Check cache
+            if (cacheEnabled && !noCache) {
+                const cached = await mediaCache.get('images', cacheKey);
+                if (cached.hit) {
+                    const base64 = cached.buffer.toString('base64');
+                    res.json({ url: `data:${cached.contentType};base64,${base64}` });
+                    return;
+                }
+            }
+
+            // Generate fresh
+            const response = await generateImage({ apiKey: configuration.apiKey, prompt, shape, quality: imageQuality, style });
             if (response.completed) {
+                // Cache the result
+                if (cacheEnabled) {
+                    const dataUrl = response.value!.url;
+                    const base64Data = dataUrl.split(',')[1];
+                    if (base64Data) {
+                        const buffer = Buffer.from(base64Data, 'base64');
+                        await mediaCache.put('images', cacheKey, buffer, 'image/png', {
+                            prompt, shape, quality: imageQuality, style,
+                        });
+                    }
+                }
                 res.json(response.value);
             } else {
                 res.status(500).send(response.error?.message);
@@ -484,18 +561,57 @@ export function useApiRoutes(config: SynthOSConfig, app: Application, customizer
         });
     });
 
-    // Define a route to generate a completion using chain-of-thought
+    // Define a route to generate a completion. When `schema` is provided, the model
+    // is constrained to emit JSON conforming to it (Anthropic output_config /
+    // OpenAI json_schema) and the parsed object is returned directly. Otherwise a
+    // plain text completion is returned as { answer: string }.
     app.post('/api/generate/completion', async (req, res) => {
-        await requiresSettings(res, config, async (settings) => {
-            const { prompt, temperature } = req.body;
+        await requiresSettings(res, config, async () => {
+            const { prompt, temperature, schema } = req.body;
+            if (typeof prompt !== 'string' || !prompt.trim()) {
+                res.status(400).json({ error: 'prompt is required' });
+                return;
+            }
+            if (schema !== undefined && (typeof schema !== 'object' || schema === null || Array.isArray(schema))) {
+                res.status(400).json({ error: 'schema must be a JSON schema object' });
+                return;
+            }
             const completePrompt = await createCompletePrompt(config, 'chat', req.body.model);
-            const response = await chainOfThought({ question: prompt, temperature, completePrompt });
-            if (response.completed) {
-                res.json(response.value ?? {});
-            } else {
-                console.error(response.error);
-                res.status(500).send(response.error?.message);
+            const userMessage: { role: 'user'; content: string } = { role: 'user', content: prompt };
+            const result = await completePrompt({
+                prompt: userMessage,
+                temperature,
+                ...(schema ? { outputSchema: schema, jsonSchema: schema } : {}),
+            });
+            if (!result.completed) {
+                console.error(result.error);
+                res.status(500).send(result.error?.message);
+                return;
+            }
+            const text = typeof result.value === 'string' ? result.value : '';
+            if (schema) {
+                let parsed: unknown;
+                if (typeof result.value === 'object' && result.value !== null) {
+                    parsed = result.value;
+                } else {
+                    let candidate = text.replace(/^```(?:json)?\s*/i, '').replace(/\s*```\s*$/, '').trim();
+                    const start = candidate.indexOf('{');
+                    const end = candidate.lastIndexOf('}');
+                    if (start !== -1 && end > start) {
+                        candidate = candidate.substring(start, end + 1);
+                    }
+                    try {
+                        parsed = JSON.parse(candidate);
+                    } catch {
+                        console.error('completion: schema-mode response was not parseable JSON:', text);
+                        res.status(502).json({ error: 'Model did not return JSON conforming to schema', raw: text });
+                        return;
+                    }
+                }
+                res.json(parsed);
+                return;
             }
+            res.json({ answer: text });
         });
     });
 
@@ -526,16 +642,10 @@ If you see a conversation between ${productName} and the User. Asses what they'r
 
 ${productName} exposes table storage and chat completion api's that every page can use. If the user wants to store something or use AI, your prompt should suggest using table storage or make llm calls.
 
-You MUST return your response as a JSON object with exactly these fields:
-{
-  "response": "Your conversational reply — explanations, options, suggestions. Markdown OK.",
-  "prompt": "A clean, actionable instruction ready to paste into ${productName} chat to build what was discussed. Update this each exchange to reflect the latest brainstorm state.",
-  "suggestions": ["Short clickable option A", "Short clickable option B", "Short clickable option C"]
-}
-
-suggestions — 2-4 short phrases the user can click to continue the conversation. These are next-step options: directions to explore, questions to answer, or choices to make. Keep each under 60 characters. Always provide suggestions.
-
-Return ONLY the JSON object.`};
+Field guidance:
+- response — Your conversational reply: explanations, options, suggestions. Markdown OK.
+- prompt — A clean, actionable instruction ready to paste into ${productName} chat to build what was discussed. Update this each exchange to reflect the latest brainstorm state. Empty string is fine before the user has a clear direction.
+- suggestions — 2-4 short phrases (under 60 characters each) the user can click to continue the conversation. Always provide suggestions.`};
 
             // Format multi-turn conversation into a single prompt
             const formatted = (messages as { role: string; content: string }[]).map(m =>
@@ -544,15 +654,35 @@ Return ONLY the JSON object.`};
 
             const prompt: { role: 'user'; content: string } = { role: 'user', content: formatted };
 
-            const result = await completePrompt({ prompt, system, jsonMode: true });
+            const result = await completePrompt({
+                prompt,
+                system,
+                outputSchema: BRAINSTORM_SCHEMA,
+                jsonSchema: BRAINSTORM_SCHEMA,
+            });
             if (result.completed) {
-                let response = result.value || '';
+                let response = '';
                 let brainstormPrompt = '';
                 let suggestions: string[] = [];
-                // jsonMode returns an already-parsed object from agentm-core
-                const parsed = (typeof result.value === 'object' && result.value !== null)
-                    ? result.value as Record<string, unknown>
-                    : (() => { try { return JSON.parse(result.value as string); } catch { return null; } })();
+                let parsed: Record<string, unknown> | null = null;
+                if (typeof result.value === 'object' && result.value !== null) {
+                    parsed = result.value as Record<string, unknown>;
+                } else if (typeof result.value === 'string') {
+                    let candidate = result.value
+                        .replace(/^```(?:json)?\s*/i, '')
+                        .replace(/\s*```\s*$/, '')
+                        .trim();
+                    const start = candidate.indexOf('{');
+                    const end = candidate.lastIndexOf('}');
+                    if (start !== -1 && end > start) {
+                        candidate = candidate.substring(start, end + 1);
+                    }
+                    try {
+                        parsed = JSON.parse(candidate) as Record<string, unknown>;
+                    } catch {
+                        console.error('brainstorm: response was not parseable JSON:', result.value);
+                    }
+                }
                 if (parsed) {
                     if (typeof parsed.response === 'string') response = parsed.response;
                     if (typeof parsed.prompt === 'string') brainstormPrompt = parsed.prompt;
@@ -883,12 +1013,20 @@ Return ONLY the JSON object.`};
                 await sp.copyFolderRecursive(folderPath, path.join(migratedFolder, name));
             }
 
-            // Clear stale version files (undo snapshots from the old page version)
-            await clearVersions(config, name);
+            // Clear stale change files (undo snapshots from the old page version)
+            await clearChanges(config, name);
 
             // Update metadata
             metadata.pageVersion = PAGE_VERSION;
             metadata.lastModified = new Date().toISOString();
+
+            // Assign a generic greeting so the shell shows a helpful first
+            // message explaining this page was auto-migrated. Only set if the
+            // page does not already have a user-authored greeting.
+            if (!metadata.greeting || metadata.greeting.trim().length === 0) {
+                metadata.greeting = MIGRATED_PAGE_GREETING;
+            }
+
             await savePageMetadata(config, name, metadata);
 
             res.json({ upgraded: true, fromVersion: currentVersion, toVersion: PAGE_VERSION });
@@ -987,4 +1125,116 @@ Return ONLY the JSON object.`};
             }
         });
     });
+
+    // -----------------------------------------------------------------------
+    // Cache management routes
+    // -----------------------------------------------------------------------
+
+    app.get('/api/cache/stats', async (_req, res) => {
+        try {
+            const cacheStats = await mediaCache.stats();
+            res.json(cacheStats);
+        } catch (err: unknown) {
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    app.delete('/api/cache/images', async (_req, res) => {
+        try {
+            await mediaCache.clearCategory('images');
+            res.json({ cleared: 'images' });
+        } catch (err: unknown) {
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    app.delete('/api/cache/audio', async (_req, res) => {
+        try {
+            await mediaCache.clearCategory('audio');
+            res.json({ cleared: 'audio' });
+        } catch (err: unknown) {
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    app.delete('/api/cache', async (_req, res) => {
+        try {
+            await mediaCache.clearAll();
+            res.json({ cleared: 'all' });
+        } catch (err: unknown) {
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // Serve a saved starter screenshot (page.light.png / page.dark.png) from
+    // the top-level starters/<name>/ folder so the carousel can display them.
+    app.get('/api/starters/:name/screenshot/:variant', async (req, res) => {
+        try {
+            const { name, variant } = req.params;
+            if (variant !== 'light' && variant !== 'dark') {
+                res.status(400).json({ error: 'variant must be "light" or "dark"' });
+                return;
+            }
+            if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+                res.status(400).json({ error: 'invalid starter name' });
+                return;
+            }
+            const target = path.join(process.cwd(), 'starters', name, `page.${variant}.png`);
+            try {
+                await fs.access(target);
+            } catch {
+                res.status(404).json({ error: 'screenshot not found' });
+                return;
+            }
+            res.sendFile(target, { headers: { 'Cache-Control': 'public, max-age=300' } });
+        } catch (err: unknown) {
+            console.error(err);
+            res.status(500).json({ error: (err as Error).message });
+        }
+    });
+
+    // Save a captured screenshot for a starter page into the top-level
+    // starters/<name>/ folder so the image lives alongside the snapshot.
+    app.post(
+        '/api/starters/:name/screenshot/:variant',
+        express.raw({ type: 'image/png', limit: '20mb' }),
+        async (req, res) => {
+            try {
+                const { name, variant } = req.params;
+
+                if (variant !== 'light' && variant !== 'dark') {
+                    res.status(400).json({ error: 'variant must be "light" or "dark"' });
+                    return;
+                }
+
+                if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+                    res.status(400).json({ error: 'invalid starter name' });
+                    return;
+                }
+
+                const png = req.body as Buffer;
+                if (!png || png.length === 0) {
+                    res.status(400).json({ error: 'empty image body' });
+                    return;
+                }
+                // PNG signature: 89 50 4E 47 0D 0A 1A 0A
+                if (png.length < 8 ||
+                    png[0] !== 0x89 || png[1] !== 0x50 || png[2] !== 0x4E || png[3] !== 0x47) {
+                    res.status(400).json({ error: 'body is not a PNG' });
+                    return;
+                }
+
+                const targetFolder = path.join(process.cwd(), 'starters', name);
+                await fs.mkdir(targetFolder, { recursive: true });
+
+                const target = path.join(targetFolder, `page.${variant}.png`);
+                await fs.writeFile(target, png);
+
+                res.json({ ok: true, paths: [target], bytes: png.length });
+            } catch (err: unknown) {
+                console.error(err);
+                res.status(500).json({ error: (err as Error).message });
+            }
+        }
+    );
 }