@hotmeshio/long-tail 0.1.13 → 0.1.14

package/build/services/yaml-workflow/pipeline/build/index.js

@@ -7,7 +7,7 @@
  * Falls back to mechanical heuristics when no plan is available.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sanitizeName = exports.capToolArguments = void 0;
+exports.sanitizeToolName = exports.capToolArguments = void 0;
 exports.build = build;
 const input_analyzer_1 = require("../../input-analyzer");
 const utils_1 = require("./utils");
@@ -17,7 +17,8 @@ const dag_1 = require("./dag");
 // Re-export public utilities used by other modules
 var utils_2 = require("./utils");
 Object.defineProperty(exports, "capToolArguments", { enumerable: true, get: function () { return utils_2.capToolArguments; } });
-Object.defineProperty(exports, "sanitizeName", { enumerable: true, get: function () { return utils_2.sanitizeName; } });
+var utils_3 = require("../../../../modules/utils");
+Object.defineProperty(exports, "sanitizeToolName", { enumerable: true, get: function () { return utils_3.sanitizeToolName; } });
 /**
  * Build pipeline stage: construct the HotMesh YAML DAG.
  *

package/build/services/yaml-workflow/pipeline/build/utils.d.ts

@@ -8,8 +8,6 @@
 export declare function keysRelated(a: string, b: string): boolean;
 /** Cap `limit` in tool arguments to avoid sending huge payloads to downstream LLM steps. */
 export declare function capToolArguments(args: Record<string, unknown>): Record<string, unknown>;
-/** Sanitize a name for use in HotMesh app IDs and topics. */
-export declare function sanitizeName(name: string): string;
 /** Convert a snake_case/camelCase field name to a readable label. */
 export declare function humanize(name: string): string;
 /**

package/build/services/yaml-workflow/pipeline/build/utils.js

@@ -5,7 +5,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.keysRelated = keysRelated;
 exports.capToolArguments = capToolArguments;
-exports.sanitizeName = sanitizeName;
 exports.humanize = humanize;
 exports.inferSchema = inferSchema;
 exports.buildInputMappings = buildInputMappings;
@@ -35,13 +34,6 @@ function capToolArguments(args) {
     }
     return capped;
 }
-/** Sanitize a name for use in HotMesh app IDs and topics. */
-function sanitizeName(name) {
-    return name
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-|-$/g, '');
-}
 /** Convert a snake_case/camelCase field name to a readable label. */
 function humanize(name) {
     return name

package/build/services/yaml-workflow/sql.d.ts

@@ -6,7 +6,8 @@ export declare const UPDATE_YAML_WORKFLOW_VERSION = "\n  UPDATE lt_yaml_workflow
 export declare const DELETE_YAML_WORKFLOW = "\n  DELETE FROM lt_yaml_workflows WHERE id = $1";
 export declare const GET_ACTIVE_YAML_WORKFLOWS = "\n  SELECT * FROM lt_yaml_workflows\n  WHERE status = 'active'\n  ORDER BY name";
 export declare const LIST_BY_APP_ID = "\n  SELECT * FROM lt_yaml_workflows\n  WHERE app_id = $1 AND status != 'archived'\n  ORDER BY name";
-export declare const GET_DISTINCT_APP_IDS = "\n  SELECT DISTINCT app_id FROM lt_yaml_workflows\n  WHERE status != 'archived'\n  ORDER BY app_id";
+export declare const GET_MAX_APP_VERSION = "\n  SELECT COALESCE(MAX(CAST(app_version AS INTEGER)), 0) AS max_version\n  FROM lt_yaml_workflows\n  WHERE app_id = $1 AND status != 'archived'";
+export declare const GET_DISTINCT_APP_IDS = "\n  SELECT DISTINCT app_id FROM (\n    SELECT app_id FROM lt_yaml_workflows WHERE status != 'archived'\n    UNION\n    SELECT app_id FROM hmsh_applications WHERE active = true\n  ) all_apps\n  ORDER BY app_id";
 export declare const MARK_CONTENT_DEPLOYED = "\n  UPDATE lt_yaml_workflows\n  SET deployed_content_version = content_version\n  WHERE id = $1";
 export declare const MARK_APP_ID_CONTENT_DEPLOYED = "\n  UPDATE lt_yaml_workflows\n  SET deployed_content_version = content_version\n  WHERE app_id = $1 AND status != 'archived'";
 export declare const CREATE_VERSION_SNAPSHOT = "\n  INSERT INTO lt_yaml_workflow_versions\n    (workflow_id, version, yaml_content, activity_manifest, input_schema, output_schema, input_field_meta, change_summary)\n  VALUES ($1, $2, $3, $4, $5, $6, $7, $8)\n  ON CONFLICT (workflow_id, version) DO NOTHING\n  RETURNING *";

package/build/services/yaml-workflow/sql.js

@@ -1,7 +1,7 @@
 "use strict";
 // ─── YAML workflow CRUD ─────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FIND_BY_TAGS_ALL = exports.FIND_BY_TAGS_ANY = exports.GET_CRON_SCHEDULED_WORKFLOWS = exports.CLEAR_CRON_SCHEDULE = exports.UPDATE_CRON_SCHEDULE = exports.UPDATE_STATUS_SUFFIX = exports.UPDATE_STATUS_BASE = exports.GET_VERSION_SNAPSHOT = exports.DISCOVER_WORKFLOWS = exports.LIST_VERSIONS = exports.COUNT_VERSIONS = exports.CREATE_VERSION_SNAPSHOT = exports.MARK_APP_ID_CONTENT_DEPLOYED = exports.MARK_CONTENT_DEPLOYED = exports.GET_DISTINCT_APP_IDS = exports.LIST_BY_APP_ID = exports.GET_ACTIVE_YAML_WORKFLOWS = exports.DELETE_YAML_WORKFLOW = exports.UPDATE_YAML_WORKFLOW_VERSION = exports.GET_YAML_WORKFLOW_BY_NAME = exports.GET_YAML_WORKFLOW = exports.CHECK_TOPIC_UNIQUE = exports.CREATE_YAML_WORKFLOW = void 0;
+exports.FIND_BY_TAGS_ALL = exports.FIND_BY_TAGS_ANY = exports.GET_CRON_SCHEDULED_WORKFLOWS = exports.CLEAR_CRON_SCHEDULE = exports.UPDATE_CRON_SCHEDULE = exports.UPDATE_STATUS_SUFFIX = exports.UPDATE_STATUS_BASE = exports.GET_VERSION_SNAPSHOT = exports.DISCOVER_WORKFLOWS = exports.LIST_VERSIONS = exports.COUNT_VERSIONS = exports.CREATE_VERSION_SNAPSHOT = exports.MARK_APP_ID_CONTENT_DEPLOYED = exports.MARK_CONTENT_DEPLOYED = exports.GET_DISTINCT_APP_IDS = exports.GET_MAX_APP_VERSION = exports.LIST_BY_APP_ID = exports.GET_ACTIVE_YAML_WORKFLOWS = exports.DELETE_YAML_WORKFLOW = exports.UPDATE_YAML_WORKFLOW_VERSION = exports.GET_YAML_WORKFLOW_BY_NAME = exports.GET_YAML_WORKFLOW = exports.CHECK_TOPIC_UNIQUE = exports.CREATE_YAML_WORKFLOW = void 0;
 exports.CREATE_YAML_WORKFLOW = `
   INSERT INTO lt_yaml_workflows
     (name, description, app_id, app_version, source_workflow_id,
@@ -32,9 +32,16 @@ exports.LIST_BY_APP_ID = `
   SELECT * FROM lt_yaml_workflows
   WHERE app_id = $1 AND status != 'archived'
   ORDER BY name`;
+exports.GET_MAX_APP_VERSION = `
+  SELECT COALESCE(MAX(CAST(app_version AS INTEGER)), 0) AS max_version
+  FROM lt_yaml_workflows
+  WHERE app_id = $1 AND status != 'archived'`;
 exports.GET_DISTINCT_APP_IDS = `
-  SELECT DISTINCT app_id FROM lt_yaml_workflows
-  WHERE status != 'archived'
+  SELECT DISTINCT app_id FROM (
+    SELECT app_id FROM lt_yaml_workflows WHERE status != 'archived'
+    UNION
+    SELECT app_id FROM hmsh_applications WHERE active = true
+  ) all_apps
   ORDER BY app_id`;
 exports.MARK_CONTENT_DEPLOYED = `
   UPDATE lt_yaml_workflows

package/build/system/activities/schema-exchange.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+/**
+ * Validate data against a JSON Schema.
+ *
+ * Returns a list of human-readable error strings (empty when valid).
+ */
+export declare function validateSchema(data: unknown, schema: Record<string, unknown>): {
+    valid: boolean;
+    errors: string[];
+};
+/**
+ * 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.
+ */
+export declare function exchange(args: {
+    endpoint?: string;
+    url?: string;
+    method: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    body?: unknown;
+    request_schema?: Record<string, unknown>;
+    response_schema?: Record<string, unknown>;
+    timeout_ms?: number;
+    credential_provider?: string;
+    credential_label?: string;
+    auth_scheme?: string;
+    auth_header?: string;
+}): Promise<{
+    status: number;
+    data: unknown;
+    headers: Record<string, string>;
+    elapsed_ms: number;
+    validated: boolean;
+    validation_errors: string[];
+}>;

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/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;
+}