@hotmeshio/long-tail 0.1.13 → 0.1.14

package/build/api/files.d.ts

@@ -0,0 +1,13 @@
+import type { LTApiResult } from '../types/sdk';
+export declare function browseFiles(input: {
+    prefix?: string;
+    pageSize?: number;
+    continuationToken?: string;
+}): Promise<LTApiResult>;
+export declare function getFileMetadata(input: {
+    filePath: string;
+}): Promise<LTApiResult>;
+export declare function generateSignedUrl(input: {
+    filePath: string;
+    expiresIn: number;
+}): Promise<LTApiResult>;

package/build/api/files.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browseFiles = browseFiles;
+exports.getFileMetadata = getFileMetadata;
+exports.generateSignedUrl = generateSignedUrl;
+const storage_1 = require("../lib/storage");
+const ALLOWED_EXPIRY = [3600, 21600, 86400, 604800, 2592000]; // 1h, 6h, 24h, 7d, 30d
+async function browseFiles(input) {
+    try {
+        const result = await (0, storage_1.getStorageBackend)().listWithPrefixes(input.prefix, input.pageSize || 100, input.continuationToken);
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+async function getFileMetadata(input) {
+    try {
+        const metadata = await (0, storage_1.getStorageBackend)().getMetadata(input.filePath);
+        return { status: 200, data: { path: input.filePath, ...metadata } };
+    }
+    catch (err) {
+        if (err.message?.includes('not found') || err.name === 'NotFound') {
+            return { status: 404, error: 'File not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
+async function generateSignedUrl(input) {
+    if (!ALLOWED_EXPIRY.includes(input.expiresIn)) {
+        return {
+            status: 400,
+            error: `expiresIn must be one of: ${ALLOWED_EXPIRY.join(', ')} (seconds)`,
+        };
+    }
+    try {
+        const url = await (0, storage_1.getStorageBackend)().getSignedUrl(input.filePath, input.expiresIn);
+        const expiresAt = new Date(Date.now() + input.expiresIn * 1000).toISOString();
+        return { status: 200, data: { url, expiresAt } };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/mcp-runs.d.ts

@@ -26,6 +26,8 @@ export declare function listJobs(input: {
     entity?: string;
     search?: string;
     status?: string;
+    sort_by?: string;
+    order?: string;
 }): Promise<LTApiResult>;
 /**
  * Get the full execution history for a single job.

package/build/api/mcp-runs.js

@@ -49,6 +49,8 @@ async function listJobs(input) {
             entity: input.entity,
             search: input.search,
             status: input.status,
+            sort_by: input.sort_by,
+            order: input.order,
         });
         return { status: 200, data: result };
     }

package/build/api/workflow-sets.d.ts

@@ -75,3 +75,14 @@ export declare function buildWorkflowSet(input: {
 export declare function deployWorkflowSet(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Add additional workflows to an existing set.
+ *
+ * Invokes the planner with the new specification and existing set context.
+ * The planner appends new plan items (offset build_order) and builds them
+ * with sibling schema awareness so composition wiring works.
+ */
+export declare function addToWorkflowSet(input: {
+    id: string;
+    specification: string;
+}, auth?: LTApiAuth): Promise<LTApiResult>;

package/build/api/workflow-sets.js

@@ -6,8 +6,10 @@ exports.getWorkflowSet = getWorkflowSet;
 exports.updateWorkflowSetPlanApi = updateWorkflowSetPlanApi;
 exports.buildWorkflowSet = buildWorkflowSet;
 exports.deployWorkflowSet = deployWorkflowSet;
+exports.addToWorkflowSet = addToWorkflowSet;
 const workflow_sets_1 = require("../services/workflow-sets");
 const insight_1 = require("../services/insight");
+const yaml_workflows_1 = require("./yaml-workflows");
 /**
  * Create a new workflow set and kick off the LLM-powered planner.
  *
@@ -168,3 +170,63 @@ async function deployWorkflowSet(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Add additional workflows to an existing set.
+ *
+ * Invokes the planner with the new specification and existing set context.
+ * The planner appends new plan items (offset build_order) and builds them
+ * with sibling schema awareness so composition wiring works.
+ */
+async function addToWorkflowSet(input, auth) {
+    try {
+        if (!input.specification || typeof input.specification !== 'string') {
+            return { status: 400, error: 'specification is required' };
+        }
+        if (!process.env.OPENAI_API_KEY && !process.env.ANTHROPIC_API_KEY) {
+            return { status: 503, error: 'Workflow planner requires an LLM API key' };
+        }
+        const set = await (0, workflow_sets_1.getWorkflowSet)(input.id);
+        if (!set) {
+            return { status: 404, error: 'Workflow set not found' };
+        }
+        // Gather existing plan items and built workflow schemas
+        const existingPlan = (set.plan || []).map(p => ({
+            name: p.name,
+            description: p.description,
+            namespace: p.namespace,
+        }));
+        const yamlResult = await (0, yaml_workflows_1.listYamlWorkflows)({ set_id: input.id, limit: 100 });
+        const workflows = yamlResult.data?.workflows || [];
+        const existingSchemas = workflows
+            .filter((w) => w.status === 'active' || w.status === 'draft')
+            .map((w) => ({
+            name: w.name,
+            input_schema: w.input_schema || {},
+            output_schema: w.output_schema || {},
+            graph_topic: w.graph_topic,
+        }));
+        // Append the new spec to the set's specification field so the full
+        // history of what was pasted is preserved and visible on step 1.
+        await (0, workflow_sets_1.appendWorkflowSetSpecification)(input.id, input.specification);
+        const plannerResult = await (0, insight_1.startWorkflowPlanner)({
+            specification: input.specification,
+            setId: input.id,
+            wait: false,
+            userId: auth?.userId,
+            existingPlan,
+            existingSchemas,
+        });
+        await (0, workflow_sets_1.updateWorkflowSetSourceWorkflow)(input.id, plannerResult.workflow_id);
+        return {
+            status: 200,
+            data: {
+                ...set,
+                source_workflow_id: plannerResult.workflow_id,
+                planner_workflow_id: plannerResult.workflow_id,
+            },
+        };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/yaml-workflows.d.ts

@@ -200,6 +200,15 @@ export declare function invokeYamlWorkflow(input: {
 export declare function archiveYamlWorkflow(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Restore an archived YAML workflow back to draft status.
+ *
+ * Transitions the workflow from "archived" to "draft" so it can be
+ * redeployed. The workflow must be in "archived" status.
+ */
+export declare function restoreYamlWorkflow(input: {
+    id: string;
+}): Promise<LTApiResult>;
 /**
  * Retrieve the version history for a YAML workflow.
  *

package/build/api/yaml-workflows.js

@@ -45,6 +45,7 @@ exports.deployYamlWorkflow = deployYamlWorkflow;
 exports.activateYamlWorkflow = activateYamlWorkflow;
 exports.invokeYamlWorkflow = invokeYamlWorkflow;
 exports.archiveYamlWorkflow = archiveYamlWorkflow;
+exports.restoreYamlWorkflow = restoreYamlWorkflow;
 exports.getVersionHistory = getVersionHistory;
 exports.getVersionSnapshot = getVersionSnapshot;
 exports.getYamlContent = getYamlContent;
@@ -58,6 +59,7 @@ const yamlWorkers = __importStar(require("../services/yaml-workflow/workers"));
 const invoke_1 = require("../services/yaml-workflow/invoke");
 const task_1 = require("../services/task");
 const cron_1 = require("../services/cron");
+const utils_1 = require("../modules/utils");
 /** Return true if a Postgres error indicates an invalid/missing ID */
 function isNotFoundError(err) {
     const msg = err?.message ?? '';
@@ -143,8 +145,8 @@ async function createYamlWorkflow(input) {
             }
         }
         // Check for topic collision in the target namespace
-        const compileAppId = app_id || 'longtail';
-        const compileTopic = subscribes || name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+        const compileAppId = (0, utils_1.sanitizeServerName)(app_id || 'longtail');
+        const compileTopic = (0, utils_1.sanitizeToolName)(subscribes || name);
         const conflicting = await yamlDb.checkTopicConflict(compileAppId, compileTopic);
         if (conflicting) {
             return {
@@ -220,15 +222,15 @@ async function createYamlWorkflowDirect(input) {
         if (!name || !yaml_content) {
             return { status: 400, error: 'name and yaml_content are required' };
         }
-        // Sanitize name (tool name): lowercase alphanumeric, periods, dashes, underscores
-        const sanitizedName = name.toLowerCase().replace(/[^a-z0-9._-]/g, '');
-        // Sanitize app_id (MCP server name): force lowercase alphanumeric only
-        const targetAppId = (app_id || 'longtail').toLowerCase().replace(/[^a-z0-9]/g, '');
-        // Sanitize graph topic: lowercase alphanumeric, periods, dashes, underscores
-        let graphTopic = (graph_topic || sanitizedName).toLowerCase().replace(/[^a-z0-9._-]/g, '');
+        // Sanitize name (tool name): snake_case only
+        const sanitizedName = (0, utils_1.sanitizeToolName)(name);
+        // Sanitize app_id (MCP server name): lowercase alphanumeric, must start with a letter
+        const targetAppId = (0, utils_1.sanitizeServerName)(app_id || 'longtail');
+        // Sanitize graph topic: snake_case only
+        let graphTopic = (0, utils_1.sanitizeToolName)(graph_topic || sanitizedName);
         const subscribesMatch = yaml_content.match(/subscribes:\s*(.+)/);
         if (subscribesMatch) {
-            graphTopic = subscribesMatch[1].trim().replace(/^['"]|['"]$/g, '').toLowerCase().replace(/[^a-z0-9._-]/g, '');
+            graphTopic = (0, utils_1.sanitizeToolName)(subscribesMatch[1].trim().replace(/^['"]|['"]$/g, ''));
         }
         // Rewrite the subscribes line in the YAML to match the sanitized topic
         let finalYaml = yaml_content;
@@ -438,8 +440,10 @@ async function deployYamlWorkflow(input) {
         if (!wf) {
             return { status: 404, error: 'YAML workflow not found' };
         }
-        // Use the version declared in the YAML (like package.json)
-        const deployVersion = wf.app_version || '1';
+        // Compute the next app-level version for the namespace.
+        // Each deploy increments regardless of individual tool versions —
+        // adding a second tool (v1 of itself) to an app already at v1 produces app v2.
+        const deployVersion = await yamlDb.getNextAppVersion(wf.app_id);
         // Deploy + activate merged YAML for the full app_id
         const siblings = await yamlDb.listYamlWorkflowsByAppId(wf.app_id);
         await yamlDeployer.deployAppId(wf.app_id, deployVersion);
@@ -573,6 +577,31 @@ async function archiveYamlWorkflow(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Restore an archived YAML workflow back to draft status.
+ *
+ * Transitions the workflow from "archived" to "draft" so it can be
+ * redeployed. The workflow must be in "archived" status.
+ */
+async function restoreYamlWorkflow(input) {
+    try {
+        const wf = await yamlDb.getYamlWorkflow(input.id);
+        if (!wf) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        if (wf.status !== 'archived') {
+            return { status: 400, error: 'Only archived workflows can be restored' };
+        }
+        const updated = await yamlDb.updateYamlWorkflowStatus(wf.id, 'draft');
+        return { status: 200, data: updated };
+    }
+    catch (err) {
+        if (isNotFoundError(err)) {
+            return { status: 404, error: 'YAML workflow not found' };
+        }
+        return { status: 500, error: err.message };
+    }
+}
 // ---------------------------------------------------------------------------
 // Versions
 // ---------------------------------------------------------------------------

package/build/lib/storage/local.d.ts

@@ -23,4 +23,19 @@ export declare class LocalStorageBackend implements StorageBackend {
         size: number;
     }>;
     createReadStream(key: string): Promise<NodeJS.ReadableStream>;
+    listWithPrefixes(prefix?: string, pageSize?: number, continuationToken?: string): Promise<{
+        files: Array<{
+            path: string;
+            size: number;
+            modified_at: string;
+        }>;
+        directories: string[];
+        nextToken?: string;
+    }>;
+    getMetadata(key: string): Promise<{
+        size: number;
+        modified_at: string;
+        content_type: string;
+    }>;
+    getSignedUrl(key: string, expiresInSeconds: number): Promise<string>;
 }

package/build/lib/storage/local.js

@@ -32,10 +32,15 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LocalStorageBackend = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const mime_1 = require("./mime");
 const BASE_DIR = process.env.LT_FILE_STORAGE_DIR || './data/files';
 function resolveAndValidate(filePath) {
     const relative = filePath.replace(/^\/+/, '');
@@ -125,5 +130,63 @@ class LocalStorageBackend {
         }
         return fs.createReadStream(resolved);
     }
+    async listWithPrefixes(prefix, pageSize, continuationToken) {
+        ensureBaseDir();
+        const dir = prefix ? resolveAndValidate(prefix) : path.resolve(BASE_DIR);
+        if (!fs.existsSync(dir)) {
+            return { files: [], directories: [] };
+        }
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        const limit = pageSize || 100;
+        const offset = continuationToken ? parseInt(continuationToken, 10) : 0;
+        const allDirs = [];
+        const allFiles = [];
+        for (const entry of entries) {
+            const relativePath = path.relative(path.resolve(BASE_DIR), path.join(dir, entry.name));
+            if (entry.isDirectory()) {
+                allDirs.push(relativePath + '/');
+            }
+            else if (entry.isFile()) {
+                const stat = fs.statSync(path.join(dir, entry.name));
+                allFiles.push({
+                    path: relativePath,
+                    size: stat.size,
+                    modified_at: stat.mtime.toISOString(),
+                });
+            }
+        }
+        // Directories first, then files — paginate the combined list
+        const combined = [...allDirs.map((d) => ({ type: 'dir', value: d })),
+            ...allFiles.map((f) => ({ type: 'file', value: f }))];
+        const page = combined.slice(offset, offset + limit);
+        const hasMore = offset + limit < combined.length;
+        const directories = page.filter((e) => e.type === 'dir').map((e) => e.value);
+        const files = page.filter((e) => e.type === 'file').map((e) => e.value);
+        return {
+            files,
+            directories,
+            nextToken: hasMore ? String(offset + limit) : undefined,
+        };
+    }
+    async getMetadata(key) {
+        const resolved = resolveAndValidate(key);
+        if (!fs.existsSync(resolved)) {
+            throw new Error(`File not found: ${key}`);
+        }
+        const stat = fs.statSync(resolved);
+        return {
+            size: stat.size,
+            modified_at: stat.mtime.toISOString(),
+            content_type: (0, mime_1.mimeFromPath)(key),
+        };
+    }
+    async getSignedUrl(key, expiresInSeconds) {
+        const secret = process.env.JWT_SECRET;
+        if (!secret) {
+            throw new Error('JWT_SECRET not configured — cannot generate signed URLs');
+        }
+        const token = jsonwebtoken_1.default.sign({ filePath: key.replace(/^\/+/, ''), purpose: 'file-download' }, secret, { expiresIn: expiresInSeconds });
+        return `/api/files/${key.replace(/^\/+/, '')}?token=${token}`;
+    }
 }
 exports.LocalStorageBackend = LocalStorageBackend;

package/build/lib/storage/mime.d.ts

@@ -0,0 +1,4 @@
+/** Shared MIME type map used by file serving routes and storage backends. */
+export declare const MIME_TYPES: Record<string, string>;
+/** Resolve MIME type from file extension. */
+export declare function mimeFromPath(filePath: string): string;

package/build/lib/storage/mime.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIME_TYPES = void 0;
+exports.mimeFromPath = mimeFromPath;
+/** Shared MIME type map used by file serving routes and storage backends. */
+exports.MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.pdf': 'application/pdf',
+    '.json': 'application/json',
+    '.txt': 'text/plain',
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.csv': 'text/csv',
+    '.xml': 'application/xml',
+    '.yaml': 'text/yaml',
+    '.yml': 'text/yaml',
+    '.md': 'text/markdown',
+    '.zip': 'application/zip',
+    '.gz': 'application/gzip',
+};
+/** Resolve MIME type from file extension. */
+function mimeFromPath(filePath) {
+    const ext = filePath.includes('.') ? '.' + filePath.split('.').pop().toLowerCase() : '';
+    return exports.MIME_TYPES[ext] || 'application/octet-stream';
+}

package/build/lib/storage/s3.d.ts

@@ -1,6 +1,7 @@
 import type { StorageBackend } from './types';
 export declare class S3StorageBackend implements StorageBackend {
     private client;
+    private signingClient;
     private bucket;
     private bucketReady;
     constructor();
@@ -28,4 +29,19 @@ export declare class S3StorageBackend implements StorageBackend {
         size: number;
     }>;
     createReadStream(key: string): Promise<NodeJS.ReadableStream>;
+    listWithPrefixes(prefix?: string, pageSize?: number, continuationToken?: string): Promise<{
+        files: Array<{
+            path: string;
+            size: number;
+            modified_at: string;
+        }>;
+        directories: string[];
+        nextToken?: string;
+    }>;
+    getMetadata(key: string): Promise<{
+        size: number;
+        modified_at: string;
+        content_type: string;
+    }>;
+    getSignedUrl(key: string, expiresInSeconds: number): Promise<string>;
 }

package/build/lib/storage/s3.js

@@ -38,10 +38,14 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const client_s3_1 = require("@aws-sdk/client-s3");
+const s3_request_presigner_1 = require("@aws-sdk/s3-request-presigner");
+const mime_1 = require("./mime");
 const STAGING_DIR = path.join(os.tmpdir(), 'lt-staging');
 class S3StorageBackend {
     constructor() {
+        this.signingClient = null;
         const endpoint = process.env.LT_S3_ENDPOINT;
+        const publicEndpoint = process.env.LT_S3_PUBLIC_ENDPOINT;
         const region = process.env.LT_S3_REGION || 'us-east-1';
         const forcePathStyle = process.env.LT_S3_FORCE_PATH_STYLE === 'true';
         this.bucket = process.env.LT_S3_BUCKET || 'long-tail-files';
@@ -63,6 +67,12 @@ class S3StorageBackend {
             };
         }
         this.client = new client_s3_1.S3Client(clientConfig);
+        // Signed URLs need the public-facing endpoint so browsers can reach them.
+        // In Docker, LT_S3_ENDPOINT is the internal hostname (e.g. http://minio:9000)
+        // while LT_S3_PUBLIC_ENDPOINT is the host-accessible URL (e.g. http://localhost:9000).
+        if (publicEndpoint && publicEndpoint !== endpoint) {
+            this.signingClient = new client_s3_1.S3Client({ ...clientConfig, endpoint: publicEndpoint });
+        }
         this.bucketReady = this.ensureBucket();
     }
     async ensureBucket() {
@@ -168,6 +178,66 @@ class S3StorageBackend {
         }));
         return resp.Body;
     }
+    async listWithPrefixes(prefix, pageSize, continuationToken) {
+        await this.bucketReady;
+        const normalizedPrefix = prefix ? normalizeKey(prefix) : undefined;
+        const listPrefix = normalizedPrefix
+            ? (normalizedPrefix.endsWith('/') ? normalizedPrefix : normalizedPrefix + '/')
+            : undefined;
+        const resp = await this.client.send(new client_s3_1.ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: listPrefix,
+            Delimiter: '/',
+            MaxKeys: pageSize || 100,
+            ContinuationToken: continuationToken || undefined,
+        }));
+        const files = [];
+        for (const obj of resp.Contents || []) {
+            if (!obj.Key)
+                continue;
+            // Skip the prefix itself if it appears as a "file"
+            if (obj.Key === listPrefix)
+                continue;
+            files.push({
+                path: obj.Key,
+                size: obj.Size || 0,
+                modified_at: obj.LastModified?.toISOString() || new Date().toISOString(),
+            });
+        }
+        const directories = [];
+        for (const cp of resp.CommonPrefixes || []) {
+            if (cp.Prefix) {
+                directories.push(cp.Prefix);
+            }
+        }
+        return {
+            files,
+            directories,
+            nextToken: resp.NextContinuationToken || undefined,
+        };
+    }
+    async getMetadata(key) {
+        await this.bucketReady;
+        const resp = await this.client.send(new client_s3_1.HeadObjectCommand({
+            Bucket: this.bucket,
+            Key: normalizeKey(key),
+        }));
+        return {
+            size: resp.ContentLength || 0,
+            modified_at: resp.LastModified?.toISOString() || new Date().toISOString(),
+            content_type: resp.ContentType || (0, mime_1.mimeFromPath)(key),
+        };
+    }
+    async getSignedUrl(key, expiresInSeconds) {
+        await this.bucketReady;
+        const command = new client_s3_1.GetObjectCommand({
+            Bucket: this.bucket,
+            Key: normalizeKey(key),
+        });
+        // Use the public-facing client so the signed URL hostname is reachable from browsers
+        const client = this.signingClient || this.client;
+        return (0, s3_request_presigner_1.getSignedUrl)(client, command, { expiresIn: expiresInSeconds });
+    }
 }
 exports.S3StorageBackend = S3StorageBackend;
 /** Strip leading slashes to create a valid S3 key; reject traversal. */

package/build/lib/storage/types.d.ts

@@ -38,4 +38,22 @@ export interface StorageBackend {
     }>;
     /** Create a readable stream for HTTP serving. */
     createReadStream(key: string): Promise<NodeJS.ReadableStream>;
+    /** List files and directory prefixes under a path (for directory browsing). */
+    listWithPrefixes(prefix?: string, pageSize?: number, continuationToken?: string): Promise<{
+        files: Array<{
+            path: string;
+            size: number;
+            modified_at: string;
+        }>;
+        directories: string[];
+        nextToken?: string;
+    }>;
+    /** Get file metadata without reading content. */
+    getMetadata(key: string): Promise<{
+        size: number;
+        modified_at: string;
+        content_type: string;
+    }>;
+    /** Generate a time-limited signed URL for unauthenticated file access. */
+    getSignedUrl(key: string, expiresInSeconds: number): Promise<string>;
 }

package/build/modules/utils.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Sanitize a value for use as an MCP tool name or HotMesh graph topic
+ * (the `subscribes` field in a YAML DAG).
+ *
+ * ## Why snake_case
+ *
+ * MCP tool names become the `subscribes` topic in a HotMesh YAML DAG.
+ * That topic is how the system routes incoming messages to the correct
+ * workflow. The same value also appears in `worker` activity `topic`
+ * fields and in the `mcp_<server>_<tool>` activity type encoding.
+ *
+ * Because the activity type uses underscores to delimit server from tool
+ * (`mcp_longtail_take_screenshot`), both the server name (letters only)
+ * and the tool name (snake_case) must avoid dashes, dots, or other
+ * separators that would create ambiguity when parsing activity types.
+ *
+ * ## Risks if violated
+ *
+ * - Dashes in tool names cause `parseMcpActivityType()` to mis-split
+ *   the server/tool boundary in activity type strings.
+ * - Dots or special chars can produce invalid HotMesh topic subscriptions
+ *   that silently fail to route.
+ * - Mixed conventions across entry points (builder, planner, discovery)
+ *   cause topic collisions or deployment failures when merging workflows
+ *   into a single app namespace.
+ *
+ * ## Contract
+ *
+ * Input:  any string (LLM output, user input, URL slug, etc.)
+ * Output: lowercase letters, digits, and underscores only.
+ *         Runs of non-alphanumeric chars become a single underscore.
+ *         No leading or trailing underscores.
+ *
+ * This is the ONE canonical backend implementation. The dashboard has an
+ * identical copy at `dashboard/src/lib/sanitize.ts`. No other file in
+ * the platform may inline this logic.
+ */
+export declare function sanitizeToolName(value: string): string;
+/**
+ * Sanitize a value for use as an MCP server name (the HotMesh `app.id`
+ * and Postgres schema name that isolates one server's workflows from another).
+ *
+ * ## Why lowercase alphanumeric, leading letter
+ *
+ * The server name becomes:
+ *   1. A Postgres schema name — must start with a letter; letters and digits
+ *      are safe without quoting.
+ *   2. The first segment in the `mcp_<server>_<tool>` activity type encoding.
+ *      Because underscores delimit server from tool, the server name itself
+ *      must never contain underscores (or dashes, dots, etc.).
+ *
+ * ## Risks if violated
+ *
+ * - Underscores or dashes in the server name make `parseMcpActivityType()`
+ *   split incorrectly — it uses the first `_` after `mcp_` as the boundary.
+ * - A leading digit produces an invalid Postgres schema name that requires
+ *   quoting and breaks HotMesh's unquoted SQL paths.
+ * - Special characters can cause silent deployment failures or schema
+ *   creation errors.
+ *
+ * ## Contract
+ *
+ * Input:  any string (LLM suggestion, user input, etc.)
+ * Output: lowercase letters and digits only, guaranteed to start with a letter.
+ *         All non-alphanumeric chars are stripped (not replaced).
+ *         Leading digits are stripped so the result starts with a letter.
+ *         Default: 'longtail' if the result is empty after sanitization.
+ *
+ * This is the ONE canonical backend implementation. The dashboard has an
+ * identical copy at `dashboard/src/lib/sanitize.ts`. No other file in
+ * the platform may inline this logic.
+ */
+export declare function sanitizeServerName(value: string): string;