synthos 0.7.2 → 0.8.0

package/src/models/openai.ts

@@ -0,0 +1,90 @@
+import OpenAI from 'openai';
+import { AgentCompletion, completePrompt, PromptCompletionArgs, RequestError } from './types';
+
+export interface OpenaiArgs {
+    apiKey: string;
+    model: string;
+    baseURL?: string;
+    organization?: string;
+    project?: string;
+    temperature?: number;
+}
+
+/**
+ * Build the input messages and text format config for an OpenAI Responses API request.
+ * Pure function — no SDK dependency.
+ */
+export function buildOpenAIRequest(args: PromptCompletionArgs): {
+    input: { role: string; content: string }[];
+    text?: { format: any };
+} {
+    const input: { role: string; content: string }[] = [];
+    if (args.history) {
+        for (const msg of args.history) {
+            input.push({ role: msg.role, content: msg.content });
+        }
+    }
+    input.push({ role: 'user', content: args.prompt.content });
+
+    if (args.jsonMode || args.jsonSchema) {
+        const inputText = input.map(m => m.content).join(' ');
+        if (!/json/i.test(inputText)) {
+            const last = input[input.length - 1];
+            if (last) {
+                last.content += '\nReturn JSON.';
+            }
+        }
+    }
+
+    let text: { format: any } | undefined;
+    if (args.jsonSchema) {
+        text = {
+            format: {
+                type: 'json_schema',
+                name: 'response',
+                strict: true,
+                schema: args.jsonSchema,
+            },
+        };
+    } else if (args.jsonMode) {
+        text = {
+            format: { type: 'json_object' },
+        };
+    }
+
+    return { input, text };
+}
+
+export function openai(args: OpenaiArgs): completePrompt {
+    const { apiKey, model, baseURL, organization, project } = args;
+
+    const client = new OpenAI({ apiKey, baseURL, organization, project });
+
+    return async (completionArgs: PromptCompletionArgs): Promise<AgentCompletion<string>> => {
+        const { input, text } = buildOpenAIRequest(completionArgs);
+
+        try {
+            const response = await client.responses.create({
+                model,
+                instructions: completionArgs.system?.content,
+                input: input as OpenAI.Responses.ResponseInputItem[],
+                ...(text ? { text } : {}),
+            });
+
+            const output = response.output_text;
+            if (output === undefined || output === null) {
+                return { completed: false, error: new Error('No response output returned') };
+            }
+
+            return { completed: true, value: output };
+        } catch (err: unknown) {
+            let error: Error;
+            if (err instanceof OpenAI.APIError && (err as any).status !== undefined) {
+                error = new RequestError(err.message, (err as any).status, err.name ?? 'APIError');
+            } else {
+                error = err as Error;
+            }
+            return { completed: false, error };
+        }
+    };
+}

package/src/models/providers.ts

@@ -3,7 +3,7 @@ import { Provider, ProviderName } from './types';
 export const AnthropicProvider: Provider = {
     name: 'Anthropic',
     builderModels: ['claude-opus-4-6', 'claude-sonnet-4-5'],
-    chatModels: ['claude-haiku-4-5', 'claude-sonnet-4-5'],
+    chatModels: ['claude-sonnet-4-5','claude-haiku-4-5'],
     detectModel(model: string): boolean {
         return model.startsWith('claude-');
     }
@@ -14,11 +14,20 @@ export const OpenAIProvider: Provider = {
     builderModels: ['gpt-5.2', 'gpt-5.2-codex'],
     chatModels: ['gpt-5-nano', 'gpt-5-mini', 'gpt-4.1'],
     detectModel(model: string): boolean {
-        return model.startsWith('gpt-') || model.startsWith('GPT-');
+        return model.startsWith('gpt-');
     }
 };
 
-export const PROVIDERS: Provider[] = [AnthropicProvider, OpenAIProvider];
+export const FireworksAIProvider: Provider = {
+    name: 'FireworksAI',
+    builderModels: ['fireworks-glm-5'],
+    chatModels: ['fireworks-minimax-m2p5', 'fireworks-kimi-k2p5', 'fireworks-glm-5'],
+    detectModel(model: string): boolean {
+        return model.startsWith('fireworks-');
+    }
+};
+
+export const PROVIDERS: Provider[] = [AnthropicProvider, OpenAIProvider, FireworksAIProvider];
 
 export function getProvider(name: ProviderName): Provider {
     const provider = PROVIDERS.find(p => p.name === name);

package/src/models/types.ts

@@ -1,9 +1,12 @@
-export type ProviderName = 'Anthropic' | 'OpenAI';
+// ---------------------------------------------------------------------------
+// Provider types
+// ---------------------------------------------------------------------------
+
+export type ProviderName = 'Anthropic' | 'OpenAI' | 'FireworksAI';
 
 export interface ProviderConfig {
     apiKey: string;
     model: string;
-    maxTokens: number;
 }
 
 export interface ModelEntry {
@@ -21,3 +24,65 @@ export interface Provider {
     chatModels: string[];
     detectModel(model: string): boolean;
 }
+
+// ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+
+export interface Message {
+    role: string;
+    content: string;
+    name?: string;
+}
+
+export interface SystemMessage extends Message {
+    role: 'system';
+}
+
+export interface UserMessage extends Message {
+    role: 'user';
+}
+
+// ---------------------------------------------------------------------------
+// Completions
+// ---------------------------------------------------------------------------
+
+export interface AgentCompletion<TValue> {
+    completed: boolean;
+    value?: TValue;
+    error?: Error;
+}
+
+export interface PromptCompletionArgs {
+    prompt: UserMessage;
+    system?: SystemMessage;
+    history?: Message[];
+    temperature?: number;
+    jsonMode?: boolean;
+    /** JSON schema for structured output. When provided, the model is asked to return JSON conforming to this schema. */
+    jsonSchema?: Record<string, unknown>;
+}
+
+export type completePrompt<TValue = string> = (args: PromptCompletionArgs) => Promise<AgentCompletion<TValue>>;
+
+// ---------------------------------------------------------------------------
+// Agent args
+// ---------------------------------------------------------------------------
+
+export interface AgentArgs {
+    completePrompt: completePrompt<any>;
+}
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class RequestError extends Error {
+    readonly status: number;
+
+    constructor(message: string, status: number, name?: string) {
+        super(message);
+        this.status = status;
+        this.name = name ?? 'RequestError';
+    }
+}

package/src/models/utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Convert any value to a string suitable for template substitution.
+ * Replaces double quotes and line feeds with spaces.
+ */
+export function variableToString(variable: any): string {
+    if (variable === null || variable === undefined) {
+        return '';
+    }
+    if (typeof variable === 'string') {
+        return variable;
+    }
+    if (typeof variable === 'object') {
+        return JSON.stringify(variable);
+    }
+    return variable.toString();
+}

package/src/scripts.ts

@@ -1,4 +1,4 @@
-import { AgentCompletion, variableToString } from 'agentm-core';
+import { AgentCompletion, variableToString } from './models';
 import { spawn } from 'child_process';
 import path from 'path';
 import { loadFile, listFiles, checkIfExists } from './files';
@@ -122,7 +122,7 @@ function spawnProcess(command: string, args: string[]): Promise<ExecuteScriptRes
     });
 }
 
-function composeArguments(template: string, variables: Record<string, any>): string {
+export function composeArguments(template: string, variables: Record<string, any>): string {
     return template.replace(/{{\s*([^}\s]+)\s*}}/g, (match, name) => {
         // Convert the variable to a string and replace double quotes and line feeds with spaces
         return variableToString(variables[name]);

package/src/service/createCompletePrompt.ts

@@ -1,4 +1,4 @@
-import {anthropic, completePrompt, logCompletePrompt, openai} from 'agentm-core';
+import { anthropic, completePrompt, fireworksai, logCompletePrompt, openai } from '../models';
 import { getModelEntry, loadSettings } from '../settings';
 import { PROVIDERS } from '../models';
 
@@ -22,6 +22,8 @@ export async function createCompletePrompt(pagesFolder: string, use: 'builder' |
     const apiKey = entry.configuration.apiKey;
     if (entry.provider === 'Anthropic') {
         modelInstance = anthropic({apiKey, model});
+    } else if (entry.provider === 'FireworksAI') {
+        modelInstance = fireworksai({apiKey, model});
     } else {
         modelInstance = openai({apiKey, model});
     }

package/src/service/generateImage.ts

@@ -1,5 +1,5 @@
 import OpenAI from "openai";
-import { AgentCompletion, RequestError } from "agentm-core";
+import { AgentCompletion, RequestError } from "../models";
 import { loadFile } from "../files";
 import path from "path";
 
@@ -81,7 +81,7 @@ export async function generateImage(args: OpenaiGenerateImageArgs): Promise<Agen
             style
         });
     
-        if (response.data.length > 0 && response.data[0].b64_json !== undefined) {
+        if (response.data && response.data.length > 0 && response.data[0].b64_json !== undefined) {
             const url = `data:image/png;base64,${response.data[0].b64_json}`
             return { completed: true, value: { url } };
         } else {

package/src/service/server.ts

@@ -4,6 +4,7 @@ import { useApiRoutes } from './useApiRoutes';
 import { SynthOSConfig } from '../init';
 import { useDataRoutes } from './useDataRoutes';
 import { useConnectorRoutes } from './useConnectorRoutes';
+import { useAgentRoutes } from './useAgentRoutes';
 import { cyan, yellow, formatTime } from './debugLog';
 
 export function server(config: SynthOSConfig): Application {
@@ -36,6 +37,9 @@ export function server(config: SynthOSConfig): Application {
     // Connector routes
     useConnectorRoutes(config, app);
 
+    // Agent routes
+    useAgentRoutes(config, app);
+
     // Data routes
     useDataRoutes(config, app);
 

package/src/service/transformPage.ts

@@ -1,8 +1,9 @@
-import { AgentArgs, AgentCompletion, SystemMessage, UserMessage } from "agentm-core";
+import { AgentArgs, AgentCompletion, SystemMessage, UserMessage } from "../models";
 import { listScripts } from "../scripts";
 import * as cheerio from "cheerio";
 import { ThemeInfo } from "../themes";
 import { CONNECTOR_REGISTRY, ConnectorsConfig, ConnectorOAuthConfig } from "../connectors";
+import { AgentConfig } from "../agents";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -12,7 +13,6 @@ export interface TransformPageArgs extends AgentArgs {
     pagesFolder: string;
     pageState: string;
     message: string;
-    maxTokens: number;
     instructions?: string;
     /** Provider-specific formatting instructions injected into the prompt. */
     modelInstructions?: string;
@@ -22,6 +22,8 @@ export interface TransformPageArgs extends AgentArgs {
     mode?: 'unlocked' | 'locked';
     /** User's configured connectors (from settings). */
     configuredConnectors?: ConnectorsConfig;
+    /** User's configured A2A agents (from settings). */
+    configuredAgents?: AgentConfig[];
 }
 
 export type ChangeOp =
@@ -53,7 +55,7 @@ export interface TransformPageResult {
 }
 
 export async function transformPage(args: TransformPageArgs): Promise<AgentCompletion<TransformPageResult>> {
-    const { pagesFolder, pageState, message, maxTokens, completePrompt } = args;
+    const { pagesFolder, pageState, message, completePrompt } = args;
 
     // 1. Assign data-node-id to every element
     const { html: annotatedHtml } = assignNodeIds(pageState);
@@ -71,7 +73,7 @@ export async function transformPage(args: TransformPageArgs): Promise<AgentCompl
             const colorList = Object.entries(colors)
                 .map(([name, value]) => `  --${name}: ${value}`)
                 .join('\n');
-            themeBlock += `Mode: ${mode}\nCSS custom properties (use instead of hardcoded values):\n${colorList}\n\nShared shell classes (pre-styled by theme, do not redefine):\n  .chat-panel — Left sidebar container (30% width)\n  .chat-header — Chat panel title bar\n  .chat-messages — Scrollable message container\n  .chat-message — Individual message wrapper\n  .link-group — Navigation links row (Save, Pages, Reset)\n  .chat-input — Message text input\n  .chat-submit — Send button\n  .viewer-panel — Right content area (70% width)\n  .loading-overlay — Full-screen loading overlay\n  .spinner — Animated loading spinner\n\nPage title bars: To align with the chat header, apply these styles:\n  min-height: var(--header-min-height);\n  padding: var(--header-padding-vertical) var(--header-padding-horizontal);\n  line-height: var(--header-line-height);\n  display: flex; align-items: center; justify-content: center; box-sizing: border-box;\n\nFull-viewer mode: For games, animations, or full-screen content, add class "full-viewer" to the viewer-panel element to remove its padding.\n\nChat panel behaviours (auto-injected via page script — do NOT recreate in page code):\n  The server injects page-v2.js after transformation. It provides:\n  - Form submit handler: sets action to window.location.pathname, shows #loadingOverlay, disables inputs\n  - Save/Reset link handlers (#saveLink, #resetLink)\n  - Chat scroll to bottom (#chatMessages)\n  - Chat toggle button (.chat-toggle) — created dynamically if not in markup\n  - .chat-input-wrapper — wraps #chatInput with a brainstorm icon button\n  - Brainstorm modal (#brainstormModal) — LLM-powered brainstorm UI, created dynamically\n  - Focus management — keeps keyboard input directed to #chatInput\n\n  Do NOT:\n  - Create your own form submit handler, toggle button, or input wrapper\n  - Modify or replace .chat-panel, .chat-header, .link-group, #chatForm, or .chat-toggle\n  - INSERT new <script> blocks that duplicate existing ones — when fixing JavaScript, UPDATE or REPLACE the existing script's nodeId instead. Always give inline scripts a unique id attribute.\n  - Set the form action attribute (page-v2.js sets it dynamically)\n  - Include these CSS rules (in the theme): #loadingOverlay position, .chat-submit:disabled, .chat-input:disabled\n\n  To add chat messages: use insert with parentId of #chatMessages and position "append".\n  #chatMessages is the only unlocked element inside .chat-panel.\n\nThe <html> element has class "${mode}-mode". Always add .light-mode CSS overrides for any page-specific styles so the page works in both light and dark themes, unless the user has explicitly requested a very specific color scheme.`;
+            themeBlock += `Mode: ${mode}\nCSS custom properties (use instead of hardcoded values):\n${colorList}\n\nShared shell classes (pre-styled by theme, do not redefine):\n  .chat-panel — Left sidebar container (30% width)\n  .chat-header — Chat panel title bar\n  .chat-messages — Scrollable message container\n  .chat-message — Individual message wrapper\n  .link-group — Navigation links row (Save, Pages, Reset)\n  .chat-input — Message text input\n  .chat-submit — Send button\n  .viewer-panel — Right content area (70% width)\n  .loading-overlay — Full-screen loading overlay\n  .spinner — Animated loading spinner\n  .modal-overlay — Full-screen modal backdrop (position:fixed, z-index:2000, backdrop-filter:blur). Add class "show" to display.\n  .modal-content — Centered modal container\n  .modal-header — Gradient header bar\n  .modal-body — Modal content area\n  .modal-footer — Bottom action bar (flex, space-between)\n  .modal-footer-right — Right-aligned button group\n\nModals and popups: ALWAYS use the theme\'s .modal-overlay class for any modal or popup overlay. Do NOT create custom overlay classes with position:fixed and z-index. Structure:\n  <div class="modal-overlay" id="myModal">\n    <div class="modal-content">\n      <div class="modal-header">Title</div>\n      <div class="modal-body">Content</div>\n      <div class="modal-footer"><div class="modal-footer-right"><button>OK</button></div></div>\n    </div>\n  </div>\nShow/hide by toggling the "show" class: el.classList.add(\'show\') / el.classList.remove(\'show\'). This ensures correct z-index layering above the chat toggle and other UI elements.\n\nPage title bars: To align with the chat header, apply these styles:\n  min-height: var(--header-min-height);\n  padding: var(--header-padding-vertical) var(--header-padding-horizontal);\n  line-height: var(--header-line-height);\n  display: flex; align-items: center; justify-content: center; box-sizing: border-box;\n\nFull-viewer mode: For games, animations, or full-screen content, add class "full-viewer" to the viewer-panel element to remove its padding.\n\nChat panel behaviours (auto-injected via page script — do NOT recreate in page code):\n  The server injects page-v2.js after transformation. It provides:\n  - Form submit handler: sets action to window.location.pathname, shows #loadingOverlay, disables inputs\n  - Save/Reset link handlers (#saveLink, #resetLink)\n  - Chat scroll to bottom (#chatMessages)\n  - Chat toggle button (.chat-toggle) — created dynamically if not in markup\n  - .chat-input-wrapper — wraps #chatInput with a brainstorm icon button\n  - Brainstorm modal (#brainstormModal) — LLM-powered brainstorm UI, created dynamically\n  - Focus management — keeps keyboard input directed to #chatInput\n\n  Do NOT:\n  - Create your own form submit handler, toggle button, or input wrapper\n  - Modify or replace .chat-panel, .chat-header, .link-group, #chatForm, or .chat-toggle\n  - INSERT new <script> blocks that duplicate existing ones — when fixing JavaScript, UPDATE or REPLACE the existing script's nodeId instead. Always give inline scripts a unique id attribute.\n  - Set the form action attribute (page-v2.js sets it dynamically)\n  - Include these CSS rules (in the theme): #loadingOverlay position, .chat-submit:disabled, .chat-input:disabled\n\n  To add chat messages: use insert with parentId of #chatMessages and position "append".\n  #chatMessages is the only unlocked element inside .chat-panel.\n\nThe <html> element has class "${mode}-mode". Always add .light-mode CSS overrides for any page-specific styles so the page works in both light and dark themes, unless the user has explicitly requested a very specific color scheme.`;
         }
 
         // Build configured-connectors block
@@ -103,7 +105,26 @@ export async function transformPage(args: TransformPageArgs): Promise<AgentCompl
             }
         }
 
-        const systemMessage = [currentPage, serverAPIs, serverScripts, connectorsBlock, themeBlock, messageFormat].filter(s => s).join('\n\n');
+        // Build configured-agents block (only enabled agents)
+        let agentsBlock = '';
+        const enabledAgents = (args.configuredAgents ?? []).filter(a => a.enabled);
+        if (enabledAgents.length > 0) {
+            const agentBlocks = enabledAgents.map(a => {
+                let block = `- ${a.name} (id: "${a.id}", provider: ${a.provider})`;
+                block += `\n  Description: ${a.description}`;
+                if (a.capabilities?.streaming) {
+                    block += `\n  Supports streaming: yes`;
+                }
+                if (a.skills && a.skills.length > 0) {
+                    const skillList = a.skills.map(s => `    - ${s.name}: ${s.description}`).join('\n');
+                    block += `\n  Skills:\n${skillList}`;
+                }
+                return block;
+            });
+            agentsBlock = `<CONFIGURED_AGENTS>\nThe user has configured these agents:\n\n${agentBlocks.join('\n\n')}\n\n${AGENT_API_REFERENCE}`;
+        }
+
+        const systemMessage = [currentPage, serverAPIs, serverScripts, connectorsBlock, agentsBlock, themeBlock, messageFormat].filter(s => s).join('\n\n');
         const system: SystemMessage = {
             role: 'system',
             content: systemMessage
@@ -118,7 +139,7 @@ export async function transformPage(args: TransformPageArgs): Promise<AgentCompl
         };
 
         // 3. Call model
-        const result = await completePrompt({ prompt, system, maxTokens });
+        const result = await completePrompt({ prompt, system });
         if (!result.completed) {
             return { completed: false, error: result.error };
         }
@@ -153,8 +174,7 @@ export async function transformPage(args: TransformPageArgs): Promise<AgentCompl
                     content: repairUSER_MESSAGE
                 };
 
-                const repairMaxTokens = Math.min(maxTokens, 4096);
-                const repairResult = await completePrompt({ prompt: repairPrompt, system: repairSystem, maxTokens: repairMaxTokens });
+                const repairResult = await completePrompt({ prompt: repairPrompt, system: repairSystem });
 
                 if (repairResult.completed) {
                     const repairChanges = parseChangeList(repairResult.value);
@@ -650,6 +670,40 @@ Return ONLY the JSON array. Example:
   { "op": "insert", "parentId": "3", "position": "append", "html": "<div class=\\"msg\\">New message</div>" }
 ]`;
 
+const AGENT_API_REFERENCE =
+`## Agent API
+
+Check availability first (required):
+  const agents = await synthos.agents.list({ enabled: true });
+
+Send a message (returns full response):
+  const result = await synthos.agents.send(agentId, message);
+  // result: { kind: 'message', text: 'response text', raw: {...} }
+
+Send with file/image attachments:
+  const result = await synthos.agents.send(agentId, message, [
+    { fileName: 'photo.jpg', mimeType: 'image/jpeg', content: '<base64-string>' }
+  ]);
+
+Stream a response (token-by-token deltas):
+  const handle = synthos.agents.sendStream(agentId, message, function(event) {
+    switch (event.kind) {
+      case 'text':   // event.data = text delta string — append to output
+      case 'status': // event.data = status info object
+      case 'done':   // stream complete — stop processing
+      case 'error':  // event.data = error message string
+    }
+  });
+  handle.close(); // call to abort the stream early
+
+Stream with attachments:
+  synthos.agents.sendStream(agentId, message, onEvent, [
+    { fileName: 'doc.pdf', mimeType: 'application/pdf', content: '<base64>' }
+  ]);
+
+IMPORTANT: Always check synthos.agents.list({ enabled: true }) before calling an agent.
+If no agents are configured, show the user a link to Settings > Agents (/settings?tab=agents).`;
+
 const serverAPIs =
 `<SERVER_APIS>
 GET /api/data/:page/:table
@@ -708,6 +762,20 @@ description: Search the web using Brave Search (must be enabled in Settings > Co
 request: { query: string, count?: number, country?: string, freshness?: string }
 response: { results: [{ title: string, url: string, description: string }] }
 
+GET /api/agents
+description: List configured agents (A2A and OpenClaw). Supports ?enabled=true and ?provider=a2a|openclaw filters.
+response: [{ id: string, name: string, description: string, url: string, enabled: boolean, provider: 'a2a'|'openclaw', capabilities?: object }]
+
+POST /api/agents/:id/send
+description: Send a text message to an agent (works for both A2A and OpenClaw protocols) and receive a normalized response
+request: { message: string, attachments?: [{ fileName: string, mimeType: string, content: string }] }
+response: { kind: 'message'|'task', text?: string, raw: object }
+
+POST /api/agents/:id/stream
+description: Send a message and receive a streaming SSE response (text/event-stream). Each event is JSON: { kind: 'text'|'status'|'artifact'|'done'|'error', data: any }
+request: { message: string, attachments?: [{ fileName: string, mimeType: string, content: string }] }
+response: SSE stream
+
 GET /api/connectors
 description: List available connectors (REST API proxies). Supports ?category=X and ?id=X filters.
 response: [{ id: string, name: string, category: string, configured: boolean }]
@@ -736,6 +804,11 @@ PAGE HELPERS (available globally as window.synthos):
   synthos.search.web(query, opts?)      — POST /api/search/web  (opts: { count?, country?, freshness? })
   synthos.connectors.call(connector, method, path, opts?) — POST /api/connectors  (proxy call; opts: { headers?, body?, query? })
   synthos.connectors.list(opts?)        — GET /api/connectors  (opts: { category?, id? })
+  synthos.agents.list(opts?)             — GET /api/agents  (returns configured agents; opts: { enabled?, provider? }; returns [{ id, name, description, url, enabled, provider, capabilities }])
+  synthos.agents.send(agentId, message, attachments?) — POST /api/agents/:id/send  (sends a text message to any agent, returns normalized { kind, text, raw }; attachments: [{ fileName, mimeType, content }])
+  synthos.agents.sendStream(agentId, message, onEvent, attachments?) — POST /api/agents/:id/stream  (SSE streaming; onEvent receives { kind, data }; returns { close() } handle; attachments: [{ fileName, mimeType, content }])
+  synthos.agents.isEnabled(agentId)     — checks if an agent is enabled (returns Promise<boolean>)
+  synthos.agents.getCapabilities(agentId) — returns agent capabilities object (streaming, skills, etc.)
 All methods return Promises. Prefer these helpers over raw fetch().`;
 
 const repairUSER_MESSAGE =