@hotmeshio/long-tail 0.1.7 → 0.1.9

package/build/api/workflows.js

@@ -59,16 +59,30 @@ function isResolveError(err) {
     return err?.message?.includes('Cannot resolve workflow');
 }
 // ── Invocation ──────────────────────────────────────────────────────────────
+/**
+ * Start a workflow — proxy for `Durable.Client.workflow.start()`.
+ *
+ * Resolves the task queue, enforces auth/role constraints, builds the
+ * LTEnvelope with IAM context, and delegates to the Durable client.
+ * Any WorkflowOptions field (workflowId, expire, entity, namespace,
+ * search, signalIn, pending, etc.) can be passed via `options` and
+ * flows through to the Durable client unchanged.
+ *
+ * @see https://docs.hotmesh.io/types/types_durable.WorkflowOptions.html
+ */
 async function invokeWorkflow(input, auth) {
     try {
-        await (0, workflow_invocation_1.checkInvocationRoles)(input.type, auth.userId);
+        await (0, workflow_invocation_1.checkInvocationRoles)(input.type, auth.userId, auth.role);
         const result = await (0, workflow_invocation_1.invokeWorkflow)({
             workflowType: input.type,
             data: input.data || {},
             metadata: input.metadata,
             executeAs: input.execute_as,
+            options: input.options,
             auth: {
                 userId: auth.userId,
+                role: auth.role,
+                scopes: auth.scopes,
             },
         });
         return {
@@ -81,6 +95,15 @@ async function invokeWorkflow(input, auth) {
         return { status, error: err.message };
     }
 }
+/**
+ * Get the execution status of a workflow.
+ *
+ * Returns the HotMesh status code (0 = completed, 1 = running).
+ * Resolves the workflow handle via task record or worker registry.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { workflowId, status } }` or 404
+ */
 async function getWorkflowStatus(input) {
     try {
         const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId);
@@ -98,6 +121,15 @@ async function getWorkflowStatus(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Get the result of a completed workflow.
+ *
+ * Returns 202 if the workflow is still running, 200 with the result
+ * payload when complete. Never blocks — always returns immediately.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { workflowId, result } }` or 202 if running
+ */
 async function getWorkflowResult(input) {
     try {
         const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId);
@@ -122,6 +154,14 @@ async function getWorkflowResult(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Terminate a running workflow.
+ *
+ * Interrupts the workflow execution immediately via HotMesh.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: { terminated: true, workflowId } }` or 404
+ */
 async function terminateWorkflow(input) {
     try {
         const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId);
@@ -139,6 +179,15 @@ async function terminateWorkflow(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Export the full state of a workflow.
+ *
+ * Returns the serialized workflow state including all activity
+ * results, signals, and metadata.
+ *
+ * @param input.workflowId — HotMesh workflow ID
+ * @returns `{ status: 200, data: <exported state> }` or 404
+ */
 async function exportWorkflow(input) {
     try {
         const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId);
@@ -152,6 +201,12 @@ async function exportWorkflow(input) {
     }
 }
 // ── Discovery ───────────────────────────────────────────────────────────────
+/**
+ * List active workflow workers with their registration status.
+ *
+ * @param input.include_system — include system workflows (default: false)
+ * @returns `{ status: 200, data: { workers: [{ name, task_queue, registered, system }] } }`
+ */
 async function listWorkers(input) {
     try {
         const activeWorkers = (0, registry_1.getRegisteredWorkers)();
@@ -172,6 +227,16 @@ async function listWorkers(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Discover all known workflow types from workers, history, and config.
+ *
+ * Merges three sources: active in-memory workers, historical entities
+ * from the durable jobs table, and registered workflow configs. Returns
+ * a unified list with status flags for each type.
+ *
+ * @param input.include_system — include system workflows (default: false)
+ * @returns `{ status: 200, data: { workflows: [{ workflow_type, task_queue, registered, active, invocable, ... }] } }`
+ */
 async function listDiscoveredWorkflows(input) {
     try {
         // 1. Active workers from in-memory registry
@@ -197,9 +262,14 @@ async function listDiscoveredWorkflows(input) {
             .map((workflowType) => {
             const config = configMap.get(workflowType);
             const worker = activeWorkers.get(workflowType);
+            const hasCertification = !!(config &&
+                ((config.roles?.length ?? 0) > 0 ||
+                    (config.consumes?.length ?? 0) > 0));
+            const tier = !config ? 'durable' : hasCertification ? 'certified' : 'configured';
             return {
                 workflow_type: workflowType,
                 task_queue: config?.task_queue ?? worker?.taskQueue ?? null,
+                tier,
                 registered: !!config,
                 active: !!worker,
                 invocable: config?.invocable ?? !!worker,
@@ -216,6 +286,11 @@ async function listDiscoveredWorkflows(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List all cron-scheduled workflows and their active state.
+ *
+ * @returns `{ status: 200, data: { schedules: [{ workflow_type, cron_schedule, active, ... }] } }`
+ */
 async function getCronStatus() {
     try {
         const configs = await configService.listWorkflowConfigs();
@@ -237,6 +312,11 @@ async function getCronStatus() {
     }
 }
 // ── Configuration ───────────────────────────────────────────────────────────
+/**
+ * List all registered workflow configurations.
+ *
+ * @returns `{ status: 200, data: { workflows: LTWorkflowConfig[] } }`
+ */
 async function listWorkflowConfigs() {
     try {
         const configs = await configService.listWorkflowConfigs();
@@ -246,6 +326,12 @@ async function listWorkflowConfigs() {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Get a single workflow configuration by type.
+ *
+ * @param input.type — workflow type name (e.g. `"reviewContent"`)
+ * @returns `{ status: 200, data: <config> }` or 404
+ */
 async function getWorkflowConfig(input) {
     try {
         const config = await configService.getWorkflowConfig(input.type);
@@ -258,6 +344,27 @@ async function getWorkflowConfig(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Create or replace a workflow configuration.
+ *
+ * Invalidates the config cache and restarts the cron schedule if one
+ * is defined. Idempotent — safe to call repeatedly with the same input.
+ *
+ * @param input.type — workflow type name
+ * @param input.invocable — whether the workflow can be started via the API
+ * @param input.task_queue — HotMesh task queue
+ * @param input.default_role — default escalation role
+ * @param input.description — human-readable description
+ * @param input.execute_as — service account for proxy invocation
+ * @param input.roles — roles that can resolve escalations
+ * @param input.invocation_roles — roles that can invoke this workflow
+ * @param input.consumes — workflow types whose data this workflow consumes
+ * @param input.tool_tags — MCP tool tags for discovery
+ * @param input.envelope_schema — JSON Schema for envelope.data validation
+ * @param input.resolver_schema — JSON Schema for resolver payload validation
+ * @param input.cron_schedule — cron expression for scheduled execution
+ * @returns `{ status: 200, data: <saved config> }`
+ */
 async function upsertWorkflowConfig(input) {
     try {
         const config = await configService.upsertWorkflowConfig({
@@ -283,6 +390,15 @@ async function upsertWorkflowConfig(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Delete a workflow configuration.
+ *
+ * Removes the config record and invalidates the cache. Active workers
+ * continue running — this only removes the config/interceptor binding.
+ *
+ * @param input.type — workflow type name
+ * @returns `{ status: 200, data: { deleted: true, workflow_type } }` or 404
+ */
 async function deleteWorkflowConfig(input) {
     try {
         const deleted = await configService.deleteWorkflowConfig(input.type);

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

@@ -1,4 +1,19 @@
 import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * List YAML workflows with optional filtering and pagination.
+ *
+ * Delegates to the DB layer. Returns 404 when a filter references an invalid UUID.
+ *
+ * @param input.status — lifecycle filter (draft, deployed, active, archived)
+ * @param input.graph_topic — filter by the HotMesh subscription topic
+ * @param input.app_id — filter by namespace (MCP server name)
+ * @param input.search — free-text search across workflow name/description
+ * @param input.source_workflow_id — filter by the execution trace this workflow was compiled from
+ * @param input.set_id — filter by compositional set membership
+ * @param input.limit — max rows to return
+ * @param input.offset — pagination offset
+ * @returns `{ status: 200, data: YamlWorkflow[] }` matching workflows
+ */
 export declare function listYamlWorkflows(input: {
     status?: string;
     graph_topic?: string;
@@ -9,6 +24,25 @@ export declare function listYamlWorkflows(input: {
     limit?: number;
     offset?: number;
 }): Promise<LTApiResult>;
+/**
+ * Compile an execution trace into a new YAML workflow (draft).
+ *
+ * Validates that the source execution did not exhaust its tool rounds, checks for
+ * topic collisions in the target namespace, then delegates to the LLM-based YAML
+ * generator. The resulting YAML, schemas, and activity manifest are persisted as a
+ * new draft record. Auto-derived tags are merged with any user-supplied tags.
+ *
+ * @param input.workflow_id — ID of the source execution trace to compile from
+ * @param input.task_queue — HotMesh task queue the source execution ran on
+ * @param input.workflow_name — type name of the source workflow
+ * @param input.name — tool name for the new workflow (no dashes; used to derive the topic)
+ * @param input.description — human-readable description passed to the generator
+ * @param input.app_id — target namespace (defaults to "longtail")
+ * @param input.subscribes — explicit subscription topic override (otherwise derived from name)
+ * @param input.tags — additional tags to merge with auto-derived tags
+ * @param input.compilation_feedback — natural-language feedback to steer the LLM compilation
+ * @returns `{ status: 201, data: YamlWorkflow }` the newly created draft record
+ */
 export declare function createYamlWorkflow(input: {
     workflow_id: string;
     task_queue: string;
@@ -20,6 +54,23 @@ export declare function createYamlWorkflow(input: {
     tags?: string[];
     compilation_feedback?: string;
 }): Promise<LTApiResult>;
+/**
+ * Create a YAML workflow directly from user-supplied YAML content (no compilation).
+ *
+ * Sanitizes the name, app_id, and graph_topic to lowercase alphanumeric characters.
+ * Rewrites the `subscribes`, `id`, and `topic` fields inside the YAML to match the
+ * sanitized values. Checks for topic collisions before persisting.
+ *
+ * @param input.name — tool name (sanitized to lowercase alphanumeric, periods, dashes, underscores)
+ * @param input.description — human-readable description; also stored as original_prompt
+ * @param input.yaml_content — raw HotMesh YAML definition
+ * @param input.input_schema — JSON Schema describing the workflow's input (defaults to empty object)
+ * @param input.activity_manifest — list of activity declarations (defaults to empty array)
+ * @param input.tags — classification tags (defaults to empty array)
+ * @param input.app_id — target namespace / MCP server name (defaults to "longtail", sanitized to lowercase alphanumeric)
+ * @param input.graph_topic — subscription topic override (defaults to sanitized name; overridden by `subscribes` in YAML if present)
+ * @returns `{ status: 200, data: YamlWorkflow }` the persisted workflow record
+ */
 export declare function createYamlWorkflowDirect(input: {
     name: string;
     description?: string;
@@ -30,28 +81,105 @@ export declare function createYamlWorkflowDirect(input: {
     app_id?: string;
     graph_topic?: string;
 }): Promise<LTApiResult>;
+/**
+ * Retrieve all distinct app_id namespaces that have at least one YAML workflow.
+ *
+ * @returns `{ status: 200, data: { app_ids: string[] } }` sorted list of namespace identifiers
+ */
 export declare function getAppIds(): Promise<LTApiResult>;
+/**
+ * Fetch a single YAML workflow by its primary key.
+ *
+ * @param input.id — UUID of the workflow record
+ * @returns `{ status: 200, data: YamlWorkflow }` the full workflow record, or 404 if not found
+ */
 export declare function getYamlWorkflow(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Partially update a YAML workflow record.
+ *
+ * Accepts arbitrary fields beyond `id` and forwards them to the DB update layer.
+ *
+ * @param input.id — UUID of the workflow to update
+ * @param input.[key] — any mutable workflow fields (name, description, yaml_content, tags, etc.)
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated record, or 404 if not found
+ */
 export declare function updateYamlWorkflow(input: {
     id: string;
     [key: string]: any;
 }): Promise<LTApiResult>;
+/**
+ * Re-compile an existing YAML workflow from its original execution trace.
+ *
+ * Looks up the source workflow reference, re-runs the LLM-based YAML generator, and
+ * overwrites the YAML content, schemas, manifest, and tags in place. When
+ * compilation_feedback is provided, the current YAML is passed as priorFailedYaml so
+ * the generator can incorporate the feedback. Archived workflows cannot be regenerated.
+ *
+ * @param input.id — UUID of the workflow to regenerate
+ * @param input.task_queue — override the task queue (otherwise resolved from the source task record)
+ * @param input.compilation_feedback — natural-language feedback to steer the re-compilation
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated record with new YAML content
+ */
 export declare function regenerateYamlWorkflow(input: {
     id: string;
     task_queue?: string;
     compilation_feedback?: string;
 }): Promise<LTApiResult>;
+/**
+ * Permanently delete a YAML workflow record.
+ *
+ * Only draft or archived workflows can be deleted. Active or deployed workflows must
+ * be archived first.
+ *
+ * @param input.id — UUID of the workflow to delete
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or 400 if the workflow is active/deployed
+ */
 export declare function deleteYamlWorkflow(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Deploy a YAML workflow and all sibling workflows sharing its app_id namespace.
+ *
+ * Merges and deploys the full app_id YAML, registers HotMesh workers for every
+ * non-archived sibling, transitions draft/deployed siblings to active, and marks
+ * the app_id content as deployed. Uses the app_version declared in the workflow record.
+ *
+ * @param input.id — UUID of the workflow to deploy
+ * @returns `{ status: 200, data: YamlWorkflow }` the refreshed workflow record after deployment
+ */
 export declare function deployYamlWorkflow(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Activate a previously deployed YAML workflow and its app_id siblings.
+ *
+ * Calls the deployer to activate the app_id at its current version, then registers
+ * HotMesh workers for all sibling workflows. Siblings in "deployed" status are
+ * transitioned to "active". The workflow must already be in deployed or active status.
+ *
+ * @param input.id — UUID of the workflow to activate
+ * @returns `{ status: 200, data: YamlWorkflow }` the refreshed workflow record after activation
+ */
 export declare function activateYamlWorkflow(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Invoke an active YAML workflow, executing its DAG pipeline.
+ *
+ * The workflow must be in "active" status. Delegates to the invoke service which
+ * starts the HotMesh execution. Supports both synchronous (wait for result) and
+ * asynchronous (fire-and-forget) invocation modes.
+ *
+ * @param input.id — UUID of the workflow to invoke
+ * @param input.data — input payload passed to the workflow's entry point
+ * @param input.sync — when true, block until the workflow completes and return its output
+ * @param input.timeout — max milliseconds to wait when sync is true
+ * @param input.execute_as — override identity for the execution context
+ * @param auth — authenticated user context; userId is forwarded to the invoke service
+ * @returns `{ status: 200, data: ... }` workflow execution result (sync) or job metadata (async)
+ */
 export declare function invokeYamlWorkflow(input: {
     id: string;
     data?: any;
@@ -59,29 +187,96 @@ export declare function invokeYamlWorkflow(input: {
     timeout?: number;
     execute_as?: string;
 }, auth?: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Archive a YAML workflow, removing it from active service.
+ *
+ * If the workflow is currently active, its HotMesh engine is stopped before
+ * transitioning the status to "archived". Archived workflows cannot be invoked
+ * or regenerated but can still be viewed or deleted.
+ *
+ * @param input.id — UUID of the workflow to archive
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated record with status "archived"
+ */
 export declare function archiveYamlWorkflow(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * Retrieve the version history for a YAML workflow.
+ *
+ * Returns a paginated list of version snapshots ordered by version number.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.limit — max versions to return (defaults to 20)
+ * @param input.offset — pagination offset (defaults to 0)
+ * @returns `{ status: 200, data: VersionSnapshot[] }` paginated version history
+ */
 export declare function getVersionHistory(input: {
     id: string;
     limit?: number;
     offset?: number;
 }): Promise<LTApiResult>;
+/**
+ * Retrieve a specific version snapshot of a YAML workflow.
+ *
+ * Validates that the version number is a positive integer before querying.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.version — 1-based version number to retrieve
+ * @returns `{ status: 200, data: VersionSnapshot }` the snapshot at the requested version, or 404
+ */
 export declare function getVersionSnapshot(input: {
     id: string;
     version: number;
 }): Promise<LTApiResult>;
+/**
+ * Retrieve the raw YAML content for a workflow, optionally at a specific version.
+ *
+ * When a version is provided, fetches from the version snapshot table. Otherwise
+ * returns the current yaml_content from the live workflow record.
+ *
+ * @param input.id — UUID of the workflow
+ * @param input.version — optional version number; when omitted, returns the current content
+ * @returns `{ status: 200, data: string }` the raw YAML string
+ */
 export declare function getYamlContent(input: {
     id: string;
     version?: number;
 }): Promise<LTApiResult<string>>;
+/**
+ * Set or update the cron schedule for a YAML workflow.
+ *
+ * Persists the schedule in the DB and restarts the in-process cron timer via the
+ * cron registry so the change takes effect immediately.
+ *
+ * @param input.id — UUID of the workflow to schedule
+ * @param input.cron_schedule — cron expression (e.g. "0 * * * *")
+ * @param input.cron_envelope — optional payload passed to each scheduled invocation
+ * @param input.execute_as — optional identity override for scheduled executions
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated workflow record with cron fields set
+ */
 export declare function setCronSchedule(input: {
     id: string;
     cron_schedule: string;
     cron_envelope?: any;
     execute_as?: string;
 }): Promise<LTApiResult>;
+/**
+ * Remove the cron schedule from a YAML workflow.
+ *
+ * Stops the in-process cron timer first, then clears the schedule fields in the DB.
+ *
+ * @param input.id — UUID of the workflow to unschedule
+ * @returns `{ status: 200, data: YamlWorkflow }` the updated workflow record with cron fields cleared
+ */
 export declare function clearCronSchedule(input: {
     id: string;
 }): Promise<LTApiResult>;
+/**
+ * List all YAML workflows that have a cron schedule, with their live timer status.
+ *
+ * Fetches all cron-scheduled workflows from the DB and cross-references with the
+ * in-process cron registry to determine which timers are actually running.
+ *
+ * @returns `{ status: 200, data: { schedules: Array<{ id, name, graph_topic, app_id, cron_schedule, execute_as, active }> } }`
+ */
 export declare function getCronStatus(): Promise<LTApiResult>;