Skip to content

feat(cli): add durable workflow and executor waiters #1338

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dqn wants to merge 7 commits into
base: main
Choose a base branch
from
Open

feat(cli): add durable workflow and executor waiters #1338

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
56f28d6
feat(cli): add workflow and executor waiters
dqn Jun 5, 2026
2331b54
docs(cli): add waiter automation examples
dqn Jun 5, 2026
5f4769b
fix(cli): preserve executor workflow wait status
dqn Jun 5, 2026
9869274
fix(cli): retain workflow execution wait diagnostics
dqn Jun 5, 2026
b4e1c93
test(cli): allow workflow wait in readonly guard
dqn Jun 5, 2026
42f5eb9
Merge remote-tracking branch 'origin/main' into feat/workflow-executo…
dqn Jun 5, 2026
0b8ef93
Merge remote-tracking branch 'origin/main' into feat/workflow-executo…
dqn Jun 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/workflow-executor-waiters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@tailor-platform/sdk": minor
---

Add durable workflow and executor waiters with timeout, retry, and JSON diagnostics.
2 changes: 1 addition & 1 deletion packages/sdk/CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@


- [#1491](https://github.com/tailor-platform/sdk/pull/1491) [`be30383`](https://github.com/tailor-platform/sdk/commit/be30383e368b01f81f7e019fc509c9b61a33eb37) Thanks [@toiroakr](https://github.com/toiroakr)! - chore(deps): upgrade typescript to 6.0.3

Upgrade the workspace dev/build toolchain to TypeScript 6.0.3. Dev-dependency
change only — no public API or runtime behavior change.

Expand Down
1 change: 1 addition & 0 deletions packages/sdk/docs/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,6 +223,7 @@ Commands for managing workflows and executions.
| [workflow list](./cli/workflow.md#workflow-list) | List all workflows in the workspace. |
| [workflow get](./cli/workflow.md#workflow-get) | Get workflow details. |
| [workflow start](./cli/workflow.md#workflow-start) | Start a workflow execution. |
| [workflow wait](./cli/workflow.md#workflow-wait) | Wait for a workflow execution. |
| [workflow executions](./cli/workflow.md#workflow-executions) | List or get workflow executions. |
| [workflow resume](./cli/workflow.md#workflow-resume) | Resume a failed or pending workflow execution. |

Expand Down
53 changes: 53 additions & 0 deletions packages/sdk/docs/cli/executor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,6 +179,7 @@ tailor-sdk executor jobs [options] <executor-name> [job-id]
| `--attempts` | - | Show job attempts (only with job ID) (detail mode only) | No | `false` | - |
| `--wait` | `-W` | Wait for job completion and downstream execution (workflow/function) if applicable (detail mode only) | No | `false` | - |
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait when using --wait (e.g., '30s', '5m') | No | `"5m"` | - |
| `--order <ORDER>` | - | Sort order (asc or desc) | No | `"desc"` | - |
| `--limit <LIMIT>` | - | Maximum number of jobs to list (0: unlimited, default: 50) (list mode only) | No | `50` | - |
| `--logs` | `-l` | Display function execution logs after completion (requires --wait) | No | `false` | - |
Expand Down Expand Up @@ -283,6 +284,7 @@ tailor-sdk executor trigger [options] <executor-name>
| `--header <HEADER>` | `-H` | Request header (format: 'Key: Value', can be specified multiple times) | No | - | - |
| `--wait` | `-W` | Wait for job completion and downstream execution (workflow/function) if applicable | No | `false` | - |
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait when using --wait (e.g., '30s', '5m') | No | `"5m"` | - |
| `--logs` | `-l` | Display function execution logs after completion (requires --wait) | No | `false` | - |

<!-- politty:command:executor trigger:options:end -->
Expand Down Expand Up @@ -323,6 +325,57 @@ $ tailor-sdk executor trigger my-executor -W -l

<!-- politty:command:executor trigger:examples:end -->

**Shell automation**

Trigger an executor and wait for the executor job plus any downstream workflow or
function execution:

```bash
tailor-sdk executor trigger daily-workflow \
--wait \
--timeout 5m \
--interval 5s \
--json
```

Wait for an existing job when another process already captured the job ID:

```bash
tailor-sdk executor jobs daily-workflow "$job_id" \
--wait \
--timeout 5m \
--logs \
--json
```

**Programmatic API**

Import your executor definition and pass it to the typed API:

```ts
import { triggerExecutor, watchExecutorJob } from "@tailor-platform/sdk/cli";
import dailyWorkflow from "../executors/dailyWorkflow";

const { jobId } = await triggerExecutor({
executor: dailyWorkflow,
});

if (!jobId) {
throw new Error("Executor trigger did not return a job ID");
}

const result = await watchExecutorJob({
executor: dailyWorkflow,
jobId,
timeout: 5 * 60 * 1000,
interval: 5000,
});

if (result.timedOut) {
throw new Error(`Executor job ${result.job.id} timed out at ${result.job.status}`);
}
```

<!-- politty:command:executor trigger:notes:start -->

**Notes**
Expand Down
177 changes: 157 additions & 20 deletions packages/sdk/docs/cli/workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ tailor-sdk workflow [command]
| [`workflow list`](#workflow-list) | List all workflows in the workspace. |
| [`workflow get`](#workflow-get) | Get workflow details. |
| [`workflow start`](#workflow-start) | Start a workflow execution. |
| [`workflow wait`](#workflow-wait) | Wait for a workflow execution. |
| [`workflow executions`](#workflow-executions) | List or get workflow executions. |
| [`workflow resume`](#workflow-resume) | Resume a failed or pending workflow execution. |

Expand Down Expand Up @@ -175,8 +176,10 @@ tailor-sdk workflow start [options] <name>
| `--machine-user <MACHINE_USER>` | `-m` | Machine user name. Falls back to the active profile's default machine user. | No | - | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
| `--arg <ARG>` | `-a` | Workflow argument (JSON string) | No | - | - |
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--logs` | `-l` | Display job execution logs after completion (requires --wait) | No | `false` | - |
| `--interval <INTERVAL>` | `-i` | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait (e.g., '30s', '10m') | No | `"10m"` | - |
| `--until <UNTIL>` | `-u` | Wait target (success, suspended, terminal) | No | `"terminal"` | - |
| `--logs` | `-l` | Display job execution logs after completion | No | `false` | - |

<!-- politty:command:workflow start:options:end -->

Expand All @@ -185,6 +188,136 @@ tailor-sdk workflow start [options] <name>
See [Global Options](../cli-reference.md#global-options) for options available to all commands.

<!-- politty:command:workflow start:global-options-link:end -->
<!-- politty:command:workflow wait:heading:start -->

### workflow wait

<!-- politty:command:workflow wait:heading:end -->

<!-- politty:command:workflow wait:description:start -->

Wait for a workflow execution.

<!-- politty:command:workflow wait:description:end -->

<!-- politty:command:workflow wait:usage:start -->

**Usage**

```
tailor-sdk workflow wait [options] <execution-id>
```

<!-- politty:command:workflow wait:usage:end -->

<!-- politty:command:workflow wait:arguments:start -->

**Arguments**

| Argument | Description | Required |
| -------------- | ------------ | -------- |
| `execution-id` | Execution ID | Yes |

<!-- politty:command:workflow wait:arguments:end -->

<!-- politty:command:workflow wait:options:start -->

**Options**

| Option | Alias | Description | Required | Default | Env |
| ------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
| `--interval <INTERVAL>` | `-i` | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait (e.g., '30s', '10m') | No | `"10m"` | - |
| `--until <UNTIL>` | `-u` | Wait target (success, suspended, terminal) | No | `"terminal"` | - |
| `--logs` | `-l` | Display job execution logs after completion | No | `false` | - |

<!-- politty:command:workflow wait:options:end -->

<!-- politty:command:workflow wait:global-options-link:start -->

See [Global Options](../cli-reference.md#global-options) for options available to all commands.

<!-- politty:command:workflow wait:global-options-link:end -->

<!-- politty:command:workflow wait:examples:start -->

**Examples**

**Wait for workflow success**

```bash
$ tailor-sdk workflow wait execution-id --until success --timeout 10m --json
```

**Wait for a workflow wait point**

```bash
$ tailor-sdk workflow wait execution-id --until suspended --timeout 6m --logs --json
```

**Wait for success, failure, or suspension**

```bash
$ tailor-sdk workflow wait execution-id --until terminal
```

<!-- politty:command:workflow wait:examples:end -->

**Shell automation**

Capture the execution ID from `workflow start` and wait for the same run from a
separate command:

```bash
execution_id="$(
tailor-sdk workflow start order-workflow --json | jq -r '.executionId'
)"

tailor-sdk workflow wait "$execution_id" \
--until success \
--timeout 10m \
--interval 5s \
--json
```

Wait until a workflow reaches a wait point, such as an approval step:

```bash
tailor-sdk workflow wait "$execution_id" \
--until suspended \
--timeout 6m \
--logs \
--json
```

**Programmatic API**

Use `waitWorkflowExecution` when a script already has an execution ID and needs
the same waiter behavior as the CLI:

```ts
import { waitWorkflowExecution } from "@tailor-platform/sdk/cli";

const executionId = process.env.EXECUTION_ID;

if (!executionId) {
throw new Error("EXECUTION_ID is required");
}

const result = await waitWorkflowExecution({
executionId,
until: "success",
timeout: 10 * 60 * 1000,
interval: 5000,
});

if (result.timedOut) {
throw new Error(`Workflow ${result.id} timed out at ${result.status}`);
}
```

<!-- politty:command:workflow executions:heading:start -->

### workflow executions
Expand Down Expand Up @@ -221,17 +354,19 @@ tailor-sdk workflow executions [options] [execution-id]

**Options**

| Option | Alias | Description | Required | Default | Env |
| --------------------------------- | ----- | -------------------------------------------------------------- | -------- | -------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
| `--order <ORDER>` | - | Sort order (asc or desc) | No | `"desc"` | - |
| `--limit <LIMIT>` | `-l` | Maximum number of items to return (0: unlimited) | No | `50` | - |
| `--workflow-name <WORKFLOW_NAME>` | `-n` | Filter by workflow name (list mode only) | No | - | - |
| `--status <STATUS>` | `-s` | Filter by status (list mode only) | No | - | - |
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--logs` | - | Display job execution logs (detail mode only) | No | `false` | - |
| Option | Alias | Description | Required | Default | Env |
| --------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
| `--order <ORDER>` | - | Sort order (asc or desc) | No | `"desc"` | - |
| `--limit <LIMIT>` | `-l` | Maximum number of items to return (0: unlimited) | No | `50` | - |
| `--workflow-name <WORKFLOW_NAME>` | `-n` | Filter by workflow name (list mode only) | No | - | - |
| `--status <STATUS>` | `-s` | Filter by status (list mode only) | No | - | - |
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
| `--interval <INTERVAL>` | `-i` | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait (e.g., '30s', '10m') | No | `"10m"` | - |
| `--until <UNTIL>` | `-u` | Wait target (success, suspended, terminal) | No | `"terminal"` | - |
| `--logs` | - | Display job execution logs (detail mode only) | No | `false` | - |

<!-- politty:command:workflow executions:options:end -->

Expand Down Expand Up @@ -276,13 +411,15 @@ tailor-sdk workflow resume [options] <execution-id>

**Options**

| Option | Alias | Description | Required | Default | Env |
| ------------------------------- | ----- | -------------------------------------------------------------- | -------- | ------- | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
| `--interval <INTERVAL>` | `-i` | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--logs` | `-l` | Display job execution logs after completion (requires --wait) | No | `false` | - |
| Option | Alias | Description | Required | Default | Env |
| ------------------------------- | ----- | --------------------------------------------------------- | -------- | ------------ | ------------------------------ |
| `--workspace-id <WORKSPACE_ID>` | `-w` | Workspace ID | No | - | `TAILOR_PLATFORM_WORKSPACE_ID` |
| `--profile <PROFILE>` | `-p` | Workspace profile | No | - | `TAILOR_PLATFORM_PROFILE` |
| `--wait` | `-W` | Wait for execution to complete | No | `false` | - |
| `--interval <INTERVAL>` | `-i` | Polling interval when waiting (e.g., '3s', '500ms', '1m') | No | `"3s"` | - |
| `--timeout <TIMEOUT>` | `-t` | Maximum time to wait (e.g., '30s', '10m') | No | `"10m"` | - |
| `--until <UNTIL>` | `-u` | Wait target (success, suspended, terminal) | No | `"terminal"` | - |
| `--logs` | `-l` | Display job execution logs after completion | No | `false` | - |

<!-- politty:command:workflow resume:options:end -->

Expand Down
Loading
Loading