@hotmeshio/long-tail 0.23.1 → 0.24.0

package/build/services/escalation/related.js

@@ -0,0 +1,196 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Related sets for list views: a host row's items (each read through its
+// payload or its reciprocal row) and rows in other roles that share facets
+// with it. Every statement serves a whole page of hosts and composes the
+// caller's read scope, so the cost is bounded by the declaration, never by
+// the page size or the item count.
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregateRelatedItems = aggregateRelatedItems;
+exports.listRelatedItems = listRelatedItems;
+exports.aggregateRelatedQuery = aggregateRelatedQuery;
+exports.listRelatedQueryRows = listRelatedQueryRows;
+exports.readRelatedHosts = readRelatedHosts;
+const db_1 = require("../../lib/db");
+const uuid_1 = require("../../lib/uuid");
+const escalation_1 = require("../../types/escalation");
+const list_schema_1 = require("../../shared/list-schema");
+const client_1 = require("./client");
+const map_1 = require("./map");
+const read_scope_sql_1 = require("./read-scope-sql");
+const UUID_PATTERN = uuid_1.UUID_RE.source;
+function foldAggregateRows(rows, hostIds, split) {
+    const out = {};
+    for (const id of hostIds)
+        out[id] = split ? { count: 0, splits: {} } : { count: 0 };
+    for (const row of rows) {
+        const agg = out[row.host_id];
+        if (!agg)
+            continue;
+        agg.count += row.n;
+        if (row.hidden) {
+            agg.hidden = (agg.hidden ?? 0) + row.n;
+        }
+        else if (split) {
+            const key = row.split ?? '';
+            agg.splits[key] = (agg.splits[key] ?? 0) + row.n;
+        }
+    }
+    return out;
+}
+/** The hosts and their item entries, read under the caller's scope. */
+function itemEntriesCte(params, scope, hostIds) {
+    const hi = params.push(hostIds);
+    const hostScope = (0, read_scope_sql_1.buildReadScopeClause)(scope, params, 'h');
+    return `hosts AS (
+      SELECT h.id, h.envelope,
+        (h.envelope ? '${escalation_1.ESCALATION_ACCUMULATE_KEYS.ITEMS}') AS acc,
+        COALESCE(h.envelope->'${escalation_1.ESCALATION_ACCUMULATE_KEYS.ITEMS}', h.envelope->'${escalation_1.ESCALATION_BATCH_KEYS.ITEMS}') AS items
+      FROM public.lt_escalations h
+      WHERE h.id = ANY($${hi}::uuid[])${hostScope ? ` AND ${hostScope}` : ''}
+    ), entries AS (
+      SELECT hosts.id AS host_id, hosts.acc, hosts.envelope, e.key AS item_key, e.value AS entry,
+        CASE WHEN hosts.acc AND (e.value->>'reciprocalId') ~* '${UUID_PATTERN}'
+          THEN (e.value->>'reciprocalId')::uuid END AS rid
+      FROM hosts, jsonb_each(CASE WHEN jsonb_typeof(hosts.items) = 'object' THEN hosts.items ELSE '{}'::jsonb END) e
+    )`;
+}
+/**
+ * Count each host's items, optionally split by `payload.<path>` or
+ * `reciprocal.metadata.<key>`. A reciprocal split counts only reciprocal rows
+ * the caller can read; the rest are reported as `hidden`. `roles` names the
+ * roles of the readable reciprocal rows, so a list can follow their changes.
+ */
+async function aggregateRelatedItems(opts) {
+    if (!opts.hostIds.length)
+        return { aggregates: {}, roles: [] };
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const cte = itemEntriesCte(params, opts.scope, opts.hostIds);
+    const splitBy = opts.splitBy ?? '';
+    let splitExpr = 'NULL::text';
+    let join = '';
+    let hiddenExpr = 'false';
+    let rolesExpr = 'NULL::text[]';
+    if (splitBy.startsWith(list_schema_1.SPLIT_PATHS.PAYLOAD)) {
+        const pi = params.push(splitBy.slice(list_schema_1.SPLIT_PATHS.PAYLOAD.length).split('.'));
+        splitExpr = `(CASE WHEN en.acc THEN en.entry->'payload' ELSE en.entry END) #>> $${pi}::text[]`;
+    }
+    else if (splitBy.startsWith(list_schema_1.SPLIT_PATHS.RECIPROCAL_METADATA)) {
+        const ki = params.push(splitBy.slice(list_schema_1.SPLIT_PATHS.RECIPROCAL_METADATA.length));
+        const rScope = (0, read_scope_sql_1.buildReadScopeClause)(opts.scope, params, 'r');
+        join = `LEFT JOIN public.lt_escalations r ON r.id = en.rid${rScope ? ` AND ${rScope}` : ''}`;
+        splitExpr = `r.metadata->>$${ki}`;
+        hiddenExpr = '(en.rid IS NOT NULL AND r.id IS NULL)';
+        rolesExpr = 'array_agg(DISTINCT r.role) FILTER (WHERE r.id IS NOT NULL)';
+    }
+    const { rows } = await (0, db_1.getPool)().query(`WITH ${cte}
+     SELECT en.host_id::text AS host_id, ${splitExpr} AS split, ${hiddenExpr} AS hidden, count(*)::int AS n,
+       ${rolesExpr} AS roles
+     FROM entries en ${join}
+     GROUP BY 1, 2, 3`, params);
+    const roles = new Set(rows.flatMap((row) => row.roles ?? []));
+    return { aggregates: foldAggregateRows(rows, opts.hostIds, !!splitBy), roles: [...roles].sort() };
+}
+/** One host's items in fill order, each with its reciprocal row when readable. */
+async function listRelatedItems(opts) {
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const cte = itemEntriesCte(params, opts.scope, [opts.hostId]);
+    const rScope = (0, read_scope_sql_1.buildReadScopeClause)(opts.scope, params, 'r');
+    const li = params.push(opts.limit);
+    const { rows } = await (0, db_1.getPool)().query(`WITH ${cte}
+     SELECT en.item_key, en.entry, en.acc,
+       en.envelope->'${escalation_1.ESCALATION_BATCH_KEYS.FILLED_AT}'->>en.item_key AS batch_at,
+       en.envelope->'${escalation_1.ESCALATION_BATCH_KEYS.FILLED_BY}'->>en.item_key AS batch_actor,
+       (en.rid IS NOT NULL AND r.id IS NULL) AS hidden,
+       CASE WHEN r.id IS NULL THEN NULL ELSE to_jsonb(r) END AS reciprocal,
+       count(*) OVER ()::int AS total
+     FROM entries en
+     LEFT JOIN public.lt_escalations r ON r.id = en.rid${rScope ? ` AND ${rScope}` : ''}
+     ORDER BY COALESCE(CASE WHEN en.acc THEN en.entry->>'at' END,
+                       en.envelope->'${escalation_1.ESCALATION_BATCH_KEYS.FILLED_AT}'->>en.item_key) NULLS LAST, en.item_key
+     LIMIT $${li}`, params);
+    return {
+        total: rows[0]?.total ?? 0,
+        rows: rows.map((row) => {
+            const entry = row.entry ?? {};
+            const item = row.acc
+                ? {
+                    itemKey: row.item_key,
+                    payload: entry.payload,
+                    at: entry.at,
+                    ...(entry.actor ? { actor: entry.actor } : {}),
+                    ...(entry.reciprocalId ? { reciprocalId: entry.reciprocalId } : {}),
+                }
+                : {
+                    itemKey: row.item_key,
+                    payload: entry,
+                    ...(row.batch_at ? { at: row.batch_at } : {}),
+                    ...(row.batch_actor ? { actor: row.batch_actor } : {}),
+                };
+            return { item, escalation: row.reciprocal ? (0, map_1.toEscalationRecord)(row.reciprocal) : null };
+        }),
+    };
+}
+/** The shared FROM/WHERE of a query set: hosts unnested beside their matches. */
+function querySetFrom(params, input) {
+    const hi = params.push(input.hosts.map((h) => h.hostId));
+    const mi = params.push(input.hosts.map((h) => JSON.stringify(h.match)));
+    const ri = params.push(input.roles);
+    const si = params.push(input.status);
+    const scope = (0, read_scope_sql_1.buildReadScopeClause)(input.scope, params, 'e');
+    return `FROM unnest($${hi}::text[], $${mi}::jsonb[]) AS h(host_id, match)
+     JOIN public.lt_escalations e ON e.metadata @> h.match
+     WHERE e.role = ANY($${ri}::text[]) AND e.status = $${si}
+       AND e.id::text <> h.host_id${scope ? ` AND ${scope}` : ''}`;
+}
+/**
+ * Count the rows that share each host's facets, grouped by role and an
+ * optional `metadata.<key>` split. The GIN index serves each host's match.
+ */
+async function aggregateRelatedQuery(input) {
+    const hostIds = input.hosts.map((h) => h.hostId);
+    if (!hostIds.length || !input.roles.length)
+        return foldAggregateRows([], hostIds, !!input.splitBy);
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const from = querySetFrom(params, input);
+    let splitExpr = 'NULL::text';
+    if (input.splitBy === list_schema_1.SPLIT_PATHS.ROLE) {
+        splitExpr = 'e.role';
+    }
+    else if (input.splitBy?.startsWith(list_schema_1.SPLIT_PATHS.METADATA)) {
+        splitExpr = `e.metadata->>$${params.push(input.splitBy.slice(list_schema_1.SPLIT_PATHS.METADATA.length))}`;
+    }
+    const { rows } = await (0, db_1.getPool)().query(`SELECT h.host_id, ${splitExpr} AS split, count(*)::int AS n ${from} GROUP BY 1, 2`, params);
+    return foldAggregateRows(rows, hostIds, !!input.splitBy);
+}
+/** One host's related rows, in role order then age. */
+async function listRelatedQueryRows(input) {
+    if (!input.hosts.length || !input.roles.length)
+        return { rows: [], total: 0 };
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [];
+    const from = querySetFrom(params, input);
+    const oi = params.push(input.roles);
+    const li = params.push(input.limit);
+    const { rows } = await (0, db_1.getPool)().query(`SELECT to_jsonb(e) AS row, count(*) OVER ()::int AS total ${from}
+     ORDER BY array_position($${oi}::text[], e.role), e.created_at
+     LIMIT $${li}`, params);
+    return {
+        total: rows[0]?.total ?? 0,
+        rows: rows.map((r) => ({ escalation: (0, map_1.toEscalationRecord)(r.row) })),
+    };
+}
+/** Host rows of one role, read under the caller's scope. */
+async function readRelatedHosts(opts) {
+    if (!opts.ids.length)
+        return [];
+    await (0, client_1.ensureEscalationCompatView)();
+    const params = [opts.ids, opts.role];
+    const scope = (0, read_scope_sql_1.buildReadScopeClause)(opts.scope, params);
+    const { rows } = await (0, db_1.getPool)().query(`SELECT * FROM public.lt_escalations WHERE id = ANY($1::uuid[]) AND role = $2${scope ? ` AND ${scope}` : ''}`, params);
+    return rows.map((row) => (0, map_1.toEscalationRecord)(row));
+}

package/build/services/export/index.d.ts

@@ -48,6 +48,16 @@ export interface WorkflowEnvelopes {
  * so, making this the natural polling body.
  */
 export declare function getWorkflowEnvelopes(workflowId: string, taskQueue: string, workflowName: string): Promise<WorkflowEnvelopes>;
+/**
+ * The identity a run was started with: its start envelope's `lt` block
+ * (`userId` is who it runs as; `initiatedBy` is the person who started it
+ * under `execute_as`). Read from the run's own input, so it holds for every
+ * registered or durable run. Null when the run cannot be found.
+ */
+export declare function getWorkflowStartIdentity(workflowId: string): Promise<{
+    userId?: string;
+    initiatedBy?: string;
+} | null>;
 /**
  * Return the current job state of a workflow.
  * If the workflow is complete this is also the output.

package/build/services/export/index.js

@@ -4,11 +4,13 @@ exports.exportWorkflow = exportWorkflow;
 exports.getWorkflowStatus = getWorkflowStatus;
 exports.exportWorkflowExecution = exportWorkflowExecution;
 exports.getWorkflowEnvelopes = getWorkflowEnvelopes;
+exports.getWorkflowStartIdentity = getWorkflowStartIdentity;
 exports.getWorkflowState = getWorkflowState;
 exports.listJobs = listJobs;
 const db_1 = require("../../lib/db");
 const hotmesh_utils_1 = require("../hotmesh-utils");
 const client_1 = require("./client");
+const resolve_1 = require("../task/resolve");
 const post_process_1 = require("./post-process");
 const workflow_state_1 = require("../workflow-state");
 /** Error thrown when a workflow job is not found (expired or never existed). */
@@ -123,6 +125,31 @@ async function getWorkflowEnvelopes(workflowId, taskQueue, workflowName) {
     const output = await handle.output().catch(() => null);
     return { workflow_id: workflowId, status: reading.state, input, output: output ?? null };
 }
+/**
+ * The identity a run was started with: its start envelope's `lt` block
+ * (`userId` is who it runs as; `initiatedBy` is the person who started it
+ * under `execute_as`). Read from the run's own input, so it holds for every
+ * registered or durable run. Null when the run cannot be found.
+ */
+async function getWorkflowStartIdentity(workflowId) {
+    let resolved;
+    try {
+        resolved = await (0, resolve_1.resolveWorkflowHandle)(workflowId);
+    }
+    catch {
+        return null;
+    }
+    const handle = await (0, client_1.getHandle)(resolved.taskQueue, resolved.workflowName, workflowId);
+    const args = await handle.input().catch(() => undefined);
+    const envelope = Array.isArray(args) && args.length >= 1 ? args[0] : null;
+    const lt = (envelope && typeof envelope === 'object' ? envelope.lt : null) ?? null;
+    if (!lt)
+        return {};
+    return {
+        ...(typeof lt.userId === 'string' ? { userId: lt.userId } : {}),
+        ...(typeof lt.initiatedBy === 'string' ? { initiatedBy: lt.initiatedBy } : {}),
+    };
+}
 /**
  * Return the current job state of a workflow.
  * If the workflow is complete this is also the output.

package/build/services/invocation-access.d.ts

@@ -8,11 +8,32 @@ export declare const INVOCATION_ROLE_TYPES: {
     readonly ADMIN: "admin";
 };
 export declare const ADMIN_ROLE = "admin";
-/** Superadmin anywhere, or the named admin role held as admin type, invokes every workflow. */
-export declare function hasGlobalInvocationAccess(roles: readonly InvocationRoleGrant[], authRole?: string): boolean;
+/** The workflow that calls a named MCP tool with lt-system authority. */
+export declare const CAPABILITY_INVOKE_WORKFLOW = "capabilityInvoke";
+/**
+ * Workflows whose activities act with lt-system authority. Started from
+ * outside the process, they would lend that authority to the caller, so only
+ * a superadmin may start one. Internal starts (agent triggers) are unaffected.
+ */
+export declare const SYSTEM_AUTHORITY_WORKFLOWS: ReadonlySet<string>;
+/**
+ * Whether a caller may run a workflow as another principal. A superadmin may
+ * act as anyone. Otherwise the caller needs an admin-type grant, the target
+ * holds no superadmin grant, and every grant the target holds the caller
+ * holds at the same or a higher type: an override never exceeds the caller.
+ */
+export declare function mayActAs(caller: readonly InvocationRoleGrant[], target: readonly InvocationRoleGrant[]): boolean;
+/**
+ * Superadmin anywhere, or the named admin role held as admin type, invokes
+ * every workflow. Decided from grants only, never a token's role claim.
+ */
+export declare function hasGlobalInvocationAccess(roles: readonly InvocationRoleGrant[]): boolean;
 /**
  * The one invocation predicate, shared by the invoke gate and the per-caller
  * list so the two can never disagree. An empty invocation_roles list opens
- * the workflow to every authenticated caller.
+ * the workflow to every authenticated caller. A system-authority workflow
+ * needs a superadmin grant, whatever its stored roles say.
  */
-export declare function canInvokeWorkflow(config: Pick<LTWorkflowConfig, 'invocable' | 'invocation_roles'>, roles: readonly InvocationRoleGrant[], authRole?: string): boolean;
+export declare function canInvokeWorkflow(config: Pick<LTWorkflowConfig, 'invocable' | 'invocation_roles'> & {
+    workflow_type?: string;
+}, roles: readonly InvocationRoleGrant[]): boolean;

package/build/services/invocation-access.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ADMIN_ROLE = exports.INVOCATION_ROLE_TYPES = void 0;
+exports.SYSTEM_AUTHORITY_WORKFLOWS = exports.CAPABILITY_INVOKE_WORKFLOW = exports.ADMIN_ROLE = exports.INVOCATION_ROLE_TYPES = void 0;
+exports.mayActAs = mayActAs;
 exports.hasGlobalInvocationAccess = hasGlobalInvocationAccess;
 exports.canInvokeWorkflow = canInvokeWorkflow;
 exports.INVOCATION_ROLE_TYPES = {
@@ -8,24 +9,55 @@ exports.INVOCATION_ROLE_TYPES = {
     ADMIN: 'admin',
 };
 exports.ADMIN_ROLE = 'admin';
-/** Superadmin anywhere, or the named admin role held as admin type, invokes every workflow. */
-function hasGlobalInvocationAccess(roles, authRole) {
-    if (authRole === exports.INVOCATION_ROLE_TYPES.SUPERADMIN)
+/** The workflow that calls a named MCP tool with lt-system authority. */
+exports.CAPABILITY_INVOKE_WORKFLOW = 'capabilityInvoke';
+/**
+ * Workflows whose activities act with lt-system authority. Started from
+ * outside the process, they would lend that authority to the caller, so only
+ * a superadmin may start one. Internal starts (agent triggers) are unaffected.
+ */
+exports.SYSTEM_AUTHORITY_WORKFLOWS = new Set([exports.CAPABILITY_INVOKE_WORKFLOW]);
+const ROLE_TYPE_RANK = { member: 1, admin: 2, superadmin: 3 };
+function holdsSuperadmin(roles) {
+    return roles.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.SUPERADMIN);
+}
+/**
+ * Whether a caller may run a workflow as another principal. A superadmin may
+ * act as anyone. Otherwise the caller needs an admin-type grant, the target
+ * holds no superadmin grant, and every grant the target holds the caller
+ * holds at the same or a higher type: an override never exceeds the caller.
+ */
+function mayActAs(caller, target) {
+    if (holdsSuperadmin(caller))
         return true;
+    if (!caller.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.ADMIN))
+        return false;
+    if (holdsSuperadmin(target))
+        return false;
+    return target.every((t) => caller.some((c) => c.role === t.role && (ROLE_TYPE_RANK[c.type] ?? 0) >= (ROLE_TYPE_RANK[t.type] ?? 0)));
+}
+/**
+ * Superadmin anywhere, or the named admin role held as admin type, invokes
+ * every workflow. Decided from grants only, never a token's role claim.
+ */
+function hasGlobalInvocationAccess(roles) {
     return roles.some((r) => r.type === exports.INVOCATION_ROLE_TYPES.SUPERADMIN)
         || roles.some((r) => r.role === exports.ADMIN_ROLE && r.type === exports.INVOCATION_ROLE_TYPES.ADMIN);
 }
 /**
  * The one invocation predicate, shared by the invoke gate and the per-caller
  * list so the two can never disagree. An empty invocation_roles list opens
- * the workflow to every authenticated caller.
+ * the workflow to every authenticated caller. A system-authority workflow
+ * needs a superadmin grant, whatever its stored roles say.
  */
-function canInvokeWorkflow(config, roles, authRole) {
+function canInvokeWorkflow(config, roles) {
     if (!config.invocable)
         return false;
+    if (config.workflow_type && exports.SYSTEM_AUTHORITY_WORKFLOWS.has(config.workflow_type))
+        return holdsSuperadmin(roles);
     if (config.invocation_roles.length === 0)
         return true;
-    if (hasGlobalInvocationAccess(roles, authRole))
+    if (hasGlobalInvocationAccess(roles))
         return true;
     const held = new Set(roles.map((r) => r.role));
     return config.invocation_roles.some((r) => held.has(r));

package/build/services/mcp/client/connection-dispatch.d.ts

@@ -8,7 +8,12 @@ import type { LTMcpToolManifest } from '../../../types';
  * are called via server._registeredTools[toolName].handler(args). This
  * eliminates the InMemoryTransport bottleneck under concurrent load.
  */
-export declare function dispatchBuiltinTool(serverId: string, toolName: string, args: Record<string, any>): Promise<{
+export declare function dispatchBuiltinTool(serverId: string, toolName: string, args: Record<string, any>, extra?: {
+    authInfo?: {
+        userId: string;
+        role?: string;
+    };
+}): Promise<{
     dispatched: true;
     result: any;
 } | null>;

package/build/services/mcp/client/connection-dispatch.js

@@ -13,7 +13,7 @@ const connection_lifecycle_1 = require("./connection-lifecycle");
  * are called via server._registeredTools[toolName].handler(args). This
  * eliminates the InMemoryTransport bottleneck under concurrent load.
  */
-async function dispatchBuiltinTool(serverId, toolName, args) {
+async function dispatchBuiltinTool(serverId, toolName, args, extra) {
     const builtinFactories = (0, connection_lifecycle_1.getBuiltinFactories)();
     const builtinServers = (0, connection_lifecycle_1.getBuiltinServers)();
     // Normalize and match against builtin factories
@@ -43,7 +43,8 @@ async function dispatchBuiltinTool(serverId, toolName, args) {
     // Call the handler directly — no transport, no JSON-RPC.
     // Tool handlers return MCP-shaped responses: { content: [{ type: 'text', text: '...' }] }
     // Parse the text content the same way callServerTool does.
-    const mcpResponse = await tool.handler(args);
+    // With `extra`, the handler sees an external caller and acts as them.
+    const mcpResponse = extra ? await tool.handler(args, extra) : await tool.handler(args);
     let parsed = mcpResponse;
     if (mcpResponse && Array.isArray(mcpResponse.content)) {
         const textContent = mcpResponse.content.find((c) => c.type === 'text');

package/build/services/mcp/client/connection-lifecycle.d.ts

@@ -1,5 +1,5 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import type { LTMcpServerRecord } from '../../../types';
+import type { LTMcpServerRecord, LTToolManifestEntry } from '../../../types';
 /** Read-only access to the clients map for sibling modules. */
 export declare function getClients(): Map<string, Client>;
 /** Read-only access to the builtin factories map for sibling modules. */
@@ -10,7 +10,9 @@ export declare function getBuiltinServers(): Map<string, any>;
  * Register a built-in server factory so it can be auto-connected
  * when callServerTool is invoked with its name.
  */
-export declare function registerBuiltinServer(name: string, factory: () => Promise<any>): void;
+export declare function registerBuiltinServer(name: string, factory: () => Promise<any>, toolManifest?: LTToolManifestEntry[]): void;
+/** The tool manifest a built-in server was registered with, if any. */
+export declare function getBuiltinToolManifest(name: string): LTToolManifestEntry[] | undefined;
 /**
  * Connect to a registered MCP server.
  * Creates the appropriate transport based on transport_type,
@@ -29,6 +31,12 @@ export declare function disconnectFromServer(serverId: string): Promise<void>;
  * Alias lookups (e.g. 'translation' matching 'long-tail-translation') reuse
  * the same client instance to avoid double-connecting the singleton server.
  */
+/**
+ * The built-in server a server id or name resolves to, by the same rules
+ * resolveClient follows: an exact or fuzzy factory name, else a registered
+ * server whose name matches a factory. Null for an external server.
+ */
+export declare function resolveBuiltinServerName(serverId: string): Promise<string | null>;
 export declare function resolveClient(serverId: string): Promise<Client | null>;
 /**
  * Connect to all auto-connect servers.

package/build/services/mcp/client/connection-lifecycle.js

@@ -37,8 +37,10 @@ exports.getClients = getClients;
 exports.getBuiltinFactories = getBuiltinFactories;
 exports.getBuiltinServers = getBuiltinServers;
 exports.registerBuiltinServer = registerBuiltinServer;
+exports.getBuiltinToolManifest = getBuiltinToolManifest;
 exports.connectToServer = connectToServer;
 exports.disconnectFromServer = disconnectFromServer;
+exports.resolveBuiltinServerName = resolveBuiltinServerName;
 exports.resolveClient = resolveClient;
 exports.connectAutoServers = connectAutoServers;
 exports.disconnectAll = disconnectAll;
@@ -46,10 +48,9 @@ exports.isConnected = isConnected;
 exports.clear = clear;
 const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
-const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
-const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
 const inMemory_js_1 = require("@modelcontextprotocol/sdk/inMemory.js");
 const logger_1 = require("../../../lib/logger");
+const network_transport_1 = require("./network-transport");
 const mcpDbService = __importStar(require("../db"));
 /** In-memory map of server ID/name to active MCP client */
 const clients = new Map();
@@ -59,6 +60,8 @@ const clients = new Map();
  * rather than external stdio/SSE connections.
  */
 const builtinFactories = new Map();
+/** Tool manifests declared with a built-in factory (Long Tail's or the host's), keyed by server name. */
+const builtinManifests = new Map();
 /**
  * Cached built-in McpServer instances -- keyed by canonical server name.
  * Used by dispatchBuiltinTool() to call tool handlers directly without
@@ -81,8 +84,16 @@ function getBuiltinServers() {
  * Register a built-in server factory so it can be auto-connected
  * when callServerTool is invoked with its name.
  */
-function registerBuiltinServer(name, factory) {
+function registerBuiltinServer(name, factory, toolManifest) {
     builtinFactories.set(name, factory);
+    if (toolManifest)
+        builtinManifests.set(name, toolManifest);
+    else
+        builtinManifests.delete(name);
+}
+/** The tool manifest a built-in server was registered with, if any. */
+function getBuiltinToolManifest(name) {
+    return builtinManifests.get(name);
 }
 /**
  * Connect to a registered MCP server.
@@ -135,11 +146,8 @@ async function connectToServer(server) {
             env: server.transport_config.env,
         });
     }
-    else if (ttype === 'streamable-http') {
-        transport = new streamableHttp_js_1.StreamableHTTPClientTransport(new URL(server.transport_config.url));
-    }
     else {
-        transport = new sse_js_1.SSEClientTransport(new URL(server.transport_config.url));
+        transport = (0, network_transport_1.createNetworkTransport)(ttype === 'streamable-http' ? 'streamable-http' : 'sse', server.transport_config);
     }
     await client.connect(transport);
     clients.set(server.id, client);
@@ -174,6 +182,36 @@ async function disconnectFromServer(serverId) {
  * Alias lookups (e.g. 'translation' matching 'long-tail-translation') reuse
  * the same client instance to avoid double-connecting the singleton server.
  */
+/**
+ * The built-in server a server id or name resolves to, by the same rules
+ * resolveClient follows: an exact or fuzzy factory name, else a registered
+ * server whose name matches a factory. Null for an external server.
+ */
+async function resolveBuiltinServerName(serverId) {
+    if (builtinFactories.has(serverId))
+        return serverId;
+    const norm = (s) => s.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
+    const normId = norm(serverId);
+    for (const [name] of builtinFactories) {
+        const normName = norm(name);
+        if (normName.includes(normId) || normId.includes(normName))
+            return name;
+    }
+    try {
+        const dbServer = (await mcpDbService.getMcpServer(serverId)) ||
+            (await mcpDbService.getMcpServerByName(serverId));
+        if (!dbServer)
+            return null;
+        for (const [name] of builtinFactories) {
+            if (dbServer.name === name || name.includes(dbServer.name) || dbServer.name.includes(name))
+                return name;
+        }
+    }
+    catch {
+        // DB lookup failed: treated as external
+    }
+    return null;
+}
 async function resolveClient(serverId) {
     // 1. Direct lookup (by UUID or name)
     if (clients.has(serverId))

package/build/services/mcp/client/connection-test.js

@@ -3,8 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.testConnection = testConnection;
 const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
-const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
-const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+const network_transport_1 = require("./network-transport");
 /**
  * Test connectivity to an MCP server without persisting.
  * Creates a temporary client, connects, lists tools, then disconnects.
@@ -21,11 +20,8 @@ async function testConnection(transportType, transportConfig) {
                 env: transportConfig.env,
             });
         }
-        else if (transportType === 'streamable-http') {
-            transport = new streamableHttp_js_1.StreamableHTTPClientTransport(new URL(transportConfig.url));
-        }
         else {
-            transport = new sse_js_1.SSEClientTransport(new URL(transportConfig.url));
+            transport = (0, network_transport_1.createNetworkTransport)(transportType, transportConfig);
         }
         await client.connect(transport);
         const { tools } = await client.listTools();

package/build/services/mcp/client/connection.d.ts

@@ -1,3 +1,3 @@
-export { registerBuiltinServer, connectToServer, disconnectFromServer, resolveClient, connectAutoServers, disconnectAll, isConnected, clear, } from './connection-lifecycle';
+export { registerBuiltinServer, getBuiltinToolManifest, connectToServer, disconnectFromServer, resolveClient, resolveBuiltinServerName, connectAutoServers, disconnectAll, isConnected, clear, } from './connection-lifecycle';
 export { testConnection } from './connection-test';
 export { dispatchBuiltinTool, listServerTools, } from './connection-dispatch';

package/build/services/mcp/client/connection.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listServerTools = exports.dispatchBuiltinTool = exports.testConnection = exports.clear = exports.isConnected = exports.disconnectAll = exports.connectAutoServers = exports.resolveClient = exports.disconnectFromServer = exports.connectToServer = exports.registerBuiltinServer = void 0;
+exports.listServerTools = exports.dispatchBuiltinTool = exports.testConnection = exports.clear = exports.isConnected = exports.disconnectAll = exports.connectAutoServers = exports.resolveBuiltinServerName = exports.resolveClient = exports.disconnectFromServer = exports.connectToServer = exports.getBuiltinToolManifest = exports.registerBuiltinServer = void 0;
 var connection_lifecycle_1 = require("./connection-lifecycle");
 Object.defineProperty(exports, "registerBuiltinServer", { enumerable: true, get: function () { return connection_lifecycle_1.registerBuiltinServer; } });
+Object.defineProperty(exports, "getBuiltinToolManifest", { enumerable: true, get: function () { return connection_lifecycle_1.getBuiltinToolManifest; } });
 Object.defineProperty(exports, "connectToServer", { enumerable: true, get: function () { return connection_lifecycle_1.connectToServer; } });
 Object.defineProperty(exports, "disconnectFromServer", { enumerable: true, get: function () { return connection_lifecycle_1.disconnectFromServer; } });
 Object.defineProperty(exports, "resolveClient", { enumerable: true, get: function () { return connection_lifecycle_1.resolveClient; } });
+Object.defineProperty(exports, "resolveBuiltinServerName", { enumerable: true, get: function () { return connection_lifecycle_1.resolveBuiltinServerName; } });
 Object.defineProperty(exports, "connectAutoServers", { enumerable: true, get: function () { return connection_lifecycle_1.connectAutoServers; } });
 Object.defineProperty(exports, "disconnectAll", { enumerable: true, get: function () { return connection_lifecycle_1.disconnectAll; } });
 Object.defineProperty(exports, "isConnected", { enumerable: true, get: function () { return connection_lifecycle_1.isConnected; } });

package/build/services/mcp/client/index.d.ts

@@ -1,2 +1,2 @@
-export { registerBuiltinServer, connectToServer, disconnectFromServer, listServerTools, resolveClient, connectAutoServers, disconnectAll, isConnected, clear, } from './connection';
-export { callServerTool, toolActivities, } from './tools';
+export { registerBuiltinServer, getBuiltinToolManifest, connectToServer, disconnectFromServer, listServerTools, resolveClient, resolveBuiltinServerName, connectAutoServers, disconnectAll, isConnected, clear, } from './connection';
+export { callServerTool, callBuiltinToolAs, toolActivities, } from './tools';

package/build/services/mcp/client/index.js

@@ -1,16 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toolActivities = exports.callServerTool = exports.clear = exports.isConnected = exports.disconnectAll = exports.connectAutoServers = exports.resolveClient = exports.listServerTools = exports.disconnectFromServer = exports.connectToServer = exports.registerBuiltinServer = void 0;
+exports.toolActivities = exports.callBuiltinToolAs = exports.callServerTool = exports.clear = exports.isConnected = exports.disconnectAll = exports.connectAutoServers = exports.resolveBuiltinServerName = exports.resolveClient = exports.listServerTools = exports.disconnectFromServer = exports.connectToServer = exports.getBuiltinToolManifest = exports.registerBuiltinServer = void 0;
 var connection_1 = require("./connection");
 Object.defineProperty(exports, "registerBuiltinServer", { enumerable: true, get: function () { return connection_1.registerBuiltinServer; } });
+Object.defineProperty(exports, "getBuiltinToolManifest", { enumerable: true, get: function () { return connection_1.getBuiltinToolManifest; } });
 Object.defineProperty(exports, "connectToServer", { enumerable: true, get: function () { return connection_1.connectToServer; } });
 Object.defineProperty(exports, "disconnectFromServer", { enumerable: true, get: function () { return connection_1.disconnectFromServer; } });
 Object.defineProperty(exports, "listServerTools", { enumerable: true, get: function () { return connection_1.listServerTools; } });
 Object.defineProperty(exports, "resolveClient", { enumerable: true, get: function () { return connection_1.resolveClient; } });
+Object.defineProperty(exports, "resolveBuiltinServerName", { enumerable: true, get: function () { return connection_1.resolveBuiltinServerName; } });
 Object.defineProperty(exports, "connectAutoServers", { enumerable: true, get: function () { return connection_1.connectAutoServers; } });
 Object.defineProperty(exports, "disconnectAll", { enumerable: true, get: function () { return connection_1.disconnectAll; } });
 Object.defineProperty(exports, "isConnected", { enumerable: true, get: function () { return connection_1.isConnected; } });
 Object.defineProperty(exports, "clear", { enumerable: true, get: function () { return connection_1.clear; } });
 var tools_1 = require("./tools");
 Object.defineProperty(exports, "callServerTool", { enumerable: true, get: function () { return tools_1.callServerTool; } });
+Object.defineProperty(exports, "callBuiltinToolAs", { enumerable: true, get: function () { return tools_1.callBuiltinToolAs; } });
 Object.defineProperty(exports, "toolActivities", { enumerable: true, get: function () { return tools_1.toolActivities; } });

package/build/services/mcp/client/network-transport.d.ts

@@ -0,0 +1,12 @@
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+/**
+ * The client transport for a network MCP server. `headers` ride every
+ * request (the SSE stream and its POSTs alike), which is how a server that
+ * authenticates its callers, such as another Long Tail's /mcp with a
+ * service-account key, is reached.
+ */
+export declare function createNetworkTransport(transportType: 'sse' | 'streamable-http', config: {
+    url?: string;
+    headers?: Record<string, string>;
+}): SSEClientTransport | StreamableHTTPClientTransport;

package/build/services/mcp/client/network-transport.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNetworkTransport = createNetworkTransport;
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/client/streamableHttp.js");
+/**
+ * The client transport for a network MCP server. `headers` ride every
+ * request (the SSE stream and its POSTs alike), which is how a server that
+ * authenticates its callers, such as another Long Tail's /mcp with a
+ * service-account key, is reached.
+ */
+function createNetworkTransport(transportType, config) {
+    if (!config.url)
+        throw new Error('A network MCP server needs a url');
+    const url = new URL(config.url);
+    const requestInit = config.headers && Object.keys(config.headers).length ? { headers: config.headers } : undefined;
+    return transportType === 'streamable-http'
+        ? new streamableHttp_js_1.StreamableHTTPClientTransport(url, { requestInit })
+        : new sse_js_1.SSEClientTransport(url, { requestInit });
+}