morpheus-cli 0.4.4 → 0.4.6

package/README.md

@@ -242,6 +242,31 @@ Morpheus features a dedicated middleware system called **Sati** (Mindfulness) th
 -   **Data Privacy**: Stored in a local, independent SQLite database (`santi-memory.db`), ensuring sensitive data is handled securely and reducing context window usage.
 -   **Memory Management**: View and manage your long-term memories through the Web UI or via API endpoints.
 
+### 🪝 Webhooks & Notifications
+
+Morpheus includes a **Webhook System** that lets any external service (GitHub Actions, CI/CD pipelines, monitoring tools, etc.) trigger Oracle and receive the result asynchronously.
+
+**How it works:**
+1. Create a webhook via the Web UI or API — give it a name (slug) and a prompt.
+2. You receive a unique `api_key` for that webhook.
+3. Trigger it from anywhere by posting JSON to `POST /api/webhooks/trigger/<name>` with the `x-api-key` header.
+4. Morpheus runs Oracle with your prompt + the received payload in the background.
+5. The result is saved as a **Notification** and optionally pushed to Telegram.
+
+**Example — trigger from GitHub Actions:**
+```yaml
+- name: Notify Morpheus of deployment
+  run: |
+    curl -s -X POST https://your-morpheus-host/api/webhooks/trigger/deploy-done \
+      -H "x-api-key: ${{ secrets.MORPHEUS_WEBHOOK_KEY }}" \
+      -H "Content-Type: application/json" \
+      -d '{"workflow":"${{ github.workflow }}","status":"success","ref":"${{ github.ref }}"}'
+```
+
+**Security:** Each webhook has its own `api_key` (UUID). The key is sent in the `x-api-key` header — never in the URL — to prevent leakage in server logs. Management endpoints remain protected by `THE_ARCHITECT_PASS`.
+
+**Notification channels:** `ui` (Web UI inbox with unread badge) and/or `telegram` (proactive push message).
+
 ### 📊 Usage Analytics
 Track your token usage across different providers and models directly from the Web UI. View detailed breakdowns of input/output tokens and message counts to monitor costs and activity.
 
@@ -920,6 +945,106 @@ Restart the Morpheus agent.
     }
     ```
 
+### Webhook Endpoints
+
+All management endpoints require `x-architect-pass` authentication. The trigger endpoint is **public** — authenticated only by the per-webhook `x-api-key` header.
+
+#### POST `/api/webhooks/trigger/:webhook_name`
+Trigger a webhook and queue an Oracle agent execution in the background.
+
+*   **Authentication:** `x-api-key: <webhook_api_key>` header (no `x-architect-pass` required).
+*   **Parameters:** `webhook_name` — the slug of the webhook to trigger.
+*   **Body:** Any JSON payload (forwarded to the agent as context).
+*   **Response (202 Accepted):**
+    ```json
+    {
+      "accepted": true,
+      "notification_id": "uuid-..."
+    }
+    ```
+*   **Errors:** `401` for missing/invalid api_key; `404` for webhook not found or disabled.
+
+#### GET `/api/webhooks`
+List all configured webhooks.
+
+*   **Authentication:** `x-architect-pass` header.
+*   **Response:**
+    ```json
+    [
+      {
+        "id": "uuid",
+        "name": "deploy-done",
+        "api_key": "uuid",
+        "prompt": "Analyze the deployment result...",
+        "enabled": true,
+        "notification_channels": ["ui", "telegram"],
+        "created_at": 1700000000000,
+        "last_triggered_at": 1700001000000,
+        "trigger_count": 42
+      }
+    ]
+    ```
+
+#### POST `/api/webhooks`
+Create a new webhook.
+
+*   **Authentication:** `x-architect-pass` header.
+*   **Body:**
+    ```json
+    {
+      "name": "deploy-done",
+      "prompt": "A deployment just finished. Analyze the payload and summarize what happened.",
+      "notification_channels": ["ui", "telegram"],
+      "enabled": true
+    }
+    ```
+*   **Response (201):** The created webhook object including the generated `api_key`.
+
+#### PUT `/api/webhooks/:id`
+Update an existing webhook (prompt, channels, enabled status).
+
+*   **Authentication:** `x-architect-pass` header.
+*   **Note:** The `name` (slug) and `api_key` fields are immutable via this endpoint.
+
+#### DELETE `/api/webhooks/:id`
+Delete a webhook and all its associated notifications.
+
+*   **Authentication:** `x-architect-pass` header.
+
+#### GET `/api/webhooks/notifications`
+List webhook execution notifications.
+
+*   **Authentication:** `x-architect-pass` header.
+*   **Query Parameters:** `unreadOnly=true` to filter unread notifications.
+*   **Response:**
+    ```json
+    [
+      {
+        "id": "uuid",
+        "webhook_id": "uuid",
+        "webhook_name": "deploy-done",
+        "status": "completed",
+        "payload": "{\"ref\":\"main\"}",
+        "result": "Deployment of main to production succeeded...",
+        "read": false,
+        "created_at": 1700001000000,
+        "completed_at": 1700001005000
+      }
+    ]
+    ```
+
+#### POST `/api/webhooks/notifications/read`
+Mark notifications as read.
+
+*   **Authentication:** `x-architect-pass` header.
+*   **Body:** `{ "ids": ["uuid1", "uuid2"] }`
+
+#### GET `/api/webhooks/notifications/unread-count`
+Get the count of unread notifications (used by the sidebar badge).
+
+*   **Authentication:** `x-architect-pass` header.
+*   **Response:** `{ "count": 3 }`
+
 ## Testing
 
 We use **Vitest** for testing.
@@ -957,8 +1082,10 @@ npm run test:watch
 
 - [x] **Web Dashboard**: Local UI for management and logs.
 - [x] **MCP Support**: Full integration with Model Context Protocol.
+- [x] **Webhook System**: External triggers with Oracle execution and multi-channel notifications.
 - [ ] **Discord Adapter**: Support for Discord interactions.
 - [ ] **Plugin System**: Extend functionality via external modules.
+- [ ] **Webhook Retry Logic**: Exponential backoff for failed Oracle executions.
 
 ## 🕵️ Privacy Protection
 

package/dist/channels/telegram.js

@@ -356,6 +356,29 @@ export class TelegramAdapter {
         await fs.writeFile(filePath, buffer);
         return filePath;
     }
+    /**
+     * Sends a proactive message to all allowed Telegram users.
+     * Used by the webhook notification system to push results.
+     */
+    async sendMessage(text) {
+        if (!this.isConnected || !this.bot) {
+            this.display.log('Cannot send message: Telegram bot not connected.', { source: 'Telegram', level: 'warning' });
+            return;
+        }
+        const allowedUsers = this.config.get().channels.telegram.allowedUsers;
+        if (allowedUsers.length === 0) {
+            this.display.log('No allowed Telegram users configured — skipping notification.', { source: 'Telegram', level: 'warning' });
+            return;
+        }
+        for (const userId of allowedUsers) {
+            try {
+                await this.bot.telegram.sendMessage(userId, text, { parse_mode: 'Markdown' });
+            }
+            catch (err) {
+                this.display.log(`Failed to send message to Telegram user ${userId}: ${err.message}`, { source: 'Telegram', level: 'error' });
+            }
+        }
+    }
     async disconnect() {
         if (!this.isConnected || !this.bot) {
             return;

package/dist/cli/commands/start.js

@@ -8,6 +8,7 @@ import { writePid, readPid, isProcessRunning, clearPid, checkStalePid, killProce
 import { ConfigManager } from '../../config/manager.js';
 import { renderBanner } from '../utils/render.js';
 import { TelegramAdapter } from '../../channels/telegram.js';
+import { WebhookDispatcher } from '../../runtime/webhooks/dispatcher.js';
 import { PATHS } from '../../config/paths.js';
 import { Oracle } from '../../runtime/oracle.js';
 import { ProviderError } from '../../runtime/errors.js';
@@ -136,6 +137,8 @@ export const startCommand = new Command('start')
                 const telegram = new TelegramAdapter(oracle);
                 try {
                     await telegram.connect(config.channels.telegram.token, config.channels.telegram.allowedUsers || []);
+                    // Wire Telegram adapter to webhook dispatcher for proactive notifications
+                    WebhookDispatcher.setTelegramAdapter(telegram);
                     adapters.push(telegram);
                 }
                 catch (e) {

package/dist/config/schemas.js

@@ -26,6 +26,9 @@ export const ApocConfigSchema = LLMConfigSchema.extend({
     working_dir: z.string().optional(),
     timeout_ms: z.number().int().positive().optional(),
 });
+export const WebhookConfigSchema = z.object({
+    telegram_notify_all: z.boolean().optional(),
+}).optional();
 // Zod Schema matching MorpheusConfig interface
 export const ConfigSchema = z.object({
     agent: z.object({
@@ -35,6 +38,7 @@ export const ConfigSchema = z.object({
     llm: LLMConfigSchema.default(DEFAULT_CONFIG.llm),
     sati: SatiConfigSchema.optional(),
     apoc: ApocConfigSchema.optional(),
+    webhooks: WebhookConfigSchema,
     audio: AudioConfigSchema.default(DEFAULT_CONFIG.audio),
     memory: z.object({
         limit: z.number().int().positive().optional(),

package/dist/http/middleware/auth.js

@@ -10,7 +10,7 @@ export const authMiddleware = (req, res, next) => {
     // If password is not configured (using default), log a warning
     if (!process.env.THE_ARCHITECT_PASS) {
         const display = DisplayManager.getInstance();
-        display.log('Using default password for dashboard access. For security, set THE_ARCHITECT_PASS environment variable.', { source: 'http', level: 'warning' });
+        // display.log('Using default password for dashboard access. For security, set THE_ARCHITECT_PASS environment variable.', { source: 'http', level: 'warning' });
     }
     const providedPass = req.headers[AUTH_HEADER];
     if (providedPass === architectPass) {

package/dist/http/server.js

@@ -6,7 +6,9 @@ import { fileURLToPath } from 'url';
 import { ConfigManager } from '../config/manager.js';
 import { DisplayManager } from '../runtime/display.js';
 import { createApiRouter } from './api.js';
+import { createWebhooksRouter } from './webhooks-router.js';
 import { authMiddleware } from './middleware/auth.js';
+import { WebhookDispatcher } from '../runtime/webhooks/dispatcher.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export class HttpServer {
@@ -16,6 +18,8 @@ export class HttpServer {
     constructor(oracle) {
         this.app = express();
         this.oracle = oracle;
+        // Wire Oracle into the webhook dispatcher so triggers use the full agent
+        WebhookDispatcher.setOracle(oracle);
         this.setupMiddleware();
         this.setupRoutes();
     }
@@ -45,6 +49,10 @@ export class HttpServer {
                 uptime: process.uptime()
             });
         });
+        // Webhooks router — mounted BEFORE the auth-guarded /api block.
+        // The trigger endpoint is public (validated via x-api-key header internally).
+        // All other webhook management endpoints apply authMiddleware internally.
+        this.app.use('/api/webhooks', createWebhooksRouter());
         this.app.use('/api', authMiddleware, createApiRouter(this.oracle));
         // Serve static frontend from compiled output
         const uiPath = path.resolve(__dirname, '../ui');

package/dist/http/webhooks-router.js

@@ -0,0 +1,181 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import { WebhookRepository } from '../runtime/webhooks/repository.js';
+import { WebhookDispatcher } from '../runtime/webhooks/dispatcher.js';
+import { authMiddleware } from './middleware/auth.js';
+import { DisplayManager } from '../runtime/display.js';
+const CreateWebhookSchema = z.object({
+    name: z
+        .string()
+        .min(1)
+        .max(100)
+        .regex(/^[a-z0-9-_]+$/, 'Name must be a slug: lowercase letters, numbers, hyphens, underscores only'),
+    prompt: z.string().min(1).max(10_000),
+    notification_channels: z.array(z.enum(['ui', 'telegram'])).min(1).default(['ui']),
+});
+const UpdateWebhookSchema = z.object({
+    name: z
+        .string()
+        .min(1)
+        .max(100)
+        .regex(/^[a-z0-9-_]+$/, 'Name must be a slug')
+        .optional(),
+    prompt: z.string().min(1).max(10_000).optional(),
+    enabled: z.boolean().optional(),
+    notification_channels: z.array(z.enum(['ui', 'telegram'])).min(1).optional(),
+});
+const MarkReadSchema = z.object({
+    ids: z.array(z.string().uuid()).min(1),
+});
+export function createWebhooksRouter() {
+    const router = Router();
+    const repo = WebhookRepository.getInstance();
+    const display = DisplayManager.getInstance();
+    const dispatcher = new WebhookDispatcher();
+    // ─────────────────────────────────────────────────────────────────────────────
+    // PUBLIC TRIGGER ENDPOINT — no authMiddleware, api_key validated via header
+    // Must be declared BEFORE router.use(authMiddleware) below
+    // ─────────────────────────────────────────────────────────────────────────────
+    router.post('/trigger/:webhook_name', async (req, res) => {
+        const { webhook_name } = req.params;
+        const apiKey = req.headers['x-api-key'];
+        if (!apiKey || typeof apiKey !== 'string') {
+            return res.status(401).json({ error: 'Missing x-api-key header' });
+        }
+        const webhook = repo.getAndValidateWebhook(webhook_name, apiKey);
+        if (!webhook) {
+            // Intentionally ambiguous — don't reveal whether the name exists or is disabled
+            return res.status(401).json({ error: 'Invalid webhook name or api key' });
+        }
+        const payload = req.body ?? {};
+        // Create pending notification immediately
+        const notification = repo.createNotification({
+            webhook_id: webhook.id,
+            webhook_name: webhook.name,
+            payload: JSON.stringify(payload),
+        });
+        // Increment trigger counter
+        repo.recordTrigger(webhook.id);
+        display.log(`Webhook "${webhook.name}" triggered (notification: ${notification.id})`, { source: 'Webhooks' });
+        // Fire-and-forget — respond immediately with 202
+        setImmediate(() => {
+            dispatcher.dispatch(webhook, payload, notification.id).catch((err) => {
+                display.log(`Unhandled webhook dispatch error for "${webhook.name}": ${err.message}`, { source: 'Webhooks', level: 'error' });
+            });
+        });
+        return res.status(202).json({
+            accepted: true,
+            notification_id: notification.id,
+        });
+    });
+    // ─────────────────────────────────────────────────────────────────────────────
+    // NOTIFICATION ENDPOINTS — declared before /:id to prevent route conflict
+    // (still public here, authMiddleware applied below protects management routes)
+    // ─────────────────────────────────────────────────────────────────────────────
+    router.get('/notifications', authMiddleware, (req, res) => {
+        try {
+            const { webhookId, unreadOnly } = req.query;
+            const notifications = repo.listNotifications({
+                webhookId: typeof webhookId === 'string' ? webhookId : undefined,
+                unreadOnly: unreadOnly === 'true',
+            });
+            res.json(notifications);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.post('/notifications/read', authMiddleware, (req, res) => {
+        const parsed = MarkReadSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return res.status(400).json({ error: 'Invalid payload', details: parsed.error.issues });
+        }
+        try {
+            repo.markNotificationsRead(parsed.data.ids);
+            res.json({ success: true });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    router.get('/notifications/unread-count', authMiddleware, (req, res) => {
+        try {
+            const count = repo.countUnread();
+            res.json({ count });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // ─────────────────────────────────────────────────────────────────────────────
+    // WEBHOOK MANAGEMENT ENDPOINTS — all require authMiddleware
+    // ─────────────────────────────────────────────────────────────────────────────
+    router.use(authMiddleware);
+    // GET /api/webhooks — list all webhooks
+    router.get('/', (req, res) => {
+        try {
+            const webhooks = repo.listWebhooks();
+            res.json(webhooks);
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // POST /api/webhooks — create a webhook
+    router.post('/', (req, res) => {
+        const parsed = CreateWebhookSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return res.status(400).json({ error: 'Invalid payload', details: parsed.error.issues });
+        }
+        try {
+            const webhook = repo.createWebhook(parsed.data);
+            res.status(201).json(webhook);
+        }
+        catch (err) {
+            // SQLite UNIQUE constraint error
+            if (err.message?.includes('UNIQUE constraint failed: webhooks.name')) {
+                return res.status(409).json({ error: `A webhook with name "${parsed.data.name}" already exists` });
+            }
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // GET /api/webhooks/:id — get one webhook
+    router.get('/:id', (req, res) => {
+        const webhook = repo.getWebhookById(req.params.id);
+        if (!webhook)
+            return res.status(404).json({ error: 'Webhook not found' });
+        res.json(webhook);
+    });
+    // PUT /api/webhooks/:id — update a webhook
+    router.put('/:id', (req, res) => {
+        const parsed = UpdateWebhookSchema.safeParse(req.body);
+        if (!parsed.success) {
+            return res.status(400).json({ error: 'Invalid payload', details: parsed.error.issues });
+        }
+        try {
+            const updated = repo.updateWebhook(req.params.id, parsed.data);
+            if (!updated)
+                return res.status(404).json({ error: 'Webhook not found' });
+            res.json(updated);
+        }
+        catch (err) {
+            if (err.message?.includes('UNIQUE constraint failed: webhooks.name')) {
+                return res.status(409).json({ error: `A webhook with that name already exists` });
+            }
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // DELETE /api/webhooks/:id — delete a webhook
+    router.delete('/:id', (req, res) => {
+        try {
+            const deleted = repo.deleteWebhook(req.params.id);
+            if (!deleted)
+                return res.status(404).json({ error: 'Webhook not found' });
+            res.json({ success: true });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    return router;
+}

package/dist/runtime/webhooks/dispatcher.js

@@ -0,0 +1,95 @@
+import { WebhookRepository } from './repository.js';
+import { DisplayManager } from '../display.js';
+export class WebhookDispatcher {
+    static telegramAdapter = null;
+    static oracle = null;
+    display = DisplayManager.getInstance();
+    /**
+     * Called at boot time after TelegramAdapter.connect() succeeds,
+     * so Telegram notifications can be dispatched from any trigger.
+     */
+    static setTelegramAdapter(adapter) {
+        WebhookDispatcher.telegramAdapter = adapter;
+    }
+    /**
+     * Called at boot time with the Oracle instance so webhooks can use
+     * the full Oracle (MCPs, apoc_delegate, memory, etc.).
+     */
+    static setOracle(oracle) {
+        WebhookDispatcher.oracle = oracle;
+    }
+    /**
+     * Main orchestration method — runs in background (fire-and-forget).
+     * 1. Builds the agent prompt from webhook.prompt + payload
+     * 2. Sends to Oracle (which can use MCPs or delegate to Apoc)
+     * 3. Persists result to DB
+     * 4. Dispatches to configured channels
+     */
+    async dispatch(webhook, payload, notificationId) {
+        const repo = WebhookRepository.getInstance();
+        const oracle = WebhookDispatcher.oracle;
+        if (!oracle) {
+            const errMsg = 'Oracle not available — webhook cannot be processed.';
+            this.display.log(errMsg, { source: 'Webhooks', level: 'error' });
+            repo.updateNotificationResult(notificationId, 'failed', errMsg);
+            return;
+        }
+        const message = this.buildPrompt(webhook.prompt, payload);
+        let result;
+        let status;
+        try {
+            result = await oracle.chat(message);
+            status = 'completed';
+            this.display.log(`Webhook "${webhook.name}" completed (notification: ${notificationId})`, { source: 'Webhooks', level: 'success' });
+        }
+        catch (err) {
+            result = `Execution error: ${err.message}`;
+            status = 'failed';
+            this.display.log(`Webhook "${webhook.name}" failed: ${err.message}`, { source: 'Webhooks', level: 'error' });
+        }
+        // Persist result
+        repo.updateNotificationResult(notificationId, status, result);
+        // Dispatch to configured channels
+        for (const channel of webhook.notification_channels) {
+            if (channel === 'telegram') {
+                await this.sendTelegram(webhook.name, result, status);
+            }
+            // 'ui' channel is handled by UI polling — nothing extra needed here
+        }
+    }
+    /**
+     * Combines the user-authored webhook prompt with the received payload.
+     */
+    buildPrompt(webhookPrompt, payload) {
+        const payloadStr = JSON.stringify(payload, null, 2);
+        return `${webhookPrompt}
+
+---
+RECEIVED WEBHOOK PAYLOAD:
+\`\`\`json
+${payloadStr}
+\`\`\`
+
+Analyze the payload above and follow the instructions provided. Be concise and actionable in your response.`;
+    }
+    /**
+     * Sends a formatted Telegram message to all allowed users.
+     * Silently skips if the adapter is not connected.
+     */
+    async sendTelegram(webhookName, result, status) {
+        const adapter = WebhookDispatcher.telegramAdapter;
+        if (!adapter) {
+            this.display.log('Telegram notification skipped — adapter not connected.', { source: 'Webhooks', level: 'warning' });
+            return;
+        }
+        try {
+            const icon = status === 'completed' ? '✅' : '❌';
+            const truncated = result.length > 3500 ? result.slice(0, 3500) + '…' : result;
+            const message = `${icon} *Webhook: ${webhookName}*\n\n${truncated}`;
+            await adapter.sendMessage(message);
+        }
+        catch (err) {
+            this.display.log(`Failed to send Telegram notification for webhook "${webhookName}": ${err.message}`, { source: 'Webhooks', level: 'error' });
+        }
+    }
+}