@hotmeshio/long-tail 0.1.7 → 0.1.8

package/build/api/exports.js

@@ -40,6 +40,19 @@ exports.getWorkflowStatus = getWorkflowStatus;
 exports.getWorkflowState = getWorkflowState;
 const exportService = __importStar(require("../services/export"));
 const resolve_1 = require("../services/task/resolve");
+/**
+ * List export jobs with optional filtering, sorting, and pagination.
+ *
+ * @param input.limit — maximum number of jobs to return
+ * @param input.offset — number of jobs to skip for pagination
+ * @param input.entity — filter by entity/workflow type
+ * @param input.search — free-text search across job fields
+ * @param input.status — filter by job status
+ * @param input.sort_by — field name to sort results by
+ * @param input.order — sort direction (asc or desc)
+ * @param input.registered — filter by registration status
+ * @returns `{ status: 200, data: { jobs, total, ... } }` on success
+ */
 async function listJobs(input) {
     try {
         const result = await exportService.listJobs(input);
@@ -49,6 +62,19 @@ async function listJobs(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Export the stored state (hash data) of a workflow.
+ *
+ * Resolves the workflow handle from its ID, then exports its state fields.
+ * Fields can be filtered via allow/block lists. Returns 404 if the workflow
+ * cannot be found or its data has expired.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @param input.allow — whitelist of field names to include in the export
+ * @param input.block — blacklist of field names to exclude from the export
+ * @param input.values — when true, include field values (not just field names)
+ * @returns `{ status: 200, data: ExportedState }` on success
+ */
 async function exportWorkflowState(input) {
     try {
         let resolved;
@@ -72,6 +98,20 @@ async function exportWorkflowState(input) {
         return { status: 500, error: msg };
     }
 }
+/**
+ * Export the full execution tree of a workflow.
+ *
+ * Resolves the workflow handle, then exports its execution graph including
+ * activity inputs and results. Returns 404 if the workflow cannot be found
+ * or its data has expired.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @param input.excludeSystem — when true, omit system-generated activities from the export
+ * @param input.omitResults — when true, exclude activity result payloads
+ * @param input.mode — export mode controlling output format (e.g., tree, flat)
+ * @param input.maxDepth — maximum depth to traverse in the execution tree
+ * @returns `{ status: 200, data: ExecutionExport }` on success
+ */
 async function exportWorkflowExecution(input) {
     try {
         let resolved;
@@ -100,6 +140,15 @@ async function exportWorkflowExecution(input) {
         };
     }
 }
+/**
+ * Get the current status of a workflow (e.g., running, completed, failed).
+ *
+ * Resolves the workflow handle, then queries its status. Returns 404 if the
+ * workflow cannot be found or its data has expired.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @returns `{ status: 200, data: WorkflowStatus }` on success
+ */
 async function getWorkflowStatus(input) {
     try {
         let resolved;
@@ -122,6 +171,15 @@ async function getWorkflowStatus(input) {
         };
     }
 }
+/**
+ * Get the current state data of a workflow.
+ *
+ * Resolves the workflow handle, then retrieves its full state. Returns 404
+ * if the workflow cannot be found or its data has expired.
+ *
+ * @param input.workflowId — the workflow's unique identifier
+ * @returns `{ status: 200, data: WorkflowState }` on success
+ */
 async function getWorkflowState(input) {
     try {
         let resolved;

package/build/api/insight.d.ts

@@ -1,4 +1,18 @@
 import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * Execute a natural-language query against connected MCP servers.
+ *
+ * Requires an LLM API key (OPENAI_API_KEY or ANTHROPIC_API_KEY) to be
+ * configured. Returns 503 if neither is set. Timeouts surface as 504.
+ *
+ * @param input.prompt — the natural-language query to execute (required)
+ * @param input.tags — optional tags to scope which MCP servers are queried
+ * @param input.wait — when true, blocks until the query completes; otherwise returns immediately
+ * @param input.direct — when true, bypasses workflow orchestration and queries the LLM directly
+ * @param input.context — optional additional context forwarded to the LLM
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { ... } }` query result from the MCP pipeline
+ */
 export declare function mcpQuery(input: {
     prompt: string;
     tags?: string[];
@@ -6,6 +20,23 @@ export declare function mcpQuery(input: {
     direct?: boolean;
     context?: any;
 }, auth?: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Generate a workflow definition from a natural-language description.
+ *
+ * Uses an LLM to produce a YAML workflow from the given prompt. Supports
+ * iterative refinement by accepting prior YAML, feedback, and Q&A answers.
+ * Requires an LLM API key. Timeouts surface as 504.
+ *
+ * @param input.prompt — natural-language description of the desired workflow (required)
+ * @param input.tags — optional tags to scope available MCP tools
+ * @param input.wait — when true, blocks until generation completes
+ * @param input.feedback — optional refinement feedback on a previous generation
+ * @param input.prior_yaml — optional YAML from a previous generation to refine
+ * @param input.answers — optional answers to clarifying questions from a prior round
+ * @param input.prior_questions — optional questions from a prior round for context
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { ... } }` generated workflow definition
+ */
 export declare function buildWorkflow(input: {
     prompt: string;
     tags?: string[];
@@ -15,6 +46,20 @@ export declare function buildWorkflow(input: {
     answers?: any;
     prior_questions?: any;
 }, auth?: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Refine an existing workflow definition using feedback.
+ *
+ * Takes a previously generated YAML workflow, the original prompt, and
+ * user feedback, then produces an updated workflow definition.
+ *
+ * @param input.prompt — original natural-language description (required)
+ * @param input.prior_yaml — the YAML workflow to refine (required)
+ * @param input.feedback — user feedback describing desired changes (required)
+ * @param input.tags — optional tags to scope available MCP tools
+ * @param input.wait — when true, blocks until refinement completes
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { ... } }` refined workflow definition
+ */
 export declare function refineWorkflow(input: {
     prompt: string;
     prior_yaml: string;
@@ -22,6 +67,18 @@ export declare function refineWorkflow(input: {
     tags?: string[];
     wait?: boolean;
 }, auth?: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Generate a human-readable description and tags for a workflow.
+ *
+ * Uses an LLM to produce a concise description from the prompt and
+ * optional result metadata. Falls back to the raw prompt as the
+ * description if the LLM call fails.
+ *
+ * @param input.prompt — the workflow prompt or content to describe (required)
+ * @param input.result_title — optional title from the workflow result for additional context
+ * @param input.result_summary — optional summary from the workflow result for additional context
+ * @returns `{ status: 200, data: { description, tags } }` generated description and tag array
+ */
 export declare function describeWorkflow(input: {
     prompt: string;
     result_title?: string;

package/build/api/insight.js

@@ -5,6 +5,20 @@ exports.buildWorkflow = buildWorkflow;
 exports.refineWorkflow = refineWorkflow;
 exports.describeWorkflow = describeWorkflow;
 const insight_1 = require("../services/insight");
+/**
+ * Execute a natural-language query against connected MCP servers.
+ *
+ * Requires an LLM API key (OPENAI_API_KEY or ANTHROPIC_API_KEY) to be
+ * configured. Returns 503 if neither is set. Timeouts surface as 504.
+ *
+ * @param input.prompt — the natural-language query to execute (required)
+ * @param input.tags — optional tags to scope which MCP servers are queried
+ * @param input.wait — when true, blocks until the query completes; otherwise returns immediately
+ * @param input.direct — when true, bypasses workflow orchestration and queries the LLM directly
+ * @param input.context — optional additional context forwarded to the LLM
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { ... } }` query result from the MCP pipeline
+ */
 async function mcpQuery(input, auth) {
     try {
         if (!input.prompt || typeof input.prompt !== 'string') {
@@ -30,6 +44,23 @@ async function mcpQuery(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Generate a workflow definition from a natural-language description.
+ *
+ * Uses an LLM to produce a YAML workflow from the given prompt. Supports
+ * iterative refinement by accepting prior YAML, feedback, and Q&A answers.
+ * Requires an LLM API key. Timeouts surface as 504.
+ *
+ * @param input.prompt — natural-language description of the desired workflow (required)
+ * @param input.tags — optional tags to scope available MCP tools
+ * @param input.wait — when true, blocks until generation completes
+ * @param input.feedback — optional refinement feedback on a previous generation
+ * @param input.prior_yaml — optional YAML from a previous generation to refine
+ * @param input.answers — optional answers to clarifying questions from a prior round
+ * @param input.prior_questions — optional questions from a prior round for context
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { ... } }` generated workflow definition
+ */
 async function buildWorkflow(input, auth) {
     try {
         if (!input.prompt || typeof input.prompt !== 'string') {
@@ -57,6 +88,20 @@ async function buildWorkflow(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Refine an existing workflow definition using feedback.
+ *
+ * Takes a previously generated YAML workflow, the original prompt, and
+ * user feedback, then produces an updated workflow definition.
+ *
+ * @param input.prompt — original natural-language description (required)
+ * @param input.prior_yaml — the YAML workflow to refine (required)
+ * @param input.feedback — user feedback describing desired changes (required)
+ * @param input.tags — optional tags to scope available MCP tools
+ * @param input.wait — when true, blocks until refinement completes
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { ... } }` refined workflow definition
+ */
 async function refineWorkflow(input, auth) {
     try {
         if (!input.prompt || !input.prior_yaml || !input.feedback) {
@@ -76,6 +121,18 @@ async function refineWorkflow(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Generate a human-readable description and tags for a workflow.
+ *
+ * Uses an LLM to produce a concise description from the prompt and
+ * optional result metadata. Falls back to the raw prompt as the
+ * description if the LLM call fails.
+ *
+ * @param input.prompt — the workflow prompt or content to describe (required)
+ * @param input.result_title — optional title from the workflow result for additional context
+ * @param input.result_summary — optional summary from the workflow result for additional context
+ * @returns `{ status: 200, data: { description, tags } }` generated description and tag array
+ */
 async function describeWorkflow(input) {
     try {
         if (!input.prompt) {

package/build/api/maintenance.d.ts

@@ -1,6 +1,21 @@
 import type { LTMaintenanceConfig } from '../types/maintenance';
 import type { LTApiResult } from '../types/sdk';
+/**
+ * Return the current maintenance cron configuration and active state.
+ *
+ * @returns `{ status: 200, data: { config, active } }`
+ */
 export declare function getMaintenanceConfig(): LTApiResult;
+/**
+ * Replace the maintenance configuration and restart the cron.
+ *
+ * Disconnects the current maintenance schedule, registers the new
+ * config, and reconnects. The cron begins executing immediately.
+ *
+ * @param input.schedule — cron expression (e.g. `"0 3 * * *"`)
+ * @param input.rules — maintenance rule definitions
+ * @returns `{ status: 200, data: { config, restarted: true } }`
+ */
 export declare function updateMaintenanceConfig(input: {
     schedule: string;
     rules: LTMaintenanceConfig['rules'];

package/build/api/maintenance.js

@@ -3,12 +3,27 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMaintenanceConfig = getMaintenanceConfig;
 exports.updateMaintenanceConfig = updateMaintenanceConfig;
 const maintenance_1 = require("../services/maintenance");
+/**
+ * Return the current maintenance cron configuration and active state.
+ *
+ * @returns `{ status: 200, data: { config, active } }`
+ */
 function getMaintenanceConfig() {
     return {
         status: 200,
         data: { config: maintenance_1.maintenanceRegistry.config, active: maintenance_1.maintenanceRegistry.hasConfig },
     };
 }
+/**
+ * Replace the maintenance configuration and restart the cron.
+ *
+ * Disconnects the current maintenance schedule, registers the new
+ * config, and reconnects. The cron begins executing immediately.
+ *
+ * @param input.schedule — cron expression (e.g. `"0 3 * * *"`)
+ * @param input.rules — maintenance rule definitions
+ * @returns `{ status: 200, data: { config, restarted: true } }`
+ */
 async function updateMaintenanceConfig(input) {
     try {
         if (!input.schedule || !Array.isArray(input.rules)) {

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

@@ -1,7 +1,24 @@
 import type { LTApiResult } from '../types/sdk';
+/**
+ * List distinct entity types for an app (HotMesh namespace).
+ *
+ * @param input.app_id — HotMesh app ID (e.g. `"durable"`)
+ * @returns `{ status: 200, data: { entities: string[] } }`
+ */
 export declare function listEntities(input: {
     app_id: string;
 }): Promise<LTApiResult>;
+/**
+ * List jobs (workflow executions) for an app, with optional filters.
+ *
+ * @param input.app_id — HotMesh app ID
+ * @param input.limit — max results
+ * @param input.offset — pagination offset
+ * @param input.entity — filter by entity type
+ * @param input.search — full-text search
+ * @param input.status — filter by job status
+ * @returns `{ status: 200, data: { jobs, total } }`
+ */
 export declare function listJobs(input: {
     app_id: string;
     limit?: number;
@@ -10,6 +27,16 @@ export declare function listJobs(input: {
     search?: string;
     status?: string;
 }): Promise<LTApiResult>;
+/**
+ * Get the full execution history for a single job.
+ *
+ * Reconstructs the execution timeline from the HotMesh stream,
+ * including activity calls, signals, and state transitions.
+ *
+ * @param input.jobId — HotMesh job (workflow) ID
+ * @param input.app_id — HotMesh app ID
+ * @returns `{ status: 200, data: <execution timeline> }` or 404
+ */
 export declare function getJobExecution(input: {
     jobId: string;
     app_id: string;

package/build/api/mcp-runs.js

@@ -5,6 +5,12 @@ exports.listJobs = listJobs;
 exports.getJobExecution = getJobExecution;
 const hotmesh_utils_1 = require("../services/hotmesh-utils");
 const mcp_runs_1 = require("../services/mcp-runs");
+/**
+ * List distinct entity types for an app (HotMesh namespace).
+ *
+ * @param input.app_id — HotMesh app ID (e.g. `"durable"`)
+ * @returns `{ status: 200, data: { entities: string[] } }`
+ */
 async function listEntities(input) {
     try {
         if (!input.app_id) {
@@ -20,6 +26,17 @@ async function listEntities(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List jobs (workflow executions) for an app, with optional filters.
+ *
+ * @param input.app_id — HotMesh app ID
+ * @param input.limit — max results
+ * @param input.offset — pagination offset
+ * @param input.entity — filter by entity type
+ * @param input.search — full-text search
+ * @param input.status — filter by job status
+ * @returns `{ status: 200, data: { jobs, total } }`
+ */
 async function listJobs(input) {
     try {
         if (!input.app_id) {
@@ -42,6 +59,16 @@ async function listJobs(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Get the full execution history for a single job.
+ *
+ * Reconstructs the execution timeline from the HotMesh stream,
+ * including activity calls, signals, and state transitions.
+ *
+ * @param input.jobId — HotMesh job (workflow) ID
+ * @param input.app_id — HotMesh app ID
+ * @returns `{ status: 200, data: <execution timeline> }` or 404
+ */
 async function getJobExecution(input) {
     try {
         if (!input.app_id) {

package/build/api/mcp.d.ts

@@ -1,4 +1,15 @@
 import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * List registered MCP servers with optional filtering and pagination.
+ *
+ * @param input.status — filter by server status (e.g. 'active', 'inactive')
+ * @param input.auto_connect — filter by auto-connect setting
+ * @param input.search — free-text search across server names and descriptions
+ * @param input.tags — filter to servers matching any of these tags
+ * @param input.limit — maximum number of results to return
+ * @param input.offset — pagination offset
+ * @returns `{ status: 200, data: { ... } }` paginated list of MCP server records
+ */
 export declare function listMcpServers(input: {
     status?: string;
     auto_connect?: boolean;
@@ -7,6 +18,22 @@ export declare function listMcpServers(input: {
     limit?: number;
     offset?: number;
 }): Promise<LTApiResult>;
+/**
+ * Register a new MCP server.
+ *
+ * Returns 409 if a server with the same name already exists.
+ *
+ * @param input.name — unique display name for the server (required)
+ * @param input.description — optional human-readable description
+ * @param input.transport_type — transport protocol, e.g. 'sse', 'stdio' (required)
+ * @param input.transport_config — transport-specific connection settings (required)
+ * @param input.auto_connect — whether to connect automatically on startup
+ * @param input.metadata — arbitrary key-value metadata
+ * @param input.tags — tags for categorization and filtering
+ * @param input.compile_hints — optional hints used during tool compilation
+ * @param input.credential_providers — OAuth/credential provider identifiers required by this server
+ * @returns `{ status: 201, data: { ... } }` the created MCP server record
+ */
 export declare function createMcpServer(input: {
     name: string;
     description?: string;
@@ -18,32 +45,113 @@ export declare function createMcpServer(input: {
     compile_hints?: any;
     credential_providers?: string[];
 }): Promise<LTApiResult>;
+/**
+ * Test connectivity to an MCP server without persisting it.
+ *
+ * Attempts to establish a connection using the provided transport
+ * configuration and returns the result. On failure, returns a
+ * successful (200) response with `success: false` and the error message.
+ *
+ * @param input.transport_type — transport protocol to test (required)
+ * @param input.transport_config — transport-specific connection settings (required)
+ * @returns `{ status: 200, data: { success, error?, tools } }` connection test result
+ */
 export declare function testConnection(input: {
     transport_type: string;
     transport_config: Record<string, any>;
 }): Promise<LTApiResult>;
+/**
+ * Retrieve a single MCP server by ID.
+ *
+ * @param input.id — the MCP server identifier
+ * @returns `{ status: 200, data: { ... } }` the MCP server record, or 404 if not found
+ */
 export declare function getMcpServer(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Update fields on an existing MCP server.
+ *
+ * Accepts any subset of mutable server fields alongside the required ID.
+ *
+ * @param input.id — the MCP server identifier (required)
+ * @param input.[key] — any mutable server field to update (name, description, transport_config, etc.)
+ * @returns `{ status: 200, data: { ... } }` the updated server record, or 404 if not found
+ */
 export declare function updateMcpServer(input: {
     id: string;
     [key: string]: any;
 }): Promise<LTApiResult>;
+/**
+ * Delete an MCP server by ID.
+ *
+ * @param input.id — the MCP server identifier
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or 404 if not found
+ */
 export declare function deleteMcpServer(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Establish a live connection to a registered MCP server.
+ *
+ * Requires the MCP adapter to be registered in the registry.
+ *
+ * @param input.id — the MCP server identifier to connect
+ * @returns `{ status: 200, data: { connected, serverId } }` confirmation of the connection
+ */
 export declare function connectMcpServer(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Disconnect a live MCP server connection.
+ *
+ * Requires the MCP adapter to be registered in the registry.
+ *
+ * @param input.id — the MCP server identifier to disconnect
+ * @returns `{ status: 200, data: { disconnected, serverId } }` confirmation of the disconnection
+ */
 export declare function disconnectMcpServer(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Check which credential providers are registered vs missing for an MCP server.
+ *
+ * Resolves each credential provider required by the server against the
+ * authenticated user's stored credentials.
+ *
+ * @param input.id — the MCP server identifier
+ * @param auth — authenticated user context used to resolve credentials
+ * @returns `{ status: 200, data: { required, registered, missing } }` credential status arrays
+ */
 export declare function getCredentialStatus(input: {
     id: string;
 }, auth?: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List all tools exposed by a connected MCP server.
+ *
+ * Requires the MCP adapter to be registered and the server to be connected.
+ *
+ * @param input.id — the MCP server identifier
+ * @returns `{ status: 200, data: { tools } }` array of tool descriptors
+ */
 export declare function listMcpServerTools(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Invoke a specific tool on a connected MCP server.
+ *
+ * Passes the tool arguments and an optional auth context (derived from
+ * `execute_as` or the authenticated user) to the MCP adapter. Returns
+ * 422 with `missing_credential` if the tool requires a credential the
+ * user has not registered.
+ *
+ * @param input.id — the MCP server identifier
+ * @param input.toolName — name of the tool to invoke
+ * @param input.arguments — key-value arguments to pass to the tool
+ * @param input.execute_as — optional user ID to impersonate for the tool call
+ * @param auth — authenticated user context
+ * @returns `{ status: 200, data: { result } }` the tool execution result
+ */
 export declare function callMcpTool(input: {
     id: string;
     toolName: string;