@hotmeshio/long-tail 0.4.18 → 0.4.20

package/build/services/topics/system-topics.js

@@ -19,7 +19,7 @@ function objectSchema(properties) {
 const SYSTEM_TOPICS = [
     // Task lifecycle
     {
-        topic: 'task.created',
+        topic: 'system.task.*.created',
         description: 'A new task has been created and queued for execution.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string', description: 'Task ID' }, status: STATUS_FIELD, data: { type: 'object', description: 'Task input data' } }),
@@ -27,7 +27,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'core'],
     },
     {
-        topic: 'task.started',
+        topic: 'system.task.*.started',
         description: 'A task has begun execution.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD }),
@@ -35,7 +35,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'core'],
     },
     {
-        topic: 'task.completed',
+        topic: 'system.task.*.completed',
         description: 'A task has finished successfully.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, milestones: { type: 'array', items: { type: 'object' }, description: 'Milestones reported' }, data: { type: 'object', description: 'Task result data' } }),
@@ -43,7 +43,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'core'],
     },
     {
-        topic: 'task.escalated',
+        topic: 'system.task.*.escalated',
         description: 'A task has been escalated for human review.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
@@ -51,7 +51,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'escalation'],
     },
     {
-        topic: 'task.failed',
+        topic: 'system.task.*.failed',
         description: 'A task has failed execution.',
         category: 'task',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object', description: 'Error details' } }),
@@ -60,7 +60,7 @@ const SYSTEM_TOPICS = [
     },
     // Workflow lifecycle
     {
-        topic: 'workflow.started',
+        topic: 'system.workflow.*.started',
         description: 'A workflow execution has started.',
         category: 'workflow',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD }),
@@ -68,7 +68,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'core'],
     },
     {
-        topic: 'workflow.completed',
+        topic: 'system.workflow.*.completed',
         description: 'A workflow execution has completed successfully.',
         category: 'workflow',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
@@ -76,7 +76,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'core'],
     },
     {
-        topic: 'workflow.failed',
+        topic: 'system.workflow.*.failed',
         description: 'A workflow execution has failed.',
         category: 'workflow',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, taskId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object', description: 'Error details' } }),
@@ -85,7 +85,7 @@ const SYSTEM_TOPICS = [
     },
     // Escalation lifecycle
     {
-        topic: 'escalation.created',
+        topic: 'system.escalation.*.created',
         description: 'A new escalation has been created for human review.',
         category: 'escalation',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
@@ -93,7 +93,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'escalation.resolved',
+        topic: 'system.escalation.*.resolved',
         description: 'An escalation has been resolved by a human operator.',
         category: 'escalation',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
@@ -101,7 +101,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'escalation.claimed',
+        topic: 'system.escalation.*.claimed',
         description: 'An escalation has been claimed by an operator.',
         category: 'escalation',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD }),
@@ -109,7 +109,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'escalation.released',
+        topic: 'system.escalation.*.released',
         description: 'An escalation has been released back to the queue.',
         category: 'escalation',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD }),
@@ -118,7 +118,7 @@ const SYSTEM_TOPICS = [
     },
     // Activity lifecycle
     {
-        topic: 'activity.started',
+        topic: 'system.activity.*.*.started',
         description: 'A YAML workflow activity step has started.',
         category: 'activity',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, activityName: { type: 'string', description: 'Activity step name' } }),
@@ -126,7 +126,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'yaml'],
     },
     {
-        topic: 'activity.completed',
+        topic: 'system.activity.*.*.completed',
         description: 'A YAML workflow activity step has completed.',
         category: 'activity',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, activityName: { type: 'string' }, data: { type: 'object' } }),
@@ -134,7 +134,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'yaml'],
     },
     {
-        topic: 'activity.failed',
+        topic: 'system.activity.*.*.failed',
         description: 'A YAML workflow activity step has failed.',
         category: 'activity',
         payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, activityName: { type: 'string' }, data: { type: 'object', description: 'Error details' } }),
@@ -143,7 +143,7 @@ const SYSTEM_TOPICS = [
     },
     // Knowledge lifecycle
     {
-        topic: 'knowledge.stored',
+        topic: 'system.knowledge.*.stored',
         description: 'A knowledge entry has been written to the knowledge store.',
         category: 'knowledge',
         payload_schema: objectSchema({ domain: { type: 'string', description: 'Knowledge domain' }, key: { type: 'string', description: 'Knowledge entry key' } }),
@@ -151,7 +151,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'knowledge'],
     },
     {
-        topic: 'knowledge.deleted',
+        topic: 'system.knowledge.*.deleted',
         description: 'A knowledge entry has been removed from the knowledge store.',
         category: 'knowledge',
         payload_schema: objectSchema({ domain: { type: 'string', description: 'Knowledge domain' }, key: { type: 'string', description: 'Knowledge entry key' } }),
@@ -160,7 +160,7 @@ const SYSTEM_TOPICS = [
     },
     // File storage
     {
-        topic: 'file.stored',
+        topic: 'system.file.stored',
         description: 'A file has been written to storage.',
         category: 'file',
         payload_schema: objectSchema({
@@ -175,7 +175,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'file', 'storage'],
     },
     {
-        topic: 'file.deleted',
+        topic: 'system.file.deleted',
         description: 'A file has been removed from storage.',
         category: 'file',
         payload_schema: objectSchema({
@@ -189,7 +189,7 @@ const SYSTEM_TOPICS = [
     },
     // Agent lifecycle
     {
-        topic: 'agent.started',
+        topic: 'system.agent.*.started',
         description: 'An agent reaction workflow has started in response to an event.',
         category: 'agent',
         payload_schema: objectSchema({ agentId: { type: 'string', description: 'Agent ID' }, agentName: { type: 'string', description: 'Agent name' }, status: STATUS_FIELD, data: { type: 'object', description: 'Trigger context' } }),
@@ -197,7 +197,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'agent'],
     },
     {
-        topic: 'agent.completed',
+        topic: 'system.agent.*.completed',
         description: 'An agent reaction workflow has completed successfully.',
         category: 'agent',
         payload_schema: objectSchema({ agentId: { type: 'string' }, agentName: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
@@ -205,7 +205,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'agent'],
     },
     {
-        topic: 'agent.failed',
+        topic: 'system.agent.*.failed',
         description: 'An agent reaction workflow has failed.',
         category: 'agent',
         payload_schema: objectSchema({ agentId: { type: 'string' }, agentName: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object', description: 'Error details' } }),
@@ -213,7 +213,7 @@ const SYSTEM_TOPICS = [
         tags: ['lifecycle', 'agent', 'error'],
     },
     {
-        topic: 'agent.status_changed',
+        topic: 'system.agent.*.status_changed',
         description: 'An agent\'s status has changed (activated, paused, errored).',
         category: 'agent',
         payload_schema: objectSchema({ agentId: { type: 'string' }, agentName: { type: 'string' }, status: STATUS_FIELD }),
@@ -222,7 +222,7 @@ const SYSTEM_TOPICS = [
     },
     // Milestone
     {
-        topic: 'milestone',
+        topic: 'system.milestone.*',
         description: 'A workflow or activity has reported progress milestones.',
         category: 'milestone',
         payload_schema: objectSchema({
@@ -240,7 +240,11 @@ const SYSTEM_TOPICS = [
  * `app.*` → 'app', everything else → first segment.
  */
 function inferCategory(topic) {
-    return topic.startsWith('app.') ? 'app' : topic.split('.')[0];
+    if (topic.startsWith('app.'))
+        return 'app';
+    if (topic.startsWith('system.'))
+        return topic.split('.')[1]; // system.workflow.* → 'workflow'
+    return topic.split('.')[0];
 }
 /**
  * Seed all 22 built-in system topics into the catalog.

package/build/services/user/index.d.ts

@@ -1,6 +1,6 @@
 export { CreateUserInput, UpdateUserInput, VALID_ROLE_TYPES } from './types';
 export { createUser, getUser, getUserByExternalId, getUserByEmail, updateUser, deleteUser, listUsers, } from './crud';
 export { isValidRoleType, addUserRole, removeUserRole, getUserRoles, hasRole, hasRoleType, } from './roles';
-export { isSuperAdmin, isGroupAdmin, canManageRole } from './rbac';
+export { isSuperAdmin, isGroupAdmin, canManageRole, hasGlobalEscalationAccess, hasRolesAsAdmin } from './rbac';
 export { verifyPassword } from './auth';
 export { seedAdmin } from './seed-admin';

package/build/services/user/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.seedAdmin = exports.verifyPassword = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
+exports.seedAdmin = exports.verifyPassword = exports.hasRolesAsAdmin = exports.hasGlobalEscalationAccess = exports.canManageRole = exports.isGroupAdmin = exports.isSuperAdmin = exports.hasRoleType = exports.hasRole = exports.getUserRoles = exports.removeUserRole = exports.addUserRole = exports.isValidRoleType = exports.listUsers = exports.deleteUser = exports.updateUser = exports.getUserByEmail = exports.getUserByExternalId = exports.getUser = exports.createUser = exports.VALID_ROLE_TYPES = void 0;
 var types_1 = require("./types");
 Object.defineProperty(exports, "VALID_ROLE_TYPES", { enumerable: true, get: function () { return types_1.VALID_ROLE_TYPES; } });
 var crud_1 = require("./crud");
@@ -22,6 +22,8 @@ var rbac_1 = require("./rbac");
 Object.defineProperty(exports, "isSuperAdmin", { enumerable: true, get: function () { return rbac_1.isSuperAdmin; } });
 Object.defineProperty(exports, "isGroupAdmin", { enumerable: true, get: function () { return rbac_1.isGroupAdmin; } });
 Object.defineProperty(exports, "canManageRole", { enumerable: true, get: function () { return rbac_1.canManageRole; } });
+Object.defineProperty(exports, "hasGlobalEscalationAccess", { enumerable: true, get: function () { return rbac_1.hasGlobalEscalationAccess; } });
+Object.defineProperty(exports, "hasRolesAsAdmin", { enumerable: true, get: function () { return rbac_1.hasRolesAsAdmin; } });
 var auth_1 = require("./auth");
 Object.defineProperty(exports, "verifyPassword", { enumerable: true, get: function () { return auth_1.verifyPassword; } });
 var seed_admin_1 = require("./seed-admin");

package/build/services/user/rbac.d.ts

@@ -13,3 +13,19 @@ export declare function isGroupAdmin(userId: string, role: string): Promise<bool
  * Superadmins can manage any role. Admins can manage roles they belong to.
  */
 export declare function canManageRole(actorId: string, role: string): Promise<boolean>;
+/**
+ * Can this user act on escalations across all roles?
+ *
+ * True for:
+ * - superadmin (any role with type 'superadmin')
+ * - admin/admin (the named 'admin' role with type 'admin')
+ *
+ * These users see all escalations, can claim/resolve/escalate across
+ * all roles, and can perform bulk actions.
+ */
+export declare function hasGlobalEscalationAccess(userId: string): Promise<boolean>;
+/**
+ * Batch check: does the user have admin type for ALL specified roles?
+ * Single query — replaces the N+1 loop in checkBulkPermission.
+ */
+export declare function hasRolesAsAdmin(userId: string, roles: string[]): Promise<boolean>;

package/build/services/user/rbac.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSuperAdmin = isSuperAdmin;
 exports.isGroupAdmin = isGroupAdmin;
 exports.canManageRole = canManageRole;
+exports.hasGlobalEscalationAccess = hasGlobalEscalationAccess;
+exports.hasRolesAsAdmin = hasRolesAsAdmin;
 const db_1 = require("../../lib/db");
 const roles_1 = require("./roles");
 const sql_1 = require("./sql");
@@ -30,3 +32,32 @@ async function isGroupAdmin(userId, role) {
 async function canManageRole(actorId, role) {
     return isGroupAdmin(actorId, role);
 }
+/**
+ * Can this user act on escalations across all roles?
+ *
+ * True for:
+ * - superadmin (any role with type 'superadmin')
+ * - admin/admin (the named 'admin' role with type 'admin')
+ *
+ * These users see all escalations, can claim/resolve/escalate across
+ * all roles, and can perform bulk actions.
+ */
+async function hasGlobalEscalationAccess(userId) {
+    if (await isSuperAdmin(userId))
+        return true;
+    const roles = await (0, roles_1.getUserRoles)(userId);
+    return roles.some((r) => r.role === 'admin' && r.type === 'admin');
+}
+/**
+ * Batch check: does the user have admin type for ALL specified roles?
+ * Single query — replaces the N+1 loop in checkBulkPermission.
+ */
+async function hasRolesAsAdmin(userId, roles) {
+    if (!roles.length)
+        return true;
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(`SELECT COUNT(DISTINCT role)::int AS cnt
+     FROM lt_user_roles
+     WHERE user_id = $1 AND role = ANY($2::text[]) AND type IN ('admin', 'superadmin')`, [userId, roles]);
+    return (rows[0]?.cnt ?? 0) >= roles.length;
+}

package/build/services/user/sso-provision.d.ts

@@ -0,0 +1,19 @@
+import type { SSOIdentity, LTSSOConfig } from '../../types/auth';
+export interface ProvisionedUser {
+    userId: string;
+    roles: Array<{
+        role: string;
+        type: string;
+    }>;
+    created: boolean;
+}
+/**
+ * JIT provision or sync an SSO identity to lt_users.
+ *
+ * Lookup by `external_id`. If not found, create with resolved roles.
+ * If found, sync any new roles from the identity.
+ *
+ * Returns the internal `lt_users.id` (UUID) that all RBAC and
+ * escalation queries use.
+ */
+export declare function ssoProvision(identity: SSOIdentity, ssoConfig: LTSSOConfig): Promise<ProvisionedUser>;

package/build/services/user/sso-provision.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ssoProvision = ssoProvision;
+const logger_1 = require("../../lib/logger");
+const crud_1 = require("./crud");
+const roles_1 = require("./roles");
+/**
+ * JIT provision or sync an SSO identity to lt_users.
+ *
+ * Lookup by `external_id`. If not found, create with resolved roles.
+ * If found, sync any new roles from the identity.
+ *
+ * Returns the internal `lt_users.id` (UUID) that all RBAC and
+ * escalation queries use.
+ */
+async function ssoProvision(identity, ssoConfig) {
+    const defaultRoleType = ssoConfig.defaultRoleType || 'member';
+    const ltRoles = resolveRoles(identity.roles || [], defaultRoleType, ssoConfig.roleMap);
+    const existing = await (0, crud_1.getUserByExternalId)(identity.externalId);
+    if (existing) {
+        // Sync roles: ensure all resolved roles exist on the user
+        const currentRoles = await (0, roles_1.getUserRoles)(existing.id);
+        for (const lr of ltRoles) {
+            const has = currentRoles.some((r) => r.role === lr.role);
+            if (!has) {
+                await (0, roles_1.addUserRole)(existing.id, lr.role, lr.type);
+            }
+        }
+        const updatedRoles = await (0, roles_1.getUserRoles)(existing.id);
+        return {
+            userId: existing.id,
+            roles: updatedRoles.map((r) => ({ role: r.role, type: r.type })),
+            created: false,
+        };
+    }
+    // Create new user
+    const user = await (0, crud_1.createUser)({
+        external_id: identity.externalId,
+        email: identity.email || undefined,
+        display_name: identity.displayName || identity.externalId,
+        roles: ltRoles.map((r) => ({ role: r.role, type: r.type })),
+        metadata: identity.metadata,
+    });
+    logger_1.loggerRegistry.info(`[lt-sso] provisioned user: ${identity.externalId} → ${user.id}`);
+    return {
+        userId: user.id,
+        roles: (user.roles || []).map((r) => ({ role: r.role, type: r.type })),
+        created: true,
+    };
+}
+function resolveRoles(hostRoles, defaultRoleType, roleMap) {
+    const mapped = roleMap
+        ? hostRoles.filter((r) => roleMap[r]).map((r) => roleMap[r])
+        : hostRoles;
+    if (mapped.length === 0) {
+        return [{ role: defaultRoleType, type: defaultRoleType }];
+    }
+    return mapped.map((role) => ({
+        role,
+        type: role === 'superadmin' ? 'superadmin' : role === 'admin' ? 'admin' : 'member',
+    }));
+}

package/build/services/workflow-invocation.js

@@ -148,15 +148,17 @@ async function checkInvocationRoles(workflowType, userId, authRole) {
     // Superadmin from JWT bypasses all invocation role checks
     if (authRole === 'superadmin')
         return;
-    const user = await userService.getUserByExternalId(userId);
+    const user = await userService.getUser(userId);
     if (!user) {
         throw new InvocationError('User not registered', 403);
     }
     const userRoles = user.roles.map((r) => r.role);
     const hasInvocationRole = wfConfig.invocation_roles.some((r) => userRoles.includes(r));
     if (!hasInvocationRole) {
-        const isSuperAdmin = user.roles.some((r) => r.type === 'superadmin');
-        if (!isSuperAdmin) {
+        // superadmin and admin/admin bypass role checks
+        const hasGlobalAccess = user.roles.some((r) => r.type === 'superadmin')
+            || user.roles.some((r) => r.role === 'admin' && r.type === 'admin');
+        if (!hasGlobalAccess) {
             throw new InvocationError('Insufficient role for invocation', 403);
         }
     }

package/build/start/config.js

@@ -100,4 +100,10 @@ async function applyServerAuthConfig(startConfig) {
             baseUrl: startConfig.auth.oauth.baseUrl,
         });
     }
+    // SSO — store config for requireAuth fallback and /api/auth/sso exchange
+    if (startConfig.auth?.sso) {
+        const { setSSOConfig } = await Promise.resolve().then(() => __importStar(require('../modules/sso')));
+        setSSOConfig(startConfig.auth.sso);
+        logger_1.loggerRegistry.info('[long-tail] SSO enabled — host auth will be trusted');
+    }
 }

package/build/start/server.js

@@ -10,6 +10,7 @@ const express_1 = __importDefault(require("express"));
 const config_1 = require("../modules/config");
 const logger_1 = require("../lib/logger");
 const routes_1 = __importDefault(require("../routes"));
+const mcp_endpoint_1 = __importDefault(require("../routes/mcp-endpoint"));
 /**
  * Create and start the embedded Express server with health check,
  * API routes, and optional dashboard static assets.
@@ -24,6 +25,7 @@ function startServer() {
         res.json({ status: 'ok', timestamp: new Date().toISOString() });
     });
     app.use('/api', routes_1.default);
+    app.use('/mcp', mcp_endpoint_1.default);
     // Serve dashboard static assets
     // Resolves correctly in both dev (ts-node from root) and prod (node build/)
     const devDist = path_1.default.join(__dirname, '..', 'dashboard', 'dist');

package/build/start/workers.js

@@ -111,6 +111,9 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
             return undefined;
         });
     }
+    // Seed MCP service account (idempotent)
+    const { seedMcpServiceAccount } = await Promise.resolve().then(() => __importStar(require('../services/mcp/seed-service-account')));
+    await seedMcpServiceAccount();
     const connection = buildConnection();
     // Readonly mode: all user-provided workers are observers — skip crons, triggers, and agent seeding.
     // System workers (mcpQuery, etc.) are always added by collectWorkers, so check the original config.
@@ -217,6 +220,9 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
             registerBuiltinServer(name, entry.factory);
         }
         logger_1.loggerRegistry.info(`[long-tail] ${Object.keys(allFactories).length} MCP server factories registered`);
+        // Set exposure config for the /mcp endpoint
+        const { setExposureConfig } = await Promise.resolve().then(() => __importStar(require('../services/mcp/exposure')));
+        setExposureConfig(startConfig.mcp?.exposure);
         // 2. Seed MCP server configs (insert-if-absent + drift log)
         for (const [name, entry] of Object.entries(allFactories)) {
             if (entry.config) {
@@ -240,6 +246,15 @@ async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
     await seedSystemTopics();
     if (startConfig.topics?.length)
         await seedConfigTopics(startConfig.topics);
+    // Seed example topics when examples are enabled
+    if (startConfig.examples) {
+        try {
+            const { EXAMPLE_TOPICS } = await Promise.resolve().then(() => __importStar(require('../examples')));
+            if (EXAMPLE_TOPICS?.length)
+                await seedConfigTopics(EXAMPLE_TOPICS);
+        }
+        catch { /* examples not available */ }
+    }
     // Seed agents (from startConfig + example system agents when enabled)
     const systemAgents = startConfig.examples
         ? (await Promise.resolve().then(() => __importStar(require('../system')))).getSystemAgents()

package/build/system/index.js

@@ -45,7 +45,17 @@ 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");
-const tool_manifests_browser_1 = require("./seed/tool-manifests-browser");
+// Playwright is an example connector — loaded conditionally (not in npm package)
+let PLAYWRIGHT_TOOLS = [];
+try {
+    PLAYWRIGHT_TOOLS = require('../examples/seed/tool-manifests-browser').PLAYWRIGHT_TOOLS;
+}
+catch { /* not available */ }
+let PLAYWRIGHT_CLI_TOOLS = [];
+try {
+    PLAYWRIGHT_CLI_TOOLS = require('../examples/seed/tool-manifests-browser').PLAYWRIGHT_CLI_TOOLS;
+}
+catch { /* not available */ }
 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");
@@ -173,6 +183,7 @@ exports.builtinMcpServerFactories = {
             description: 'Text translation using LLM. Translates content between languages with automatic source language detection.',
             tags: ['translation', 'language', 'text-processing'],
             category: 'Analysis',
+            aiRequired: true,
             credentialProviders: ['anthropic'],
             toolManifest: tool_manifests_data_1.TRANSLATION_TOOLS,
         },
@@ -183,6 +194,7 @@ exports.builtinMcpServerFactories = {
             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',
+            aiRequired: true,
             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.',
@@ -193,34 +205,6 @@ exports.builtinMcpServerFactories = {
             toolManifest: tool_manifests_data_1.VISION_ANALYSIS_TOOLS,
         },
     },
-    'long-tail-playwright': {
-        factory: () => Promise.resolve().then(() => __importStar(require('./mcp-servers/playwright'))).then((m) => m.createPlaywrightServer()),
-        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.',
-                'run_script exposes `screenshots` (array) and `last_screenshot_path` (string) as output fields.',
-            ].join(' '),
-            toolManifest: tool_manifests_browser_1.PLAYWRIGHT_TOOLS,
-        },
-    },
-    'long-tail-playwright-cli': {
-        factory: () => Promise.resolve().then(() => __importStar(require('./mcp-servers/playwright-cli'))).then((m) => m.createPlaywrightCliServer()),
-        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.',
-                'capture_page screenshot_path MUST include a file extension (.png).',
-            ].join(' '),
-            toolManifest: tool_manifests_browser_1.PLAYWRIGHT_CLI_TOOLS,
-        },
-    },
     'long-tail-docs': {
         factory: () => Promise.resolve().then(() => __importStar(require('./mcp-servers/docs'))).then((m) => m.createDocsServer()),
         config: {
@@ -265,6 +249,7 @@ exports.builtinMcpServerFactories = {
             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',
+            aiRequired: true,
             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'],
@@ -274,8 +259,8 @@ exports.builtinMcpServerFactories = {
     'long-tail-admin': {
         factory: () => Promise.resolve().then(() => __importStar(require('./mcp-servers/admin'))).then((m) => m.createAdminServer()),
         config: {
-            description: 'System administration tools for reflexive self-management. Certify workflows, update server tags, manage roles.',
-            tags: ['admin', 'system', 'configuration'],
+            description: 'Unified system management — tasks, escalations, workflows, agents, bot accounts, control plane, pipelines, topics, users, roles, and settings.',
+            tags: ['admin', 'system', 'configuration', 'agents', 'bot-accounts', 'controlplane', 'pipelines', 'topics'],
             category: 'System',
             compileHints: 'Admin tools modify system configuration. certify_workflow and decertify_workflow change interceptor behavior.',
             toolManifest: tool_manifests_admin_1.ADMIN_TOOLS,
@@ -318,6 +303,39 @@ exports.builtinMcpServerFactories = {
         },
     },
 };
+// Playwright is an example connector — only register when available (not in npm package)
+if (PLAYWRIGHT_TOOLS.length > 0) {
+    exports.builtinMcpServerFactories['long-tail-playwright'] = {
+        factory: () => Promise.resolve().then(() => __importStar(require('../examples/mcp-servers/playwright'))).then((m) => m.createPlaywrightServer()),
+        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.',
+                'run_script exposes `screenshots` (array) and `last_screenshot_path` (string) as output fields.',
+            ].join(' '),
+            toolManifest: PLAYWRIGHT_TOOLS,
+        },
+    };
+}
+if (PLAYWRIGHT_CLI_TOOLS.length > 0) {
+    exports.builtinMcpServerFactories['long-tail-playwright-cli'] = {
+        factory: () => Promise.resolve().then(() => __importStar(require('../examples/mcp-servers/playwright-cli'))).then((m) => m.createPlaywrightCliServer()),
+        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.',
+                'capture_page screenshot_path MUST include a file extension (.png).',
+            ].join(' '),
+            toolManifest: PLAYWRIGHT_CLI_TOOLS,
+        },
+    };
+}
 // Gmail is an example connector — only register when available (not in npm package)
 if (GMAIL_TOOLS.length > 0) {
     exports.builtinMcpServerFactories['long-tail-gmail'] = {
@@ -360,8 +378,8 @@ function getSystemAgents() {
                 { 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: 'system.workflow.*.failed', reaction_type: 'durable', workflow_type: 'basicEcho', input_mapping: { data: { error: '{event.status}', workflowId: '{event.workflowId}' } } },
+                { topic: 'system.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}' } } },
             ],
         },
@@ -374,7 +392,7 @@ function getSystemAgents() {
             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}' } } },
+                { topic: 'system.knowledge.*.stored', reaction_type: 'durable', workflow_type: 'basicEcho', input_mapping: { data: { domain: '{event.data.domain}', key: '{event.data.key}' } } },
             ],
         },
         {
@@ -388,7 +406,7 @@ function getSystemAgents() {
                 { 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}' } } },
+                { topic: 'system.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/admin/agent-subscriptions.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Agent subscription tools — mirrors routes/agents.ts subscription routes
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAgentSubscriptionTools(server: McpServer): void;