@hotmeshio/long-tail 0.1.4 → 0.1.5

package/docs/api/workflows.md

@@ -0,0 +1,616 @@
+# Workflows API
+
+The workflow API covers the full lifecycle: configure a workflow, invoke it, observe its progress, and export its durable execution history. All endpoints require authentication. Responses use `application/json`.
+
+---
+
+## Discovery
+
+### List active workers
+
+```
+GET /api/workflows/workers
+```
+
+Returns all in-memory workflow workers with their registration status (whether a config exists in `lt_config_workflows`).
+
+**Response 200:**
+
+```json
+{
+  "workers": [
+    {
+      "name": "reviewContent",
+      "taskQueue": "long-tail",
+      "registered": true
+    }
+  ]
+}
+```
+
+### List discovered workflows
+
+```
+GET /api/workflows/discovered
+```
+
+Returns a unified list that merges active workers, historical workflow entities from the durable store, and workflow configurations. Each entry includes a `registered` boolean indicating whether a config exists.
+
+**Response 200:**
+
+```json
+{
+  "workflows": [
+    {
+      "name": "reviewContent",
+      "taskQueue": "long-tail",
+      "registered": true,
+      "config": { "..." }
+    }
+  ]
+}
+```
+
+---
+
+## Configuration
+
+Workflow configuration lives in Postgres (`lt_config_workflows`) and drives everything: which workflows the interceptor manages, who can escalate, who can invoke, and what data flows between steps.
+
+### List all workflow configurations
+
+```
+GET /api/workflows/config
+```
+
+**Response 200:**
+
+```json
+{
+  "workflows": [
+    {
+      "id": "a1b2c3d4-...",
+      "workflow_type": "reviewContent",
+      "invocable": true,
+      "task_queue": "long-tail",
+      "default_role": "reviewer",
+      "default_modality": "default",
+      "description": "AI content review with human escalation",
+      "consumes": [],
+      "execute_as": null,
+      "tool_tags": [],
+      "envelope_schema": null,
+      "resolver_schema": null,
+      "cron_schedule": null,
+      "roles": ["reviewer"],
+      "invocation_roles": ["submitter"],
+      "created_at": "2025-01-15T10:00:00.000Z",
+      "updated_at": "2025-01-15T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+### Get a single workflow configuration
+
+```
+GET /api/workflows/:type/config
+```
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `type` | Workflow type name (e.g., `reviewContent`) |
+
+**Response 200:** A single workflow config object (same shape as the array element above).
+
+**Response 404:**
+
+```json
+{ "error": "Workflow config not found" }
+```
+
+### Create or replace a workflow configuration
+
+Requires `admin` or `superadmin` role.
+
+```
+PUT /api/workflows/:type/config
+```
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `type` | Workflow type name |
+
+**Request body:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `invocable` | `boolean` | `false` | Allow this workflow to be started via `POST /api/workflows/:type/invoke` |
+| `task_queue` | `string \| null` | `null` | Task queue name (required for invocable workflows) |
+| `default_role` | `string` | `"reviewer"` | Role assigned to escalations when the workflow doesn't specify one |
+| `description` | `string \| null` | `null` | Human-readable description |
+| `roles` | `string[]` | `[]` | Roles allowed to claim escalations for this workflow |
+| `invocation_roles` | `string[]` | `[]` | Roles allowed to invoke via API. Empty = any authenticated user. |
+| `consumes` | `string[]` | `[]` | Workflow types whose completed data this workflow receives via `envelope.lt.providers` |
+| `execute_as` | `string \| null` | `null` | Service account `external_id` to run as (overrides invoker identity) |
+| `tool_tags` | `string[]` | `[]` | MCP tool tags for scoped tool discovery |
+| `envelope_schema` | `object \| null` | `null` | JSON Schema for the workflow input envelope |
+| `resolver_schema` | `object \| null` | `null` | JSON Schema for the escalation resolver payload |
+| `cron_schedule` | `string \| null` | `null` | Cron expression for scheduled execution (e.g., `"0 9 * * *"`) |
+
+**Example request:**
+
+```json
+{
+  "invocable": true,
+  "task_queue": "long-tail",
+  "default_role": "reviewer",
+  "roles": ["reviewer", "senior-reviewer"],
+  "invocation_roles": ["submitter", "admin"],
+  "consumes": ["extractDocument"]
+}
+```
+
+**Response 200:** The created or updated config object.
+
+This endpoint is idempotent. It replaces the entire configuration, including roles and invocation roles (cascade delete + re-insert). It also invalidates the in-memory config cache.
+
+### Delete a workflow configuration
+
+Requires `admin` or `superadmin` role.
+
+```
+DELETE /api/workflows/:type/config
+```
+
+Deletes the workflow config and all associated roles and invocation roles (cascade).
+
+**Response 200:**
+
+```json
+{ "deleted": true, "workflow_type": "reviewContent" }
+```
+
+**Response 404:**
+
+```json
+{ "error": "Workflow config not found" }
+```
+
+---
+
+## Invocation
+
+### Invoke a workflow
+
+```
+POST /api/workflows/:type/invoke
+```
+
+Start a workflow by its registered type. The workflow must have `invocable: true` in its configuration.
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `type` | Workflow type name (e.g., `reviewContent`) |
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data` | `object` | yes | Business data passed to the workflow as `envelope.data` |
+| `metadata` | `object` | no | Control flow metadata passed as `envelope.metadata` |
+| `execute_as` | `string` | no | Service account `external_id` to run as (admin only) |
+
+**Example request:**
+
+```json
+{
+  "data": {
+    "contentId": "post-456",
+    "content": "This article discusses the impact of...",
+    "contentType": "article"
+  }
+}
+```
+
+**Response 202:**
+
+```json
+{
+  "workflowId": "reviewContent-a1b2c3d4",
+  "message": "Workflow started"
+}
+```
+
+The workflow starts on its configured `task_queue` with a generated workflow ID (`{type}-{guid}`). The response returns immediately — the workflow runs durably in the background.
+
+**Error responses:**
+
+| Status | Body | Meaning |
+|--------|------|---------|
+| `400` | `{ "error": "Request body must include a data object" }` | Missing or invalid `data` field |
+| `400` | `{ "error": "Workflow has no task_queue configured" }` | Config exists but `task_queue` is null |
+| `403` | `{ "error": "Workflow is not invocable" }` | `invocable` is `false` |
+| `403` | `{ "error": "User not registered" }` | RBAC check failed — no matching user |
+| `403` | `{ "error": "Insufficient role for invocation" }` | User lacks a required invocation role |
+| `404` | `{ "error": "Workflow not found" }` | No config exists for this type |
+
+**Authorization:**
+
+When `invocation_roles` is empty, any authenticated user can invoke. When set, the user must hold at least one of the listed roles (checked against `lt_user_roles` via the user's `external_id`). Superadmins bypass this check.
+
+---
+
+## Observation
+
+These endpoints let you check on running or completed workflows. The `workflowId` (returned from the invoke call) is all you need.
+
+### Get workflow status
+
+```
+GET /api/workflows/:workflowId/status
+```
+
+**Response 200:**
+
+```json
+{
+  "workflowId": "reviewContent-a1b2c3d4",
+  "status": 0
+}
+```
+
+| Status value | Meaning |
+|--------------|---------|
+| `0` | Complete |
+| Positive | Running |
+| Negative | Interrupted |
+
+### Get workflow result
+
+```
+GET /api/workflows/:workflowId/result
+```
+
+Returns the result if the workflow is complete, or `202` if it's still running. Never blocks.
+
+**Response 200** (complete):
+
+```json
+{
+  "workflowId": "reviewContent-a1b2c3d4",
+  "result": {
+    "type": "return",
+    "data": {
+      "approved": true,
+      "analysis": { "confidence": 0.92 }
+    },
+    "milestones": [
+      { "name": "ai_review", "value": "approved" }
+    ]
+  }
+}
+```
+
+**Response 202** (still running):
+
+```json
+{
+  "workflowId": "reviewContent-a1b2c3d4",
+  "status": "running"
+}
+```
+
+---
+
+## Execution History Export
+
+Every workflow's full execution history is exportable in JSON. Two formats are available: a raw state export (HotMesh-native) and a structured execution event history with typed events, ISO timestamps, durations, and cross-references.
+
+Because workflows are durably executed — state is transactionally checkpointed to Postgres after every step — the export is a complete, faithful record of everything that happened. Every activity scheduled, every result returned, every signal received, every child workflow spawned. Nothing is reconstructed or approximated.
+
+### Convenience alias
+
+```
+GET /api/workflows/:workflowId/export
+```
+
+Returns the raw workflow state from HotMesh. For full control over facet filtering and execution format, use the dedicated `/api/workflow-states` endpoints below.
+
+**Response 200:** Raw workflow state object (data, state, status, timeline, transitions).
+
+### Raw workflow state
+
+```
+GET /api/workflow-states/:workflowId
+```
+
+Full state export with facet filtering. The response includes five facets: `data`, `state`, `status`, `timeline`, and `transitions`. Use `allow` or `block` to control which facets are returned.
+
+**Query parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `allow` | `string` | no | Comma-separated allowlist of facets |
+| `block` | `string` | no | Comma-separated blocklist of facets |
+| `values` | `string` | no | Set to `false` to omit timeline values |
+
+`allow` and `block` are mutually exclusive. If both are provided, `allow` takes precedence.
+
+**Example — only data and status:**
+
+```
+GET /api/workflow-states/reviewContent-a1b2c3d4?allow=data,status
+```
+
+**Response 200:**
+
+```json
+{
+  "workflow_id": "reviewContent-a1b2c3d4",
+  "data": {
+    "contentId": "post-456",
+    "approved": true,
+    "analysis": { "confidence": 0.92 }
+  },
+  "status": 0
+}
+```
+
+### Structured execution history
+
+```
+GET /api/workflow-states/:workflowId/execution
+```
+
+Exports the workflow's execution as a sequence of typed events. Each event has an `eventType`, an ISO timestamp, and typed attributes. Activity events include durations and cross-reference the scheduling event via `scheduledEventId`. The response ends with a `summary` that captures total event count, wall-clock duration, and final status.
+
+This is the primary export format for auditing, debugging, and building dashboards over durable workflow executions.
+
+**Query parameters:**
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `excludeSystem` | `string` | no | `false` | `true` to omit LT interceptor activities (`lt*`) |
+| `omitResults` | `string` | no | `false` | `true` to strip activity result payloads |
+| `mode` | `string` | no | `sparse` | `sparse` = flat event list, `verbose` = nested child workflows |
+| `maxDepth` | `integer` | no | `5` | Recursion depth limit for verbose mode |
+
+**Event types:**
+
+| Event type | Description |
+|------------|-------------|
+| `workflow_execution_started` | Workflow began — includes input arguments |
+| `activity_task_scheduled` | Activity dispatched to a task queue |
+| `activity_task_completed` | Activity returned a result — includes duration and `scheduledEventId` |
+| `activity_task_failed` | Activity threw an error |
+| `child_workflow_execution_started` | Orchestrator spawned a child workflow |
+| `child_workflow_execution_completed` | Child workflow returned |
+| `child_workflow_execution_failed` | Child workflow failed |
+| `timer_started` | Timer (sleep/delay) began |
+| `timer_fired` | Timer elapsed |
+| `workflow_execution_signaled` | External signal received (e.g., escalation resolution) |
+| `workflow_execution_completed` | Workflow finished successfully |
+| `workflow_execution_failed` | Workflow failed |
+
+**Example request — clean history without interceptor internals:**
+
+```
+GET /api/workflow-states/reviewContent-a1b2c3d4/execution?excludeSystem=true
+```
+
+**Response 200:**
+
+```json
+{
+  "workflowId": "reviewContent-a1b2c3d4",
+  "workflowName": "reviewContent",
+  "taskQueue": "long-tail",
+  "events": [
+    {
+      "eventId": 1,
+      "eventType": "workflow_execution_started",
+      "timestamp": "2025-01-15T10:00:00.000Z",
+      "details": {
+        "input": {
+          "data": { "contentId": "post-456" },
+          "metadata": {}
+        }
+      }
+    },
+    {
+      "eventId": 2,
+      "eventType": "activity_task_scheduled",
+      "timestamp": "2025-01-15T10:00:00.050Z",
+      "details": {
+        "activityType": "analyzeContent",
+        "taskQueue": "long-tail"
+      }
+    },
+    {
+      "eventId": 3,
+      "eventType": "activity_task_completed",
+      "timestamp": "2025-01-15T10:00:02.300Z",
+      "details": {
+        "scheduledEventId": 2,
+        "duration": "2.250s",
+        "result": {
+          "confidence": 0.92,
+          "flags": []
+        }
+      }
+    },
+    {
+      "eventId": 4,
+      "eventType": "workflow_execution_completed",
+      "timestamp": "2025-01-15T10:00:02.350Z",
+      "details": {
+        "result": {
+          "approved": true,
+          "analysis": { "confidence": 0.92 }
+        }
+      }
+    }
+  ],
+  "summary": {
+    "totalEvents": 4,
+    "duration": "2.350s",
+    "status": "completed"
+  }
+}
+```
+
+Every event is faithfully reconstructed from the durable execution log — activities are only executed once (their results are checkpointed), so the event history reflects exactly what happened, not a re-execution.
+
+**Verbose mode** includes nested `children` arrays for orchestrator workflows, where each child contains its own full event sequence. Use `maxDepth` to limit recursion for deeply nested orchestrations.
+
+### Workflow status semaphore
+
+```
+GET /api/workflow-states/:workflowId/status
+```
+
+Returns only the numeric status — useful for lightweight polling.
+
+**Response 200:**
+
+```json
+{ "workflow_id": "reviewContent-a1b2c3d4", "status": 0 }
+```
+
+| Value | Meaning |
+|-------|---------|
+| `0` | Complete |
+| Positive | Running |
+| Negative | Interrupted |
+
+### Workflow state snapshot
+
+```
+GET /api/workflow-states/:workflowId/state
+```
+
+Returns the current internal job state — the HotMesh representation of where the workflow is in its execution graph. For completed workflows, this is the final output.
+
+**Response 200:** HotMesh job state object. Structure depends on the workflow's current execution point.
+
+### Programmatic access
+
+The same export data is available directly through the Durable client, without going through the HTTP API:
+
+```typescript
+import { Durable } from '@hotmeshio/hotmesh';
+
+const client = new Durable.Client({ connection });
+const handle = await client.workflow.getHandle(
+  taskQueue,
+  workflowName,
+  workflowId,
+);
+
+// Structured execution history
+const execution = await handle.exportExecution({
+  exclude_system: true,
+});
+
+// Raw state export with facet filtering
+const state = await handle.export({
+  allow: ['data', 'status'],
+});
+
+// Status semaphore
+const status = await handle.status();
+
+// Current state snapshot
+const snapshot = await handle.state(true);
+```
+
+---
+
+## Cron Status
+
+### Get cron workflow status
+
+```
+GET /api/workflows/cron/status
+```
+
+Lists all cron-configured workflows and whether each is actively running.
+
+**Response 200:**
+
+```json
+{
+  "schedules": [
+    {
+      "workflow_type": "dailyReport",
+      "cron_schedule": "0 9 * * *",
+      "description": "Generate daily report",
+      "task_queue": "long-tail",
+      "invocable": true,
+      "active": true,
+      "envelope_schema": null
+    }
+  ]
+}
+```
+
+---
+
+## Termination
+
+### Terminate a workflow
+
+```
+POST /api/workflows/:workflowId/terminate
+```
+
+Interrupt a running workflow. The workflow is immediately terminated.
+
+**Path parameters:**
+
+| Parameter | Description |
+|-----------|-------------|
+| `workflowId` | HotMesh workflow ID |
+
+**Response 200:**
+
+```json
+{ "terminated": true, "workflowId": "reviewContent-a1b2c3d4" }
+```
+
+---
+
+## Endpoint summary
+
+### `/api/workflows`
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `/workers` | any | List active in-memory workers with registration status |
+| `GET` | `/discovered` | any | Unified list of workers, entities, and configs |
+| `GET` | `/cron/status` | any | List cron-configured workflows and active status |
+| `GET` | `/config` | any | List all workflow configurations |
+| `GET` | `/:type/config` | any | Get a single workflow configuration |
+| `PUT` | `/:type/config` | admin | Create or replace a workflow configuration |
+| `DELETE` | `/:type/config` | admin | Delete a workflow configuration (cascade) |
+| `POST` | `/:type/invoke` | RBAC | Invoke a workflow (requires `invocable: true`) |
+| `GET` | `/:workflowId/status` | any | Workflow status |
+| `GET` | `/:workflowId/result` | any | Get workflow result (200 if complete, 202 if running) |
+| `POST` | `/:workflowId/terminate` | any | Terminate a running workflow |
+| `GET` | `/:workflowId/export` | any | Raw state export (convenience alias) |
+
+### `/api/workflow-states`
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `/:workflowId` | any | Raw state export with facet filtering |
+| `GET` | `/:workflowId/execution` | any | Structured execution history |
+| `GET` | `/:workflowId/status` | any | Status semaphore |
+| `GET` | `/:workflowId/state` | any | Current workflow state snapshot |