@hotmeshio/long-tail 0.4.20 → 0.4.22

package/docs/api/http/escalations.md

@@ -730,6 +730,24 @@ Finds one available (pending + unassigned/expired) escalation matching the metad
 | `durationMinutes` | `number` | Claim duration (default 30) |
 | `assignee` | `string` | Claim as a Long Tail user (resolved via `getUserByExternalId`) |
 | `metadata` | `object` | Additional metadata to merge (new keys added, existing overwritten) |
+| `provisionIfAbsent` | `object` | JIT-provision the assignee if they don't exist (superadmin only) |
+
+**`provisionIfAbsent`** — when the `assignee` doesn't exist in `lt_users` or lacks the escalation's role, provision them inline:
+
+```json
+{
+  "key": "orderId",
+  "value": "order-123",
+  "assignee": "jane.doe",
+  "provisionIfAbsent": {
+    "displayName": "Jane Doe",
+    "email": "jane@example.com",
+    "roles": [{ "role": "station-operator", "type": "member" }]
+  }
+}
+```
+
+Only callers with global escalation access (superadmin, admin/admin) can use this flag. The user is created with the declared roles if absent. If the user exists but lacks a required role, the role is added. The happy path (user exists, has role) adds zero extra queries.
 
 **Response 200:**
 
@@ -748,7 +766,9 @@ Finds one available (pending + unassigned/expired) escalation matching the metad
 POST /api/escalations/resolve-by-metadata
 ```
 
-Finds the pending escalation, auto-claims if unclaimed, then resolves it. Supports all five resolution paths (signal, re-run, triage, etc.).
+Single atomic query finds the pending escalation by metadata, auto-claims if unclaimed, and resolves it. RBAC is enforced in the SQL WHERE clause.
+
+**Signal guard:** If the escalation has `metadata.signal_id` (created by `conditionLT`), the SQL does NOT resolve it directly. Instead, the endpoint signals the running workflow — `conditionLT` receives the signal and resolves the escalation durably inside the workflow. This preserves the same transactional integrity as the standard resolve-by-ID path.
 
 **Body:**
 
@@ -769,4 +789,20 @@ Finds the pending escalation, auto-claims if unclaimed, then resolves it. Suppor
 | `assignee` | `string` | Resolve as a Long Tail user (resolved via `getUserByExternalId`) |
 | `metadata` | `object` | Additional metadata to merge (new keys added, existing overwritten) |
 
-**Response 200:** Same as standard resolve endpoint.
+**Response 200 (non-signal):** Escalation resolved atomically.
+
+```json
+{
+  "escalation": { "id": "...", "status": "resolved", ... }
+}
+```
+
+**Response 200 (signal-backed):** Workflow signaled; `conditionLT` resolves the escalation durably.
+
+```json
+{
+  "signaled": true,
+  "escalationId": "...",
+  "workflowId": "..."
+}
+```

package/docs/api/sdk/escalations.md

@@ -542,14 +542,20 @@ const result = await lt.escalations.findByMetadata({
 
 ## claimByMetadata
 
-Find and claim an escalation by metadata key-value pair in one atomic call.
+Find and claim an escalation by metadata key-value pair in one atomic call. RBAC is enforced in the SQL WHERE clause.
 
 ```typescript
 const result = await lt.escalations.claimByMetadata({
   key: 'orderId',
   value: 'order-123',
   durationMinutes: 30,
+  assignee: 'jane.doe',
   metadata: { claimedBy: 'jimbo', station: 'scanning' },
+  provisionIfAbsent: {
+    displayName: 'Jane Doe',
+    email: 'jane@example.com',
+    roles: [{ role: 'station-operator', type: 'member' }],
+  },
 });
 ```
 
@@ -562,6 +568,9 @@ const result = await lt.escalations.claimByMetadata({
 | `durationMinutes` | `number` | No | Claim duration (default: 30) |
 | `assignee` | `string` | No | Claim as a Long Tail user (resolved via `getUserByExternalId`) |
 | `metadata` | `object` | No | Merge into escalation metadata (single atomic SQL call with the claim) |
+| `provisionIfAbsent` | `object` | No | JIT-provision the assignee if they don't exist or lack the required role (superadmin only) |
+
+`provisionIfAbsent` accepts `{ displayName?, email?, roles?: [{ role, type? }] }`. Only callers with global escalation access can use this flag. The happy path (user exists, has role) adds zero extra queries.
 
 **Returns:** `LTApiResult<{ escalation, isExtension }>` -- 404 if no match, 409 if already claimed.
 
@@ -571,15 +580,26 @@ const result = await lt.escalations.claimByMetadata({
 
 ## resolveByMetadata
 
-Find and resolve an escalation by metadata key-value pair. Auto-claims if unclaimed. Supports all resolution paths.
+Find and resolve an escalation by metadata key-value pair. Single atomic query with signal guard.
+
+If the escalation has `metadata.signal_id` (created by `conditionLT`), the endpoint signals the running workflow instead of resolving directly in the DB. `conditionLT` receives the signal and resolves the escalation durably inside the workflow. This preserves the same transactional integrity as the standard resolve-by-ID path.
 
 ```typescript
+// Non-signal escalation → resolved atomically
+const result = await lt.escalations.resolveByMetadata({
+  key: 'orderId',
+  value: 'order-123',
+  resolverPayload: { approved: true },
+});
+// result.data.escalation.status === 'resolved'
+
+// Signal-backed escalation → workflow signaled
 const result = await lt.escalations.resolveByMetadata({
   key: 'orderId',
   value: 'order-123',
-  resolverPayload: { approved: true, targetStatus: 'completed' },
-  metadata: { completedBy: 'jimbo' },
+  resolverPayload: { approved: true },
 });
+// result.data.signaled === true, result.data.workflowId === '...'
 ```
 
 **Parameters:**
@@ -592,6 +612,6 @@ const result = await lt.escalations.resolveByMetadata({
 | `assignee` | `string` | No | Resolve as a Long Tail user (resolved via `getUserByExternalId`) |
 | `metadata` | `object` | No | Merge into escalation metadata before resolving |
 
-**Returns:** Same as `resolve` -- 404 if no match.
+**Returns:** `LTApiResult<{ escalation }>` for non-signal, `LTApiResult<{ signaled, escalationId, workflowId }>` for signal-backed. 404 if no match.
 
 **Auth:** Required

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -70,7 +70,7 @@
     "@anthropic-ai/sdk": "^0.92.0",
     "@aws-sdk/client-s3": "^3.1017.0",
     "@aws-sdk/s3-request-presigner": "^3.1045.0",
-    "@hotmeshio/hotmesh": "^0.19.4",
+    "@hotmeshio/hotmesh": "^0.19.5",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@opentelemetry/exporter-trace-otlp-proto": "^0.215.0",
     "@opentelemetry/resources": "^2.5.1",