@hotmeshio/long-tail 0.4.17 → 0.4.19

package/docs/api/mcp/claude-code.md

@@ -0,0 +1,47 @@
+# Claude Code
+
+Agentic coding assistant via Claude Code CLI. Execute development tasks: code generation, refactoring, file analysis, and multi-step workflows.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-claude-code` |
+| Category | Development |
+| AI required | Yes |
+| Credential providers | anthropic |
+
+## Compile Hints
+
+execute_task runs Claude Code as a subprocess. The `prompt` parameter is ALWAYS a dynamic trigger input. Keep prompts self-contained. For read-only analysis, restrict with allowed_tools: ["Read", "Grep", "Glob"].
+
+## Tools
+
+### execute_task
+
+Run a task using Claude Code CLI.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| prompt | string | Yes | The task prompt to execute. |
+| working_directory | string | No | Working directory for the task (default /app). |
+| allowed_tools | string[] | No | Restrict which tools Claude Code may use. |
+| max_turns | number | No | Maximum conversation turns (default 5). |
+| model | string | No | Model to use for the task. |
+| system_prompt | string | No | System prompt override. |
+| timeout_ms | number | No | Timeout in milliseconds (default 120000). |
+| credential_label | string | No | Credential label for API key resolution. |
+
+### check_availability
+
+Check if Claude Code CLI is installed and an API key is available.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:** None.

package/docs/api/mcp/docs.md

@@ -0,0 +1,54 @@
+# Docs
+
+Product documentation search and retrieval. List, search, and read Long Tail documentation.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-docs` |
+| Category | Reference |
+| AI required | No |
+| Credential providers | — |
+
+## Compile Hints
+
+None.
+
+## Tools
+
+### list_docs
+
+List all available documentation files with their titles.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:** None.
+
+### search_docs
+
+Search across all documentation for a keyword or phrase. Returns matching files with line context.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| query | string | Yes | Search term or phrase to find in documentation |
+
+### read_doc
+
+Read the full content of a documentation file.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | Yes | Document path relative to docs/ (e.g. "mcp.md" or "api/tasks.md") |

package/docs/api/mcp/events.md

@@ -0,0 +1,80 @@
+# Events
+
+Event bus for agent-to-agent communication. Publish custom events that other agents subscribe to and react to.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-events` |
+| Category | Communication |
+| AI required | No |
+| Credential providers | — |
+
+## Compile Hints
+
+publish_event: topic follows app.{namespace}.{entity}.{action} convention. The app. prefix is auto-added if omitted. Events are delivered to all matching subscribers.
+
+## Tools
+
+### publish_event
+
+Publish a custom event to the event bus. Other agents and workflows can subscribe to these events and react.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| topic | string | Yes | Event topic using dot-delimited segments (e.g., app.epic.apis.createorder.error). The "app." prefix is auto-added if omitted. |
+| data | object | No | Event payload — any structured data relevant to the event. |
+| source | string | No | Source identifier (agent name, workflow type, or free-form label). |
+
+### list_subscriptions
+
+List all active agent event subscriptions, optionally filtered by topic pattern.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| topic | string | No | Optional topic pattern to filter subscriptions. |
+
+### list_topics
+
+Browse the topic catalog to discover available event topics, their descriptions, payload schemas, and subscriber counts.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| category | string | No | Filter by category (task, workflow, escalation, activity, knowledge, agent, app, milestone). |
+| search | string | No | Search topics by name or description. |
+| limit | number | No | Max results (default 50). |
+
+### register_topic
+
+Declare a topic in the catalog with its description and payload schema. Use this to pre-register topics before first publish so other agents can discover them.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| topic | string | Yes | Topic name (e.g., app.vendor.orders.created). |
+| description | string | No | Human-readable description of the event. |
+| category | string | No | Category (defaults to first segment or "app"). |
+| payload_schema | object | No | JSON Schema describing the event.data shape. |
+| tags | string[] | No | Tags for filtering. |

package/docs/api/mcp/file-storage.md

@@ -0,0 +1,76 @@
+# File Storage
+
+Managed file storage for reading, writing, listing, and deleting files.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-file-storage` |
+| Category | Data |
+| AI required | No |
+| Credential providers | — |
+
+## Compile Hints
+
+None.
+
+## Tools
+
+### read_file
+
+Read file content from managed storage. Returns content, size, and detected MIME type. Supports utf8 (text) or base64 encoding.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | Yes | Relative path to the file in managed storage |
+| encoding | string | No | Encoding to use: utf8 or base64 (default: utf8) |
+
+### write_file
+
+Write content to a file in managed storage. Creates directories as needed. Returns the storage reference and size.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | Yes | Relative path for the file in managed storage |
+| content | string | Yes | File content to write |
+| encoding | string | No | Encoding of the content: utf8 or base64 (default: utf8) |
+
+### list_files
+
+List files in a storage directory. Returns file paths, sizes, and modification timestamps.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| directory | string | No | Directory path to list (default: /) |
+| recursive | boolean | No | Whether to list recursively (default: false) |
+
+### delete_file
+
+Remove a file from managed storage.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| path | string | Yes | Relative path to the file to delete |

package/docs/api/mcp/http-fetch.md

@@ -0,0 +1,64 @@
+# HTTP Fetch
+
+HTTP client tools for making GET, POST, and arbitrary HTTP requests.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-http-fetch` |
+| Category | Data |
+| AI required | No |
+| Credential providers | — |
+
+## Compile Hints
+
+HTTP response bodies may be large. Prefer specific fields from parsed JSON rather than raw body.
+
+## Tools
+
+### http_request
+
+Make an HTTP request to any URL. Supports all methods, custom headers, and request bodies. Returns status, headers, and body.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| url | string | Yes | URL to request |
+| method | string | No | HTTP method (default: GET) |
+| headers | object | No | Request headers |
+| body | string | No | Request body |
+| timeout_ms | number | No | Request timeout in milliseconds |
+
+### fetch_json
+
+GET a URL and parse the response as JSON. Convenience wrapper around http_request.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| url | string | Yes | URL to fetch JSON from |
+| headers | object | No | Request headers |
+
+### fetch_text
+
+GET a URL and return the response as text. Returns content, status, and content type.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| url | string | Yes | URL to fetch text from |
+| headers | object | No | Request headers |

package/docs/api/mcp/human-queue.md

@@ -0,0 +1,101 @@
+# Human Queue
+
+Built-in escalation and human queue management. Exposes the escalation API as MCP tools for AI agents and remediation workflows.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-human-queue` |
+| Category | Automation |
+| AI required | No |
+| Credential providers | — |
+
+## Compile Hints
+
+escalate_and_wait creates a durable pause point. The step AFTER escalate_and_wait is always a signal step (kind: "signal") that receives the human response. Fields from the signal step output (e.g., password) must be wired via data_flow edges to ALL downstream steps that need them.
+
+## Tools
+
+### escalate_to_human
+
+Create a new escalation for human review. Returns the escalation ID.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| role | string | Yes | Target role for the escalation (e.g., "reviewer") |
+| message | string | Yes | Description of what needs human review |
+| data | object | No | Contextual data for the reviewer |
+| type | string | No | Escalation type classification (default: "mcp") |
+| subtype | string | No | Escalation subtype (default: "tool_call") |
+| priority | number | No | Priority: 1 (highest) to 4 (lowest) (default: 2) |
+
+### check_resolution
+
+Check the status of an escalation. Returns status and resolver payload if resolved.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| escalation_id | string | Yes | The escalation ID to check |
+
+### get_available_work
+
+List available escalations for a role. Returns pending, unassigned escalations.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| role | string | Yes | Role to filter by |
+| limit | number | No | Max results to return (default: 10) |
+
+### claim_and_resolve
+
+Claim an escalation and immediately resolve it with a payload. Atomic operation.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| escalation_id | string | Yes | The escalation ID to claim and resolve |
+| resolver_id | string | Yes | Identifier for who/what is resolving |
+| payload | object | Yes | Resolution payload data |
+
+### escalate_and_wait
+
+Create an escalation and pause the workflow until a human responds. Returns a signal ID that the workflow uses to wait durably. Preferred over escalate_to_human + check_resolution polling.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| role | string | Yes | Target role for the escalation (e.g., "reviewer") |
+| message | string | Yes | Description of what input is needed from the human |
+| form_schema | object | No | JSON Schema for the resolver form. Use format:"password" for sensitive fields. |
+| data | object | No | Contextual data for the reviewer |
+| assigned_to | string | No | Auto-assign to a specific user |
+| type | string | No | Escalation type classification (default: "mcp") |
+| subtype | string | No | Escalation subtype (default: "wait_for_human") |
+| priority | number | No | Priority: 1 (highest) to 4 (lowest) (default: 1) |

package/docs/api/mcp/index.md

@@ -0,0 +1,52 @@
+# MCP Tools Reference
+
+Long Tail exposes its full API surface as MCP (Model Context Protocol) tools. These tools allow AI agents (or Long Tail itself in reflexive mode) to perform any action a human would via the dashboard or REST APIs.
+
+**Endpoint**: `POST /mcp` — see [MCP Endpoint](../http/mcp-endpoint.md) for connection examples, authentication, and scope filtering.
+
+## Exposure Control
+
+Configure which tools are exposed when Long Tail acts as an MCP server:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `mcp.exposure.readOnly` | boolean | false | Only expose tools marked `read_safe` |
+| `mcp.exposure.hideAiWhenUnavailable` | boolean | true | Hide AI-dependent servers when no API key |
+| `mcp.exposure.allowServers` | string[] | — | Explicit server allowlist |
+| `mcp.exposure.denyServers` | string[] | — | Server denylist |
+
+## Built-in Servers
+
+These servers ship with the product and reflect the core API surface:
+
+| Server | Category | Tools | Description |
+|--------|----------|-------|-------------|
+| [long-tail-admin](admin.md) | System | 71 | Unified system management — tasks, escalations, agents, workflows, users, etc. |
+| [long-tail-human-queue](human-queue.md) | Automation | 5 | Escalation workflow primitives (durable pause + signal) |
+| [long-tail-file-storage](file-storage.md) | Data | 4 | Managed file storage (MinIO/GCS/S3) |
+| [long-tail-http-fetch](http-fetch.md) | Data | 3 | HTTP client for external requests |
+| [long-tail-schema-exchange](schema-exchange.md) | Data | 2 | Schema-validated HTTP exchange with credential resolution |
+| [long-tail-oauth](oauth.md) | System | 3 | OAuth token management and refresh |
+| [long-tail-knowledge](knowledge.md) | Data | 7 | Persistent JSONB knowledge store |
+| [long-tail-docs](docs.md) | Reference | 3 | Documentation search and retrieval |
+| [long-tail-events](events.md) | Communication | 4 | Event bus pub/sub |
+| [long-tail-vision](vision.md) | Analysis | 2 | Image analysis via LLM vision (AI key required) |
+| [long-tail-translation](translation.md) | Analysis | 1 | Text translation via LLM (AI key required) |
+| [long-tail-claude-code](claude-code.md) | Development | 2 | Agentic code execution (AI key required) |
+
+## Example Servers
+
+These servers are included as examples of how to extend Long Tail with additional MCP capabilities. They demonstrate the registration pattern for adding browser automation or other domain-specific tools:
+
+| Server | Category | Description |
+|--------|----------|-------------|
+| long-tail-playwright | Automation | Low-level browser automation via Playwright (requires binary) |
+| long-tail-playwright-cli | Automation | High-level browser automation |
+| long-tail-gmail | Communication | Gmail integration (OAuth) |
+| long-tail-image-tools | Media | Image processing via sharp |
+
+See `examples/mcp-servers/` for the registration pattern.
+
+## Read-Safe Classification
+
+Every tool is classified as either **read-safe** (query-only, no side effects) or **write** (modifies state). When `mcp.exposure.readOnly` is enabled, only read-safe tools are available to external MCP consumers.

package/docs/api/mcp/knowledge.md

@@ -0,0 +1,125 @@
+# Knowledge
+
+Persistent knowledge store for autonomous agents. Store, retrieve, search, and accumulate JSONB documents in isolated domains.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-knowledge` |
+| Category | Data |
+| AI required | No |
+| Credential providers | — |
+
+## Compile Hints
+
+store_knowledge: domain (string), key (string), data (object — MUST be JSON object, never string). Upserts by domain+key. search_knowledge uses JSONB containment (@>). append_knowledge adds to arrays without replacing. list_domains returns all domains with counts.
+
+## Tools
+
+### store_knowledge
+
+Store a value in a 3-level additive hierarchy: domain > key > field. Upserts by domain+key — fields accumulate across calls. Same domain+key+field overwrites that field.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | string | Yes | Top level — groups entries by namespace (e.g. "screenshots", "config") |
+| key | string | Yes | Second level — unique identifier within domain (e.g. "homepage") |
+| data | any | Yes | The value to store. Any type when field is provided; must be an object when field is omitted. |
+| field | string | No | Third level (leaf) — names a specific field. Different fields accumulate; same field overwrites. |
+| tags | string[] | No | Categorization tags (unioned on upsert) |
+
+### get_knowledge
+
+Retrieve a single knowledge entry by domain and key.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | string | Yes | Knowledge domain |
+| key | string | Yes | Document key |
+
+### search_knowledge
+
+Search knowledge entries using JSONB containment queries. The query object matches entries whose data contains the specified key-value pairs.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | string | Yes | Knowledge domain to search |
+| query | object | Yes | JSONB containment query |
+| tags | string[] | No | Filter by tags |
+| limit | number | No | Max results (default 50) |
+
+### list_knowledge
+
+List knowledge entries in a domain, optionally filtered by tags. Returns most recently updated first.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | string | Yes | Knowledge domain |
+| tags | string[] | No | Filter by tags |
+| limit | number | No | Max results (default 50) |
+| offset | number | No | Pagination offset |
+
+### delete_knowledge
+
+Delete a knowledge entry by domain and key.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | string | Yes | Knowledge domain |
+| key | string | Yes | Document key to delete |
+
+### list_domains
+
+List all knowledge domains with entry counts and last-updated timestamps.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:** None.
+
+### append_knowledge
+
+Append a value to an array field within a knowledge entry. Creates the entry and array if they do not exist.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| domain | string | Yes | Knowledge domain |
+| key | string | Yes | Document key |
+| path | string | Yes | JSONB path to array field |
+| value | any | Yes | Value to append to the array |

package/docs/api/mcp/oauth.md

@@ -0,0 +1,62 @@
+# OAuth
+
+OAuth token management. Get fresh access tokens for external services. Handles automatic token refresh.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-oauth` |
+| Category | System |
+| AI required | No |
+| Credential providers | — |
+
+## Compile Hints
+
+get_access_token returns a short-lived token. Call immediately before authenticated API requests — do not cache across steps.
+
+## Tools
+
+### get_access_token
+
+Get a fresh OAuth access token for an external service. Automatically refreshes expired tokens.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| provider | string | Yes | OAuth provider name (google, github, microsoft, anthropic, etc.) |
+| user_id | string | Yes | User ID to get token for |
+| label | string | No | Credential label (default: "default"). Select among multiple credentials for the same provider. |
+
+### list_connections
+
+List all OAuth providers connected for a user. Returns provider, label, and credential type for each connection.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| user_id | string | Yes | User ID to list connections for |
+
+### revoke_connection
+
+Disconnect an OAuth provider for a user, removing stored tokens. Use label to target a specific credential.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| provider | string | Yes | OAuth provider name to disconnect |
+| user_id | string | Yes | User ID to revoke connection for |
+| label | string | No | Credential label to revoke (default: "default") |