@hotmeshio/long-tail 0.1.7 → 0.1.8

package/docs/api/sdk/escalations.md

@@ -0,0 +1,374 @@
+# lt.escalations
+
+Manage human-in-the-loop escalations -- list, claim, resolve, and bulk-operate on workflow escalations.
+
+## list
+
+List escalations with optional filters, scoped to the authenticated user's roles.
+
+```typescript
+const result = await lt.escalations.list({
+  status: 'pending',
+  role: 'reviewer',
+  limit: 25,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | `string` | No | Filter by `pending`, `resolved`, or `cancelled` |
+| `role` | `string` | No | Filter by assigned role |
+| `type` | `string` | No | Filter by workflow type |
+| `subtype` | `string` | No | Filter by subtype |
+| `assigned_to` | `string` | No | Filter by assigned user ID |
+| `priority` | `number` | No | Filter by priority (1--4) |
+| `limit` | `number` | No | Max results (default: 50) |
+| `offset` | `number` | No | Pagination offset |
+| `sort_by` | `string` | No | Column to sort by (e.g. `created_at`, `priority`) |
+| `order` | `string` | No | `asc` or `desc` |
+
+**Returns:** `LTApiResult<{ escalations, total }>`
+
+**Auth:** Required
+
+---
+
+## listAvailable
+
+List escalations available for claim (pending and not actively claimed).
+
+```typescript
+const result = await lt.escalations.listAvailable({
+  role: 'reviewer',
+  limit: 10,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | No | Filter by role |
+| `type` | `string` | No | Filter by workflow type |
+| `subtype` | `string` | No | Filter by subtype |
+| `priority` | `number` | No | Filter by priority (1--4) |
+| `limit` | `number` | No | Max results (default: 50) |
+| `offset` | `number` | No | Pagination offset |
+| `sort_by` | `string` | No | Column to sort by |
+| `order` | `string` | No | `asc` or `desc` |
+
+**Returns:** `LTApiResult<{ escalations, total }>`
+
+**Auth:** Required
+
+---
+
+## listTypes
+
+List all distinct escalation type values.
+
+```typescript
+const result = await lt.escalations.listTypes();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ types: string[] }>`
+
+**Auth:** Not required
+
+---
+
+## getStats
+
+Get aggregate escalation statistics scoped to the user's roles.
+
+```typescript
+const result = await lt.escalations.getStats({ period: '24h' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `period` | `string` | No | Time window (`1h`, `24h`, `7d`, `30d`) |
+
+**Returns:** `LTApiResult<{ pending, claimed, created, resolved, by_role, by_type }>`
+
+**Auth:** Required
+
+---
+
+## get
+
+Get a single escalation by ID.
+
+```typescript
+const result = await lt.escalations.get({ id: 'esc_123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+
+**Returns:** `LTApiResult<Escalation>` -- returns 403 if user lacks the role, 404 if not found.
+
+**Auth:** Required
+
+---
+
+## getByWorkflowId
+
+List all escalations for a given workflow ID.
+
+```typescript
+const result = await lt.escalations.getByWorkflowId({ workflowId: 'wf_abc' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | HotMesh workflow ID |
+
+**Returns:** `LTApiResult<{ escalations }>`
+
+**Auth:** Not required
+
+---
+
+## escalate
+
+Route a pending escalation to a different role.
+
+```typescript
+const result = await lt.escalations.escalate({
+  id: 'esc_123',
+  targetRole: 'senior-reviewer',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+| `targetRole` | `string` | Yes | Destination role |
+
+**Returns:** `LTApiResult<Escalation>` -- returns 403 if not authorized, 404 if not found, 409 if not pending.
+
+**Auth:** Required
+
+---
+
+## claim
+
+Claim a pending escalation for the authenticated user.
+
+```typescript
+const result = await lt.escalations.claim({
+  id: 'esc_123',
+  durationMinutes: 60,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+| `durationMinutes` | `number` | No | Claim duration (default: 30) |
+
+**Returns:** `LTApiResult<{ escalation, isExtension }>` -- returns 403 if user lacks the role, 404 if not found, 409 if not available.
+
+**Auth:** Required
+
+---
+
+## release
+
+Release a claimed escalation back to the pool.
+
+```typescript
+const result = await lt.escalations.release({ id: 'esc_123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+
+**Returns:** `LTApiResult<{ escalation }>` -- returns 409 if not claimed by the caller.
+
+**Auth:** Required
+
+---
+
+## resolve
+
+Resolve a pending escalation with a human-provided payload.
+
+Supports two resolution paths: signal-routed (sends payload to a paused workflow) and re-run (restarts the workflow with resolver data injected). Password fields are replaced with ephemeral tokens.
+
+```typescript
+const result = await lt.escalations.resolve({
+  id: 'esc_123',
+  resolverPayload: { approved: true, comment: 'Looks good' },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | Escalation UUID |
+| `resolverPayload` | `Record<string, any>` | Yes | Human decision data |
+
+**Returns:** `LTApiResult<{ signaled, escalationId, workflowId }>` (signal path) or `LTApiResult<{ started, escalationId, workflowId }>` (re-run path) -- returns 404 if not found, 409 if not pending.
+
+**Auth:** Required
+
+---
+
+## releaseExpired
+
+Release all escalation claims past their `assigned_until` deadline.
+
+```typescript
+const result = await lt.escalations.releaseExpired();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ released: number }>`
+
+**Auth:** Not required
+
+---
+
+## updatePriority
+
+Update priority for one or more escalations.
+
+```typescript
+const result = await lt.escalations.updatePriority({
+  ids: ['esc_1', 'esc_2'],
+  priority: 1,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `priority` | `number` | Yes | New priority (1=critical, 2=high, 3=medium, 4=low) |
+
+**Returns:** `LTApiResult<{ updated: number }>`
+
+**Auth:** Required
+
+---
+
+## bulkClaim
+
+Claim multiple escalations at once for the authenticated user.
+
+```typescript
+const result = await lt.escalations.bulkClaim({
+  ids: ['esc_1', 'esc_2'],
+  durationMinutes: 60,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `durationMinutes` | `number` | No | Claim duration (default: 30) |
+
+**Returns:** `LTApiResult<{ claimed, skipped }>`
+
+**Auth:** Required
+
+---
+
+## bulkAssign
+
+Assign multiple escalations to a specific user.
+
+```typescript
+const result = await lt.escalations.bulkAssign({
+  ids: ['esc_1', 'esc_2'],
+  targetUserId: 'user_456',
+  durationMinutes: 60,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `targetUserId` | `string` | Yes | User to assign to |
+| `durationMinutes` | `number` | No | Assignment duration (default: 30) |
+
+**Returns:** `LTApiResult<{ assigned, skipped }>`
+
+**Auth:** Required
+
+---
+
+## bulkEscalate
+
+Route multiple escalations to a different role.
+
+```typescript
+const result = await lt.escalations.bulkEscalate({
+  ids: ['esc_1', 'esc_2'],
+  targetRole: 'senior-reviewer',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `targetRole` | `string` | Yes | Destination role |
+
+**Returns:** `LTApiResult<{ updated: number }>`
+
+**Auth:** Required
+
+---
+
+## bulkTriage
+
+Trigger AI triage for multiple escalations.
+
+Resolves each escalation and starts a triage workflow that uses MCP tools to analyze and potentially auto-resolve the issue.
+
+```typescript
+const result = await lt.escalations.bulkTriage({
+  ids: ['esc_1', 'esc_2'],
+  hint: 'Check if the content violates policy section 3.2',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ids` | `string[]` | Yes | Array of escalation UUIDs |
+| `hint` | `string` | No | Natural-language guidance for the triage AI |
+
+**Returns:** `LTApiResult<{ triaged, workflows }>`
+
+**Auth:** Required

package/docs/api/sdk/events.md

@@ -0,0 +1,68 @@
+# lt.events
+
+Subscribe to real-time Long Tail events via in-process callbacks.
+
+## on
+
+Subscribe to events by type pattern. Returns an unsubscribe function.
+
+```typescript
+// Exact event type
+const unsub = lt.events.on('escalation.claimed', (event) => {
+  console.log('claimed:', event.escalationId);
+});
+
+// Category wildcard — all task events
+const unsub2 = lt.events.on('task.*', (event) => {
+  console.log('task event:', event.type);
+});
+
+// Global wildcard — every event
+const unsub3 = lt.events.on('*', (event) => {
+  console.log(event.type, event.workflowId);
+});
+
+// Unsubscribe when done
+unsub();
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `pattern` | `LTEventType \| '*' \| string` | Yes | Event type to match |
+| `callback` | `(event: LTEvent) => void` | Yes | Handler invoked for each matching event |
+
+**Pattern matching:**
+
+| Pattern | Matches |
+|---------|---------|
+| `'task.created'` | Exact match on `task.created` only |
+| `'task.*'` | All events starting with `task.` (e.g. `task.created`, `task.completed`, `task.failed`) |
+| `'*'` | Every event |
+
+**Returns:** `() => void` -- call the returned function to unsubscribe.
+
+**Auth:** Not required
+
+---
+
+### LTEventType values
+
+`task.created`, `task.started`, `task.completed`, `task.escalated`, `task.failed`, `escalation.created`, `escalation.resolved`, `escalation.claimed`, `escalation.released`, `workflow.started`, `workflow.completed`, `workflow.failed`, `activity.started`, `activity.completed`, `activity.failed`, `milestone`
+
+### LTEvent fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `LTEventType \| string` | Event classification |
+| `source` | `string` | Origin: `'interceptor'`, `'orchestrator'`, or `'activity'` |
+| `workflowId` | `string` | The workflow instance that produced this event |
+| `workflowName` | `string` | The workflow function name |
+| `taskQueue` | `string` | The task queue the workflow ran on |
+| `taskId` | `string?` | The task ID (present when orchestrated) |
+| `escalationId` | `string?` | The escalation ID (present for escalation events) |
+| `originId` | `string?` | Root process lineage |
+| `status` | `string?` | Task or workflow status after this event |
+| `data` | `Record<string, unknown>?` | Event-specific payload |
+| `timestamp` | `string` | ISO 8601 timestamp |

package/docs/api/sdk/exports.md

@@ -0,0 +1,124 @@
+# lt.exports
+
+Export workflow state, execution trees, and job metadata.
+
+## listJobs
+
+List export jobs with optional filtering, sorting, and pagination.
+
+```typescript
+const result = await lt.exports.listJobs({ limit: 25, offset: 0, status: 'completed' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `limit` | `number` | No | Maximum number of jobs to return |
+| `offset` | `number` | No | Number of jobs to skip for pagination |
+| `entity` | `string` | No | Filter by entity/workflow type |
+| `search` | `string` | No | Free-text search across job fields |
+| `status` | `string` | No | Filter by job status |
+| `sort_by` | `string` | No | Field name to sort results by |
+| `order` | `string` | No | Sort direction (`asc` or `desc`) |
+| `registered` | `string` | No | Filter by registration status |
+
+**Returns:** `LTApiResult<{ jobs, total, ... }>`
+
+**Auth:** Not required
+
+---
+
+## exportState
+
+Export the stored state (hash data) of a workflow. Fields can be filtered via allow/block lists.
+
+```typescript
+const result = await lt.exports.exportState({
+  workflowId: 'wf_abc123',
+  allow: ['data', 'status'],
+  values: true,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | The workflow's unique identifier |
+| `allow` | `LTExportField[]` | No | Whitelist of field names to include |
+| `block` | `LTExportField[]` | No | Blacklist of field names to exclude |
+| `values` | `boolean` | No | When true, include field values (not just names) |
+
+`LTExportField` is one of: `'data'`, `'state'`, `'status'`, `'timeline'`, `'transitions'`
+
+**Returns:** `LTApiResult<ExportedState>` -- returns 404 if the workflow is not found or data has expired.
+
+**Auth:** Not required
+
+---
+
+## exportExecution
+
+Export the full execution tree of a workflow, including activity inputs and results.
+
+```typescript
+const result = await lt.exports.exportExecution({
+  workflowId: 'wf_abc123',
+  excludeSystem: true,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | The workflow's unique identifier |
+| `excludeSystem` | `boolean` | No | Omit system-generated activities from the export |
+| `omitResults` | `boolean` | No | Exclude activity result payloads |
+| `mode` | `ExportMode` | No | Export mode controlling output format (e.g., tree, flat) |
+| `maxDepth` | `number` | No | Maximum depth to traverse in the execution tree |
+
+**Returns:** `LTApiResult<ExecutionExport>` -- returns 404 if the workflow is not found or data has expired.
+
+**Auth:** Not required
+
+---
+
+## getStatus
+
+Get the current status of a workflow (e.g., running, completed, failed).
+
+```typescript
+const result = await lt.exports.getStatus({ workflowId: 'wf_abc123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | The workflow's unique identifier |
+
+**Returns:** `LTApiResult<WorkflowStatus>` -- returns 404 if the workflow is not found or data has expired.
+
+**Auth:** Not required
+
+---
+
+## getState
+
+Get the current state data of a workflow.
+
+```typescript
+const result = await lt.exports.getState({ workflowId: 'wf_abc123' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `workflowId` | `string` | Yes | The workflow's unique identifier |
+
+**Returns:** `LTApiResult<WorkflowState>` -- returns 404 if the workflow is not found or data has expired.
+
+**Auth:** Not required

package/docs/api/sdk/insight.md

@@ -0,0 +1,112 @@
+# lt.insight
+
+LLM-powered natural-language queries and workflow generation against connected MCP servers.
+
+## mcpQuery
+
+Execute a natural-language query against connected MCP servers.
+
+```typescript
+const result = await lt.insight.mcpQuery({
+  prompt: 'Find all open issues labeled bug',
+  tags: ['github'],
+  wait: true,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prompt` | `string` | Yes | The natural-language query to execute |
+| `tags` | `string[]` | No | Tags to scope which MCP servers are queried |
+| `wait` | `boolean` | No | When true, block until the query completes; otherwise return immediately |
+| `direct` | `boolean` | No | When true, bypass workflow orchestration and query the LLM directly |
+| `context` | `any` | No | Additional context forwarded to the LLM |
+
+**Returns:** `LTApiResult<any>`
+
+**Auth:** Optional (userId forwarded to the query pipeline when provided)
+
+---
+
+## buildWorkflow
+
+Generate a workflow definition from a natural-language description.
+
+```typescript
+const result = await lt.insight.buildWorkflow({
+  prompt: 'Screenshot a URL, analyze the image, and store results in a spreadsheet',
+  tags: ['browser', 'vision', 'sheets'],
+  wait: true,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prompt` | `string` | Yes | Natural-language description of the desired workflow |
+| `tags` | `string[]` | No | Tags to scope available MCP tools |
+| `wait` | `boolean` | No | When true, block until generation completes |
+| `feedback` | `string` | No | Refinement feedback on a previous generation |
+| `prior_yaml` | `string` | No | YAML from a previous generation to refine |
+| `answers` | `any` | No | Answers to clarifying questions from a prior round |
+| `prior_questions` | `any` | No | Questions from a prior round for context |
+
+**Returns:** `LTApiResult<any>`
+
+**Auth:** Optional (userId forwarded to the builder when provided)
+
+---
+
+## refineWorkflow
+
+Refine an existing workflow definition using feedback.
+
+```typescript
+const result = await lt.insight.refineWorkflow({
+  prompt: 'Screenshot and analyze a URL',
+  prior_yaml: existingYaml,
+  feedback: 'Add a retry step if the screenshot fails',
+  wait: true,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prompt` | `string` | Yes | Original natural-language description |
+| `prior_yaml` | `string` | Yes | The YAML workflow to refine |
+| `feedback` | `string` | Yes | User feedback describing desired changes |
+| `tags` | `string[]` | No | Tags to scope available MCP tools |
+| `wait` | `boolean` | No | When true, block until refinement completes |
+
+**Returns:** `LTApiResult<any>`
+
+**Auth:** Optional (userId forwarded to the builder when provided)
+
+---
+
+## describeWorkflow
+
+Generate a human-readable description and tags for a workflow.
+
+```typescript
+const result = await lt.insight.describeWorkflow({
+  prompt: 'Take a screenshot of a URL and analyze it with GPT-4 Vision',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prompt` | `string` | Yes | The workflow prompt or content to describe |
+| `result_title` | `string` | No | Title from the workflow result for additional context |
+| `result_summary` | `string` | No | Summary from the workflow result for additional context |
+
+**Returns:** `LTApiResult<{ description: string, tags: string[] }>`
+
+**Auth:** Not required