@hotmeshio/long-tail 0.1.12 → 0.1.14

package/build/system/activities/schema-exchange.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * Schema-driven data exchange with external service endpoints.
+ *
+ * Three pillars: endpoint + schema + identity.
+ * Transport (fetch, Playwright, gRPC) is an implementation detail.
+ * The value is schema enforcement and credential resolution —
+ * validating both sides of the exchange and resolving auth from
+ * the connection store at the last mile.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSchema = validateSchema;
+exports.exchange = exchange;
+const ajv_1 = __importDefault(require("ajv"));
+const context_1 = require("../../services/iam/context");
+const credentials_1 = require("../../services/iam/credentials");
+const DEFAULT_TIMEOUT = parseInt(process.env.LT_SCHEMA_EXCHANGE_TIMEOUT_MS || '30000', 10);
+const ajv = new ajv_1.default({ allErrors: true, strict: false });
+/**
+ * Normalize a JSON Schema object before validation.
+ *
+ * HotMesh YAML maps serialize JSON arrays as indexed objects
+ * (e.g. `required: {"0":"username","1":"password"}` instead of
+ * `required: ["username","password"]`). This recursively converts
+ * any indexed-object `required` fields back to arrays so Ajv
+ * validates correctly.
+ */
+function normalizeSchema(obj) {
+    if (obj === null || obj === undefined || typeof obj !== 'object')
+        return obj;
+    if (Array.isArray(obj))
+        return obj.map(normalizeSchema);
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (key === 'required' && value && typeof value === 'object' && !Array.isArray(value)) {
+            // Convert indexed object {"0":"a","1":"b"} to array ["a","b"]
+            const keys = Object.keys(value);
+            if (keys.every(k => /^\d+$/.test(k))) {
+                result[key] = keys.sort((a, b) => Number(a) - Number(b)).map(k => value[k]);
+                continue;
+            }
+        }
+        result[key] = normalizeSchema(value);
+    }
+    return result;
+}
+/**
+ * Validate data against a JSON Schema.
+ *
+ * Returns a list of human-readable error strings (empty when valid).
+ */
+function validateSchema(data, schema) {
+    const normalized = normalizeSchema(schema);
+    const validate = ajv.compile(normalized);
+    const valid = validate(data);
+    if (valid)
+        return { valid: true, errors: [] };
+    const errors = (validate.errors || []).map((e) => {
+        const path = e.instancePath || '(root)';
+        return `${path}: ${e.message}${e.params ? ` (${JSON.stringify(e.params)})` : ''}`;
+    });
+    return { valid: false, errors };
+}
+/**
+ * Exchange data with an external service endpoint under schema enforcement.
+ *
+ * 1. If request_schema provided, validate body before sending.
+ *    On failure: return immediately (never send the request).
+ * 2. Make the HTTP call (transport layer — currently Node.js fetch).
+ * 3. Parse response body (JSON auto-detect).
+ * 4. If response_schema provided, validate response after receiving.
+ * 5. Return result with validated flag and any validation_errors.
+ */
+async function exchange(args) {
+    // 1. Validate request body against schema (if provided)
+    if (args.request_schema && args.body !== undefined) {
+        const result = validateSchema(args.body, args.request_schema);
+        if (!result.valid) {
+            return {
+                status: 0,
+                data: null,
+                headers: {},
+                elapsed_ms: 0,
+                validated: false,
+                validation_errors: result.errors.map((e) => `request: ${e}`),
+            };
+        }
+    }
+    // 2. Resolve credential from connection store (if credential_provider set)
+    if (args.credential_provider) {
+        const ctx = (0, context_1.getToolContext)();
+        if (!ctx?.principal) {
+            return {
+                status: 0, data: null, headers: {}, elapsed_ms: 0,
+                validated: false,
+                validation_errors: ['credential: no identity context — cannot resolve credential_provider without a principal'],
+            };
+        }
+        const cred = await (0, credentials_1.resolveCredential)(ctx.principal, args.credential_provider, args.credential_label, ctx.initiatingPrincipal ? { fallbackPrincipal: ctx.initiatingPrincipal } : undefined);
+        if (!cred) {
+            return {
+                status: 0, data: null, headers: {}, elapsed_ms: 0,
+                validated: false,
+                validation_errors: [`credential: no credential found for provider "${args.credential_provider}" — register one at Settings > Connections`],
+            };
+        }
+        const scheme = args.auth_scheme || 'Bearer';
+        const headerName = args.auth_header || 'Authorization';
+        args.headers = { ...args.headers, [headerName]: `${scheme} ${cred.value}` };
+    }
+    // 3. Build URL with query parameters (accept endpoint or url)
+    let url = args.endpoint || args.url;
+    if (!url) {
+        return {
+            status: 0, data: null, headers: {}, elapsed_ms: 0,
+            validated: false, validation_errors: ['endpoint or url is required'],
+        };
+    }
+    if (args.query && Object.keys(args.query).length > 0) {
+        const params = new URLSearchParams(args.query);
+        url += (url.includes('?') ? '&' : '?') + params.toString();
+    }
+    // 3. Make the HTTP call
+    const start = performance.now();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), args.timeout_ms || DEFAULT_TIMEOUT);
+    let status;
+    let responseHeaders = {};
+    let rawBody;
+    try {
+        const fetchOpts = {
+            method: args.method,
+            headers: args.headers,
+            signal: controller.signal,
+        };
+        if (args.body !== undefined && args.method !== 'GET' && args.method !== 'HEAD') {
+            fetchOpts.body = typeof args.body === 'string' ? args.body : JSON.stringify(args.body);
+            if (!args.headers?.['Content-Type'] && !args.headers?.['content-type']) {
+                fetchOpts.headers = { ...fetchOpts.headers, 'Content-Type': 'application/json' };
+            }
+        }
+        const response = await fetch(url, fetchOpts);
+        status = response.status;
+        response.headers.forEach((value, key) => { responseHeaders[key] = value; });
+        rawBody = await response.text();
+    }
+    catch (err) {
+        const elapsed = performance.now() - start;
+        return {
+            status: 0,
+            data: null,
+            headers: {},
+            elapsed_ms: Math.round(elapsed),
+            validated: false,
+            validation_errors: [`transport: ${err.name === 'AbortError' ? 'request timed out' : err.message}`],
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    const elapsed = performance.now() - start;
+    // 3b. Fail fast on auth errors — don't silently return a 401 as a "result"
+    if (status === 401 || status === 403) {
+        return {
+            status,
+            data: null,
+            headers: responseHeaders,
+            elapsed_ms: Math.round(elapsed),
+            validated: false,
+            validation_errors: [
+                status === 401
+                    ? 'authentication: token expired or invalid — refresh credentials and retry'
+                    : 'authorization: insufficient permissions for this endpoint',
+            ],
+        };
+    }
+    // 4. Parse response body
+    let data;
+    const contentType = responseHeaders['content-type'] || '';
+    if (contentType.includes('json') || (rawBody.startsWith('{') || rawBody.startsWith('['))) {
+        try {
+            data = JSON.parse(rawBody);
+        }
+        catch {
+            data = rawBody;
+        }
+    }
+    else {
+        data = rawBody;
+    }
+    // 5. Validate response against schema (if provided)
+    let validated = true;
+    let validationErrors = [];
+    if (args.response_schema) {
+        const result = validateSchema(data, args.response_schema);
+        validated = result.valid;
+        validationErrors = result.errors.map((e) => `response: ${e}`);
+    }
+    return {
+        status,
+        data,
+        headers: responseHeaders,
+        elapsed_ms: Math.round(elapsed),
+        validated,
+        validation_errors: validationErrors,
+    };
+}

package/build/system/activities/sql.d.ts

@@ -1,4 +1,4 @@
-export declare const UPSERT_KNOWLEDGE = "\n  INSERT INTO lt_knowledge (domain, key, data, tags)\n  VALUES ($1, $2, $3, $4)\n  ON CONFLICT (domain, key) DO UPDATE SET\n    data = lt_knowledge.data || EXCLUDED.data,\n    tags = ARRAY(SELECT DISTINCT unnest(lt_knowledge.tags || EXCLUDED.tags))\n  RETURNING id, domain, key, (xmax = 0) AS created, updated_at";
+export declare const UPSERT_KNOWLEDGE = "\n  INSERT INTO lt_knowledge (domain, key, data, tags)\n  VALUES ($1, $2, $3, $4)\n  ON CONFLICT (domain, key) DO UPDATE SET\n    data = CASE\n      WHEN jsonb_typeof(lt_knowledge.data) = 'object'\n      THEN lt_knowledge.data || EXCLUDED.data\n      ELSE EXCLUDED.data\n    END,\n    tags = ARRAY(SELECT DISTINCT unnest(lt_knowledge.tags || EXCLUDED.tags))\n  RETURNING id, domain, key, (xmax = 0) AS created, updated_at";
 export declare const GET_KNOWLEDGE = "\n  SELECT id, domain, key, data, tags, created_at, updated_at\n  FROM lt_knowledge WHERE domain = $1 AND key = $2";
 export declare const SEARCH_KNOWLEDGE = "\n  SELECT id, domain, key, data, tags, created_at, updated_at\n  FROM lt_knowledge\n  WHERE domain = $1 AND data @> $2::jsonb";
 export declare const COUNT_KNOWLEDGE_SEARCH = "\n  SELECT COUNT(*)::int AS total FROM lt_knowledge\n  WHERE domain = $1 AND data @> $2::jsonb";

package/build/system/activities/sql.js

@@ -2,11 +2,22 @@
 // ─── Knowledge CRUD ─────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APPEND_KNOWLEDGE = exports.LIST_DOMAINS = exports.DELETE_KNOWLEDGE = exports.COUNT_KNOWLEDGE_LIST = exports.LIST_KNOWLEDGE = exports.COUNT_KNOWLEDGE_SEARCH = exports.SEARCH_KNOWLEDGE = exports.GET_KNOWLEDGE = exports.UPSERT_KNOWLEDGE = void 0;
+// Upsert knowledge entry. On conflict (domain+key), merges JSONB data at
+// the top level — new keys are added, existing keys are overwritten.
+//
+// Guard: if the existing `data` column is not a JSON object (e.g. it was
+// corrupted into an array by a prior string merge), replace it entirely
+// rather than appending to the array. The CASE expression ensures the
+// `||` operator always receives object || object, which produces a merge.
 exports.UPSERT_KNOWLEDGE = `
   INSERT INTO lt_knowledge (domain, key, data, tags)
   VALUES ($1, $2, $3, $4)
   ON CONFLICT (domain, key) DO UPDATE SET
-    data = lt_knowledge.data || EXCLUDED.data,
+    data = CASE
+      WHEN jsonb_typeof(lt_knowledge.data) = 'object'
+      THEN lt_knowledge.data || EXCLUDED.data
+      ELSE EXCLUDED.data
+    END,
     tags = ARRAY(SELECT DISTINCT unnest(lt_knowledge.tags || EXCLUDED.tags))
   RETURNING id, domain, key, (xmax = 0) AS created, updated_at`;
 exports.GET_KNOWLEDGE = `

package/build/system/index.js

@@ -110,4 +110,5 @@ exports.builtinMcpServerFactories = {
     'long-tail-claude-code': () => Promise.resolve().then(() => __importStar(require('./mcp-servers/claude-code'))).then((m) => m.createClaudeCodeServer()),
     'long-tail-admin': () => Promise.resolve().then(() => __importStar(require('./mcp-servers/admin'))).then((m) => m.createAdminServer()),
     'long-tail-knowledge': () => Promise.resolve().then(() => __importStar(require('./mcp-servers/knowledge'))).then((m) => m.createKnowledgeServer()),
+    'long-tail-schema-exchange': () => Promise.resolve().then(() => __importStar(require('./mcp-servers/schema-exchange'))).then((m) => m.createSchemaExchangeServer()),
 };

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

@@ -64,6 +64,10 @@ const claimAndResolveSchema = zod_1.z.object({
     resolver_id: zod_1.z.string().describe('Identifier for who/what is resolving'),
     payload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload data'),
 });
+const resolveEscalationSchema = zod_1.z.object({
+    escalation_id: zod_1.z.string().describe('The escalation ID to resolve'),
+    payload: zod_1.z.record(zod_1.z.any()).describe('Resolution payload data'),
+});
 const escalateAndWaitSchema = zod_1.z.object({
     role: zod_1.z.string().describe('Target role for the escalation (e.g., "reviewer")'),
     message: zod_1.z.string().describe('Description of what input is needed from the human'),
@@ -218,6 +222,33 @@ async function createHumanQueueServer(options) {
                 }],
         };
     });
+    // ── resolve_escalation ──────────────────────────────────────────────
+    server.registerTool('resolve_escalation', {
+        title: 'Resolve Escalation',
+        description: 'Resolve an already-claimed escalation with a payload. Use when the claim happened externally (e.g. via API).',
+        inputSchema: resolveEscalationSchema,
+    }, async (args) => {
+        const resolved = await escalationService.resolveEscalation(args.escalation_id, args.payload);
+        if (!resolved) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: 'Failed to resolve escalation' }),
+                    }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        escalation_id: resolved.id,
+                        status: resolved.status,
+                        resolved_at: resolved.resolved_at,
+                    }),
+                }],
+        };
+    });
     // ── escalate_and_wait ──────────────────────────────────────────────
     server.registerTool('escalate_and_wait', {
         title: 'Escalate and Wait',

package/build/system/mcp-servers/knowledge.js

@@ -39,10 +39,11 @@ const zod_1 = require("zod");
 const logger_1 = require("../../lib/logger");
 const knowledge = __importStar(require("../activities/knowledge"));
 const storeSchema = zod_1.z.object({
-    domain: zod_1.z.string().describe('Knowledge domain (namespace)'),
-    key: zod_1.z.string().describe('Unique key within domain'),
-    data: zod_1.z.record(zod_1.z.any()).describe('JSONB object payload to store (must be an object, not a string — wrap text as { "description": "..." })'),
-    tags: zod_1.z.array(zod_1.z.string()).optional().describe('Categorization tags'),
+    domain: zod_1.z.string().describe('Top level of a 3-level hierarchy (domain > key > field). Groups related entries by namespace (e.g. "screenshots", "config", "analysis").'),
+    key: zod_1.z.string().describe('Second level. Unique identifier within a domain (e.g. "homepage", "user_profile"). Multiple fields accumulate under the same domain+key.'),
+    field: zod_1.z.string().optional().describe('Third level (leaf). Names a specific field within the domain+key entry (e.g. "url", "analysis", "score"). When provided, data is stored as { [field]: data } and merged into the existing entry. Calls with the same domain+key+field overwrite that field; different fields accumulate additively. Omit to pass data as a full object.'),
+    data: zod_1.z.any().describe('The value to store. When field is provided, this can be any type (string, number, boolean, object, array). When field is omitted, this must be a JSON object whose keys become the fields.'),
+    tags: zod_1.z.array(zod_1.z.string()).optional().describe('Categorization tags (unioned on upsert)'),
 });
 const getSchema = zod_1.z.object({
     domain: zod_1.z.string().describe('Knowledge domain'),
@@ -73,10 +74,38 @@ const appendSchema = zod_1.z.object({
 function registerTools(server) {
     server.registerTool('store_knowledge', {
         title: 'Store Knowledge',
-        description: 'Store or update a knowledge entry. Upserts by domain+key: merges data and unions tags if the entry already exists.',
+        description: 'Store a value in a 3-level additive hierarchy: domain > key > field. ' +
+            'Upserts by domain+key — fields accumulate across calls. ' +
+            'If all three (domain+key+field) match, that field is overwritten. ' +
+            'When field is provided, data can be any type (string, number, etc.). ' +
+            'When field is omitted, data must be an object whose keys become the fields.',
         inputSchema: storeSchema,
     }, async (args) => {
-        const result = await knowledge.storeKnowledge(args);
+        // When field is provided, wrap the data value as { [field]: data }
+        // so it merges into the JSONB column at the field level.
+        // When field is omitted, data must be a plain object — reject strings,
+        // arrays, and primitives that would corrupt the JSONB merge
+        // (Postgres `object || string` produces an array, not a merge).
+        let dataObj;
+        if (args.field != null) {
+            dataObj = { [args.field]: args.data };
+        }
+        else {
+            if (args.data == null || typeof args.data !== 'object' || Array.isArray(args.data)) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                error: 'When field is omitted, data must be a JSON object. Use the field parameter to store strings and other primitives.',
+                            }),
+                        }],
+                };
+            }
+            dataObj = args.data;
+        }
+        const result = await knowledge.storeKnowledge({
+            domain: args.domain, key: args.key, data: dataObj, tags: args.tags,
+        });
         return { content: [{ type: 'text', text: JSON.stringify(result) }] };
     });
     server.registerTool('get_knowledge', {

package/build/system/mcp-servers/schema-exchange.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createSchemaExchangeServer(options?: {
+    name?: string;
+}): Promise<McpServer>;

package/build/system/mcp-servers/schema-exchange.js

@@ -0,0 +1,93 @@
+"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.createSchemaExchangeServer = createSchemaExchangeServer;
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const zod_1 = require("zod");
+const logger_1 = require("../../lib/logger");
+const schemaExchange = __importStar(require("../activities/schema-exchange"));
+const exchangeSchema = zod_1.z.object({
+    endpoint: zod_1.z.string().optional().describe('Service endpoint URL. Supports template variables resolved by the caller (e.g. /Patient/{id}).'),
+    url: zod_1.z.string().optional().describe('Alias for endpoint (either endpoint or url is required).'),
+    method: zod_1.z.string().describe('HTTP method: GET, POST, PUT, DELETE, PATCH.'),
+    headers: zod_1.z.record(zod_1.z.string()).optional().describe('Request headers (e.g. Authorization, Accept, Content-Type).'),
+    query: zod_1.z.record(zod_1.z.string()).optional().describe('Query parameters appended to the URL.'),
+    body: zod_1.z.any().optional().describe('Request body. Validated against request_schema before sending (if provided).'),
+    request_schema: zod_1.z.record(zod_1.z.any()).optional().describe('JSON Schema for the request body. When provided, the body is validated before the request is sent. Validation failure returns immediately — the request is never made.'),
+    response_schema: zod_1.z.record(zod_1.z.any()).optional().describe('JSON Schema for the expected response body. When provided, the response is validated after receiving. The validated flag and validation_errors in the output indicate whether the response matched.'),
+    timeout_ms: zod_1.z.number().optional().describe('Request timeout in milliseconds (default: 30000).'),
+    credential_provider: zod_1.z.string().optional().describe('Credential provider name (e.g. "stripe", "epic", "google"). When set, resolves authentication from the connection store using the calling principal\'s identity. No manual token input needed.'),
+    credential_label: zod_1.z.string().optional().describe('Credential label for multi-credential accounts (default: "default").'),
+    auth_scheme: zod_1.z.string().optional().describe('Authentication scheme (default: "Bearer"). Used with credential_provider to build the auth header value.'),
+    auth_header: zod_1.z.string().optional().describe('Header name for the credential (default: "Authorization"). Some APIs use X-API-Key instead.'),
+});
+const validateSchema = zod_1.z.object({
+    data: zod_1.z.any().describe('The value to validate against the schema.'),
+    schema: zod_1.z.record(zod_1.z.any()).describe('JSON Schema to validate against.'),
+});
+async function createSchemaExchangeServer(options) {
+    const name = options?.name || 'long-tail-schema-exchange';
+    const instance = new mcp_js_1.McpServer({ name, version: '1.0.0' });
+    instance.registerTool('exchange', {
+        title: 'Schema Exchange',
+        description: 'Exchange data with an external service endpoint under schema enforcement. ' +
+            'Validates the request body against request_schema before sending and the response ' +
+            'body against response_schema after receiving. Transport is an implementation detail — ' +
+            'the principle is endpoint + schema + validated data exchange. ' +
+            'Use response_schema to detect API drift: schedule on cron and the validated flag ' +
+            'tells you immediately when the API shape changes.',
+        inputSchema: exchangeSchema,
+    }, async (args) => {
+        try {
+            const result = await schemaExchange.exchange(args);
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (err) {
+            return { content: [{ type: 'text', text: JSON.stringify({ error: err.message }) }], isError: true };
+        }
+    });
+    instance.registerTool('validate_schema', {
+        title: 'Validate Schema',
+        description: 'Validate any value against a JSON Schema without making a network call. ' +
+            'Useful for pre-validating data before storage, checking API response shapes in tests, ' +
+            'or verifying that transforms produce correct output.',
+        inputSchema: validateSchema,
+    }, async (args) => {
+        const result = schemaExchange.validateSchema(args.data, args.schema);
+        return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+    });
+    logger_1.loggerRegistry.info(`[lt-mcp:schema-exchange] ${name} ready (2 tools registered)`);
+    return instance;
+}

package/build/system/seed/server-definitions.d.ts

@@ -2931,10 +2931,13 @@ export declare const SEED_MCP_SERVERS: ({
                     type: string;
                     description: string;
                 };
-                data: {
+                field: {
                     type: string;
                     description: string;
                 };
+                data: {
+                    description: string;
+                };
                 tags: {
                     type: string;
                     items: {
@@ -2964,6 +2967,7 @@ export declare const SEED_MCP_SERVERS: ({
                     type: string;
                     description: string;
                 };
+                field?: undefined;
                 data?: undefined;
                 tags?: undefined;
                 query?: undefined;
@@ -3000,6 +3004,7 @@ export declare const SEED_MCP_SERVERS: ({
                     description: string;
                 };
                 key?: undefined;
+                field?: undefined;
                 data?: undefined;
                 offset?: undefined;
                 path?: undefined;
@@ -3033,6 +3038,7 @@ export declare const SEED_MCP_SERVERS: ({
                     description: string;
                 };
                 key?: undefined;
+                field?: undefined;
                 data?: undefined;
                 query?: undefined;
                 path?: undefined;
@@ -3048,6 +3054,7 @@ export declare const SEED_MCP_SERVERS: ({
             properties: {
                 domain?: undefined;
                 key?: undefined;
+                field?: undefined;
                 data?: undefined;
                 tags?: undefined;
                 query?: undefined;
@@ -3079,6 +3086,7 @@ export declare const SEED_MCP_SERVERS: ({
                 value: {
                     description: string;
                 };
+                field?: undefined;
                 data?: undefined;
                 tags?: undefined;
                 query?: undefined;
@@ -3096,4 +3104,107 @@ export declare const SEED_MCP_SERVERS: ({
     tags: string[];
     compile_hints: string;
     credential_providers: never[];
+} | {
+    name: string;
+    description: string;
+    transport_type: string;
+    transport_config: {
+        builtin: boolean;
+        process: string;
+    };
+    tool_manifest: ({
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                endpoint: {
+                    type: string;
+                    description: string;
+                };
+                method: {
+                    type: string;
+                    description: string;
+                };
+                headers: {
+                    type: string;
+                    description: string;
+                };
+                query: {
+                    type: string;
+                    description: string;
+                };
+                body: {
+                    description: string;
+                };
+                request_schema: {
+                    type: string;
+                    description: string;
+                };
+                response_schema: {
+                    type: string;
+                    description: string;
+                };
+                timeout_ms: {
+                    type: string;
+                    description: string;
+                };
+                credential_provider: {
+                    type: string;
+                    description: string;
+                };
+                credential_label: {
+                    type: string;
+                    description: string;
+                };
+                auth_scheme: {
+                    type: string;
+                    description: string;
+                };
+                auth_header: {
+                    type: string;
+                    description: string;
+                };
+                data?: undefined;
+                schema?: undefined;
+            };
+            required: string[];
+        };
+    } | {
+        name: string;
+        description: string;
+        inputSchema: {
+            type: string;
+            properties: {
+                data: {
+                    description: string;
+                };
+                schema: {
+                    type: string;
+                    description: string;
+                };
+                endpoint?: undefined;
+                method?: undefined;
+                headers?: undefined;
+                query?: undefined;
+                body?: undefined;
+                request_schema?: undefined;
+                response_schema?: undefined;
+                timeout_ms?: undefined;
+                credential_provider?: undefined;
+                credential_label?: undefined;
+                auth_scheme?: undefined;
+                auth_header?: undefined;
+            };
+            required: string[];
+        };
+    })[];
+    metadata: {
+        builtin: boolean;
+        category: string;
+        level?: undefined;
+    };
+    tags: string[];
+    compile_hints: string;
+    credential_providers: never[];
 })[];

package/build/system/seed/server-definitions.js

@@ -192,4 +192,41 @@ exports.SEED_MCP_SERVERS = [
             'list_domains returns all domains with counts, useful for discovering what knowledge exists.',
         credential_providers: [],
     },
+    {
+        name: 'long-tail-schema-exchange',
+        description: 'Schema-driven data exchange with external service endpoints. Validates requests and responses ' +
+            'against JSON Schema. Transport is an implementation detail — the principle is endpoint + schema + ' +
+            'validated exchange. Use this as the building block for wrapping any external API.',
+        transport_type: 'stdio',
+        transport_config: { builtin: true, process: 'in-memory' },
+        tool_manifest: tool_manifests_data_1.SCHEMA_EXCHANGE_TOOLS,
+        metadata: { builtin: true, category: 'data' },
+        tags: ['api', 'schema', 'exchange', 'validation', 'fetch'],
+        compile_hints: 'Schema-driven data exchange for external API endpoints. Validates requests before sending and responses after receiving against JSON Schema. ' +
+            'When building a workflow that calls an external API endpoint, use exchange as the worker activity. ' +
+            'Embed request_schema and response_schema as STATIC values in input.maps (not dynamic inputs — schemas are fixed per endpoint). ' +
+            'Build the endpoint URL using @pipe concat for template variables. Use "url" for the endpoint field name. ' +
+            'CRITICAL — Authorization headers: when the trigger provides a token and you need to build "Bearer {token}", use this EXACT YAML structure for the headers field in input.maps:\n' +
+            '  headers:\n' +
+            '    Authorization:\n' +
+            '      \'@pipe\':\n' +
+            '        - [\'Bearer \', \'{trigger_XXXX.output.data.token}\']\n' +
+            '        - [\'{@string.concat}\']\n' +
+            'NEVER nest @pipe inside @pipe for headers. NEVER use @object.fromEntries for headers. The headers field is a plain object — each header name is a key, and its value can be a static string or a single @pipe expression. ' +
+            'The trigger input_schema should reflect the endpoint\'s dynamic parameters (IDs, search terms, pagination) plus base_url and credentials. ' +
+            'CRITICAL — exchange output structure: the exchange tool returns { status, data, headers, elapsed_ms, validated, validation_errors }. ' +
+            'The actual API response body is inside the "data" field. So to reference a response field like "token", ' +
+            'use {activity.output.data.data.token} (NOT {activity.output.data.token}). ' +
+            'The double .data is because HotMesh wraps activity output in .output.data, and the exchange tool puts the API response in its own .data field. ' +
+            'For job.maps on the last activity: job.maps.token: \'{exchange_xxxx.output.data.data.token}\'. ' +
+            'Also surface validated and status: job.maps.validated: \'{exchange_xxxx.output.data.validated}\', job.maps.status: \'{exchange_xxxx.output.data.status}\'. ' +
+            'response_schema enables self-testing: schedule the compiled tool on cron against a dev/staging server — if validation fails, the API schema changed. ' +
+            'request_schema prevents malformed requests from ever leaving the system. ' +
+            'Both schemas are optional — use response_schema alone for read endpoints, both for write endpoints, neither for exploratory calls. ' +
+            'For authentication, prefer credential_provider over manually wiring tokens in headers. ' +
+            'Set credential_provider to the provider name registered in the connection store (e.g. "stripe", "epic", "google"). ' +
+            'The tool resolves the credential from the calling principal\'s stored connections at the last mile — no token input needed, auto-refreshes expired tokens. ' +
+            'Use auth_scheme for non-Bearer schemes (e.g. "Basic", "Token") and auth_header for APIs that use X-API-Key instead of Authorization.',
+        credential_providers: [],
+    },
 ];