@hotmeshio/long-tail 0.1.21 → 0.2.0

package/build/services/cron/index.js

@@ -289,16 +289,164 @@ class LTCronRegistry {
             logger_1.loggerRegistry.info(`[lt-cron] restarted YAML cron ${wf.graph_topic} (${wf.cron_schedule})`);
         }
     }
+    // ── Agent schedule crons ──────────────────────────────────────────────
+    /**
+     * Start a single agent schedule cron.
+     */
+    async startAgentCron(agent, schedule, idx) {
+        const key = `agent:${agent.id}-${idx}`;
+        if (this.activeCrons.has(key))
+            return;
+        validateCronSchedule(schedule.cron);
+        const connection = (0, db_1.getConnection)();
+        const topic = `lt.cron.agent.${agent.id}.${idx}`;
+        const cronId = `lt-cron-agent-${agent.id}-${idx}`;
+        const executeAs = schedule.execute_as || agent.user_id || undefined;
+        let principal;
+        if (executeAs) {
+            try {
+                principal = await (0, principal_1.resolvePrincipal)(executeAs);
+            }
+            catch { /* use system */ }
+        }
+        if (!principal) {
+            principal = this.systemPrincipal ?? undefined;
+        }
+        const envelope = {
+            data: schedule.envelope ?? {},
+            metadata: { source: 'agent-cron', agentId: agent.id, agentName: agent.name, certified: true },
+            lt: {
+                userId: principal?.id ?? 'lt-system',
+                principal,
+                scopes: ['workflow:invoke'],
+            },
+        };
+        const isPipeline = schedule.reaction_type === 'pipeline' && schedule.pipeline_id;
+        // Resolve the actual task queue from workflow config (durable only)
+        let taskQueue;
+        if (!isPipeline) {
+            const wfConfig = await configService.getWorkflowConfig(schedule.workflow_type);
+            taskQueue = wfConfig?.task_queue || schedule.workflow_type;
+        }
+        const targetLabel = isPipeline ? `pipeline:${schedule.pipeline_id}` : schedule.workflow_type;
+        await hotmesh_1.Virtual.cron({
+            topic,
+            connection,
+            callback: async () => {
+                try {
+                    if (isPipeline) {
+                        const { invokeYamlWorkflow } = await Promise.resolve().then(() => __importStar(require('../yaml-workflow/invoke')));
+                        const { getYamlWorkflow } = await Promise.resolve().then(() => __importStar(require('../yaml-workflow/db')));
+                        const wf = await getYamlWorkflow(schedule.pipeline_id);
+                        if (!wf)
+                            throw new Error(`Pipeline ${schedule.pipeline_id} not found`);
+                        logger_1.loggerRegistry.info(`[lt-cron] agent invoking pipeline ${schedule.pipeline_id}`);
+                        await invokeYamlWorkflow(wf, {
+                            data: envelope.data ?? {},
+                            execute_as: executeAs,
+                        });
+                    }
+                    else {
+                        const client = new hotmesh_1.Durable.Client({ connection });
+                        const workflowId = `agent-cron-${agent.id}-${idx}-${hotmesh_1.Durable.guid()}`;
+                        logger_1.loggerRegistry.info(`[lt-cron] agent invoking ${schedule.workflow_type} on ${taskQueue} (${workflowId})`);
+                        await client.workflow.start({
+                            args: [envelope],
+                            taskQueue,
+                            workflowName: schedule.workflow_type,
+                            workflowId,
+                            expire: defaults_1.JOB_EXPIRE_SECS,
+                            entity: schedule.workflow_type,
+                            signalIn: false,
+                        });
+                    }
+                }
+                catch (err) {
+                    logger_1.loggerRegistry.error(`[lt-cron] agent ${agent.name}/${targetLabel} failed: ${err?.message}`);
+                }
+            },
+            args: [],
+            options: { id: cronId, interval: schedule.cron },
+        });
+        this.activeCrons.set(key, cronId);
+        logger_1.loggerRegistry.info(`[lt-cron] agent schedule started: ${agent.name}/${targetLabel} (${schedule.cron})`);
+    }
+    /**
+     * Stop all cron schedules for an agent.
+     */
+    async stopAgentCrons(agentId) {
+        const connection = (0, db_1.getConnection)();
+        const toRemove = [];
+        for (const [key, cronId] of this.activeCrons) {
+            if (key.startsWith(`agent:${agentId}-`)) {
+                const idx = key.split('-').pop();
+                const topic = `lt.cron.agent.${agentId}.${idx}`;
+                try {
+                    await hotmesh_1.Virtual.interrupt({ topic, connection, options: { id: cronId } });
+                }
+                catch { /* already stopped */ }
+                toRemove.push(key);
+            }
+        }
+        for (const key of toRemove)
+            this.activeCrons.delete(key);
+        if (toRemove.length) {
+            logger_1.loggerRegistry.info(`[lt-cron] stopped ${toRemove.length} agent schedule(s) for ${agentId}`);
+        }
+    }
+    /**
+     * Restart all cron schedules for an agent (after config change or pause/resume).
+     */
+    async restartAgentCrons(agent) {
+        await this.stopAgentCrons(agent.id);
+        if (agent.status !== 'active')
+            return;
+        const schedules = agent.behaviors?.schedules ?? [];
+        for (let i = 0; i < schedules.length; i++) {
+            const sched = schedules[i];
+            if (sched.cron && (sched.workflow_type || sched.pipeline_id)) {
+                await this.startAgentCron(agent, sched, i);
+            }
+        }
+    }
+    /**
+     * Arm all cron schedules for active agents. Called at startup.
+     */
+    async connectAgentCrons() {
+        const { listAgents } = await Promise.resolve().then(() => __importStar(require('../agent')));
+        const { agents } = await listAgents({ status: 'active', limit: 1000 });
+        let armed = 0;
+        for (const agent of agents) {
+            const schedules = agent.behaviors?.schedules ?? [];
+            for (let i = 0; i < schedules.length; i++) {
+                const sched = schedules[i];
+                if (sched.cron && (sched.workflow_type || sched.pipeline_id)) {
+                    try {
+                        await this.startAgentCron(agent, sched, i);
+                        armed++;
+                    }
+                    catch (err) {
+                        logger_1.loggerRegistry.warn(`[lt-cron] agent schedule failed: ${agent.name}/${sched.cron}: ${err.message}`);
+                    }
+                }
+            }
+        }
+        logger_1.loggerRegistry.info(`[lt-cron] ${armed} agent schedule(s) armed`);
+    }
     /**
      * Stop all active crons. Call during graceful shutdown.
      */
     async disconnect() {
-        for (const workflowType of [...this.activeCrons.keys()]) {
-            if (workflowType.startsWith('yaml:')) {
-                await this.stopYamlCron(workflowType.replace('yaml:', ''));
+        for (const key of [...this.activeCrons.keys()]) {
+            if (key.startsWith('agent:')) {
+                const agentId = key.split(':')[1].split('-')[0];
+                await this.stopAgentCrons(agentId);
+            }
+            else if (key.startsWith('yaml:')) {
+                await this.stopYamlCron(key.replace('yaml:', ''));
             }
             else {
-                await this.stopCron(workflowType);
+                await this.stopCron(key);
             }
         }
         this.connected = false;

package/build/services/insight/index.js

@@ -13,6 +13,7 @@ const db_1 = require("../../lib/db");
 const defaults_1 = require("../../modules/defaults");
 const utils_1 = require("../../modules/utils");
 const llm_1 = require("../llm");
+const principal_1 = require("../iam/principal");
 const prompts_1 = require("./prompts");
 // ── MCP query invocation ─────────────────────────────────────────────────────
 async function startMcpQuery(input) {
@@ -23,11 +24,13 @@ async function startMcpQuery(input) {
     const entity = direct ? 'mcpQuery' : 'mcpQueryRouter';
     const prefix = direct ? 'mcp-query-direct' : 'mcp-query';
     const workflowId = `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    // Resolve the full principal so ToolContext carries identity to tool calls
+    const principal = userId ? await (0, principal_1.resolvePrincipal)(userId) : undefined;
     const handle = await client.workflow.start({
         args: [{
                 data: { prompt, tags, context },
-                metadata: { source: 'dashboard' },
-                lt: { userId },
+                metadata: { source: 'dashboard', certified: true },
+                lt: { userId, principal, scopes: ['workflow:invoke', 'mcp:tool:call'] },
             }],
         taskQueue: 'long-tail-system',
         workflowName: wfName,
@@ -53,11 +56,12 @@ async function startWorkflowBuilder(input) {
     const startTime = Date.now();
     const client = new hotmesh_1.Durable.Client({ connection: (0, db_1.getConnection)() });
     const workflowId = `wf-builder-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const principal = userId ? await (0, principal_1.resolvePrincipal)(userId) : undefined;
     const handle = await client.workflow.start({
         args: [{
                 data: { prompt, tags, feedback, prior_yaml, answers, prior_questions },
-                metadata: { source: 'dashboard' },
-                lt: { userId },
+                metadata: { source: 'dashboard', certified: true },
+                lt: { userId, principal, scopes: ['workflow:invoke', 'mcp:tool:call'] },
             }],
         taskQueue: 'long-tail-system',
         workflowName: 'mcpWorkflowBuilder',
@@ -83,11 +87,12 @@ async function startWorkflowPlanner(input) {
     const startTime = Date.now();
     const client = new hotmesh_1.Durable.Client({ connection: (0, db_1.getConnection)() });
     const workflowId = `wf-planner-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const principal = userId ? await (0, principal_1.resolvePrincipal)(userId) : undefined;
     const handle = await client.workflow.start({
         args: [{
                 data: { specification, setId, existingPlan, existingSchemas },
-                metadata: { source: 'dashboard' },
-                lt: { userId },
+                metadata: { source: 'dashboard', certified: true },
+                lt: { userId, principal, scopes: ['workflow:invoke', 'mcp:tool:call'] },
             }],
         taskQueue: 'long-tail-system',
         workflowName: 'mcpWorkflowPlanner',

package/build/services/mcp/db.d.ts

@@ -33,6 +33,7 @@ export declare function seedMcpServer(input: {
     name: string;
     description?: string;
     tags?: string[];
+    category?: string;
     compileHints?: string;
     credentialProviders?: string[];
     toolManifest?: any[];

package/build/services/mcp/db.js

@@ -169,6 +169,7 @@ async function seedMcpServer(input) {
         input.tags || [],
         input.compileHints || null,
         input.credentialProviders || [],
+        input.category || null,
     ]);
     const inserted = (rowCount ?? 0) > 0;
     if (!inserted) {

package/build/services/mcp/sql.d.ts

@@ -18,4 +18,4 @@ export declare const DELETE_STALE_BUILTIN_SERVERS = "\n  DELETE FROM lt_mcp_serv
 /** Upsert — used by dashboard/API writes (overwrites intentionally). */
 export declare const UPSERT_MCP_SERVER = "\n  INSERT INTO lt_mcp_servers\n    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, last_connected_at)\n  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, NOW())\n  ON CONFLICT (name) DO UPDATE SET\n    tool_manifest = EXCLUDED.tool_manifest,\n    metadata = EXCLUDED.metadata,\n    description = EXCLUDED.description,\n    tags = EXCLUDED.tags,\n    compile_hints = EXCLUDED.compile_hints,\n    credential_providers = EXCLUDED.credential_providers,\n    status = 'connected',\n    last_connected_at = NOW()";
 /** Seed — insert-if-absent. DB is source of truth after first boot. */
-export declare const SEED_MCP_SERVER = "\n  INSERT INTO lt_mcp_servers\n    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, last_connected_at)\n  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, NOW())\n  ON CONFLICT (name) DO NOTHING";
+export declare const SEED_MCP_SERVER = "\n  INSERT INTO lt_mcp_servers\n    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, category, last_connected_at)\n  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, $10, NOW())\n  ON CONFLICT (name) DO NOTHING";

package/build/services/mcp/sql.js

@@ -94,6 +94,6 @@ exports.UPSERT_MCP_SERVER = `
 /** Seed — insert-if-absent. DB is source of truth after first boot. */
 exports.SEED_MCP_SERVER = `
   INSERT INTO lt_mcp_servers
-    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, last_connected_at)
-  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, NOW())
+    (name, description, transport_type, transport_config, auto_connect, status, tool_manifest, metadata, tags, compile_hints, credential_providers, category, last_connected_at)
+  VALUES ($1, $2, $3, $4, true, 'connected', $5, $6, $7, $8, $9, $10, NOW())
   ON CONFLICT (name) DO NOTHING`;

package/build/start/workers.js

@@ -220,12 +220,79 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
         // Register workers for active YAML (deterministic) workflows
         await yamlWorkflowWorkers.registerAllActiveWorkers();
     }
+    // Seed agents (from startConfig + system agents)
+    const { getSystemAgents } = await Promise.resolve().then(() => __importStar(require('../system')));
+    const allAgentConfigs = [...(startConfig.agents ?? []), ...getSystemAgents()];
+    if (allAgentConfigs.length > 0) {
+        const { seedAgent, getAgentByName } = await Promise.resolve().then(() => __importStar(require('../services/agent')));
+        const { seedSubscription } = await Promise.resolve().then(() => __importStar(require('../services/agent/subscriptions')));
+        for (const agentConfig of allAgentConfigs) {
+            try {
+                // Map flat schedules into behaviors.schedules for DB storage
+                const behaviors = {};
+                if (agentConfig.schedules?.length) {
+                    behaviors.schedules = agentConfig.schedules;
+                    behaviors.cron = agentConfig.schedules[0].cron;
+                }
+                const inserted = await seedAgent({
+                    name: agentConfig.name,
+                    description: agentConfig.description,
+                    goals: agentConfig.goals,
+                    rules: agentConfig.rules,
+                    status: (agentConfig.status ?? 'active'),
+                    knowledge_domain: agentConfig.knowledge_domain,
+                    behaviors,
+                    workflow_type: agentConfig.schedules?.[0]?.workflow_type,
+                });
+                if (inserted)
+                    logger_1.loggerRegistry.info(`[long-tail] agent seeded: ${agentConfig.name}`);
+                // Seed subscriptions for this agent
+                if (agentConfig.subscriptions?.length) {
+                    const agent = await getAgentByName(agentConfig.name);
+                    if (agent) {
+                        for (const sub of agentConfig.subscriptions) {
+                            try {
+                                const subInserted = await seedSubscription(agent.id, sub);
+                                if (subInserted)
+                                    logger_1.loggerRegistry.info(`[long-tail] subscription seeded: ${agentConfig.name}/${sub.topic}`);
+                            }
+                            catch (subErr) {
+                                logger_1.loggerRegistry.warn(`[long-tail] subscription seed failed: ${agentConfig.name}/${sub.topic}: ${subErr.message}`);
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger_1.loggerRegistry.warn(`[long-tail] agent seed failed for ${agentConfig.name}: ${err.message}`);
+            }
+        }
+    }
+    // Register the in-process callback adapter for agent event triggers
+    const { CallbackEventAdapter } = await Promise.resolve().then(() => __importStar(require('../lib/events/callback')));
+    const { agentTriggerRegistry } = await Promise.resolve().then(() => __importStar(require('../services/agent/trigger-registry')));
+    const callbackAdapter = new CallbackEventAdapter();
+    events_1.eventRegistry.register(callbackAdapter);
     // Connect event adapters (outside workers guard so API-only containers
     // still connect to NATS and can publish/receive events)
     if (events_1.eventRegistry.hasAdapters) {
         await events_1.eventRegistry.connect();
         logger_1.loggerRegistry.info('[long-tail] event adapters connected');
     }
+    // Arm agent event subscriptions (after event adapters are connected)
+    try {
+        await agentTriggerRegistry.connect(callbackAdapter);
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[long-tail] agent trigger registry: ${err.message}`);
+    }
+    // Arm agent cron schedules
+    try {
+        await cron_1.cronRegistry.connectAgentCrons();
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[long-tail] agent cron schedules: ${err.message}`);
+    }
     // Ensure system bot account exists for cron/system-initiated workflows
     const { ensureSystemBot } = await Promise.resolve().then(() => __importStar(require('../services/iam/bots')));
     await ensureSystemBot().catch((err) => logger_1.loggerRegistry.warn(`[long-tail] system bot seed error: ${err.message}`));

package/build/system/activities/knowledge.js

@@ -10,6 +10,7 @@ exports.removeKnowledgeField = removeKnowledgeField;
 exports.listDomains = listDomains;
 exports.appendKnowledge = appendKnowledge;
 const db_1 = require("../../lib/db");
+const publish_1 = require("../../lib/events/publish");
 const sql_1 = require("./sql");
 async function withClient(fn) {
     const { class: PgClient, options } = (0, db_1.getConnection)();
@@ -26,7 +27,9 @@ async function storeKnowledge(args) {
     return withClient(async (client) => {
         const sql = args.replace ? sql_1.REPLACE_KNOWLEDGE : sql_1.UPSERT_KNOWLEDGE;
         const { rows } = await client.query(sql, [args.domain, args.key, JSON.stringify(args.data), args.tags || []]);
-        return { ...rows[0], updated_at: rows[0].updated_at.toISOString() };
+        const result = { ...rows[0], updated_at: rows[0].updated_at.toISOString() };
+        (0, publish_1.publishKnowledgeEvent)({ type: 'knowledge.stored', domain: args.domain, key: args.key });
+        return result;
     });
 }
 async function getKnowledge(args) {
@@ -111,7 +114,11 @@ async function listKnowledge(args) {
 async function deleteKnowledge(args) {
     return withClient(async (client) => {
         const { rowCount } = await client.query(sql_1.DELETE_KNOWLEDGE, [args.domain, args.key]);
-        return { deleted: (rowCount ?? 0) > 0 };
+        const deleted = (rowCount ?? 0) > 0;
+        if (deleted) {
+            (0, publish_1.publishKnowledgeEvent)({ type: 'knowledge.deleted', domain: args.domain, key: args.key });
+        }
+        return { deleted };
     });
 }
 async function setKnowledgeField(args) {

package/build/system/index.d.ts

@@ -4,7 +4,7 @@
  * All declarations carry inline `config` that seeds the DB on first boot.
  * DB is the source of truth after seeding — startup never overwrites.
  */
-import type { LTWorkerConfig, LTMcpServerConfig } from '../types/startup';
+import type { LTWorkerConfig, LTMcpServerConfig, LTAgentConfig } from '../types/startup';
 export type SystemWorkerEntry = {
     taskQueue: string;
     workflow: (...args: any[]) => any;
@@ -16,3 +16,4 @@ export type McpServerFactoryEntry = {
     config: LTMcpServerConfig;
 };
 export declare const builtinMcpServerFactories: Record<string, McpServerFactoryEntry>;
+export declare function getSystemAgents(): LTAgentConfig[];

package/build/system/index.js

@@ -41,6 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.builtinMcpServerFactories = void 0;
 exports.getSystemWorkers = getSystemWorkers;
+exports.getSystemAgents = getSystemAgents;
 // ── Tool manifests (static JSON schema data) ────────────────────────────────
 const tool_manifests_escalation_1 = require("./seed/tool-manifests-escalation");
 const tool_manifests_data_1 = require("./seed/tool-manifests-data");
@@ -48,12 +49,18 @@ const tool_manifests_browser_1 = require("./seed/tool-manifests-browser");
 const tool_manifests_workflows_1 = require("./seed/tool-manifests-workflows");
 const tool_manifests_admin_1 = require("./seed/tool-manifests-admin");
 const tool_manifests_knowledge_1 = require("./seed/tool-manifests-knowledge");
-// Gmail is an example connector — loaded conditionally (not in npm package)
+const tool_manifests_events_1 = require("./seed/tool-manifests-events");
+// Example connectors — loaded conditionally (not in npm package)
 let GMAIL_TOOLS = [];
 try {
     GMAIL_TOOLS = require('../examples/seed/tool-manifests-gmail').GMAIL_TOOLS;
 }
 catch { /* not available */ }
+let IMAGE_TOOLS = [];
+try {
+    IMAGE_TOOLS = require('../examples/mcp-servers/tool-manifests-image').IMAGE_TOOLS;
+}
+catch { /* not available */ }
 // ── Role constants ──────────────────────────────────────────────────────────
 const SYSTEM_ROLES = ['reviewer', 'engineer', 'admin'];
 const ENGINEER = 'engineer';
@@ -135,6 +142,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Built-in escalation and human queue management. Exposes the escalation API as MCP tools for AI agents and remediation workflows.',
             tags: ['escalation', 'human-queue', 'routing'],
+            category: 'Automation',
             compileHints: [
                 'escalate_and_wait creates a durable pause point.',
                 'The step AFTER escalate_and_wait is always a signal step (kind: "signal") that receives the human response.',
@@ -148,6 +156,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Text translation using LLM. Translates content between languages with automatic source language detection.',
             tags: ['translation', 'language', 'text-processing'],
+            category: 'Analysis',
             credentialProviders: ['anthropic'],
             toolManifest: tool_manifests_data_1.TRANSLATION_TOOLS,
         },
@@ -157,6 +166,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Image analysis and description using LLM vision. Analyzes images to extract structured data, text content, and descriptions.',
             tags: ['vision', 'image-analysis', 'multimodal'],
+            category: 'Analysis',
             compileHints: [
                 'Vision tools process one image at a time.',
                 'The argument name is `image` (NOT `image_path`). It accepts a storage path, data URI, or https:// URL.',
@@ -172,6 +182,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Low-level browser automation via Playwright. Fine-grained control: navigate, click, fill, wait_for, evaluate, run_script.',
             tags: ['browser-automation', 'testing', 'screenshots'],
+            category: 'Automation',
             compileHints: [
                 'Session fields (_handle, page_id) MUST be threaded from the step that created them to EVERY subsequent browser step.',
                 'run_script accepts a `steps` array — fixed implementation detail, never a dynamic input.',
@@ -185,6 +196,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'High-level browser automation. Intent-based tools that handle session management, timing, and error recovery internally.',
             tags: ['browser-automation', 'screenshots', 'scraping', 'forms'],
+            category: 'Automation',
             compileHints: [
                 'Session fields (_handle, page_id) MUST be threaded from producing step to ALL subsequent browser steps.',
                 'extract_content returns `links` (structured array) and `script_result` (raw). Use `links` as the source field.',
@@ -198,6 +210,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Product documentation search and retrieval. List, search, and read Long Tail documentation.',
             tags: ['documentation', 'help', 'reference'],
+            category: 'Reference',
             toolManifest: tool_manifests_data_1.DOCS_TOOLS,
         },
     },
@@ -206,6 +219,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Managed file storage for reading, writing, listing, and deleting files.',
             tags: ['storage', 'files', 'io'],
+            category: 'Data',
             toolManifest: tool_manifests_data_1.FILE_STORAGE_TOOLS,
         },
     },
@@ -214,6 +228,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'HTTP client tools for making GET, POST, and arbitrary HTTP requests.',
             tags: ['http', 'api', 'fetch', 'network'],
+            category: 'Data',
             compileHints: 'HTTP response bodies may be large. Prefer specific fields from parsed JSON rather than raw body.',
             toolManifest: tool_manifests_data_1.HTTP_FETCH_TOOLS,
         },
@@ -223,6 +238,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'OAuth token management. Get fresh access tokens for external services. Handles automatic token refresh.',
             tags: ['authentication', 'oauth', 'credentials'],
+            category: 'System',
             compileHints: 'get_access_token returns a short-lived token. Call immediately before authenticated API requests — do not cache across steps.',
             toolManifest: tool_manifests_data_1.OAUTH_TOOLS,
         },
@@ -232,6 +248,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Agentic coding assistant via Claude Code CLI. Execute development tasks: code generation, refactoring, file analysis, and multi-step workflows.',
             tags: ['development', 'coding', 'ai-agent', 'terminal', 'code-generation'],
+            category: 'Development',
             compileHints: 'execute_task runs Claude Code as a subprocess. The `prompt` parameter is ALWAYS a dynamic trigger input. ' +
                 'Keep prompts self-contained. For read-only analysis, restrict with allowed_tools: ["Read", "Grep", "Glob"].',
             credentialProviders: ['anthropic'],
@@ -243,6 +260,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'System administration tools for reflexive self-management. Certify workflows, update server tags, manage roles.',
             tags: ['admin', 'system', 'configuration'],
+            category: 'System',
             compileHints: 'Admin tools modify system configuration. certify_workflow and decertify_workflow change interceptor behavior.',
             toolManifest: tool_manifests_admin_1.ADMIN_TOOLS,
         },
@@ -252,6 +270,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Persistent knowledge store for autonomous agents. Store, retrieve, search, and accumulate JSONB documents in isolated domains.',
             tags: ['knowledge', 'memory', 'state', 'storage'],
+            category: 'Data',
             compileHints: 'store_knowledge: domain (string), key (string), data (object — MUST be JSON object, never string). ' +
                 'Upserts by domain+key. search_knowledge uses JSONB containment (@>). ' +
                 'append_knowledge adds to arrays without replacing. list_domains returns all domains with counts.',
@@ -263,6 +282,7 @@ exports.builtinMcpServerFactories = {
         config: {
             description: 'Schema-driven data exchange with external service endpoints. Validates requests and responses against JSON Schema.',
             tags: ['api', 'schema', 'exchange', 'validation', 'fetch'],
+            category: 'Data',
             compileHints: 'Validates requests before sending and responses after receiving. ' +
                 'Embed request_schema and response_schema as STATIC values. ' +
                 'Exchange output: { status, data, headers, elapsed_ms, validated }. API response is in .data field. ' +
@@ -270,6 +290,17 @@ exports.builtinMcpServerFactories = {
             toolManifest: tool_manifests_data_1.SCHEMA_EXCHANGE_TOOLS,
         },
     },
+    'long-tail-events': {
+        factory: () => Promise.resolve().then(() => __importStar(require('./mcp-servers/events'))).then((m) => m.createEventsServer()),
+        config: {
+            description: 'Event bus for agent-to-agent communication. Publish custom events that other agents subscribe to and react to.',
+            tags: ['events', 'messaging', 'pub-sub'],
+            category: 'Communication',
+            compileHints: 'publish_event: topic follows app.{namespace}.{entity}.{action} convention. ' +
+                'The app. prefix is auto-added if omitted. Events are delivered to all matching subscribers.',
+            toolManifest: tool_manifests_events_1.EVENTS_TOOLS,
+        },
+    },
 };
 // Gmail is an example connector — only register when available (not in npm package)
 if (GMAIL_TOOLS.length > 0) {
@@ -278,6 +309,7 @@ if (GMAIL_TOOLS.length > 0) {
         config: {
             description: 'Gmail tools — search, read, summarize, extract, and draft emails using your connected Google account.',
             tags: ['gmail', 'email', 'messaging', 'google'],
+            category: 'Communication',
             compileHints: 'Requires a connected Google account (OAuth). gmail_search finds messages, gmail_read gets full content, ' +
                 'gmail_summarize for threads, gmail_extract for structured data, gmail_draft for composing.',
             credentialProviders: ['google'],
@@ -285,3 +317,63 @@ if (GMAIL_TOOLS.length > 0) {
         },
     };
 }
+// Image tools — example connector for image processing via sharp
+if (IMAGE_TOOLS.length > 0) {
+    exports.builtinMcpServerFactories['long-tail-image-tools'] = {
+        factory: () => Promise.resolve().then(() => __importStar(require('../examples/mcp-servers/image-tools'))).then((m) => m.createImageToolsServer()),
+        config: {
+            description: 'Image processing tools — resize, crop, rotate, convert, blur, compress, and more.',
+            tags: ['image', 'processing', 'vision'],
+            category: 'Media',
+            compileHints: 'Image tools accept file paths from storage. Use file_storage tools to upload images first.',
+            toolManifest: IMAGE_TOOLS,
+        },
+    };
+}
+// ── System agents ──────────────────────────────────────────────────────────
+function getSystemAgents() {
+    return [
+        {
+            name: 'health-monitor',
+            description: 'Watches for workflow failures and schema drift',
+            goals: 'Detect failures early, capture diagnostics, and alert before cascading issues',
+            rules: 'Do not restart failed workflows automatically. Capture state and escalate.',
+            status: 'active',
+            knowledge_domain: 'system-health',
+            schedules: [
+                { cron: '0 * * * *', workflow_type: 'basicEcho' },
+            ],
+            subscriptions: [
+                { topic: 'workflow.failed', reaction_type: 'durable', workflow_type: 'basicEcho', input_mapping: { data: { error: '{event.status}', workflowId: '{event.workflowId}' } } },
+                { topic: 'activity.failed', reaction_type: 'durable', workflow_type: 'basicEcho', input_mapping: { data: { activity: '{event.activityName}', workflowId: '{event.workflowId}' } } },
+                { topic: 'app.*.*.error', reaction_type: 'durable', workflow_type: 'basicEcho', input_mapping: { data: { error: '{event.data}', source: '{event.source}' } } },
+            ],
+        },
+        {
+            name: 'event-coordinator',
+            description: 'Coordinates cross-system events and routes them to workflows',
+            goals: 'Serve as the central nervous system for event-driven automation',
+            rules: 'Route critical events within 5 seconds. Never drop events.',
+            status: 'active',
+            knowledge_domain: 'event-routing',
+            subscriptions: [
+                { topic: 'app.>', reaction_type: 'durable', workflow_type: 'basicEcho', input_mapping: { data: { topic: '{event.type}', source: '{event.source}', payload: '{event.data}' } } },
+                { topic: 'knowledge.stored', reaction_type: 'durable', workflow_type: 'basicEcho', input_mapping: { data: { domain: '{event.data.domain}', key: '{event.data.key}' } } },
+            ],
+        },
+        {
+            name: 'content-triage',
+            description: 'Auto-resolves low-confidence content review escalations',
+            goals: 'Reduce human review burden by auto-triaging content below confidence thresholds',
+            rules: 'Never auto-approve content flagged for legal review.',
+            status: 'active',
+            knowledge_domain: 'content-review',
+            schedules: [
+                { cron: '*/15 * * * *', workflow_type: 'reviewContent' },
+            ],
+            subscriptions: [
+                { topic: 'escalation.created', reaction_type: 'durable', workflow_type: 'reviewContent', filter: { workflowName: 'reviewContent' }, input_mapping: { data: { escalationId: '{event.escalationId}', workflowId: '{event.workflowId}' } } },
+            ],
+        },
+    ];
+}

package/build/system/mcp-servers/events.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createEventsServer(options?: {
+    name?: string;
+}): Promise<McpServer>;
+export declare function stopEventsServer(): Promise<void>;