npm - @hotmeshio/long-tail - Versions diffs - 0.7.1 → 0.7.3 - Mend

@hotmeshio/long-tail 0.7.1 → 0.7.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (229) hide show

package/build/services/role/sql.js CHANGED Viewed

@@ -1,7 +1,7 @@
 "use strict";
 // ─── Escalation chain queries ───────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_METADATA_SCHEMA = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
+exports.COUNT_ACTIVE_ESCALATION_REFS = exports.COUNT_WORKFLOW_REFS = exports.COUNT_CHAIN_REFS = exports.COUNT_USER_ROLE_REFS = exports.LIST_ROLES_WITH_DETAILS = exports.GET_ROLE_SCHEMA_CURRENT = exports.GET_ROLE_SCHEMA_VERSION = exports.LIST_ROLE_SCHEMA_VERSIONS = exports.GET_ROLE_UPSTREAMS = exports.GET_ROLE_METADATA_SCHEMA = exports.GET_ROLE_FORM_SCHEMA = exports.UPDATE_ROLE_METADATA = exports.DELETE_ROLE = exports.LIST_ROLES = exports.ENSURE_ROLE_EXISTS = exports.CHECK_ESCALATION_CHAIN_EXISTS = exports.DELETE_ESCALATION_CHAINS_BY_SOURCE = exports.DELETE_ESCALATION_CHAIN = exports.ADD_ESCALATION_CHAIN = exports.INSERT_ESCALATION_CHAIN = exports.GET_ALL_ESCALATION_CHAINS = exports.GET_ESCALATION_TARGETS = void 0;
 exports.GET_ESCALATION_TARGETS = `
   SELECT target_role
   FROM lt_config_role_escalations
@@ -55,27 +55,96 @@ exports.DELETE_ROLE = `
  * true the paired value is written (null clears; properties resets to '{}').
  * This is what lets the dashboard's per-tab saves and single-field MCP calls
  * coexist on the same row without read-modify-write.
+ *
+ * Schema versioning rides in the same statement: when a provided form_schema
+ * or metadata_schema actually differs from the stored value (IS DISTINCT FROM,
+ * evaluated against the pre-update row), current_schema_version advances and
+ * the post-update schema pair is snapshotted into lt_role_schemas. A no-change
+ * save leaves the version alone and the snapshot INSERT conflicts away.
+ * $22 = optional change summary recorded on the snapshot.
+ *
+ * Upstream inputs ($23 = provided sentinel, $24 = replacement set) sync in the
+ * same statement with replace semantics. The two CTEs deliberately avoid
+ * touching the same row: the DELETE only removes rows leaving the set, and the
+ * INSERT's ON CONFLICT DO NOTHING skips rows that stay (delete+insert of the
+ * SAME key in one statement would silently drop it — CTEs share a snapshot).
  */
 exports.UPDATE_ROLE_METADATA = `
-  UPDATE lt_roles SET
-    title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,
-    description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,
-    form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,
-    metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,
-    properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,
-    ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,
-    parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,
-    sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,
-    target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,
-    worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END
-  WHERE role = $1
-  RETURNING
-    role, title, description, form_schema, metadata_schema, properties,
-    ops_visible, parent_role, sla_minutes, target_per_hour, worker_count`;
+  WITH updated AS (
+    UPDATE lt_roles SET
+      title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,
+      description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,
+      form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,
+      metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,
+      properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,
+      ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,
+      parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,
+      sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,
+      target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,
+      worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END,
+      current_schema_version = CASE
+        WHEN ($6::boolean AND $7::jsonb IS DISTINCT FROM form_schema)
+          OR ($8::boolean AND $9::jsonb IS DISTINCT FROM metadata_schema)
+        THEN COALESCE(current_schema_version, 0) + 1
+        ELSE current_schema_version END
+    WHERE role = $1
+    RETURNING
+      role, title, description, form_schema, metadata_schema, properties,
+      ops_visible, parent_role, sla_minutes, target_per_hour, worker_count,
+      current_schema_version
+  ), snapshot AS (
+    INSERT INTO lt_role_schemas (role, version, form_schema, metadata_schema, change_summary)
+    SELECT role, current_schema_version, form_schema, metadata_schema, $22
+    FROM updated
+    WHERE ($6::boolean OR $8::boolean) AND current_schema_version IS NOT NULL
+    ON CONFLICT (role, version) DO NOTHING
+  ), upstream_prune AS (
+    DELETE FROM lt_role_upstreams
+    WHERE $23::boolean AND role = $1 AND upstream_role <> ALL($24::text[])
+  ), upstream_add AS (
+    INSERT INTO lt_role_upstreams (role, upstream_role)
+    SELECT $1, u FROM unnest($24::text[]) AS u
+    WHERE $23::boolean
+    ON CONFLICT DO NOTHING
+  )
+  SELECT * FROM updated`;
 exports.GET_ROLE_FORM_SCHEMA = `
   SELECT form_schema FROM lt_roles WHERE role = $1`;
 exports.GET_ROLE_METADATA_SCHEMA = `
   SELECT metadata_schema FROM lt_roles WHERE role = $1`;
+exports.GET_ROLE_UPSTREAMS = `
+  SELECT upstream_role FROM lt_role_upstreams WHERE role = $1 ORDER BY upstream_role`;
+// ─── Versioned role schemas ─────────────────────────────────────────────────
+exports.LIST_ROLE_SCHEMA_VERSIONS = `
+  SELECT
+    s.version,
+    s.form_schema IS NOT NULL     AS has_form_schema,
+    s.metadata_schema IS NOT NULL AS has_metadata_schema,
+    s.change_summary,
+    s.created_at,
+    s.version = r.current_schema_version AS is_current
+  FROM lt_role_schemas s
+  JOIN lt_roles r ON r.role = s.role
+  WHERE s.role = $1
+  ORDER BY s.version DESC`;
+exports.GET_ROLE_SCHEMA_VERSION = `
+  SELECT s.role, s.version, s.form_schema, s.metadata_schema, s.change_summary,
+         s.created_at, r.current_schema_version AS latest_version
+  FROM lt_role_schemas s
+  JOIN lt_roles r ON r.role = s.role
+  WHERE s.role = $1 AND s.version = $2`;
+/**
+ * Latest schema resolves from the live lt_roles columns (a role that has never
+ * versioned its schema still answers, with version NULL).
+ */
+exports.GET_ROLE_SCHEMA_CURRENT = `
+  SELECT r.role, r.current_schema_version AS version, r.form_schema,
+         r.metadata_schema, s.change_summary, s.created_at,
+         r.current_schema_version AS latest_version
+  FROM lt_roles r
+  LEFT JOIN lt_role_schemas s
+    ON s.role = r.role AND s.version = r.current_schema_version
+  WHERE r.role = $1`;
 // ─── Role detail aggregation ────────────────────────────────────────────────
 exports.LIST_ROLES_WITH_DETAILS = `
   WITH
@@ -97,6 +166,11 @@ exports.LIST_ROLES_WITH_DETAILS = `
     SELECT role, COUNT(*)::int AS cnt
     FROM lt_config_roles
     GROUP BY role
+  ),
+  upstreams AS (
+    SELECT role, array_agg(upstream_role ORDER BY upstream_role) AS ups
+    FROM lt_role_upstreams
+    GROUP BY role
   )
   SELECT
     r.role,
@@ -110,6 +184,8 @@ exports.LIST_ROLES_WITH_DETAILS = `
     r.sla_minutes,
     r.target_per_hour,
     r.worker_count,
+    r.current_schema_version,
+    COALESCE(up.ups, '{}') AS upstream_roles,
     COALESCE(uc.cnt, 0) AS user_count,
     COALESCE(cc.cnt, 0) AS chain_count,
     COALESCE(wc.cnt, 0) AS workflow_count
@@ -117,6 +193,7 @@ exports.LIST_ROLES_WITH_DETAILS = `
   LEFT JOIN user_counts uc ON uc.role = r.role
   LEFT JOIN chain_counts cc ON cc.role = r.role
   LEFT JOIN workflow_counts wc ON wc.role = r.role
+  LEFT JOIN upstreams up ON up.role = r.role
   ORDER BY r.role`;
 // ─── Reference checks (used before role deletion) ──────────────────────────
 exports.COUNT_USER_ROLE_REFS = `

package/build/services/role/types.d.ts CHANGED Viewed

@@ -25,10 +25,44 @@ export interface RoleDetail {
     target_per_hour: number | null;
     /** Capacity at this station (people or machines). Part of the ops triangle. */
     worker_count: number | null;
+    /**
+     * Version of the live form_schema/metadata_schema pair. Advances whenever a
+     * schema field changes; each version is snapshotted in lt_role_schemas so
+     * escalations can pin the exact schema they were created against. Null until
+     * the role first carries a schema.
+     */
+    current_schema_version: number | null;
+    /**
+     * Roles this station draws input from that live in OTHER sequences.
+     * parent_role is the single "prior step" placing the role in one sequence;
+     * upstream inputs are the remaining graph edges (mixin-like, many allowed),
+     * rendered on the Operations chart as a merge affordance.
+     */
+    upstream_roles: string[];
     user_count: number;
     chain_count: number;
     workflow_count: number;
 }
+/** One immutable snapshot of a role's schema pair. */
+export interface RoleSchemaVersion {
+    role: string;
+    version: number | null;
+    form_schema: Record<string, any> | null;
+    metadata_schema: Record<string, any> | null;
+    change_summary: string | null;
+    created_at: string | null;
+    /** The role's current version, so callers can tell a pinned read from the latest. */
+    latest_version: number | null;
+}
+/** Listing row for the version history (schemas elided; presence flags only). */
+export interface RoleSchemaVersionSummary {
+    version: number;
+    has_form_schema: boolean;
+    has_metadata_schema: boolean;
+    change_summary: string | null;
+    created_at: string;
+    is_current: boolean;
+}
 export interface UpdateRoleInput {
     title?: string | null;
     description?: string | null;
@@ -40,4 +74,11 @@ export interface UpdateRoleInput {
     sla_minutes?: number | null;
     target_per_hour?: number | null;
     worker_count?: number | null;
+    /**
+     * Replace the upstream-input set (omitted = preserve; null or [] = clear).
+     * Every entry must name an existing role other than this one.
+     */
+    upstream_roles?: string[] | null;
+    /** Recorded on the schema snapshot when this update changes a schema field. */
+    change_summary?: string;
 }

package/build/system/mcp-servers/admin/index.js CHANGED Viewed

@@ -56,7 +56,7 @@ const exports_1 = require("./exports");
 const overview_1 = require("./overview");
 const diagnostics_1 = require("./diagnostics");
 const ortho_1 = require("./ortho");
-const TOOL_COUNT = 88;
+const TOOL_COUNT = 90;
 let server = null;
 async function createAdminServer(options) {
     if (server && !options?.fresh)
@@ -72,7 +72,7 @@ async function createAdminServer(options) {
     (0, workflows_1.registerWorkflowTools)(instance); //  3 tools
     (0, mcp_servers_1.registerMcpServerTools)(instance); //  4 tools
     (0, yaml_workflows_1.registerYamlWorkflowTools)(instance); //  5 tools
-    (0, users_1.registerUserTools)(instance); //  8 tools (users + roles)
+    (0, users_1.registerUserTools)(instance); // 10 tools (users + roles + role schemas)
     (0, maintenance_1.registerMaintenanceTools)(instance); //  1 tool
     (0, agents_1.registerAgentTools)(instance); //  5 tools
     (0, agent_subscriptions_1.registerAgentSubscriptionTools)(instance); //  3 tools
@@ -85,7 +85,7 @@ async function createAdminServer(options) {
     (0, overview_1.registerOverviewTools)(instance); //  1 tool
     (0, diagnostics_1.registerDiagnosticsTools)(instance); //  3 tools
     (0, ortho_1.registerOrthoTools)(instance); //  4 tools
-    // Total: 88
+    // Total: 90
     logger_1.loggerRegistry.info(`[lt-mcp:admin] ${name} ready (${TOOL_COUNT} tools registered)`);
     return instance;
 }

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

@@ -562,11 +562,13 @@ export declare const updateRoleSchema: z.ZodObject<{
     sla_minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     target_per_hour: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     worker_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    upstream_roles: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+    change_summary: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     role: string;
+    form_schema?: Record<string, any> | null | undefined;
     description?: string | null | undefined;
     title?: string | null | undefined;
-    form_schema?: Record<string, any> | null | undefined;
     properties?: Record<string, any> | null | undefined;
     metadata_schema?: Record<string, any> | null | undefined;
     ops_visible?: boolean | undefined;
@@ -574,11 +576,13 @@ export declare const updateRoleSchema: z.ZodObject<{
     sla_minutes?: number | null | undefined;
     target_per_hour?: number | null | undefined;
     worker_count?: number | null | undefined;
+    upstream_roles?: string[] | null | undefined;
+    change_summary?: string | undefined;
 }, {
     role: string;
+    form_schema?: Record<string, any> | null | undefined;
     description?: string | null | undefined;
     title?: string | null | undefined;
-    form_schema?: Record<string, any> | null | undefined;
     properties?: Record<string, any> | null | undefined;
     metadata_schema?: Record<string, any> | null | undefined;
     ops_visible?: boolean | undefined;
@@ -586,6 +590,25 @@ export declare const updateRoleSchema: z.ZodObject<{
     sla_minutes?: number | null | undefined;
     target_per_hour?: number | null | undefined;
     worker_count?: number | null | undefined;
+    upstream_roles?: string[] | null | undefined;
+    change_summary?: string | undefined;
+}>;
+export declare const getRoleSchemaSchema: z.ZodObject<{
+    role: z.ZodString;
+    version: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    version?: number | undefined;
+}, {
+    role: string;
+    version?: number | undefined;
+}>;
+export declare const listRoleSchemaVersionsSchema: z.ZodObject<{
+    role: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+}, {
+    role: string;
 }>;
 export declare const pruneSchema: z.ZodObject<{
     app_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.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 = void 0;
+exports.listBotsSchema = exports.deleteAgentSubscriptionSchema = exports.createAgentSubscriptionSchema = exports.listAgentSubscriptionsSchema = exports.deleteAgentSchema = exports.updateAgentSchema = exports.createAgentSchema = exports.getAgentSchema = exports.listAgentsSchema = exports.pruneSchema = 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 = void 0;
 /**
  * Zod schemas for the admin MCP server tools.
  *
@@ -242,6 +242,15 @@ exports.updateRoleSchema = zod_1.z.object({
     sla_minutes: zod_1.z.number().nullable().optional().describe('Target resolution time in minutes. One of the capacity settings: target_per_hour = worker_count / (sla_minutes / 60)'),
     target_per_hour: zod_1.z.number().nullable().optional().describe('Intended throughput (items resolved per hour). Drives the station pace baseline on the Operations view.'),
     worker_count: zod_1.z.number().nullable().optional().describe('Capacity at this station (staff or machine count). One of the capacity settings.'),
+    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.'),
+    change_summary: zod_1.z.string().optional().describe('Recorded on the schema version snapshot when this update changes form_schema or metadata_schema'),
+});
+exports.getRoleSchemaSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Role whose schema to fetch'),
+    version: zod_1.z.number().int().min(1).optional().describe('Version pin — returns that immutable snapshot. Omit for the live (latest) schema.'),
+});
+exports.listRoleSchemaVersionsSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Role whose schema version history to list'),
 });
 // ── maintenance (routes/dba.ts) ─────────────────────────────────────────────
 exports.pruneSchema = zod_1.z.object({

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

@@ -210,6 +210,8 @@ function registerUserTools(server) {
             sla_minutes: args.sla_minutes,
             target_per_hour: args.target_per_hour,
             worker_count: args.worker_count,
+            upstream_roles: args.upstream_roles,
+            change_summary: args.change_summary,
         });
         if (!updated) {
             return {
@@ -221,4 +223,44 @@ function registerUserTools(server) {
             content: [{ type: 'text', text: JSON.stringify(updated) }],
         };
     });
+    // mirrors GET /api/roles/:role/schema
+    server.registerTool('get_role_schema', {
+        title: 'Get Role Schema',
+        description: 'Fetch a role\'s form_schema + metadata_schema pair. Pass version to ' +
+            'read that immutable snapshot from the version history (the version an ' +
+            'escalation pinned via metadata.schema_version); omit it for the live ' +
+            '(latest) schema and its current version number.',
+        inputSchema: schemas_1.getRoleSchemaSchema,
+    }, async (args) => {
+        const schema = await roleService.getRoleSchema(args.role, args.version);
+        if (!schema) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: args.version !== undefined
+                                ? `Schema version ${args.version} not found for role '${args.role}'`
+                                : `Role '${args.role}' not found`,
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(schema) }],
+        };
+    });
+    // mirrors GET /api/roles/:role/schema/versions
+    server.registerTool('list_role_schema_versions', {
+        title: 'List Role Schema Versions',
+        description: 'List a role\'s schema version history, newest first. Each schema edit ' +
+            'creates a new version; escalations may pin one via metadata.schema_version. ' +
+            'Use get_role_schema with a version for the full snapshot.',
+        inputSchema: schemas_1.listRoleSchemaVersionsSchema,
+    }, async (args) => {
+        const versions = await roleService.listRoleSchemaVersions(args.role);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ versions }) }],
+        };
+    });
 }

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

@@ -6,16 +6,19 @@ export declare const escalateSchema: z.ZodObject<{
     type: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     subtype: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     priority: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    schema_version: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     role: 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;
     data?: Record<string, any> | undefined;
     type?: string | undefined;
     priority?: number | undefined;
@@ -70,6 +73,7 @@ export declare const escalateAndWaitSchema: z.ZodObject<{
     type: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     subtype: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     priority: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    schema_version: z.ZodOptional<z.ZodNumber>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
     role: z.ZodString;
     message: z.ZodString;
@@ -79,6 +83,7 @@ export declare const escalateAndWaitSchema: z.ZodObject<{
     type: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     subtype: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     priority: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    schema_version: z.ZodOptional<z.ZodNumber>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
     role: z.ZodString;
     message: z.ZodString;
@@ -88,4 +93,5 @@ export declare const escalateAndWaitSchema: z.ZodObject<{
     type: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     subtype: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     priority: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    schema_version: z.ZodOptional<z.ZodNumber>;
 }, z.ZodTypeAny, "passthrough">>;

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

@@ -11,6 +11,8 @@ exports.escalateSchema = zod_1.z.object({
     subtype: zod_1.z.string().optional().default('tool_call').describe('Escalation subtype'),
     priority: zod_1.z.number().min(1).max(4).optional().default(2)
         .describe('Priority: 1 (highest) to 4 (lowest)'),
+    schema_version: zod_1.z.number().int().min(1).optional()
+        .describe('Pin the role schema version the resolver form renders (defaults to latest)'),
 });
 exports.checkResolutionSchema = zod_1.z.object({
     escalation_id: zod_1.z.string().describe('The escalation ID to check'),
@@ -39,4 +41,6 @@ exports.escalateAndWaitSchema = zod_1.z.object({
     subtype: zod_1.z.string().optional().default('wait_for_human').describe('Escalation subtype'),
     priority: zod_1.z.number().min(1).max(4).optional().default(1)
         .describe('Priority: 1 (highest) to 4 (lowest)'),
+    schema_version: zod_1.z.number().int().min(1).optional()
+        .describe('Pin the role schema version the resolver form renders (defaults to latest; ignored when form_schema is embedded)'),
 }).passthrough();

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

@@ -40,6 +40,7 @@ const crypto = __importStar(require("crypto"));
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const logger_1 = require("../../lib/logger");
 const escalationService = __importStar(require("../../services/escalation"));
+const escalation_1 = require("../../types/escalation");
 const human_queue_schemas_1 = require("./human-queue-schemas");
 let server = null;
 /**
@@ -67,6 +68,10 @@ async function createHumanQueueServer(options) {
         description: 'Create a new escalation for human review. Returns the escalation ID.',
         inputSchema: human_queue_schemas_1.escalateSchema,
     }, async (args) => {
+        const metadata = { source: 'mcp_server' };
+        if (args.schema_version != null) {
+            metadata[escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION] = args.schema_version;
+        }
         const escalation = await escalationService.createEscalation({
             type: args.type || 'mcp',
             subtype: args.subtype || 'tool_call',
@@ -74,7 +79,7 @@ async function createHumanQueueServer(options) {
             priority: args.priority,
             role: args.role,
             envelope: JSON.stringify(args.data || {}),
-            metadata: { source: 'mcp_server' },
+            metadata,
         });
         return {
             content: [{
@@ -230,7 +235,10 @@ async function createHumanQueueServer(options) {
             signal_routing: signalRouting,
         };
         if (args.form_schema) {
-            metadata.form_schema = args.form_schema;
+            metadata[escalation_1.ESCALATION_METADATA_KEYS.FORM_SCHEMA] = args.form_schema;
+        }
+        if (args.schema_version != null) {
+            metadata[escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION] = args.schema_version;
         }
         const escalation = await escalationService.createEscalation({
             type: args.type || 'mcp',