@hotmeshio/long-tail 0.11.1 → 0.12.0

package/build/system/mcp-servers/admin/domain-context.js

@@ -0,0 +1,220 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDomainContextTools = registerDomainContextTools;
+const domain_1 = require("../../../services/domain");
+const role_1 = require("../../../services/role");
+const types_1 = require("../../../services/role/types");
+const config_1 = require("../../../services/config");
+const queries_1 = require("../../../services/escalation/queries");
+const schemas_1 = require("./schemas");
+const REGISTER_HINT = 'An admin can register a dictionary via startConfig.mcp.domainDictionaryPath or PUT /api/domain.';
+const norm = (s) => s.trim().toLowerCase();
+/** True when the term (or any alias) matches the lookup name. */
+function termMatches(term, name) {
+    const n = norm(name);
+    if (norm(term.term) === n)
+        return true;
+    return (term.aliases ?? []).some((a) => norm(a) === n);
+}
+/** Role names a term references (for live joins). */
+function rolesOf(term) {
+    const out = [];
+    if (term.maps_to?.role)
+        out.push(term.maps_to.role);
+    if (term.maps_to?.roles)
+        out.push(...term.maps_to.roles);
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Registry-derived fallback — the ontology FLOOR. The live registries already
+// self-describe the structure: roles (title/description/entity_facet + verb
+// semantics from properties), workflow configs, and in-use facet keys. When no
+// dictionary is registered, this tool serves that derived view, so it is
+// useful on every deployment from day one; a dictionary ADDS the jargon,
+// guidance, and runbooks the registries cannot know.
+// ---------------------------------------------------------------------------
+/** Topics that only exist as authored dictionary content. */
+const AUTHORED_TOPICS = new Set(['action', 'rule', 'runbook']);
+async function derivedContext(topic, name) {
+    if (topic && AUTHORED_TOPICS.has(topic)) {
+        return {
+            derived: true,
+            error: `"${topic}" entries are authored in the dictionary; none is registered.`,
+            hint: REGISTER_HINT,
+        };
+    }
+    const [roles, configs, facetKeys] = await Promise.all([
+        (0, role_1.listRolesWithDetails)(),
+        (0, config_1.listWorkflowConfigs)(),
+        (0, queries_1.listFacetKeys)({ global: true }),
+    ]);
+    const roleEntries = roles.map((r) => {
+        const props = r.properties ?? {};
+        return {
+            kind: 'role',
+            term: r.role,
+            derived: true,
+            title: r.title ?? undefined,
+            description: r.description ?? undefined,
+            entity_facet: r.entity_facet ?? undefined,
+            on_cancel: typeof props[types_1.ROLE_PROPERTY_KEYS.ON_CANCEL] === 'string' ? props[types_1.ROLE_PROPERTY_KEYS.ON_CANCEL] : undefined,
+            on_timeout: typeof props[types_1.ROLE_PROPERTY_KEYS.ON_TIMEOUT] === 'string' ? props[types_1.ROLE_PROPERTY_KEYS.ON_TIMEOUT] : undefined,
+            worked_by: typeof props[types_1.ROLE_PROPERTY_KEYS.WORKED_BY] === 'string' ? props[types_1.ROLE_PROPERTY_KEYS.WORKED_BY] : undefined,
+        };
+    });
+    // Entities: roles sharing an entity_facet form that entity's system; the
+    // facet key is the best available name until a dictionary declares a noun.
+    const rolesByFacet = new Map();
+    for (const r of roles) {
+        if (!r.entity_facet)
+            continue;
+        const list = rolesByFacet.get(r.entity_facet) ?? [];
+        list.push(r.role);
+        rolesByFacet.set(r.entity_facet, list);
+    }
+    const entityEntries = [...rolesByFacet.entries()].map(([facet, facetRoles]) => ({
+        kind: 'entity',
+        term: facet,
+        derived: true,
+        idFacet: facet,
+        roles: facetRoles,
+        guidance: `Query escalations with facets={${facet}: value}, created_at desc.`,
+    }));
+    const workflowEntries = configs.map((c) => ({
+        kind: 'workflow',
+        term: c.workflow_type,
+        derived: true,
+        description: c.description ?? undefined,
+        invocable: c.invocable,
+        task_queue: c.task_queue ?? undefined,
+        stop_note: 'Stop a workflow with terminate_workflow (kills the handle AND cancels its escalations).',
+    }));
+    const facetEntries = facetKeys.map((key) => ({ kind: 'facet', term: key, derived: true }));
+    if (!topic) {
+        return {
+            derived: true,
+            note: `No dictionary is registered — this index is derived from the live registries. ${REGISTER_HINT}`,
+            terms: {
+                entity: entityEntries.map((e) => e.term),
+                role: roleEntries.map((r) => r.term),
+                workflow: workflowEntries.map((w) => w.term),
+                facet: facetEntries.map((f) => f.term),
+            },
+            runbooks: [],
+        };
+    }
+    const byTopic = {
+        entity: entityEntries,
+        role: roleEntries,
+        workflow: workflowEntries,
+        facet: facetEntries,
+        term: [...entityEntries, ...roleEntries, ...workflowEntries, ...facetEntries],
+    };
+    let entries = byTopic[topic] ?? [];
+    if (name)
+        entries = entries.filter((e) => norm(e.term) === norm(name));
+    if (!entries.length) {
+        return {
+            derived: true,
+            error: `No live-registry entry matches topic "${topic}"${name ? ` name "${name}"` : ''}.`,
+            hint: 'Call with no args for the derived index.',
+        };
+    }
+    return entries;
+}
+/**
+ * Enrich terms with live registry state. Dangling references are annotated so
+ * a stale dictionary reads as stale instead of lying or crashing.
+ */
+async function enrichTerms(terms) {
+    const wantsRoles = terms.some((t) => rolesOf(t).length > 0);
+    const wantsWorkflows = terms.some((t) => t.maps_to?.workflow);
+    const [roles, configs] = await Promise.all([
+        wantsRoles ? (0, role_1.listRolesWithDetails)() : Promise.resolve([]),
+        wantsWorkflows ? (0, config_1.listWorkflowConfigs)() : Promise.resolve([]),
+    ]);
+    const roleByName = new Map(roles.map((r) => [r.role, r]));
+    const configByType = new Map(configs.map((c) => [c.workflow_type, c]));
+    return terms.map((t) => {
+        const out = { ...t };
+        const liveRoles = rolesOf(t).map((name) => {
+            const row = roleByName.get(name);
+            if (!row)
+                return { role: name, dangling: 'no longer a live role' };
+            const props = row.properties ?? {};
+            return {
+                role: row.role,
+                title: row.title ?? undefined,
+                description: row.description ?? undefined,
+                entity_facet: row.entity_facet ?? undefined,
+                on_cancel: typeof props[types_1.ROLE_PROPERTY_KEYS.ON_CANCEL] === 'string' ? props[types_1.ROLE_PROPERTY_KEYS.ON_CANCEL] : undefined,
+                on_timeout: typeof props[types_1.ROLE_PROPERTY_KEYS.ON_TIMEOUT] === 'string' ? props[types_1.ROLE_PROPERTY_KEYS.ON_TIMEOUT] : undefined,
+                worked_by: typeof props[types_1.ROLE_PROPERTY_KEYS.WORKED_BY] === 'string' ? props[types_1.ROLE_PROPERTY_KEYS.WORKED_BY] : undefined,
+            };
+        });
+        if (liveRoles.length)
+            out.live_roles = liveRoles;
+        if (t.kind === 'entity' && !out.idFacet) {
+            // Fallback derivation for docs written before the role declared its facet.
+            const derived = liveRoles.find((r) => 'entity_facet' in r && r.entity_facet);
+            if (derived)
+                out.idFacet = derived.entity_facet;
+        }
+        if (t.maps_to?.workflow) {
+            const config = configByType.get(t.maps_to.workflow);
+            out.live_workflow = config
+                ? {
+                    workflow_type: config.workflow_type,
+                    description: config.description ?? undefined,
+                    invocable: config.invocable,
+                    task_queue: config.task_queue ?? undefined,
+                }
+                : { workflow_type: t.maps_to.workflow, dangling: 'not a registered workflow' };
+            out.stop_note = 'Stop a workflow with terminate_workflow (kills the handle AND cancels its escalations).';
+        }
+        return out;
+    });
+}
+function registerDomainContextTools(server) {
+    server.registerTool('get_domain_context', {
+        title: 'Get Domain Context',
+        description: 'The deployment\'s domain dictionary merged with live platform state — how ' +
+            'this operation\'s jargon maps to roles, queues, workflows, escalations, and ' +
+            'metadata facets. No args → overview + index. { topic, name } → specific ' +
+            'entries: entity (id facet + roles → build an escalation query on ' +
+            'facets={idFacet: value}, sorted created_at desc), role (live title + ' +
+            'cancel/timeout semantics), workflow (kill road + id convention), facet, ' +
+            'action, rule, or runbook; topic `term` looks a word or alias up across every ' +
+            'kind. Works on every deployment: with no dictionary registered it serves a ' +
+            'view derived from the live registries (roles, entity facets, workflows, ' +
+            'facet keys). Call this before acting on anything deployment-specific — ' +
+            'verbs like cancel invert meaning by role.',
+        inputSchema: schemas_1.getDomainContextSchema,
+    }, async (args) => {
+        const respond = (payload) => ({
+            content: [{ type: 'text', text: JSON.stringify(payload) }],
+        });
+        const record = await (0, domain_1.getDomainDictionary)();
+        if (!record)
+            return respond(await derivedContext(args.topic, args.name));
+        const doc = record.doc;
+        if (!args.topic)
+            return respond(await (0, domain_1.getDomainIndex)());
+        if (args.topic === 'runbook') {
+            const runbooks = doc.runbooks ?? [];
+            return respond(args.name ? runbooks.filter((r) => norm(r.name) === norm(args.name)) : runbooks);
+        }
+        let terms = doc.terms ?? [];
+        if (args.topic !== 'term')
+            terms = terms.filter((t) => t.kind === args.topic);
+        if (args.name)
+            terms = terms.filter((t) => termMatches(t, args.name));
+        if (!terms.length) {
+            return respond({
+                error: `No dictionary entry matches topic "${args.topic}"${args.name ? ` name "${args.name}"` : ''}.`,
+                hint: 'Call with no args for the index of known terms.',
+            });
+        }
+        return respond(await enrichTerms(terms));
+    });
+}

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

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerExportTools = registerExportTools;
 const api = __importStar(require("../../../api/exports"));
+const pick_1 = require("../../../lib/json-path/pick");
 const schemas_1 = require("./schemas");
 function registerExportTools(server) {
     // mirrors GET /api/workflow-states/jobs
@@ -53,7 +54,8 @@ function registerExportTools(server) {
     server.registerTool('export_workflow_state', {
         title: 'Export Workflow State',
         description: 'Export the full workflow state using HotMesh durable export. ' +
-            'Optionally allow/block specific fields.',
+            'allow/block filter which sections the engine fetches; select projects the ' +
+            'returned JSON down to dot paths (token-efficient).',
         inputSchema: schemas_1.exportWorkflowStateSchema,
     }, async (args) => {
         const result = await api.exportWorkflowState({
@@ -65,13 +67,14 @@ function registerExportTools(server) {
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
-        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+        return { content: [{ type: 'text', text: JSON.stringify((0, pick_1.pickPaths)(result.data, args.select)) }] };
     });
     // mirrors GET /api/workflow-states/:workflowId/execution
     server.registerTool('export_workflow_execution', {
         title: 'Export Workflow Execution',
         description: 'Export workflow state as a structured execution event history. ' +
-            'Useful for debugging and workflow compilation.',
+            'Useful for debugging and workflow compilation. Histories run large — ' +
+            'pass select (dot paths) to return only what you need.',
         inputSchema: schemas_1.exportWorkflowExecutionSchema,
     }, async (args) => {
         const result = await api.exportWorkflowExecution({
@@ -84,7 +87,7 @@ function registerExportTools(server) {
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
-        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+        return { content: [{ type: 'text', text: JSON.stringify((0, pick_1.pickPaths)(result.data, args.select)) }] };
     });
     // mirrors GET /api/workflow-states/:workflowId/status
     server.registerTool('get_export_status', {

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

@@ -59,7 +59,8 @@ const exports_1 = require("./exports");
 const overview_1 = require("./overview");
 const diagnostics_1 = require("./diagnostics");
 const scan_codes_1 = require("./scan-codes");
-const TOOL_COUNT = 101;
+const domain_context_1 = require("./domain-context");
+const TOOL_COUNT = 103;
 let server = null;
 async function createAdminServer(options) {
     if (server && !options?.fresh)
@@ -72,7 +73,7 @@ async function createAdminServer(options) {
     (0, tasks_1.registerTaskTools)(instance); //  2 tools
     (0, escalations_1.registerEscalationTools)(instance); // 20 tools (RO + RW single + metadata + bulk)
     (0, workflow_config_1.registerWorkflowConfigTools)(instance); //  3 tools
-    (0, workflows_1.registerWorkflowTools)(instance); //  3 tools
+    (0, workflows_1.registerWorkflowTools)(instance); //  4 tools (+ terminate_workflow)
     (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)
@@ -89,7 +90,8 @@ async function createAdminServer(options) {
     (0, overview_1.registerOverviewTools)(instance); //  1 tool
     (0, diagnostics_1.registerDiagnosticsTools)(instance); //  3 tools
     (0, scan_codes_1.registerScanCodeTools)(instance); //  5 tools (scan schemes + rules + execute)
-    // Total: 101
+    (0, domain_context_1.registerDomainContextTools)(instance); //  1 tool  (get_domain_context)
+    // Total: 103
     logger_1.loggerRegistry.info(`[lt-mcp:admin] ${name} ready (${TOOL_COUNT} tools registered)`);
     return instance;
 }

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

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerPipelineTools = registerPipelineTools;
 const api = __importStar(require("../../../api/pipelines"));
+const pick_1 = require("../../../lib/json-path/pick");
 const schemas_1 = require("./schemas");
 function registerPipelineTools(server) {
     // mirrors GET /api/pipelines/entities
@@ -65,7 +66,8 @@ function registerPipelineTools(server) {
     // mirrors GET /api/pipelines/:jobId/execution
     server.registerTool('get_pipeline_execution', {
         title: 'Get Pipeline Execution',
-        description: 'Export execution details for a specific pipeline job.',
+        description: 'Export execution details for a specific pipeline job. Histories run to ' +
+            'tens of KB — pass select (dot paths) to return only what you need.',
         inputSchema: schemas_1.getJobExecutionSchema,
     }, async (args) => {
         const result = await api.getJobExecution({
@@ -75,12 +77,16 @@ function registerPipelineTools(server) {
         if (result.error) {
             return { content: [{ type: 'text', text: JSON.stringify({ error: result.error }) }], isError: true };
         }
-        return { content: [{ type: 'text', text: JSON.stringify(result.data) }] };
+        return { content: [{ type: 'text', text: JSON.stringify((0, pick_1.pickPaths)(result.data, args.select)) }] };
     });
     // mirrors POST /api/pipelines/:jobId/interrupt
     server.registerTool('interrupt_pipeline_job', {
         title: 'Interrupt Pipeline Job',
-        description: 'Interrupt a running pipeline job.',
+        description: 'Engine-level interrupt of a running job. WARNING: this does NOT cancel the ' +
+            'workflow\'s escalations — they are stranded as pending orphans. To stop a ' +
+            'workflow cleanly use terminate_workflow, which also cancels its escalations. ' +
+            'Use interrupt_pipeline_job only for a raw engine interrupt when you have a ' +
+            'specific reason to leave escalation rows untouched.',
         inputSchema: schemas_1.interruptJobSchema,
     }, async (args) => {
         const result = await api.interruptJob({