@hotmeshio/long-tail 0.6.0 → 0.7.0

package/build/services/role/index.js

@@ -9,6 +9,9 @@ exports.canEscalateTo = canEscalateTo;
 exports.listDistinctRoles = listDistinctRoles;
 exports.listRolesWithDetails = listRolesWithDetails;
 exports.createRole = createRole;
+exports.updateRoleMetadata = updateRoleMetadata;
+exports.getRoleFormSchema = getRoleFormSchema;
+exports.getRoleMetadataSchema = getRoleMetadataSchema;
 exports.deleteRole = deleteRole;
 const db_1 = require("../../lib/db");
 const user_1 = require("../user");
@@ -103,11 +106,56 @@ async function listRolesWithDetails() {
     return rows;
 }
 /**
- * Create a standalone role entry.
+ * Create a standalone role entry. Returns true when the role was created by
+ * this call, false when it already existed — seeders use this to write
+ * default metadata exactly once and leave later admin edits alone.
  */
 async function createRole(role) {
     const pool = (0, db_1.getPool)();
-    await pool.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
+    const { rowCount } = await pool.query(sql_1.ENSURE_ROLE_EXISTS, [role]);
+    return (rowCount ?? 0) > 0;
+}
+/**
+ * Update role metadata with PATCH semantics: a field omitted from the input
+ * (undefined) keeps its current value; explicit null clears it (properties
+ * resets to {}). One atomic UPDATE — see UPDATE_ROLE_METADATA.
+ */
+async function updateRoleMetadata(role, input) {
+    const pool = (0, db_1.getPool)();
+    const provided = (key) => input[key] !== undefined;
+    const { rows } = await pool.query(sql_1.UPDATE_ROLE_METADATA, [
+        role,
+        provided('title'), input.title ?? null,
+        provided('description'), input.description ?? null,
+        provided('form_schema'), input.form_schema != null ? JSON.stringify(input.form_schema) : null,
+        provided('metadata_schema'), input.metadata_schema != null ? JSON.stringify(input.metadata_schema) : null,
+        provided('properties'), input.properties != null ? JSON.stringify(input.properties) : null,
+        provided('ops_visible'), input.ops_visible ?? null,
+        provided('parent_role'), input.parent_role ?? null,
+        provided('sla_minutes'), input.sla_minutes ?? null,
+        provided('target_per_hour'), input.target_per_hour ?? null,
+        provided('worker_count'), input.worker_count ?? null,
+    ]);
+    return rows[0] ?? null;
+}
+/**
+ * Fetch form_schema for a role (used as default escalation form when workflow
+ * config does not specify a resolver_schema).
+ */
+async function getRoleFormSchema(role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLE_FORM_SCHEMA, [role]);
+    return rows[0]?.form_schema ?? null;
+}
+/**
+ * Fetch metadata_schema for a role. Used at escalation creation time to
+ * validate the caller-supplied metadata bag, and by the faceted-query UI
+ * to surface expected keys before any data exists.
+ */
+async function getRoleMetadataSchema(role) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(sql_1.GET_ROLE_METADATA_SCHEMA, [role]);
+    return rows[0]?.metadata_schema ?? null;
 }
 /**
  * Delete a role. Returns an error message if the role is referenced.

package/build/services/role/sql.d.ts

@@ -15,7 +15,17 @@ export declare const CHECK_ESCALATION_CHAIN_EXISTS = "\n  SELECT 1\n  FROM lt_co
 export declare const ENSURE_ROLE_EXISTS = "\n  INSERT INTO lt_roles (role) VALUES ($1)\n  ON CONFLICT DO NOTHING";
 export declare const LIST_ROLES = "\n  SELECT role FROM lt_roles ORDER BY role";
 export declare const DELETE_ROLE = "\n  DELETE FROM lt_roles WHERE role = $1";
-export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  ORDER BY r.role";
+/**
+ * PATCH semantics in ONE atomic statement: each column has a boolean
+ * "provided" sentinel — when false the column keeps its current value, when
+ * 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.
+ */
+export declare const UPDATE_ROLE_METADATA = "\n  UPDATE lt_roles SET\n    title           = CASE WHEN $2::boolean  THEN $3                                ELSE title           END,\n    description     = CASE WHEN $4::boolean  THEN $5                                ELSE description     END,\n    form_schema     = CASE WHEN $6::boolean  THEN $7::jsonb                         ELSE form_schema     END,\n    metadata_schema = CASE WHEN $8::boolean  THEN $9::jsonb                         ELSE metadata_schema END,\n    properties      = CASE WHEN $10::boolean THEN COALESCE($11::jsonb, '{}'::jsonb) ELSE properties      END,\n    ops_visible     = CASE WHEN $12::boolean THEN $13::boolean                      ELSE ops_visible     END,\n    parent_role     = CASE WHEN $14::boolean THEN $15                               ELSE parent_role     END,\n    sla_minutes     = CASE WHEN $16::boolean THEN $17::numeric                      ELSE sla_minutes     END,\n    target_per_hour = CASE WHEN $18::boolean THEN $19::numeric                      ELSE target_per_hour END,\n    worker_count    = CASE WHEN $20::boolean THEN $21::int                          ELSE worker_count    END\n  WHERE role = $1\n  RETURNING\n    role, title, description, form_schema, metadata_schema, properties,\n    ops_visible, parent_role, sla_minutes, target_per_hour, worker_count";
+export declare const GET_ROLE_FORM_SCHEMA = "\n  SELECT form_schema FROM lt_roles WHERE role = $1";
+export declare const GET_ROLE_METADATA_SCHEMA = "\n  SELECT metadata_schema FROM lt_roles WHERE role = $1";
+export declare const LIST_ROLES_WITH_DETAILS = "\n  WITH\n  user_counts AS (\n    SELECT role, COUNT(DISTINCT user_id)::int AS cnt\n    FROM lt_user_roles\n    GROUP BY role\n  ),\n  chain_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM (\n      SELECT source_role AS role FROM lt_config_role_escalations\n      UNION ALL\n      SELECT target_role AS role FROM lt_config_role_escalations\n    ) c\n    GROUP BY role\n  ),\n  workflow_counts AS (\n    SELECT role, COUNT(*)::int AS cnt\n    FROM lt_config_roles\n    GROUP BY role\n  )\n  SELECT\n    r.role,\n    r.title,\n    r.description,\n    r.form_schema,\n    r.metadata_schema,\n    r.properties,\n    r.ops_visible,\n    r.parent_role,\n    r.sla_minutes,\n    r.target_per_hour,\n    r.worker_count,\n    COALESCE(uc.cnt, 0) AS user_count,\n    COALESCE(cc.cnt, 0) AS chain_count,\n    COALESCE(wc.cnt, 0) AS workflow_count\n  FROM lt_roles r\n  LEFT JOIN user_counts uc ON uc.role = r.role\n  LEFT JOIN chain_counts cc ON cc.role = r.role\n  LEFT JOIN workflow_counts wc ON wc.role = r.role\n  ORDER BY r.role";
 export declare const COUNT_USER_ROLE_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_user_roles WHERE role = $1";
 export declare const COUNT_CHAIN_REFS = "\n  SELECT COUNT(*)::int AS cnt\n  FROM lt_config_role_escalations\n  WHERE source_role = $1 OR target_role = $1";
 export declare const COUNT_WORKFLOW_REFS = "\n  SELECT COUNT(*)::int AS cnt FROM lt_config_roles WHERE role = $1";

package/build/services/role/sql.js

@@ -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.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_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
@@ -49,6 +49,33 @@ exports.LIST_ROLES = `
   SELECT role FROM lt_roles ORDER BY role`;
 exports.DELETE_ROLE = `
   DELETE FROM lt_roles WHERE role = $1`;
+/**
+ * PATCH semantics in ONE atomic statement: each column has a boolean
+ * "provided" sentinel — when false the column keeps its current value, when
+ * 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.
+ */
+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`;
+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`;
 // ─── Role detail aggregation ────────────────────────────────────────────────
 exports.LIST_ROLES_WITH_DETAILS = `
   WITH
@@ -73,6 +100,16 @@ exports.LIST_ROLES_WITH_DETAILS = `
   )
   SELECT
     r.role,
+    r.title,
+    r.description,
+    r.form_schema,
+    r.metadata_schema,
+    r.properties,
+    r.ops_visible,
+    r.parent_role,
+    r.sla_minutes,
+    r.target_per_hour,
+    r.worker_count,
     COALESCE(uc.cnt, 0) AS user_count,
     COALESCE(cc.cnt, 0) AS chain_count,
     COALESCE(wc.cnt, 0) AS workflow_count

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

@@ -5,7 +5,39 @@ export interface EscalationChain {
 }
 export interface RoleDetail {
     role: string;
+    title: string | null;
+    description: string | null;
+    /** JSON Schema for the escalation resolve form. Overridden per-workflow by resolver_schema. */
+    form_schema: Record<string, any> | null;
+    /**
+     * JSON Schema declaring the expected shape of lt_escalations.metadata for
+     * escalations created under this role. Drives faceted-query key autocomplete
+     * and creation-time metadata validation.
+     */
+    metadata_schema: Record<string, any> | null;
+    /** Free-form user-owned bag. No reserved keys — use for icons, colors, tags, etc. */
+    properties: Record<string, any>;
+    ops_visible: boolean;
+    parent_role: string | null;
+    /** Target resolution time (minutes). Part of the ops triangle. */
+    sla_minutes: number | null;
+    /** Intended throughput (items per hour). Part of the ops triangle. */
+    target_per_hour: number | null;
+    /** Capacity at this station (people or machines). Part of the ops triangle. */
+    worker_count: number | null;
     user_count: number;
     chain_count: number;
     workflow_count: number;
 }
+export interface UpdateRoleInput {
+    title?: string | null;
+    description?: string | null;
+    form_schema?: Record<string, any> | null;
+    metadata_schema?: Record<string, any> | null;
+    properties?: Record<string, any> | null;
+    ops_visible?: boolean;
+    parent_role?: string | null;
+    sla_minutes?: number | null;
+    target_per_hour?: number | null;
+    worker_count?: number | null;
+}

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

@@ -78,13 +78,14 @@ function registerEscalationTools(server) {
     server.registerTool('find_escalations', {
         title: 'Find Escalations',
         description: 'Search escalations with optional filters (status, role, type, subtype, ' +
-            'assigned_to, priority), free-text `search`, and sorting. `search` matches ' +
-            'across description, type/subtype, role, workflow/origin id, and metadata values ' +
-            '(e.g. a correlation key like an order id) server-side over the full result set. ' +
-            'Also supports FACETED metadata query — `facets` (metadata @> containment), `block` ' +
-            '(exclusion), `range` (numeric), `exists` (key present), `roles`, `available`, and ' +
-            '`orderBy` (incl. metadata.<key>) — all role-scoped and run in SQL. ' +
-            'Returns full records including metadata, workflow linkage, assignment, and signal_key.',
+            'assigned_to, priority), correlation-id `search`, and sorting. `search` is an ' +
+            'exact-match lookup by escalation id, workflow id, or origin id (order/ticket) — ' +
+            'index-served over the full result set. To match a value INSIDE metadata ' +
+            '(e.g. an order id), use the FACETED metadata query — `facets` (metadata @> containment), ' +
+            '`block` (exclusion), `range` (numeric), `exists` (key present), `roles`, `available`, and ' +
+            '`orderBy` (incl. metadata.<key>) — all role-scoped, GIN-served, and status-agnostic ' +
+            '(no status filter required). Returns full records including metadata, workflow linkage, ' +
+            'assignment, and signal_key.',
         inputSchema: schemas_1.findEscalationsSchema,
     }, async (args) => {
         const result = await escalationApi.listEscalations({

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

@@ -55,7 +55,8 @@ const settings_1 = require("./settings");
 const exports_1 = require("./exports");
 const overview_1 = require("./overview");
 const diagnostics_1 = require("./diagnostics");
-const TOOL_COUNT = 83;
+const ortho_1 = require("./ortho");
+const TOOL_COUNT = 88;
 let server = null;
 async function createAdminServer(options) {
     if (server && !options?.fresh)
@@ -71,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); //  7 tools (users + roles)
+    (0, users_1.registerUserTools)(instance); //  8 tools (users + roles)
     (0, maintenance_1.registerMaintenanceTools)(instance); //  1 tool
     (0, agents_1.registerAgentTools)(instance); //  5 tools
     (0, agent_subscriptions_1.registerAgentSubscriptionTools)(instance); //  3 tools
@@ -83,7 +84,8 @@ async function createAdminServer(options) {
     (0, exports_1.registerExportTools)(instance); //  4 tools
     (0, overview_1.registerOverviewTools)(instance); //  1 tool
     (0, diagnostics_1.registerDiagnosticsTools)(instance); //  3 tools
-    // Total: 83
+    (0, ortho_1.registerOrthoTools)(instance); //  4 tools
+    // Total: 88
     logger_1.loggerRegistry.info(`[lt-mcp:admin] ${name} ready (${TOOL_COUNT} tools registered)`);
     return instance;
 }

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

@@ -0,0 +1,10 @@
+/**
+ * Ortho pipeline MCP tools — AI-operable interface for the 8-stage manufacturing workflow.
+ *
+ * ortho_submit          — start a new order through the orthoPipeline workflow
+ * ortho_pending         — list open stage escalations waiting for completion
+ * ortho_complete_stage  — claim and resolve one stage escalation (advances the pipeline)
+ * ortho_status          — get the current status and results for an order workflow
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerOrthoTools(server: McpServer): void;

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

@@ -0,0 +1,242 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerOrthoTools = registerOrthoTools;
+const zod_1 = require("zod");
+const workflow_invocation_1 = require("../../../services/workflow-invocation");
+const escalationApi = __importStar(require("../../../api/escalations"));
+const workflowApi = __importStar(require("../../../api/workflows"));
+const iam_1 = require("../../../services/iam");
+const types_1 = require("../../../examples/workflows/ortho-pipeline/types");
+let systemPrincipalId = null;
+async function systemAuth() {
+    if (!systemPrincipalId)
+        systemPrincipalId = await (0, iam_1.ensureSystemBot)();
+    return { userId: systemPrincipalId, role: 'superadmin' };
+}
+// ── Schemas ──────────────────────────────────────────────────────────────────
+const orthoSubmitSchema = zod_1.z.object({
+    order_id: zod_1.z.string().describe('Unique order identifier (e.g. "ORD-001")'),
+    item_type: zod_1.z.string().describe('Item type (e.g. "insole-standard", "insole-diabetic")'),
+    stages: zod_1.z.array(zod_1.z.string()).optional().describe('Override stage sequence (default: all 8 stages)'),
+    metadata: zod_1.z.record(zod_1.z.unknown()).optional().describe('Additional order metadata passed through to each stage'),
+});
+const orthoPendingSchema = zod_1.z.object({
+    stage: zod_1.z.string().optional().describe('Filter to a specific stage (e.g. "design"). Omit for all stages.'),
+    limit: zod_1.z.number().int().optional().default(50).describe('Max results'),
+});
+const orthoCompleteStageSchema = zod_1.z.object({
+    escalation_id: zod_1.z.string().describe('Escalation ID returned by ortho_pending'),
+    notes: zod_1.z.string().describe('Completion notes — what was done, any decisions made'),
+    outcome: zod_1.z.record(zod_1.z.unknown()).optional().describe('Structured outcome data specific to this stage'),
+});
+const orthoStatusSchema = zod_1.z.object({
+    workflow_id: zod_1.z.string().describe('Workflow ID returned by ortho_submit'),
+});
+// ── Tool registration ────────────────────────────────────────────────────────
+function registerOrthoTools(server) {
+    // Submit a new order through the ortho manufacturing pipeline
+    server.registerTool('ortho_submit', {
+        title: 'Submit Ortho Order',
+        description: 'Start a new orthotic manufacturing order through the 8-stage pipeline ' +
+            '(design → review → print → grind → glue → finish → qa → ship). ' +
+            'Returns a workflow_id used to track progress. Each stage creates a pending ' +
+            'escalation that must be completed via ortho_complete_stage before the next stage begins.',
+        inputSchema: orthoSubmitSchema,
+    }, async (args) => {
+        const auth = await systemAuth();
+        const result = await (0, workflow_invocation_1.invokeWorkflow)({
+            workflowType: types_1.ORTHO_PIPELINE_WORKFLOW,
+            data: {
+                order_id: args.order_id,
+                item_type: args.item_type,
+                ...(args.stages ? { stages: args.stages } : {}),
+                ...(args.metadata ? { metadata: args.metadata } : {}),
+            },
+            auth,
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        workflow_id: result.workflowId,
+                        order_id: args.order_id,
+                        item_type: args.item_type,
+                        stages: args.stages ?? [...types_1.ORTHO_STAGES],
+                        message: 'Pipeline started — first stage escalation will appear momentarily',
+                    }),
+                }],
+        };
+    });
+    // List pending stage escalations, optionally filtered by stage
+    server.registerTool('ortho_pending', {
+        title: 'List Pending Ortho Stages',
+        description: 'List open ortho-pipeline escalations waiting to be completed. ' +
+            'Each entry represents one manufacturing stage blocked on human or AI review. ' +
+            'Filter by stage name to focus on one step. Use ortho_complete_stage to advance.',
+        inputSchema: orthoPendingSchema,
+    }, async (args) => {
+        const auth = await systemAuth();
+        const result = await escalationApi.listEscalations({
+            status: 'pending',
+            type: types_1.ORTHO_STAGE_TYPE,
+            ...(args.stage ? { subtype: args.stage } : {}),
+            limit: args.limit ?? 50,
+            sort_by: 'created_at',
+            order: 'asc',
+        }, auth);
+        if (result.status !== 200 || !result.data) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: result.error ?? 'Failed to list escalations' }),
+                    }],
+            };
+        }
+        const escalations = (result.data.escalations ?? []).map((e) => ({
+            id: e.id,
+            stage: e.subtype,
+            order_id: e.metadata?.order_id,
+            item_type: e.metadata?.item_type,
+            description: e.description,
+            created_at: e.created_at,
+            signal_key: e.signal_key,
+            workflow_id: e.workflow_id,
+        }));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({ count: escalations.length, escalations }),
+                }],
+        };
+    });
+    // Claim and resolve one stage escalation (advances to the next stage)
+    server.registerTool('ortho_complete_stage', {
+        title: 'Complete Ortho Stage',
+        description: 'Complete a pending ortho pipeline stage. Claims the escalation as the system ' +
+            'operator and resolves it with your notes and outcome data. Resolving automatically ' +
+            'signals the workflow to advance to the next stage — a new escalation will appear ' +
+            'for the subsequent step within seconds.',
+        inputSchema: orthoCompleteStageSchema,
+    }, async (args) => {
+        const auth = await systemAuth();
+        // Contract guard: this tool advances pipeline stage gates only. The
+        // general-purpose resolve_escalation tool covers every other type.
+        const detail = await escalationApi.getEscalation({ id: args.escalation_id }, auth);
+        if (detail.status !== 200 || detail.data?.type !== types_1.ORTHO_STAGE_TYPE) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Escalation ${args.escalation_id} is ${detail.status !== 200 ? 'unknown' : `type "${detail.data?.type}"`} — ortho_complete_stage resolves ${types_1.ORTHO_STAGE_TYPE} gates. Use resolve_escalation for other types.`,
+                        }),
+                    }],
+            };
+        }
+        // Claim first (idempotent if already claimed by us)
+        const claimResult = await escalationApi.claimEscalation({ id: args.escalation_id, durationMinutes: 60 }, auth);
+        if (claimResult.status !== 200) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: `Claim failed: ${claimResult.error}` }),
+                    }],
+            };
+        }
+        // Resolve with stage output. completed_at is stamped here — the durable
+        // workflow reads it from the signal payload (replay-deterministic).
+        const resolveResult = await escalationApi.resolveEscalation({
+            id: args.escalation_id,
+            resolverPayload: {
+                notes: args.notes,
+                completed_at: new Date().toISOString(),
+                ...(args.outcome ? { outcome: args.outcome } : {}),
+            },
+        }, auth);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        resolved: resolveResult.status === 200,
+                        escalation_id: args.escalation_id,
+                        status: resolveResult.status,
+                        error: resolveResult.status !== 200 ? resolveResult.error : undefined,
+                        message: resolveResult.status === 200
+                            ? 'Stage resolved — next stage escalation will appear shortly'
+                            : undefined,
+                    }),
+                }],
+        };
+    });
+    // Get the current status and accumulated results for a pipeline run
+    server.registerTool('ortho_status', {
+        title: 'Get Ortho Pipeline Status',
+        description: 'Get the current status and completed stage results for an ortho pipeline workflow. ' +
+            'Returns "running" while stages are in progress, "complete" with the full stage ' +
+            'result history when all stages are done.',
+        inputSchema: orthoStatusSchema,
+    }, async (args) => {
+        const statusResult = await workflowApi.getWorkflowStatus({ workflowId: args.workflow_id });
+        if (statusResult.status === 404) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Workflow not found', workflow_id: args.workflow_id }),
+                    }],
+            };
+        }
+        // status=0 means complete in HotMesh
+        const isComplete = statusResult.data?.status === 0;
+        if (!isComplete) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ workflow_id: args.workflow_id, status: 'running' }),
+                    }],
+            };
+        }
+        const resultData = await workflowApi.getWorkflowResult({ workflowId: args.workflow_id });
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        workflow_id: args.workflow_id,
+                        status: 'complete',
+                        result: resultData.data?.result ?? null,
+                    }),
+                }],
+        };
+    });
+}

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

@@ -40,7 +40,7 @@ export declare const getProcessDetailSchema: z.ZodObject<{
     origin_id: string;
 }>;
 export declare const findEscalationsSchema: z.ZodObject<{
-    status: z.ZodOptional<z.ZodEnum<["pending", "resolved", "cancelled"]>>;
+    status: z.ZodOptional<z.ZodEnum<["pending", "resolved", "cancelled", "expired"]>>;
     role: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodString>;
     subtype: z.ZodOptional<z.ZodString>;
@@ -86,7 +86,7 @@ export declare const findEscalationsSchema: z.ZodObject<{
     limit: number;
     offset: number;
     role?: string | undefined;
-    status?: "pending" | "cancelled" | "resolved" | undefined;
+    status?: "pending" | "cancelled" | "resolved" | "expired" | undefined;
     roles?: string[] | undefined;
     type?: string | undefined;
     search?: string | undefined;
@@ -111,7 +111,7 @@ export declare const findEscalationsSchema: z.ZodObject<{
     exists?: string[] | undefined;
 }, {
     role?: string | undefined;
-    status?: "pending" | "cancelled" | "resolved" | undefined;
+    status?: "pending" | "cancelled" | "resolved" | "expired" | undefined;
     roles?: string[] | undefined;
     type?: string | undefined;
     search?: string | undefined;
@@ -550,6 +550,43 @@ export declare const addEscalationChainSchema: z.ZodObject<{
     source_role: string;
     target_role: string;
 }>;
+export declare const updateRoleSchema: z.ZodObject<{
+    role: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    form_schema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
+    metadata_schema: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
+    properties: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodAny>>>;
+    ops_visible: z.ZodOptional<z.ZodBoolean>;
+    parent_role: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    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>>;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    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;
+    parent_role?: string | null | undefined;
+    sla_minutes?: number | null | undefined;
+    target_per_hour?: number | null | undefined;
+    worker_count?: number | null | undefined;
+}, {
+    role: string;
+    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;
+    parent_role?: string | null | undefined;
+    sla_minutes?: number | null | undefined;
+    target_per_hour?: number | null | undefined;
+    worker_count?: number | null | undefined;
+}>;
 export declare const pruneSchema: z.ZodObject<{
     app_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     expire: z.ZodDefault<z.ZodOptional<z.ZodString>>;

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.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;
+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;
 /**
  * Zod schemas for the admin MCP server tools.
  *
@@ -28,12 +28,12 @@ exports.getProcessDetailSchema = zod_1.z.object({
 });
 // ── escalations (routes/escalations/) ───────────────────────────────────────
 exports.findEscalationsSchema = zod_1.z.object({
-    status: zod_1.z.enum(['pending', 'resolved', 'cancelled']).optional().describe('Filter by status'),
+    status: zod_1.z.enum(['pending', 'resolved', 'cancelled', 'expired']).optional().describe('Filter by status'),
     role: zod_1.z.string().optional().describe('Filter by target role'),
     type: zod_1.z.string().optional().describe('Filter by escalation type'),
     subtype: zod_1.z.string().optional().describe('Filter by escalation subtype'),
     assigned_to: zod_1.z.string().optional().describe('Filter by assigned user UUID (active claim holder)'),
-    search: zod_1.z.string().optional().describe('Free-text search across description, type/subtype, role, workflow/origin id, and metadata values (e.g. a correlation key like an order id). Server-side over the full result set.'),
+    search: zod_1.z.string().optional().describe('Exact-match lookup by correlation id — the escalation id, its workflow id, or origin id (order/ticket). Index-served, server-side over the full result set. To match a value INSIDE metadata (e.g. an order id), use `facets` instead.'),
     priority: zod_1.z.number().int().min(1).max(4).optional().describe('Filter by priority (1=critical, 4=low)'),
     sort_by: zod_1.z.enum(['created_at', 'priority', 'updated_at']).optional().describe('Sort column (default: priority asc, then created_at asc)'),
     order: zod_1.z.enum(['asc', 'desc']).optional().describe('Sort direction for sort_by'),
@@ -230,6 +230,19 @@ exports.addEscalationChainSchema = zod_1.z.object({
     source_role: zod_1.z.string().describe('Originating role'),
     target_role: zod_1.z.string().describe('Destination role for escalation'),
 });
+exports.updateRoleSchema = zod_1.z.object({
+    role: zod_1.z.string().describe('Role key to update'),
+    title: zod_1.z.string().nullable().optional().describe('Display name shown on role cards and station views'),
+    description: zod_1.z.string().nullable().optional().describe('Short description of this role\'s purpose'),
+    form_schema: zod_1.z.record(zod_1.z.any()).nullable().optional().describe('JSON Schema for the escalation resolve form (overridden by workflow-level resolver_schema)'),
+    metadata_schema: zod_1.z.record(zod_1.z.any()).nullable().optional().describe('JSON Schema declaring the expected shape of lt_escalations.metadata for this role. Drives creation-time validation and faceted-query key autocomplete.'),
+    properties: zod_1.z.record(zod_1.z.any()).nullable().optional().describe('Free user-owned bag (icon, color, tags, etc.). No reserved keys — use the typed columns below for operational values.'),
+    ops_visible: zod_1.z.boolean().optional().describe('When true, role appears as a station on the /operations view'),
+    parent_role: zod_1.z.string().nullable().optional().describe('Parent role in the process dependency graph (nullable; roots have no parent)'),
+    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.'),
+});
 // ── maintenance (routes/dba.ts) ─────────────────────────────────────────────
 exports.pruneSchema = zod_1.z.object({
     app_id: zod_1.z.string().optional().default('durable').describe('HotMesh application namespace (default: durable)'),