@hotmeshio/long-tail 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as
+defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights
+under the License will not include, and the License does not grant to
+you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of
+the rights granted to you under the License to provide to third parties,
+for a fee or other consideration (including without limitation fees for
+hosting or consulting/support services related to the Software), a
+product or service whose value derives, entirely or substantially, from
+the functionality of the Software. Any license notice or attribution
+required by the License must also include this Commons Clause License
+Condition notice.
+
+Software: HotMesh LongTail
+
+License: Apache 2.0
+
+Licensor: HotMeshIO
+
+---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,262 @@
+# Long Tail
+
+Long Tail treats uncertainty as part of the workflow — not as an error, but as an undiscovered pathway. When confidence is low, the task escalates. When a human can't fix it, AI triages with the tools at hand. When AI finds the fix, the solution is compiled into a deterministic workflow so the next occurrence runs automatically — no LLM, no human, no cost.
+
+The system works because everything is treated as a **tool**.
+
+Activities, AI models, human reviewers, and compiled workflows all expose the same interface. A workflow doesn't need to know whether its next step is code, a model, or a person waiting on a screen. The protocol is the same. This is what makes handoffs seamless and what lets the system compose solutions from parts it already has.
+
+## Quick Start
+
+```bash
+git clone https://github.com/hotmeshio/long-tail.git
+cd long-tail
+docker compose up -d --build
+```
+
+Open [http://localhost:3000](http://localhost:3000) once healthy (~10s). Four workflows seed the dashboard.
+
+| User | Password | Role |
+|------|----------|------|
+| `superadmin` | `l0ngt@1l` | superadmin |
+| `admin` | `l0ngt@1l` | admin |
+| `engineer` | `l0ngt@1l` | engineer |
+| `reviewer` | `l0ngt@1l` | reviewer |
+
+To reset: `docker compose down -v && docker compose up -d --build`
+
+## Write a Workflow
+
+A **workflow** is a deterministic function. It receives an envelope, makes decisions, and returns a result. If the process crashes mid-execution, the workflow replays from its last checkpoint — no work is lost, no step runs twice.
+
+Register it with Long Tail and it becomes a **certified workflow**. The interceptor wraps every execution in an escalation chain: sub-workflows that would normally throw instead escalate, humans and AI collaborate to resolve, and the original workflow resumes with the answer. A certified workflow cannot silently fail — every error is either handled or surfaced.
+
+```typescript
+import { Durable } from '@hotmeshio/hotmesh';
+import type { LTEnvelope, LTReturn, LTEscalation } from '@hotmeshio/long-tail';
+import * as activities from './activities';
+
+const { analyzeContent } = Durable.workflow.proxyActivities<typeof activities>({
+  activities,
+});
+
+export async function reviewContent(
+  envelope: LTEnvelope,
+): Promise<LTReturn | LTEscalation> {
+
+  // A resolved escalation re-enters here with the human's decision
+  if (envelope.resolver) {
+    return {
+      type: 'return',
+      data: {
+        ...envelope.data,
+        resolution: envelope.resolver,
+      },
+    };
+  }
+
+  const analysis = await analyzeContent(envelope.data.content);
+
+  if (analysis.confidence >= 0.85) {
+    return {
+      type: 'return',
+      data: { approved: true, analysis },
+    };
+  }
+
+  // Low confidence — escalate to a human reviewer
+  return {
+    type: 'escalation',
+    data: {
+      content: envelope.data.content,
+      analysis,
+    },
+    message: `Review needed (confidence: ${analysis.confidence})`,
+    role: 'reviewer',
+  };
+}
+```
+
+Side effects — API calls, LLM invocations, database queries — live in **activity** functions. The `proxyActivities` call wraps them so the workflow engine can checkpoint each result. If a crash occurs, activities replay from cache rather than re-executing.
+
+## Every Activity is a Tool
+
+The `proxyActivities` call in the workflow above does more than checkpoint `analyzeContent` — it also registers it as an **MCP tool**. The function you write is both a durable workflow step and a tool that any agent, workflow, or compiled pipeline can invoke.
+
+The same is true in reverse: register an MCP server and its tools become proxy activities automatically.
+
+```typescript
+// This function is BOTH an activity AND a tool.
+// Called by a workflow via proxyActivities, it's checkpointed.
+// Exposed via MCP, it's discoverable by agents and other workflows.
+export async function classify(args: { content: string }) {
+  const response = await llm.analyze(args.content);
+  return { category: response.category, confidence: response.confidence };
+}
+```
+
+Humans are tools too. Long Tail exposes its escalation queue as an MCP server (`long-tail-human-queue`). Compiled workflows are tools. An agent can call a human the same way it calls a database. A human can kick a task to AI the same way they'd assign it to a colleague. The protocol doesn't care who's on either end.
+
+This uniformity is what makes the system composable — and it's what closes the loop from uncertainty to automation.
+
+See the [Architecture Guide](docs/architecture.md) for project structure, conventions, built-in servers, and tag-based tool discovery. See the [MCP Guide](docs/mcp.md) for server registration, tool calls, and the human queue protocol.
+
+## Workflow Function Registration and Startup
+
+Register and start. MCP Servers initialize, workers start, and the API listens. The only infrastructure is PostgreSQL.
+
+```typescript
+import { start } from '@hotmeshio/long-tail';
+import * as myWorkflow from './workflows/my-workflow';
+
+const lt = await start({
+  database: {
+    host: 'localhost',
+    port: 5432,
+    user: 'postgres',
+    password: 'password',
+    database: 'mydb',
+  },
+  workers: [{
+    taskQueue: 'my-queue',
+    workflow: myWorkflow.reviewContent,
+  }],
+});
+
+const handle = await lt.client.workflow.start({
+  args: [{
+    data: { content: 'Review this' },
+    metadata: {},
+  }],
+  taskQueue: 'my-queue',
+  workflowName: 'reviewContent',
+  workflowId: `review-${Date.now()}`,
+});
+```
+
+See the full [Workflows Guide](docs/workflows.md) for activities, the interceptor, escalation lifecycle, composition, and testing.
+
+## How the System Evolves
+
+The escalation in the workflow above — `{ type: 'escalation' }` — is where the system starts learning. Four layers work together, each one feeding the next.
+
+### 1. Escalation
+
+When AI isn't confident, the workflow returns `{ type: 'escalation' }`. The interceptor creates a record with full context — what the AI tried, what it saw, why it wasn't sure. A human claims the work through the dashboard or API, resolves it, and the workflow re-runs with their decision.
+
+```
+POST /api/escalations/esc-abc123/resolve
+{ "resolverPayload": { "approved": true, "notes": "Content is fine" } }
+```
+
+Most escalations end here. The human had the judgment the AI lacked. But sometimes the human *can't* fix it — the problem isn't a judgment call, it's a process gap.
+
+### 2. Triage
+
+An upside-down page, a document in the wrong language, a missing API credential — the human flags `needsTriage` with a hint, and an AI triage agent takes over.
+
+Because every activity is a tool, the triage agent already has what it needs. It queries the escalation history, discovers available tools by tag, and runs an agentic loop — rotate the page, re-extract data, call an external API, validate against a database. Every tool call is checkpointed. If the agent can't fix it either, it escalates to an engineer with a full diagnosis. The engineer might install a missing tool, fix a configuration, then send it back. The handoff is always bidirectional — human to AI, AI to human, human to different human — until the problem is resolved and the original workflow gets its answer.
+
+### 3. Compilation — Dynamic to Deterministic
+
+Every dynamic execution — whether from triage, an MCP query, or any agentic workflow — produces a recording of which tools were called, in what order, with what data flow between them. The workflow compiler analyzes that recording and converts it into a deterministic YAML pipeline:
+
+```
+Dynamic execution (LLM-driven)                 Compiled workflow (deterministic)
+  navigate_to(url)                                step 1: navigate_to
+  extract_links(page)                        →    step 2: extract_links
+  screenshot(link) × N                            step 3: screenshot (iterates over step 2 output)
+```
+
+The compiler detects iteration patterns, traces data provenance between steps, classifies which inputs are dynamic (user-provided) versus fixed (implementation details), and generates a parameterized input schema. A dashboard wizard walks through the full lifecycle: review the original execution, profile the tool pipeline, configure inputs and tags, deploy, test side-by-side against the original, and verify end-to-end.
+
+The compiled workflow deploys as a new MCP tool — tagged for discovery, versioned, and invocable by any agent, workflow, or API call. See the [Compilation Pipeline Guide](docs/compilation.md) for a detailed walkthrough with screenshots.
+
+### 4. Routing — The Loop Closes
+
+Once deployed, the system routes automatically. Every request passes through the `mcpQueryRouter`, which checks: has this problem been solved before?
+
+```
+User prompt → Router → Discovery (FTS + tags) → LLM Judge (scope match?)
+                 │                                       │
+                 │  confidence ≥ 0.7                     │  no match
+                 ▼                                       ▼
+          mcpDeterministic                          mcpQuery
+          (compiled YAML, no LLM)                   (dynamic, LLM agentic loop)
+```
+
+The deterministic path skips LLM reasoning entirely — it extracts structured inputs from the prompt, maps them to the compiled workflow's schema, and executes the YAML pipeline directly. What took minutes with an LLM now runs in seconds. What cost tokens now costs nothing.
+
+The dynamic path still works exactly as before — and every dynamic execution is a candidate for compilation. The system accumulates deterministic solutions over time. The inventory of tools grows. The need for LLM reasoning shrinks. Problems that once required a human, then required an AI, eventually require neither.
+
+## Developer API
+
+```typescript
+import { start } from '@hotmeshio/long-tail';
+
+const lt = await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  workers: [{ taskQueue: 'my-queue', workflow: myWorkflow.reviewContent }],
+
+  // Everything below is optional
+  examples: true,                                          // seed demo workflows
+  mcp: { server: { enabled: true } },                     // MCP server + clients
+  escalation: { strategy: 'mcp' },                        // AI triage on escalation
+  auth: { secret: process.env.JWT_SECRET },                // JWT auth + IAM identity context
+  telemetry: { honeycomb: { apiKey: process.env.HNY } },   // OpenTelemetry
+  events: { nats: { url: 'nats://localhost:4222' } },      // real-time events
+  logging: { pino: { level: 'info' } },                    // structured logging
+  maintenance: true,                                       // scheduled cleanup
+});
+```
+
+Every cross-cutting concern follows the same pattern: implement a typed interface, register at startup, done. Every workflow executes with identity context — who initiated the request, which user or bot it runs as, and what credentials it holds. Escalations carry the same context, so reviewers see exactly who triggered the work and what permissions were in play. See the [Docs](#docs) section for the full list of guides.
+
+## Deployment
+
+Two container types from the same codebase — one serves the API, the other executes workflows:
+
+```typescript
+// api.ts — REST endpoints, no workflow execution
+await start({ database: { connectionString: process.env.DATABASE_URL } });
+
+// worker.ts — workflow execution, no HTTP server
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  server: { enabled: false },
+  workers: [{ taskQueue: 'my-queue', workflow: reviewContent.reviewContent }],
+});
+```
+
+Both share PostgreSQL and scale independently. See [Cloud Deployment](docs/cloud.md).
+
+## Docs
+
+| Guide | What it covers |
+|-------|---------------|
+| [Compilation Pipeline](docs/compilation.md) | Dynamic → deterministic: full wizard walkthrough with screenshots |
+| [Workflows](docs/workflows.md) | Activities, interceptor, escalation lifecycle, composition, testing |
+| [Architecture](docs/architecture.md) | Project structure, conventions, built-in MCP servers, tag-based discovery |
+| [MCP](docs/mcp.md) | Server registration, tool calls, human queue, compiled workflows as tools |
+| [Escalation Strategies](docs/escalation-strategies.md) | Default, MCP triage, and custom escalation handlers |
+| [Cloud Deployment](docs/cloud.md) | AWS ECS, GCP Cloud Run, Docker configurations |
+| [Data Model](docs/data.md) | Database schema and tables |
+| [Contributing](docs/contributing.md) | Development setup and guidelines |
+
+### Adapter Guides
+
+[Auth](docs/auth.md) | [Events](docs/events.md) | [Telemetry](docs/telemetry.md) | [Logging](docs/logging.md) | [Maintenance](docs/maintenance.md)
+
+### API Reference
+
+[Workflows](docs/api/workflows.md) | [Tasks](docs/api/tasks.md) | [Escalations](docs/api/escalations.md) | [YAML Workflows](docs/api/yaml-workflows.md) | [Users](docs/api/users.md) | [Roles](docs/api/roles.md) | [MCP Servers](docs/api/mcp-servers.md) | [MCP Runs](docs/api/mcp-runs.md) | [Namespaces](docs/api/namespaces.md) | [Settings](docs/api/settings.md) | [Maintenance](docs/api/maintenance.md) | [DBA](docs/api/dba.md) | [Exports](docs/api/exports.md)
+
+## Install
+
+```bash
+npm install @hotmeshio/long-tail @hotmeshio/hotmesh
+```
+
+## License
+
+See [LICENSE](LICENSE).

package/build/examples/external-mcp-server/server.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Example External MCP Server
+ *
+ * Demonstrates how an external MCP server authenticates to Long Tail,
+ * receives delegation tokens via tool args, and fetches user-scoped
+ * OAuth credentials through the delegation API.
+ *
+ * This server exposes an SSE-based MCP interface with one tool:
+ *   fetch_external_data — simulates fetching data from an external API
+ *                         using the user's OAuth credentials.
+ *
+ * Environment:
+ *   LT_API_URL        — Long Tail API base URL (e.g., http://long-tail:3000)
+ *   LT_SERVICE_TOKEN  — Service token for authenticating back to Long Tail
+ *   PORT              — Port to listen on (default: 9090)
+ */
+export {};

package/build/examples/external-mcp-server/server.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * Example External MCP Server
+ *
+ * Demonstrates how an external MCP server authenticates to Long Tail,
+ * receives delegation tokens via tool args, and fetches user-scoped
+ * OAuth credentials through the delegation API.
+ *
+ * This server exposes an SSE-based MCP interface with one tool:
+ *   fetch_external_data — simulates fetching data from an external API
+ *                         using the user's OAuth credentials.
+ *
+ * Environment:
+ *   LT_API_URL        — Long Tail API base URL (e.g., http://long-tail:3000)
+ *   LT_SERVICE_TOKEN  — Service token for authenticating back to Long Tail
+ *   PORT              — Port to listen on (default: 9090)
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = __importDefault(require("express"));
+const app = (0, express_1.default)();
+app.use(express_1.default.json());
+const PORT = parseInt(process.env.PORT || '9090', 10);
+const LT_API_URL = process.env.LT_API_URL || 'http://localhost:3000';
+const LT_SERVICE_TOKEN = process.env.LT_SERVICE_TOKEN || '';
+/**
+ * Validate a delegation token against Long Tail.
+ */
+async function validateDelegation(token) {
+    const res = await fetch(`${LT_API_URL}/api/delegation/validate`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${LT_SERVICE_TOKEN}`,
+        },
+        body: JSON.stringify({ token }),
+    });
+    return res.json();
+}
+/**
+ * Get a user's OAuth access token via the delegation API.
+ */
+async function getUserOAuthToken(delegationToken, provider) {
+    const res = await fetch(`${LT_API_URL}/api/delegation/oauth/${provider}/token`, {
+        headers: { Authorization: `Bearer ${delegationToken}` },
+    });
+    if (!res.ok) {
+        const err = await res.json();
+        throw new Error(err.error || `Failed to get OAuth token: ${res.status}`);
+    }
+    return res.json();
+}
+// ── MCP Tool: fetch_external_data ────────────────────────────────────────────
+/**
+ * Simulates an external MCP tool that needs user-scoped credentials.
+ *
+ * In a real server, this would:
+ * 1. Extract the delegation token from _auth.token
+ * 2. Call the delegation API to get a fresh OAuth access token
+ * 3. Use that token to call an external API (Google Calendar, GitHub, etc.)
+ * 4. Return the results
+ */
+app.post('/tools/fetch_external_data', async (req, res) => {
+    const { provider, query, _auth } = req.body;
+    if (!_auth?.token) {
+        res.status(400).json({
+            error: 'No delegation token provided. This tool requires user authorization.',
+        });
+        return;
+    }
+    try {
+        // 1. Validate the delegation token
+        const validation = await validateDelegation(_auth.token);
+        if (!validation.valid) {
+            res.status(403).json({ error: `Invalid delegation: ${validation.error}` });
+            return;
+        }
+        // 2. Get the user's OAuth token for the requested provider
+        const oauth = await getUserOAuthToken(_auth.token, provider || 'google');
+        // 3. Simulate calling an external API with the OAuth token
+        // In production, this would be a real API call like:
+        //   const data = await fetch('https://api.example.com/data', {
+        //     headers: { Authorization: `Bearer ${oauth.access_token}` }
+        //   });
+        res.json({
+            success: true,
+            userId: validation.userId,
+            provider: provider || 'google',
+            query,
+            result: {
+                message: `Successfully fetched data for user ${validation.userId} using ${provider || 'google'} OAuth token`,
+                token_preview: `${oauth.access_token.slice(0, 10)}...`,
+                expires_at: oauth.expires_at,
+            },
+        });
+    }
+    catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+// ── Health check ─────────────────────────────────────────────────────────────
+app.get('/health', (_req, res) => {
+    res.json({
+        status: 'ok',
+        service: 'external-mcp-server',
+        lt_api: LT_API_URL,
+        has_service_token: !!LT_SERVICE_TOKEN,
+    });
+});
+app.listen(PORT, () => {
+    console.log(`[external-mcp] listening on :${PORT}`);
+    console.log(`[external-mcp] Long Tail API: ${LT_API_URL}`);
+    console.log(`[external-mcp] Service token: ${LT_SERVICE_TOKEN ? 'configured' : 'NOT SET'}`);
+});

package/build/examples/index.d.ts

@@ -0,0 +1,2 @@
+export { exampleWorkers } from './workers';
+export { seedExamples } from './seed';

package/build/examples/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.seedExamples = exports.exampleWorkers = void 0;
+var workers_1 = require("./workers");
+Object.defineProperty(exports, "exampleWorkers", { enumerable: true, get: function () { return workers_1.exampleWorkers; } });
+var seed_1 = require("./seed");
+Object.defineProperty(exports, "seedExamples", { enumerable: true, get: function () { return seed_1.seedExamples; } });

package/build/examples/seed.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Seed example workflows so the dashboard tells a story immediately.
+ * Called automatically when `examples: true` is set in the start config.
+ */
+export declare function seedExamples(client: any): Promise<void>;