@hotmeshio/long-tail 0.5.3 → 0.5.5

package/README.md

@@ -1,6 +1,6 @@
 # Long Tail
 
-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.
+The world is not passive. Machines fail, humans intervene, and conditions change. Long Tail gives TypeScript workflows a durable way to adapt on the fly: call machines, wait on people, resume from Postgres.
 
 ```bash
 npm install @hotmeshio/long-tail
@@ -8,7 +8,7 @@ npm install @hotmeshio/long-tail
 
 ## How it works
 
-You write a workflow function. Each activity call checkpoints to Postgres — if the process crashes, it resumes from the last completed step.
+Author in TypeScript. Checkpoint to Postgres. Route work to machines or people with the same workflow model.
 
 ```typescript
 import { Durable } from '@hotmeshio/hotmesh';
@@ -18,23 +18,33 @@ import * as activities from './activities';
 const { analyzeContent } = Durable.workflow.proxyActivities<typeof activities>({ activities });
 
 export async function reviewContent(envelope: LTEnvelope) {
+  // A machine does the work — your code, an API, a model.
   const analysis = await analyzeContent(envelope.data.content);
 
   if (analysis.confidence >= 0.85) {
     return { type: 'return' as const, data: { approved: true, analysis } };
   }
 
-  // Low confidence — escalate to a human reviewer
-  return {
-    type: 'escalation' as const,
-    role: 'reviewer',
-    message: `Review needed (confidence: ${analysis.confidence})`,
-    data: { content: envelope.data.content, analysis },
-  };
+  // The work goes to a person: the workflow suspends and writes one escalation
+  // row — assigned to a role, claimable and resolvable from the dashboard, API, or MCP.
+  const { workflowId } = Durable.workflow.workflowInfo();
+  const decision = await Durable.workflow.condition<{ approved: boolean; notes?: string }>(
+    `review-${workflowId}`,
+    {
+      role: 'reviewer',
+      type: 'content-review',
+      priority: 2,
+      description: `Confidence ${analysis.confidence} — needs a human`,
+      metadata: { contentId: envelope.data.contentId },
+      envelope: { data: envelope.data, analysis },
+    },
+  );
+
+  return { type: 'return' as const, data: { approved: decision.approved, analysis } };
 }
 ```
 
-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.
+Two surfaces, one model. A `proxyActivity` targets a machine: call it, get a result. `condition()` targets the external world — a reviewer, an operator, a factory cell. It suspends the workflow and writes a single escalation row carrying everything needed to route the work: the `role` that should act, its `type` and `priority`, and any `metadata` to display or filter on. People work that row through an RBAC-scoped surface — find it, claim it, resolve it — from the dashboard, the API, or MCP, and resolving it resumes the workflow exactly where it paused.
 
 Activities are plain functions:
 
@@ -62,6 +72,8 @@ Dashboard at [http://localhost:3000](http://localhost:3000). The [boilerplate](h
 
 ## The pattern
 
+Four moves, from a plan you write to a plan that keeps up with reality.
+
 **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.
@@ -72,7 +84,7 @@ curl -X PUT http://localhost:3000/api/workflows/reviewContent/config \
   -d '{ "invocable": true, "task_queue": "default", "default_role": "reviewer" }'
 ```
 
-**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 3 — React to events.** Signals are reality reporting back. 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 same workflow has two forms. What you wrote in Step 1 is the *procedural* form — readable, Temporal-like, emulated atop the graph: cheap to maintain, heavier to run. The Designer compiles a working execution into the *graph* form — the same durable workflow as a deterministic DAG: no LLM at runtime, no replay overhead, typed in and out, roughly 3x faster. Every procedural pattern has a graph equivalent and the reverse; you pick readability or speed without giving up durability, escalation, or transactional guarantees. It deploys as a reusable tool that any workflow or API call can invoke.
 
@@ -134,7 +146,7 @@ const lt = await start({
 });
 ```
 
-All three paths produce the same outcome: tools callable as durable activities. See the [MCP guide](docs/mcp.md).
+All three paths produce the same outcome: tools callable as durable activities. See the [MCP guide](https://github.com/hotmeshio/long-tail/blob/main/docs/mcp.md).
 
 ## Compile workflows
 
@@ -145,44 +157,62 @@ export ANTHROPIC_API_KEY=sk-ant-...
 npx ltc compile workflows/
 ```
 
-The source is the spec. The compiled YAML is the optimized execution. Both live in the repo. See the [Compiler Guide](docs/compiler.md).
+The source is the spec. The compiled YAML is the optimized execution. Both live in the repo. See the [Compiler Guide](https://github.com/hotmeshio/long-tail/blob/main/docs/compiler.md).
 
 ## Register a graph flow by hand
 
-`graphWorkflows` is the graph-form peer of `workers`: hand-author the HotMesh YAML and it's created, deployed, and activated at startup. This hello-world assembles a greeting from the input with a single trigger mapping:
+`graphWorkflows` is the graph-form peer of `workers`: hand-author the HotMesh YAML and it's created, deployed, and activated at startup. The same human surface is declarative here — a `hook` with an `escalation:` block. When the flow reaches it, the workflow suspends and writes the escalation row; a person resolves it and the flow continues:
 
 ```typescript
 const lt = await start({
   database: { connectionString: process.env.DATABASE_URL },
   graphWorkflows: [{
-    name: 'hello_world',
+    name: 'order_approval',
     namespace: 'graph',
-    inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+    inputSchema: { type: 'object', properties: { orderId: { type: 'string' }, region: { type: 'string' } }, required: ['orderId'] },
     yaml: `
 app:
   id: graph
   version: '1'
   graphs:
-    - subscribes: hello_world
-      publishes: hello_world.done
-      input:  { schema: { type: object, properties: { name: { type: string } } } }
-      output: { schema: { type: object, properties: { greeting: { type: string } } } }
+    - subscribes: order_approval
+      publishes: order_approval.done
+      input:  { schema: { type: object, properties: { orderId: { type: string }, region: { type: string } } } }
+      output: { schema: { type: object, properties: { approved: { type: boolean } } } }
       activities:
         trigger:
           type: trigger
+        review:
+          type: hook
+          escalation:
+            role: approver
+            type: order-approval
+            priority: 2
+            description: Approve order for dispatch
+            metadata:
+              orderId: '{trigger.output.data.orderId}'
+              region: '{trigger.output.data.region}'
+            envelope:
+              instructions: Review and approve or reject
           job:
             maps:
-              greeting:
-                '@pipe':
-                  - ['Hello, ', '{$self.input.data.name}', '!']
-                  - ['{@string.concat}']
-      transitions: {}
+              approved: '{review.hook.data.approved}'
+      transitions:
+        trigger:
+          - to: review
+      hooks:
+        order_approval.approve:
+          - to: review
+            conditions:
+              match:
+                - expected: '{$job.metadata.jid}'
+                  actual: '{$self.hook.data.id}'
 `,
   }],
 });
 ```
 
-It appears under **Orchestrate › Graph** and runs the same way a procedural workflow does — durable, transactional, invocable from the dashboard or API.
+It appears under **Orchestrate › Graph** and routes to a person exactly like the procedural `condition()` above — the same claim-and-resolve surface, declared in YAML. The `metadata` expressions resolve against the live job at suspension time, so the row carries the real order values.
 
 ## Full configuration
 
@@ -240,7 +270,7 @@ client.events.on('task.completed', (event) => console.log('done:', event.workflo
 client.events.on('escalation.*', (event) => notifyTeam(event));
 ```
 
-Every SDK call returns an `LTApiResult` — same status codes, same validation, same RBAC. See the [SDK guide](docs/sdk.md).
+Every SDK call returns an `LTApiResult` — same status codes, same validation, same RBAC. See the [SDK guide](https://github.com/hotmeshio/long-tail/blob/main/docs/sdk.md).
 
 ## Deployment
 
@@ -258,31 +288,31 @@ await start({ database: { connectionString: process.env.DATABASE_URL }, server:
 const lt = createClient({ auth: { userId: 'service' } });
 ```
 
-All modes share PostgreSQL and scale independently. See [Cloud Deployment](docs/cloud.md).
+All modes share PostgreSQL and scale independently. See [Cloud Deployment](https://github.com/hotmeshio/long-tail/blob/main/docs/cloud.md).
 
 ## Docs
 
 | Guide | What it covers |
 |-------|---------------|
-| [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 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 |
-| [SDK](docs/sdk.md) | Embedded usage, `createClient`, event subscriptions |
-| [Architecture](docs/architecture.md) | Project structure, conventions, discovery |
-| [Cloud](docs/cloud.md) | AWS ECS, GCP Cloud Run, Docker |
-| [Data Model](docs/data.md) | Database schema |
-
-**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) · [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)
+| [The Long Tail Story](https://github.com/hotmeshio/long-tail/blob/main/docs/story.md) | Why this exists, what accumulates over time |
+| [Workflows](https://github.com/hotmeshio/long-tail/blob/main/docs/workflows.md) | Activities, interceptor, escalation lifecycle, composition |
+| [IAM](https://github.com/hotmeshio/long-tail/blob/main/docs/iam.md) | Identity propagation, service accounts, credential exchange |
+| [Dashboard](https://github.com/hotmeshio/long-tail/blob/main/docs/dashboard.md) | Navigation, key pages, event feed |
+| [MCP](https://github.com/hotmeshio/long-tail/blob/main/docs/mcp.md) | Server registration, tool calls, human queue |
+| [Compilation](https://github.com/hotmeshio/long-tail/blob/main/docs/compilation.md) | Dynamic to deterministic pipeline wizard |
+| [Compiler](https://github.com/hotmeshio/long-tail/blob/main/docs/compiler.md) | `ltc compile` — durable TypeScript to YAML DAGs |
+| [CLI](https://github.com/hotmeshio/long-tail/blob/main/docs/cli.md) | `ltc` — terminal access to workflows, escalations, knowledge, MCP |
+| [Escalation Strategies](https://github.com/hotmeshio/long-tail/blob/main/docs/escalation-strategies.md) | Default, MCP triage, custom handlers |
+| [SDK](https://github.com/hotmeshio/long-tail/blob/main/docs/sdk.md) | Embedded usage, `createClient`, event subscriptions |
+| [Architecture](https://github.com/hotmeshio/long-tail/blob/main/docs/architecture.md) | Project structure, conventions, discovery |
+| [Cloud](https://github.com/hotmeshio/long-tail/blob/main/docs/cloud.md) | AWS ECS, GCP Cloud Run, Docker |
+| [Data Model](https://github.com/hotmeshio/long-tail/blob/main/docs/data.md) | Database schema |
+
+**Adapters:** [Auth](https://github.com/hotmeshio/long-tail/blob/main/docs/auth.md) · [Events](https://github.com/hotmeshio/long-tail/blob/main/docs/events.md) · [Telemetry](https://github.com/hotmeshio/long-tail/blob/main/docs/telemetry.md) · [Logging](https://github.com/hotmeshio/long-tail/blob/main/docs/logging.md) · [Maintenance](https://github.com/hotmeshio/long-tail/blob/main/docs/maintenance.md) · [OAuth](https://github.com/hotmeshio/long-tail/blob/main/docs/oauth-and-delegation.md)
+
+**HTTP API:** [Workflows](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/workflows.md) · [Tasks](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/tasks.md) · [Escalations](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/escalations.md) · [YAML Workflows](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/yaml-workflows.md) · [Users](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/users.md) · [Roles](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/roles.md) · [Service Accounts](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/service-accounts.md) · [MCP Servers](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/mcp-servers.md) · [Pipelines](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/pipelines.md) · [Exports](https://github.com/hotmeshio/long-tail/blob/main/docs/api/http/exports.md)
+
+**SDK:** [Overview](https://github.com/hotmeshio/long-tail/blob/main/docs/sdk.md) · [Workflows](https://github.com/hotmeshio/long-tail/blob/main/docs/api/sdk/workflows.md) · [Tasks](https://github.com/hotmeshio/long-tail/blob/main/docs/api/sdk/tasks.md) · [Escalations](https://github.com/hotmeshio/long-tail/blob/main/docs/api/sdk/escalations.md) · [YAML Workflows](https://github.com/hotmeshio/long-tail/blob/main/docs/api/sdk/yaml-workflows.md) · [MCP](https://github.com/hotmeshio/long-tail/blob/main/docs/api/sdk/mcp.md) · [Events](https://github.com/hotmeshio/long-tail/blob/main/docs/api/sdk/events.md)
 
 ## Contributing
 
@@ -301,8 +331,8 @@ Open [http://localhost:3000](http://localhost:3000). Example workflows seed the
 | `engineer` | `l0ngt@1l` | engineer |
 | `reviewer` | `l0ngt@1l` | reviewer |
 
-See [Contributing](docs/contributing.md).
+See [Contributing](https://github.com/hotmeshio/long-tail/blob/main/docs/contributing.md).
 
 ## License
 
-See [LICENSE](LICENSE).
+See [LICENSE](https://github.com/hotmeshio/long-tail/blob/main/LICENSE).

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

@@ -3,5 +3,5 @@ export { listEscalations, listAvailableEscalations, listDistinctTypes, getEscala
 export { getEscalation, getEscalationsByWorkflowId, escalateToRole } from './single';
 export { claimEscalation, releaseEscalation } from './claim';
 export { releaseExpiredClaims, updatePriority, bulkClaim, bulkAssign, bulkEscalate, bulkTriage } from './bulk';
-export { resolveEscalation } from './resolve';
+export { resolveEscalation, resolveBySignalKey } 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.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;
+exports.resolveByMetadata = exports.claimByMetadata = exports.findByMetadata = exports.resolveBySignalKey = 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,6 +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; } });
+Object.defineProperty(exports, "resolveBySignalKey", { enumerable: true, get: function () { return resolve_1.resolveBySignalKey; } });
 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; } });

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

@@ -16,3 +16,13 @@ export declare function resolveEscalation(input: {
     id: string;
     resolverPayload: Record<string, any>;
 }, _auth: LTApiAuth): Promise<LTApiResult>;
+/**
+ * Resolve an efficient (atomic) escalation directly by its `signal_key` and
+ * resume the waiting workflow in place. For webhook callers that know the
+ * deterministic signal id (e.g. `signal-scan-ar-${orderId}`) and want to skip
+ * the id lookup. RBAC-scoped to the caller's visible roles.
+ */
+export declare function resolveBySignalKey(input: {
+    signalKey: string;
+    resolverPayload: Record<string, any>;
+}, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/resolve.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveEscalation = resolveEscalation;
+exports.resolveBySignalKey = resolveBySignalKey;
 const escalationService = __importStar(require("../../services/escalation"));
 const taskService = __importStar(require("../../services/task"));
 const escalation_strategy_1 = require("../../services/escalation-strategy");
@@ -41,6 +42,7 @@ const ephemeral_1 = require("../../services/iam/ephemeral");
 const deployer_1 = require("../../services/yaml-workflow/deployer");
 const workers_1 = require("../../workers");
 const defaults_1 = require("../../modules/defaults");
+const helpers_1 = require("./helpers");
 // ── Orchestrator ─────────────────────────────────────────────────────────
 /**
  * Resolve a pending escalation with a human-provided payload.
@@ -76,6 +78,13 @@ async function resolveEscalation(input, _auth) {
         if (signalRouting?.signalId) {
             return resolveViaSignalRouting(escalation, resolverPayload);
         }
+        // Path 0: efficient (atomic) escalation — signal_key resumes in place.
+        // The row was written inside the workflow's Leg1 checkpoint via
+        // `condition(signalId, config)`. The SDK's resolve marks it resolved AND
+        // delivers the signal to `signal_key`, resuming THIS job — no re-run.
+        if (escalation.signal_key) {
+            return resolveViaSignalKey(escalation, resolverPayload);
+        }
         // Path C: escalation strategy may redirect to triage
         const envelope = await reconstructEnvelope(escalation);
         const strategy = escalation_strategy_1.escalationStrategyRegistry.current;
@@ -97,6 +106,34 @@ async function resolveEscalation(input, _auth) {
         return { status: 500, error: err.message };
     }
 }
+/**
+ * Resolve an efficient (atomic) escalation directly by its `signal_key` and
+ * resume the waiting workflow in place. For webhook callers that know the
+ * deterministic signal id (e.g. `signal-scan-ar-${orderId}`) and want to skip
+ * the id lookup. RBAC-scoped to the caller's visible roles.
+ */
+async function resolveBySignalKey(input, auth) {
+    try {
+        const { signalKey, resolverPayload } = input;
+        if (!signalKey)
+            return { status: 400, error: 'signalKey is required' };
+        if (!resolverPayload)
+            return { status: 400, error: 'resolverPayload is required' };
+        const escalation = await escalationService.getEscalationBySignalKey(signalKey);
+        if (!escalation)
+            return { status: 404, error: 'Escalation not found' };
+        if (escalation.status !== 'pending')
+            return { status: 409, error: 'Escalation not available for resolution' };
+        const visibleRoles = await (0, helpers_1.getVisibleRoles)(auth.userId);
+        if (visibleRoles && !visibleRoles.includes(escalation.role)) {
+            return { status: 404, error: 'Escalation not found' };
+        }
+        return resolveViaSignalKey(escalation, resolverPayload);
+    }
+    catch (err) {
+        return { status: 500, error: err.message };
+    }
+}
 // ── Resolution paths ─────────────────────────────────────────────────────
 /** Path A: lightweight conditionLT signal — inject $escalation_id and signal the running workflow. */
 async function resolveViaConditionSignal(escalation, resolverPayload) {
@@ -107,6 +144,21 @@ async function resolveViaConditionSignal(escalation, resolverPayload) {
     // Event published by service layer (services/escalation/crud.ts)
     return signaledResult(escalation, escalation.workflow_id);
 }
+/**
+ * Path 0: efficient escalation — resolve by `signal_key`. The SDK delivers the
+ * signal to the waiting `condition()` AND marks the row resolved in one
+ * transaction, so the original job resumes in place (no re-run, no separate
+ * resolve activity). Password fields are redacted before they enter the signal.
+ */
+async function resolveViaSignalKey(escalation, resolverPayload) {
+    const signalPayload = await redactPasswords(resolverPayload, escalation.metadata?.form_schema);
+    const resolved = await escalationService.resolveEscalation(escalation.id, signalPayload);
+    if (!resolved) {
+        return { status: 409, error: 'Escalation not available for resolution' };
+    }
+    // Event published by service layer (services/escalation/crud.ts)
+    return signaledResult(escalation, escalation.workflow_id || '');
+}
 /** Path B: waitFor signal escalation — signal via YAML engine or Durable handle. */
 async function resolveViaSignalRouting(escalation, resolverPayload) {
     const signalRouting = escalation.metadata.signal_routing;

package/build/api/topics.d.ts

@@ -1,3 +1,4 @@
+import type { LTEvent } from '../types';
 import type { LTApiResult } from '../types/sdk';
 export declare function listTopics(input: {
     category?: string;
@@ -27,10 +28,19 @@ export declare function deleteTopic(input: {
  * Literal segments must match exactly.
  */
 export declare function isValidVariant(pattern: string, subject: string): boolean;
+/**
+ * A publishable event envelope. The request body IS the event: any `LTEvent`
+ * field the caller wants to set (`id`, `source`, `data`, and — for system
+ * families — `workflowId` / `workflowName` / `taskQueue` / `status` / etc.),
+ * minus the server-managed ones (`type` is derived from the subject, `timestamp`
+ * is stamped). `subject` is an optional concrete variant of a wildcard topic.
+ *
+ * One typed object, infinitely extensible — no per-field API parameters.
+ */
+export type PublishEventInput = Partial<Omit<LTEvent, 'type' | 'timestamp'>> & {
+    subject?: string;
+};
 export declare function publishTopic(input: {
     topic: string;
-    subject?: string;
-    eventId?: string;
-    data: Record<string, any>;
-    source?: string;
+    event?: PublishEventInput;
 }): Promise<LTApiResult>;

package/build/api/topics.js

@@ -129,19 +129,19 @@ function isValidVariant(pattern, subject) {
 }
 async function publishTopic(input) {
     try {
-        const publishSubject = input.subject || input.topic;
+        const { subject, ...fields } = input.event ?? {};
+        const publishSubject = subject || input.topic;
         // Validate subject is a valid variant of the topic pattern
-        if (input.subject && !isValidVariant(input.topic, input.subject)) {
-            return { status: 400, error: `Subject "${input.subject}" does not match topic pattern "${input.topic}"` };
+        if (subject && !isValidVariant(input.topic, subject)) {
+            return { status: 400, error: `Subject "${subject}" does not match topic pattern "${input.topic}"` };
         }
+        // The envelope is the caller's; the server owns type/timestamp (and mints id
+        // downstream in eventRegistry.publish if the caller didn't supply one).
         const event = {
-            id: input.eventId,
+            ...fields,
             type: publishSubject,
-            source: input.source || 'dashboard',
-            workflowId: '',
-            workflowName: '',
-            taskQueue: '',
-            data: input.data,
+            source: fields.source || 'dashboard',
+            data: fields.data ?? {},
             timestamp: new Date().toISOString(),
         };
         await events_1.eventRegistry.publish(event);

package/build/lib/events/index.js

@@ -30,9 +30,15 @@ class LTEventRegistry {
     async publish(event) {
         if (!this.adapters.length)
             return;
+        // The manager guarantees the universal envelope fields: mint an idempotent
+        // id and stamp a timestamp when the publisher (e.g. a custom app event) did
+        // not supply them. `type` is the publisher's responsibility.
         if (!event.id) {
             event.id = `evt-${Date.now()}-${Math.random().toString(16).slice(2, 6)}`;
         }
+        if (!event.timestamp) {
+            event.timestamp = new Date().toISOString();
+        }
         await Promise.allSettled(this.adapters.map((a) => a.publish(event).catch((err) => {
             logger_1.loggerRegistry.error(`[lt-events] adapter publish failed: ${err?.message}`);
         })));

package/build/lib/events/publish.js

@@ -103,12 +103,10 @@ function publishActivityEvent(params) {
  */
 function publishKnowledgeEvent(params) {
     const action = params.type.split('.')[1];
+    // No workflow context — knowledge events carry only the minimal envelope + data.
     return fireAndForget({
         type: `system.knowledge.${params.domain}.${action}`,
         source: 'knowledge',
-        workflowId: '',
-        workflowName: '',
-        taskQueue: '',
         data: { domain: params.domain, key: params.key },
         timestamp: new Date().toISOString(),
     });
@@ -124,12 +122,10 @@ function publishFileEvent(params) {
     const dotIdx = filename.lastIndexOf('.');
     const name = dotIdx > 0 ? filename.slice(0, dotIdx) : filename;
     const extension = dotIdx > 0 ? filename.slice(dotIdx + 1) : '';
+    // No workflow context — file events carry only the minimal envelope + data.
     return fireAndForget({
         type: `system.file.${action}`,
         source: 'file-storage',
-        workflowId: '',
-        workflowName: '',
-        taskQueue: '',
         data: {
             path: params.path,
             name,
@@ -147,12 +143,12 @@ function publishFileEvent(params) {
  */
 function publishAgentEvent(params) {
     const action = params.type.replace('agent.', '');
+    // Agents have no task queue; agentId/agentName ride workflowId/workflowName for routing parity.
     return fireAndForget({
         type: `system.agent.${params.agentName}.${action}`,
         source: 'agent',
         workflowId: params.agentId,
         workflowName: params.agentName,
-        taskQueue: '',
         status: params.status,
         data: params.data,
         timestamp: new Date().toISOString(),

package/build/lib/events/system-events.js

@@ -27,9 +27,9 @@ function mapSystemEvent(event) {
         return {
             type: event.type,
             source: 'sdk',
-            workflowId: row.workflow_id || event.workflow_id || '',
-            workflowName: row.workflow_type || '',
-            taskQueue: row.task_queue || '',
+            workflowId: row.workflow_id || event.workflow_id || undefined,
+            workflowName: row.workflow_type || undefined,
+            taskQueue: row.task_queue || undefined,
             escalationId: row.id || segments[2],
             originId: row.origin_id || event.origin_id || undefined,
             status: ESCALATION_STATUS_BY_VERB[verb] ?? verb,
@@ -42,9 +42,8 @@ function mapSystemEvent(event) {
     return {
         type: event.type,
         source: 'sdk',
-        workflowId: event.workflow_id || '',
-        workflowName: '',
-        taskQueue: event.data?.taskQueue || '',
+        workflowId: event.workflow_id || undefined,
+        taskQueue: event.data?.taskQueue || undefined,
         data: event.data,
         timestamp: event.ts,
     };

package/build/routes/escalations/resolve.js

@@ -36,11 +36,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerResolveRoutes = registerResolveRoutes;
 const api = __importStar(require("../../api/escalations"));
 function registerResolveRoutes(router) {
+    /**
+     * POST /api/escalations/resolve-by-signal-key
+     * Resolve an efficient (atomic) escalation by its signal_key and resume the
+     * waiting workflow in place. For webhook callers that know the deterministic
+     * signal id. Literal single-segment path — registered before /:id/resolve so
+     * it is never shadowed by the parameterized route.
+     * Body: { signalKey: string, resolverPayload: Record<string, any> }
+     */
+    router.post('/resolve-by-signal-key', async (req, res) => {
+        const result = await api.resolveBySignalKey({ signalKey: req.body?.signalKey, resolverPayload: req.body?.resolverPayload }, req.auth);
+        res.status(result.status).json(result.data ?? { error: result.error });
+    });
     /**
      * POST /api/escalations/:id/resolve
-     * Start a new workflow with resolver data to re-run the failed step.
-     * The interceptor in the new workflow resolves the escalation record
-     * and signals back to the orchestrator (if any) on success.
+     * Resolve a pending escalation with a human-provided payload. Routes by
+     * escalation shape: efficient (signal_key) resumes the job in place; legacy
+     * paths signal via routing metadata or re-run the original workflow.
      * Body: { resolverPayload: Record<string, any> }
      */
     router.post('/:id/resolve', async (req, res) => {

package/build/routes/topics.js

@@ -92,12 +92,10 @@ router.delete('/by-name/:topic', async (req, res) => {
  * Publish a test event to the event bus with the given topic and payload.
  */
 router.post('/by-name/:topic/publish', async (req, res) => {
+    // The request body IS the event envelope (Partial<LTEvent> + optional subject).
     const result = await api.publishTopic({
         topic: decodeURIComponent(req.params.topic),
-        subject: req.body.subject || undefined,
-        eventId: req.body.eventId || undefined,
-        data: req.body.data ?? {},
-        source: req.body.source ?? 'dashboard',
+        event: (req.body ?? {}),
     });
     res.status(result.status).json(result.data ?? { error: result.error });
 });

package/build/services/agent/input-mapper.js

@@ -2,21 +2,44 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.applyInputMapping = applyInputMapping;
 /**
- * Resolve a template string like "{event.data.orderId}" against an event object.
- * Returns the resolved value, or the raw template if the path doesn't exist.
+ * Resolve a dotted path like "event.data.orderId" against `{ event }`.
+ * Returns the resolved value, or `undefined` if any segment is missing.
  */
-function resolveTemplate(template, event) {
-    const match = template.match(/^\{(.+)\}$/);
-    if (!match)
-        return template;
-    const path = match[1].split('.');
+function resolvePath(path, event) {
+    const segments = path.trim().split('.');
     let current = { event };
-    for (const segment of path) {
+    for (const segment of segments) {
         if (current == null || typeof current !== 'object')
-            return template;
+            return undefined;
         current = current[segment];
     }
-    return current ?? template;
+    return current;
+}
+/**
+ * Resolve a template string against an event.
+ *
+ * - A string that is exactly one token resolving to a **non-scalar**
+ *   (object/array) returns that value unchanged — full-object resolution,
+ *   e.g. `"{event.data}"` → the whole data object.
+ * - Every other string is interpolated **inline**: each `{path}` is replaced by
+ *   `String(resolved)`. This covers tokens embedded in surrounding text, multiple
+ *   tokens in one string, and single tokens that resolve to a scalar — e.g.
+ *   `"https://host/lt?entity={event.workflowName}&q={event.workflowId}"`.
+ *   A token whose path does not exist is left verbatim, so an unresolved
+ *   `{event.data.missing}` passes through unchanged (other tokens still resolve).
+ */
+function resolveTemplate(template, event) {
+    const exact = template.match(/^\{([^}]+)\}$/);
+    if (exact) {
+        const resolved = resolvePath(exact[1], event);
+        if (resolved !== null && resolved !== undefined && typeof resolved === 'object') {
+            return resolved;
+        }
+    }
+    return template.replace(/\{([^}]+)\}/g, (original, path) => {
+        const resolved = resolvePath(path, event);
+        return resolved !== null && resolved !== undefined ? String(resolved) : original;
+    });
 }
 /**
  * Recursively apply input mapping templates against an event.