@hotmeshio/long-tail 0.4.12 → 0.4.14

package/README.md

@@ -1,41 +1,14 @@
 # Long Tail
 
-Long Tail turns your PostgreSQL database into a workflow engine where human and AI work share the same durable execution path. Hand off, pull back, escalate, automate — without rewriting systems or losing continuity.
+Write durable workflows in TypeScript. When they need a human, they escalate. When they need AI, they orchestrate. When a pattern repeats, they compile it away. Postgres is the engine.
 
 ```bash
 npm install @hotmeshio/long-tail
 ```
 
-## Use Long Tail for
+## How it works
 
-- **Durable execution** — Your functions run as workflows and checkpoint to Postgres. If the process crashes, execution resumes from the last completed step.
-- **Identity everywhere** — Workflows know who started them, whose credentials govern their execution, and what permissions are in play. IAM is not bolted on — it's woven into every activity call.
-- **Human-in-the-loop** — When confidence is low, the workflow escalates. RBAC-scoped escalation chains route work to the right reviewer. Approval workflows, content review, document verification — the pattern is the same.
-- **AI triage** — When human-in-the-loop teams can't resolve a request, AI takes over. Its tool calls are checkpointed. And when the fix works, it compiles into a deterministic pipeline for next time.
-- **MCP tool orchestration** — Describe what you need. If you've registered the tools, the Pipeline Designer builds the workflow. Every compiled pipeline deploys as a reusable MCP tool.
-
-A dashboard, REST API, and live event stream ship with the package. Use what you need.
-
-## Start
-
-Point at Postgres. Everything else is optional.
-
-```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: 'default', workflow: myWorkflow.reviewContent }],
-  auth: { secret: process.env.JWT_SECRET },
-});
-```
-
-Dashboard at [http://localhost:3000](http://localhost:3000). The [boilerplate](https://github.com/hotmeshio/long-tail-boilerplate) has a working project with custom MCP servers, MinIO, and example workflows.
-
-## Write a Durable Workflow
-
-A workflow receives an envelope and returns a result. Each activity call checkpoints — no work is lost, no step runs twice.
+You write a workflow function. Each activity call checkpoints to Postgres — if the process crashes, it resumes from the last completed step.
 
 ```typescript
 import { Durable } from '@hotmeshio/hotmesh';
@@ -51,6 +24,7 @@ export async function reviewContent(envelope: LTEnvelope) {
     return { type: 'return' as const, data: { approved: true, analysis } };
   }
 
+  // Low confidence — escalate to a human reviewer
   return {
     type: 'escalation' as const,
     role: 'reviewer',
@@ -60,32 +34,39 @@ export async function reviewContent(envelope: LTEnvelope) {
 }
 ```
 
-Activities are plain functions with side effects — API calls, LLM invocations, database queries. The `proxyActivities` call wraps them so the engine can checkpoint each result.
+That's a complete workflow. It runs, checkpoints, and when confidence is low, it hands off to a human. The human resolves it through the dashboard or API, and the workflow completes. No separate queue system, no webhook callbacks — the escalation is part of the execution.
+
+Activities are plain functions:
 
 ```typescript
-// activities.ts
 export async function analyzeContent(content: string) {
   const result = await llm.classify(content);
   return { confidence: result.confidence, flags: result.flags };
 }
 ```
 
-## Compile Workflows
+## Start
 
-Write durable workflows in TypeScript. Compile to YAML DAGs that run without replay overhead. `ltc` is the compiler — like `tsc` for workflows.
+Point at Postgres. Everything else is optional.
 
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
+```typescript
+import { start } from '@hotmeshio/long-tail';
 
-npx ltc compile workflows/              # scan and compile all workflow files
-npx ltc compile --dry-run               # discover without compiling
+const lt = await start({
+  database: { host: 'localhost', port: 5432, user: 'postgres', password: 'password', database: 'mydb' },
+  workers: [{ taskQueue: 'default', workflow: reviewContent }],
+});
 ```
 
-The source is the spec. The compiled YAML is the optimized execution. Both live in the repo. See the [Compiler Guide](docs/compiler.md).
+Dashboard at [http://localhost:3000](http://localhost:3000). The [boilerplate](https://github.com/hotmeshio/long-tail-boilerplate) has a working project with workflows, MCP servers, and MinIO.
+
+## The pattern
 
-## Certify a Workflow
+Most systems start with a durable workflow and stop there. Long Tail keeps going.
 
-Any durable workflow can be promoted to **certified** through the dashboard or API. A certified workflow gains interceptor guarantees: failures escalate instead of throwing, escalation chains route through roles, and every error is either handled or surfaced. It cannot silently fail.
+**Step 1 — Author a durable workflow.** Your function checkpoints to Postgres. It can sleep, branch, call child workflows, wait for signals. Standard durable execution.
+
+**Step 2 — Certify it.** Promotion to certified adds interceptor guarantees: failures escalate instead of throwing, escalation chains route through RBAC-scoped roles, and every error is either handled or surfaced. It cannot silently fail.
 
 ```bash
 curl -X PUT http://localhost:3000/api/workflows/reviewContent/config \
@@ -93,13 +74,17 @@ curl -X PUT http://localhost:3000/api/workflows/reviewContent/config \
   -d '{ "invocable": true, "task_queue": "default", "default_role": "reviewer" }'
 ```
 
-De-certifying removes the interceptor. The workflow continues as a standard durable workflow — same code, different guarantees.
+**Step 3 — React to events.** Workflows publish topics. Agents subscribe. When `activity.failed` fires, an automation can re-run the step, notify a team, or trigger a different workflow. The choreography is dynamic — add subscribers through the dashboard without changing code.
+
+**Step 4 — Compile what repeats.** The Pipeline Designer takes a working execution and compiles it into a deterministic YAML DAG. No LLM at runtime, no replay overhead, typed inputs and outputs. It deploys as a reusable tool that any workflow or API call can invoke.
+
+Over time, the system accumulates compiled tools. Problems that once required a human, then required AI reasoning, eventually require neither.
 
-## Register MCP Servers
+## Register MCP tools
 
-Long Tail connects to any MCP server — an npm package, a remote service, or one you write yourself. Registered tools become durable activities and are available to the Pipeline Designer.
+Long Tail connects to any MCP server. Registered tools become durable activities and are available to the Pipeline Designer.
 
-**Use an existing package** — no code, just register:
+**Existing package — no code:**
 
 ```bash
 curl -X POST http://localhost:3000/api/mcp/servers \
@@ -113,21 +98,14 @@ curl -X POST http://localhost:3000/api/mcp/servers \
   }'
 ```
 
-**Connect a remote server** — point at a URL:
+**Remote server — point at a URL:**
 
 ```bash
 curl -X POST http://localhost:3000/api/mcp/servers \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "name": "my-python-server",
-    "transport_type": "sse",
-    "transport_config": { "url": "http://python-service:8000/mcp" },
-    "tags": ["ml", "classification"],
-    "compile_hints": "Returns confidence scores. Use threshold 0.85 for auto-approve."
-  }'
+  -d '{ "name": "my-python-server", "transport_type": "sse", "transport_config": { "url": "http://python-service:8000/mcp" } }'
 ```
 
-**Write your own** and register it in-process:
+**In-process — write your own:**
 
 ```typescript
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -139,8 +117,8 @@ export function createImageToolsServer(): McpServer {
 
   registerMcpTool(server, 'resize_image', 'Resize an image.', {
     path: z.string().describe('Path to the image'),
-    width: z.number().optional().describe('Target width'),
-    height: z.number().optional().describe('Target height'),
+    width: z.number().optional(),
+    height: z.number().optional(),
   }, async (args: any) => ({
     content: [{ type: 'text', text: JSON.stringify(await resize(args)) }],
   }));
@@ -152,36 +130,33 @@ export function createImageToolsServer(): McpServer {
 ```typescript
 const lt = await start({
   // ...
-  mcp: {
-    serverFactories: { 'image-tools': createImageToolsServer },
-  },
+  mcp: { serverFactories: { 'image-tools': createImageToolsServer } },
 });
 ```
 
-All three paths produce the same outcome: tools callable as durable activities. Tags enable discovery. Compile hints guide the compiler when tools are compiled into deterministic pipelines. See the [MCP guide](docs/mcp.md) for the full registration lifecycle.
+All three paths produce the same outcome: tools callable as durable activities. See the [MCP guide](docs/mcp.md).
 
-## Ask It Anything
+## Compile workflows
 
-Once your tools are registered, the Pipeline Designer orchestrates them. Describe what you need in plain language:
+The `ltc` compiler scans TypeScript workflow files and compiles them to YAML DAGs — like `tsc` for workflows.
 
-> *"Log into localhost:3000 as superadmin, navigate to every page in the sidebar, and save a screenshot of each."*
-
-The system discovers the right MCP servers, calls the tools, chains the results. If it works, the compilation wizard converts the execution into a deterministic pipeline — parameterized inputs, typed schema, no LLM at runtime. It deploys as a new MCP tool that any workflow, agent, or API call can invoke.
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+npx ltc compile workflows/
+```
 
-The inventory of compiled tools grows over time. The need for LLM reasoning shrinks. Problems that once required a human, then required an AI, eventually require neither.
+The source is the spec. The compiled YAML is the optimized execution. Both live in the repo. See the [Compiler Guide](docs/compiler.md).
 
-## Full Configuration
+## Full configuration
 
 ```typescript
 const lt = await start({
   database: { connectionString: process.env.DATABASE_URL },
-  workers: [{ taskQueue: 'default', workflow: myWorkflow.reviewContent }],
+  workers: [{ taskQueue: 'default', workflow: reviewContent }],
 
   // Everything below is optional
-  mcp: {
-    server: { enabled: true },
-    serverFactories: { 'my-tools': createMyToolsServer },
-  },
+  seed: { admin: { externalId: 'admin', password: process.env.ADMIN_PASSWORD } },
+  mcp: { server: { enabled: true }, serverFactories: { 'my-tools': createMyToolsServer } },
   escalation: { strategy: 'mcp' },
   auth: { secret: process.env.JWT_SECRET },
   telemetry: { honeycomb: { apiKey: process.env.HNY } },
@@ -190,56 +165,57 @@ const lt = await start({
 });
 ```
 
-## Use as a Package (No HTTP Server)
+## Embed in an existing app
 
-Long Tail can run as an embedded package inside your existing application — no Express server, no socket.io, no extra ports. The same API surface is available as direct function calls.
+Long Tail runs as an embedded package inside NestJS, Express, or any Node.js application. No extra HTTP server, no extra ports.
 
 ```typescript
 import { start, createClient } from '@hotmeshio/long-tail';
 
-await start({
+const lt = await start({
   database: { connectionString: process.env.DATABASE_URL },
   server: { enabled: false },
-  workers: [{ taskQueue: 'default', workflow: reviewContent.reviewContent }],
+  seed: { admin: { externalId: 'system' } },
+  workers: [{ taskQueue: 'default', workflow: reviewContent }],
 });
 
-const lt = createClient({ auth: { userId: 'system' } });
+const client = createClient({ auth: { userId: lt.adminUserId } });
 
-// Same operations as the REST API — no HTTP overhead
-const tasks = await lt.tasks.list({ status: 'completed', limit: 10 });
-const result = await lt.escalations.claim({ id: 'esc_123', durationMinutes: 30 });
+const tasks = await client.tasks.list({ status: 'completed', limit: 10 });
+const result = await client.escalations.claim({ id: 'esc_123', durationMinutes: 30 });
 ```
 
-Subscribe to events with callbacks instead of socket.io:
+Mount the dashboard at a subpath:
 
 ```typescript
-lt.events.on('task.completed', (event) => {
-  console.log('done:', event.workflowId);
-});
+import { LTExpressAdapter } from '@hotmeshio/long-tail';
 
-lt.events.on('escalation.*', (event) => {
-  notifyTeam(event);
-});
+const adapter = new LTExpressAdapter();
+adapter.setBasePath('/admin/longtail');
+app.use('/admin/longtail', adapter.getRouter());
+```
+
+Subscribe to events with callbacks:
+
+```typescript
+client.events.on('task.completed', (event) => console.log('done:', event.workflowId));
+client.events.on('escalation.*', (event) => notifyTeam(event));
 ```
 
-Every SDK call returns an `LTApiResult` — same status codes, same validation, same RBAC. The transport is the only thing that changes. See the [SDK guide](docs/sdk.md) for the full API reference.
+Every SDK call returns an `LTApiResult` — same status codes, same validation, same RBAC. See the [SDK guide](docs/sdk.md).
 
 ## Deployment
 
 Three modes from the same codebase:
 
 ```typescript
-// 1. Standalone — dashboard + REST API + workers
+// Standalone — dashboard + API + workers
 await start({ database: { connectionString: process.env.DATABASE_URL } });
 
-// 2. Worker-only — workflow execution, no HTTP server
-await start({
-  database: { connectionString: process.env.DATABASE_URL },
-  server: { enabled: false },
-  workers: [{ taskQueue: 'default', workflow: reviewContent.reviewContent }],
-});
+// Worker-only — no HTTP server
+await start({ database: { connectionString: process.env.DATABASE_URL }, server: { enabled: false }, workers: [...] });
 
-// 3. Embedded — inside your NestJS/Next.js/Express app, SDK calls only
+// Embedded — inside your app, SDK calls only
 await start({ database: { connectionString: process.env.DATABASE_URL }, server: { enabled: false } });
 const lt = createClient({ auth: { userId: 'service' } });
 ```
@@ -250,12 +226,12 @@ All modes share PostgreSQL and scale independently. See [Cloud Deployment](docs/
 
 | Guide | What it covers |
 |-------|---------------|
-| [The Long Tail Story](docs/story.md) | Why this exists, what accumulates over time, what you own |
+| [The Long Tail Story](docs/story.md) | Why this exists, what accumulates over time |
 | [Workflows](docs/workflows.md) | Activities, interceptor, escalation lifecycle, composition |
 | [IAM](docs/iam.md) | Identity propagation, service accounts, credential exchange |
 | [Dashboard](docs/dashboard.md) | Navigation, key pages, event feed |
 | [MCP](docs/mcp.md) | Server registration, tool calls, human queue |
-| [Compilation](docs/compilation.md) | Dynamic → deterministic pipeline wizard |
+| [Compilation](docs/compilation.md) | Dynamic to deterministic pipeline wizard |
 | [Compiler](docs/compiler.md) | `ltc compile` — durable TypeScript to YAML DAGs |
 | [CLI](docs/cli.md) | `ltc` — terminal access to workflows, escalations, knowledge, MCP |
 | [Escalation Strategies](docs/escalation-strategies.md) | Default, MCP triage, custom handlers |
@@ -266,7 +242,7 @@ All modes share PostgreSQL and scale independently. See [Cloud Deployment](docs/
 
 **Adapters:** [Auth](docs/auth.md) · [Events](docs/events.md) · [Telemetry](docs/telemetry.md) · [Logging](docs/logging.md) · [Maintenance](docs/maintenance.md) · [OAuth](docs/oauth-and-delegation.md)
 
-**HTTP API:** [Workflows](docs/api/http/workflows.md) · [Tasks](docs/api/http/tasks.md) · [Escalations](docs/api/http/escalations.md) · [YAML Workflows](docs/api/http/yaml-workflows.md) · [Users](docs/api/http/users.md) · [Roles](docs/api/http/roles.md) · [Service Accounts](docs/api/http/service-accounts.md) · [MCP Servers](docs/api/http/mcp-servers.md) · [MCP Runs](docs/api/http/mcp-runs.md) · [Exports](docs/api/http/exports.md)
+**HTTP API:** [Workflows](docs/api/http/workflows.md) · [Tasks](docs/api/http/tasks.md) · [Escalations](docs/api/http/escalations.md) · [YAML Workflows](docs/api/http/yaml-workflows.md) · [Users](docs/api/http/users.md) · [Roles](docs/api/http/roles.md) · [Service Accounts](docs/api/http/service-accounts.md) · [MCP Servers](docs/api/http/mcp-servers.md) · [Pipelines](docs/api/http/pipelines.md) · [Exports](docs/api/http/exports.md)
 
 **SDK:** [Overview](docs/sdk.md) · [Workflows](docs/api/sdk/workflows.md) · [Tasks](docs/api/sdk/tasks.md) · [Escalations](docs/api/sdk/escalations.md) · [YAML Workflows](docs/api/sdk/yaml-workflows.md) · [MCP](docs/api/sdk/mcp.md) · [Events](docs/api/sdk/events.md)
 

package/build/api/escalations/helpers.d.ts

@@ -7,4 +7,18 @@ export declare function checkBulkPermission(userId: string, ids: string[]): Prom
     status: 403;
     error: string;
 }>;
+/**
+ * Resolve an optional assignee external_id to an internal userId.
+ * When omitted, returns the caller's userId from auth.
+ */
+export declare function resolveAssignee(assignee: string | undefined, auth: {
+    userId: string;
+}): Promise<{
+    userId: string;
+} | {
+    error: {
+        status: number;
+        error: string;
+    };
+}>;
 export declare function publishBulkClaimEvents(ids: string[], assignedTo: string): void;

package/build/api/escalations/helpers.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getVisibleRoles = getVisibleRoles;
 exports.validateIds = validateIds;
 exports.checkBulkPermission = checkBulkPermission;
+exports.resolveAssignee = resolveAssignee;
 exports.publishBulkClaimEvents = publishBulkClaimEvents;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
@@ -64,6 +65,19 @@ async function checkBulkPermission(userId, ids) {
     }
     return { allowed: true };
 }
+/**
+ * Resolve an optional assignee external_id to an internal userId.
+ * When omitted, returns the caller's userId from auth.
+ */
+async function resolveAssignee(assignee, auth) {
+    if (!assignee)
+        return { userId: auth.userId };
+    const user = await userService.getUserByExternalId(assignee);
+    if (!user) {
+        return { error: { status: 404, error: `User not found for external_id: ${assignee}` } };
+    }
+    return { userId: user.id };
+}
 function publishBulkClaimEvents(ids, assignedTo) {
     for (const id of ids) {
         (0, publish_1.publishEscalationEvent)({

package/build/api/escalations/index.d.ts

@@ -4,3 +4,4 @@ export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './sin
 export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkEscalate, bulkTriage } from './bulk';
 export { resolveEscalation } from './resolve';
+export { findByMetadata, claimByMetadata, resolveByMetadata } from './metadata';

package/build/api/escalations/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getEscalationStats = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
+exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveEscalation = exports.bulkTriage = exports.bulkEscalate = exports.bulkAssign = exports.bulkClaim = exports.updatePriority = exports.releaseExpiredClaims = exports.releaseEscalation = exports.claimEscalation = exports.escalateToRole = exports.getEscalationsByWorkflowId = exports.getEscalation = exports.getEscalationStats = exports.listDistinctTypes = exports.listAvailableEscalations = exports.listEscalations = exports.createEscalation = void 0;
 var create_1 = require("./create");
 Object.defineProperty(exports, "createEscalation", { enumerable: true, get: function () { return create_1.createEscalation; } });
 var list_1 = require("./list");
@@ -24,3 +24,7 @@ Object.defineProperty(exports, "bulkEscalate", { enumerable: true, get: function
 Object.defineProperty(exports, "bulkTriage", { enumerable: true, get: function () { return bulk_1.bulkTriage; } });
 var resolve_1 = require("./resolve");
 Object.defineProperty(exports, "resolveEscalation", { enumerable: true, get: function () { return resolve_1.resolveEscalation; } });
+var metadata_1 = require("./metadata");
+Object.defineProperty(exports, "findByMetadata", { enumerable: true, get: function () { return metadata_1.findByMetadata; } });
+Object.defineProperty(exports, "claimByMetadata", { enumerable: true, get: function () { return metadata_1.claimByMetadata; } });
+Object.defineProperty(exports, "resolveByMetadata", { enumerable: true, get: function () { return metadata_1.resolveByMetadata; } });

package/build/api/escalations/metadata.d.ts

@@ -0,0 +1,56 @@
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+/**
+ * Find escalations by a metadata key-value pair.
+ *
+ * Uses JSONB containment (`@>`) backed by a GIN index.
+ * Results are RBAC-scoped to the caller's visible roles.
+ *
+ * @param input.key — metadata field name (e.g. `"orderId"`)
+ * @param input.value — metadata field value (e.g. `"order-123"`)
+ * @param input.status — optional status filter (e.g. `"pending"`)
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+export declare function findByMetadata(input: {
+    key: string;
+    value: string;
+    status?: string;
+    limit?: number;
+    offset?: number;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Claim an escalation by metadata key-value pair.
+ *
+ * Finds one available (pending + unassigned/expired) escalation matching
+ * the metadata and claims it atomically. Optionally resolves an assignee
+ * from an external_id.
+ *
+ * @param input.key — metadata field name
+ * @param input.value — metadata field value
+ * @param input.durationMinutes — claim duration (default 30)
+ * @param input.assignee — optional external_id of the user to claim as
+ * @returns `{ status: 200, data: { escalation, isExtension } }`
+ */
+export declare function claimByMetadata(input: {
+    key: string;
+    value: string;
+    durationMinutes?: number;
+    assignee?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Resolve an escalation by metadata key-value pair.
+ *
+ * Finds the pending escalation, auto-claims if unclaimed, then delegates
+ * to the standard resolve logic (supports all 5 resolution paths).
+ *
+ * @param input.key — metadata field name
+ * @param input.value — metadata field value
+ * @param input.resolverPayload — resolution data for the workflow
+ * @param input.assignee — optional external_id of the resolving user
+ * @returns result from the standard resolve endpoint
+ */
+export declare function resolveByMetadata(input: {
+    key: string;
+    value: string;
+    resolverPayload: Record<string, any>;
+    assignee?: string;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/metadata.js

@@ -0,0 +1,178 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findByMetadata = findByMetadata;
+exports.claimByMetadata = claimByMetadata;
+exports.resolveByMetadata = resolveByMetadata;
+const escalationService = __importStar(require("../../services/escalation"));
+const userService = __importStar(require("../../services/user"));
+const publish_1 = require("../../lib/events/publish");
+const helpers_1 = require("./helpers");
+/**
+ * Find escalations by a metadata key-value pair.
+ *
+ * Uses JSONB containment (`@>`) backed by a GIN index.
+ * Results are RBAC-scoped to the caller's visible roles.
+ *
+ * @param input.key — metadata field name (e.g. `"orderId"`)
+ * @param input.value — metadata field value (e.g. `"order-123"`)
+ * @param input.status — optional status filter (e.g. `"pending"`)
+ * @returns `{ status: 200, data: { escalations, total } }`
+ */
+async function findByMetadata(input, auth) {
+    try {
+        if (!input.key || !input.value) {
+            return { status: 400, error: 'key and value are required' };
+        }
+        const result = await escalationService.findByMetadata(input.key, input.value, input.status, input.limit, input.offset);
+        // RBAC: scope to visible roles
+        const visibleRoles = await (0, helpers_1.getVisibleRoles)(auth.userId);
+        if (visibleRoles) {
+            const roleSet = new Set(visibleRoles);
+            result.escalations = result.escalations.filter(e => roleSet.has(e.role));
+            result.total = result.escalations.length;
+        }
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Claim an escalation by metadata key-value pair.
+ *
+ * Finds one available (pending + unassigned/expired) escalation matching
+ * the metadata and claims it atomically. Optionally resolves an assignee
+ * from an external_id.
+ *
+ * @param input.key — metadata field name
+ * @param input.value — metadata field value
+ * @param input.durationMinutes — claim duration (default 30)
+ * @param input.assignee — optional external_id of the user to claim as
+ * @returns `{ status: 200, data: { escalation, isExtension } }`
+ */
+async function claimByMetadata(input, auth) {
+    try {
+        if (!input.key || !input.value) {
+            return { status: 400, error: 'key and value are required' };
+        }
+        const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth);
+        if ('error' in resolved)
+            return resolved.error;
+        const claimUserId = resolved.userId;
+        // RBAC: find the candidate to check role membership before atomic claim
+        const candidates = await escalationService.findByMetadata(input.key, input.value, 'pending', 1, 0);
+        if (candidates.escalations.length === 0) {
+            return { status: 404, error: 'No pending escalation found for this metadata' };
+        }
+        const candidate = candidates.escalations[0];
+        const isSuperAdmin = await userService.isSuperAdmin(auth.userId);
+        if (!isSuperAdmin) {
+            const userHasRole = await userService.hasRole(claimUserId, candidate.role);
+            if (!userHasRole) {
+                return { status: 403, error: `User must have the "${candidate.role}" role to claim this escalation` };
+            }
+        }
+        const result = await escalationService.claimByMetadata(input.key, input.value, claimUserId, input.durationMinutes);
+        if (!result) {
+            return { status: 409, error: 'Escalation not available for claim' };
+        }
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.claimed',
+            source: 'api',
+            workflowId: result.escalation.workflow_id || '',
+            workflowName: result.escalation.workflow_type || '',
+            taskQueue: result.escalation.task_queue || '',
+            escalationId: result.escalation.id,
+            status: 'claimed',
+            data: { assigned_to: claimUserId },
+        });
+        return { status: 200, data: result };
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
+/**
+ * Resolve an escalation by metadata key-value pair.
+ *
+ * Finds the pending escalation, auto-claims if unclaimed, then delegates
+ * to the standard resolve logic (supports all 5 resolution paths).
+ *
+ * @param input.key — metadata field name
+ * @param input.value — metadata field value
+ * @param input.resolverPayload — resolution data for the workflow
+ * @param input.assignee — optional external_id of the resolving user
+ * @returns result from the standard resolve endpoint
+ */
+async function resolveByMetadata(input, auth) {
+    try {
+        if (!input.key || !input.value) {
+            return { status: 400, error: 'key and value are required' };
+        }
+        if (!input.resolverPayload) {
+            return { status: 400, error: 'resolverPayload is required' };
+        }
+        const candidates = await escalationService.findByMetadata(input.key, input.value, 'pending', 1, 0);
+        if (candidates.escalations.length === 0) {
+            return { status: 404, error: 'No pending escalation found for this metadata' };
+        }
+        const escalation = candidates.escalations[0];
+        const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth);
+        if ('error' in resolved)
+            return resolved.error;
+        const resolveUserId = resolved.userId;
+        const isSuperAdmin = await userService.isSuperAdmin(auth.userId);
+        if (!isSuperAdmin) {
+            const userHasRole = await userService.hasRole(resolveUserId, escalation.role);
+            if (!userHasRole) {
+                return { status: 403, error: `User must have the "${escalation.role}" role` };
+            }
+        }
+        // Auto-claim if unclaimed or expired
+        const isClaimed = escalation.assigned_to &&
+            escalation.assigned_until &&
+            new Date(escalation.assigned_until) > new Date();
+        if (!isClaimed) {
+            await escalationService.claimEscalation(escalation.id, resolveUserId, 5);
+        }
+        // Delegate to the full resolve logic (handles all 5 resolution paths)
+        const { resolveEscalation } = await Promise.resolve().then(() => __importStar(require('./resolve')));
+        return resolveEscalation({ id: escalation.id, resolverPayload: input.resolverPayload }, auth);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}

package/build/api/index.d.ts

@@ -6,7 +6,8 @@ export * as users from './users';
 export * as roles from './roles';
 export * as auth from './auth';
 export * as mcp from './mcp';
-export * as mcpRuns from './mcp-runs';
+export * as pipelines from './pipelines';
+export * as mcpRuns from './pipelines';
 export * as insight from './insight';
 export * as settings from './settings';
 export * as exports from './exports';