@everysk/apps-sdk 0.2.0 → 0.3.0-beta-20261019175049

package/src/api/workflow.ts

@@ -1,285 +1,158 @@
-import { isAxiosError, type AxiosInstance, type AxiosResponse } from "axios";
+import type { AxiosInstance } from "axios";
 
 import type { AnyRecord } from "@/types/anyRecord";
-import type { FilterExpression, QueryObject } from "@/types/entityQuery";
-import type { WorkerExecution, WorkerExecutionListResponse, WorkerExecutionSingleResponse, Workflow, WorkflowExecution, WorkflowExecutionListResponse, WorkflowExecutionSingleResponse, WorkflowListResponse, WorkflowSingleResponse } from "@/types/workflow";
+import { pageParams, request, requireWorkspace } from "./request";
+import type { EntitySingleResponse } from "@/types/entityQuery";
+import type {
+    WorkerExecution,
+    WorkerExecutionListResponse,
+    Workflow,
+    WorkflowExecution,
+    WorkflowExecutionListResponse,
+    WorkflowListResponse,
+} from "@/types/workflow";
 
 const baseUrl = "workflows";
 
-/**
- * Runs a workflow asynchronously.
- *
- * Starts the workflow in a non-blocking way: the response carries a workflow execution
- * with a non-terminal status (e.g. "RUNNING"). Use polling to wait for the terminal state.
- *
- * @param api - Axios instance used to make the HTTP request.
- * @param id - The unique identifier of the workflow to run.
- * @param workspace - The workspace in which the workflow will be executed.
- * @param parameters - Key-value parameters to pass to the workflow.
- * @returns A promise that resolves with the workflow execution response data.
- * @throws {Error} If `workspace` is not provided.
- * @throws {Error} If the request fails.
- */
-export const runWorkflow = async (api: AxiosInstance, id: string, workspace: string, parameters: AnyRecord): Promise<AnyRecord> => {
-  
-  if (!workspace) {
-    throw new Error("Workspace is required to run workflow");
-  } 
-
-  try {
-    const body: AnyRecord = {
-      workspace,
-      parameters,
-    };
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const response: AxiosResponse<any> = await api.post(`${baseUrl}/${id}/run`, body);
-
-    return response.data;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error while running workflow", { cause: error });
-  }
-};
+/** The endpoints' envelopes, private: every function here returns the entity itself. */
+type WorkflowSingleResponse = EntitySingleResponse<"workflow", Workflow>;
+type WorkflowExecutionSingleResponse = EntitySingleResponse<
+    "workflow_execution",
+    WorkflowExecution
+>;
+type WorkerExecutionSingleResponse = EntitySingleResponse<"worker_execution", WorkerExecution>;
 
 /**
- * Run statuses that indicate a workflow execution has reached a terminal state
- * (i.e. it is no longer running and will not change again).
- *
- * Union of the backend's `WORKFLOW_EXECUTION_STATUS_FINISHED` set and the API's documented
- * terminal `run_status` values (`SUCCEEDED`/`FAILED`/`KILLED`). `KILLED` is included so a
- * killed execution is detected as terminal instead of polling until timeout.
+ * What `POST /workflows/:id/run` answers: the execution it started, still `RUNNING`, and a
+ * `result` that is always `null` — the run is asynchronous, and the output is read from the
+ * Ender's worker execution once it finishes. Private: `runWorkflow` returns the execution.
  */
-export const TERMINAL_RUN_STATUSES = ["CANCELED", "COMPLETED", "SUCCEEDED", "FAILED", "KILLED"] as const;
-
-const isTerminalRunStatus = (runStatus: unknown): boolean =>
-  TERMINAL_RUN_STATUSES.includes(String(runStatus ?? "").toUpperCase() as (typeof TERMINAL_RUN_STATUSES)[number]);
-
-const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
-
-export type PollWorkflowExecutionOptions = {
-  /** Delay between status checks, in milliseconds. Defaults to 2000ms. */
-  intervalMs?: number;
-  /** Maximum time to wait for a terminal status before giving up, in milliseconds. Defaults to 5 minutes. */
-  timeoutMs?: number;
-  /** Optional abort signal to cancel polling (e.g. on unmount). */
-  signal?: AbortSignal;
+type RunWorkflowResponse = {
+    workflow_execution: WorkflowExecution;
+    result: null;
 };
 
 /**
- * Polls a workflow execution until it reaches a terminal run status (see {@link TERMINAL_RUN_STATUSES}).
- *
- * This is the interim, non-blocking replacement for synchronous (`synchronous: true`) execution:
- * the workflow is started asynchronously and its status is checked periodically until it completes.
- *
- * @param api - Axios instance used to make the HTTP request.
- * @param workflowId - The unique identifier of the workflow.
- * @param executionId - The unique identifier of the workflow execution to poll.
- * @param workspace - The workspace in which the workflow execution resides.
- * @param options - Polling configuration (interval, timeout, abort signal).
- * @returns A promise that resolves with the terminal {@link WorkflowExecution}.
- * @throws {Error} If `workspace` is not provided.
- * @throws {Error} If polling is aborted via `options.signal`.
- * @throws {Error} If a terminal status is not reached before `options.timeoutMs` elapses.
- */
-export const pollWorkflowExecution = async (
-  api: AxiosInstance,
-  workflowId: string,
-  executionId: string,
-  workspace: string,
-  options: PollWorkflowExecutionOptions = {}
-): Promise<WorkflowExecution> => {
-  if (!workspace) {
-    throw new Error("Workspace is required to poll a workflow execution");
-  }
-
-  const { intervalMs = 2000, timeoutMs = 5 * 60 * 1000, signal } = options;
-  const startedAt = Date.now();
-
-  while (true) {
-    if (signal?.aborted) {
-      throw new Error("Workflow execution polling was aborted");
-    }
-
-    const execution = await getWorkflowExecution(api, workflowId, executionId, workspace);
-
-    if (isTerminalRunStatus(execution.run_status)) {
-      return execution;
-    }
-
-    if (Date.now() - startedAt >= timeoutMs) {
-      throw new Error("Timed out while waiting for the workflow execution to complete");
-    }
-
-    await sleep(intervalMs);
-  }
-};
-
-/**
- * Starts a workflow asynchronously and polls its execution until completion.
+ * Runs a workflow asynchronously.
  *
- * Interim replacement for synchronous execution: instead of holding the request open with
- * `synchronous: true`, the workflow is started in a non-blocking way and its status is polled
- * until it reaches a terminal state, at which point the final execution (with its result) is returned.
+ * Starts the workflow in a non-blocking way: the response carries a workflow execution
+ * with a non-terminal status (e.g. "RUNNING"). `useRunWorkflow` waits for the end over
+ * the websocket.
  *
  * @param api - Axios instance used to make the HTTP request.
  * @param id - The unique identifier of the workflow to run.
  * @param workspace - The workspace in which the workflow will be executed.
  * @param parameters - Key-value parameters to pass to the workflow.
- * @param options - Polling configuration (interval, timeout, abort signal).
- * @returns A promise that resolves with the terminal {@link WorkflowExecution}.
+ * @returns The execution the run started, still `RUNNING`. It used to be the raw body,
+ *   `{ workflow_execution, result: null }`, where every other function returns the entity.
  * @throws {Error} If `workspace` is not provided.
- * @throws {Error} If the run response does not contain a workflow execution id.
- * @throws {Error} If the workflow execution ends in a "FAILED" run status.
- * @throws {Error} If polling times out or is aborted.
+ * @throws {Error} If the request fails.
  */
-const runWorkflowAndPoll = async (
-  api: AxiosInstance,
-  id: string,
-  workspace: string,
-  parameters: AnyRecord,
-  options: PollWorkflowExecutionOptions = {}
+export const runWorkflow = async (
+    api: AxiosInstance,
+    id: string,
+    workspace: string,
+    parameters: AnyRecord,
 ): Promise<WorkflowExecution> => {
-  if (!workspace) {
-    throw new Error("Workspace is required to run workflow");
-  }
-
-  // Start the workflow asynchronously (non-blocking).
-  const startResponse = await runWorkflow(api, id, workspace, parameters);
-  const executionId = (startResponse.workflow_execution as WorkflowExecution | undefined)?.id;
-
-  if (!executionId) {
-    throw new Error("Workflow run did not return an execution id to poll");
-  }
+    requireWorkspace(workspace, "run a workflow");
 
-  // Poll the execution status until it completes, then consume the result.
-  const execution = await pollWorkflowExecution(api, id, executionId, workspace, options);
-
-  if (String(execution.run_status ?? "").toUpperCase() === "FAILED") {
-    throw new Error("Workflow execution failed");
-  }
-
-  return execution;
+    const body = await request(
+        () => api.post<RunWorkflowResponse>(`${baseUrl}/${id}/run`, { workspace, parameters }),
+        "Error running workflow",
+    );
+    return body.workflow_execution;
 };
 
 /**
- * The terminal workflow execution together with the output produced by its final (ender) worker.
+ * The run statuses a workflow execution can end with. The backend writes `RUNNING` when the run
+ * starts, and `SUCCEEDED` or `FAILED` once its Ender finishes; `CANCELED` is reserved for a
+ * cancellation it does not write yet. This list used to carry `KILLED`, which the backend never
+ * writes, and `COMPLETED`, the value of the deprecated `status` field, seen in `run_status` only
+ * on executions from before 2024-10-03.
  */
-export type WorkflowResult = {
-  /** The terminal workflow execution. */
-  execution: WorkflowExecution;
-  /** The ender worker execution, or `null` if the execution did not reference one. */
-  workerExecution: WorkerExecution | null;
-  /** The output data produced by the ender worker (`workerExecution.result`), or `null`. */
-  result: Record<string, unknown> | null;
-};
+export const TERMINAL_RUN_STATUSES = ["SUCCEEDED", "FAILED", "CANCELED"] as const;
+
+export type TerminalRunStatus = (typeof TERMINAL_RUN_STATUSES)[number];
 
 /**
- * Starts a workflow, polls it to completion, then fetches the output produced by its final worker.
- *
- * A workflow execution does not carry the output payload itself — it references the final worker via
- * `ender_worker_execution_id`, and that worker execution's `result` field holds the actual data.
- * This helper performs the full flow: start (async) → poll → fetch ender worker → return its `result`.
- *
- * @param api - Axios instance used to make the HTTP request.
- * @param id - The unique identifier of the workflow to run.
- * @param workspace - The workspace in which the workflow will be executed.
- * @param parameters - Key-value parameters to pass to the workflow.
- * @param options - Polling configuration (interval, timeout, abort signal).
- * @returns A promise that resolves with the {@link WorkflowResult} (execution, ender worker execution, and its result).
- * @throws {Error} If `workspace` is not provided.
- * @throws {Error} If the workflow execution ends in a "FAILED" run status.
- * @throws {Error} If polling times out or is aborted.
+ * The status a run ended with, read whatever its case; `null` while it has not ended. A missing
+ * status — a projection can drop the field, and JSON can carry it as `null` — is a run not known
+ * to have ended. The one place a run's status is read, so a comparison against it is typed.
  */
-export const runWorkflowAndGetResult = async (
-  api: AxiosInstance,
-  id: string,
-  workspace: string,
-  parameters: AnyRecord,
-  options: PollWorkflowExecutionOptions = {}
-): Promise<WorkflowResult> => {
-  const execution = await runWorkflowAndPoll(api, id, workspace, parameters, options);
-
-  const enderWorkerExecutionId = execution.ender_worker_execution_id;
-  if (!enderWorkerExecutionId) {
-    return { execution, workerExecution: null, result: null };
-  }
-
-  const workerExecution = await getWorkerExecution(api, id, enderWorkerExecutionId, workspace);
-
-  return { execution, workerExecution, result: workerExecution.result ?? null };
+export const terminalRunStatusOf = (
+    runStatus: string | null | undefined,
+): TerminalRunStatus | null => {
+    const upper = runStatus?.toUpperCase();
+    return TERMINAL_RUN_STATUSES.find((status) => status === upper) ?? null;
 };
 
+/** Whether a run with this `run_status` has ended; see `terminalRunStatusOf`. */
+export const isTerminalRunStatus = (runStatus: string | null | undefined): boolean =>
+    terminalRunStatusOf(runStatus) !== null;
+
 /**
  * Fetches a single workflow by ID.
  *
  * @param api - Axios instance used to make the HTTP request.
  * @param id - The unique identifier of the workflow to fetch.
  * @param workspace - The workspace in which the workflow resides.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
  * @returns A promise that resolves with the {@link Workflow} object.
  * @throws {Error} If `workspace` is not provided.
  * @throws {Error} If the request fails.
  */
-export const getWorkflow = async (api: AxiosInstance, id: string, workspace: string): Promise<Workflow> => {
-  if (!workspace) {
-    throw new Error("Workspace is required to fetch a workflow");
-  }
-  
-  try {
-    const params: AnyRecord = { workspace };
-    const response: AxiosResponse<WorkflowSingleResponse> = await api.get(`${baseUrl}/${id}`, { params });
-
-    return response.data.workflow;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "Error while fetching workflow", { cause: error });
-    } 
-    if (error instanceof Error) {
-      throw error;
-    }
+export const getWorkflow = async (
+    api: AxiosInstance,
+    id: string,
+    workspace: string,
+    signal?: AbortSignal,
+): Promise<Workflow> => {
+    requireWorkspace(workspace, "fetch a workflow");
+
+    const body = await request(
+        () =>
+            api.get<WorkflowSingleResponse>(`${baseUrl}/${id}`, { params: { workspace }, signal }),
+        "Error fetching workflow",
+    );
+    return body.workflow;
+};
 
-    throw new Error("Error while fetching workflow", { cause: error });
-  }
+/** What `listWorkflows` sends. */
+export type WorkflowListParams = {
+    /** Required: without one the API lists `main` rather than failing, and refuses a sub-user. */
+    workspace: string;
+    /** A name prefix, an id, `#tag #tag` (every tag), or `&link_uid`. Sent as `query`. */
+    search?: string;
+    pageSize?: number;
+    pageToken?: string;
 };
 
 /**
- * Fetches a paginated list of workflows using the legacy method (workspace as query param).
+ * Lists the workflows of a workspace, a page at a time.
+ *
+ * The endpoint takes a text search rather than the JSON query the other lists take, so this
+ * takes `search` rather than a `QueryObject`.
  *
  * @param api - Axios instance used to make the HTTP request.
- * @param workspace - Current workspace name. Sent as a query param via the legacy method, required by some API configurations.
- * @param pageSize - Number of items per page.
- * @param pageToken - Cursor token for the next page.
- * @returns A promise that resolves with a {@link WorkflowListResponse} containing the matched workflows.
+ * @param params - Workspace, search and paging.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
+ * @returns A page of workflows, with the cursor to the next one.
+ * @throws {Error} If `workspace` is empty.
  * @throws {Error} If the request fails.
  */
-export const listWorkflows = async (api: AxiosInstance, workspace?: string, pageSize?: number, pageToken?: string): Promise<WorkflowListResponse> => {
-  const params: AnyRecord = {};
-
-  if (workspace) params.workspace = workspace;
-  if (pageSize) params.page_size = pageSize;
-  if (pageToken) params.page_token = pageToken;
-
-  try {
-    const response: AxiosResponse<WorkflowListResponse> = await api.get(baseUrl, { params });
-    return response.data;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "Error listing workflows", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error listing workflows", { cause: error });
-  }
+export const listWorkflows = async (
+    api: AxiosInstance,
+    { workspace, search, pageSize, pageToken }: WorkflowListParams,
+    signal?: AbortSignal,
+): Promise<WorkflowListResponse> => {
+    requireWorkspace(workspace, "list workflows");
+
+    const params = pageParams({ workspace, search, pageSize, pageToken });
+
+    return request(
+        () => api.get<WorkflowListResponse>(baseUrl, { params, signal }),
+        "Error listing workflows",
+    );
 };
 
 /**
@@ -287,70 +160,83 @@ export const listWorkflows = async (api: AxiosInstance, workspace?: string, page
  *
  * @param api - Axios instance used to make the HTTP request.
  * @param workflowId - The unique identifier of the workflow.
- * @param executionId - The unique identifier of the workflow execution to fetch.
+ * @param workflowExecutionId - The unique identifier of the workflow execution to fetch.
  * @param workspace - The workspace in which the workflow execution resides.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
  * @returns A promise that resolves with the {@link WorkflowExecution} object.
  * @throws {Error} If `workspace` is not provided.
  * @throws {Error} If the request fails.
  */
-export const getWorkflowExecution = async (api: AxiosInstance, workflowId: string, executionId: string, workspace: string): Promise<WorkflowExecution> => {
-  if (!workspace) {
-    throw new Error("Workspace is required to fetch a workflow execution");
-  }
-
-  try {
-    const params: AnyRecord = { workspace, workflow_execution_id: executionId };
-    const response: AxiosResponse<WorkflowExecutionSingleResponse> = await api.get(`${baseUrl}/${workflowId}/workflow_executions`, { params });
-    return response.data.workflow_execution;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "Error fetching workflow execution", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
+export const getWorkflowExecution = async (
+    api: AxiosInstance,
+    workflowId: string,
+    workflowExecutionId: string,
+    workspace: string,
+    signal?: AbortSignal,
+): Promise<WorkflowExecution> => {
+    requireWorkspace(workspace, "fetch a workflow execution");
+
+    const params: AnyRecord = { workspace, workflow_execution_id: workflowExecutionId };
+    const body = await request(
+        () =>
+            api.get<WorkflowExecutionSingleResponse>(
+                `${baseUrl}/${workflowId}/workflow_executions`,
+                { params, signal },
+            ),
+        "Error fetching workflow execution",
+    );
+    return body.workflow_execution;
+};
 
-    throw new Error("Error fetching workflow execution", { cause: error });
-  }
+/** What `listWorkflowExecutions` sends: the parameters the endpoint reads, each from the URL. */
+export type WorkflowExecutionListParams = {
+    /** Not used to filter: the endpoint lists the workflow's executions. A sub-user's role check needs it. */
+    workspace: string;
+    pageSize?: number;
+    pageToken?: string;
+    /** Only the executions this worker took part in. */
+    workerId?: string;
+    /** Include each execution's `resume`, the per-worker summary. The API leaves it out by default. */
+    withResume?: boolean;
 };
 
 /**
- * Fetches a paginated list of workflow executions matching the given query.
+ * Lists the executions of one workflow, newest first, a page at a time.
+ *
+ * Everything goes in the URL. The endpoint reads `page_size`, `page_token`, `worker_id` and
+ * `with_resume` from there and ignores a JSON `query`, which is what this function used to send:
+ * the page size had no effect and every "next page" came back as the first one.
  *
  * @param api - Axios instance used to make the HTTP request.
- * @param workflowId - The unique identifier of the workflow whose executions to list.
- * @param query - Query object containing filters, pagination, and sorting options.
- *   Must include a `workspace` filter expression.
- * @returns A promise that resolves with a {@link WorkflowExecutionListResponse} containing the matched executions.
- * @throws {Error} If the `workspace` filter is not present in `query.filters`.
+ * @param workflowId - The workflow whose executions to list.
+ * @param params - Workspace, paging, and the endpoint's two filters.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the list hooks pass the query's own.
+ * @returns A page of executions, with the cursor to the next one.
+ * @throws {Error} If `workspace` is empty.
  * @throws {Error} If the request fails.
  */
-export const listWorkflowExecutions = async (api: AxiosInstance, workflowId: string, query: QueryObject): Promise<WorkflowExecutionListResponse> => {
-  const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === "workspace");
-  const workspace = workspaceFilter?.[workspaceFilter.length - 1];
-
-  if (!workspace) throw new Error("Workspace filter is required to list workflows");
-
-  try {
-    const params: AnyRecord = {
-      workspace,
-      ...(query ? { query: JSON.stringify(query) } : {}),
+export const listWorkflowExecutions = async (
+    api: AxiosInstance,
+    workflowId: string,
+    { workspace, pageSize, pageToken, workerId, withResume }: WorkflowExecutionListParams,
+    signal?: AbortSignal,
+): Promise<WorkflowExecutionListResponse> => {
+    requireWorkspace(workspace, "list workflow executions");
+
+    const params = {
+        ...pageParams({ workspace, pageSize, pageToken }),
+        ...(workerId ? { worker_id: workerId } : {}),
+        ...(withResume !== undefined ? { with_resume: withResume } : {}),
     };
 
-    const response: AxiosResponse<WorkflowExecutionListResponse> = await api.get(`${baseUrl}/${workflowId}/workflow_executions`, { params });
-    return response.data;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "Error listing workflow executions", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error listing workflow executions", { cause: error });
-  }
+    return request(
+        () =>
+            api.get<WorkflowExecutionListResponse>(`${baseUrl}/${workflowId}/workflow_executions`, {
+                params,
+                signal,
+            }),
+        "Error listing workflow executions",
+    );
 };
 
 /**
@@ -360,68 +246,80 @@ export const listWorkflowExecutions = async (api: AxiosInstance, workflowId: str
  * @param workflowId - The unique identifier of the parent workflow.
  * @param workerExecutionId - The unique identifier of the worker execution to fetch.
  * @param workspace - The workspace in which the worker execution resides.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the entity hooks pass the query's own.
  * @returns A promise that resolves with the {@link WorkerExecution} object.
  * @throws {Error} If `workspace` is not provided.
  * @throws {Error} If the request fails.
  */
-export const getWorkerExecution = async (api: AxiosInstance, workflowId: string, workerExecutionId: string, workspace: string): Promise<WorkerExecution> => {
-  if (!workspace) {
-    throw new Error("Workspace is required to fetch a worker execution");
-  }
+export const getWorkerExecution = async (
+    api: AxiosInstance,
+    workflowId: string,
+    workerExecutionId: string,
+    workspace: string,
+    signal?: AbortSignal,
+): Promise<WorkerExecution> => {
+    requireWorkspace(workspace, "fetch a worker execution");
 
-  try {
-    const params: AnyRecord = { workspace, worker_execution_id: workerExecutionId, with_result: true };
-    const response: AxiosResponse<WorkerExecutionSingleResponse> = await api.get(`${baseUrl}/${workflowId}/worker_executions`, { params });
-    return response.data.worker_execution;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "Error fetching worker execution", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
+    const params: AnyRecord = {
+        workspace,
+        worker_execution_id: workerExecutionId,
+        with_result: true,
+    };
+    const body = await request(
+        () =>
+            api.get<WorkerExecutionSingleResponse>(`${baseUrl}/${workflowId}/worker_executions`, {
+                params,
+                signal,
+            }),
+        "Error fetching worker execution",
+    );
+    return body.worker_execution;
+};
 
-    throw new Error("Error fetching worker execution", { cause: error });
-  }
-}
+/** What `listWorkerExecutions` sends besides the execution id. */
+export type WorkerExecutionListParams = {
+    /** Not used to filter. A sub-user's role check needs it. */
+    workspace: string;
+    /** Include each run's `result` and `input_params`. The API leaves them out by default. */
+    withResult?: boolean;
+};
 
 /**
- * Fetches a paginated list of worker executions for a given workflow.
+ * Lists every worker execution of one workflow execution, grouped by worker.
+ *
+ * The endpoint returns them all at once: it is not paginated and takes no query. Each group is
+ * one worker, with its run as `execution`, or every parallel run as `executions`.
  *
  * @param api - Axios instance used to make the HTTP request.
- * @param workflowId - The unique identifier of the parent workflow.
- * @param workflowExecutionId - The unique identifier of the workflow execution to filter by.
- * @param query - Query object containing filters, pagination, and sorting options.
- *   Must include a `workspace` filter expression.
- * @returns A promise that resolves with a {@link WorkerExecutionListResponse} containing the matched worker executions.
- * @throws {Error} If the `workspace` filter is not present in `query.filters`.
+ * @param workflowId - The parent workflow.
+ * @param workflowExecutionId - The workflow execution whose workers to list.
+ * @param params - Workspace, and whether to include results.
+ * @param {AbortSignal} [signal] - Aborts the request itself; the hooks pass the query's own.
+ * @returns The groups, and the highest parallel index among them.
+ * @throws {Error} If `workspace` is empty.
  * @throws {Error} If the request fails.
  */
-export const listWorkerExecutions = async (api: AxiosInstance, workflowId: string, workflowExecutionId: string, query: QueryObject): Promise<WorkerExecutionListResponse> => {
-  const workspaceFilter = query.filters.find((filter: FilterExpression) => filter[0] === "workspace");
-  const workspace = workspaceFilter?.[workspaceFilter.length - 1];
-
-  if (!workspace) throw new Error("Workspace filter is required to list worker executions");
-
-  try {
-    const params: AnyRecord = {
-      workspace,
-      workflow_execution_id: workflowExecutionId,
-      ...(query ? { query: JSON.stringify(query) } : {}),
+export const listWorkerExecutions = async (
+    api: AxiosInstance,
+    workflowId: string,
+    workflowExecutionId: string,
+    { workspace, withResult }: WorkerExecutionListParams,
+    signal?: AbortSignal,
+): Promise<WorkerExecutionListResponse> => {
+    requireWorkspace(workspace, "list worker executions");
+
+    const params = {
+        workspace,
+        workflow_execution_id: workflowExecutionId,
+        ...(withResult !== undefined ? { with_result: withResult } : {}),
     };
 
-    const response: AxiosResponse<WorkerExecutionListResponse> = await api.get(`${baseUrl}/${workflowId}/worker_executions`, { params });
-    return response.data;
-  } catch (error: unknown) {
-    if (isAxiosError<AnyRecord>(error)) {
-      throw new Error(error.message || "Error listing worker executions", { cause: error });
-    }
-
-    if (error instanceof Error) {
-      throw error;
-    }
-
-    throw new Error("Error listing worker executions", { cause: error });
-  }
-};
+    return request(
+        () =>
+            api.get<WorkerExecutionListResponse>(`${baseUrl}/${workflowId}/worker_executions`, {
+                params,
+                signal,
+            }),
+        "Error listing worker executions",
+    );
+};