@hotmeshio/long-tail 0.5.12 → 0.6.2

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

@@ -51,30 +51,91 @@ export declare const findEscalationsSchema: z.ZodObject<{
     order: z.ZodOptional<z.ZodEnum<["asc", "desc"]>>;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     offset: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    roles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    block: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodAny>, "many">>;
+    range: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        facet: z.ZodString;
+        op: z.ZodEnum<["<", "<=", ">", ">=", "="]>;
+        value: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        facet: string;
+        op: "<" | "<=" | ">" | ">=" | "=";
+    }, {
+        value: number;
+        facet: string;
+        op: "<" | "<=" | ">" | ">=" | "=";
+    }>, "many">>;
+    exists: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    available: z.ZodOptional<z.ZodBoolean>;
+    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        direction: z.ZodOptional<z.ZodEnum<["asc", "desc"]>>;
+        numeric: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+        numeric?: boolean | undefined;
+    }, {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+        numeric?: boolean | undefined;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     limit: number;
     offset: number;
     role?: string | undefined;
     status?: "pending" | "cancelled" | "resolved" | undefined;
+    roles?: string[] | undefined;
     type?: string | undefined;
     search?: string | undefined;
     priority?: number | undefined;
+    orderBy?: {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+        numeric?: boolean | undefined;
+    }[] | undefined;
     assigned_to?: string | undefined;
     subtype?: string | undefined;
+    available?: boolean | undefined;
     sort_by?: "created_at" | "updated_at" | "priority" | undefined;
     order?: "asc" | "desc" | undefined;
+    facets?: Record<string, any> | undefined;
+    block?: Record<string, any>[] | undefined;
+    range?: {
+        value: number;
+        facet: string;
+        op: "<" | "<=" | ">" | ">=" | "=";
+    }[] | undefined;
+    exists?: string[] | undefined;
 }, {
     role?: string | undefined;
     status?: "pending" | "cancelled" | "resolved" | undefined;
+    roles?: string[] | undefined;
     type?: string | undefined;
     search?: string | undefined;
     limit?: number | undefined;
     offset?: number | undefined;
     priority?: number | undefined;
+    orderBy?: {
+        field: string;
+        direction?: "asc" | "desc" | undefined;
+        numeric?: boolean | undefined;
+    }[] | undefined;
     assigned_to?: string | undefined;
     subtype?: string | undefined;
+    available?: boolean | undefined;
     sort_by?: "created_at" | "updated_at" | "priority" | undefined;
     order?: "asc" | "desc" | undefined;
+    facets?: Record<string, any> | undefined;
+    block?: Record<string, any>[] | undefined;
+    range?: {
+        value: number;
+        facet: string;
+        op: "<" | "<=" | ">" | ">=" | "=";
+    }[] | undefined;
+    exists?: string[] | undefined;
 }>;
 export declare const getEscalationSchema: z.ZodObject<{
     id: z.ZodString;
@@ -406,19 +467,27 @@ export declare const createUserSchema: z.ZodObject<{
     display_name: z.ZodOptional<z.ZodString>;
     email: z.ZodOptional<z.ZodString>;
     roles: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        read_scope: z.ZodOptional<z.ZodEnum<["self", "all"]>>;
+        write_scope: z.ZodOptional<z.ZodEnum<["none", "self", "all"]>>;
         role: z.ZodString;
         type: z.ZodEnum<["superadmin", "admin", "member"]>;
     }, "strip", z.ZodTypeAny, {
         role: string;
         type: "admin" | "member" | "superadmin";
+        read_scope?: "self" | "all" | undefined;
+        write_scope?: "self" | "all" | "none" | undefined;
     }, {
         role: string;
         type: "admin" | "member" | "superadmin";
+        read_scope?: "self" | "all" | undefined;
+        write_scope?: "self" | "all" | "none" | undefined;
     }>, "many">>>;
 }, "strip", z.ZodTypeAny, {
     roles: {
         role: string;
         type: "admin" | "member" | "superadmin";
+        read_scope?: "self" | "all" | undefined;
+        write_scope?: "self" | "all" | "none" | undefined;
     }[];
     external_id: string;
     email?: string | undefined;
@@ -428,11 +497,15 @@ export declare const createUserSchema: z.ZodObject<{
     roles?: {
         role: string;
         type: "admin" | "member" | "superadmin";
+        read_scope?: "self" | "all" | undefined;
+        write_scope?: "self" | "all" | "none" | undefined;
     }[] | undefined;
     email?: string | undefined;
     display_name?: string | undefined;
 }>;
 export declare const addUserRoleSchema: z.ZodObject<{
+    read_scope: z.ZodOptional<z.ZodEnum<["self", "all"]>>;
+    write_scope: z.ZodOptional<z.ZodEnum<["none", "self", "all"]>>;
     user_id: z.ZodString;
     role: z.ZodString;
     type: z.ZodEnum<["superadmin", "admin", "member"]>;
@@ -440,10 +513,14 @@ export declare const addUserRoleSchema: z.ZodObject<{
     role: string;
     type: "admin" | "member" | "superadmin";
     user_id: string;
+    read_scope?: "self" | "all" | undefined;
+    write_scope?: "self" | "all" | "none" | undefined;
 }, {
     role: string;
     type: "admin" | "member" | "superadmin";
     user_id: string;
+    read_scope?: "self" | "all" | undefined;
+    write_scope?: "self" | "all" | "none" | undefined;
 }>;
 export declare const removeUserRoleSchema: z.ZodObject<{
     user_id: z.ZodString;
@@ -1154,3 +1231,251 @@ export declare const findOrphanedSignalsSchema: z.ZodObject<{
     limit?: number | undefined;
     within_hours?: number | undefined;
 }>;
+/** A faceted query over a pond — filter/sort by columns and metadata facets. */
+export declare const facetQuerySchema: z.ZodObject<{
+    role: z.ZodString;
+    status: z.ZodOptional<z.ZodString>;
+    available: z.ZodOptional<z.ZodBoolean>;
+    facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        column: z.ZodString;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strip", z.ZodTypeAny, {
+        column: string;
+        direction: "asc" | "desc";
+    }, {
+        column: string;
+        direction: "asc" | "desc";
+    }>, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    status?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    orderBy?: {
+        column: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    available?: boolean | undefined;
+    facets?: Record<string, any> | undefined;
+}, {
+    role: string;
+    status?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    orderBy?: {
+        column: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    available?: boolean | undefined;
+    facets?: Record<string, any> | undefined;
+}>;
+export declare const resolveByIdsSchema: z.ZodObject<{
+    ids: z.ZodArray<z.ZodString, "many">;
+    resolverPayload: z.ZodRecord<z.ZodString, z.ZodAny>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    ids: string[];
+    resolverPayload: Record<string, any>;
+    metadata?: Record<string, any> | undefined;
+}, {
+    ids: string[];
+    resolverPayload: Record<string, any>;
+    metadata?: Record<string, any> | undefined;
+}>;
+export declare const searchByFacetsSchema: z.ZodObject<{
+    role: z.ZodString;
+    status: z.ZodOptional<z.ZodString>;
+    available: z.ZodOptional<z.ZodBoolean>;
+    facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        column: z.ZodString;
+        direction: z.ZodEnum<["asc", "desc"]>;
+    }, "strip", z.ZodTypeAny, {
+        column: string;
+        direction: "asc" | "desc";
+    }, {
+        column: string;
+        direction: "asc" | "desc";
+    }>, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    status?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    orderBy?: {
+        column: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    available?: boolean | undefined;
+    facets?: Record<string, any> | undefined;
+}, {
+    role: string;
+    status?: string | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    orderBy?: {
+        column: string;
+        direction: "asc" | "desc";
+    }[] | undefined;
+    available?: boolean | undefined;
+    facets?: Record<string, any> | undefined;
+}>;
+export declare const claimGroupsSchema: z.ZodObject<{
+    query: z.ZodObject<{
+        role: z.ZodString;
+        status: z.ZodOptional<z.ZodString>;
+        available: z.ZodOptional<z.ZodBoolean>;
+        facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            direction: z.ZodEnum<["asc", "desc"]>;
+        }, "strip", z.ZodTypeAny, {
+            column: string;
+            direction: "asc" | "desc";
+        }, {
+            column: string;
+            direction: "asc" | "desc";
+        }>, "many">>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        offset: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        role: string;
+        status?: string | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        orderBy?: {
+            column: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        available?: boolean | undefined;
+        facets?: Record<string, any> | undefined;
+    }, {
+        role: string;
+        status?: string | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        orderBy?: {
+            column: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        available?: boolean | undefined;
+        facets?: Record<string, any> | undefined;
+    }>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    durationMinutes: z.ZodOptional<z.ZodNumber>;
+    sizeFacet: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    query: {
+        role: string;
+        status?: string | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        orderBy?: {
+            column: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        available?: boolean | undefined;
+        facets?: Record<string, any> | undefined;
+    };
+    limit?: number | undefined;
+    durationMinutes?: number | undefined;
+    sizeFacet?: string | undefined;
+}, {
+    query: {
+        role: string;
+        status?: string | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        orderBy?: {
+            column: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        available?: boolean | undefined;
+        facets?: Record<string, any> | undefined;
+    };
+    limit?: number | undefined;
+    durationMinutes?: number | undefined;
+    sizeFacet?: string | undefined;
+}>;
+export declare const claimByFacetsSchema: z.ZodObject<{
+    query: z.ZodObject<{
+        role: z.ZodString;
+        status: z.ZodOptional<z.ZodString>;
+        available: z.ZodOptional<z.ZodBoolean>;
+        facets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        orderBy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            column: z.ZodString;
+            direction: z.ZodEnum<["asc", "desc"]>;
+        }, "strip", z.ZodTypeAny, {
+            column: string;
+            direction: "asc" | "desc";
+        }, {
+            column: string;
+            direction: "asc" | "desc";
+        }>, "many">>;
+        limit: z.ZodOptional<z.ZodNumber>;
+        offset: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        role: string;
+        status?: string | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        orderBy?: {
+            column: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        available?: boolean | undefined;
+        facets?: Record<string, any> | undefined;
+    }, {
+        role: string;
+        status?: string | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        orderBy?: {
+            column: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        available?: boolean | undefined;
+        facets?: Record<string, any> | undefined;
+    }>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    durationMinutes: z.ZodOptional<z.ZodNumber>;
+    allOrNone: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    query: {
+        role: string;
+        status?: string | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        orderBy?: {
+            column: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        available?: boolean | undefined;
+        facets?: Record<string, any> | undefined;
+    };
+    limit?: number | undefined;
+    durationMinutes?: number | undefined;
+    allOrNone?: boolean | undefined;
+}, {
+    query: {
+        role: string;
+        status?: string | undefined;
+        limit?: number | undefined;
+        offset?: number | undefined;
+        orderBy?: {
+            column: string;
+            direction: "asc" | "desc";
+        }[] | undefined;
+        available?: boolean | undefined;
+        facets?: Record<string, any> | undefined;
+    };
+    limit?: number | undefined;
+    durationMinutes?: number | undefined;
+    allOrNone?: boolean | undefined;
+}>;

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 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.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;
+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.
  *
@@ -39,6 +39,23 @@ exports.findEscalationsSchema = zod_1.z.object({
     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'),
@@ -174,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(),
@@ -181,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'),
@@ -467,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) }],
         };