@hotmeshio/long-tail 0.10.13 → 0.11.0

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

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUserPersonasSchema = exports.unassignPersonaSchema = exports.assignPersonaSchema = exports.unlinkPersonaRoleSchema = exports.linkPersonaRoleSchema = exports.deletePersonaSchema = exports.updatePersonaSchema = exports.createPersonaSchema = exports.getPersonaSchema = exports.listPersonasSchema = exports.listRoleSchemaVersionsSchema = exports.getRoleSchemaSchema = exports.updateRoleSchema = 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 = 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 = void 0;
-exports.deleteScanRuleSchema = exports.upsertScanRuleSchema = exports.upsertScanSchemeSchema = exports.listScanSchemesSchema = exports.executeScanCodeSchema = void 0;
+exports.deleteScanRuleSchema = exports.upsertScanRuleSchema = exports.upsertScanSchemeSchema = exports.listScanSchemesSchema = exports.executeScanChoiceSchema = exports.executeScanCodeSchema = exports.timelineByFacetSchema = exports.aggregateByFacetsSchema = void 0;
 /**
  * Zod schemas for the admin MCP server tools.
  *
@@ -251,6 +251,8 @@ exports.updateRoleSchema = zod_1.z.object({
     worker_count: zod_1.z.number().nullable().optional().describe('Capacity at this station (staff or machine count). One of the capacity settings.'),
     priority_threshold_minutes: zod_1.z.number().min(0).nullable().optional().describe('Max age in minutes before a pending unclaimed escalation counts toward the Pace Board priority count. Falls back to sla_minutes when null.'),
     priority_facet: zod_1.z.string().regex(facet_sql_1.FACET_KEY).nullable().optional().describe('lt_escalations.metadata key holding the age origin for the priority count as an ISO 8601 UTC timestamp (e.g. authorized_at). Falls back to created_at when null. When set, items missing the key or holding an unparseable value are not counted.'),
+    entity_facet: zod_1.z.string().regex(facet_sql_1.FACET_KEY).nullable().optional().describe('lt_escalations.metadata key identifying the ENTITY that moves through this role (e.g. serialNumber, orderId). Powers the analytics surfaces: distinct-entity counts, per-entity dwell, entity timelines. Roles sharing an entity_facet form that entity\'s system. Null = no entity notion.'),
+    entity_state_source: zod_1.z.enum(['role', 'subtype']).nullable().optional().describe("How this role names its states for the entity: 'role' (the station itself is the state, default) or 'subtype' (the role's subtypes are its states, e.g. a fleet role parking ready/printing). Null resets to 'role'."),
     enforce_schema: zod_1.z.boolean().optional().describe('When true, every resolve surface validates the submitted resolverPayload against the escalation\'s form schema (the same pass the dashboard runs) and rejects violations with a structured schema_validation error before any state changes.'),
     upstream_roles: zod_1.z.array(zod_1.z.string()).nullable().optional().describe('Replace the set of roles this station draws input from across other sequences (parent_role stays the single prior step in its own sequence). Omitted = preserve; null or [] = clear.'),
     list_schema: zod_1.z.record(zod_1.z.any()).nullable().optional().describe('JSON contract (x-lt-* markup) that richly formats this role\'s escalation LIST page. Versioned independently of form_schema; the list always renders the latest version.'),
@@ -606,24 +608,131 @@ exports.claimByFacetsSchema = zod_1.z.object({
     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'),
 });
+// ── Escalation analytics ─────────────────────────────────────────────────────
+/**
+ * The analytics filter — the WHAT of a facet query only. status/available/
+ * jeopardy (and row paging) are REJECTED by the API: liveness derives from
+ * the interval + measure, paging applies to result groups.
+ */
+const analyticsFilterSchema = zod_1.z.object({
+    role: zod_1.z.string().optional().describe('Single pond role to target'),
+    roles: zod_1.z.array(zod_1.z.string()).optional().describe('Multiple pond roles; no role at all spans every pond (global principals only)'),
+    entity: zod_1.z.string().optional().describe("An entity facet key (e.g. serialNumber): resolves server-side to every role declaring it as entity_facet — the entity's SYSTEM. Mutually exclusive with role/roles."),
+    facets: zod_1.z.record(zod_1.z.any()).optional().describe('Metadata facet equality filters (metadata @> containment)'),
+    anyOf: zod_1.z.array(zod_1.z.record(zod_1.z.any())).optional().describe('Rows carrying ANY of these facet sets (OR, GIN-served; max 200 entries) — target an explicit entity set, e.g. one table page'),
+    prefix: zod_1.z.record(zod_1.z.string()).optional().describe("Case-insensitive prefix match on facet VALUES (metadata->>key ILIKE 'value%') — the locate affordance for entity keys"),
+    block: zod_1.z.array(zod_1.z.record(zod_1.z.any())).optional().describe('Exclude rows carrying ANY of these facet sets'),
+    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 range predicates over metadata facets'),
+    exists: zod_1.z.array(zod_1.z.string()).optional().describe('Metadata keys that must be present'),
+});
+const analyticsWindowSchema = zod_1.z.object({
+    from: zod_1.z.string().describe('ISO instant, inclusive'),
+    to: zod_1.z.string().describe('ISO instant, exclusive (half-open [from, to))'),
+});
+exports.aggregateByFacetsSchema = zod_1.z.object({
+    query: analyticsFilterSchema.describe('The filter (WHAT only — no status/available/jeopardy)'),
+    groupBy: zod_1.z.object({
+        columns: zod_1.z.array(zod_1.z.enum(['role', 'subtype', 'status'])).optional().describe('Top-level group columns'),
+        facets: zod_1.z.array(zod_1.z.string()).optional().describe('Metadata keys to group by (a NULL group key = facet absent on those rows)'),
+        state: zod_1.z.boolean().optional().describe("Group by the derived STATE label: each role contributes per its entity_state_source — its subtypes or itself. Answers 'how do the entities spend their time'. Requires role scope (entity or role/roles); mutually exclusive with states[]."),
+    }).describe('Group keys; empty object → one total row'),
+    measure: zod_1.z.union([
+        zod_1.z.object({
+            kind: zod_1.z.literal('membership'),
+            asOf: zod_1.z.string().optional().describe('ISO instant; omit for now. A past instant reconstructs the live set at that moment.'),
+        }),
+        zod_1.z.object({
+            kind: zod_1.z.literal('dwell'),
+            window: analyticsWindowSchema,
+        }),
+    ]).describe('membership = rows/entities open at an instant; dwell = open-seconds per group within the window, clipped to it'),
+    distinctBy: zod_1.z.string().optional().describe('membership only: count DISTINCT of this metadata facet (entities, not rows)'),
+    states: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string(),
+        match: zod_1.z.object({
+            role: zod_1.z.string().optional(),
+            roles: zod_1.z.array(zod_1.z.string()).optional(),
+            subtype: zod_1.z.string().optional(),
+            facets: zod_1.z.record(zod_1.z.any()).optional(),
+            exists: zod_1.z.array(zod_1.z.string()).optional(),
+        }),
+    })).optional().describe('Pure labeling: tag each group with the FIRST matching state name'),
+    liveStatuses: zod_1.z.array(zod_1.z.string()).optional().describe("Statuses considered live (default ['pending'])"),
+    orderBy: zod_1.z.array(zod_1.z.object({
+        field: zod_1.z.string().describe('count | dwellSeconds | sampleCount | a grouped column or facet key'),
+        direction: zod_1.z.enum(['asc', 'desc']).optional(),
+    })).optional().describe('Order the RESULT groups'),
+    limit: zod_1.z.number().int().min(1).optional().describe('Max result groups (server-capped; overflow flag when more exist)'),
+    offset: zod_1.z.number().int().min(0).optional(),
+});
+exports.timelineByFacetSchema = zod_1.z.object({
+    facet: zod_1.z.object({
+        key: zod_1.z.string(),
+        value: zod_1.z.string(),
+    }).describe('The entity facet, matched via GIN containment — the stored value must be a JSON string'),
+    query: analyticsFilterSchema.optional().describe('Optional extra filter / role scope'),
+    window: analyticsWindowSchema.optional().describe('Only intervals overlapping this window (overlap-filtered, not clipped)'),
+    select: zod_1.z.object({
+        columns: zod_1.z.array(zod_1.z.enum(['role', 'subtype', 'status'])).optional(),
+        facets: zod_1.z.array(zod_1.z.string()).optional(),
+    }).optional().describe('Columns/facets to surface per interval (default: all three columns)'),
+    liveStatuses: zod_1.z.array(zod_1.z.string()).optional().describe("Statuses considered live (default ['pending'])"),
+    order: zod_1.z.enum(['asc', 'desc']).optional().describe("Interval ordering by start instant (default asc); desc + before pages a long history recent-first"),
+    before: zod_1.z.string().optional().describe('Strict upper bound on startedAt (ISO instant) — the "load earlier" cursor'),
+    limit: zod_1.z.number().int().min(1).optional(),
+});
 // ── Scan codes ──────────────────────────────────────────────────────────────
 exports.executeScanCodeSchema = zod_1.z.object({
-    code: zod_1.z.string().min(1).describe('Raw scan string, e.g. "1:01:SN123" or "10175433211"'),
+    code: zod_1.z.string().min(1).describe('Raw scan string, e.g. "10:1:SN123" or "10175433211"'),
+    actingToken: zod_1.z.string().optional().describe('An acting-identity grant (eph:v1:acting_identity:*) — verbs run as the badged person'),
+    previousActingToken: zod_1.z.string().optional().describe('The grant an identity scan replaces — best-effort revoked on mint'),
+});
+exports.executeScanChoiceSchema = zod_1.z.object({
+    schemeVersion: zod_1.z.number().int().min(10).max(99),
+    category: zod_1.z.string().regex(/^[0-9]$/),
+    stepIndex: zod_1.z.number().int().min(0),
+    choiceIndex: zod_1.z.number().int().min(0),
+    escalationId: zod_1.z.string().describe('The escalation the CHOICES screen presented'),
+    actingToken: zod_1.z.string().optional().describe('An acting-identity grant — the choice attributes to the badged person'),
 });
 exports.listScanSchemesSchema = zod_1.z.object({});
+const scanStepParamsSchema = zod_1.z.object({
+    resolverPayload: zod_1.z.record(zod_1.z.any()).optional(),
+    metadata: zod_1.z.record(zod_1.z.any()).optional(),
+    targetRole: zod_1.z.string().optional(),
+    escalationType: zod_1.z.string().optional(),
+    description: zod_1.z.string().optional(),
+    closeCurrent: zod_1.z.enum(['resolve', 'cancel']).optional(),
+    durationMinutes: zod_1.z.number().int().min(1).optional(),
+});
+const scanChoiceSchema = zod_1.z.object({
+    label: zod_1.z.string().describe('Button text the associate reads'),
+    verb: zod_1.z.enum(['show-detail', 'claim', 'claim-show-detail', 'release', 'resolve', 'escalate', 'cancel']),
+    params: scanStepParamsSchema.optional(),
+    confirm: zod_1.z.object({ prompt: zod_1.z.string() }).optional(),
+    requireActingIdentity: zod_1.z.boolean().optional().describe('The choice executes only under a real acting identity (badge or a write-capable login)'),
+    code: zod_1.z.string().optional().describe('Short token enabling double-scan selection (scan object, then an action card)'),
+});
 exports.upsertScanSchemeSchema = zod_1.z.object({
-    version: zod_1.z.number().int().min(1).max(9).describe('Scheme version digit (1-9)'),
+    version: zod_1.z.number().int().min(10).max(99).describe('Two-digit scheme version (10-99)'),
     name: zod_1.z.string().describe('Scheme display name'),
     description: zod_1.z.string().optional(),
-    target_facet: zod_1.z.string().describe('Escalation metadata key the scanned target resolves against'),
+    target_facet: zod_1.z.string().describe("The metadata key the target resolves against: an escalation metadata key for action schemes, an lt_users.metadata key (e.g. badge_id) for identity schemes"),
     encoding: zod_1.z.enum(['fixed', 'delimited']).optional().describe('fixed = digits only (UPC), delimited = text with separators'),
     delimiter: zod_1.z.string().optional().describe('Separator character for delimited encoding (default ":")'),
     target_length: zod_1.z.number().int().min(1).optional().describe('Target digit count for fixed encoding'),
+    kind: zod_1.z.enum(['action', 'identity']).optional().describe("action = ECA steps over escalations (default); identity = a badge that mints a short-lived acting-identity grant"),
+    grant_ttl_seconds: zod_1.z.number().int().min(1).max(86400).optional().describe('Identity kind: how long a minted acting grant lives'),
+    grant_max_uses: zod_1.z.number().int().min(0).optional().describe('Identity kind: 0 = TTL-bound; n = the grant covers n scan requests'),
     enabled: zod_1.z.boolean().optional(),
 });
 exports.upsertScanRuleSchema = zod_1.z.object({
-    scheme_version: zod_1.z.number().int().min(1).max(9),
-    category: zod_1.z.string().regex(/^[0-9]{2}$/).describe('Two-digit category (00-99)'),
+    scheme_version: zod_1.z.number().int().min(10).max(99),
+    category: zod_1.z.string().regex(/^[0-9]$/).describe('Single-digit category (0-9)'),
     name: zod_1.z.string().describe('Friendly label — printed next to the physical code'),
     steps: zod_1.z.array(zod_1.z.object({
         query: zod_1.z.object({
@@ -633,25 +742,24 @@ exports.upsertScanRuleSchema = zod_1.z.object({
             facets: zod_1.z.record(zod_1.z.any()).optional().describe('Extra metadata guards'),
         }),
         cardinality: zod_1.z.enum(['first', 'many']).optional(),
-        verb: zod_1.z.enum(['show-detail', 'show-list', 'claim', 'claim-show-detail', 'release', 'resolve', 'escalate', 'cancel']),
+        verb: zod_1.z.enum(['show-detail', 'show-list', 'claim', 'claim-show-detail', 'release', 'resolve', 'escalate', 'cancel', 'present']),
         confirm: zod_1.z.object({ prompt: zod_1.z.string() }).optional(),
-        params: zod_1.z.object({
-            resolverPayload: zod_1.z.record(zod_1.z.any()).optional(),
-            metadata: zod_1.z.record(zod_1.z.any()).optional(),
-            targetRole: zod_1.z.string().optional(),
-            escalationType: zod_1.z.string().optional(),
-            description: zod_1.z.string().optional(),
-            closeCurrent: zod_1.z.enum(['resolve', 'cancel']).optional(),
-            durationMinutes: zod_1.z.number().int().min(1).optional(),
-        }).optional(),
+        params: scanStepParamsSchema.optional(),
+        requireActingIdentity: zod_1.z.boolean().optional().describe('The step executes only under a real acting identity — a badge grant, or a login whose own write scope covers the step'),
+        choices: zod_1.z.array(scanChoiceSchema).optional().describe("present verb only: the labeled choice set rendered under the located reality"),
+        autoSelectSingle: zod_1.z.boolean().optional().describe('present verb with exactly one confirm-less choice: the scan executes it directly — one scan, one action; an unsatisfied identity requirement still presents the badge stop-over'),
     })).describe('Ordered condition/action steps — first match wins'),
     fallback: zod_1.z.object({
         markdown: zod_1.z.string().optional(),
         route: zod_1.z.string().optional(),
-    }).optional().describe('Rendered when no step matches'),
+    }).optional().describe('Rendered when no step matches (identity schemes: the unknown-badge screen)'),
+    notPrimed: zod_1.z.object({
+        markdown: zod_1.z.string().optional(),
+        route: zod_1.z.string().optional(),
+    }).optional().describe('The "scan your badge" screen — rendered when an acting identity is required and absent'),
     enabled: zod_1.z.boolean().optional(),
 });
 exports.deleteScanRuleSchema = zod_1.z.object({
-    scheme_version: zod_1.z.number().int().min(1).max(9),
-    category: zod_1.z.string().regex(/^[0-9]{2}$/),
+    scheme_version: zod_1.z.number().int().min(10).max(99),
+    category: zod_1.z.string().regex(/^[0-9]$/),
 });

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

@@ -199,7 +199,7 @@ function registerUserTools(server) {
             '(server-side resolver validation), parent role, default_pins ' +
             '(member pinned-view seeds), and the typed operational targets ' +
             '(sla_minutes, target_per_hour, worker_count, ' +
-            'priority_threshold_minutes, priority_facet).',
+            'priority_threshold_minutes, priority_facet, entity_facet).',
         inputSchema: schemas_1.updateRoleSchema,
     }, async (args) => {
         const updated = await roleService.updateRoleMetadata(args.role, {
@@ -216,6 +216,8 @@ function registerUserTools(server) {
             worker_count: args.worker_count,
             priority_threshold_minutes: args.priority_threshold_minutes,
             priority_facet: args.priority_facet,
+            entity_facet: args.entity_facet,
+            entity_state_source: args.entity_state_source,
             enforce_schema: args.enforce_schema,
             upstream_roles: args.upstream_roles,
             list_schema: args.list_schema,

package/build/system/mcp-servers/human-queue-schemas.d.ts

@@ -9,20 +9,20 @@ export declare const escalateSchema: z.ZodObject<{
     schema_version: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     role: string;
+    subtype: string;
     type: string;
     message: string;
     priority: number;
-    subtype: string;
     schema_version?: number | undefined;
     data?: Record<string, any> | undefined;
 }, {
     role: string;
     message: string;
     schema_version?: number | undefined;
+    subtype?: string | undefined;
     data?: Record<string, any> | undefined;
     type?: string | undefined;
     priority?: number | undefined;
-    subtype?: string | undefined;
 }>;
 export declare const checkResolutionSchema: z.ZodObject<{
     escalation_id: z.ZodString;