@hotmeshio/long-tail 0.4.17 → 0.4.19

package/docs/api/mcp/schema-exchange.md

@@ -0,0 +1,56 @@
+# Schema Exchange
+
+Schema-driven data exchange with external service endpoints. Validates requests and responses against JSON Schema.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-schema-exchange` |
+| Category | Data |
+| AI required | No |
+| Credential providers | — |
+
+## Compile Hints
+
+Validates requests before sending and responses after receiving. Embed request_schema and response_schema as STATIC values. Exchange output: { status, data, headers, elapsed_ms, validated }. API response is in .data field. For auth, prefer credential_provider over manual token wiring.
+
+## Tools
+
+### exchange
+
+Exchange data with an external service endpoint under schema enforcement. Validates request body against request_schema before sending and response body against response_schema after receiving.
+
+| | |
+|---|---|
+| Read-safe | No |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| endpoint | string | Yes | Service endpoint URL |
+| method | string | Yes | HTTP method: GET, POST, PUT, DELETE, PATCH |
+| headers | object | No | Request headers |
+| query | object | No | Query parameters |
+| body | any | No | Request body (validated against request_schema if provided) |
+| request_schema | object | No | JSON Schema for request body validation |
+| response_schema | object | No | JSON Schema for response body validation |
+| timeout_ms | number | No | Request timeout in milliseconds |
+| credential_provider | string | No | Credential provider name — resolves auth from the connection store automatically |
+| credential_label | string | No | Credential label for multi-credential accounts |
+| auth_scheme | string | No | Auth scheme (default: Bearer) |
+| auth_header | string | No | Header name for credential (default: Authorization) |
+
+### validate_schema
+
+Validate any value against a JSON Schema without making a network call. Useful for pre-validation, testing, and transform verification.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| data | any | Yes | The value to validate |
+| schema | object | Yes | JSON Schema to validate against |

package/docs/api/mcp/translation.md

@@ -0,0 +1,28 @@
+# Translation
+
+Text translation using LLM. Translates content between languages with automatic source language detection.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-translation` |
+| Category | Analysis |
+| AI required | Yes |
+| Credential providers | anthropic |
+
+## Tools
+
+### translate_content
+
+Translate content to target language.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| content | string | Yes | The content to translate. |
+| target_language | string | Yes | Target language for the translation. |
+| source_language | string | No | Source language. Auto-detected if omitted. |

package/docs/api/mcp/vision.md

@@ -0,0 +1,46 @@
+# Vision
+
+Image analysis and description using LLM vision. Analyzes images to extract structured data, text content, and descriptions.
+
+| Property | Value |
+|----------|-------|
+| Server ID | `long-tail-vision` |
+| Category | Analysis |
+| AI required | Yes |
+| Credential providers | anthropic |
+
+## Compile Hints
+
+Vision tools process one image at a time. The argument name is `image` (NOT `image_path`). It accepts a storage path, data URI, or https:// URL. Vision tools do NOT use browser sessions. Do NOT wire page_id or _handle to vision tools. analyze_image output fields: description (string), text_content (string), objects (array).
+
+## Tools
+
+### analyze_image
+
+Analyze an image and extract structured data.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| image | string | Yes | Image source: storage path, data URI, or https:// URL. |
+| prompt | string | No | Optional prompt to guide the analysis. |
+
+### describe_image
+
+Generate a detailed description of an image.
+
+| | |
+|---|---|
+| Read-safe | Yes |
+
+**Parameters:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| image | string | Yes | Image source: storage path, data URI, or https:// URL. |
+| context | string | No | Optional context to guide the description. |

package/docs/api/sdk/settings.md

@@ -12,7 +12,7 @@ const result = await lt.settings.get();
 
 **Parameters:** None
 
-**Returns:** `LTApiResult<{ telemetry, escalation, events, ai }>`
+**Returns:** `LTApiResult<{ telemetry, escalation, events, auth, ai }>`
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -21,6 +21,8 @@ const result = await lt.settings.get();
 | `events.transport` | `'socketio' \| 'nats' \| 'none'` | Dashboard event transport (default: `socketio`; `nats` when `EVENT_TRANSPORT=nats`) |
 | `events.natsWsUrl` | `string \| null` | NATS WebSocket URL (present when NATS adapter registered) |
 | `events.natsToken` | `string \| null` | NATS auth token (present when NATS adapter registered) |
+| `auth.sso` | `boolean` | Whether SSO is configured for embedded deployments |
+| `auth.ssoLogoutUrl` | `string \| null` | Host logout URL (redirected to on dashboard sign out) |
 | `ai.enabled` | `boolean` | Whether an LLM API key is configured |
 
 **Auth:** Not required

package/docs/auth.md

@@ -136,6 +136,115 @@ await start({
 
 This adapter grants admin access to every request. Restrict its use to local environments.
 
+## SSO for Embedded Deployments
+
+When Long Tail is mounted inside a host application (NestJS, Express, Rails, etc.) at a subpath, users authenticate with the host — not with Long Tail. The host's middleware validates cookies, headers, or session tokens before requests reach Long Tail's routes. SSO integration tells Long Tail how to extract that identity and transparently provision matching users.
+
+### How It Works
+
+1. User authenticates with the host application (via OIDC, SAML, cookies, etc.)
+2. Host middleware validates identity and attaches user context to the request
+3. Dashboard loads, detects SSO is enabled via `/api/settings`
+4. Dashboard calls `POST /api/auth/sso` — host cookies are sent automatically
+5. Long Tail calls `sso.resolve(req)`, extracts the host identity, and JIT provisions a user in `lt_users`
+6. Long Tail returns its own JWT — the dashboard stores it for subsequent API calls
+7. All downstream RBAC, escalation claims, and audit trails use the provisioned `lt_users.id`
+
+### Configuration
+
+The host provides a single `resolve` function. Long Tail handles provisioning, role mapping, JWT issuance, and dashboard awareness.
+
+```typescript
+import { start } from '@hotmeshio/long-tail';
+
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  server: { enabled: false }, // host owns the HTTP server
+
+  auth: {
+    secret: process.env.JWT_SECRET,
+    sso: {
+      // Extract identity from the host's already-validated request.
+      // req.user is set by the host's auth middleware before Long Tail sees it.
+      resolve: (req) => {
+        const user = (req as any).user;
+        if (!user) return null;
+        return {
+          externalId: user.id,           // stable identifier → lt_users.external_id
+          displayName: user.displayName,
+          email: user.email,
+          roles: ['operator', 'reviewer'],
+        };
+      },
+
+      // Optional: map host role names to LT role names.
+      // Unmapped roles are ignored. Omit to pass roles through as-is.
+      roleMap: {
+        admin: 'superadmin',
+        operator: 'station-operator',
+      },
+
+      // Optional: default role type for provisioned users (default: 'member')
+      defaultRoleType: 'member',
+
+      // Optional: redirect here when user logs out of LT dashboard
+      logoutUrl: '/auth/logout',
+    },
+  },
+});
+```
+
+### SSOIdentity
+
+The `resolve` function returns an `SSOIdentity` or `null`:
+
+```typescript
+interface SSOIdentity {
+  externalId: string;                    // mapped to lt_users.external_id
+  displayName?: string;                  // lt_users.display_name
+  email?: string;                        // lt_users.email
+  roles?: string[];                      // mapped to lt_user_roles via roleMap
+  metadata?: Record<string, any>;        // lt_users.metadata (JSONB)
+}
+```
+
+### JIT Provisioning
+
+On first contact, Long Tail creates a `lt_users` record with the resolved identity. On subsequent contacts, it syncs any new roles. The internal `lt_users.id` (UUID) is used for all RBAC, escalation claims, and audit trails — the host's external ID is stored in `lt_users.external_id` as a stable lookup key.
+
+### Token Exchange
+
+`POST /api/auth/sso` is a public endpoint (no Bearer required). It calls `sso.resolve(req)`, provisions the user, and returns an LT JWT. The dashboard calls this automatically when `auth.sso` is `true` in settings.
+
+```
+POST /api/auth/sso
+
+Response 200:
+{
+  "token": "<jwt>",
+  "user": {
+    "id": "lt-uuid",
+    "external_id": "host-user-id",
+    "display_name": "Jane Doe",
+    "roles": [{ "role": "operator", "type": "member" }]
+  }
+}
+```
+
+### requireAuth Fallback
+
+When SSO is configured and a request arrives without a Bearer token, `requireAuth` calls `sso.resolve(req)` as a fallback. This allows direct API calls from the host backend (which forward cookies but not Bearer tokens) to authenticate without an explicit exchange. The dashboard always uses Bearer after the initial exchange.
+
+### Role Mapping
+
+Roles are resolved once during the token exchange (not per-request) and baked into the JWT — the same pattern as the built-in login. When the host system changes a user's roles, the new roles take effect on the next token refresh.
+
+If `roleMap` is provided, only mapped roles are assigned. If omitted, host role names are passed through directly as LT role names. Roles named `superadmin` or `admin` are assigned the corresponding role type; all others default to `member`.
+
+### Standalone Deployments
+
+When `auth.sso` is not configured, nothing changes. The login page, OAuth providers, service accounts, and JWT auth all work exactly as before. SSO is purely additive.
+
 ## Service Account Authentication
 
 Service accounts are named identities that authenticate with API keys instead of passwords or OAuth. They share the same RBAC system as human users — same roles, same delegation tokens, same credential storage.

package/docs/dashboard.md

@@ -6,7 +6,7 @@ The Long Tail dashboard is a React single-page application for managing durable
 
 The sidebar organizes pages into five groups.
 
-### Durable Workflows
+### Workflows
 
 | Page | Route | Purpose |
 |------|-------|---------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.4.17",
+  "version": "0.4.19",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

package/build/system/mcp-servers/playwright/browser-lifecycle.d.ts

@@ -1,26 +0,0 @@
-import { type Browser, type Page } from 'playwright';
-import type { PlaywrightHandle } from './types';
-export declare const pages: Map<string, Page>;
-/** Allocate a unique page ID (shared across both playwright servers). */
-export declare function allocatePageId(): string;
-export declare function ensureBrowser(): Promise<Browser>;
-/**
- * Resolve a page from either a local `page_id`, a `_handle`, or "most recent".
- * Handles cross-container reconnection via CDP when needed.
- */
-export declare function resolvePage(args: {
-    page_id?: string;
-    _handle?: PlaywrightHandle;
-}): Promise<{
-    page: Page;
-    pageId: string;
-}>;
-/**
- * Build a _handle for a page. Includes CDP endpoint when available
- * (for cross-container access in distributed deployments).
- */
-export declare function buildHandle(pageId: string): PlaywrightHandle;
-/**
- * Shut down the shared browser and release all pages.
- */
-export declare function stopPlaywrightServer(): Promise<void>;

package/build/system/mcp-servers/playwright/browser-lifecycle.js

@@ -1,125 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.pages = void 0;
-exports.allocatePageId = allocatePageId;
-exports.ensureBrowser = ensureBrowser;
-exports.resolvePage = resolvePage;
-exports.buildHandle = buildHandle;
-exports.stopPlaywrightServer = stopPlaywrightServer;
-const playwright_1 = require("playwright");
-const logger_1 = require("../../../lib/logger");
-const types_1 = require("./types");
-// ── Browser lifecycle ────────────────────────────────────────────────────────
-// Shared browser instance across tool calls within a single server lifetime.
-// Lazy-launched on first use, cleaned up via stopPlaywrightServer().
-let browser = null;
-exports.pages = new Map();
-let pageCounter = 0;
-/** Remote browsers connected via CDP — cached to avoid reconnecting per call. */
-const remoteBrowsers = new Map();
-/** Allocate a unique page ID (shared across both playwright servers). */
-function allocatePageId() {
-    return `page_${++pageCounter}`;
-}
-async function ensureBrowser() {
-    if (!browser || !browser.isConnected()) {
-        browser = await playwright_1.chromium.launch({ headless: true });
-        logger_1.loggerRegistry.info('[lt-mcp:playwright] browser launched');
-    }
-    return browser;
-}
-/**
- * Resolve a page from either a local `page_id`, a `_handle`, or "most recent".
- * Handles cross-container reconnection via CDP when needed.
- */
-async function resolvePage(args) {
-    // 1. Try local pages Map (fast path — same container)
-    const localId = args._handle?.page_id || args.page_id;
-    if (localId) {
-        const local = exports.pages.get(localId);
-        if (local)
-            return { page: local, pageId: localId };
-    }
-    // 2. Try CDP reconnection via handle (cross-container)
-    if (args._handle?.cdp_endpoint) {
-        const cdp = args._handle.cdp_endpoint;
-        let remoteBrowser = remoteBrowsers.get(cdp);
-        if (!remoteBrowser || !remoteBrowser.isConnected()) {
-            try {
-                remoteBrowser = await playwright_1.chromium.connectOverCDP(cdp);
-                remoteBrowsers.set(cdp, remoteBrowser);
-                logger_1.loggerRegistry.info(`[lt-mcp:playwright] connected to remote browser: ${cdp}`);
-            }
-            catch (err) {
-                throw Object.assign(new Error(`Cannot reach browser at ${cdp}`), { code: types_1.SESSION_UNREACHABLE, cdp_endpoint: cdp });
-            }
-        }
-        // Find the page — for now, use the first page in the default context
-        const contexts = remoteBrowser.contexts();
-        const ctx = contexts[0] || await remoteBrowser.newContext();
-        const remotePages = ctx.pages();
-        if (remotePages.length > 0) {
-            const page = remotePages[remotePages.length - 1];
-            const id = args._handle.page_id || `remote_${++pageCounter}`;
-            exports.pages.set(id, page);
-            return { page, pageId: id };
-        }
-        throw Object.assign(new Error(`No pages found on remote browser at ${cdp}`), { code: types_1.SESSION_NOT_FOUND, cdp_endpoint: cdp });
-    }
-    // 3. If a specific page_id was requested but not found, throw structured error
-    if (localId) {
-        throw Object.assign(new Error(`Page ${localId} not found`), { code: types_1.SESSION_NOT_FOUND, page_id: localId });
-    }
-    // 4. Fall back to most recent local page
-    const entries = Array.from(exports.pages.entries());
-    if (entries.length === 0) {
-        throw Object.assign(new Error('No pages open. Navigate to a URL first, or pass a _handle.'), { code: types_1.SESSION_NOT_FOUND });
-    }
-    return { page: entries[entries.length - 1][1], pageId: entries[entries.length - 1][0] };
-}
-/**
- * Build a _handle for a page. Includes CDP endpoint when available
- * (for cross-container access in distributed deployments).
- */
-function buildHandle(pageId) {
-    const handle = {
-        type: 'playwright_page',
-        page_id: pageId,
-    };
-    // Include CDP endpoint if browser exposes one (e.g., launchServer or remote)
-    if (browser && typeof browser.wsEndpoint === 'function') {
-        try {
-            handle.cdp_endpoint = browser.wsEndpoint();
-        }
-        catch {
-            // Not available — single-process mode, local pages Map suffices
-        }
-    }
-    return handle;
-}
-/**
- * Shut down the shared browser and release all pages.
- */
-async function stopPlaywrightServer() {
-    for (const [id, page] of exports.pages) {
-        try {
-            await page.close();
-        }
-        catch { /* ignore */ }
-        exports.pages.delete(id);
-    }
-    // Close remote browsers
-    for (const [endpoint, rb] of remoteBrowsers) {
-        try {
-            await rb.close();
-        }
-        catch { /* ignore */ }
-        remoteBrowsers.delete(endpoint);
-    }
-    if (browser) {
-        await browser.close();
-        browser = null;
-    }
-    pageCounter = 0;
-    logger_1.loggerRegistry.info('[lt-mcp:playwright] browser closed');
-}

package/build/system/mcp-servers/playwright/index.d.ts

@@ -1,25 +0,0 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export { pages, allocatePageId, ensureBrowser, buildHandle, stopPlaywrightServer } from './browser-lifecycle';
-export type { PlaywrightHandle } from './types';
-/**
- * Create a Playwright Browser MCP server.
- *
- * Provides 9 tools for browser automation:
- *   navigate, screenshot, click, fill, wait_for, evaluate, run_script, list_pages, close_page
- *
- * All page-scoped tools participate in the _handle convention:
- * - navigate returns a _handle in its result
- * - All other tools accept _handle to locate the page across activities
- * - Fast path: local pages Map (same container)
- * - Slow path: CDP reconnection (different container)
- *
- * `run_script` is the preferred tool for YAML workflows — it executes a
- * multi-step browser script in a single activity, avoiding cross-activity
- * session issues entirely.
- *
- * Returns a fresh McpServer instance each time. The browser is shared
- * and lazy-launched on first tool call.
- */
-export declare function createPlaywrightServer(options?: {
-    name?: string;
-}): Promise<McpServer>;

package/build/system/mcp-servers/playwright/index.js

@@ -1,42 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.stopPlaywrightServer = exports.buildHandle = exports.ensureBrowser = exports.allocatePageId = exports.pages = void 0;
-exports.createPlaywrightServer = createPlaywrightServer;
-const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
-const logger_1 = require("../../../lib/logger");
-const tools_atomic_1 = require("./tools-atomic");
-const tools_run_script_1 = require("./tools-run-script");
-// Re-export public API consumed by playwright-cli.ts and system/index.ts
-var browser_lifecycle_1 = require("./browser-lifecycle");
-Object.defineProperty(exports, "pages", { enumerable: true, get: function () { return browser_lifecycle_1.pages; } });
-Object.defineProperty(exports, "allocatePageId", { enumerable: true, get: function () { return browser_lifecycle_1.allocatePageId; } });
-Object.defineProperty(exports, "ensureBrowser", { enumerable: true, get: function () { return browser_lifecycle_1.ensureBrowser; } });
-Object.defineProperty(exports, "buildHandle", { enumerable: true, get: function () { return browser_lifecycle_1.buildHandle; } });
-Object.defineProperty(exports, "stopPlaywrightServer", { enumerable: true, get: function () { return browser_lifecycle_1.stopPlaywrightServer; } });
-/**
- * Create a Playwright Browser MCP server.
- *
- * Provides 9 tools for browser automation:
- *   navigate, screenshot, click, fill, wait_for, evaluate, run_script, list_pages, close_page
- *
- * All page-scoped tools participate in the _handle convention:
- * - navigate returns a _handle in its result
- * - All other tools accept _handle to locate the page across activities
- * - Fast path: local pages Map (same container)
- * - Slow path: CDP reconnection (different container)
- *
- * `run_script` is the preferred tool for YAML workflows — it executes a
- * multi-step browser script in a single activity, avoiding cross-activity
- * session issues entirely.
- *
- * Returns a fresh McpServer instance each time. The browser is shared
- * and lazy-launched on first tool call.
- */
-async function createPlaywrightServer(options) {
-    const name = options?.name || 'long-tail-playwright';
-    const instance = new mcp_js_1.McpServer({ name, version: '1.0.0' });
-    (0, tools_atomic_1.registerAtomicTools)(instance);
-    (0, tools_run_script_1.registerRunScript)(instance);
-    logger_1.loggerRegistry.info(`[lt-mcp:playwright] ${name} ready (9 tools registered)`);
-    return instance;
-}