@hotmeshio/long-tail-dbos 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,221 @@
+Plain-language summary (not part of the license)
+
+Long Tail for DBOS is source available under the Apache License 2.0 with
+the Commons Clause condition below. In short:
+
+- You may use, copy, modify and run it, in production and inside your
+  organization, and self-host it for your own work.
+- You may build and sell your own products that use it, as long as their
+  value does not derive entirely or substantially from Long Tail for DBOS.
+- You may not sell Long Tail for DBOS itself: no product, hosted service,
+  or paid hosting, consulting or support whose value derives entirely or
+  substantially from it. Only HotMeshIO offers Long Tail for DBOS
+  commercially.
+
+This summary is a convenience. It does not change the license below; where
+the two differ, the license governs.
+
+---
+
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as
+defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights
+under the License will not include, and the License does not grant to
+you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of
+the rights granted to you under the License to provide to third parties,
+for a fee or other consideration (including without limitation fees for
+hosting or consulting/support services related to the Software), a
+product or service whose value derives, entirely or substantially, from
+the functionality of the Software. Any license notice or attribution
+required by the License must also include this Commons Clause License
+Condition notice.
+
+Software: HotMesh Long Tail for DBOS
+
+License: Apache 2.0
+
+Licensor: HotMeshIO
+
+---
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# Long Tail for DBOS
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Human steps for DBOS workflows, on your own Postgres
+
+**One call, `conditional()`, gives a DBOS workflow a full human-in-the-loop desk: role queues, claims, forms, SLAs and a dashboard. It runs entirely on-prem: Postgres, your app and one Long Tail container. No cloud service, no extra server to operate.**
+
+DBOS is a library over Postgres. Long Tail is a container over Postgres. Together they run where your data already lives, with no connection to anything outside your network. A DBOS workflow that needs a person to approve, correct or decide something calls `conditional()`, parks, and gets the answer back as a typed value. Everything between those two moments (who sees the work, who claims it, which form they fill in, what happens when nobody answers in time) is Long Tail's job.
+
+### The problem
+
+Durable workflows are good at the parts machines do. The moment a step needs a person, every team builds the same things again: a table of pending tasks, a way to route them to the right people, a UI to work them, a timeout, an audit trail, and the plumbing to wake the workflow when someone answers. That code is rarely the product, and it is rarely done well.
+
+### The solution
+
+Take one small step sideways. Keep DBOS exactly as it is, and call `conditional()` where a person belongs:
+
+```ts
+import { DBOS } from '@dbos-inc/dbos-sdk';
+import { conditional } from '@hotmeshio/long-tail-dbos';
+
+async function reviewOrderFn(orderId: string) {
+  const { risk } = await DBOS.runStep(() => scoreOrder(orderId), { name: 'score' });
+
+  const decision = await conditional<{ approved: boolean; notes?: string }>(`review-${orderId}`, {
+    role: 'reviewer',
+    type: 'order-review',
+    description: `Review order ${orderId}`,
+    metadata: { orderId },
+    data: { risk },
+    timeout: '48h',
+  });
+
+  if (!decision) return { orderId, status: 'expired-or-cancelled' };
+  if (decision.approved) await DBOS.runStep(() => ship(orderId), { name: 'ship' });
+  return { orderId, status: decision.approved ? 'shipped' : 'rejected' };
+}
+
+export const reviewOrder = DBOS.registerWorkflow(reviewOrderFn, { name: 'reviewOrder' });
+```
+
+The workflow parks in `DBOS.recv`. An escalation appears in the `reviewer` queue in the Long Tail dashboard. A reviewer claims it, fills in the role's form, and submits. Long Tail delivers one terminal outcome back to the workflow, which carries on.
+
+### `conditional()` at a glance
+
+```ts
+const answer = await conditional<T>(key, ask);
+```
+
+- `key` names the wait within the workflow. Opening the same key again returns the same escalation, so a retried step never creates a second one.
+- `ask` describes the escalation: `role` (the queue), `type`, `description`, `priority` (1 to 4), `metadata` (searchable facets), `data` (shown to the resolver) and `timeout` (the SLA, such as `'48h'`).
+- `answer` is the resolver's payload, typed as `T`, or `null` when the escalation expired or was cancelled.
+
+The same call works in HotMesh and Temporal workflows. Long Tail's documentation is at [hotmesh.io](https://hotmesh.io/docs/start/quickstart); [conditional()](https://hotmesh.io/docs/build/conditional) covers roles, forms and facets in depth.
+
+## Getting started in five minutes
+
+You need Docker.
+
+```bash
+docker compose up -d --build             # Postgres, Long Tail, and the example DBOS app
+curl -X POST localhost:4000/orders/42    # starts reviewOrder for order 42
+```
+
+Open http://localhost:3400, sign in as `superadmin` / `l0ngt@1l` (set `LT_ADMIN_PASSWORD` in `.env` to change it), open the **reviewer** queue, claim the review for order 42 and resolve it. The app logs the result.
+
+Try the restart story while the review is waiting:
+
+```bash
+curl -X POST localhost:4000/orders/43
+docker compose restart review-order      # the app goes away mid-wait
+# resolve order 43 in the dashboard; the restarted app recovers the workflow and it completes
+```
+
+Everything in `docker-compose.yml` is local: one Postgres database, `longtail`, holding Long Tail's tables and DBOS's system tables (in the `dbos` schema), the Long Tail container (API, dashboard and delivery relay) and the example app. Nothing calls out to the internet.
+
+| Port | Service | Override |
+|---|---|---|
+| 3400 | Long Tail dashboard and API | `LT_PORT` |
+| 4000 | The example DBOS app | `APP_PORT` |
+| 5425 | Postgres (`longtail`) | `PG_PORT` |
+
+The example app mints its own Long Tail bot key at startup by signing in as the admin. That is a local convenience; in production, set `LT_API_KEY`.
+
+### In your own app
+
+```bash
+npm install @hotmeshio/long-tail-dbos @dbos-inc/dbos-sdk
+```
+
+```ts
+import { DBOS } from '@dbos-inc/dbos-sdk';
+import { configureLongTail } from '@hotmeshio/long-tail-dbos'; // registers the lt.open and lt.close steps
+
+configureLongTail({ url: process.env.LT_URL!, apiKey: process.env.LT_API_KEY! });
+DBOS.setConfig({ name: 'orders', systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL });
+await DBOS.launch();
+```
+
+- Import the package before `DBOS.launch()`. DBOS requires steps to be registered first, and the package says so clearly if the order is wrong.
+- `LT_API_KEY` is a Long Tail bot account key (create the bot and its key once in the dashboard) whose roles allow creating escalations in the roles your workflows use.
+
+Run Long Tail with the provider, either from this repo's image (`node build/start.js`) or in your own code. The image reads its configuration from the environment:
+
+| Variable | Meaning |
+|---|---|
+| `DBOS_SYSTEM_DATABASE_URL` | The DBOS system database your app uses. Long Tail reads it to deliver outcomes and to show the timeline. Defaults to `DATABASE_URL`: one database, with DBOS's tables in the `dbos` schema. |
+| `DATABASE_URL` or `POSTGRES_HOST/PORT/USER/PASSWORD/DB` | Long Tail's database. |
+| `PORT`, `JWT_SECRET` | Long Tail's HTTP port and token secret. |
+| `LT_ADMIN_USER`, `LT_ADMIN_PASSWORD`, `LT_ADMIN_EMAIL` | The seeded admin. |
+| `LT_ROLES` | Comma-separated roles to create, such as `reviewer,finance`. |
+| `LT_START_CONFIG` | Optional JSON file with further `start()` settings, such as role titles or SSO. |
+
+In your own code:
+
+```ts
+import { start } from '@hotmeshio/long-tail';
+import { dbosProvider } from '@hotmeshio/long-tail-dbos/provider';
+
+await start({
+  database: { connectionString: process.env.DATABASE_URL },
+  durable: { provider: await dbosProvider({ systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL! }) },
+});
+```
+
+## FAQ
+
+### What does DBOS still own, and what does Long Tail own?
+
+| DBOS | Long Tail |
+|---|---|
+| Checkpoints, step retries, recovery, executor and version handling | The escalation row, role routing, RBAC, claims and reassignment |
+| Time inside the workflow, and the `recv` that parks it | Forms, schema enforcement, facets, priority, the dashboard and MCP tools |
+| Your workflow and step code | SLA expiry, cancellation by a person, and delivery of the outcome |
+
+The two meet at one call. `conditional()` opens a wait and receives exactly one terminal outcome: `resolved` (with the resolver's payload), `expired` or `cancelled`. It returns the payload, or `null` for the other two.
+
+### How is the outcome delivered?
+
+When an escalation reaches a terminal state, by any path (dashboard, API, MCP tool, bulk action, scan rule, expiry), Long Tail's relay delivers it:
+
+1. It checks that the workflow is still waiting (`DBOSClient.getWorkflow`). A finished or missing workflow is recorded as gone and never sent; DBOS would otherwise store the message without error and nobody would read it.
+2. It calls `DBOSClient.send(workflowId, outcome, waitKey, escalationId)`. The escalation id is the DBOS idempotency key, so a retried delivery stores one message.
+3. It records the delivery. Failed sends retry with capped backoff, and a lease keeps two Long Tail replicas from delivering the same wait.
+
+If the app is down when someone resolves, the message waits in the DBOS system database. When the app restarts and recovers the workflow, `recv` reads it.
+
+### Why must keys be unique per workflow?
+
+Long Tail opens a wait once per `(workflowId, key)`, so a retried `lt.open` step never creates a second escalation. A loop that asks again uses a new key per round: `review-${orderId}-${round}`. A forked workflow has a new id, so it opens new waits. A `rewindWorkflow` that re-runs the wait reopens it, and Long Tail delivers the outcome again.
+
+### How do SLAs, expiry and the `recv` deadline fit together?
+
+- `timeout` (for example `'48h'`) becomes the escalation's expiry. Long Tail expires the row on time and delivers `expired`; `conditional()` returns `null`.
+- DBOS gives `recv` a default timeout of 60 seconds, so `conditional()` always sets its own: the SLA plus ten minutes of grace, so Long Tail's expiry arrives first.
+- With no SLA, the backstop is `maxWaitSeconds` (default 365 days).
+- If the backstop passes before any outcome, the `lt.close` step cancels the escalation and `conditional()` returns `null`.
+
+### What does the dashboard show for a DBOS workflow?
+
+All of the escalation work surfaces: queues, claims, forms, history, analytics, roles and users.
+
+**Executions** (under Workflows in the sidebar) lists DBOS workflows, newest first. It filters by workflow id prefix, workflow type and state. Running covers `PENDING`, `ENQUEUED`, `DELAYED` and `SUSPENDED`; failed covers `ERROR`, `CANCELLED` and `MAX_RECOVERY_ATTEMPTS_EXCEEDED`. The rows come from `DBOSClient.listWorkflows`. The total comes from a count over the `workflow_status` table in the DBOS system database, with the same filters, because the client lists but does not count.
+
+The workflow execution page builds its timeline from DBOS's own records (`getWorkflow` and `listWorkflowSteps`):
+
+- steps as activities;
+- the wait as a span from `lt.open` to the `recv` that read the outcome;
+- timers, child workflows and failures.
+
+DBOS records step outputs but not step inputs, so the timeline shows outputs and the workflow's input. The wait ends when the workflow read the outcome; if the app was down when someone resolved, the escalation shows the resolve time.
+
+Pages that only make sense on HotMesh (YAML pipelines, stream tables, control plane, triage and AI query) are hidden. Their API routes answer 501 with a message naming the engine.
+
+### Running on-prem without Conductor
+
+This package targets self-hosted DBOS: the open source library and your Postgres. Recovery works without any hosted service, provided each replica keeps a stable identity. The integration tests verify each point below.
+
+- **Stable executor IDs per replica.** DBOS tags each workflow with the executor that runs it (`DBOS__VMID`, or `executorID` in `DBOS.setConfig`; the default is `local`). On launch, a process recovers pending workflows tagged with its own executor ID. Give every replica a fixed ID, such as the compose service name or a StatefulSet ordinal. A restarted replica then picks up its own parked waits.
+- **A pinned application version, plus `DBOS.patch` for code changes.** DBOS recovers a workflow only on a process running the same application version (`DBOS__APPVERSION`, or `applicationVersion`). The default is a hash of your code, so an ordinary redeploy would leave earlier waits parked. Pin the version. When you change a workflow's code path, gate the new branch with `DBOS.patch('name')`: waits parked under the old code replay the old path, and new runs take the new one.
+- **Retiring a replica.** Its workflows stay tagged with its executor ID. Recover them from a running replica:
+  - Find them with `DBOS.listWorkflows({ status: 'PENDING', executorId: 'replica-a' })`.
+  - Adopt each one with `DBOS.resumeWorkflow(id)`.
+
+  DBOS also documents an admin recovery endpoint, `POST /dbos-workflow-recovery`. The TypeScript 5.5 package this repo tests against does not include it, so `resumeWorkflow` is the path shown here. Only resume workflows from a replica that is really gone.
+- **Memory per parked wait.** A workflow parked in `recv` is an in-memory promise in the app process. DBOS listens for messages with Postgres LISTEN/NOTIFY and also polls periodically as a fallback. A restart replays each pending workflow from its checkpoints until it parks again. Size the app process for the number of open escalations it holds.
+
+DBOS Cloud and Conductor are a possible later follow-on; nothing here depends on them.
+
+### Do I need anything besides Postgres?
+
+No. By default DBOS keeps its system tables in Long Tail's database, in the `dbos` schema, so one Postgres database serves both. Separate databases work too: set `DBOS_SYSTEM_DATABASE_URL`. The Long Tail container needs no other service. If you already run NATS for Long Tail events you can keep it, but it is optional.
+
+### What is the license?
+
+Source available: Apache 2.0 with the Commons Clause.
+- You can use it, change it and run it in production for your own work.
+- You can build and sell your own products on top of it.
+- You cannot sell this package itself, or a hosted service built mainly from it. Only HotMeshIO does that.
+
+See [LICENSE](LICENSE); its summary is a convenience and the license text governs.
+
+### What is out of scope today?
+
+- Batch and accumulate escalations, where one row collects many items.
+- Starting DBOS workflows from Long Tail.
+- DBOS schedules.
+- Running HotMesh and DBOS workflows in one deployment.
+- DBOS suspend mode.
+
+## Development
+
+```bash
+npm install
+npm test                    # unit tests, no services needed
+npm run test:integration    # Long Tail and DBOS in process against Postgres
+npm run test:e2e            # the running stack over HTTP (docker compose up -d --build)
+npm run build
+npm run probe               # re-records tests/fixtures/dbos-run.json from a real DBOS run
+```
+
+- The integration tests use this repo's Postgres (`docker compose up -d postgres`, port 5425; set `PG_PORT` to point elsewhere). They create and drop only their own database, `lt_dbos_e2e`.
+- The end-to-end tests drive the compose stack the way a deployment runs: they start reviews through the app on port 4000 and work them through Long Tail on port 3400 as people and bots would. `LT_URL`, `APP_URL`, `LT_ADMIN_USER` and `LT_ADMIN_PASSWORD` point them elsewhere. Each run uses unique ids, so it can run repeatedly against one stack.
+- The image installs `@hotmeshio/long-tail` from npm. To try an unreleased build, run `./scripts/pack-long-tail.sh ../long-tail`; the image then installs `vendor/*.tgz` instead.
+
+### Releasing
+
+CI runs on every pull request and every push to `main`. To release, bump `version` in `package.json` and merge to `main`. The Release workflow runs CI again, publishes the version to npm with provenance, tags `v<version>` and creates a GitHub release. A version npm already has is skipped.

package/build/conditional.d.ts

@@ -0,0 +1,11 @@
+import type { LTConditionalConfig } from './types';
+/**
+ * Wait for a person (or machine) through Long Tail.
+ *
+ * Opens an escalation in `config.role`, parks the workflow in DBOS.recv, and
+ * returns the resolver payload. Returns null when the escalation expires or
+ * is cancelled. `key` is unique per wait within one workflow.
+ */
+export declare function conditional<T = Record<string, unknown>>(key: string, config: LTConditionalConfig): Promise<T | null>;
+/** recv deadline: the SLA plus a grace period, or the max wait when there is no SLA. */
+export declare function waitSeconds(config: LTConditionalConfig): number;

package/build/conditional.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conditional = conditional;
+exports.waitSeconds = waitSeconds;
+const dbos_sdk_1 = require("@dbos-inc/dbos-sdk");
+const constants_1 = require("./constants");
+const duration_1 = require("./duration");
+const steps_1 = require("./steps");
+/**
+ * Wait for a person (or machine) through Long Tail.
+ *
+ * Opens an escalation in `config.role`, parks the workflow in DBOS.recv, and
+ * returns the resolver payload. Returns null when the escalation expires or
+ * is cancelled. `key` is unique per wait within one workflow.
+ */
+async function conditional(key, config) {
+    if (!key)
+        throw new Error('conditional(key): key is required');
+    if (!config?.role || !config.type)
+        throw new Error('conditional(key, config): role and type are required');
+    if (!dbos_sdk_1.DBOS.isInWorkflow())
+        throw new Error('conditional() must run in a DBOS workflow body, not inside a step');
+    // 1. Open the wait (idempotent on workflowId + key)
+    const opened = await (0, steps_1.ltOpen)(key, config);
+    // 2. Park until Long Tail delivers; DBOS defaults recv to 60 s, so the deadline is explicit
+    const outcome = await dbos_sdk_1.DBOS.recv(key, { timeoutSeconds: waitSeconds(config) });
+    // 3. No outcome means the backstop passed first: close the row
+    if (!outcome) {
+        dbos_sdk_1.DBOS.logger.warn(`long-tail-dbos: ${key} reached its recv deadline (${constants_1.CLOSE_REASON_DEADLINE}); cancelling ${opened.escalationId}`);
+        await (0, steps_1.ltClose)(opened.escalationId);
+        return null;
+    }
+    return outcome.status === 'resolved' ? (outcome.data ?? {}) : null;
+}
+/** recv deadline: the SLA plus a grace period, or the max wait when there is no SLA. */
+function waitSeconds(config) {
+    if (config.timeout !== undefined) {
+        return Math.ceil((0, duration_1.toMs)(config.timeout) / 1000) + constants_1.WAIT_DEFAULTS.GRACE_SECONDS;
+    }
+    return config.maxWaitSeconds ?? constants_1.WAIT_DEFAULTS.MAX_WAIT_SECONDS;
+}

package/build/config.d.ts

@@ -0,0 +1,6 @@
+import type { LongTailConnection } from './types';
+/** Point the shim at Long Tail. Call once at startup, before DBOS.launch(). */
+export declare function configureLongTail(config: LongTailConnection): void;
+export declare function getLongTailConnection(): LongTailConnection;
+/** For tests. */
+export declare function resetLongTailConnection(): void;

package/build/config.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureLongTail = configureLongTail;
+exports.getLongTailConnection = getLongTailConnection;
+exports.resetLongTailConnection = resetLongTailConnection;
+let connection = null;
+/** Point the shim at Long Tail. Call once at startup, before DBOS.launch(). */
+function configureLongTail(config) {
+    if (!config?.url || typeof config.url !== 'string')
+        throw new Error('configureLongTail: url is required');
+    if (!config.apiKey || typeof config.apiKey !== 'string')
+        throw new Error('configureLongTail: apiKey is required');
+    try {
+        new URL(config.url);
+    }
+    catch {
+        throw new Error(`configureLongTail: url "${config.url}" is not a valid URL`);
+    }
+    connection = { ...config, url: config.url.replace(/\/+$/, '') };
+}
+function getLongTailConnection() {
+    if (!connection)
+        throw new Error('Long Tail is not configured: call configureLongTail({ url, apiKey }) before conditional()');
+    return connection;
+}
+/** For tests. */
+function resetLongTailConnection() {
+    connection = null;
+}

package/build/constants.d.ts

@@ -0,0 +1,33 @@
+/** Step names the shim registers; they appear in the DBOS step list. */
+export declare const STEP: {
+    readonly OPEN: "lt.open";
+    readonly CLOSE: "lt.close";
+};
+/** Reserved DBOS operation names (they appear in listWorkflowSteps). */
+export declare const DBOS_OP: {
+    readonly RECV: "DBOS.recv";
+    readonly SLEEP: "DBOS.sleep";
+    readonly SEND: "DBOS.send";
+    readonly GET_RESULT: "DBOS.getResult";
+    readonly GET_STATUS: "getStatus";
+};
+/** DBOS operations that are bookkeeping, not work. */
+export declare const DBOS_SYSTEM_STEPS: readonly string[];
+export declare const PROVIDER_NAME = "dbos";
+export declare const WAIT_DEFAULTS: {
+    /** Added to the SLA so Long Tail's expiry reaches the workflow before the recv deadline. */
+    readonly GRACE_SECONDS: number;
+    /** recv deadline when the wait has no SLA. */
+    readonly MAX_WAIT_SECONDS: number;
+    readonly OPEN_ATTEMPTS: 10;
+    readonly REQUEST_TIMEOUT_MS: 15000;
+};
+export declare const LT_PATHS: {
+    readonly OPEN_WAIT: "/api/escalations/waits";
+    readonly CANCEL: (escalationId: string) => string;
+};
+export declare const STEP_PAGE_SIZE = 500;
+/** Connections the provider keeps for counting workflows in the executions list. */
+export declare const COUNT_POOL_SIZE = 2;
+/** Reason sent when the recv deadline passes before Long Tail delivered an outcome. */
+export declare const CLOSE_REASON_DEADLINE = "wait-deadline";

package/build/constants.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLOSE_REASON_DEADLINE = exports.COUNT_POOL_SIZE = exports.STEP_PAGE_SIZE = exports.LT_PATHS = exports.WAIT_DEFAULTS = exports.PROVIDER_NAME = exports.DBOS_SYSTEM_STEPS = exports.DBOS_OP = exports.STEP = void 0;
+/** Step names the shim registers; they appear in the DBOS step list. */
+exports.STEP = {
+    OPEN: 'lt.open',
+    CLOSE: 'lt.close',
+};
+/** Reserved DBOS operation names (they appear in listWorkflowSteps). */
+exports.DBOS_OP = {
+    RECV: 'DBOS.recv',
+    SLEEP: 'DBOS.sleep',
+    SEND: 'DBOS.send',
+    GET_RESULT: 'DBOS.getResult',
+    GET_STATUS: 'getStatus',
+};
+/** DBOS operations that are bookkeeping, not work. */
+exports.DBOS_SYSTEM_STEPS = [
+    'DBOS.now',
+    'DBOS.randomUUID',
+    'DBOS.setEvent',
+    'DBOS.getEvent',
+    'DBOS.writeStream',
+    'DBOS.closeStream',
+    'DBOS.readStream',
+    'DBOS.send',
+    'getStatus',
+];
+exports.PROVIDER_NAME = 'dbos';
+exports.WAIT_DEFAULTS = {
+    /** Added to the SLA so Long Tail's expiry reaches the workflow before the recv deadline. */
+    GRACE_SECONDS: 10 * 60,
+    /** recv deadline when the wait has no SLA. */
+    MAX_WAIT_SECONDS: 365 * 24 * 60 * 60,
+    OPEN_ATTEMPTS: 10,
+    REQUEST_TIMEOUT_MS: 15_000,
+};
+exports.LT_PATHS = {
+    OPEN_WAIT: '/api/escalations/waits',
+    CANCEL: (escalationId) => `/api/escalations/${encodeURIComponent(escalationId)}/cancel`,
+};
+exports.STEP_PAGE_SIZE = 500;
+/** Connections the provider keeps for counting workflows in the executions list. */
+exports.COUNT_POOL_SIZE = 2;
+/** Reason sent when the recv deadline passes before Long Tail delivered an outcome. */
+exports.CLOSE_REASON_DEADLINE = 'wait-deadline';

package/build/duration.d.ts

@@ -0,0 +1,2 @@
+/** Milliseconds from '48h', '30m', '10s', '2d', '500ms' or a number of milliseconds. */
+export declare function toMs(value: string | number): number;

package/build/duration.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toMs = toMs;
+const UNIT_MS = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+const DURATION = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/;
+/** Milliseconds from '48h', '30m', '10s', '2d', '500ms' or a number of milliseconds. */
+function toMs(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value <= 0)
+            throw new Error(`duration must be a positive number of milliseconds, got ${value}`);
+        return value;
+    }
+    const match = DURATION.exec(value.trim());
+    if (!match)
+        throw new Error(`duration "${value}" must look like 48h, 30m, 10s, 2d or 500ms`);
+    const ms = Number(match[1]) * UNIT_MS[match[2]];
+    if (ms <= 0)
+        throw new Error(`duration "${value}" must be positive`);
+    return ms;
+}

package/build/index.d.ts

@@ -0,0 +1,6 @@
+export { conditional, waitSeconds } from './conditional';
+export { configureLongTail } from './config';
+export { LongTailRequestError } from './lt-client';
+export { toMs } from './duration';
+export { STEP, WAIT_DEFAULTS } from './constants';
+export type { LTConditionalConfig, LTWaitOutcome, LongTailConnection, OpenedWait } from './types';