openkbs 0.0.36 → 0.0.38

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "openkbs",
-  "version": "0.0.36",
+  "version": "0.0.38",
   "description": "OpenKBS - Command Line Interface",
   "main": "src/index.js",
   "scripts": {
     "build": "pkg .",
-    "deploy": "npm run build && npm run deploy:linux && npm run deploy:macos && npm run deploy:win",
+    "deploy": "npm run build && npm run deploy:linux && npm run deploy:macos && npm run deploy:win && npm run deploy:templates",
     "deploy:linux": "aws s3 cp build/openkbs-linux-x64 s3://openkbs-downloads/cli/linux/openkbs && aws s3 cp build/openkbs-linux-arm64 s3://openkbs-downloads/cli/linux/openkbs-arm64",
     "deploy:macos": "aws s3 cp build/openkbs-macos-arm64 s3://openkbs-downloads/cli/macos/openkbs && aws s3 cp build/openkbs-macos-x64 s3://openkbs-downloads/cli/macos/openkbs-x64",
     "deploy:win": "aws s3 cp build/openkbs-win-x64.exe s3://openkbs-downloads/cli/windows/openkbs.exe && aws s3 cp build/openkbs-win-arm64.exe s3://openkbs-downloads/cli/windows/openkbs-arm64.exe",

package/scripts/deploy-templates.js

@@ -1,41 +1,21 @@
 #!/usr/bin/env node
 
-const fs = require('fs-extra');
+const { execSync } = require('child_process');
 const path = require('path');
-const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
 
-const s3Client = new S3Client({ region: 'us-east-1' });
 const BUCKET = 'openkbs-downloads';
 const TEMPLATES_DIR = path.join(__dirname, '../templates');
 
-async function uploadDirectory(localPath, s3Prefix) {
-    const items = await fs.readdir(localPath, { withFileTypes: true });
-    
-    for (const item of items) {
-        const itemPath = path.join(localPath, item.name);
-        const s3Key = `${s3Prefix}/${item.name}`;
-        
-        if (item.isDirectory()) {
-            await uploadDirectory(itemPath, s3Key);
-        } else {
-            const fileContent = await fs.readFile(itemPath);
-            await s3Client.send(new PutObjectCommand({
-                Bucket: BUCKET,
-                Key: s3Key,
-                Body: fileContent
-            }));
-            console.log(`Uploaded: ${s3Key}`);
-        }
-    }
-}
-
 async function deployTemplates() {
     try {
-        console.log('Deploying templates to S3...');
-        await uploadDirectory(TEMPLATES_DIR, 'templates');
-        console.log('Templates deployed successfully!');
+        console.log('Syncing templates to S3...');
+        
+        const syncCommand = `aws s3 sync "${TEMPLATES_DIR}" s3://${BUCKET}/templates --delete`;
+        execSync(syncCommand, { stdio: 'inherit' });
+        
+        console.log('Templates synced successfully!');
     } catch (error) {
-        console.error('Error deploying templates:', error);
+        console.error('Error syncing templates:', error);
         process.exit(1);
     }
 }

package/src/actions.js

@@ -542,6 +542,7 @@ async function updateKnowledgeAction() {
     try {
         const knowledgeDir = path.join(process.cwd(), '.openkbs', 'knowledge');
         const metadataPath = path.join(knowledgeDir, 'metadata.json');
+        const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
         
         // Check if .openkbs/knowledge directory exists
         if (!fs.existsSync(knowledgeDir)) {
@@ -593,7 +594,10 @@ async function updateKnowledgeAction() {
         // Download updated knowledge files from S3
         await downloadKnowledgeFromS3(knowledgeDir);
         
-        console.green('Knowledge base updated successfully!');
+        // Download CLAUDE.md file from S3
+        await downloadClaudeMdFromS3(claudeMdPath, s3Client, bucket);
+        
+        console.green('Knowledge base and CLAUDE.md updated successfully!');
         
     } catch (error) {
         console.red('Error updating knowledge base:', error.message);
@@ -651,6 +655,31 @@ async function downloadKnowledgeFromS3(targetDir) {
     }
 }
 
+async function downloadClaudeMdFromS3(claudeMdPath, s3Client, bucket) {
+    const claudeMdKey = 'templates/CLAUDE.md';
+    
+    try {
+        // Download CLAUDE.md file from S3
+        const response = await s3Client.send(new GetObjectCommand({
+            Bucket: bucket,
+            Key: claudeMdKey
+        }));
+        
+        const fileContent = await response.Body.transformToByteArray();
+        await fs.writeFile(claudeMdPath, fileContent);
+        
+        // console.log('Downloaded: CLAUDE.md');
+        
+    } catch (error) {
+        if (error.name === 'NoSuchKey') {
+            console.yellow('CLAUDE.md not found in remote repository, skipping...');
+        } else {
+            console.red('Error downloading CLAUDE.md from S3:', error.message);
+            throw error;
+        }
+    }
+}
+
 module.exports = {
     signAction,
     loginAction,

package/src/utils.js

@@ -1080,7 +1080,6 @@ async function downloadTemplatesFromS3(targetDir) {
         
         const fileContent = await streamToBuffer(response.Body);
         await fs.writeFile(localPath, fileContent);
-        console.log(relativePath);
     });
     
     // Wait for all downloads to complete

package/templates/.openkbs/knowledge/examples/{ai-copywriter → ai-copywriter-agent}/app/instructions.txt

@@ -7,7 +7,7 @@ Job:
 - If you see additional instructions in PROCESS_PRODUCT, execute them.
 - When you have obtained all the necessary information, output JOB_COMPLETED response.
 
-Guidelines:
+Important Guidelines:
 - use webpageToText command to read websites content in details
 - Always output one command per response and wait for the response before continuing
 - If an API call fails, so that you can't extract a required data, retry with different website or search query

package/templates/.openkbs/knowledge/examples/ai-copywriter-agent/app/settings.json

@@ -0,0 +1,6 @@
+{
+  "chatVendor": "anthropic",
+  "kbDescription": "An autonomous AI powerhouse for content generation",
+  "kbTitle": "Copywriter",
+  "model": "claude-3-5-haiku-20241022"
+}

package/templates/.openkbs/knowledge/examples/ai-copywriter-agent/scripts/run_job.js

@@ -0,0 +1,26 @@
+// This boilerplate code is a starting point for development.
+
+const OpenKBSAgentClient = require('./utils/agent_client');
+
+async function main() {
+    const client = new OpenKBSAgentClient();
+    
+    const message = `Today's Date: ${new Date().toLocaleDateString()}
+
+PROCESS_PRODUCT:
+    Product Name: iPhone 14 Pro Max
+    Product Code: MQ9X3RX/A
+    ID: 97649
+    
+    find at least 2 images and 2 videos
+`;
+
+    try {
+        const result = await client.runJob(message);
+        console.log('Job completed:', result);
+    } catch (error) {
+        console.error('Job failed:', error.message);
+    }
+}
+
+main();

package/templates/.openkbs/knowledge/examples/ai-copywriter-agent/scripts/utils/agent_client.js

@@ -0,0 +1,169 @@
+const https = require('https');
+const fs = require('fs');
+const readline = require('readline');
+const path = require('path');
+
+class OpenKBSAgentClient {
+    constructor() {
+        this.settings = this.findSettings();
+        this.secretsPath = this.findSecretsPath();
+        this.apiKey = null;
+    }
+
+    findSettings() {
+        let currentDir = __dirname;
+        
+        while (currentDir !== path.parse(currentDir).root) {
+            const settingsPath = path.join(currentDir, 'app', 'settings.json');
+            if (fs.existsSync(settingsPath)) {
+                return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            }
+            currentDir = path.dirname(currentDir);
+        }
+        
+        throw new Error('Could not find app/settings.json in parent directories');
+    }
+
+    findSecretsPath() {
+        let currentDir = __dirname;
+        
+        while (currentDir !== path.parse(currentDir).root) {
+            const settingsPath = path.join(currentDir, 'app', 'settings.json');
+            if (fs.existsSync(settingsPath)) {
+                const secretsPath = path.join(currentDir, '.openkbs', 'secrets.json');
+                return secretsPath;
+            }
+            currentDir = path.dirname(currentDir);
+        }
+        
+        throw new Error('Could not find agent directory with app/settings.json');
+    }
+
+    async getApiKey() {
+        if (this.apiKey) return this.apiKey;
+        
+        if (fs.existsSync(this.secretsPath)) {
+            const secrets = JSON.parse(fs.readFileSync(this.secretsPath, 'utf8'));
+            this.apiKey = secrets.apiKey;
+            return this.apiKey;
+        }
+        
+        this.apiKey = await this.promptForApiKey();
+        this.saveApiKey(this.apiKey);
+        return this.apiKey;
+    }
+
+    async promptForApiKey() {
+        return new Promise((resolve) => {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout
+            });
+
+            console.log(`Please generate an API key from: https://${this.settings.kbId}.apps.openkbs.com/?tab=access&createAPIKey=api-${+new Date()}`);
+
+            rl.question('Enter your API key: ', (key) => {
+                rl.close();
+                resolve(key);
+            });
+
+            rl._writeToOutput = (str) => rl.output.write(rl.line ? "*" : str);
+        });
+    }
+
+    saveApiKey(key) {
+        const secretsDir = path.dirname(this.secretsPath);
+        if (!fs.existsSync(secretsDir)) {
+            fs.mkdirSync(secretsDir, { recursive: true });
+        }
+        fs.writeFileSync(this.secretsPath, JSON.stringify({ apiKey: key }, null, 2));
+    }
+
+    async runJob(message, options = {}) {
+        const apiKey = await this.getApiKey();
+        
+        if (!this.settings.kbId) {
+            throw new Error('First use: "openkbs push" to create the agent');
+        }
+
+        const chatTitle = options.chatTitle || `Task ${new Date().getTime()}`;
+        const chatId = await this.startJob(chatTitle, message, { kbId: this.settings.kbId, apiKey });
+        
+        console.log(`Job ${chatId} created.\nWorking ...`);
+        
+        if (options.poll !== false) {
+            return this.pollForMessages(chatId, { kbId: this.settings.kbId, apiKey });
+        }
+        
+        return chatId;
+    }
+
+    async startJob(chatTitle, data, app) {
+        const response = await this.makeRequest('https://chat.openkbs.com/', { 
+            ...app, 
+            chatTitle, 
+            message: data 
+        });
+        
+        try {
+            return JSON.parse(response)[0].createdChatId;
+        } catch (error) {
+            if (fs.existsSync(this.secretsPath)) {
+                fs.unlinkSync(this.secretsPath);
+            }
+            throw new Error('Authentication failed.');
+        }
+    }
+
+    makeRequest(url, payload) {
+        return new Promise((resolve, reject) => {
+            const { hostname, pathname } = new URL(url);
+            const req = https.request({
+                hostname, 
+                path: pathname, 
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' }
+            }, res => {
+                let data = '';
+                res.on('data', chunk => data += chunk);
+                res.on('end', () => resolve(data));
+            }).on('error', reject);
+
+            req.write(JSON.stringify(payload));
+            req.end();
+        });
+    }
+
+    async pollForMessages(chatId, app) {
+        const payload = { 
+            ...app, 
+            action: 'getChatMessages', 
+            chatId, 
+            decryptContent: true 
+        };
+        
+        return new Promise((resolve) => {
+            const interval = setInterval(() => {
+                this.makeRequest('https://chat.openkbs.com/', payload)
+                    .then(jsonString => {
+                        const messages = JSON.parse(jsonString)[0].data.messages;
+                        for (const message of messages) {
+                            if (message.role === 'system' && 
+                                /{"type"\s*:\s*"(JOB_COMPLETED|JOB_FAILED)".*?}/s.test(message.content)) {
+                                
+                                const result = JSON.parse(message.content)?.data?.find(item => 
+                                    item.type === 'JOB_COMPLETED' || item.type === 'JOB_FAILED'
+                                );
+                                clearInterval(interval);
+                                resolve(result);
+                                return;
+                            }
+                        }
+                    })
+                    .catch(console.error);
+            }, 1000);
+        });
+    }
+}
+
+module.exports = OpenKBSAgentClient;

package/templates/.openkbs/knowledge/examples/{ai-copywriter → ai-copywriter-agent}/src/Events/actions.js

@@ -32,37 +32,33 @@ export const getActions = () => [
 
 
     [/[\s\S]*"type"\s*:\s*"JOB_FAILED"[\s\S]*/, async (match, event) => {
-        const json = extractJSONFromText(match[0]);
-        if (json && json.type === "JOB_FAILED") {
+        const parsedData = extractJSONFromText(match[0]);
+        if (parsedData && parsedData.type === "JOB_FAILED") {
             await openkbs.chats({
                 action: "updateChat",
-                title: await openkbs.encrypt(json.reason),
+                title: await openkbs.encrypt(parsedData.reason),
                 chatIcon: '🔴',
                 chatId: event?.payload?.chatId
             })
+            return parsedData;
         }
     }],
 
-    [/\/?googleSearch\("(.*?)"(?:,\s*(\d+))?\)/, async (match) => {
+    [/\/?googleSearch\("(.*?)"\)/, async (match) => {
         const q = match[1];
-        const limit = match[2] ? parseInt(match[2]) : 5;
-
         try {
             const response = await openkbs.googleSearch(q, {});
             const data = response?.map(({ title, link, snippet, pagemap }) => ({
                 title, link, snippet, image: pagemap?.metatags?.[0]?.["og:image"]
-            })).slice(0, limit);
-
-            if(!data?.length) return { data: { error: "No results found" } };
+            }));
             return { data };
         } catch (e) {
             return { error: e.message };
         }
     }],
 
-    [/\/?youtubeSearch\("(.*?)"(?:,\s*(\d+))?\)/, async (match) => {
+    [/\/?youtubeSearch\("(.*?)"\)/, async (match) => {
         const q = match[1];
-        const limit = match[2] ? parseInt(match[2]) : 5;
         try {
             const response = await openkbs.googleSearch(q + ' site:youtube.com', { videoOnly: true });
             const data = response?.map(({ title, link, snippet, pagemap }) => ({
@@ -72,19 +68,15 @@ export const getActions = () => [
                 thumbnail: pagemap?.videoobject?.[0]?.thumbnailurl || pagemap?.metatags?.[0]?.["og:image"],
                 duration: pagemap?.videoobject?.[0]?.duration,
                 channel: pagemap?.metatags?.[0]?.["og:site_name"],
-            })).filter(item => item.link.includes('youtu')).slice(0, limit);
-
-            if(!data?.length) return { data: { error: "No YouTube videos found" } };
+            })).filter(item => item.link.includes('youtu'));
             return { data };
         } catch (e) {
             return { error: e.message };
         }
     }],
 
-    [/\/?googleImageSearch\("(.*?)"(?:,\s*(\d+))?\)/, async (match) => {
+    [/\/?googleImageSearch\("(.*?)"\)/, async (match) => {
         const q = match[1];
-        const limit = match[2] ? parseInt(match[2]) : 10;
-
         try {
             const response = await openkbs.googleSearch(q, { searchType: 'image' });
             const data = response?.map(({ title, link, snippet, pagemap }) => {
@@ -96,11 +88,8 @@ export const getActions = () => [
                     snippet,
                     image: thumbnail
                 };
-            })?.slice(0, limit);
-
-            if (!data?.length) return { data: { error: "No image results found" } };
+            });
             return { data };
-
         } catch (e) {
             return { error: e.message };
         }

package/templates/.openkbs/knowledge/examples/{ai-copywriter/src/Events/onResponse.js → ai-copywriter-agent/src/Events/handler.js}

@@ -1,30 +1,26 @@
 import {getActions} from './actions.js';
 
-export const handler = async (event) => {
+export const backendHandler = async (event) => {
     const maxSelfInvokeMessagesCount = 60;
-    const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;
-    
-    // Check if this is a JOB_COMPLETED or JOB_FAILED event
-    const isJobCompleted = /"type"\s*:\s*"JOB_COMPLETED"/.test(lastMessage);
-    const isJobFailed = /"type"\s*:\s*"JOB_FAILED"/.test(lastMessage);
-
+    const lastMessage = event.payload.messages[event.payload.messages.length - 1];
     const actions = getActions();
 
     const matchingActions = actions.reduce((acc, [regex, action]) => {
-        const matches = [...lastMessage.matchAll(new RegExp(regex, 'g'))];
+        const matches = [...lastMessage.content.matchAll(new RegExp(regex, 'g'))];
         matches.forEach(match => {
             acc.push(action(match, event));
         });
         return acc;
     }, []);
 
-    const isJobFinished = isJobCompleted || isJobFailed;
+    // For Coding Agents: avoid unnecessary LLM reactions after job is finished
+    const isJobFinished = /"JOB_COMPLETED"|"JOB_FAILED"/.test(lastMessage.content);
 
     const meta = {
         _meta_actions:
             (
                 event?.payload?.messages?.length > maxSelfInvokeMessagesCount ||
-                isJobFinished && (matchingActions.length === 1 || lastMessage.role === 'system')
+                isJobFinished && lastMessage.role === 'system'
             )
                 ? []
                 : ["REQUEST_CHAT_MODEL"]

package/templates/.openkbs/knowledge/examples/ai-copywriter-agent/src/Events/onRequest.js

@@ -0,0 +1,3 @@
+import {backendHandler} from './handler';
+
+export const handler = async (event) => backendHandler(event)

package/templates/.openkbs/knowledge/examples/ai-copywriter-agent/src/Events/onRequest.json

@@ -0,0 +1,5 @@
+{
+    "dependencies": {
+        "mysql2": "^3.11.4"
+    }
+}

package/templates/.openkbs/knowledge/examples/ai-copywriter-agent/src/Events/onResponse.js

@@ -0,0 +1,3 @@
+import {backendHandler} from './handler';
+
+export const handler = async (event) => backendHandler(event)

package/templates/.openkbs/knowledge/examples/ai-copywriter-agent/src/Events/onResponse.json

@@ -0,0 +1,5 @@
+{
+    "dependencies": {
+        "mysql2": "^3.11.4"
+    }
+}

package/templates/.openkbs/knowledge/examples/ai-copywriter-agent/src/Frontend/contentRender.js

@@ -0,0 +1,64 @@
+import React, { useEffect } from "react";
+import JsonView from '@uiw/react-json-view';
+import { Chip } from '@mui/material';
+
+const extractJSONFromText = (text) => {
+    let braceCount = 0, startIndex = text.indexOf('{');
+    if (startIndex === -1) return null;
+
+    for (let i = startIndex; i < text.length; i++) {
+        if (text[i] === '{') braceCount++;
+        if (text[i] === '}' && --braceCount === 0) {
+            try {
+                return JSON.parse(text.slice(startIndex, i + 1));
+            } catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+
+const parseCommands = (text) => {
+    return text.match(/\/\w+\("([^"]+)"\)/g) || [];
+}
+
+// do NOT useState() directly in this function, it is not a React component
+const onRenderChatMessage = async (params) => {
+    const { content } = params.messages[params.msgIndex];
+    const JSONData = extractJSONFromText(content);
+    const commands = parseCommands(content);
+    
+    if (JSONData?.type === 'JOB_COMPLETED') {
+        return <JsonView value={JSONData} />
+    }
+    
+    if (commands.length > 0) {
+        return commands.map((cmd, i) => (
+            <Chip key={i} label={cmd} size="small" />
+        ));
+    }
+
+    // return undefined to use default message render
+};
+
+const Header = ({ setRenderSettings }) => {
+    useEffect(() => {
+        setRenderSettings({
+            inputLabelsQuickSend: true,
+            disableBalanceView: false,
+            disableSentLabel: false,
+            disableChatAvatar: false,
+            disableChatModelsSelect: false,
+            disableContextItems: false,
+            disableCopyButton: false,
+            disableEmojiButton: false,
+            disableTextToSpeechButton: false,
+            disableMobileLeftButton: false,
+        });
+    }, [setRenderSettings]);
+}
+
+const exports = { onRenderChatMessage, Header };
+window.contentRender = exports;
+export default exports;

package/templates/.openkbs/knowledge/examples/{ai-copywriter → ai-copywriter-agent}/src/Frontend/contentRender.json

@@ -5,6 +5,7 @@
     "@mui/material": "^5.16.1 (fixed)",
     "@mui/icons-material": "^5.16.1 (fixed)",
     "@emotion/react": "^11.10.6 (fixed)",
-    "@emotion/styled": "^11.10.6 (fixed)"
+    "@emotion/styled": "^11.10.6 (fixed)",
+    "@uiw/react-json-view": "^2.0.0-alpha.33"
   }
 }

package/templates/.openkbs/knowledge/metadata.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.0.1"
+  "version": "0.0.8"
 }

package/templates/CLAUDE.md

@@ -1,15 +1,109 @@
 # Claude Code Instructions
 
-## Initial Setup
-1. First, update the knowledge base to ensure you have the latest information:
-   ```bash
-   openkbs update knowledge
-   ```
-
-2. Then read the project contribution guidelines:
-   ```bash
-   # Read the knowledge base README for detailed instructions
-   .openkbs/knowledge/README.md
-   ```
-
-This file contains comprehensive instructions on how to contribute to this OpenKBS project.
+# MANDATORY FIRST STEPS
+**CRITICAL**: Before taking ANY action, implementing ANY feature, planing the implementation or answering ANY question about this project, you must perform the following steps:
+
+**FIRST**: Update the knowledge base:
+```bash
+openkbs update knowledge
+```
+
+**SECOND**: Read every file in the examples folder using the Read tool:
+- First discover all files in the `.openkbs/knowledge/examples/` directory and ALL subdirectories.
+- Then, use the Read tool to examine the content of EACH file individually (skip only icon.png files).
+- You must read ALL files directly
+
+**THIRD**: Read existing agent code using the Read tool:
+- First discover all files in the `./app/`, `./src/`, and `./scripts/` folders.
+- Then, use the Read tool to examine each file individually
+
+# OpenKBS Agent Development Guidelines
+
+## **Critical** Rules (**IMPORTANT**)
+- Never skip reading examples
+- Study the complete working examples to understand OpenKBS patterns
+- Never guess framework methods, settings or variables — always reference the examples.
+
+## Development Guidelines
+- To add npm dependency to backend handlers, add it to onRequest.json and onResponse.json
+- In src/Events and src/Frontend always use Imports (not Require)
+- To add npm dependency to the frontend, add it to contentRender.json
+- Valid values for the _meta_actions key are [] or ["REQUEST_CHAT_MODEL"]
+- Add and use npm dependencies only if necessary, some of those shown in the examples are purely demonstrative
+- If developing new agent, generate it's own ./scripts/run_job.js
+- Before using third-party services in onRequest and onResponse handlers, ask the user for permission
+
+## Architecture Overview
+OpenKBS agents have **two execution environments**:
+
+### 1. Cloud Environment (`./src/`)
+- **Event handlers** (`onRequest.js`, `onResponse.js`) run on OpenKBS cloud platform
+- **Purpose**: Process user messages, execute AI actions, return responses
+- **Deployment**: Code is deployed via `openkbs push`
+
+### 2. Local Environment (`./scripts/`)
+- **User-run scripts** execute locally on user's machine
+- **Purpose**: Call cloud agents via API, orchestrate multi-agent workflows, integrate with external systems
+- **Execution**: Run directly with `node scripts/script-name.js`
+
+### Backend
+The OpenKBS backend framework is for developing AI agents with custom tools, using Node.js.
+It integrates with openkbs chat service via `onRequest` and `onResponse` handlers for custom actions and service integration.
+
+#### Backend Handlers
+The OpenKBS framework's core uses `onRequest` and `onResponse` handlers as middleware for message tool call parsing and execution.
+All these event handlers are executed on-demand (upon API request) by the OpenKBS cloud platform, where user production agents are deployed.
+- **`onResponse` Handler:** Activated after the LLM generates a message, enabling command extraction, and action execution.
+- **`onRequest` Handler:** Triggered on user message to allow the user to execute action
+
+#### NPM Dependencies for onRequest.js or onResponse.js Backend Handlers
+1. If a file imports an NPM dependency and is then imported by onRequest.js or onResponse.js, this dependency must be defined in the handler's corresponding json file
+   Example: If actions.js imports mysql2 and onResponse.js imports actions.js, then mysql2 must be in onResponse.json:
+   {
+   "dependencies": {
+   "mysql2": "^3.14.2"
+   }
+   }
+
+Similarly, we need to create onRequest.json for onRequest.js as each handler have separate Node.js build with separate dependencies
+
+#### Managing Secrets
+To securely manage sensitive information like API keys or database passwords within your backend event handlers (onRequest, onResponse, etc.), use the {{secrets.your_secret_name}} syntax.
+
+#### User-Run Scripts
+**User-run scripts** are located in `./scripts/` folder and communicate with cloud agents via API calls.
+
+**Key Components:**
+- `scripts/run_job.js` - Main job runner for calling the cloud agent
+- `scripts/utils/agent_client.js` - Shared utility using `OpenKBSAgentClient` class
+- Custom workflow scripts for multi-agent orchestration
+
+**Architecture:**
+- Scripts use `OpenKBSAgentClient` to communicate with deployed cloud agents
+- **Path Resolution**: Automatically finds `app/settings.json` and `.openkbs/secrets.json` by walking up directories
+- **Usage**: `const client = new OpenKBSAgentClient(); await client.runJob(message);`
+- **Multi-agent support**: Each agent (base or related) finds its own settings and secrets in its directory structure
+
+#### NPM Dependencies for User-Run Scripts
+Add needed NPM dependencies to `package.json`.
+
+### Frontend Overview
+The OpenKBS frontend framework, built with React and MUI, offers a flexible platform for custom chat interfaces. Developers can customize chat appearance and behavior via the `contentRender` module.
+
+#### contentRender
+The `contentRender.js` file is central to frontend customization, exporting key functions for interface adjustments.
+- **`onRenderChatMessage(params)`:** function called every time a chat message is rendered.
+
+#### OpenKBS commands
+`openkbs push` - deploy the agent to openkbs cloud
+`openkbs create my-agent` - creates a directory structure for a new agent
+
+### Creating Related Agents
+To create related agents that work alongside the main agent:
+
+1. **Create in related-agents/ folder**: `cd related-agents && openkbs create agent-name`
+2. **Each related agent gets**: Own `app/settings.json`, `src/` folder, and `.openkbs/secrets.json`
+3. **Script usage**: Related agents use same `OpenKBSAgentClient` - it automatically finds their settings and secrets
+4. **Multi-agent workflows**: Scripts can orchestrate multiple agents by creating separate client instances
+
+Related agents are independent but can share the base agent's script utilities.

package/templates/app/instructions.txt

@@ -1,10 +1 @@
-You are an AI assistant, assist users with their inquiries and tasks efficiently.
-
-Here are some APIs you can use to assist users:
-
-/googleSearch("query")
-Description: """
-Get results from Google Search API.
-"""
-$InputLabel = """Let me Search in Google!"""
-$InputValue = """Search in google for the latest news"""
+You are an AI assistant, assist users with their inquiries and tasks efficiently.

package/templates/app/settings.json

@@ -1,8 +1,8 @@
 {
-  "chatVendor": "openai",
+  "chatVendor": "anthropic",
   "kbDescription": "{{{openkbsAppName}}}",
   "kbTitle": "{{{openkbsAppName}}}",
-  "model": "gpt-4o",
+  "model": "claude-sonnet-4-20250514",
   "inputTools": [
     "imageToText",
     "speechToText"

package/templates/related-agents/README.md

@@ -0,0 +1,6 @@
+# Related Agents
+
+To add a related agent, use:
+```
+openkbs create "my-agent"
+```

package/templates/scripts/run_job.js

@@ -0,0 +1,26 @@
+// This boilerplate code is a starting point for development.
+
+const OpenKBSAgentClient = require('./utils/agent_client');
+
+async function main() {
+    const client = new OpenKBSAgentClient();
+    
+    const message = `Today's Date: ${new Date().toLocaleDateString()}
+
+PROCESS_PRODUCT:
+    Product Name: iPhone 14 Pro Max
+    Product Code: MQ9X3RX/A
+    ID: 97649
+    
+    find at least 2 images and 2 videos
+`;
+
+    try {
+        const result = await client.runJob(message);
+        console.log('Job completed:', result);
+    } catch (error) {
+        console.error('Job failed:', error.message);
+    }
+}
+
+main();

package/templates/scripts/utils/agent_client.js

@@ -0,0 +1,169 @@
+const https = require('https');
+const fs = require('fs');
+const readline = require('readline');
+const path = require('path');
+
+class OpenKBSAgentClient {
+    constructor() {
+        this.settings = this.findSettings();
+        this.secretsPath = this.findSecretsPath();
+        this.apiKey = null;
+    }
+
+    findSettings() {
+        let currentDir = __dirname;
+        
+        while (currentDir !== path.parse(currentDir).root) {
+            const settingsPath = path.join(currentDir, 'app', 'settings.json');
+            if (fs.existsSync(settingsPath)) {
+                return JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+            }
+            currentDir = path.dirname(currentDir);
+        }
+        
+        throw new Error('Could not find app/settings.json in parent directories');
+    }
+
+    findSecretsPath() {
+        let currentDir = __dirname;
+        
+        while (currentDir !== path.parse(currentDir).root) {
+            const settingsPath = path.join(currentDir, 'app', 'settings.json');
+            if (fs.existsSync(settingsPath)) {
+                const secretsPath = path.join(currentDir, '.openkbs', 'secrets.json');
+                return secretsPath;
+            }
+            currentDir = path.dirname(currentDir);
+        }
+        
+        throw new Error('Could not find agent directory with app/settings.json');
+    }
+
+    async getApiKey() {
+        if (this.apiKey) return this.apiKey;
+        
+        if (fs.existsSync(this.secretsPath)) {
+            const secrets = JSON.parse(fs.readFileSync(this.secretsPath, 'utf8'));
+            this.apiKey = secrets.apiKey;
+            return this.apiKey;
+        }
+        
+        this.apiKey = await this.promptForApiKey();
+        this.saveApiKey(this.apiKey);
+        return this.apiKey;
+    }
+
+    async promptForApiKey() {
+        return new Promise((resolve) => {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout
+            });
+
+            console.log(`Please generate an API key from: https://${this.settings.kbId}.apps.openkbs.com/?tab=access&createAPIKey=api-${+new Date()}`);
+
+            rl.question('Enter your API key: ', (key) => {
+                rl.close();
+                resolve(key);
+            });
+
+            rl._writeToOutput = (str) => rl.output.write(rl.line ? "*" : str);
+        });
+    }
+
+    saveApiKey(key) {
+        const secretsDir = path.dirname(this.secretsPath);
+        if (!fs.existsSync(secretsDir)) {
+            fs.mkdirSync(secretsDir, { recursive: true });
+        }
+        fs.writeFileSync(this.secretsPath, JSON.stringify({ apiKey: key }, null, 2));
+    }
+
+    async runJob(message, options = {}) {
+        const apiKey = await this.getApiKey();
+        
+        if (!this.settings.kbId) {
+            throw new Error('First use: "openkbs push" to create the agent');
+        }
+
+        const chatTitle = options.chatTitle || `Task ${new Date().getTime()}`;
+        const chatId = await this.startJob(chatTitle, message, { kbId: this.settings.kbId, apiKey });
+        
+        console.log(`Job ${chatId} created.\nWorking ...`);
+        
+        if (options.poll !== false) {
+            return this.pollForMessages(chatId, { kbId: this.settings.kbId, apiKey });
+        }
+        
+        return chatId;
+    }
+
+    async startJob(chatTitle, data, app) {
+        const response = await this.makeRequest('https://chat.openkbs.com/', { 
+            ...app, 
+            chatTitle, 
+            message: data 
+        });
+        
+        try {
+            return JSON.parse(response)[0].createdChatId;
+        } catch (error) {
+            if (fs.existsSync(this.secretsPath)) {
+                fs.unlinkSync(this.secretsPath);
+            }
+            throw new Error('Authentication failed.');
+        }
+    }
+
+    makeRequest(url, payload) {
+        return new Promise((resolve, reject) => {
+            const { hostname, pathname } = new URL(url);
+            const req = https.request({
+                hostname, 
+                path: pathname, 
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' }
+            }, res => {
+                let data = '';
+                res.on('data', chunk => data += chunk);
+                res.on('end', () => resolve(data));
+            }).on('error', reject);
+
+            req.write(JSON.stringify(payload));
+            req.end();
+        });
+    }
+
+    async pollForMessages(chatId, app) {
+        const payload = { 
+            ...app, 
+            action: 'getChatMessages', 
+            chatId, 
+            decryptContent: true 
+        };
+        
+        return new Promise((resolve) => {
+            const interval = setInterval(() => {
+                this.makeRequest('https://chat.openkbs.com/', payload)
+                    .then(jsonString => {
+                        const messages = JSON.parse(jsonString)[0].data.messages;
+                        for (const message of messages) {
+                            if (message.role === 'system' && 
+                                /{"type"\s*:\s*"(JOB_COMPLETED|JOB_FAILED)".*?}/s.test(message.content)) {
+                                
+                                const result = JSON.parse(message.content)?.data?.find(item => 
+                                    item.type === 'JOB_COMPLETED' || item.type === 'JOB_FAILED'
+                                );
+                                clearInterval(interval);
+                                resolve(result);
+                                return;
+                            }
+                        }
+                    })
+                    .catch(console.error);
+            }, 1000);
+        });
+    }
+}
+
+module.exports = OpenKBSAgentClient;

package/templates/src/Events/actions.js

@@ -1,18 +1,16 @@
-export const getActions = (meta) => [
-    [/\/?googleSearch\("(.*)"\)/, async (match) => {
+// This boilerplate code is a starting point for development.
+export const getActions = () => [
+    [/\/?googleSearch\("(.*?)"\)/, async (match) => {
         const q = match[1];
         try {
-            const noSecrets = '{{secrets.googlesearch_api_key}}'.includes('secrets.googlesearch_api_key');
-            const params = { q, ...(noSecrets ? {} : { key: '{{secrets.googlesearch_api_key}}', cx: '{{secrets.googlesearch_engine_id}}' }) };
-            const response = noSecrets
-                ? await openkbs.googleSearch(params.q, params)
-                : (await axios.get('https://www.googleapis.com/customsearch/v1', { params }))?.data?.items;
+            const response = await openkbs.googleSearch(q, {});
             const data = response?.map(({ title, link, snippet, pagemap }) => ({
                 title, link, snippet, image: pagemap?.metatags?.[0]?.["og:image"]
             }));
-            return { data, ...meta };
+            return { data };
         } catch (e) {
-            return { error: e.response.data, ...meta };
+            return { error: e.message };
         }
-    }]
+    }],
+    // add more actions here
 ];

package/templates/src/Events/handler.js

@@ -0,0 +1,55 @@
+import {getActions} from './actions.js';
+
+export const backendHandler = async (event) => {
+    const maxSelfInvokeMessagesCount = 60;
+    const lastMessage = event.payload.messages[event.payload.messages.length - 1];
+    const actions = getActions();
+
+    const matchingActions = actions.reduce((acc, [regex, action]) => {
+        const matches = [...lastMessage.content.matchAll(new RegExp(regex, 'g'))];
+        matches.forEach(match => {
+            acc.push(action(match, event));
+        });
+        return acc;
+    }, []);
+
+    // Avoid unnecessary LLM reactions if job is finished
+    const isJobFinished = /"JOB_COMPLETED"|"JOB_FAILED"/.test(lastMessage.content);
+
+    const meta = {
+        _meta_actions:
+            (
+                event?.payload?.messages?.length > maxSelfInvokeMessagesCount ||
+                isJobFinished && lastMessage.role === 'system'
+            )
+                ? []
+                : ["REQUEST_CHAT_MODEL"]
+    }
+
+    if (matchingActions.length > 0) {
+        try {
+            const results = await Promise.all(matchingActions);
+
+            if (results?.[0]?.data?.some?.(o => o?.type === 'image_url')) {
+                return {
+                    ...results[0],
+                    ...meta
+                };
+            }
+
+            return {
+                type: 'RESPONSE',
+                data: results,
+                ...meta
+            };
+        } catch (error) {
+            return {
+                type: 'ERROR',
+                error: error.message,
+                ...meta
+            };
+        }
+    }
+
+    return { type: 'CONTINUE' };
+};

package/templates/src/Events/onRequest.js

@@ -1,14 +1,3 @@
-import {getActions} from './actions.js';
+import {backendHandler} from './handler';
 
-
-export const handler = async (event) => {
-    const actions = getActions({});
-
-    for (let [regex, action] of actions) {
-        const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;        
-        const match = lastMessage?.match(regex);        
-        if (match) return await action(match);            
-    }
-
-    return { type: 'CONTINUE' }
-};
+export const handler = async (event) => backendHandler(event)

package/templates/src/Events/onRequest.json

@@ -0,0 +1,5 @@
+{
+    "dependencies": {
+
+    }
+}

package/templates/src/Events/onResponse.js

@@ -1,13 +1,3 @@
-import {getActions} from './actions.js';
+import {backendHandler} from './handler';
 
-export const handler = async (event) => {
-    const actions = getActions({_meta_actions: ["REQUEST_CHAT_MODEL"]});
-
-    for (let [regex, action] of actions) {
-        const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;        
-        const match = lastMessage?.match(regex);        
-        if (match) return await action(match);            
-    }
-
-    return { type: 'CONTINUE' }
-};
+export const handler = async (event) => backendHandler(event)

package/templates/{.openkbs/knowledge/examples/ai-copywriter/src → src}/Events/onResponse.json

@@ -1,4 +1,5 @@
 {
     "dependencies": {
+
     }
 }

package/templates/.openkbs/knowledge/README.md

@@ -1,34 +0,0 @@
-# OpenKBS Development Guidelines
-
-## Development Flow
-
-1. **Read existing code first:**
-   - `./app/` folder (settings, instructions, etc.)
-   - `./src/` folder (all Events and Frontend files)
-
-2. **Assess implementation requirements:**
-   - **Minor changes only**: Simple modifications to existing code that don't require framework knowledge
-   - **Framework implementation needed**: New features, new event handlers, new frontend components, or placeholder app development
-
-3. **For framework implementation:**
-   - Read all source code in `.openkbs/knowledge/examples/`
-   - Study complete working applications to understand OpenKBS patterns
-   - Never guess framework methods or variables - always reference examples
-
-## When Examples Are Required
-
-- New OpenKBS application development (placeholder app)
-- Adding new event handlers (onRequest, onResponse, etc.)
-- Creating new frontend components
-- Implementing OpenKBS-specific functionality
-- Any framework-related implementation
-
-## When Examples May Not Be Needed
-
-- Simple text changes to existing files
-- Minor bug fixes in existing code
-- Configuration adjustments that don't involve framework methods
-
-## Critical Rule
-
-**When in doubt, read the examples.** They contain all necessary framework knowledge for proper OpenKBS implementation.

package/templates/.openkbs/knowledge/examples/ai-copywriter/app/settings.json

@@ -1,13 +0,0 @@
-{
-  "chatVendor": "anthropic",
-  "kbDescription": "An autonomous AI powerhouse for content generation",
-  "kbTitle": "Copywriter",
-  "model": "claude-3-5-haiku-20241022",
-  "inputTools": [
-    "imageToText"
-  ],
-  "embeddingModel": "none",
-  "embeddingDimension": "none",
-  "searchEngine": "IndexedDB",
-  "itemTypes": {}
-}

package/templates/.openkbs/knowledge/examples/ai-copywriter/run_agent.js

@@ -1,120 +0,0 @@
-const https = require('https');
-const fs = require('fs');
-const readline = require('readline');
-const path = require('path');
-
-const settings = JSON.parse(fs.readFileSync('app/settings.json', 'utf8'));
-const secretsPath = path.join('.openkbs', 'secrets.json');
-let apiKey;
-
-const message = `PROCESS_PRODUCT:
-    Product Name: iPhone 14 Pro Max
-    Product Code: MQ9X3RX/A
-    ID: 97649
-    
-    find at least 2 images and 2 videos
-`;
-
-if (!settings.kbId) {
-    console.log('First use: "openkbs push" To create the agent')
-    return;
-}
-
-// Function to read the API key from secrets.json
-function getApiKey() {
-    if (fs.existsSync(secretsPath)) {
-        const secrets = JSON.parse(fs.readFileSync(secretsPath, 'utf8'));
-        return secrets.apiKey;
-    }
-    return null;
-}
-
-function promptForApiKey() {
-    return new Promise((resolve) => {
-        const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout
-        });
-
-        console.log(`Please generate an API key from: https://${settings.kbId}.apps.openkbs.com/?tab=access&createAPIKey=api-${+new Date()}`);
-
-        rl.question('Enter your API key: ', (key) => {
-            rl.close();
-            resolve(key);
-        });
-
-        rl._writeToOutput = (str) => rl.output.write(rl.line ? "*" : str);
-    });
-}
-
-function saveApiKey(key) {
-    if (!fs.existsSync('.openkbs')) {
-        fs.mkdirSync('.openkbs');
-    }
-    fs.writeFileSync(secretsPath, JSON.stringify({ apiKey: key }, null, 2));
-}
-
-async function main() {
-    apiKey = getApiKey();
-
-    if (!apiKey) {
-        apiKey = await promptForApiKey();
-        console.log('\n')
-        saveApiKey(apiKey);
-    }
-
-    const app = { kbId: settings.kbId, apiKey };
-
-    const chatTitle = "Task " + new Date().getTime();
-    startJob(chatTitle, message, app).then(chatId => {
-        console.log(`Job ${chatId} created.\nWorking ...`);
-        pollForMessages(chatId, app);
-    }).catch(console.error);
-}
-
-function startJob(chatTitle, data, app) {
-    return makeRequest('https://chat.openkbs.com/', { ...app, chatTitle, message: data })
-        .then(res => {
-            try {
-                return JSON.parse(res)[0].createdChatId;
-            } catch (error) {
-                fs.unlinkSync(secretsPath);
-                throw 'Authentication failed.';
-            }
-        });
-}
-
-function makeRequest(url, payload) {
-    return new Promise((resolve, reject) => {
-        const { hostname, pathname } = new URL(url);
-        const req = https.request({
-            hostname, path: pathname, method: 'POST',
-            headers: { 'Content-Type': 'application/json' }
-        }, res => {
-            let data = '';
-            res.on('data', chunk => data += chunk);
-            res.on('end', () => resolve(data));
-        }).on('error', reject);
-
-        req.write(JSON.stringify(payload));
-        req.end();
-    });
-}
-
-function pollForMessages(chatId, app) {
-    const payload = { ...app, action: 'getChatMessages', chatId, decryptContent: true };
-    const interval = setInterval(() => {
-        makeRequest('https://chat.openkbs.com/', payload).then(jsonString => {
-            const messages = JSON.parse(jsonString)[0].data.messages;
-            for (const message of messages) {
-                if (message.role === 'system' && /{"type"\s*:\s*"(JOB_COMPLETED|JOB_FAILED)".*?}/s.test(message.content)) {
-                    console.log(JSON.parse(message.content).data[0]);
-                    clearInterval(interval);
-                    return;
-                }
-            }
-        }).catch(console.error);
-    }, 1000);
-}
-
-main();

package/templates/.openkbs/knowledge/examples/ai-copywriter/src/Frontend/contentRender.js

@@ -1,26 +0,0 @@
-import React, { useEffect } from "react";
-
-const onRenderChatMessage = async (params) => {
-    return;
-};
-
-const Header = ({ setRenderSettings }) => {
-    useEffect(() => {
-        setRenderSettings({
-            inputLabelsQuickSend: true,
-            disableBalanceView: false,
-            disableSentLabel: false,
-            disableChatAvatar: false,
-            disableChatModelsSelect: false,
-            disableContextItems: false,
-            disableCopyButton: false,
-            disableEmojiButton: false,
-            disableTextToSpeechButton: false,
-            disableMobileLeftButton: false,
-        });
-    }, [setRenderSettings]);
-}
-
-const exports = { onRenderChatMessage, Header };
-window.contentRender = exports;
-export default exports;