@hotmeshio/long-tail 0.10.8 → 0.10.10

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

@@ -0,0 +1,23 @@
+import type { LTPersonaRelationship, LTWriteScope } from '../../types';
+/**
+ * Canonical relationship values, ordered by allowance (highest first). A
+ * persona grant is always a `member` membership; the relationship selects the
+ * point on the work-surface scope lattice the membership stores.
+ */
+export declare const PERSONA_RELATIONSHIPS: LTPersonaRelationship[];
+/** Normalize an input relationship (canonical or alias) — null if unknown. */
+export declare function normalizeRelationship(value: string): LTPersonaRelationship | null;
+/**
+ * The membership scope a relationship grants. Read is always `all` (an
+ * observer sees the whole pond); write is the axis the relationship selects.
+ */
+export declare function relationshipToWriteScope(relationship: LTPersonaRelationship): LTWriteScope;
+export interface CreatePersonaInput {
+    key: string;
+    title?: string;
+    description?: string;
+}
+export interface UpdatePersonaInput {
+    title?: string | null;
+    description?: string | null;
+}

package/build/services/persona/types.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PERSONA_RELATIONSHIPS = void 0;
+exports.normalizeRelationship = normalizeRelationship;
+exports.relationshipToWriteScope = relationshipToWriteScope;
+/**
+ * Canonical relationship values, ordered by allowance (highest first). A
+ * persona grant is always a `member` membership; the relationship selects the
+ * point on the work-surface scope lattice the membership stores.
+ */
+exports.PERSONA_RELATIONSHIPS = ['write-all', 'write-self', 'read-all'];
+/** Input synonyms accepted at every surface and normalized to canonical values. */
+const RELATIONSHIP_ALIASES = {
+    'write-none': 'read-all',
+};
+/** Normalize an input relationship (canonical or alias) — null if unknown. */
+function normalizeRelationship(value) {
+    if (exports.PERSONA_RELATIONSHIPS.includes(value)) {
+        return value;
+    }
+    return RELATIONSHIP_ALIASES[value] ?? null;
+}
+/**
+ * The membership scope a relationship grants. Read is always `all` (an
+ * observer sees the whole pond); write is the axis the relationship selects.
+ */
+function relationshipToWriteScope(relationship) {
+    switch (relationship) {
+        case 'write-all': return 'all';
+        case 'write-self': return 'self';
+        case 'read-all': return 'none';
+    }
+}

package/build/services/topics/system-topics.d.ts

@@ -1,8 +1,4 @@
 import type { LTTopicConfig } from '../../types';
-/**
- * Seed all 22 built-in system topics into the catalog.
- * Called once at startup after migrations.
- */
 export declare function seedSystemTopics(): Promise<void>;
 /**
  * Seed user-declared topics from startConfig.topics[].

package/build/services/topics/system-topics.js

@@ -12,6 +12,7 @@ const WORKFLOW_CONTEXT_PROPS = {
     originId: { type: 'string', description: 'Root process lineage ID' },
 };
 const STATUS_FIELD = { type: 'string', description: 'Status after this event' };
+const ROLE_FIELD = { type: 'string', description: 'Escalation role (the queue) — also the third subject token' };
 function objectSchema(properties) {
     return { type: 'object', properties };
 }
@@ -83,37 +84,64 @@ const SYSTEM_TOPICS = [
         example_payload: { workflowId: 'wf-abc', workflowName: 'processOrder', status: 'failed' },
         tags: ['lifecycle', 'error'],
     },
-    // Escalation lifecycle
+    // Escalation lifecycle — subjects are `system.escalation.{role}.{id}.{verb}`.
+    // The role token is the organizing level: subscribe to one queue with
+    // `system.escalation.{role}.>`, one verb across queues with
+    // `system.escalation.*.*.{verb}`, or one item with `system.escalation.*.{id}.>`.
     {
-        topic: 'system.escalation.*.created',
+        topic: 'system.escalation.*.*.created',
         description: 'An escalation has been created.',
         category: 'escalation',
-        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
-        example_payload: { escalationId: 'esc-001', status: 'pending', workflowName: 'processOrder' },
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'pending', workflowName: 'processOrder' },
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'system.escalation.*.resolved',
+        topic: 'system.escalation.*.*.resolved',
         description: 'An escalation has been resolved.',
         category: 'escalation',
-        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD, data: { type: 'object' } }),
-        example_payload: { escalationId: 'esc-001', status: 'resolved', workflowName: 'processOrder' },
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'resolved', workflowName: 'processOrder' },
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'system.escalation.*.claimed',
+        topic: 'system.escalation.*.*.claimed',
         description: 'An escalation has been claimed.',
         category: 'escalation',
-        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD }),
-        example_payload: { escalationId: 'esc-001', status: 'claimed' },
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'claimed' },
         tags: ['lifecycle', 'hitl'],
     },
     {
-        topic: 'system.escalation.*.released',
+        topic: 'system.escalation.*.*.released',
         description: 'An escalation has been returned to the queue.',
         category: 'escalation',
-        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, status: STATUS_FIELD }),
-        example_payload: { escalationId: 'esc-001', status: 'pending' },
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'pending' },
+        tags: ['lifecycle', 'hitl'],
+    },
+    {
+        topic: 'system.escalation.*.*.cancelled',
+        description: 'An escalation has been cancelled.',
+        category: 'escalation',
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'cancelled' },
+        tags: ['lifecycle', 'hitl'],
+    },
+    {
+        topic: 'system.escalation.*.*.reassigned',
+        description: 'An escalation has moved to a different role. Publishes under both the departing and arriving role.',
+        category: 'escalation',
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object', description: 'from_role and to_role' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-manager', status: 'pending', data: { from_role: 'order-review', to_role: 'order-manager' } },
+        tags: ['lifecycle', 'hitl'],
+    },
+    {
+        topic: 'system.escalation.*.*.expired',
+        description: 'A waiting escalation hit its SLA timeout and the engine transitioned it.',
+        category: 'escalation',
+        payload_schema: objectSchema({ ...WORKFLOW_CONTEXT_PROPS, escalationId: { type: 'string' }, role: ROLE_FIELD, status: STATUS_FIELD, data: { type: 'object' } }),
+        example_payload: { escalationId: 'esc-001', role: 'order-review', status: 'expired' },
         tags: ['lifecycle', 'hitl'],
     },
     // Activity lifecycle
@@ -247,9 +275,18 @@ function inferCategory(topic) {
     return topic.split('.')[0];
 }
 /**
- * Seed all 22 built-in system topics into the catalog.
+ * Seed the built-in system topics into the catalog.
  * Called once at startup after migrations.
  */
+// Catalog names no longer published. Escalation subjects carry the role token
+// (`system.escalation.{role}.{id}.{verb}`), so the roleless names are retired
+// from the catalog at seed time.
+const RETIRED_TOPICS = [
+    'system.escalation.*.created',
+    'system.escalation.*.resolved',
+    'system.escalation.*.claimed',
+    'system.escalation.*.released',
+];
 async function seedSystemTopics() {
     for (const def of SYSTEM_TOPICS) {
         try {
@@ -268,6 +305,12 @@ async function seedSystemTopics() {
             logger_1.loggerRegistry.warn(`[long-tail] topic seed failed for ${def.topic}: ${err.message}`);
         }
     }
+    for (const retired of RETIRED_TOPICS) {
+        try {
+            await (0, index_1.deleteTopic)(retired);
+        }
+        catch { /* absent on a fresh catalog */ }
+    }
 }
 /**
  * Seed user-declared topics from startConfig.topics[].

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

@@ -1,7 +1,8 @@
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 export declare const ENSURE_ROLE_EXISTS = "INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING";
-/** Fetch roles for a single user, ordered by creation time. */
-export declare const GET_ROLES_BY_USER_ID = "SELECT role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at";
+/** Fetch roles for a single user, ordered by creation time. granted_by_persona
+ *  is the sustaining persona's key (null = direct grant). */
+export declare const GET_ROLES_BY_USER_ID = "SELECT r.role, r.type, r.read_scope, r.write_scope, r.created_at, p.key AS granted_by_persona\n   FROM lt_user_roles r\n   LEFT JOIN lt_personas p ON p.id = r.granted_by_persona\n   WHERE r.user_id = $1 ORDER BY r.created_at";
 /** Fetch a user row by external_id. */
 export declare const GET_USER_BY_EXTERNAL_ID = "SELECT * FROM lt_users WHERE external_id = $1";
 /**
@@ -23,9 +24,11 @@ export declare const VERIFY_USER_BY_ID = "SELECT id FROM lt_users WHERE id = $1
 export declare const GET_USER_WITH_ROLES = "SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,\n          r.role, r.type AS role_type, r.read_scope, r.write_scope\n   FROM lt_users u\n   LEFT JOIN lt_user_roles r ON r.user_id = u.id\n   WHERE u.external_id = $1\n   ORDER BY r.created_at";
 export declare const DELETE_USER_BY_ID = "DELETE FROM lt_users WHERE id = $1";
 /** Batch-load roles for many users (avoids N+1). */
-export declare const GET_ROLES_BY_USER_IDS = "SELECT user_id, role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at";
-/** Upsert a user–role assignment, promoting the type/scope if the row exists. */
-export declare const UPSERT_USER_ROLE = "INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)\n   ON CONFLICT (user_id, role) DO UPDATE SET\n     type = EXCLUDED.type,\n     read_scope = EXCLUDED.read_scope,\n     write_scope = EXCLUDED.write_scope\n   RETURNING role, type, read_scope, write_scope, created_at";
+export declare const GET_ROLES_BY_USER_IDS = "SELECT r.user_id, r.role, r.type, r.read_scope, r.write_scope, r.created_at, p.key AS granted_by_persona\n   FROM lt_user_roles r\n   LEFT JOIN lt_personas p ON p.id = r.granted_by_persona\n   WHERE r.user_id = ANY($1) ORDER BY r.created_at";
+/** Upsert a user–role assignment, promoting the type/scope if the row exists.
+ *  A direct grant takes the row over: granted_by_persona resets to NULL, so a
+ *  later persona unassign can never remove a membership an admin set by hand. */
+export declare const UPSERT_USER_ROLE = "INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)\n   ON CONFLICT (user_id, role) DO UPDATE SET\n     type = EXCLUDED.type,\n     read_scope = EXCLUDED.read_scope,\n     write_scope = EXCLUDED.write_scope,\n     granted_by_persona = NULL\n   RETURNING role, type, read_scope, write_scope, created_at";
 export declare const DELETE_USER_ROLE = "DELETE FROM lt_user_roles WHERE user_id = $1 AND role = $2";
 export declare const HAS_ROLE = "SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1";
 export declare const HAS_ROLE_TYPE = "SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND type = $2 LIMIT 1";

package/build/services/user/sql.js

@@ -4,8 +4,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.IS_GROUP_ADMIN = exports.GET_ROLE_SCOPE = exports.HAS_ROLE_TYPE = exports.HAS_ROLE = exports.DELETE_USER_ROLE = exports.UPSERT_USER_ROLE = exports.GET_ROLES_BY_USER_IDS = exports.DELETE_USER_BY_ID = exports.GET_USER_WITH_ROLES = exports.VERIFY_USER_BY_ID = exports.GET_USER_BY_ID = exports.GET_USER_BY_EMAIL = exports.CREATE_USER_WITH_ROLES = exports.GET_USER_BY_EXTERNAL_ID = exports.GET_ROLES_BY_USER_ID = exports.ENSURE_ROLE_EXISTS = void 0;
 /** Ensure a role name exists in the lt_roles lookup table (FK target). */
 exports.ENSURE_ROLE_EXISTS = 'INSERT INTO lt_roles (role) VALUES ($1) ON CONFLICT DO NOTHING';
-/** Fetch roles for a single user, ordered by creation time. */
-exports.GET_ROLES_BY_USER_ID = 'SELECT role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = $1 ORDER BY created_at';
+/** Fetch roles for a single user, ordered by creation time. granted_by_persona
+ *  is the sustaining persona's key (null = direct grant). */
+exports.GET_ROLES_BY_USER_ID = `SELECT r.role, r.type, r.read_scope, r.write_scope, r.created_at, p.key AS granted_by_persona
+   FROM lt_user_roles r
+   LEFT JOIN lt_personas p ON p.id = r.granted_by_persona
+   WHERE r.user_id = $1 ORDER BY r.created_at`;
 /** Fetch a user row by external_id. */
 exports.GET_USER_BY_EXTERNAL_ID = 'SELECT * FROM lt_users WHERE external_id = $1';
 // ─── User CRUD ───────────────────────────────────────────────────────────────
@@ -48,13 +52,19 @@ exports.GET_USER_WITH_ROLES = `SELECT u.id, u.external_id, u.display_name, u.sta
 exports.DELETE_USER_BY_ID = 'DELETE FROM lt_users WHERE id = $1';
 // ─── Role management ─────────────────────────────────────────────────────────
 /** Batch-load roles for many users (avoids N+1). */
-exports.GET_ROLES_BY_USER_IDS = 'SELECT user_id, role, type, read_scope, write_scope, created_at FROM lt_user_roles WHERE user_id = ANY($1) ORDER BY created_at';
-/** Upsert a user–role assignment, promoting the type/scope if the row exists. */
+exports.GET_ROLES_BY_USER_IDS = `SELECT r.user_id, r.role, r.type, r.read_scope, r.write_scope, r.created_at, p.key AS granted_by_persona
+   FROM lt_user_roles r
+   LEFT JOIN lt_personas p ON p.id = r.granted_by_persona
+   WHERE r.user_id = ANY($1) ORDER BY r.created_at`;
+/** Upsert a user–role assignment, promoting the type/scope if the row exists.
+ *  A direct grant takes the row over: granted_by_persona resets to NULL, so a
+ *  later persona unassign can never remove a membership an admin set by hand. */
 exports.UPSERT_USER_ROLE = `INSERT INTO lt_user_roles (user_id, role, type, read_scope, write_scope) VALUES ($1, $2, $3, $4, $5)
    ON CONFLICT (user_id, role) DO UPDATE SET
      type = EXCLUDED.type,
      read_scope = EXCLUDED.read_scope,
-     write_scope = EXCLUDED.write_scope
+     write_scope = EXCLUDED.write_scope,
+     granted_by_persona = NULL
    RETURNING role, type, read_scope, write_scope, created_at`;
 exports.DELETE_USER_ROLE = 'DELETE FROM lt_user_roles WHERE user_id = $1 AND role = $2';
 exports.HAS_ROLE = 'SELECT 1 FROM lt_user_roles WHERE user_id = $1 AND role = $2 LIMIT 1';

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

@@ -11,6 +11,7 @@
  *   mcp-servers.ts         — routes/mcp.ts
  *   yaml-workflows.ts      — routes/yaml-workflows/
  *   users.ts               — routes/users.ts + routes/roles.ts
+ *   personas.ts            — routes/personas.ts + persona sub-routes on routes/users.ts
  *   maintenance.ts         — routes/dba.ts
  *   agents.ts              — routes/agents.ts
  *   agent-subscriptions.ts — routes/agents.ts (subscription sub-routes)

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

@@ -16,6 +16,7 @@ exports.stopAdminServer = stopAdminServer;
  *   mcp-servers.ts         — routes/mcp.ts
  *   yaml-workflows.ts      — routes/yaml-workflows/
  *   users.ts               — routes/users.ts + routes/roles.ts
+ *   personas.ts            — routes/personas.ts + persona sub-routes on routes/users.ts
  *   maintenance.ts         — routes/dba.ts
  *   agents.ts              — routes/agents.ts
  *   agent-subscriptions.ts — routes/agents.ts (subscription sub-routes)
@@ -44,6 +45,7 @@ const workflows_1 = require("./workflows");
 const mcp_servers_1 = require("./mcp-servers");
 const yaml_workflows_1 = require("./yaml-workflows");
 const users_1 = require("./users");
+const personas_1 = require("./personas");
 const maintenance_1 = require("./maintenance");
 const agents_1 = require("./agents");
 const agent_subscriptions_1 = require("./agent-subscriptions");
@@ -56,7 +58,7 @@ const exports_1 = require("./exports");
 const overview_1 = require("./overview");
 const diagnostics_1 = require("./diagnostics");
 const ortho_1 = require("./ortho");
-const TOOL_COUNT = 90;
+const TOOL_COUNT = 100;
 let server = null;
 async function createAdminServer(options) {
     if (server && !options?.fresh)
@@ -73,6 +75,7 @@ async function createAdminServer(options) {
     (0, mcp_servers_1.registerMcpServerTools)(instance); //  4 tools
     (0, yaml_workflows_1.registerYamlWorkflowTools)(instance); //  5 tools
     (0, users_1.registerUserTools)(instance); // 10 tools (users + roles + role schemas)
+    (0, personas_1.registerPersonaTools)(instance); // 10 tools (persona CRUD + links + assignment)
     (0, maintenance_1.registerMaintenanceTools)(instance); //  1 tool
     (0, agents_1.registerAgentTools)(instance); //  5 tools
     (0, agent_subscriptions_1.registerAgentSubscriptionTools)(instance); //  3 tools
@@ -85,7 +88,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: 90
+    // Total: 100
     logger_1.loggerRegistry.info(`[lt-mcp:admin] ${name} ready (${TOOL_COUNT} tools registered)`);
     return instance;
 }

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

@@ -0,0 +1,8 @@
+/**
+ * Persona management tools — mirrors routes/personas.ts plus the persona
+ * sub-routes on routes/users.ts. A persona is a named bundle of roles with a
+ * per-role relationship scope; assigning one fans out to ordinary scoped role
+ * memberships (lt_user_roles stays the single source of authorization truth).
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPersonaTools(server: McpServer): void;

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

@@ -0,0 +1,186 @@
+"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.registerPersonaTools = registerPersonaTools;
+const personaService = __importStar(require("../../../services/persona"));
+const schemas_1 = require("./schemas");
+const PERSONA_KEY = /^[a-z][a-z0-9_-]*$/;
+function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
+        isError: true,
+    };
+}
+function jsonResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data) }],
+    };
+}
+function registerPersonaTools(server) {
+    // mirrors GET /api/personas
+    server.registerTool('list_personas', {
+        title: 'List Personas',
+        description: 'List all personas — named role bundles with per-role relationship ' +
+            'scope — with their role links and holder counts.',
+        inputSchema: schemas_1.listPersonasSchema,
+    }, async (_args) => {
+        const personas = await personaService.listPersonas();
+        return jsonResult({ personas });
+    });
+    // mirrors GET /api/personas/:key
+    server.registerTool('get_persona', {
+        title: 'Get Persona',
+        description: 'Fetch one persona with its role links and current assignees.',
+        inputSchema: schemas_1.getPersonaSchema,
+    }, async (args) => {
+        const persona = await personaService.getPersona(args.key);
+        if (!persona)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult(persona);
+    });
+    // mirrors POST /api/personas
+    server.registerTool('create_persona', {
+        title: 'Create Persona',
+        description: 'Create a persona. Link roles with link_persona_role, then assign ' +
+            'users with assign_persona.',
+        inputSchema: schemas_1.createPersonaSchema,
+    }, async (args) => {
+        const key = args.key.trim().toLowerCase();
+        if (!PERSONA_KEY.test(key)) {
+            return errorResult('key must start with a letter and contain only lowercase letters, numbers, hyphens, and underscores');
+        }
+        const persona = await personaService.createPersona({
+            key,
+            title: args.title,
+            description: args.description,
+        });
+        return jsonResult(persona);
+    });
+    // mirrors PATCH /api/personas/:key
+    server.registerTool('update_persona', {
+        title: 'Update Persona',
+        description: 'Update a persona\'s title/description with PATCH semantics — omitted fields keep their values; null clears.',
+        inputSchema: schemas_1.updatePersonaSchema,
+    }, async (args) => {
+        const persona = await personaService.updatePersona(args.key, {
+            title: args.title,
+            description: args.description,
+        });
+        if (!persona)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult(persona);
+    });
+    // mirrors DELETE /api/personas/:key
+    server.registerTool('delete_persona', {
+        title: 'Delete Persona',
+        description: 'Delete a persona. Memberships it sustains are removed (or re-homed ' +
+            'to a sibling persona the user still holds); direct grants are never touched.',
+        inputSchema: schemas_1.deletePersonaSchema,
+    }, async (args) => {
+        const result = await personaService.deletePersona(args.key);
+        if (!result.deleted)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult({ deleted: true, recompute: result.recompute });
+    });
+    // mirrors PUT /api/personas/:key/roles/:role
+    server.registerTool('link_persona_role', {
+        title: 'Link Persona Role',
+        description: 'Link a role to a persona (or change the link\'s relationship). Every ' +
+            'current holder\'s memberships are reconciled in the same transaction.',
+        inputSchema: schemas_1.linkPersonaRoleSchema,
+    }, async (args) => {
+        const relationship = personaService.normalizeRelationship(args.relationship);
+        if (!relationship) {
+            return errorResult('relationship must be write-all, write-self, or read-all (write-none is accepted as read-all)');
+        }
+        const result = await personaService.linkPersonaRole(args.key, args.role.trim().toLowerCase(), relationship);
+        if (!result)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult(result);
+    });
+    // mirrors DELETE /api/personas/:key/roles/:role
+    server.registerTool('unlink_persona_role', {
+        title: 'Unlink Persona Role',
+        description: 'Remove a role link from a persona and reconcile every holder\'s memberships.',
+        inputSchema: schemas_1.unlinkPersonaRoleSchema,
+    }, async (args) => {
+        const result = await personaService.unlinkPersonaRole(args.key, args.role);
+        if (!result.personaFound)
+            return errorResult(`Persona '${args.key}' not found`);
+        if (!result.unlinked)
+            return errorResult(`Persona '${args.key}' does not link role '${args.role}'`);
+        return jsonResult({ unlinked: true, recompute: result.recompute });
+    });
+    // mirrors POST /api/users/:id/personas
+    server.registerTool('assign_persona', {
+        title: 'Assign Persona',
+        description: 'Assign a persona to a user — shorthand for adding the user to each ' +
+            'linked role at the linked scope. Idempotent: re-assigning overlays ' +
+            'fresh from the persona\'s current links. Highest allowance wins when ' +
+            'bundles overlap; direct grants are only ever raised, never lowered.',
+        inputSchema: schemas_1.assignPersonaSchema,
+    }, async (args) => {
+        const recompute = await personaService.assignPersona(args.user_id, args.key);
+        if (!recompute)
+            return errorResult(`Persona '${args.key}' not found`);
+        return jsonResult({ assigned: true, recompute });
+    });
+    // mirrors DELETE /api/users/:id/personas/:key
+    server.registerTool('unassign_persona', {
+        title: 'Unassign Persona',
+        description: 'Unassign a persona from a user. Removes only memberships the persona ' +
+            'sustains — rows another held persona still grants are re-homed to it, ' +
+            'and direct grants are never touched.',
+        inputSchema: schemas_1.unassignPersonaSchema,
+    }, async (args) => {
+        const result = await personaService.unassignPersona(args.user_id, args.key);
+        if (!result.personaFound)
+            return errorResult(`Persona '${args.key}' not found`);
+        if (!result.unassigned)
+            return errorResult(`User does not hold persona '${args.key}'`);
+        return jsonResult({ unassigned: true, recompute: result.recompute });
+    });
+    // mirrors GET /api/users/:id/personas
+    server.registerTool('get_user_personas', {
+        title: 'Get User Personas',
+        description: 'The personas a user holds plus the composed role/scope map their ' +
+            'memberships form (each row names the sustaining persona, or null for ' +
+            'a direct grant).',
+        inputSchema: schemas_1.getUserPersonasSchema,
+    }, async (args) => {
+        const result = await personaService.getUserPersonas(args.user_id);
+        return jsonResult(result);
+    });
+}

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

@@ -648,6 +648,97 @@ export declare const listRoleSchemaVersionsSchema: z.ZodObject<{
 }, {
     role: string;
 }>;
+export declare const listPersonasSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare const getPersonaSchema: z.ZodObject<{
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+}, {
+    key: string;
+}>;
+export declare const createPersonaSchema: z.ZodObject<{
+    key: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    description?: string | undefined;
+    title?: string | undefined;
+}, {
+    key: string;
+    description?: string | undefined;
+    title?: string | undefined;
+}>;
+export declare const updatePersonaSchema: z.ZodObject<{
+    key: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    description?: string | null | undefined;
+    title?: string | null | undefined;
+}, {
+    key: string;
+    description?: string | null | undefined;
+    title?: string | null | undefined;
+}>;
+export declare const deletePersonaSchema: z.ZodObject<{
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+}, {
+    key: string;
+}>;
+export declare const linkPersonaRoleSchema: z.ZodObject<{
+    key: z.ZodString;
+    role: z.ZodString;
+    relationship: z.ZodEnum<["write-all", "write-self", "read-all", "write-none"]>;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    key: string;
+    relationship: "write-all" | "write-self" | "read-all" | "write-none";
+}, {
+    role: string;
+    key: string;
+    relationship: "write-all" | "write-self" | "read-all" | "write-none";
+}>;
+export declare const unlinkPersonaRoleSchema: z.ZodObject<{
+    key: z.ZodString;
+    role: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    key: string;
+}, {
+    role: string;
+    key: string;
+}>;
+export declare const assignPersonaSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    user_id: string;
+}, {
+    key: string;
+    user_id: string;
+}>;
+export declare const unassignPersonaSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    key: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    key: string;
+    user_id: string;
+}, {
+    key: string;
+    user_id: string;
+}>;
+export declare const getUserPersonasSchema: z.ZodObject<{
+    user_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    user_id: string;
+}, {
+    user_id: string;
+}>;
 export declare const pruneSchema: z.ZodObject<{
     app_id: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     expire: z.ZodDefault<z.ZodOptional<z.ZodString>>;