@hotmeshio/long-tail 0.5.11 → 0.6.0

package/build/system/mcp-servers/admin/schemas.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listStreamMessagesSchema = exports.getStreamStatsSchema = exports.applyThrottleSchema = exports.rollCallSchema = exports.listAppsSchema = exports.revokeBotKeySchema = exports.createBotApiKeySchema = exports.deleteBotSchema = exports.updateBotSchema = exports.createBotSchema = exports.getBotSchema = exports.listBotsSchema = exports.deleteAgentSubscriptionSchema = exports.createAgentSubscriptionSchema = exports.listAgentSubscriptionsSchema = exports.deleteAgentSchema = exports.updateAgentSchema = exports.createAgentSchema = exports.getAgentSchema = exports.listAgentsSchema = exports.pruneSchema = exports.addEscalationChainSchema = exports.createRoleSchema = exports.listRolesSchema = exports.removeUserRoleSchema = exports.addUserRoleSchema = exports.createUserSchema = exports.listUsersSchema = exports.invokeYamlWorkflowSchema = exports.deployYamlWorkflowSchema = exports.createYamlWorkflowSchema = exports.getYamlWorkflowSchema = exports.listYamlWorkflowsSchema = exports.disconnectMcpServerSchema = exports.connectMcpServerSchema = exports.updateMcpServerSchema = exports.listMcpServersSchema = exports.getWorkflowStatusSchema = exports.invokeWorkflowSchema = exports.listDiscoveredWorkflowsSchema = exports.deleteWorkflowConfigSchema = exports.upsertWorkflowConfigSchema = exports.listWorkflowConfigsSchema = exports.bulkTriageSchema = exports.releaseExpiredClaimsSchema = exports.claimEscalationSchema = exports.getEscalationStatsSchema = exports.findEscalationsSchema = exports.getProcessDetailSchema = exports.findTasksSchema = void 0;
-exports.findOrphanedSignalsSchema = exports.findStalledJobsSchema = exports.diagnoseJobSchema = exports.getExportStatusSchema = exports.exportWorkflowExecutionSchema = exports.exportWorkflowStateSchema = exports.listExportJobsSchema = exports.getSettingsSchema = exports.updatePrioritySchema = exports.bulkEscalateSchema = exports.bulkAssignSchema = exports.bulkClaimSchema = exports.resolveByMetadataSchema = exports.claimByMetadataSchema = exports.findByMetadataSchema = exports.deleteTopicSchema = exports.updateTopicSchema = exports.createTopicSchema = exports.getTopicSchema = exports.listTopicsSchema = exports.interruptJobSchema = exports.getJobExecutionSchema = exports.listPipelineJobsSchema = exports.listPipelineEntitiesSchema = void 0;
+exports.updateBotSchema = exports.createBotSchema = exports.getBotSchema = exports.listBotsSchema = exports.deleteAgentSubscriptionSchema = exports.createAgentSubscriptionSchema = exports.listAgentSubscriptionsSchema = exports.deleteAgentSchema = exports.updateAgentSchema = exports.createAgentSchema = exports.getAgentSchema = exports.listAgentsSchema = exports.pruneSchema = exports.addEscalationChainSchema = exports.createRoleSchema = exports.listRolesSchema = exports.removeUserRoleSchema = exports.addUserRoleSchema = exports.createUserSchema = exports.listUsersSchema = exports.invokeYamlWorkflowSchema = exports.deployYamlWorkflowSchema = exports.createYamlWorkflowSchema = exports.getYamlWorkflowSchema = exports.listYamlWorkflowsSchema = exports.disconnectMcpServerSchema = exports.connectMcpServerSchema = exports.updateMcpServerSchema = exports.listMcpServersSchema = exports.getWorkflowStatusSchema = exports.invokeWorkflowSchema = exports.listDiscoveredWorkflowsSchema = exports.deleteWorkflowConfigSchema = exports.upsertWorkflowConfigSchema = exports.listWorkflowConfigsSchema = exports.bulkTriageSchema = exports.releaseExpiredClaimsSchema = exports.bulkCancelSchema = exports.cancelEscalationSchema = exports.escalateEscalationSchema = exports.resolveBySignalKeySchema = exports.resolveEscalationSchema = exports.releaseEscalationSchema = exports.claimEscalationSchema = exports.getEscalationStatsSchema = exports.getEscalationsByWorkflowSchema = exports.getEscalationSchema = exports.findEscalationsSchema = exports.getProcessDetailSchema = exports.findTasksSchema = void 0;
+exports.claimByFacetsSchema = exports.claimGroupsSchema = exports.searchByFacetsSchema = exports.resolveByIdsSchema = exports.facetQuerySchema = exports.findOrphanedSignalsSchema = exports.findStalledJobsSchema = exports.diagnoseJobSchema = exports.getExportStatusSchema = exports.exportWorkflowExecutionSchema = exports.exportWorkflowStateSchema = exports.listExportJobsSchema = exports.getSettingsSchema = exports.updatePrioritySchema = exports.bulkEscalateSchema = exports.bulkAssignSchema = exports.bulkClaimSchema = exports.resolveByMetadataSchema = exports.claimByMetadataSchema = exports.findByMetadataSchema = exports.deleteTopicSchema = exports.updateTopicSchema = exports.createTopicSchema = exports.getTopicSchema = exports.listTopicsSchema = exports.interruptJobSchema = exports.getJobExecutionSchema = exports.listPipelineJobsSchema = exports.listPipelineEntitiesSchema = exports.listStreamMessagesSchema = exports.getStreamStatsSchema = exports.applyThrottleSchema = exports.rollCallSchema = exports.listAppsSchema = exports.revokeBotKeySchema = exports.createBotApiKeySchema = exports.deleteBotSchema = void 0;
 /**
  * Zod schemas for the admin MCP server tools.
  *
@@ -28,12 +28,40 @@ exports.getProcessDetailSchema = zod_1.z.object({
 });
 // ── escalations (routes/escalations/) ───────────────────────────────────────
 exports.findEscalationsSchema = zod_1.z.object({
-    status: zod_1.z.enum(['pending', 'resolved']).optional().describe('Filter by status'),
+    status: zod_1.z.enum(['pending', 'resolved', 'cancelled']).optional().describe('Filter by status'),
     role: zod_1.z.string().optional().describe('Filter by target role'),
     type: zod_1.z.string().optional().describe('Filter by escalation type'),
+    subtype: zod_1.z.string().optional().describe('Filter by escalation subtype'),
+    assigned_to: zod_1.z.string().optional().describe('Filter by assigned user UUID (active claim holder)'),
+    search: zod_1.z.string().optional().describe('Free-text search across description, type/subtype, role, workflow/origin id, and metadata values (e.g. a correlation key like an order id). Server-side over the full result set.'),
     priority: zod_1.z.number().int().min(1).max(4).optional().describe('Filter by priority (1=critical, 4=low)'),
+    sort_by: zod_1.z.enum(['created_at', 'priority', 'updated_at']).optional().describe('Sort column (default: priority asc, then created_at asc)'),
+    order: zod_1.z.enum(['asc', 'desc']).optional().describe('Sort direction for sort_by'),
     limit: zod_1.z.number().int().min(1).max(100).optional().default(5),
     offset: zod_1.z.number().int().min(0).optional().default(0),
+    // Faceted metadata query (role-scoped in SQL). A "facet" is a key/value INSIDE the
+    // row's metadata JSONB, matched by containment (metadata @>), GIN-served.
+    roles: zod_1.z.array(zod_1.z.string()).optional().describe('Restrict to these roles (role = ANY); narrows within scope, never widens past it'),
+    facets: zod_1.z.record(zod_1.z.any()).optional().describe('Required metadata facets — metadata @> facets (AND). e.g. { filament: "pla" } means metadata.filament == "pla"'),
+    block: zod_1.z.array(zod_1.z.record(zod_1.z.any())).optional().describe('Exclude rows whose metadata contains ANY of these facet sets: NOT (metadata @> ANY(block))'),
+    range: zod_1.z.array(zod_1.z.object({
+        facet: zod_1.z.string(),
+        op: zod_1.z.enum(['<', '<=', '>', '>=', '=']),
+        value: zod_1.z.number(),
+    })).optional().describe('Numeric ranges over a metadata facet, e.g. { facet: "confidence", op: "<=", value: 0.7 }'),
+    exists: zod_1.z.array(zod_1.z.string()).optional().describe('Metadata keys that must be present: metadata ? key'),
+    available: zod_1.z.boolean().optional().describe('true = only unclaimed/expired; false = only held now'),
+    orderBy: zod_1.z.array(zod_1.z.object({
+        field: zod_1.z.string(),
+        direction: zod_1.z.enum(['asc', 'desc']).optional(),
+        numeric: zod_1.z.boolean().optional(),
+    })).optional().describe('Sort by a column or a metadata path written "metadata.<key>" (set numeric for numeric sort)'),
+});
+exports.getEscalationSchema = zod_1.z.object({
+    id: zod_1.z.string().describe('Escalation UUID'),
+});
+exports.getEscalationsByWorkflowSchema = zod_1.z.object({
+    workflow_id: zod_1.z.string().describe('HotMesh workflow ID to list escalations for'),
 });
 exports.getEscalationStatsSchema = zod_1.z.object({
     period: zod_1.z.string().optional().describe('Time period: 1h, 24h, 7d, 30d'),
@@ -43,6 +71,27 @@ exports.claimEscalationSchema = zod_1.z.object({
     duration_minutes: zod_1.z.number().int().optional().default(30)
         .describe('Lock duration in minutes'),
 });
+exports.releaseEscalationSchema = zod_1.z.object({
+    id: zod_1.z.string().describe('Escalation UUID to release back to the pool'),
+});
+exports.resolveEscalationSchema = zod_1.z.object({
+    id: zod_1.z.string().describe('Escalation UUID to resolve'),
+    resolverPayload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload (matches the escalation form/resolver schema)'),
+});
+exports.resolveBySignalKeySchema = zod_1.z.object({
+    signalKey: zod_1.z.string().describe('Deterministic signal_key of an efficient escalation'),
+    resolverPayload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload'),
+});
+exports.escalateEscalationSchema = zod_1.z.object({
+    id: zod_1.z.string().describe('Escalation UUID'),
+    targetRole: zod_1.z.string().describe('Role to route the escalation to'),
+});
+exports.cancelEscalationSchema = zod_1.z.object({
+    id: zod_1.z.string().describe('Escalation UUID to cancel'),
+});
+exports.bulkCancelSchema = zod_1.z.object({
+    ids: zod_1.z.array(zod_1.z.string()).min(1).describe('Escalation UUIDs to cancel'),
+});
 exports.releaseExpiredClaimsSchema = zod_1.z.object({});
 exports.bulkTriageSchema = zod_1.z.object({
     ids: zod_1.z.array(zod_1.z.string()).min(1).describe('Escalation UUIDs to triage'),
@@ -81,6 +130,7 @@ exports.invokeWorkflowSchema = zod_1.z.object({
 });
 exports.getWorkflowStatusSchema = zod_1.z.object({
     workflow_id: zod_1.z.string().describe('HotMesh workflow ID'),
+    app_id: zod_1.z.string().optional().describe('HotMesh namespace for resolution (default: durable). Set this to read a child/workflow running in another app.'),
 });
 // ── mcp servers (routes/mcp.ts) ─────────────────────────────────────────────
 exports.listMcpServersSchema = zod_1.z.object({
@@ -141,6 +191,16 @@ exports.listUsersSchema = zod_1.z.object({
     limit: zod_1.z.number().int().min(1).max(100).optional().default(50),
     offset: zod_1.z.number().int().min(0).optional().default(0),
 });
+// Work-surface scope for a `member` grant. read governs search breadth, write
+// governs claim/ack/delete breadth; admin/superadmin ignore scope (act on all).
+// The write ⊆ read constraint (write_scope='all' requires read_scope='all') is
+// validated in the handler so these stay plain object shapes for the tool registry.
+const scopeFields = {
+    read_scope: zod_1.z.enum(['self', 'all']).optional()
+        .describe("Member search breadth: 'self' (own items) or 'all' (whole queue). Default all"),
+    write_scope: zod_1.z.enum(['none', 'self', 'all']).optional()
+        .describe("Member claim/ack/delete breadth: 'none', 'self' (own items), or 'all'. Default all"),
+};
 exports.createUserSchema = zod_1.z.object({
     external_id: zod_1.z.string().describe('Stable user identifier'),
     display_name: zod_1.z.string().optional(),
@@ -148,12 +208,14 @@ exports.createUserSchema = zod_1.z.object({
     roles: zod_1.z.array(zod_1.z.object({
         role: zod_1.z.string(),
         type: zod_1.z.enum(['superadmin', 'admin', 'member']),
-    })).optional().default([]).describe('Roles to assign on creation'),
+        ...scopeFields,
+    })).optional().default([]).describe('Roles to assign on creation (each with optional work-surface scope)'),
 });
 exports.addUserRoleSchema = zod_1.z.object({
     user_id: zod_1.z.string().describe('User UUID'),
     role: zod_1.z.string().describe('Role name'),
     type: zod_1.z.enum(['superadmin', 'admin', 'member']).describe('Permission level'),
+    ...scopeFields,
 });
 exports.removeUserRoleSchema = zod_1.z.object({
     user_id: zod_1.z.string().describe('User UUID'),
@@ -419,7 +481,9 @@ exports.getExportStatusSchema = zod_1.z.object({
 exports.diagnoseJobSchema = zod_1.z.object({
     workflow_id: zod_1.z.string().describe('Workflow ID to diagnose'),
     app_id: zod_1.z.string().optional().default('durable').describe('HotMesh namespace / DB schema (default: durable)'),
-    max_events: zod_1.z.number().int().min(1).optional().default(500).describe('Cap on execution events returned; most recent are kept (default: 500). For full per-message payloads use the stream browser (list_stream_messages filtered by jid) instead.'),
+    max_events: zod_1.z.number().int().min(1).optional().default(500).describe('Cap on execution events returned when events are included; most recent are kept (default: 500).'),
+    include: zod_1.z.array(zod_1.z.enum(['events', 'streams'])).optional().describe('Heavy sections to add to the verdict. "events" adds the execution timeline; "streams" adds raw engine+worker messages. Omit for the compact verdict (status, idle, stream counts, escalation, findings). For full raw message payloads prefer list_stream_messages filtered by jid.'),
+    verbosity: zod_1.z.enum(['summary', 'full']).optional().describe('Shorthand: "summary" (default) = verdict only; "full" = events + streams. Overridden by an explicit include[].'),
 });
 exports.findStalledJobsSchema = zod_1.z.object({
     app_id: zod_1.z.string().optional().default('durable').describe('HotMesh namespace / DB schema (default: durable)'),
@@ -432,3 +496,35 @@ exports.findOrphanedSignalsSchema = zod_1.z.object({
     within_hours: zod_1.z.number().int().min(1).max(720).optional().default(24).describe('Recent time window to scan, in hours (default: 24, max: 720). Bounds the scan of the partitioned worker_streams table — widen deliberately to reach older orphans.'),
     limit: zod_1.z.number().int().min(1).max(500).optional().default(100).describe('Max results (default: 100, max: 500)'),
 });
+// ── Faceted routing + set resolve ───────────────────────────────────────────
+/** A faceted query over a pond — filter/sort by columns and metadata facets. */
+exports.facetQuerySchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Pond role to target (the escalation role)'),
+    status: zod_1.z.string().optional().describe("Status filter (e.g. 'pending')"),
+    available: zod_1.z.boolean().optional().describe('Only rows not currently claimed'),
+    facets: zod_1.z.record(zod_1.z.any()).optional().describe('Metadata facet equality filters'),
+    orderBy: zod_1.z.array(zod_1.z.object({
+        column: zod_1.z.string(),
+        direction: zod_1.z.enum(['asc', 'desc']),
+    })).optional().describe('Sort order over columns'),
+    limit: zod_1.z.number().int().min(1).optional(),
+    offset: zod_1.z.number().int().min(0).optional(),
+});
+exports.resolveByIdsSchema = zod_1.z.object({
+    ids: zod_1.z.array(zod_1.z.string()).min(1).describe('Escalation ids to resolve as one set'),
+    resolverPayload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload applied to every row'),
+    metadata: zod_1.z.record(zod_1.z.any()).optional().describe('Outcome patch merged into each row'),
+});
+exports.searchByFacetsSchema = exports.facetQuerySchema;
+exports.claimGroupsSchema = zod_1.z.object({
+    query: exports.facetQuerySchema,
+    limit: zod_1.z.number().int().min(1).optional().describe('Max groups to claim'),
+    durationMinutes: zod_1.z.number().int().min(1).optional().describe('Claim TTL in minutes'),
+    sizeFacet: zod_1.z.string().optional().describe('Metadata key holding the group size'),
+});
+exports.claimByFacetsSchema = zod_1.z.object({
+    query: exports.facetQuerySchema,
+    limit: zod_1.z.number().int().min(1).optional().describe('Max rows to claim'),
+    durationMinutes: zod_1.z.number().int().min(1).optional().describe('Claim TTL in minutes'),
+    allOrNone: zod_1.z.boolean().optional().describe('Commit only if the full limit was acquired'),
+});

package/build/system/mcp-servers/admin/users.js

@@ -74,6 +74,18 @@ function registerUserTools(server) {
             'claim and resolve escalations for their assigned roles.',
         inputSchema: schemas_1.createUserSchema,
     }, async (args) => {
+        // roles carry optional read_scope/write_scope (default all/all); createUser
+        // normalizes admin/superadmin to all/all and stores member scope verbatim.
+        for (const r of args.roles) {
+            const read = r.read_scope ?? userService.DEFAULT_READ_SCOPE;
+            const write = r.write_scope ?? userService.DEFAULT_WRITE_SCOPE;
+            if (!userService.isValidScopePair(read, write)) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: `write_scope=all requires read_scope=all (role "${r.role}")` }],
+                };
+            }
+        }
         const user = await userService.createUser({
             external_id: args.external_id,
             display_name: args.display_name,
@@ -87,10 +99,24 @@ function registerUserTools(server) {
     // mirrors POST /api/users/:id/roles
     server.registerTool('add_user_role', {
         title: 'Add User Role',
-        description: 'Assign a role to a user. Role type: member, admin, or superadmin.',
+        description: 'Assign a role to a user. Role type: member, admin, or superadmin. For a ' +
+            'member, optional read_scope/write_scope set the work-surface (e.g. ' +
+            'read_scope=self + write_scope=self for a one-time user who only handles ' +
+            'their own pre-assigned escalation).',
         inputSchema: schemas_1.addUserRoleSchema,
     }, async (args) => {
-        const result = await userService.addUserRole(args.user_id, args.role, args.type);
+        const read = args.read_scope ?? userService.DEFAULT_READ_SCOPE;
+        const write = args.write_scope ?? userService.DEFAULT_WRITE_SCOPE;
+        if (!userService.isValidScopePair(read, write)) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: 'write_scope=all requires read_scope=all' }],
+            };
+        }
+        const result = await userService.addUserRole(args.user_id, args.role, args.type, {
+            read_scope: args.read_scope,
+            write_scope: args.write_scope,
+        });
         return {
             content: [{ type: 'text', text: JSON.stringify(result) }],
         };

package/build/system/mcp-servers/admin/workflows.js

@@ -37,7 +37,7 @@ exports.registerWorkflowTools = registerWorkflowTools;
 const configService = __importStar(require("../../../services/config"));
 const registry_1 = require("../../../services/workers/registry");
 const workflow_invocation_1 = require("../../../services/workflow-invocation");
-const workers_1 = require("../../../workers");
+const workflowApi = __importStar(require("../../../api/workflows"));
 const schemas_1 = require("./schemas");
 function registerWorkflowTools(server) {
     // mirrors GET /api/workflows/discovered
@@ -110,21 +110,23 @@ function registerWorkflowTools(server) {
     server.registerTool('get_workflow_status', {
         title: 'Get Workflow Status',
         description: 'Check the status and result of a workflow execution. Returns ' +
-            'status (0=complete, positive=running) and the result if complete.',
+            'status (running | complete) and the result if complete. ' +
+            'Resolution is namespace-aware: pass app_id to read a workflow (e.g. a ' +
+            'child) running in a non-default HotMesh namespace.',
         inputSchema: schemas_1.getWorkflowStatusSchema,
     }, async (args) => {
-        const { getTaskByWorkflowId } = await Promise.resolve().then(() => __importStar(require('../../../services/task')));
-        const task = await getTaskByWorkflowId(args.workflow_id);
-        if (!task) {
+        const statusResult = await workflowApi.getWorkflowStatus({
+            workflowId: args.workflow_id,
+            appId: args.app_id,
+        });
+        if (statusResult.error) {
             return {
-                content: [{ type: 'text', text: JSON.stringify({ error: 'Workflow not found' }) }],
+                content: [{ type: 'text', text: JSON.stringify({ error: statusResult.error }) }],
                 isError: true,
             };
         }
-        const client = (0, workers_1.createClient)();
-        const handle = await client.workflow.getHandle(task.task_queue || 'long-tail-system', task.workflow_type, args.workflow_id);
-        const status = await handle.status();
-        if (status !== 0) {
+        // HotMesh status: 0 = complete, positive = running.
+        if (statusResult.data?.status !== 0) {
             return {
                 content: [{
                         type: 'text',
@@ -132,11 +134,20 @@ function registerWorkflowTools(server) {
                     }],
             };
         }
-        const result = await handle.result();
+        const resultResult = await workflowApi.getWorkflowResult({
+            workflowId: args.workflow_id,
+            appId: args.app_id,
+        });
+        if (resultResult.error) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ error: resultResult.error }) }],
+                isError: true,
+            };
+        }
         return {
             content: [{
                     type: 'text',
-                    text: JSON.stringify({ workflow_id: args.workflow_id, status: 'complete', result }),
+                    text: JSON.stringify({ workflow_id: args.workflow_id, status: 'complete', result: resultResult.data?.result }),
                 }],
         };
     });