@hotmeshio/long-tail 0.4.20 → 0.4.22

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

@@ -1,3 +1,4 @@
+import { type ProvisionIfAbsent } from './helpers';
 import type { LTApiResult, LTApiAuth } from '../../types/sdk';
 /**
  * Claim a pending escalation for the authenticated user.
@@ -14,6 +15,7 @@ import type { LTApiResult, LTApiAuth } from '../../types/sdk';
 export declare function claimEscalation(input: {
     id: string;
     durationMinutes?: number;
+    provisionIfAbsent?: ProvisionIfAbsent;
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * Release a claimed escalation back to the pool.

package/build/api/escalations/claim.js

@@ -52,26 +52,30 @@ const helpers_1 = require("./helpers");
  */
 async function claimEscalation(input, auth) {
     try {
-        const { id, durationMinutes } = input;
+        const { id, durationMinutes, provisionIfAbsent } = input;
         const escalation = await escalationService.getEscalation(id);
         if (!escalation) {
             return { status: 404, error: 'Escalation not found' };
         }
+        // Happy path: try claim assuming user has the role
         const hasGlobal = await (0, helpers_1.hasGlobalEscalationAccess)(auth.userId);
         if (!hasGlobal) {
             const userHasRole = await userService.hasRole(auth.userId, escalation.role);
             if (!userHasRole) {
-                return {
-                    status: 403,
-                    error: `You must have the "${escalation.role}" role to claim this escalation`,
-                };
+                // Unhappy path: provision role if flag present, then retry
+                const provisioned = await (0, helpers_1.ensureRoleMembership)(auth.userId, escalation.role, auth.userId, provisionIfAbsent);
+                if (!provisioned) {
+                    return {
+                        status: 403,
+                        error: `You must have the "${escalation.role}" role to claim this escalation`,
+                    };
+                }
             }
         }
         const result = await escalationService.claimEscalation(id, auth.userId, durationMinutes);
         if (!result) {
             return { status: 409, error: 'Escalation not available for claim' };
         }
-        // Event published by service layer (services/escalation/crud.ts)
         return { status: 200, data: result };
     }
     catch (err) {

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

@@ -8,13 +8,30 @@ export declare function checkBulkPermission(userId: string, ids: string[]): Prom
     status: 403;
     error: string;
 }>;
+/**
+ * Identity to provision when the assignee doesn't exist in lt_users
+ * or lacks the required role. Only honored for callers with global
+ * escalation access (superadmin, admin/admin).
+ */
+export interface ProvisionIfAbsent {
+    displayName?: string;
+    email?: string;
+    roles?: Array<{
+        role: string;
+        type?: string;
+    }>;
+}
 /**
  * Resolve an optional assignee external_id to an internal userId.
  * When omitted, returns the caller's userId from auth.
+ *
+ * When `provisionIfAbsent` is provided and the caller has global access,
+ * the user is JIT-provisioned if absent and roles are ensured. This avoids
+ * pre-flight queries — the happy path (user exists) is one lookup.
  */
 export declare function resolveAssignee(assignee: string | undefined, auth: {
     userId: string;
-}): Promise<{
+}, provisionIfAbsent?: ProvisionIfAbsent): Promise<{
     userId: string;
 } | {
     error: {
@@ -22,4 +39,10 @@ export declare function resolveAssignee(assignee: string | undefined, auth: {
         error: string;
     };
 }>;
+/**
+ * Ensure a user has the required role for an escalation.
+ * Called after claim when the atomic SQL returns null due to role mismatch.
+ * Only adds the role if `provisionIfAbsent` declares it and caller has authority.
+ */
+export declare function ensureRoleMembership(userId: string, requiredRole: string, callerUserId: string, provisionIfAbsent?: ProvisionIfAbsent): Promise<boolean>;
 export declare function publishBulkClaimEvents(ids: string[], assignedTo: string): void;

package/build/api/escalations/helpers.js

@@ -38,6 +38,7 @@ exports.getVisibleRoles = getVisibleRoles;
 exports.validateIds = validateIds;
 exports.checkBulkPermission = checkBulkPermission;
 exports.resolveAssignee = resolveAssignee;
+exports.ensureRoleMembership = ensureRoleMembership;
 exports.publishBulkClaimEvents = publishBulkClaimEvents;
 const escalationService = __importStar(require("../../services/escalation"));
 const userService = __importStar(require("../../services/user"));
@@ -71,15 +72,59 @@ async function checkBulkPermission(userId, ids) {
 /**
  * Resolve an optional assignee external_id to an internal userId.
  * When omitted, returns the caller's userId from auth.
+ *
+ * When `provisionIfAbsent` is provided and the caller has global access,
+ * the user is JIT-provisioned if absent and roles are ensured. This avoids
+ * pre-flight queries — the happy path (user exists) is one lookup.
  */
-async function resolveAssignee(assignee, auth) {
+async function resolveAssignee(assignee, auth, provisionIfAbsent) {
     if (!assignee)
         return { userId: auth.userId };
+    // Happy path: user exists
     const user = await userService.getUserByExternalId(assignee);
-    if (!user) {
+    if (user)
+        return { userId: user.id };
+    // User not found — provision if caller has authority and flag is set
+    if (!provisionIfAbsent) {
         return { error: { status: 404, error: `User not found for external_id: ${assignee}` } };
     }
-    return { userId: user.id };
+    const hasAuthority = await userService.hasGlobalEscalationAccess(auth.userId);
+    if (!hasAuthority) {
+        return { error: { status: 403, error: 'Only superadmin or admin can provision users on claim' } };
+    }
+    // Provision the user
+    const created = await userService.createUser({
+        external_id: assignee,
+        display_name: provisionIfAbsent.displayName || assignee,
+        email: provisionIfAbsent.email,
+        roles: (provisionIfAbsent.roles || []).map((r) => ({
+            role: r.role,
+            type: (r.type || 'member'),
+        })),
+    });
+    return { userId: created.id };
+}
+/**
+ * Ensure a user has the required role for an escalation.
+ * Called after claim when the atomic SQL returns null due to role mismatch.
+ * Only adds the role if `provisionIfAbsent` declares it and caller has authority.
+ */
+async function ensureRoleMembership(userId, requiredRole, callerUserId, provisionIfAbsent) {
+    if (!provisionIfAbsent)
+        return false;
+    const hasAuthority = await userService.hasGlobalEscalationAccess(callerUserId);
+    if (!hasAuthority)
+        return false;
+    // Check if the provision declares this role
+    const declaredRole = provisionIfAbsent.roles?.find((r) => r.role === requiredRole);
+    if (!declaredRole)
+        return false;
+    // Add the role — idempotent (ON CONFLICT DO NOTHING)
+    try {
+        await userService.addUserRole(userId, requiredRole, (declaredRole.type || 'member'));
+    }
+    catch { /* already has it */ }
+    return true;
 }
 function publishBulkClaimEvents(ids, assignedTo) {
     for (const id of ids) {

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

@@ -1,3 +1,4 @@
+import { type ProvisionIfAbsent } from './helpers';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
 /**
  * Find escalations by a metadata key-value pair.
@@ -25,12 +26,19 @@ export declare function claimByMetadata(input: {
     durationMinutes?: number;
     assignee?: string;
     metadata?: Record<string, any>;
+    provisionIfAbsent?: ProvisionIfAbsent;
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * Resolve an escalation by metadata key-value pair.
  *
- * Single atomic CTE: find + claim + resolve in one query.
- * RBAC is enforced in the SQL WHERE clause.
+ * Single atomic query with signal guard:
+ * - No signal_id → claim + resolve atomically in SQL. One query. Done.
+ * - signal_id present → SQL returns the signal info without resolving.
+ *   Caller signals the workflow; conditionLT resolves durably inside
+ *   the workflow via ltResolveEscalation.
+ *
+ * Never does SELECT-then-UPDATE. The SQL CTE handles find + RBAC +
+ * claim + resolve (or signal detection) in one round-trip.
  */
 export declare function resolveByMetadata(input: {
     key: string;

package/build/api/escalations/metadata.js

@@ -76,7 +76,7 @@ async function claimByMetadata(input, auth) {
         if (!input.key || !input.value) {
             return { status: 400, error: 'key and value are required' };
         }
-        const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth);
+        const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth, input.provisionIfAbsent);
         if ('error' in resolved)
             return resolved.error;
         const claimUserId = resolved.userId;
@@ -99,8 +99,14 @@ async function claimByMetadata(input, auth) {
 /**
  * Resolve an escalation by metadata key-value pair.
  *
- * Single atomic CTE: find + claim + resolve in one query.
- * RBAC is enforced in the SQL WHERE clause.
+ * Single atomic query with signal guard:
+ * - No signal_id → claim + resolve atomically in SQL. One query. Done.
+ * - signal_id present → SQL returns the signal info without resolving.
+ *   Caller signals the workflow; conditionLT resolves durably inside
+ *   the workflow via ltResolveEscalation.
+ *
+ * Never does SELECT-then-UPDATE. The SQL CTE handles find + RBAC +
+ * claim + resolve (or signal detection) in one round-trip.
  */
 async function resolveByMetadata(input, auth) {
     try {
@@ -115,11 +121,25 @@ async function resolveByMetadata(input, auth) {
             return resolved.error;
         const resolveUserId = resolved.userId;
         const allowedRoles = await resolveAllowedRoles(auth.userId);
-        const escalation = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, allowedRoles);
-        if (!escalation) {
+        const result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, allowedRoles);
+        if (result.outcome === 'not_found') {
             return { status: 404, error: 'No pending escalation found for this metadata, or insufficient role permissions' };
         }
-        return { status: 200, data: { escalation } };
+        if (result.outcome === 'resolved') {
+            return { status: 200, data: { escalation: result.escalation } };
+        }
+        // Signal-backed escalation — signal the workflow, conditionLT resolves durably
+        const { createClient } = await Promise.resolve().then(() => __importStar(require('../../workers')));
+        const client = createClient();
+        const handle = await client.workflow.getHandle(result.taskQueue, result.workflowType, result.workflowId);
+        await handle.signal(result.signalId, {
+            ...input.resolverPayload,
+            $escalation_id: result.escalationId,
+        });
+        return {
+            status: 200,
+            data: { signaled: true, escalationId: result.escalationId, workflowId: result.workflowId },
+        };
     }
     catch (err) {
         return { status: 500, error: err.message };
@@ -134,5 +154,8 @@ async function resolveAllowedRoles(userId) {
     if (await userService.hasGlobalEscalationAccess(userId))
         return null;
     const userRoles = await userService.getUserRoles(userId);
+    // Return the user's roles (may be empty → SQL filters out all rows).
+    // System/service accounts that need unrestricted access should be
+    // seeded with the superadmin role via start({ seed: { admin } }).
     return userRoles.map(r => r.role);
 }

package/build/modules/auth.d.ts

@@ -55,7 +55,7 @@ export declare const requireAdmin: RequestHandler;
 /**
  * Middleware that requires builder access. Must be placed AFTER requireAuth.
  *
- * Builders are superadmin, admin, or users with the 'engineer' role.
+ * Builders are superadmin or users with the 'engineer' role.
  * This is the backend equivalent of the dashboard's `isBuilder` check.
  */
 export declare const requireBuilder: RequestHandler;

package/build/modules/auth.js

@@ -225,7 +225,7 @@ exports.requireAdmin = requireAdmin;
 /**
  * Middleware that requires builder access. Must be placed AFTER requireAuth.
  *
- * Builders are superadmin, admin, or users with the 'engineer' role.
+ * Builders are superadmin or users with the 'engineer' role.
  * This is the backend equivalent of the dashboard's `isBuilder` check.
  */
 const requireBuilder = async (req, res, next) => {
@@ -234,8 +234,8 @@ const requireBuilder = async (req, res, next) => {
             res.status(403).json({ error: 'Forbidden' });
             return;
         }
-        // Fast path: trust the JWT role claim for admin/superadmin
-        if (req.auth.role === 'admin' || req.auth.role === 'superadmin') {
+        // Fast path: trust the JWT role claim for superadmin
+        if (req.auth.role === 'superadmin') {
             next();
             return;
         }

package/build/routes/escalations/metadata.js

@@ -58,7 +58,7 @@ function registerMetadataRoutes(router) {
     /**
      * POST /api/escalations/claim-by-metadata
      * Find and claim an escalation by metadata key-value pair.
-     * Body: { key, value, durationMinutes?, assignee?, metadata? }
+     * Body: { key, value, durationMinutes?, assignee?, metadata?, provisionIfAbsent? }
      */
     router.post('/claim-by-metadata', async (req, res) => {
         const result = await api.claimByMetadata({
@@ -67,6 +67,7 @@ function registerMetadataRoutes(router) {
             durationMinutes: req.body?.durationMinutes,
             assignee: req.body?.assignee,
             metadata: req.body?.metadata,
+            provisionIfAbsent: req.body?.provisionIfAbsent,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });

package/build/routes/escalations/single.js

@@ -71,7 +71,7 @@ function registerSingleRoutes(router) {
      * Body: { durationMinutes?: number }
      */
     router.post('/:id/claim', async (req, res) => {
-        const result = await api.claimEscalation({ id: req.params.id, durationMinutes: req.body?.durationMinutes }, req.auth);
+        const result = await api.claimEscalation({ id: req.params.id, durationMinutes: req.body?.durationMinutes, provisionIfAbsent: req.body?.provisionIfAbsent }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
     /**

package/build/sdk/index.d.ts

@@ -121,6 +121,7 @@ export declare function createClient(options?: LTClientOptions): {
         claim: (input: {
             id: string;
             durationMinutes?: number;
+            provisionIfAbsent?: import("../api/escalations/helpers").ProvisionIfAbsent;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         release: (input: {
             id: string;
@@ -164,6 +165,7 @@ export declare function createClient(options?: LTClientOptions): {
             durationMinutes?: number;
             assignee?: string;
             metadata?: Record<string, any>;
+            provisionIfAbsent?: import("../api/escalations/helpers").ProvisionIfAbsent;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         resolveByMetadata: (input: {
             key: string;

package/build/services/auth/bot-api-key.js

@@ -43,26 +43,8 @@ exports.listBotApiKeys = listBotApiKeys;
 const crypto = __importStar(require("crypto"));
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
 const db_1 = require("../../lib/db");
+const sql_1 = require("./sql");
 const TOKEN_PREFIX = 'lt_bot_';
-const INSERT_KEY = `
-  INSERT INTO lt_bot_api_keys (name, user_id, key_hash, scopes, expires_at)
-  VALUES ($1, $2, $3, $4, $5) RETURNING id`;
-const GET_KEYS_BY_USER = `
-  SELECT id, name, user_id, key_hash, scopes
-  FROM lt_bot_api_keys
-  WHERE user_id = $1
-    AND (expires_at IS NULL OR expires_at > NOW())`;
-const GET_ALL_ACTIVE_KEYS = `
-  SELECT id, name, user_id, key_hash, scopes
-  FROM lt_bot_api_keys
-  WHERE (expires_at IS NULL OR expires_at > NOW())`;
-const UPDATE_LAST_USED = `
-  UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1`;
-const DELETE_KEY = `
-  DELETE FROM lt_bot_api_keys WHERE id = $1`;
-const LIST_BY_USER = `
-  SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at
-  FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at`;
 /**
  * Generate a new API key for a bot account.
  * Returns the raw key once — it is never stored in plaintext.
@@ -71,7 +53,7 @@ async function generateBotApiKey(name, userId, scopes = [], expiresAt) {
     const rawKey = `${TOKEN_PREFIX}${crypto.randomBytes(32).toString('hex')}`;
     const keyHash = await bcryptjs_1.default.hash(rawKey, 10);
     const pool = await (0, db_1.getPool)();
-    const { rows } = await pool.query(INSERT_KEY, [
+    const { rows } = await pool.query(sql_1.INSERT_BOT_KEY, [
         name, userId, keyHash, scopes, expiresAt || null,
     ]);
     return { id: rows[0].id, rawKey };
@@ -84,10 +66,10 @@ async function validateBotApiKey(rawKey) {
     if (!rawKey.startsWith(TOKEN_PREFIX))
         return null;
     const pool = await (0, db_1.getPool)();
-    const { rows } = await pool.query(GET_ALL_ACTIVE_KEYS);
+    const { rows } = await pool.query(sql_1.GET_ALL_ACTIVE_BOT_KEYS);
     for (const row of rows) {
         if (await bcryptjs_1.default.compare(rawKey, row.key_hash)) {
-            await pool.query(UPDATE_LAST_USED, [row.id]);
+            await pool.query(sql_1.UPDATE_BOT_KEY_LAST_USED, [row.id]);
             const { key_hash, ...record } = row;
             return record;
         }
@@ -99,7 +81,7 @@ async function validateBotApiKey(rawKey) {
  */
 async function revokeBotApiKey(id) {
     const pool = await (0, db_1.getPool)();
-    const result = await pool.query(DELETE_KEY, [id]);
+    const result = await pool.query(sql_1.DELETE_BOT_KEY, [id]);
     return (result.rowCount ?? 0) > 0;
 }
 /**
@@ -107,6 +89,6 @@ async function revokeBotApiKey(id) {
  */
 async function listBotApiKeys(userId) {
     const pool = await (0, db_1.getPool)();
-    const { rows } = await pool.query(LIST_BY_USER, [userId]);
+    const { rows } = await pool.query(sql_1.LIST_BOT_KEYS_BY_USER, [userId]);
     return rows;
 }

package/build/services/auth/service-token.js

@@ -43,20 +43,8 @@ exports.listServiceTokens = listServiceTokens;
 const crypto = __importStar(require("crypto"));
 const bcryptjs_1 = __importDefault(require("bcryptjs"));
 const db_1 = require("../../lib/db");
+const sql_1 = require("./sql");
 const TOKEN_PREFIX = 'lt_svc_';
-const INSERT_TOKEN = `
-  INSERT INTO lt_service_tokens (name, token_hash, server_id, scopes, expires_at)
-  VALUES ($1, $2, $3, $4, $5) RETURNING id`;
-const GET_ALL_TOKENS = `
-  SELECT id, name, token_hash FROM lt_service_tokens
-  WHERE (expires_at IS NULL OR expires_at > NOW())`;
-const UPDATE_LAST_USED = `
-  UPDATE lt_service_tokens SET last_used_at = NOW() WHERE id = $1`;
-const DELETE_TOKEN = `
-  DELETE FROM lt_service_tokens WHERE id = $1`;
-const LIST_BY_SERVER = `
-  SELECT id, name, server_id, scopes, expires_at, last_used_at, created_at, updated_at
-  FROM lt_service_tokens WHERE server_id = $1 ORDER BY created_at`;
 /**
  * Generate a new service token for an external MCP server.
  * Returns the raw token once — it is never stored in plaintext.
@@ -65,7 +53,7 @@ async function generateServiceToken(name, serverId, scopes, expiresAt) {
     const rawToken = `${TOKEN_PREFIX}${crypto.randomBytes(32).toString('hex')}`;
     const tokenHash = await bcryptjs_1.default.hash(rawToken, 10);
     const pool = await (0, db_1.getPool)();
-    const { rows } = await pool.query(INSERT_TOKEN, [
+    const { rows } = await pool.query(sql_1.INSERT_SERVICE_TOKEN, [
         name, tokenHash, serverId, scopes, expiresAt || null,
     ]);
     return { id: rows[0].id, rawToken };
@@ -77,10 +65,10 @@ async function validateServiceToken(rawToken) {
     if (!rawToken.startsWith(TOKEN_PREFIX))
         return null;
     const pool = await (0, db_1.getPool)();
-    const { rows } = await pool.query(GET_ALL_TOKENS);
+    const { rows } = await pool.query(sql_1.GET_ALL_ACTIVE_SERVICE_TOKENS);
     for (const row of rows) {
         if (await bcryptjs_1.default.compare(rawToken, row.token_hash)) {
-            await pool.query(UPDATE_LAST_USED, [row.id]);
+            await pool.query(sql_1.UPDATE_SERVICE_TOKEN_LAST_USED, [row.id]);
             const { token_hash, ...record } = row;
             return record;
         }
@@ -92,7 +80,7 @@ async function validateServiceToken(rawToken) {
  */
 async function revokeServiceToken(id) {
     const pool = await (0, db_1.getPool)();
-    const result = await pool.query(DELETE_TOKEN, [id]);
+    const result = await pool.query(sql_1.DELETE_SERVICE_TOKEN, [id]);
     return (result.rowCount ?? 0) > 0;
 }
 /**
@@ -100,6 +88,6 @@ async function revokeServiceToken(id) {
  */
 async function listServiceTokens(serverId) {
     const pool = await (0, db_1.getPool)();
-    const { rows } = await pool.query(LIST_BY_SERVER, [serverId]);
+    const { rows } = await pool.query(sql_1.LIST_SERVICE_TOKENS_BY_SERVER, [serverId]);
     return rows;
 }

package/build/services/auth/sql.d.ts

@@ -0,0 +1,11 @@
+export declare const INSERT_BOT_KEY = "\n  INSERT INTO lt_bot_api_keys (name, user_id, key_hash, scopes, expires_at)\n  VALUES ($1, $2, $3, $4, $5) RETURNING id";
+export declare const GET_BOT_KEYS_BY_USER = "\n  SELECT id, name, user_id, key_hash, scopes\n  FROM lt_bot_api_keys\n  WHERE user_id = $1\n    AND (expires_at IS NULL OR expires_at > NOW())";
+export declare const GET_ALL_ACTIVE_BOT_KEYS = "\n  SELECT id, name, user_id, key_hash, scopes\n  FROM lt_bot_api_keys\n  WHERE (expires_at IS NULL OR expires_at > NOW())";
+export declare const UPDATE_BOT_KEY_LAST_USED = "\n  UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1";
+export declare const DELETE_BOT_KEY = "\n  DELETE FROM lt_bot_api_keys WHERE id = $1";
+export declare const LIST_BOT_KEYS_BY_USER = "\n  SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at\n  FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at";
+export declare const INSERT_SERVICE_TOKEN = "\n  INSERT INTO lt_service_tokens (name, token_hash, server_id, scopes, expires_at)\n  VALUES ($1, $2, $3, $4, $5) RETURNING id";
+export declare const GET_ALL_ACTIVE_SERVICE_TOKENS = "\n  SELECT id, name, token_hash FROM lt_service_tokens\n  WHERE (expires_at IS NULL OR expires_at > NOW())";
+export declare const UPDATE_SERVICE_TOKEN_LAST_USED = "\n  UPDATE lt_service_tokens SET last_used_at = NOW() WHERE id = $1";
+export declare const DELETE_SERVICE_TOKEN = "\n  DELETE FROM lt_service_tokens WHERE id = $1";
+export declare const LIST_SERVICE_TOKENS_BY_SERVER = "\n  SELECT id, name, server_id, scopes, expires_at, last_used_at, created_at, updated_at\n  FROM lt_service_tokens WHERE server_id = $1 ORDER BY created_at";

package/build/services/auth/sql.js

@@ -0,0 +1,37 @@
+"use strict";
+// ── Bot API key queries ─────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_SERVICE_TOKENS_BY_SERVER = exports.DELETE_SERVICE_TOKEN = exports.UPDATE_SERVICE_TOKEN_LAST_USED = exports.GET_ALL_ACTIVE_SERVICE_TOKENS = exports.INSERT_SERVICE_TOKEN = exports.LIST_BOT_KEYS_BY_USER = exports.DELETE_BOT_KEY = exports.UPDATE_BOT_KEY_LAST_USED = exports.GET_ALL_ACTIVE_BOT_KEYS = exports.GET_BOT_KEYS_BY_USER = exports.INSERT_BOT_KEY = void 0;
+exports.INSERT_BOT_KEY = `
+  INSERT INTO lt_bot_api_keys (name, user_id, key_hash, scopes, expires_at)
+  VALUES ($1, $2, $3, $4, $5) RETURNING id`;
+exports.GET_BOT_KEYS_BY_USER = `
+  SELECT id, name, user_id, key_hash, scopes
+  FROM lt_bot_api_keys
+  WHERE user_id = $1
+    AND (expires_at IS NULL OR expires_at > NOW())`;
+exports.GET_ALL_ACTIVE_BOT_KEYS = `
+  SELECT id, name, user_id, key_hash, scopes
+  FROM lt_bot_api_keys
+  WHERE (expires_at IS NULL OR expires_at > NOW())`;
+exports.UPDATE_BOT_KEY_LAST_USED = `
+  UPDATE lt_bot_api_keys SET last_used_at = NOW() WHERE id = $1`;
+exports.DELETE_BOT_KEY = `
+  DELETE FROM lt_bot_api_keys WHERE id = $1`;
+exports.LIST_BOT_KEYS_BY_USER = `
+  SELECT id, name, user_id, scopes, expires_at, last_used_at, created_at, updated_at
+  FROM lt_bot_api_keys WHERE user_id = $1 ORDER BY created_at`;
+// ── Service token queries ───────────────────────────────────────────────────
+exports.INSERT_SERVICE_TOKEN = `
+  INSERT INTO lt_service_tokens (name, token_hash, server_id, scopes, expires_at)
+  VALUES ($1, $2, $3, $4, $5) RETURNING id`;
+exports.GET_ALL_ACTIVE_SERVICE_TOKENS = `
+  SELECT id, name, token_hash FROM lt_service_tokens
+  WHERE (expires_at IS NULL OR expires_at > NOW())`;
+exports.UPDATE_SERVICE_TOKEN_LAST_USED = `
+  UPDATE lt_service_tokens SET last_used_at = NOW() WHERE id = $1`;
+exports.DELETE_SERVICE_TOKEN = `
+  DELETE FROM lt_service_tokens WHERE id = $1`;
+exports.LIST_SERVICE_TOKENS_BY_SERVER = `
+  SELECT id, name, server_id, scopes, expires_at, last_used_at, created_at, updated_at
+  FROM lt_service_tokens WHERE server_id = $1 ORDER BY created_at`;

package/build/services/escalation/crud.d.ts

@@ -61,8 +61,24 @@ export declare function findByMetadata(key: string, value: string, status?: stri
 export declare function claimByMetadata(key: string, value: string, userId: string, durationMinutes?: number, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<(ClaimResult & {
     candidatesExist: number;
 }) | null>;
+export interface ResolveByMetadataResult {
+    /** 'resolved' = done atomically. 'signal_required' = signal_id present, caller must signal. */
+    outcome: 'resolved' | 'signal_required' | 'not_found';
+    /** The resolved escalation (when outcome = 'resolved') */
+    escalation?: LTEscalationRecord;
+    /** Signal info (when outcome = 'signal_required') */
+    signalId?: string;
+    escalationId?: string;
+    workflowId?: string;
+    workflowType?: string;
+    taskQueue?: string;
+}
 /**
- * Atomic resolve by metadata: find + claim + resolve in one CTE.
- * RBAC is enforced in the SQL WHERE clause via allowedRoles.
+ * Atomic resolve by metadata with signal guard.
+ *
+ * Single query, two outcomes:
+ * 1. No signal_id → claim + resolve atomically. Returns { outcome: 'resolved', escalation }.
+ * 2. signal_id present → resolve skipped. Returns { outcome: 'signal_required', signalId, escalationId, ... }
+ *    so the caller can signal the workflow. conditionLT handles the rest.
  */
-export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<LTEscalationRecord | null>;
+export declare function resolveByMetadataAtomic(key: string, value: string, userId: string, resolverPayload: Record<string, any>, metadata?: Record<string, any>, allowedRoles?: string[] | null): Promise<ResolveByMetadataResult>;

package/build/services/escalation/crud.js

@@ -249,8 +249,12 @@ async function claimByMetadata(key, value, userId, durationMinutes = 30, metadat
     };
 }
 /**
- * Atomic resolve by metadata: find + claim + resolve in one CTE.
- * RBAC is enforced in the SQL WHERE clause via allowedRoles.
+ * Atomic resolve by metadata with signal guard.
+ *
+ * Single query, two outcomes:
+ * 1. No signal_id → claim + resolve atomically. Returns { outcome: 'resolved', escalation }.
+ * 2. signal_id present → resolve skipped. Returns { outcome: 'signal_required', signalId, escalationId, ... }
+ *    so the caller can signal the workflow. conditionLT handles the rest.
  */
 async function resolveByMetadataAtomic(key, value, userId, resolverPayload, metadata, allowedRoles) {
     const pool = (0, db_1.getPool)();
@@ -260,17 +264,30 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
     const roles = allowedRoles ?? null;
     const { rows } = await pool.query(sql_1.RESOLVE_BY_METADATA_ATOMIC, [filter, userId, payloadJson, metaPatch, roles]);
     if (rows.length === 0)
-        return null;
-    const escalation = rows[0];
-    (0, publish_1.publishEscalationEvent)({
-        type: 'escalation.resolved',
-        source: 'service',
-        workflowId: escalation.workflow_id || '',
-        workflowName: escalation.workflow_type || '',
-        taskQueue: escalation.task_queue || '',
-        escalationId: escalation.id,
-        status: 'resolved',
-        data: { resolved_by: userId },
-    });
-    return escalation;
+        return { outcome: 'not_found' };
+    const row = rows[0];
+    if (row.outcome === 'resolved') {
+        const { target_id, signal_id, target_workflow_id, target_workflow_type, target_task_queue, outcome, ...rest } = row;
+        const escalation = rest;
+        (0, publish_1.publishEscalationEvent)({
+            type: 'escalation.resolved',
+            source: 'service',
+            workflowId: escalation.workflow_id || '',
+            workflowName: escalation.workflow_type || '',
+            taskQueue: escalation.task_queue || '',
+            escalationId: escalation.id,
+            status: 'resolved',
+            data: { resolved_by: userId },
+        });
+        return { outcome: 'resolved', escalation };
+    }
+    // Signal-backed escalation — return the signal info for the caller
+    return {
+        outcome: 'signal_required',
+        signalId: row.signal_id,
+        escalationId: row.target_id,
+        workflowId: row.target_workflow_id,
+        workflowType: row.target_workflow_type,
+        taskQueue: row.target_task_queue,
+    };
 }

package/build/services/escalation/sql.d.ts

@@ -28,8 +28,15 @@ export declare const FIND_BY_METADATA = "SELECT *, COUNT(*) OVER() AS _total\nFR
  */
 export declare const CLAIM_BY_METADATA_GUARDED = "WITH target AS (\n  SELECT id, assigned_to\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND (assigned_to IS NULL OR assigned_until <= NOW() OR assigned_to = $2)\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nupdated AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '1 minute' * $3,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target t\n  WHERE e.id = t.id\n  RETURNING e.*, t.assigned_to AS prev_assigned_to\n)\nSELECT *,\n  (SELECT COUNT(*) FROM lt_escalations WHERE metadata @> $1::jsonb AND status = 'pending') AS candidates_exist\nFROM updated";
 /**
- * Atomic resolve by metadata: find + claim + resolve in one CTE.
+ * Atomic resolve by metadata with signal guard.
+ *
+ * Single query, two outcomes:
+ * 1. No signal_id → claim + resolve atomically. `resolved` is populated.
+ * 2. signal_id present → resolve CTE skips (guard in WHERE). `resolved` is null,
+ *    but `target_id`, `signal_id`, `workflow_id`, `task_queue`, `workflow_type`
+ *    are returned so the caller can signal the workflow directly.
+ *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
-export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS (\n  SELECT id\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE SKIP LOCKED\n),\nclaimed AS (\n  UPDATE lt_escalations e\n  SET assigned_to = $2,\n      claimed_at = NOW(),\n      assigned_until = NOW() + INTERVAL '5 minutes',\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END\n  FROM target\n  WHERE e.id = target.id\n  RETURNING e.*\n)\nUPDATE lt_escalations e\nSET status = 'resolved',\n    resolved_at = NOW(),\n    resolver_payload = $3,\n    updated_at = NOW()\nFROM claimed\nWHERE e.id = claimed.id\nRETURNING e.*";
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS (\n  SELECT *\n  FROM lt_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE lt_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END\n  FROM target\n  WHERE e.id = target.id\n    AND (target.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE lt_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";