@hotmeshio/long-tail 0.1.7 → 0.1.9

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

package/docs/api/sdk/maintenance.md

@@ -0,0 +1,54 @@
+# lt.maintenance
+
+Configure and manage the automated maintenance cron for data pruning.
+
+## getConfig
+
+Return the current maintenance cron configuration and whether it is active.
+
+```typescript
+const result = lt.maintenance.getConfig();
+```
+
+**Parameters:** None
+
+**Returns:** `LTApiResult<{ config: LTMaintenanceConfig | null, active: boolean }>`
+
+**Auth:** Not required
+
+---
+
+## updateConfig
+
+Replace the maintenance configuration and restart the cron. The schedule begins executing immediately.
+
+```typescript
+const result = await lt.maintenance.updateConfig({
+  schedule: '0 3 * * *',
+  rules: [
+    { target: 'streams', action: 'delete', olderThan: '7 days' },
+    { target: 'jobs', action: 'prune', olderThan: '90 days', hasEntity: true },
+  ],
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `schedule` | `string` | Yes | Cron expression (e.g. `'0 3 * * *'`) |
+| `rules` | `LTMaintenanceRule[]` | Yes | Ordered list of maintenance rules |
+
+Each `LTMaintenanceRule` has:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `target` | `'streams' \| 'jobs'` | Yes | Which resource to target |
+| `action` | `'delete' \| 'prune'` | Yes | `delete` = hard-delete rows; `prune` = strip execution artifacts |
+| `olderThan` | `string` | Yes | Retention window, e.g. `'7 days'`, `'90 days'` |
+| `hasEntity` | `boolean` | No | When target is `jobs`: true = entity jobs, false = transient |
+| `pruned` | `boolean` | No | When true, only target jobs already pruned |
+
+**Returns:** `LTApiResult<{ config: LTMaintenanceConfig, restarted: true }>`
+
+**Auth:** Not required

package/docs/api/sdk/mcp-runs.md

@@ -0,0 +1,71 @@
+# lt.mcpRuns
+
+Query MCP workflow execution history: entities, jobs, and full execution timelines.
+
+## listEntities
+
+List distinct entity types for an app (HotMesh namespace).
+
+```typescript
+const result = await lt.mcpRuns.listEntities({ app_id: 'durable' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `app_id` | `string` | Yes | HotMesh app ID (e.g. `"durable"`) |
+
+**Returns:** `LTApiResult<{ entities: string[] }>`
+
+**Auth:** Not required
+
+---
+
+## listJobs
+
+List jobs (workflow executions) for an app, with optional filters.
+
+```typescript
+const result = await lt.mcpRuns.listJobs({
+  app_id: 'durable',
+  entity: 'mcp_query',
+  limit: 25,
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `app_id` | `string` | Yes | HotMesh app ID |
+| `limit` | `number` | No | Max results to return |
+| `offset` | `number` | No | Pagination offset |
+| `entity` | `string` | No | Filter by entity type |
+| `search` | `string` | No | Full-text search |
+| `status` | `string` | No | Filter by job status |
+
+**Returns:** `LTApiResult<{ jobs: any[], total: number }>`
+
+**Auth:** Not required
+
+---
+
+## getExecution
+
+Get the full execution history for a single job.
+
+```typescript
+const result = await lt.mcpRuns.getExecution({ jobId: 'job-123', app_id: 'durable' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `jobId` | `string` | Yes | HotMesh job (workflow) ID |
+| `app_id` | `string` | Yes | HotMesh app ID |
+
+**Returns:** `LTApiResult<ExecutionTimeline>`
+
+**Auth:** Not required

package/docs/api/sdk/mcp.md

@@ -0,0 +1,250 @@
+# lt.mcp
+
+Manage MCP (Model Context Protocol) server registrations, connections, credentials, and tool invocations.
+
+## listServers
+
+List registered MCP servers with optional filtering and pagination.
+
+```typescript
+const result = await lt.mcp.listServers({ status: 'active', limit: 10 });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | `string` | No | Filter by server status (e.g. `'active'`, `'inactive'`) |
+| `auto_connect` | `boolean` | No | Filter by auto-connect setting |
+| `search` | `string` | No | Free-text search across server names and descriptions |
+| `tags` | `string[]` | No | Filter to servers matching any of these tags |
+| `limit` | `number` | No | Maximum number of results to return |
+| `offset` | `number` | No | Pagination offset |
+
+**Returns:** `LTApiResult<{ ... }>`
+
+**Auth:** Not required
+
+---
+
+## createServer
+
+Register a new MCP server.
+
+```typescript
+const result = await lt.mcp.createServer({
+  name: 'my-server',
+  transport_type: 'sse',
+  transport_config: { url: 'https://mcp.example.com/sse' },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Unique display name for the server |
+| `description` | `string` | No | Human-readable description |
+| `transport_type` | `string` | Yes | Transport protocol (e.g. `'sse'`, `'stdio'`) |
+| `transport_config` | `Record<string, any>` | Yes | Transport-specific connection settings |
+| `auto_connect` | `boolean` | No | Whether to connect automatically on startup |
+| `metadata` | `Record<string, any>` | No | Arbitrary key-value metadata |
+| `tags` | `string[]` | No | Tags for categorization and filtering |
+| `compile_hints` | `any` | No | Hints used during tool compilation |
+| `credential_providers` | `string[]` | No | OAuth/credential provider identifiers required by this server |
+
+**Returns:** `LTApiResult<McpServer>`
+
+**Auth:** Not required
+
+---
+
+## testConnection
+
+Test connectivity to an MCP server without persisting it.
+
+```typescript
+const result = await lt.mcp.testConnection({
+  transport_type: 'sse',
+  transport_config: { url: 'https://mcp.example.com/sse' },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `transport_type` | `string` | Yes | Transport protocol to test |
+| `transport_config` | `Record<string, any>` | Yes | Transport-specific connection settings |
+
+**Returns:** `LTApiResult<{ success: boolean, error?: string, tools: any[] }>`
+
+**Auth:** Not required
+
+---
+
+## getServer
+
+Retrieve a single MCP server by ID.
+
+```typescript
+const result = await lt.mcp.getServer({ id: 'server-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | The MCP server identifier |
+
+**Returns:** `LTApiResult<McpServer>`
+
+**Auth:** Not required
+
+---
+
+## updateServer
+
+Update fields on an existing MCP server.
+
+```typescript
+const result = await lt.mcp.updateServer({ id: 'server-id', description: 'Updated description' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | The MCP server identifier |
+| `[key]` | `any` | No | Any mutable server field (name, description, transport_config, etc.) |
+
+**Returns:** `LTApiResult<McpServer>`
+
+**Auth:** Not required
+
+---
+
+## deleteServer
+
+Delete an MCP server by ID.
+
+```typescript
+const result = await lt.mcp.deleteServer({ id: 'server-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | The MCP server identifier |
+
+**Returns:** `LTApiResult<{ deleted: true }>`
+
+**Auth:** Not required
+
+---
+
+## connectServer
+
+Establish a live connection to a registered MCP server.
+
+```typescript
+const result = await lt.mcp.connectServer({ id: 'server-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | The MCP server identifier to connect |
+
+**Returns:** `LTApiResult<{ connected: true, serverId: string }>`
+
+**Auth:** Not required
+
+---
+
+## disconnectServer
+
+Disconnect a live MCP server connection.
+
+```typescript
+const result = await lt.mcp.disconnectServer({ id: 'server-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | The MCP server identifier to disconnect |
+
+**Returns:** `LTApiResult<{ disconnected: true, serverId: string }>`
+
+**Auth:** Not required
+
+---
+
+## getCredentialStatus
+
+Check which credential providers are registered vs missing for an MCP server.
+
+```typescript
+const result = await lt.mcp.getCredentialStatus({ id: 'server-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | The MCP server identifier |
+
+**Returns:** `LTApiResult<{ required: string[], registered: string[], missing: string[] }>`
+
+**Auth:** Required (credentials resolved against the authenticated user)
+
+---
+
+## listTools
+
+List all tools exposed by a connected MCP server.
+
+```typescript
+const result = await lt.mcp.listTools({ id: 'server-id' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | The MCP server identifier |
+
+**Returns:** `LTApiResult<{ tools: any[] }>`
+
+**Auth:** Not required
+
+---
+
+## callTool
+
+Invoke a specific tool on a connected MCP server.
+
+```typescript
+const result = await lt.mcp.callTool({
+  id: 'server-id',
+  toolName: 'screenshot',
+  arguments: { url: 'https://example.com' },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | Yes | The MCP server identifier |
+| `toolName` | `string` | Yes | Name of the tool to invoke |
+| `arguments` | `Record<string, any>` | No | Key-value arguments to pass to the tool |
+| `execute_as` | `string` | No | User ID to impersonate for the tool call |
+
+**Returns:** `LTApiResult<{ result: any }>`
+
+**Auth:** Optional (userId forwarded to the MCP adapter when provided)

package/docs/api/sdk/namespaces.md

@@ -0,0 +1,43 @@
+# lt.namespaces
+
+Manage namespaces for multi-tenant isolation.
+
+## list
+
+List all registered namespaces.
+
+```typescript
+const result = await lt.namespaces.list();
+```
+
+**Parameters:** None
+
+**Returns:** `LTApiResult<{ namespaces: LTNamespace[] }>`
+
+**Auth:** Not required
+
+---
+
+## register
+
+Register a new namespace.
+
+```typescript
+const result = await lt.namespaces.register({
+  name: 'acme-corp',
+  description: 'Acme Corporation tenant',
+  metadata: { region: 'us-east-1' },
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | `string` | Yes | Unique namespace identifier |
+| `description` | `string` | No | Human-readable description |
+| `metadata` | `Record<string, unknown>` | No | Arbitrary key-value metadata |
+
+**Returns:** `LTApiResult<LTNamespace>`
+
+**Auth:** Not required

package/docs/api/sdk/roles.md

@@ -0,0 +1,183 @@
+# lt.roles
+
+Manage roles and escalation chain routing between roles.
+
+## list
+
+List all distinct role names in the system.
+
+```typescript
+const result = await lt.roles.list();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ roles: string[] }>`
+
+**Auth:** Not required
+
+---
+
+## listWithDetails
+
+List all roles with full details (member counts, escalation chains, etc.).
+
+```typescript
+const result = await lt.roles.listWithDetails();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ roles: RoleDetail[] }>`
+
+**Auth:** Not required
+
+---
+
+## create
+
+Create a new role.
+
+The role name is trimmed, lowercased, and validated against `^[a-z][a-z0-9_-]*$`.
+
+```typescript
+const result = await lt.roles.create({ role: 'senior-reviewer' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | Yes | Role name (lowercase letters, numbers, hyphens, underscores; must start with a letter) |
+
+**Returns:** `LTApiResult<{ role: string }>` (status 201)
+
+**Auth:** Not required
+
+---
+
+## delete
+
+Delete a role from the system.
+
+```typescript
+const result = await lt.roles.delete({ role: 'old-role' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | Yes | Role name to delete |
+
+**Returns:** `LTApiResult<{ deleted: true }>` -- returns 409 if the role cannot be deleted (e.g., still assigned to users).
+
+**Auth:** Not required
+
+---
+
+## getEscalationChains
+
+Retrieve all escalation chains across all roles.
+
+```typescript
+const result = await lt.roles.getEscalationChains();
+```
+
+**Parameters:** None (pass `{}` or `undefined`).
+
+**Returns:** `LTApiResult<{ chains: EscalationChain[] }>`
+
+**Auth:** Not required
+
+---
+
+## addEscalationChain
+
+Add an escalation chain link from one role to another.
+
+```typescript
+const result = await lt.roles.addEscalationChain({
+  source_role: 'reviewer',
+  target_role: 'senior-reviewer',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `source_role` | `string` | Yes | Role that escalates from |
+| `target_role` | `string` | Yes | Role that receives the escalation |
+
+**Returns:** `LTApiResult<{ source_role, target_role }>` (status 201)
+
+**Auth:** Not required
+
+---
+
+## removeEscalationChain
+
+Remove an escalation chain link between two roles.
+
+```typescript
+const result = await lt.roles.removeEscalationChain({
+  source_role: 'reviewer',
+  target_role: 'senior-reviewer',
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `source_role` | `string` | Yes | Role that escalates from |
+| `target_role` | `string` | Yes | Role that receives the escalation |
+
+**Returns:** `LTApiResult<{ removed: true }>` -- returns 404 if not found.
+
+**Auth:** Not required
+
+---
+
+## getEscalationTargets
+
+Get all escalation target roles for a given source role.
+
+```typescript
+const result = await lt.roles.getEscalationTargets({ role: 'reviewer' });
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | Yes | Source role to look up targets for |
+
+**Returns:** `LTApiResult<{ targets: string[] }>`
+
+**Auth:** Not required
+
+---
+
+## replaceEscalationTargets
+
+Replace all escalation targets for a role with a new set.
+
+```typescript
+const result = await lt.roles.replaceEscalationTargets({
+  role: 'reviewer',
+  targets: ['senior-reviewer', 'team-lead'],
+});
+```
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `role` | `string` | Yes | Source role whose targets are being replaced |
+| `targets` | `string[]` | Yes | Array of target role names |
+
+**Returns:** `LTApiResult<{ role, targets }>`
+
+**Auth:** Not required