@hotmeshio/long-tail 0.1.0

package/build/services/iam/ephemeral.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatEphemeralToken = formatEphemeralToken;
+exports.isEphemeralToken = isEphemeralToken;
+exports.parseEphemeralToken = parseEphemeralToken;
+exports.exchangeEphemeralToken = exchangeEphemeralToken;
+exports.exchangeTokensInArgs = exchangeTokensInArgs;
+exports.storeEphemeral = storeEphemeral;
+exports.exchangeEphemeral = exchangeEphemeral;
+exports.revokeEphemeral = revokeEphemeral;
+exports.cleanupExpired = cleanupExpired;
+const db_1 = require("../db");
+const crypto_1 = require("../oauth/crypto");
+const logger_1 = require("../logger");
+// ── Token format ────────────────────────────────────────────────────────────
+// Opaque string: eph:v1:<label>:<uuid>
+// The LLM passes these through as-is. Exchange happens inside activity bodies.
+const EPH_PREFIX = 'eph:v1:';
+const EPH_REGEX = /^eph:v1:([a-z_][a-z0-9_]*):([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+function formatEphemeralToken(uuid, label) {
+    return `${EPH_PREFIX}${label}:${uuid}`;
+}
+function isEphemeralToken(value) {
+    return typeof value === 'string' && value.startsWith(EPH_PREFIX);
+}
+function parseEphemeralToken(value) {
+    const match = value.match(EPH_REGEX);
+    if (!match)
+        return null;
+    return { label: match[1], uuid: match[2] };
+}
+/**
+ * Parse a token string and exchange the UUID for the decrypted value.
+ * Returns null if the token format is invalid, expired, or uses exhausted.
+ */
+async function exchangeEphemeralToken(tokenString) {
+    const parsed = parseEphemeralToken(tokenString);
+    if (!parsed)
+        return null;
+    return exchangeEphemeral(parsed.uuid);
+}
+/**
+ * Deep-traverse a JSON value, replacing any string matching the eph:v1: format
+ * with the exchanged plaintext. Non-matching values pass through unchanged.
+ */
+async function exchangeTokensInArgs(obj) {
+    if (typeof obj === 'string') {
+        if (!isEphemeralToken(obj))
+            return obj;
+        const plaintext = await exchangeEphemeralToken(obj);
+        if (plaintext !== null)
+            return plaintext;
+        logger_1.loggerRegistry.warn(`[ephemeral] token exchange failed: ${obj.slice(0, 40)}...`);
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return Promise.all(obj.map(exchangeTokensInArgs));
+    }
+    if (obj && typeof obj === 'object') {
+        const result = {};
+        for (const [k, v] of Object.entries(obj)) {
+            result[k] = await exchangeTokensInArgs(v);
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Store a sensitive value. Returns the raw token UUID.
+ * The value is encrypted at rest using AES-256-GCM.
+ *
+ * - maxUses: 0 (default) = unlimited exchanges until expired/revoked
+ * - ttlSeconds: null (default) = no time-based expiry
+ * - Both can be combined: e.g., maxUses=10, ttlSeconds=900
+ */
+async function storeEphemeral(value, opts = {}) {
+    const pool = (0, db_1.getPool)();
+    const encrypted = (0, crypto_1.encrypt)(value);
+    const maxUses = opts.maxUses ?? 0;
+    const expiresAt = opts.ttlSeconds
+        ? `NOW() + ${opts.ttlSeconds} * INTERVAL '1 second'`
+        : 'NULL';
+    const { rows } = await pool.query(`INSERT INTO lt_ephemeral_credentials (value, label, max_uses, expires_at)
+     VALUES ($1, $2, $3, ${expiresAt})
+     RETURNING token`, [Buffer.from(encrypted, 'base64'), opts.label || null, maxUses]);
+    return rows[0].token;
+}
+/**
+ * Exchange a raw UUID token for the decrypted value.
+ *
+ * - If max_uses > 0: increments use_count, returns null when exhausted
+ * - If max_uses = 0: unlimited (never blocked by count)
+ * - If expires_at is set: returns null after expiry
+ * - Row is deleted when use_count reaches max_uses (if max_uses > 0)
+ */
+async function exchangeEphemeral(token) {
+    const pool = (0, db_1.getPool)();
+    // Atomic increment + check in one query.
+    // Returns the row if the exchange is valid, nothing if expired/exhausted.
+    const { rows } = await pool.query(`UPDATE lt_ephemeral_credentials
+     SET use_count = use_count + 1
+     WHERE token = $1
+       AND (expires_at IS NULL OR expires_at > NOW())
+       AND (max_uses = 0 OR use_count < max_uses)
+     RETURNING value, use_count, max_uses`, [token]);
+    if (rows.length === 0)
+        return null;
+    const { value: buf, use_count, max_uses } = rows[0];
+    // Auto-delete when max_uses is reached (if bounded)
+    if (max_uses > 0 && use_count >= max_uses) {
+        await pool.query(`DELETE FROM lt_ephemeral_credentials WHERE token = $1`, [token]);
+    }
+    return (0, crypto_1.decrypt)(buf.toString('base64'));
+}
+/**
+ * Explicitly revoke a token before expiry/exhaustion.
+ */
+async function revokeEphemeral(token) {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(`DELETE FROM lt_ephemeral_credentials WHERE token = $1`, [token]);
+    return (rowCount ?? 0) > 0;
+}
+/**
+ * Clean up expired tokens. Returns the number of rows deleted.
+ */
+async function cleanupExpired() {
+    const pool = (0, db_1.getPool)();
+    const { rowCount } = await pool.query(`DELETE FROM lt_ephemeral_credentials
+     WHERE expires_at IS NOT NULL AND expires_at < NOW()`);
+    return rowCount ?? 0;
+}

package/build/services/iam/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Universal IAM service for Long Tail.
+ *
+ * Provides identity context propagation, resolution, and credential lookup
+ * that works identically across all invocation paths:
+ * - MCP server tools
+ * - Proxy activities in workflows
+ * - YAML workflow workers
+ * - Direct route handlers
+ */
+export { runWithToolContext, getToolContext } from './context';
+export { getActivityIdentity } from './activity';
+export type { ActivityIdentity } from './activity';
+export { resolveToolContext } from './resolve';
+export type { ToolContextSource } from './resolve';
+export { resolveCredential, MissingCredentialError } from './credentials';
+export type { ResolvedCredential } from './credentials';
+export { createBot, getBot, listBots, updateBot, deactivateBot, deleteBot, createBotKey, listBotKeys, revokeBotKey, addBotRole, removeBotRole, getBotRoles, ensureSystemBot, } from './bots';
+export type { CreateBotInput, BotAccountRecord, BotApiKeyRecord } from './bots';

package/build/services/iam/index.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureSystemBot = exports.getBotRoles = exports.removeBotRole = exports.addBotRole = exports.revokeBotKey = exports.listBotKeys = exports.createBotKey = exports.deleteBot = exports.deactivateBot = exports.updateBot = exports.listBots = exports.getBot = exports.createBot = exports.MissingCredentialError = exports.resolveCredential = exports.resolveToolContext = exports.getActivityIdentity = exports.getToolContext = exports.runWithToolContext = void 0;
+/**
+ * Universal IAM service for Long Tail.
+ *
+ * Provides identity context propagation, resolution, and credential lookup
+ * that works identically across all invocation paths:
+ * - MCP server tools
+ * - Proxy activities in workflows
+ * - YAML workflow workers
+ * - Direct route handlers
+ */
+var context_1 = require("./context");
+Object.defineProperty(exports, "runWithToolContext", { enumerable: true, get: function () { return context_1.runWithToolContext; } });
+Object.defineProperty(exports, "getToolContext", { enumerable: true, get: function () { return context_1.getToolContext; } });
+var activity_1 = require("./activity");
+Object.defineProperty(exports, "getActivityIdentity", { enumerable: true, get: function () { return activity_1.getActivityIdentity; } });
+var resolve_1 = require("./resolve");
+Object.defineProperty(exports, "resolveToolContext", { enumerable: true, get: function () { return resolve_1.resolveToolContext; } });
+var credentials_1 = require("./credentials");
+Object.defineProperty(exports, "resolveCredential", { enumerable: true, get: function () { return credentials_1.resolveCredential; } });
+Object.defineProperty(exports, "MissingCredentialError", { enumerable: true, get: function () { return credentials_1.MissingCredentialError; } });
+var bots_1 = require("./bots");
+Object.defineProperty(exports, "createBot", { enumerable: true, get: function () { return bots_1.createBot; } });
+Object.defineProperty(exports, "getBot", { enumerable: true, get: function () { return bots_1.getBot; } });
+Object.defineProperty(exports, "listBots", { enumerable: true, get: function () { return bots_1.listBots; } });
+Object.defineProperty(exports, "updateBot", { enumerable: true, get: function () { return bots_1.updateBot; } });
+Object.defineProperty(exports, "deactivateBot", { enumerable: true, get: function () { return bots_1.deactivateBot; } });
+Object.defineProperty(exports, "deleteBot", { enumerable: true, get: function () { return bots_1.deleteBot; } });
+Object.defineProperty(exports, "createBotKey", { enumerable: true, get: function () { return bots_1.createBotKey; } });
+Object.defineProperty(exports, "listBotKeys", { enumerable: true, get: function () { return bots_1.listBotKeys; } });
+Object.defineProperty(exports, "revokeBotKey", { enumerable: true, get: function () { return bots_1.revokeBotKey; } });
+Object.defineProperty(exports, "addBotRole", { enumerable: true, get: function () { return bots_1.addBotRole; } });
+Object.defineProperty(exports, "removeBotRole", { enumerable: true, get: function () { return bots_1.removeBotRole; } });
+Object.defineProperty(exports, "getBotRoles", { enumerable: true, get: function () { return bots_1.getBotRoles; } });
+Object.defineProperty(exports, "ensureSystemBot", { enumerable: true, get: function () { return bots_1.ensureSystemBot; } });

package/build/services/iam/principal.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolve an LTEnvelopePrincipal from external_id or UUID in a single query.
+ *
+ * Called at the front door (API routes, cron) — never inside workflows.
+ * Uses a LEFT JOIN to fetch user + roles in one round-trip.
+ *
+ * Accepts either:
+ * - external_id (e.g., 'superadmin', 'lt-system')
+ * - UUID id (e.g., '76d28d6c-...' — as stored in JWT userId)
+ */
+import type { LTEnvelopePrincipal } from '../../types/envelope';
+export declare function resolvePrincipal(identifier: string): Promise<LTEnvelopePrincipal | null>;

package/build/services/iam/principal.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Resolve an LTEnvelopePrincipal from external_id or UUID in a single query.
+ *
+ * Called at the front door (API routes, cron) — never inside workflows.
+ * Uses a LEFT JOIN to fetch user + roles in one round-trip.
+ *
+ * Accepts either:
+ * - external_id (e.g., 'superadmin', 'lt-system')
+ * - UUID id (e.g., '76d28d6c-...' — as stored in JWT userId)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePrincipal = resolvePrincipal;
+const db_1 = require("../db");
+/** UUID v4 pattern for distinguishing UUIDs from external_ids. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Fetch user + roles by external_id OR id in one query. */
+const GET_USER_WITH_ROLES_FLEXIBLE = `
+  SELECT u.id, u.external_id, u.display_name, u.status, u.metadata,
+         r.role, r.type AS role_type
+  FROM lt_users u
+  LEFT JOIN lt_user_roles r ON r.user_id = u.id
+  WHERE u.external_id = $1 OR u.id::text = $1
+  ORDER BY r.created_at`;
+const ROLE_TYPE_PRIORITY = { superadmin: 3, admin: 2, member: 1 };
+async function resolvePrincipal(identifier) {
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(GET_USER_WITH_ROLES_FLEXIBLE, [identifier]);
+    if (rows.length === 0)
+        return null;
+    const user = rows[0];
+    const roleNames = [];
+    let highestPriority = 0;
+    let highestType;
+    for (const row of rows) {
+        if (row.role) {
+            roleNames.push(row.role);
+            const priority = ROLE_TYPE_PRIORITY[row.role_type] ?? 0;
+            if (priority > highestPriority) {
+                highestPriority = priority;
+                highestType = row.role_type;
+            }
+        }
+    }
+    // Use external_id as the canonical identifier (stable, human-readable)
+    return {
+        id: user.external_id,
+        type: user.metadata?.account_type ?? 'user',
+        displayName: user.display_name ?? undefined,
+        roles: roleNames,
+        roleType: highestType,
+    };
+}

package/build/services/iam/resolve.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Resolves a ToolContext from whatever identity information is available.
+ *
+ * This is the single convergence point for all three invocation paths.
+ * Each path calls `resolveToolContext()` with whatever identity data
+ * it has, and gets back the same ToolContext shape.
+ */
+import type { LTEnvelope } from '../../types/envelope';
+import type { ToolContext } from '../../types/tool-context';
+import type { OrchestratorContext } from '../interceptor/types';
+/**
+ * Source data for resolving a ToolContext.
+ * Callers pass whichever fields they have; resolution picks the best available.
+ */
+export interface ToolContextSource {
+    /** Direct userId (e.g., from _auth injection or envelope). */
+    userId?: string;
+    /** Account type override (for known bot invocations). */
+    accountType?: 'user' | 'bot';
+    /** Existing delegation token to decode instead of minting new. */
+    delegationToken?: string;
+    /** Scopes for delegation token (defaults to ['mcp:tool:call']). */
+    scopes?: string[];
+    /** Envelope from workflow args. */
+    envelope?: LTEnvelope;
+    /** OrchestratorContext from AsyncLocalStorage. */
+    orchestratorContext?: OrchestratorContext;
+    /** _auth from MCP tool args. */
+    _auth?: {
+        userId?: string;
+        token?: string;
+    };
+    /** Trace IDs for audit lineage. */
+    traceId?: string;
+    spanId?: string;
+}
+/**
+ * Resolve identity from any available source, load roles, mint delegation token.
+ *
+ * Resolution priority for userId:
+ * 1. Explicit `_auth.userId` (MCP server tool path)
+ * 2. Explicit `userId` parameter
+ * 3. `envelope.lt.userId` (workflow/envelope path)
+ * 4. `orchestratorContext.userId` (proxy activity path)
+ *
+ * Returns null when no identity can be resolved (anonymous/system context).
+ */
+export declare function resolveToolContext(source: ToolContextSource): Promise<ToolContext | null>;

package/build/services/iam/resolve.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveToolContext = resolveToolContext;
+const delegation_1 = require("../auth/delegation");
+const user_1 = require("../user");
+const logger_1 = require("../logger");
+/** Role type priority for determining highest role type. */
+const ROLE_TYPE_PRIORITY = { superadmin: 3, admin: 2, member: 1 };
+/**
+ * Resolve identity from any available source, load roles, mint delegation token.
+ *
+ * Resolution priority for userId:
+ * 1. Explicit `_auth.userId` (MCP server tool path)
+ * 2. Explicit `userId` parameter
+ * 3. `envelope.lt.userId` (workflow/envelope path)
+ * 4. `orchestratorContext.userId` (proxy activity path)
+ *
+ * Returns null when no identity can be resolved (anonymous/system context).
+ */
+async function resolveToolContext(source) {
+    // Resolve userId from available sources
+    const userId = source._auth?.userId ||
+        source.userId ||
+        source.envelope?.lt?.userId ||
+        source.orchestratorContext?.userId;
+    if (!userId) {
+        return null;
+    }
+    // Build principal with roles from DB
+    const principal = await resolvePrincipal(userId, source.accountType);
+    // Use existing delegation token or mint a new one
+    const scopes = source.scopes ?? ['mcp:tool:call'];
+    const delegationToken = source._auth?.token ?? source.delegationToken ?? (0, delegation_1.createDelegationToken)(userId, scopes, 300, {
+        workflowId: source.orchestratorContext?.workflowId ?? source.envelope?.lt?.parentWorkflowId,
+    });
+    const credentials = {
+        delegationToken,
+        scopes,
+    };
+    // Build trace from envelope and orchestrator context
+    const trace = {
+        originId: source.envelope?.lt?.originId,
+        parentId: source.envelope?.lt?.parentId,
+        workflowId: source.orchestratorContext?.workflowId,
+        traceId: source.traceId,
+        spanId: source.spanId,
+    };
+    return { principal, credentials, trace };
+}
+/**
+ * Load a ToolPrincipal from the database.
+ * Lightweight: one query for user + one for roles.
+ */
+async function resolvePrincipal(userId, accountType) {
+    try {
+        const [user, roles] = await Promise.all([
+            (0, user_1.getUser)(userId),
+            (0, user_1.getUserRoles)(userId),
+        ]);
+        // Determine highest role type
+        let highestPriority = 0;
+        let highestType;
+        const roleNames = [];
+        for (const r of roles) {
+            roleNames.push(r.role);
+            const priority = ROLE_TYPE_PRIORITY[r.type] ?? 0;
+            if (priority > highestPriority) {
+                highestPriority = priority;
+                highestType = r.type;
+            }
+        }
+        return {
+            id: userId,
+            type: accountType ?? user?.metadata?.account_type ?? 'user',
+            displayName: user?.display_name ?? undefined,
+            roles: roleNames,
+            roleType: highestType,
+        };
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`Failed to load principal for userId=${userId}: ${err}`);
+        // Fallback: minimal principal with just the ID
+        return {
+            id: userId,
+            type: accountType ?? 'user',
+            roles: [],
+        };
+    }
+}

package/build/services/insight/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Insight service — business logic for MCP query invocation and
+ * workflow description generation.
+ */
+export interface McpQueryInput {
+    prompt: string;
+    tags?: string[];
+    wait?: boolean;
+    direct?: boolean;
+    userId?: string;
+}
+export interface McpQueryResult {
+    workflow_id: string;
+    status?: string;
+    prompt: string;
+    duration_ms?: number;
+    [key: string]: unknown;
+}
+export interface DescribeInput {
+    prompt: string;
+    result_title?: string;
+    result_summary?: string;
+}
+export interface DescribeResult {
+    tool_name?: string;
+    description: string;
+    tags: string[];
+}
+export declare function startMcpQuery(input: McpQueryInput): Promise<McpQueryResult>;
+export declare function describeWorkflow(input: DescribeInput): Promise<DescribeResult>;

package/build/services/insight/index.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Insight service — business logic for MCP query invocation and
+ * workflow description generation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startMcpQuery = startMcpQuery;
+exports.describeWorkflow = describeWorkflow;
+const pg_1 = require("pg");
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const config_1 = require("../../modules/config");
+const defaults_1 = require("../../modules/defaults");
+const llm_1 = require("../llm");
+const prompts_1 = require("./prompts");
+// ── MCP query invocation ─────────────────────────────────────────────────────
+async function startMcpQuery(input) {
+    const { prompt, tags, wait = true, direct = false, userId } = input;
+    const startTime = Date.now();
+    const connection = { class: pg_1.Client, options: config_1.postgres_options };
+    const client = new hotmesh_1.Durable.Client({ connection });
+    const wfName = direct ? 'mcpQuery' : 'mcpQueryRouter';
+    const entity = direct ? 'mcpQuery' : 'mcpQueryRouter';
+    const prefix = direct ? 'mcp-query-direct' : 'mcp-query';
+    const workflowId = `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const handle = await client.workflow.start({
+        args: [{
+                data: { prompt, tags },
+                metadata: { source: 'dashboard' },
+                lt: { userId },
+            }],
+        taskQueue: 'long-tail-system',
+        workflowName: wfName,
+        workflowId,
+        expire: defaults_1.JOB_EXPIRE_SECS,
+        entity,
+    });
+    if (wait === false) {
+        return { workflow_id: workflowId, status: 'started', prompt };
+    }
+    const result = await handle.result({ state: true });
+    const data = result?.data || result;
+    return {
+        ...data,
+        prompt,
+        workflow_id: workflowId,
+        duration_ms: Date.now() - startTime,
+    };
+}
+// ── Workflow description generation ──────────────────────────────────────────
+async function describeWorkflow(input) {
+    const { prompt, result_title, result_summary } = input;
+    if (!(0, llm_1.hasLLMApiKey)(defaults_1.LLM_MODEL_SECONDARY)) {
+        return { description: prompt, tags: [] };
+    }
+    const userContent = [
+        `Original query: "${prompt}"`,
+        result_title ? `Result: ${result_title}` : '',
+        result_summary ? `Summary: ${result_summary.slice(0, 500)}` : '',
+    ].filter(Boolean).join('\n');
+    const response = await (0, llm_1.callLLM)({
+        model: defaults_1.LLM_MODEL_SECONDARY,
+        max_tokens: 300,
+        messages: [
+            { role: 'system', content: prompts_1.DESCRIBE_WORKFLOW_SYSTEM_PROMPT },
+            { role: 'user', content: userContent },
+        ],
+    });
+    const raw = response.content || '{}';
+    const cleaned = raw.replace(/^```(?:json)?\s*/m, '').replace(/\s*```$/m, '').trim();
+    const parsed = JSON.parse(cleaned);
+    const toolName = (parsed.tool_name || '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 60);
+    return {
+        tool_name: toolName || undefined,
+        description: parsed.description || prompt,
+        tags: Array.isArray(parsed.tags) ? parsed.tags : [],
+    };
+}

package/build/services/insight/prompts.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Externalized LLM prompt constants for the insight service.
+ */
+export declare const DESCRIBE_WORKFLOW_SYSTEM_PROMPT = "You generate concise workflow descriptions, tool names, and discovery tags.\n\nGiven a user's original query and the execution result, produce:\n1. A short, descriptive tool name as a lowercase kebab-case slug (e.g. \"screenshot-all-nav-pages\", \"fetch-order-status\", \"translate-content\"). The name should describe what the workflow does, not be generic like \"query-complete\".\n2. A clear, reusable description of what this workflow does (not what the user asked, but what the workflow accomplishes as a reusable tool). Write it as if describing a tool in a catalog. 2-3 sentences max.\n3. Discovery tags \u2014 lowercase keywords that help find this workflow when similar future queries are made.\n\nReturn ONLY a JSON object:\n{ \"tool_name\": \"...\", \"description\": \"...\", \"tags\": [\"tag1\", \"tag2\", ...] }";

package/build/services/insight/prompts.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Externalized LLM prompt constants for the insight service.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESCRIBE_WORKFLOW_SYSTEM_PROMPT = void 0;
+exports.DESCRIBE_WORKFLOW_SYSTEM_PROMPT = `You generate concise workflow descriptions, tool names, and discovery tags.
+
+Given a user's original query and the execution result, produce:
+1. A short, descriptive tool name as a lowercase kebab-case slug (e.g. "screenshot-all-nav-pages", "fetch-order-status", "translate-content"). The name should describe what the workflow does, not be generic like "query-complete".
+2. A clear, reusable description of what this workflow does (not what the user asked, but what the workflow accomplishes as a reusable tool). Write it as if describing a tool in a catalog. 2-3 sentences max.
+3. Discovery tags — lowercase keywords that help find this workflow when similar future queries are made.
+
+Return ONLY a JSON object:
+{ "tool_name": "...", "description": "...", "tags": ["tag1", "tag2", ...] }`;

package/build/services/interceptor/activities/config.d.ts

@@ -0,0 +1,21 @@
+import type { LTResolvedConfig, LTProviderData } from '../../../types';
+/**
+ * Get the resolved workflow configuration for a given workflow name.
+ *
+ * Bridges the deterministic workflow sandbox to the config system.
+ * Activities run on the activity worker (outside the sandbox), so
+ * they use the {@link ltConfig} singleton which maintains a 5-minute
+ * TTL cache — most calls resolve from memory without hitting the DB.
+ */
+export declare function ltGetWorkflowConfig(workflowName: string): Promise<LTResolvedConfig | null>;
+/**
+ * Get provider data for a workflow's consumers by looking up
+ * completed sibling tasks that share the same origin_id.
+ *
+ * Uses the cached config to resolve the consumer list, then
+ * queries the DB for matching completed task data.
+ */
+export declare function ltGetProviderData(input: {
+    workflowName: string;
+    originId: string;
+}): Promise<LTProviderData>;

package/build/services/interceptor/activities/config.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ltGetWorkflowConfig = ltGetWorkflowConfig;
+exports.ltGetProviderData = ltGetProviderData;
+const ltconfig_1 = require("../../../modules/ltconfig");
+/**
+ * Get the resolved workflow configuration for a given workflow name.
+ *
+ * Bridges the deterministic workflow sandbox to the config system.
+ * Activities run on the activity worker (outside the sandbox), so
+ * they use the {@link ltConfig} singleton which maintains a 5-minute
+ * TTL cache — most calls resolve from memory without hitting the DB.
+ */
+async function ltGetWorkflowConfig(workflowName) {
+    return ltconfig_1.ltConfig.getResolvedConfig(workflowName);
+}
+/**
+ * Get provider data for a workflow's consumers by looking up
+ * completed sibling tasks that share the same origin_id.
+ *
+ * Uses the cached config to resolve the consumer list, then
+ * queries the DB for matching completed task data.
+ */
+async function ltGetProviderData(input) {
+    return ltconfig_1.ltConfig.getProviderData(input.workflowName, input.originId);
+}

package/build/services/interceptor/activities/escalation.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Resolve an escalation record. Called by the interceptor after
+ * detecting a re-run (resolver data present in the envelope).
+ * This makes resolution durable: if the server crashes after
+ * signaling but before DB update, the workflow replays and
+ * retries this activity.
+ */
+export declare function ltResolveEscalation(input: {
+    escalationId: string;
+    resolverPayload: Record<string, any>;
+}): Promise<void>;
+/**
+ * Claim an escalation to a specific user. Used for auto-assignment
+ * when the system creates an advisory escalation (e.g., rounds exhausted).
+ */
+export declare function ltClaimEscalation(input: {
+    escalationId: string;
+    userId: string;
+    durationMinutes: number;
+}): Promise<void>;
+/**
+ * Enrich an escalation record with signal routing metadata and workflow
+ * context so the resolution API can signal the paused workflow directly
+ * and the dashboard can display full context. Optionally auto-claims
+ * the escalation to the initiating user.
+ */
+export declare function ltEnrichEscalationRouting(input: {
+    escalationId: string;
+    signalRouting: {
+        taskQueue: string;
+        workflowType: string;
+        workflowId: string;
+        signalId: string;
+    };
+    taskId?: string;
+    claimForUserId?: string;
+}): Promise<void>;
+/**
+ * Create an escalation record when a workflow needs human intervention.
+ */
+export declare function ltCreateEscalation(input: {
+    type: string;
+    subtype: string;
+    description?: string;
+    priority?: number;
+    taskId?: string;
+    originId?: string;
+    parentId?: string;
+    role: string;
+    envelope: string;
+    metadata?: Record<string, any>;
+    escalationPayload?: string;
+    workflowId?: string;
+    taskQueue?: string;
+    workflowType?: string;
+    traceId?: string;
+    spanId?: string;
+}): Promise<string>;