@hotmeshio/long-tail 0.31.1 → 0.32.0

package/build/system/mcp-servers/admin/schemas.d.ts

@@ -2101,6 +2101,33 @@ export declare const aggregateByFacetsSchema: z.ZodObject<{
             from: string;
             to: string;
         };
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"resolved">;
+        window: z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            from: string;
+            to: string;
+        }, {
+            from: string;
+            to: string;
+        }>;
+        bucket: z.ZodOptional<z.ZodEnum<["day", "week", "month"]>>;
+    }, "strip", z.ZodTypeAny, {
+        kind: "resolved";
+        window: {
+            from: string;
+            to: string;
+        };
+        bucket?: "day" | "week" | "month" | undefined;
+    }, {
+        kind: "resolved";
+        window: {
+            from: string;
+            to: string;
+        };
+        bucket?: "day" | "week" | "month" | undefined;
     }>]>;
     distinctBy: z.ZodOptional<z.ZodString>;
     states: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -2186,6 +2213,13 @@ export declare const aggregateByFacetsSchema: z.ZodObject<{
             from: string;
             to: string;
         };
+    } | {
+        kind: "resolved";
+        window: {
+            from: string;
+            to: string;
+        };
+        bucket?: "day" | "week" | "month" | undefined;
     };
     orderBy?: {
         field: string;
@@ -2235,6 +2269,13 @@ export declare const aggregateByFacetsSchema: z.ZodObject<{
             from: string;
             to: string;
         };
+    } | {
+        kind: "resolved";
+        window: {
+            from: string;
+            to: string;
+        };
+        bucket?: "day" | "week" | "month" | undefined;
     };
     orderBy?: {
         field: string;
@@ -3191,9 +3232,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 afterSeconds?: number | undefined;
                 nextPrompt?: string | undefined;
             } | undefined;
-            confirm?: {
-                prompt: string;
-            } | undefined;
             params?: {
                 fill?: {
                     into: "subject" | "scanned";
@@ -3252,6 +3290,9 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 escalationType?: string | undefined;
                 closeCurrent?: "resolve" | "cancel" | undefined;
             } | undefined;
+            confirm?: {
+                prompt: string;
+            } | undefined;
             requireActingIdentity?: boolean | undefined;
         }, {
             verb: "resolve" | "show-detail" | "claim" | "claim-show-detail" | "release" | "escalate" | "cancel" | "hold";
@@ -3262,9 +3303,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 afterSeconds?: number | undefined;
                 nextPrompt?: string | undefined;
             } | undefined;
-            confirm?: {
-                prompt: string;
-            } | undefined;
             params?: {
                 fill?: {
                     into: "subject" | "scanned";
@@ -3323,6 +3361,9 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 escalationType?: string | undefined;
                 closeCurrent?: "resolve" | "cancel" | undefined;
             } | undefined;
+            confirm?: {
+                prompt: string;
+            } | undefined;
             requireActingIdentity?: boolean | undefined;
         }>, "many">>;
         facts: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -3451,9 +3492,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 afterSeconds?: number | undefined;
                 nextPrompt?: string | undefined;
             } | undefined;
-            confirm?: {
-                prompt: string;
-            } | undefined;
             params?: {
                 fill?: {
                     into: "subject" | "scanned";
@@ -3512,6 +3550,9 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 escalationType?: string | undefined;
                 closeCurrent?: "resolve" | "cancel" | undefined;
             } | undefined;
+            confirm?: {
+                prompt: string;
+            } | undefined;
             requireActingIdentity?: boolean | undefined;
         }[] | undefined;
         refuse?: {
@@ -3528,19 +3569,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             afterSeconds?: number | undefined;
             nextPrompt?: string | undefined;
         } | undefined;
-        confirm?: {
-            prompt: string;
-        } | undefined;
-        show?: string | undefined;
-        open?: {
-            target: "subject" | "located" | "row";
-            claim?: boolean | undefined;
-            list?: {
-                facets: string[];
-                role?: string | undefined;
-            } | undefined;
-            label?: string | undefined;
-        } | undefined;
         params?: {
             fill?: {
                 into: "subject" | "scanned";
@@ -3599,6 +3627,19 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             escalationType?: string | undefined;
             closeCurrent?: "resolve" | "cancel" | undefined;
         } | undefined;
+        confirm?: {
+            prompt: string;
+        } | undefined;
+        open?: {
+            target: "subject" | "located" | "row";
+            claim?: boolean | undefined;
+            list?: {
+                facets: string[];
+                role?: string | undefined;
+            } | undefined;
+            label?: string | undefined;
+        } | undefined;
+        show?: string | undefined;
         requireActingIdentity?: boolean | undefined;
         cardinality?: "first" | "many" | undefined;
         facts?: {
@@ -3634,9 +3675,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 afterSeconds?: number | undefined;
                 nextPrompt?: string | undefined;
             } | undefined;
-            confirm?: {
-                prompt: string;
-            } | undefined;
             params?: {
                 fill?: {
                     into: "subject" | "scanned";
@@ -3695,6 +3733,9 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 escalationType?: string | undefined;
                 closeCurrent?: "resolve" | "cancel" | undefined;
             } | undefined;
+            confirm?: {
+                prompt: string;
+            } | undefined;
             requireActingIdentity?: boolean | undefined;
         }[] | undefined;
         refuse?: {
@@ -3711,19 +3752,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             afterSeconds?: number | undefined;
             nextPrompt?: string | undefined;
         } | undefined;
-        confirm?: {
-            prompt: string;
-        } | undefined;
-        show?: string | undefined;
-        open?: {
-            target: "subject" | "located" | "row";
-            claim?: boolean | undefined;
-            list?: {
-                facets: string[];
-                role?: string | undefined;
-            } | undefined;
-            label?: string | undefined;
-        } | undefined;
         params?: {
             fill?: {
                 into: "subject" | "scanned";
@@ -3782,6 +3810,19 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             escalationType?: string | undefined;
             closeCurrent?: "resolve" | "cancel" | undefined;
         } | undefined;
+        confirm?: {
+            prompt: string;
+        } | undefined;
+        open?: {
+            target: "subject" | "located" | "row";
+            claim?: boolean | undefined;
+            list?: {
+                facets: string[];
+                role?: string | undefined;
+            } | undefined;
+            label?: string | undefined;
+        } | undefined;
+        show?: string | undefined;
         requireActingIdentity?: boolean | undefined;
         cardinality?: "first" | "many" | undefined;
         facts?: {
@@ -3842,9 +3883,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 afterSeconds?: number | undefined;
                 nextPrompt?: string | undefined;
             } | undefined;
-            confirm?: {
-                prompt: string;
-            } | undefined;
             params?: {
                 fill?: {
                     into: "subject" | "scanned";
@@ -3903,6 +3941,9 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 escalationType?: string | undefined;
                 closeCurrent?: "resolve" | "cancel" | undefined;
             } | undefined;
+            confirm?: {
+                prompt: string;
+            } | undefined;
             requireActingIdentity?: boolean | undefined;
         }[] | undefined;
         refuse?: {
@@ -3919,19 +3960,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             afterSeconds?: number | undefined;
             nextPrompt?: string | undefined;
         } | undefined;
-        confirm?: {
-            prompt: string;
-        } | undefined;
-        show?: string | undefined;
-        open?: {
-            target: "subject" | "located" | "row";
-            claim?: boolean | undefined;
-            list?: {
-                facets: string[];
-                role?: string | undefined;
-            } | undefined;
-            label?: string | undefined;
-        } | undefined;
         params?: {
             fill?: {
                 into: "subject" | "scanned";
@@ -3990,6 +4018,19 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             escalationType?: string | undefined;
             closeCurrent?: "resolve" | "cancel" | undefined;
         } | undefined;
+        confirm?: {
+            prompt: string;
+        } | undefined;
+        open?: {
+            target: "subject" | "located" | "row";
+            claim?: boolean | undefined;
+            list?: {
+                facets: string[];
+                role?: string | undefined;
+            } | undefined;
+            label?: string | undefined;
+        } | undefined;
+        show?: string | undefined;
         requireActingIdentity?: boolean | undefined;
         cardinality?: "first" | "many" | undefined;
         facts?: {
@@ -4039,9 +4080,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 afterSeconds?: number | undefined;
                 nextPrompt?: string | undefined;
             } | undefined;
-            confirm?: {
-                prompt: string;
-            } | undefined;
             params?: {
                 fill?: {
                     into: "subject" | "scanned";
@@ -4100,6 +4138,9 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
                 escalationType?: string | undefined;
                 closeCurrent?: "resolve" | "cancel" | undefined;
             } | undefined;
+            confirm?: {
+                prompt: string;
+            } | undefined;
             requireActingIdentity?: boolean | undefined;
         }[] | undefined;
         refuse?: {
@@ -4116,19 +4157,6 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             afterSeconds?: number | undefined;
             nextPrompt?: string | undefined;
         } | undefined;
-        confirm?: {
-            prompt: string;
-        } | undefined;
-        show?: string | undefined;
-        open?: {
-            target: "subject" | "located" | "row";
-            claim?: boolean | undefined;
-            list?: {
-                facets: string[];
-                role?: string | undefined;
-            } | undefined;
-            label?: string | undefined;
-        } | undefined;
         params?: {
             fill?: {
                 into: "subject" | "scanned";
@@ -4187,6 +4215,19 @@ export declare const upsertScanRuleSchema: z.ZodObject<{
             escalationType?: string | undefined;
             closeCurrent?: "resolve" | "cancel" | undefined;
         } | undefined;
+        confirm?: {
+            prompt: string;
+        } | undefined;
+        open?: {
+            target: "subject" | "located" | "row";
+            claim?: boolean | undefined;
+            list?: {
+                facets: string[];
+                role?: string | undefined;
+            } | undefined;
+            label?: string | undefined;
+        } | undefined;
+        show?: string | undefined;
         requireActingIdentity?: boolean | undefined;
         cardinality?: "first" | "many" | undefined;
         facts?: {

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

@@ -738,8 +738,13 @@ exports.aggregateByFacetsSchema = 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)'),
+        zod_1.z.object({
+            kind: zod_1.z.literal('resolved'),
+            window: analyticsWindowSchema.describe('Rows whose resolved_at falls in [from, to); up to a year'),
+            bucket: zod_1.z.enum(['day', 'week', 'month']).optional().describe('Count per UTC calendar bucket; each group carries its bucket start'),
+        }),
+    ]).describe('membership = rows/entities open at an instant; dwell = open-seconds per group within the window, clipped to it; resolved = rows resolved in the window, optionally per day/week/month (requires role, roles or entity), the trend measure'),
+    distinctBy: zod_1.z.string().optional().describe('membership and resolved: 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({
@@ -752,7 +757,7 @@ exports.aggregateByFacetsSchema = zod_1.z.object({
     })).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'),
+        field: zod_1.z.string().describe('count | dwellSeconds | sampleCount | bucket | 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)'),

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

@@ -0,0 +1,8 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * get_escalation_files: time-limited links to the stored files a row names,
+ * for anyone who may read the row. Runs the same read check as
+ * GET /api/escalations/:id/files, as the /mcp caller, else lt-system for an
+ * internal call.
+ */
+export declare function registerEscalationFilesTool(server: McpServer): void;

package/build/system/mcp-servers/human-queue-files.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerEscalationFilesTool = registerEscalationFilesTool;
+const files_1 = require("../../api/escalations/files");
+const caller_auth_1 = require("./caller-auth");
+const human_queue_schemas_1 = require("./human-queue-schemas");
+/**
+ * get_escalation_files: time-limited links to the stored files a row names,
+ * for anyone who may read the row. Runs the same read check as
+ * GET /api/escalations/:id/files, as the /mcp caller, else lt-system for an
+ * internal call.
+ */
+function registerEscalationFilesTool(server) {
+    server.registerTool('get_escalation_files', {
+        title: 'Get Escalation Files',
+        description: 'Sign the stored files an escalation names (envelope.files), for a caller who may read ' +
+            'the escalation. Each ref answers with a time-limited url, its expiresAt, name and ' +
+            'contentType; a ref that cannot be signed answers with error.',
+        inputSchema: human_queue_schemas_1.getEscalationFilesSchema,
+    }, async (args, extra) => {
+        const result = await (0, files_1.getEscalationFiles)({ id: args.escalation_id }, await (0, caller_auth_1.callerAuth)(extra));
+        if (result.error) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ escalation_id: args.escalation_id, ...result.data }),
+                }],
+        };
+    });
+}

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

@@ -38,6 +38,13 @@ export declare const getEscalationLookupsSchema: z.ZodObject<{
 }, {
     escalation_id: string;
 }>;
+export declare const getEscalationFilesSchema: z.ZodObject<{
+    escalation_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    escalation_id: string;
+}, {
+    escalation_id: string;
+}>;
 export declare const getAvailableWorkSchema: z.ZodObject<{
     role: z.ZodString;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;

package/build/system/mcp-servers/human-queue-schemas.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.escalateAndWaitSchema = exports.removeItemSchema = exports.accumulateItemSchema = exports.resolveBatchItemSchema = exports.resolveEscalationSchema = exports.claimAndResolveSchema = exports.getAvailableWorkSchema = exports.getEscalationLookupsSchema = exports.checkResolutionSchema = exports.escalateSchema = void 0;
+exports.escalateAndWaitSchema = exports.removeItemSchema = exports.accumulateItemSchema = exports.resolveBatchItemSchema = exports.resolveEscalationSchema = exports.claimAndResolveSchema = exports.getAvailableWorkSchema = exports.getEscalationFilesSchema = exports.getEscalationLookupsSchema = exports.checkResolutionSchema = exports.escalateSchema = void 0;
 const zod_1 = require("zod");
 // ── Schemas (extracted to break TS2589 deep-instantiation in registerTool generics) ──
 exports.escalateSchema = zod_1.z.object({
@@ -20,6 +20,9 @@ exports.checkResolutionSchema = zod_1.z.object({
 exports.getEscalationLookupsSchema = zod_1.z.object({
     escalation_id: zod_1.z.string().describe('The escalation whose pinned knowledge lookups to resolve'),
 });
+exports.getEscalationFilesSchema = zod_1.z.object({
+    escalation_id: zod_1.z.string().describe('The escalation whose stored files to sign'),
+});
 exports.getAvailableWorkSchema = zod_1.z.object({
     role: zod_1.z.string().describe('Role to filter by'),
     limit: zod_1.z.number().optional().default(10).describe('Max results to return'),

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

@@ -6,6 +6,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * - escalate_to_human — create a new escalation (fire-and-forget)
  * - check_resolution — check escalation status
  * - get_escalation_lookups — read the knowledge editions pinned on an escalation the caller may read
+ * - get_escalation_files: sign the stored files an escalation the caller may read names
  * - get_available_work — list available escalations by role
  * - claim_and_resolve — claim + resolve in one step
  * - resolve_escalation — resolve an already-claimed escalation

package/build/system/mcp-servers/human-queue.js

@@ -42,6 +42,7 @@ const logger_1 = require("../../lib/logger");
 const caller_auth_1 = require("./caller-auth");
 const registered_tools_1 = require("../../services/mcp/registered-tools");
 const human_queue_lookups_1 = require("./human-queue-lookups");
+const human_queue_files_1 = require("./human-queue-files");
 const escalationService = __importStar(require("../../services/escalation"));
 const resolver_validation_1 = require("../../services/escalation/resolver-validation");
 const enforcement_cache_1 = require("../../services/role/enforcement-cache");
@@ -53,26 +54,30 @@ let server = null;
  * surfaces run (agents and the sim workforce submit through these tools, so
  * they get the same contract and the same canonical violation body). Costs
  * zero reads when no role enforces (cached set); otherwise one row read.
- * Returns the MCP error content when the payload is rejected, null to proceed.
+ * Returns the MCP error content when the payload is rejected, and the review
+ * facets a passing single-row resolve stamps onto the row.
  */
-async function checkResolveToolPayload(escalationId, payload) {
+async function assessResolveToolPayload(escalationId, payload) {
     const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
     if (enforcing.size === 0)
-        return null;
+        return { rejected: null, facets: null };
     const escalation = await escalationService.getEscalation(escalationId);
     if (!escalation || !enforcing.has(escalation.role))
-        return null;
-    const report = await (0, resolver_validation_1.checkResolverPayload)(escalation, payload);
-    if (!report)
-        return null;
+        return { rejected: null, facets: null };
+    const { violation, facets } = await (0, resolver_validation_1.assessResolverPayload)(escalation, payload);
+    if (!violation)
+        return { rejected: null, facets };
     return {
-        content: [{
-                type: 'text',
-                text: JSON.stringify((0, resolver_validation_1.toValidationErrorBody)(report)),
-            }],
-        isError: true,
+        rejected: {
+            content: [{ type: 'text', text: JSON.stringify((0, resolver_validation_1.toValidationErrorBody)(violation)) }],
+            isError: true,
+        },
+        facets: null,
     };
 }
+async function checkResolveToolPayload(escalationId, payload) {
+    return (await assessResolveToolPayload(escalationId, payload)).rejected;
+}
 /**
  * Create the Long Tail Human Queue MCP server.
  *
@@ -80,6 +85,7 @@ async function checkResolveToolPayload(escalationId, payload) {
  * - escalate_to_human — create a new escalation (fire-and-forget)
  * - check_resolution — check escalation status
  * - get_escalation_lookups — read the knowledge editions pinned on an escalation the caller may read
+ * - get_escalation_files: sign the stored files an escalation the caller may read names
  * - get_available_work — list available escalations by role
  * - claim_and_resolve — claim + resolve in one step
  * - resolve_escalation — resolve an already-claimed escalation
@@ -175,6 +181,7 @@ async function createHumanQueueServer(options) {
         };
     });
     (0, human_queue_lookups_1.registerEscalationLookupsTool)(server);
+    (0, human_queue_files_1.registerEscalationFilesTool)(server);
     // ── get_available_work ──────────────────────────────────────────────
     server.registerTool('get_available_work', {
         title: 'Get Available Work',
@@ -208,7 +215,7 @@ async function createHumanQueueServer(options) {
         inputSchema: human_queue_schemas_1.claimAndResolveSchema,
     }, async (args) => {
         // Validate BEFORE claiming — a rejected payload must never strand a claim.
-        const rejected = await checkResolveToolPayload(args.escalation_id, args.payload);
+        const { rejected, facets } = await assessResolveToolPayload(args.escalation_id, args.payload);
         if (rejected)
             return rejected;
         const claimed = await escalationService.claimEscalation(args.escalation_id, args.resolver_id, 5);
@@ -221,7 +228,7 @@ async function createHumanQueueServer(options) {
                 isError: true,
             };
         }
-        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload);
+        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload, facets ?? undefined);
         if (!resolved) {
             return {
                 content: [{
@@ -248,10 +255,10 @@ async function createHumanQueueServer(options) {
         description: 'Resolve an already-claimed escalation with a payload. Use when the claim happened externally (e.g. via API). Roles with enforce_schema validate the payload against the form_schema (see check_resolution) and reject violations with a schema_validation error listing each field.',
         inputSchema: human_queue_schemas_1.resolveEscalationSchema,
     }, async (args) => {
-        const rejected = await checkResolveToolPayload(args.escalation_id, args.payload);
+        const { rejected, facets } = await assessResolveToolPayload(args.escalation_id, args.payload);
         if (rejected)
             return rejected;
-        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload);
+        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload, facets ?? undefined);
         if (!resolved) {
             return {
                 content: [{

package/build/system/seed/tool-manifests-admin.js

@@ -28,7 +28,7 @@ exports.ADMIN_TOOLS = [
     { name: 'search_by_facets', gate: 'caller', description: 'Faceted search over a pond, scoped to the caller\'s role: status, availability, metadata facets, sorting, and paging.', read_safe: true, inputSchema: { type: 'object', properties: { role: { type: 'string' }, status: { type: 'string' }, available: { type: 'boolean' }, facets: { type: 'object' }, orderBy: { type: 'array' }, limit: { type: 'integer' }, offset: { type: 'integer' } }, required: ['role'] } },
     { name: 'claim_groups', gate: 'caller', description: 'Batch-claim complete origin groups (orders) in priority order over a pond, assigned to the calling principal.', read_safe: false, inputSchema: { type: 'object', properties: { query: { type: 'object' }, limit: { type: 'integer' }, durationMinutes: { type: 'integer' }, sizeFacet: { type: 'string' } }, required: ['query'] } },
     { name: 'claim_by_facets', gate: 'caller', description: 'Batch-claim individual rows matching a facet query, assigned to the calling principal. With allOrNone, commits only the full set.', read_safe: false, inputSchema: { type: 'object', properties: { query: { type: 'object' }, limit: { type: 'integer' }, durationMinutes: { type: 'integer' }, allOrNone: { type: 'boolean' } }, required: ['query'] } },
-    { name: 'aggregate_by_facets', gate: 'caller', description: 'Grouped analytics over the escalation intervals: membership (rows or distinct entities open at an instant, incl. past instants) or dwell (open-seconds per group within a window), grouped by role/subtype/status columns, metadata facet keys, or the derived entity STATE (query.entity + groupBy.state answers "how do the entities spend their time").', read_safe: true, inputSchema: { type: 'object', properties: { query: { type: 'object' }, groupBy: { type: 'object' }, measure: { type: 'object' }, distinctBy: { type: 'string' }, states: { type: 'array' }, liveStatuses: { type: 'array', items: { type: 'string' } }, orderBy: { type: 'array' }, limit: { type: 'integer' }, offset: { type: 'integer' } }, required: ['query', 'groupBy', 'measure'] } },
+    { name: 'aggregate_by_facets', gate: 'caller', description: 'Grouped analytics over the escalation intervals: membership (rows or distinct entities open at an instant, incl. past instants), dwell (open-seconds per group within a window), or resolved (rows resolved in a window, optionally per day/week/month bucket, for trends), grouped by role/subtype/status columns, metadata facet keys, or the derived entity STATE (query.entity + groupBy.state answers "how do the entities spend their time").', read_safe: true, inputSchema: { type: 'object', properties: { query: { type: 'object' }, groupBy: { type: 'object' }, measure: { type: 'object' }, distinctBy: { type: 'string' }, states: { type: 'array' }, liveStatuses: { type: 'array', items: { type: 'string' } }, orderBy: { type: 'array' }, limit: { type: 'integer' }, offset: { type: 'integer' } }, required: ['query', 'groupBy', 'measure'] } },
     { name: 'timeline_by_facet', gate: 'caller', description: 'One entity\'s ordered escalation-interval timeline: [startedAt, endedAt) spans with durations in created_at order; open intervals report endedAt null; gaps are untracked time and are preserved.', read_safe: true, inputSchema: { type: 'object', properties: { facet: { type: 'object', properties: { key: { type: 'string' }, value: { type: 'string' } }, required: ['key', 'value'] }, query: { type: 'object' }, window: { type: 'object' }, select: { type: 'object' }, liveStatuses: { type: 'array', items: { type: 'string' } }, limit: { type: 'integer' } }, required: ['facet'] } },
     { name: 'find_by_metadata', gate: 'caller', description: 'Find escalations by a metadata key-value pair.', read_safe: true, inputSchema: { type: 'object', properties: { key: { type: 'string' }, value: { type: 'string' }, status: { type: 'string' }, limit: { type: 'integer' }, offset: { type: 'integer' } }, required: ['key', 'value'] } },
     { name: 'claim_by_metadata', gate: 'caller', description: 'Find and claim an escalation by metadata key-value pair. Supports provisionIfAbsent for JIT user+role provisioning (superadmin only).', read_safe: false, inputSchema: { type: 'object', properties: { key: { type: 'string' }, value: { type: 'string' }, durationMinutes: { type: 'integer' }, assignee: { type: 'string' }, metadata: { type: 'object' }, provisionIfAbsent: { type: 'object', description: 'JIT-provision assignee if absent: { displayName?, email?, roles?: [{ role, type? }] }' } }, required: ['key', 'value'] } },

package/build/system/seed/tool-manifests-escalation.js

@@ -47,6 +47,19 @@ exports.HUMAN_QUEUE_TOOLS = [
             required: ['escalation_id'],
         },
     },
+    {
+        name: 'get_escalation_files',
+        gate: 'caller',
+        description: 'Sign the stored files an escalation names (envelope.files), for a caller who may read the escalation. Each ref answers with a time-limited url, its expiresAt, name and contentType; a ref that cannot be signed answers with error.',
+        read_safe: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                escalation_id: { type: 'string', description: 'The escalation whose stored files to sign' },
+            },
+            required: ['escalation_id'],
+        },
+    },
     {
         name: 'get_available_work',
         gate: 'superadmin',