@hotmeshio/long-tail 0.1.7 → 0.1.9

package/build/api/mcp.js

@@ -46,6 +46,17 @@ exports.listMcpServerTools = listMcpServerTools;
 exports.callMcpTool = callMcpTool;
 const mcpDbService = __importStar(require("../services/mcp/db"));
 const mcp_1 = require("../services/mcp");
+/**
+ * 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
+ */
 async function listMcpServers(input) {
     try {
         const result = await mcpDbService.listMcpServers(input);
@@ -55,6 +66,22 @@ async function listMcpServers(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function createMcpServer(input) {
     try {
         if (!input.name || !input.transport_type || !input.transport_config) {
@@ -70,6 +97,17 @@ async function createMcpServer(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function testConnection(input) {
     try {
         if (!input.transport_type || !input.transport_config) {
@@ -83,6 +121,12 @@ async function testConnection(input) {
         return { status: 200, data: { success: false, error: err.message, tools: [] } };
     }
 }
+/**
+ * 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
+ */
 async function getMcpServer(input) {
     try {
         const server = await mcpDbService.getMcpServer(input.id);
@@ -95,6 +139,15 @@ async function getMcpServer(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function updateMcpServer(input) {
     try {
         const { id, ...fields } = input;
@@ -108,6 +161,12 @@ async function updateMcpServer(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function deleteMcpServer(input) {
     try {
         const deleted = await mcpDbService.deleteMcpServer(input.id);
@@ -120,6 +179,14 @@ async function deleteMcpServer(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function connectMcpServer(input) {
     try {
         const adapter = mcp_1.mcpRegistry.current;
@@ -133,6 +200,14 @@ async function connectMcpServer(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function disconnectMcpServer(input) {
     try {
         const adapter = mcp_1.mcpRegistry.current;
@@ -146,6 +221,16 @@ async function disconnectMcpServer(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function getCredentialStatus(input, auth) {
     try {
         const server = await mcpDbService.getMcpServer(input.id);
@@ -174,6 +259,14 @@ async function getCredentialStatus(input, auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function listMcpServerTools(input) {
     try {
         const adapter = mcp_1.mcpRegistry.current;
@@ -187,6 +280,21 @@ async function listMcpServerTools(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * 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
+ */
 async function callMcpTool(input, auth) {
     try {
         const adapter = mcp_1.mcpRegistry.current;

package/build/api/namespaces.d.ts

@@ -1,5 +1,18 @@
 import type { LTApiResult } from '../types/sdk';
+/**
+ * List all registered namespaces.
+ *
+ * @returns `{ status: 200, data: { namespaces: LTNamespace[] } }`
+ */
 export declare function listNamespaces(): Promise<LTApiResult>;
+/**
+ * Register a new namespace.
+ *
+ * @param input.name — unique namespace identifier
+ * @param input.description — human-readable description
+ * @param input.metadata — arbitrary key-value metadata
+ * @returns `{ status: 200, data: <namespace record> }`
+ */
 export declare function registerNamespace(input: {
     name: string;
     description?: string;

package/build/api/namespaces.js

@@ -36,6 +36,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.listNamespaces = listNamespaces;
 exports.registerNamespace = registerNamespace;
 const namespaceService = __importStar(require("../services/namespace"));
+/**
+ * List all registered namespaces.
+ *
+ * @returns `{ status: 200, data: { namespaces: LTNamespace[] } }`
+ */
 async function listNamespaces() {
     try {
         const namespaces = await namespaceService.listNamespaces();
@@ -45,6 +50,14 @@ async function listNamespaces() {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Register a new namespace.
+ *
+ * @param input.name — unique namespace identifier
+ * @param input.description — human-readable description
+ * @param input.metadata — arbitrary key-value metadata
+ * @returns `{ status: 200, data: <namespace record> }`
+ */
 async function registerNamespace(input) {
     try {
         const { name, description, metadata } = input;

package/build/api/roles.d.ts

@@ -1,25 +1,88 @@
 import type { LTApiResult } from '../types/sdk';
+/**
+ * List all distinct role names in the system.
+ *
+ * @returns `{ status: 200, data: { roles: string[] } }` on success
+ */
 export declare function listRoles(): Promise<LTApiResult>;
+/**
+ * List all roles with their full details (member counts, escalation chains, etc.).
+ *
+ * @returns `{ status: 200, data: { roles: RoleDetail[] } }` on success
+ */
 export declare function listRolesWithDetails(): Promise<LTApiResult>;
+/**
+ * Create a new role. Requires admin privileges.
+ *
+ * The role name is trimmed, lowercased, and validated against the pattern
+ * `^[a-z][a-z0-9_-]*$` (must start with a letter, then lowercase alphanumerics,
+ * hyphens, or underscores).
+ *
+ * @param input.role — the role name to create
+ * @returns `{ status: 201, data: { role: string } }` on success
+ */
 export declare function createRole(input: {
     role: string;
 }): Promise<LTApiResult>;
+/**
+ * Retrieve all escalation chains across all roles.
+ *
+ * @returns `{ status: 200, data: { chains: EscalationChain[] } }` on success
+ */
 export declare function getEscalationChains(): Promise<LTApiResult>;
+/**
+ * Add an escalation chain link from one role to another. Requires admin privileges.
+ *
+ * @param input.source_role — the role that escalates from
+ * @param input.target_role — the role that receives the escalation
+ * @returns `{ status: 201, data: { source_role, target_role } }` on success
+ */
 export declare function addEscalationChain(input: {
     source_role: string;
     target_role: string;
 }): Promise<LTApiResult>;
+/**
+ * Remove an escalation chain link between two roles. Requires admin privileges.
+ *
+ * @param input.source_role — the role that escalates from
+ * @param input.target_role — the role that receives the escalation
+ * @returns `{ status: 200, data: { removed: true } }` on success, or `{ status: 404 }` if not found
+ */
 export declare function removeEscalationChain(input: {
     source_role: string;
     target_role: string;
 }): Promise<LTApiResult>;
+/**
+ * Get all escalation target roles for a given source role.
+ *
+ * @param input.role — the source role to look up escalation targets for
+ * @returns `{ status: 200, data: { targets: string[] } }` on success
+ */
 export declare function getEscalationTargets(input: {
     role: string;
 }): Promise<LTApiResult>;
+/**
+ * Replace all escalation targets for a role with a new set. Requires admin privileges.
+ *
+ * Removes all existing escalation links from the source role and creates new
+ * ones for each target in the provided array.
+ *
+ * @param input.role — the source role whose targets are being replaced
+ * @param input.targets — array of target role names to set as the new escalation targets
+ * @returns `{ status: 200, data: { role, targets } }` on success
+ */
 export declare function replaceEscalationTargets(input: {
     role: string;
     targets: string[];
 }): Promise<LTApiResult>;
+/**
+ * Delete a role from the system. Requires admin privileges.
+ *
+ * Returns 409 if the role cannot be deleted (e.g., still assigned to users).
+ *
+ * @param input.role — the role name to delete
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or `{ status: 409 }` if deletion blocked
+ */
 export declare function deleteRole(input: {
     role: string;
 }): Promise<LTApiResult>;

package/build/api/roles.js

@@ -43,6 +43,11 @@ exports.getEscalationTargets = getEscalationTargets;
 exports.replaceEscalationTargets = replaceEscalationTargets;
 exports.deleteRole = deleteRole;
 const roleService = __importStar(require("../services/role"));
+/**
+ * List all distinct role names in the system.
+ *
+ * @returns `{ status: 200, data: { roles: string[] } }` on success
+ */
 async function listRoles() {
     try {
         const roles = await roleService.listDistinctRoles();
@@ -52,6 +57,11 @@ async function listRoles() {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List all roles with their full details (member counts, escalation chains, etc.).
+ *
+ * @returns `{ status: 200, data: { roles: RoleDetail[] } }` on success
+ */
 async function listRolesWithDetails() {
     try {
         const roles = await roleService.listRolesWithDetails();
@@ -61,7 +71,16 @@ async function listRolesWithDetails() {
         return { status: 500, error: err.message };
     }
 }
-// Admin-required
+/**
+ * Create a new role. Requires admin privileges.
+ *
+ * The role name is trimmed, lowercased, and validated against the pattern
+ * `^[a-z][a-z0-9_-]*$` (must start with a letter, then lowercase alphanumerics,
+ * hyphens, or underscores).
+ *
+ * @param input.role — the role name to create
+ * @returns `{ status: 201, data: { role: string } }` on success
+ */
 async function createRole(input) {
     try {
         if (!input.role || typeof input.role !== 'string' || !input.role.trim()) {
@@ -81,6 +100,11 @@ async function createRole(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Retrieve all escalation chains across all roles.
+ *
+ * @returns `{ status: 200, data: { chains: EscalationChain[] } }` on success
+ */
 async function getEscalationChains() {
     try {
         const chains = await roleService.getAllEscalationChains();
@@ -90,7 +114,13 @@ async function getEscalationChains() {
         return { status: 500, error: err.message };
     }
 }
-// Admin-required
+/**
+ * Add an escalation chain link from one role to another. Requires admin privileges.
+ *
+ * @param input.source_role — the role that escalates from
+ * @param input.target_role — the role that receives the escalation
+ * @returns `{ status: 201, data: { source_role, target_role } }` on success
+ */
 async function addEscalationChain(input) {
     try {
         if (!input.source_role || !input.target_role) {
@@ -106,7 +136,13 @@ async function addEscalationChain(input) {
         return { status: 500, error: err.message };
     }
 }
-// Admin-required
+/**
+ * Remove an escalation chain link between two roles. Requires admin privileges.
+ *
+ * @param input.source_role — the role that escalates from
+ * @param input.target_role — the role that receives the escalation
+ * @returns `{ status: 200, data: { removed: true } }` on success, or `{ status: 404 }` if not found
+ */
 async function removeEscalationChain(input) {
     try {
         if (!input.source_role || !input.target_role) {
@@ -122,6 +158,12 @@ async function removeEscalationChain(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Get all escalation target roles for a given source role.
+ *
+ * @param input.role — the source role to look up escalation targets for
+ * @returns `{ status: 200, data: { targets: string[] } }` on success
+ */
 async function getEscalationTargets(input) {
     try {
         const targets = await roleService.getEscalationTargets(input.role);
@@ -131,7 +173,16 @@ async function getEscalationTargets(input) {
         return { status: 500, error: err.message };
     }
 }
-// Admin-required
+/**
+ * Replace all escalation targets for a role with a new set. Requires admin privileges.
+ *
+ * Removes all existing escalation links from the source role and creates new
+ * ones for each target in the provided array.
+ *
+ * @param input.role — the source role whose targets are being replaced
+ * @param input.targets — array of target role names to set as the new escalation targets
+ * @returns `{ status: 200, data: { role, targets } }` on success
+ */
 async function replaceEscalationTargets(input) {
     try {
         if (!Array.isArray(input.targets)) {
@@ -144,7 +195,14 @@ async function replaceEscalationTargets(input) {
         return { status: 500, error: err.message };
     }
 }
-// Admin-required
+/**
+ * Delete a role from the system. Requires admin privileges.
+ *
+ * Returns 409 if the role cannot be deleted (e.g., still assigned to users).
+ *
+ * @param input.role — the role name to delete
+ * @returns `{ status: 200, data: { deleted: true } }` on success, or `{ status: 409 }` if deletion blocked
+ */
 async function deleteRole(input) {
     try {
         const result = await roleService.deleteRole(input.role);

package/build/api/settings.d.ts

@@ -1,2 +1,10 @@
 import type { LTApiResult } from '../types/sdk';
+/**
+ * Return platform settings for the current deployment.
+ *
+ * Includes telemetry configuration (trace URL), escalation claim duration
+ * options, and event transport details (socket.io, NATS, or none).
+ *
+ * @returns `{ status: 200, data: { telemetry, escalation, events } }`
+ */
 export declare function getSettings(): Promise<LTApiResult>;

package/build/api/settings.js

@@ -6,6 +6,14 @@ const events_1 = require("../lib/events");
 const nats_1 = require("../lib/events/nats");
 const socketio_1 = require("../lib/events/socketio");
 const defaults_1 = require("../modules/defaults");
+/**
+ * Return platform settings for the current deployment.
+ *
+ * Includes telemetry configuration (trace URL), escalation claim duration
+ * options, and event transport details (socket.io, NATS, or none).
+ *
+ * @returns `{ status: 200, data: { telemetry, escalation, events } }`
+ */
 async function getSettings() {
     try {
         const hasSocketIO = !!events_1.eventRegistry.getAdapter(socketio_1.SocketIOEventAdapter);

package/build/api/tasks.d.ts

@@ -1,4 +1,43 @@
-import type { LTApiResult } from '../types/sdk';
+import type { LTApiResult, LTApiAuth } from '../types/sdk';
+/**
+ * Create a task record.
+ *
+ * Tasks represent workflow executions tracked by the LT interceptor.
+ * Required fields: `workflow_id`, `workflow_type`, `lt_type`,
+ * `signal_id`, `parent_workflow_id`, and `envelope`.
+ *
+ * @returns `{ status: 201, data: <task record> }`
+ */
+export declare function createTask(input: {
+    workflow_id: string;
+    workflow_type: string;
+    lt_type: string;
+    task_queue?: string;
+    signal_id: string;
+    parent_workflow_id: string;
+    origin_id?: string;
+    parent_id?: string;
+    envelope?: string;
+    metadata?: Record<string, any>;
+    priority?: number;
+    trace_id?: string;
+    span_id?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * List tasks with optional filters.
+ *
+ * Tasks represent workflow executions tracked by the LT interceptor.
+ *
+ * @param input.status — filter by `pending` or `completed`
+ * @param input.lt_type — filter by interceptor classification
+ * @param input.workflow_type — filter by workflow function name
+ * @param input.workflow_id — filter by HotMesh workflow ID
+ * @param input.parent_workflow_id — filter by parent orchestrator ID
+ * @param input.origin_id — filter by root process origin ID
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset (default: 0)
+ * @returns `{ status: 200, data: { tasks, total } }`
+ */
 export declare function listTasks(input: {
     status?: string;
     lt_type?: string;
@@ -9,9 +48,25 @@ export declare function listTasks(input: {
     limit?: number;
     offset?: number;
 }): Promise<LTApiResult>;
+/**
+ * Return aggregate process statistics.
+ *
+ * @param input.period — time window (`1h`, `24h`, `7d`, `30d`)
+ * @returns `{ status: 200, data: <process stats> }`
+ */
 export declare function getProcessStats(input: {
     period?: string;
 }): Promise<LTApiResult>;
+/**
+ * List processes (grouped by origin_id) with optional filters.
+ *
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.workflow_type — filter by workflow type
+ * @param input.status — filter by status
+ * @param input.search — full-text search across process fields
+ * @returns `{ status: 200, data: { processes, total } }`
+ */
 export declare function listProcesses(input: {
     limit?: number;
     offset?: number;
@@ -19,9 +74,21 @@ export declare function listProcesses(input: {
     status?: string;
     search?: string;
 }): Promise<LTApiResult>;
+/**
+ * Get a single process with all its tasks and escalations.
+ *
+ * @param input.originId — root process origin ID
+ * @returns `{ status: 200, data: { origin_id, tasks, escalations } }`
+ */
 export declare function getProcess(input: {
     originId: string;
 }): Promise<LTApiResult>;
+/**
+ * Get a single task by ID.
+ *
+ * @param input.id — task UUID
+ * @returns `{ status: 200, data: <task record> }` or 404
+ */
 export declare function getTask(input: {
     id: string;
 }): Promise<LTApiResult>;

package/build/api/tasks.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTask = createTask;
 exports.listTasks = listTasks;
 exports.getProcessStats = getProcessStats;
 exports.listProcesses = listProcesses;
@@ -40,6 +41,69 @@ exports.getProcess = getProcess;
 exports.getTask = getTask;
 const taskService = __importStar(require("../services/task"));
 const escalationService = __importStar(require("../services/escalation"));
+/**
+ * Create a task record.
+ *
+ * Tasks represent workflow executions tracked by the LT interceptor.
+ * Required fields: `workflow_id`, `workflow_type`, `lt_type`,
+ * `signal_id`, `parent_workflow_id`, and `envelope`.
+ *
+ * @returns `{ status: 201, data: <task record> }`
+ */
+async function createTask(input, auth) {
+    try {
+        const { workflow_id, workflow_type, lt_type, signal_id, parent_workflow_id } = input;
+        if (!workflow_id || typeof workflow_id !== 'string') {
+            return { status: 400, error: 'workflow_id is required' };
+        }
+        if (!workflow_type || typeof workflow_type !== 'string') {
+            return { status: 400, error: 'workflow_type is required' };
+        }
+        if (!lt_type || typeof lt_type !== 'string') {
+            return { status: 400, error: 'lt_type is required' };
+        }
+        if (!signal_id || typeof signal_id !== 'string') {
+            return { status: 400, error: 'signal_id is required' };
+        }
+        if (!parent_workflow_id || typeof parent_workflow_id !== 'string') {
+            return { status: 400, error: 'parent_workflow_id is required' };
+        }
+        const task = await taskService.createTask({
+            workflow_id,
+            workflow_type,
+            lt_type,
+            task_queue: input.task_queue,
+            signal_id,
+            parent_workflow_id,
+            origin_id: input.origin_id,
+            parent_id: input.parent_id,
+            envelope: input.envelope ?? '{}',
+            metadata: input.metadata,
+            priority: input.priority,
+            trace_id: input.trace_id,
+            span_id: input.span_id,
+        });
+        return { status: 201, data: task };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * List tasks with optional filters.
+ *
+ * Tasks represent workflow executions tracked by the LT interceptor.
+ *
+ * @param input.status — filter by `pending` or `completed`
+ * @param input.lt_type — filter by interceptor classification
+ * @param input.workflow_type — filter by workflow function name
+ * @param input.workflow_id — filter by HotMesh workflow ID
+ * @param input.parent_workflow_id — filter by parent orchestrator ID
+ * @param input.origin_id — filter by root process origin ID
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset (default: 0)
+ * @returns `{ status: 200, data: { tasks, total } }`
+ */
 async function listTasks(input) {
     try {
         const result = await taskService.listTasks(input);
@@ -49,6 +113,12 @@ async function listTasks(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Return aggregate process statistics.
+ *
+ * @param input.period — time window (`1h`, `24h`, `7d`, `30d`)
+ * @returns `{ status: 200, data: <process stats> }`
+ */
 async function getProcessStats(input) {
     try {
         const stats = await taskService.getProcessStats(input.period);
@@ -58,6 +128,16 @@ async function getProcessStats(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * List processes (grouped by origin_id) with optional filters.
+ *
+ * @param input.limit — max results (default: 50)
+ * @param input.offset — pagination offset
+ * @param input.workflow_type — filter by workflow type
+ * @param input.status — filter by status
+ * @param input.search — full-text search across process fields
+ * @returns `{ status: 200, data: { processes, total } }`
+ */
 async function listProcesses(input) {
     try {
         const result = await taskService.listProcesses(input);
@@ -67,6 +147,12 @@ async function listProcesses(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Get a single process with all its tasks and escalations.
+ *
+ * @param input.originId — root process origin ID
+ * @returns `{ status: 200, data: { origin_id, tasks, escalations } }`
+ */
 async function getProcess(input) {
     try {
         const [tasks, escalations] = await Promise.all([
@@ -82,6 +168,12 @@ async function getProcess(input) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Get a single task by ID.
+ *
+ * @param input.id — task UUID
+ * @returns `{ status: 200, data: <task record> }` or 404
+ */
 async function getTask(input) {
     try {
         const task = await taskService.getTask(input.id);