unfazed 0.5.0 → 0.6.1

package/dist/remote/world.js

@@ -0,0 +1,628 @@
+import { ENDPOINT_ENV_VAR, TOKEN_ENV_VAR, UnfazedClient, VERSION } from "../client.js";
+import { LOGIN_COMMAND } from "../credentials.js";
+import { UnfazedAuthError, UnfazedGraphQLError, UnfazedHTTPError, UnfazedInspectError } from "../errors.js";
+import { APP_ENV_VAR, currentDirectory, resolveAlias } from "./app.js";
+import * as docs from "./documents.js";
+import { chunkValue, EVENT_PAYLOAD_FIELDS, eventData, frame, serializedValue, structuredError, toDate, } from "./values.js";
+/**
+ * `SPEC_VERSION_CURRENT` of the `@workflow/world` this backend was written
+ * against (a test keeps the two equal). Informational: this World creates
+ * and replays nothing.
+ */
+export const REMOTE_SPEC_VERSION = 8;
+/** A run page is reused for this long, so one CLI or web UI view costs one relay. */
+const RUN_PAGE_TTL_MS = 2_000;
+/** Active runs searched for a hook that no run page read so far named. */
+const HOOK_SCAN_RUNS = 20;
+/** Pages of 200 steps read to serve `steps.list` newest first (the API lists oldest first). */
+const STEP_PAGES_MAX = 10;
+const STREAM_PAGE = 50;
+const STREAM_POLL_MIN_MS = 1_000;
+const CONCURRENCY = 4;
+/** A wake-up's own re-enqueue happens inside the app; the SDK's follow-up `queue()` within this window is a no-op. */
+const WAKE_QUEUE_WINDOW_MS = 60_000;
+/** Hook tokens never leave the app (contract: hooks are shown by ID, kind and state). */
+const REDACTED = "[redacted]";
+/**
+ * Creates the CLI backend's World for one app. Throws when there is no token
+ * or no app to read, saying what to set.
+ */
+export function createRemoteWorld(options = {}) {
+    const env = options.env ?? globalThis.process?.env ?? {};
+    const endpointEnv = env[ENDPOINT_ENV_VAR];
+    let client;
+    try {
+        // The token is `token`, else UNFZ_API_TOKEN, else the stored login of
+        // `npx unfazed login` (refreshed as it expires), all read from `env`.
+        client = new UnfazedClient({
+            ...(options.token ? { token: options.token } : {}),
+            env,
+            endpoint: options.endpoint ?? (endpointEnv ? normalizeEndpoint(endpointEnv) : undefined),
+            timeoutMs: options.timeoutMs ?? 60_000,
+            userAgent: `unfazed-sdk/${VERSION} (workflow-cli-backend)`,
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+        });
+    }
+    catch (error) {
+        if (!(error instanceof UnfazedAuthError))
+            throw error;
+        const inApp = env["UNFZ_STATE_URL"]
+            ? ' Inside an unfazed app the World is unfazed/workflow (its Nitro module, or setWorld(createWorld()) from "unfazed/workflow"); ' +
+                "WORKFLOW_TARGET_WORLD=unfazed selects this read-only CLI backend instead."
+            : "";
+        // A login for another control plane says which command fixes it; keep that.
+        const message = error.message.includes("the stored login is for")
+            ? error.message
+            : `unfazed: not signed in. Run \`${LOGIN_COMMAND}\` to inspect your apps' workflow runs with your own account, ` +
+                `or set ${TOKEN_ENV_VAR} (a token with the unfz:read scope; unfz:deploy too for cancel and wake; ` +
+                `an agent gets one at https://unfazed.dev/auth.md).`;
+        throw new UnfazedAuthError(message + inApp, { cause: error });
+    }
+    const alias = resolveAlias({ alias: options.alias, env, cwd: options.cwd ?? currentDirectory() });
+    const authSource = client.authSource;
+    const pollMaxMs = Math.max(1, options.streamPollMs ?? 5_000);
+    const pollMinMs = Math.min(STREAM_POLL_MIN_MS, pollMaxMs);
+    let closed = false;
+    /** Pending waits of stream readers; `close()` ends them so no timer outlives the World. */
+    const sleepers = new Set();
+    const sleep = (ms) => new Promise((resolve) => {
+        const wake = () => {
+            clearTimeout(timer);
+            sleepers.delete(wake);
+            resolve();
+        };
+        const timer = setTimeout(wake, ms);
+        sleepers.add(wake);
+    });
+    // ---- Transport and errors ----
+    async function call(document, variables, runId) {
+        try {
+            return await client.request(document, variables);
+        }
+        catch (error) {
+            throw translate(error, alias, runId, authSource);
+        }
+    }
+    // ---- Run pages: one relay serves runs.get, hooks, streams.list ----
+    const runPages = new Map();
+    /** hookId → runId, from every run page read: how `hooks.get(hookId)` finds the run. */
+    const hookRuns = new Map();
+    function runPage(runId) {
+        const cached = runPages.get(runId);
+        if (cached && cached.expires > Date.now())
+            return cached.page;
+        // Never expires while in flight (a relay may wait out a cold start); reused for a moment after.
+        const entry = { expires: Number.POSITIVE_INFINITY };
+        entry.page = call(docs.RUN, { alias, runID: runId }, runId).then(({ workflowRun }) => {
+            for (const hook of workflowRun.hooks)
+                hookRuns.set(hook.hookID, runId);
+            entry.expires = Date.now() + RUN_PAGE_TTL_MS;
+            return workflowRun;
+        }, (error) => {
+            if (runPages.get(runId) === entry)
+                runPages.delete(runId);
+            throw error;
+        });
+        runPages.set(runId, entry);
+        return entry.page;
+    }
+    // ---- Records in the World's shapes ----
+    function runRecord(run, page, withData = false) {
+        const record = {
+            runId: run.runID,
+            status: run.status.toLowerCase(),
+            deploymentId: run.deploymentID,
+            workflowName: run.workflowName,
+            attributes: Object.fromEntries(run.attributes.map(({ key, value }) => [key, value])),
+            createdAt: toDate(run.createdAt),
+            updatedAt: toDate(run.updatedAt),
+        };
+        setDate(record, "startedAt", run.startedAt);
+        setDate(record, "completedAt", run.completedAt);
+        setDate(record, "expiredAt", run.expiredAt);
+        if (run.errorCode !== null)
+            record.errorCode = run.errorCode;
+        if (page && withData) {
+            setDefined(record, "input", serializedValue(page.input));
+            setDefined(record, "output", serializedValue(page.output));
+        }
+        if (page?.error)
+            record.error = structuredError(page.error);
+        return record;
+    }
+    function stepRecord(runId, step, detail, withData = false) {
+        const record = {
+            runId,
+            stepId: step.stepID,
+            stepName: step.stepName,
+            status: step.status,
+            attempt: step.attempt,
+            createdAt: toDate(step.createdAt),
+            updatedAt: toDate(step.updatedAt),
+        };
+        setDate(record, "startedAt", step.startedAt);
+        setDate(record, "completedAt", step.completedAt);
+        setDate(record, "retryAfter", step.retryAfter);
+        if (detail && withData) {
+            setDefined(record, "input", serializedValue(detail.input));
+            setDefined(record, "output", serializedValue(detail.output));
+        }
+        if (detail?.error)
+            record.error = structuredError(detail.error);
+        return record;
+    }
+    function eventRecord(runId, event, data) {
+        const record = {
+            runId,
+            eventId: event.eventID,
+            eventType: event.eventType,
+            createdAt: toDate(event.createdAt),
+            eventData: eventData(event.info),
+        };
+        if (event.correlationID !== null)
+            record.correlationId = event.correlationID;
+        const field = EVENT_PAYLOAD_FIELDS[event.eventType];
+        if (field && data)
+            record.eventData[field] = serializedValue(data);
+        return record;
+    }
+    function hookRecord(runId, hook) {
+        const record = {
+            runId,
+            hookId: hook.hookID,
+            token: REDACTED,
+            ownerId: "",
+            projectId: alias,
+            environment: "production",
+            createdAt: toDate(hook.createdAt),
+            isWebhook: hook.kind === "webhook",
+            isSystem: hook.kind === "system",
+            // What the inspection API adds: the hook's state from its run's events.
+            status: hook.status,
+            receivedCount: hook.receivedCount,
+        };
+        setDate(record, "lastReceivedAt", hook.lastReceivedAt);
+        setDate(record, "disposedAt", hook.disposedAt);
+        return record;
+    }
+    // ---- Lists ----
+    async function allSteps(runId) {
+        const steps = [];
+        let cursor = null;
+        for (let page = 0; page < STEP_PAGES_MAX; page++) {
+            const { workflowSteps } = await call(docs.STEPS, { alias, runID: runId, limit: 200, cursor }, runId);
+            steps.push(...workflowSteps.steps);
+            if (!workflowSteps.hasMore || !workflowSteps.nextCursor)
+                break;
+            cursor = workflowSteps.nextCursor;
+        }
+        return steps;
+    }
+    async function activeRuns(limit, cursor) {
+        const { workflowRuns } = await call(docs.RUNS, {
+            alias,
+            status: ["RUNNING", "PENDING"],
+            limit,
+            cursor,
+        });
+        const pages = await mapLimit(workflowRuns.runs, CONCURRENCY, (run) => runPage(run.runID));
+        return { pages, nextCursor: workflowRuns.nextCursor, hasMore: workflowRuns.hasMore };
+    }
+    function hooksOf(page, onlyActive) {
+        return page.hooks
+            .filter((hook) => !onlyActive || hook.status === "active")
+            .map((hook) => hookRecord(page.run.runID, hook));
+    }
+    // ---- Writes the inspection API offers ----
+    /** Runs woken through this World, for the SDK's follow-up `queue()` (see {@link WAKE_QUEUE_WINDOW_MS}). */
+    const woken = new Map();
+    /**
+     * Cancels a run; resolves `"already_cancelled"` for a run cancelled before,
+     * which, as in the upstream Worlds, is not an error. A run that completed or
+     * failed is refused with the platform's "run … already ended (…)".
+     */
+    async function cancel(runId, reason) {
+        try {
+            await call(docs.CANCEL, 
+            // The platform takes at most 512 characters (code points); cut on a character boundary.
+            { input: { alias, runID: runId, ...(reason !== undefined ? { reason: Array.from(reason).slice(0, 512).join("") } : {}) } }, runId);
+            return "cancelled";
+        }
+        catch (error) {
+            if (endedAs(error) === "cancelled")
+                return "already_cancelled";
+            throw error;
+        }
+        finally {
+            runPages.delete(runId);
+        }
+    }
+    // ---- The World ----
+    const world = {
+        alias,
+        specVersion: REMOTE_SPEC_VERSION,
+        capabilities: {},
+        runs: {
+            async get(id, params) {
+                const page = await runPage(id);
+                return runRecord(page.run, page, params?.resolveData !== "none");
+            },
+            async list(params = {}) {
+                if ((params.pagination?.sortOrder ?? "desc") !== "desc") {
+                    throw invalidArgument("runs.list", "sortOrder", "the unfazed backend lists runs newest first only; drop --sort asc");
+                }
+                const status = params.status === undefined
+                    ? null
+                    : (Array.isArray(params.status) ? params.status : [params.status]).map((s) => s.toUpperCase());
+                const { workflowRuns } = await call(docs.RUNS, {
+                    alias,
+                    status,
+                    workflowName: params.workflowName ?? null,
+                    limit: clamp(params.pagination?.limit ?? 20, 1, 100),
+                    cursor: params.pagination?.cursor || null,
+                });
+                return {
+                    data: workflowRuns.runs.map((run) => runRecord(run)),
+                    cursor: workflowRuns.hasMore ? workflowRuns.nextCursor : null,
+                    hasMore: workflowRuns.hasMore,
+                };
+            },
+            async cancelMany(request) {
+                const results = await mapLimit(request.runIds, CONCURRENCY, async (runId) => {
+                    try {
+                        return { runId, outcome: await cancel(runId, request.cancelReason) };
+                    }
+                    catch (error) {
+                        if (error instanceof UnfazedInspectError && (error.status === 401 || error.status === 403))
+                            throw error;
+                        const ended = endedAs(error);
+                        if (ended)
+                            return { runId, outcome: "not_cancellable", status: ended };
+                        if (error instanceof UnfazedInspectError && error.name === "WorkflowRunNotFoundError") {
+                            return { runId, outcome: "not_found" };
+                        }
+                        return { runId, outcome: "failed", code: "internal_error", retryable: true };
+                    }
+                });
+                const count = (outcome) => results.filter((r) => r.outcome === outcome).length;
+                return {
+                    summary: {
+                        requested: results.length,
+                        cancelled: count("cancelled"),
+                        alreadyCancelled: count("already_cancelled"),
+                        notCancellable: count("not_cancellable"),
+                        notFound: count("not_found"),
+                        failed: count("failed"),
+                    },
+                    results,
+                };
+            },
+        },
+        steps: {
+            async get(runId, stepId, params) {
+                const { workflowStep } = await call(docs.STEP_DETAIL, { alias, runID: runId, stepID: stepId }, runId);
+                return stepRecord(runId, workflowStep.step, workflowStep, params?.resolveData !== "none");
+            },
+            async list(params) {
+                const { runId, pagination } = params;
+                const limit = clamp(pagination?.limit ?? 20, 1, 200);
+                if ((pagination?.sortOrder ?? "desc") === "asc") {
+                    if (pagination?.cursor?.startsWith(CURSOR_PREFIX))
+                        throw badCursor("steps.list");
+                    const { workflowSteps } = await call(docs.STEPS, { alias, runID: runId, limit, cursor: pagination?.cursor || null }, runId);
+                    return {
+                        data: workflowSteps.steps.map((step) => stepRecord(runId, step)),
+                        cursor: workflowSteps.hasMore ? workflowSteps.nextCursor : null,
+                        hasMore: workflowSteps.hasMore,
+                    };
+                }
+                // Newest first: the API pages oldest first, so read the run's steps and page them here.
+                const offset = decodeOffset(pagination?.cursor, "steps.list");
+                const steps = (await allSteps(runId)).reverse();
+                return offsetPage(steps.map((step) => stepRecord(runId, step)), offset, limit);
+            },
+        },
+        events: {
+            async get(runId, eventId, params) {
+                const { workflowEvent } = await call(docs.EVENT_DETAIL, { alias, runID: runId, eventID: eventId }, runId);
+                return eventRecord(runId, workflowEvent.event, params?.resolveData === "none" ? null : workflowEvent.data);
+            },
+            async list(params) {
+                return listEvents(params.runId, null, params.pagination);
+            },
+            async listByCorrelationId(params) {
+                if (!params.runId) {
+                    throw invalidArgument("events.listByCorrelationId", "runId", "the unfazed backend reads events per run: pass the run ID");
+                }
+                return listEvents(params.runId, params.correlationId, params.pagination);
+            },
+            async create(runId, data) {
+                if (runId && data.eventType === "run_cancelled") {
+                    const reason = data.eventData?.cancelReason;
+                    await cancel(runId, typeof reason === "string" ? reason : undefined);
+                    return { event: syntheticEvent(runId, data) };
+                }
+                if (runId && data.eventType === "wait_completed" && data.correlationId) {
+                    await call(docs.WAKE, { input: { alias, runID: runId, correlationIDs: [data.correlationId] } }, runId);
+                    woken.set(runId, Date.now() + WAKE_QUEUE_WINDOW_MS);
+                    runPages.delete(runId);
+                    return { event: syntheticEvent(runId, data) };
+                }
+                throw readOnly(`write a ${data.eventType} event`);
+            },
+        },
+        hooks: {
+            async get(hookId) {
+                const known = hookRuns.get(hookId);
+                if (known) {
+                    const hook = (await runPage(known)).hooks.find((h) => h.hookID === hookId);
+                    if (hook)
+                        return hookRecord(known, hook);
+                }
+                const { pages } = await activeRuns(HOOK_SCAN_RUNS, null);
+                for (const page of pages) {
+                    const hook = page.hooks.find((h) => h.hookID === hookId);
+                    if (hook)
+                        return hookRecord(page.run.runID, hook);
+                }
+                throw new UnfazedInspectError(`Hook ${hookId} not found. The unfazed backend finds a hook through its run, and no run read so far, ` +
+                    `nor any of the ${HOOK_SCAN_RUNS} newest active runs, has it. List a run's hooks with ` +
+                    "`workflow inspect hooks --runId <run-id>`.", { name: "HookNotFoundError", status: 404 });
+            },
+            async getByToken() {
+                throw readOnly("look a hook up by its token (hook tokens never leave the app)");
+            },
+            async list(params) {
+                const { runId, pagination } = params;
+                const desc = pagination?.sortOrder === "desc";
+                const byCreated = (a, b) => (a.createdAt.getTime() - b.createdAt.getTime()) * (desc ? -1 : 1);
+                if (runId) {
+                    const hooks = hooksOf(await runPage(runId), false).sort(byCreated);
+                    return offsetPage(hooks, decodeOffset(pagination?.cursor, "hooks.list"), clamp(pagination?.limit ?? 100, 1, 500));
+                }
+                // Every hook of the app: those of its active runs (a finished run's hooks are gone), a page of runs at a time.
+                const runsCursor = decodeWrapped(pagination?.cursor, "runs", "hooks.list");
+                const { pages, nextCursor, hasMore } = await activeRuns(clamp(pagination?.limit ?? 20, 1, HOOK_SCAN_RUNS), runsCursor);
+                return {
+                    data: pages.flatMap((page) => hooksOf(page, true)).sort(byCreated),
+                    cursor: hasMore && nextCursor ? `${CURSOR_PREFIX}runs:${nextCursor}` : null,
+                    hasMore: hasMore && nextCursor !== null,
+                };
+            },
+        },
+        streams: {
+            async list(runId) {
+                return (await runPage(runId)).streams.map((stream) => stream.name);
+            },
+            async getInfo(runId, name) {
+                const { workflowStream } = await call(docs.STREAM, { alias, runID: runId, name, limit: 1 }, runId);
+                return { tailIndex: workflowStream.tailIndex, done: workflowStream.done };
+            },
+            async getChunks(runId, name, options) {
+                const { workflowStream } = await call(docs.STREAM, { alias, runID: runId, name, limit: clamp(options?.limit ?? 100, 1, 200), cursor: options?.cursor || null }, runId);
+                return {
+                    data: workflowStream.chunks.map((chunk) => ({ index: chunk.index, data: frame(chunkValue(chunk)) })),
+                    cursor: workflowStream.hasMore ? workflowStream.nextCursor : null,
+                    hasMore: workflowStream.hasMore,
+                    done: workflowStream.done,
+                };
+            },
+            /**
+             * The stream from `startIndex` (negative: from the end), each chunk one
+             * frame, read a page at a time and, while the run is still writing it,
+             * polled (1 s, doubling up to `streamPollMs`) until it is done.
+             */
+            async get(runId, name, startIndex = 0) {
+                let pageCursor = null;
+                let position;
+                let delay = pollMinMs;
+                let cancelled = false;
+                return new ReadableStream({
+                    async pull(controller) {
+                        for (;;) {
+                            if (cancelled || closed) {
+                                controller.close();
+                                return;
+                            }
+                            const { workflowStream } = await call(docs.STREAM, { alias, runID: runId, name, limit: STREAM_PAGE, cursor: pageCursor }, runId);
+                            position ??= startIndex < 0 ? Math.max(0, workflowStream.tailIndex + 1 + startIndex) : startIndex;
+                            const fresh = workflowStream.chunks.filter((chunk) => chunk.index >= position);
+                            // A page with more after it is never read again; the last page is re-read for new chunks.
+                            if (workflowStream.hasMore && workflowStream.nextCursor)
+                                pageCursor = workflowStream.nextCursor;
+                            if (fresh.length > 0) {
+                                for (const chunk of fresh)
+                                    controller.enqueue(frame(chunkValue(chunk)));
+                                position = fresh[fresh.length - 1].index + 1;
+                                delay = pollMinMs;
+                                return;
+                            }
+                            if (workflowStream.hasMore)
+                                continue;
+                            if (workflowStream.done) {
+                                controller.close();
+                                return;
+                            }
+                            await sleep(delay);
+                            delay = Math.min(delay * 2, pollMaxMs);
+                        }
+                    },
+                    cancel() {
+                        cancelled = true;
+                    },
+                });
+            },
+            async write() {
+                throw readOnly("write to a stream");
+            },
+            async writeMulti() {
+                throw readOnly("write to a stream");
+            },
+            async close() {
+                throw readOnly("close a stream");
+            },
+        },
+        async getDeploymentId() {
+            throw readOnly("start runs (it has no deployment of its own)");
+        },
+        async queue(_queueName, message) {
+            const runId = message?.runId;
+            const until = typeof runId === "string" ? woken.get(runId) : undefined;
+            // `wakeUp()` re-enqueues the run after completing its waits; the app already did both.
+            if (until !== undefined && until > Date.now())
+                return { messageId: null };
+            throw readOnly("enqueue messages");
+        },
+        createQueueHandler() {
+            throw readOnly("handle queue deliveries");
+        },
+        async close() {
+            closed = true;
+            for (const wake of [...sleepers])
+                wake();
+        },
+    };
+    async function listEvents(runId, correlationId, pagination) {
+        const { workflowEvents } = await call(docs.EVENTS, {
+            alias,
+            runID: runId,
+            correlationID: correlationId,
+            newestFirst: pagination?.sortOrder === "desc",
+            limit: clamp(pagination?.limit ?? 100, 1, 500),
+            cursor: pagination?.cursor || null,
+        }, runId);
+        return {
+            data: workflowEvents.events.map((event) => eventRecord(runId, event)),
+            cursor: workflowEvents.hasMore ? workflowEvents.nextCursor : null,
+            hasMore: workflowEvents.hasMore,
+        };
+    }
+    // Every member exists on Workflow SDK's World (no misspelt or invented method); parameters
+    // are the World's own types above. The overloaded return types are not checked here.
+    const keys = true;
+    const namespaces = [true, true, true, true, true];
+    void keys;
+    void namespaces;
+    return world;
+}
+/** Cursors this backend mints itself (offset pages, wrapped run cursors); the API's own pass through untouched. */
+const CURSOR_PREFIX = "unfz:";
+function offsetPage(items, offset, limit) {
+    const end = offset + limit;
+    const hasMore = end < items.length;
+    return { data: items.slice(offset, end), cursor: hasMore ? `${CURSOR_PREFIX}offset:${end}` : null, hasMore };
+}
+function decodeOffset(cursor, method) {
+    if (!cursor)
+        return 0;
+    const match = /^unfz:offset:(\d{1,9})$/.exec(cursor);
+    if (!match)
+        throw badCursor(method);
+    return Number(match[1]);
+}
+function decodeWrapped(cursor, kind, method) {
+    if (!cursor)
+        return null;
+    const prefix = `${CURSOR_PREFIX}${kind}:`;
+    if (!cursor.startsWith(prefix) || cursor.length === prefix.length)
+        throw badCursor(method);
+    return cursor.slice(prefix.length);
+}
+function badCursor(method) {
+    return invalidArgument(method, "cursor", "this cursor came from another listing or sort order");
+}
+function invalidArgument(method, field, why) {
+    return new UnfazedInspectError(`unfazed: ${method}: ${field}: ${why}.`, { code: "INVALID_ARGUMENT" });
+}
+function readOnly(what) {
+    return new UnfazedInspectError(`unfazed: the \`unfazed\` CLI backend is read-only and cannot ${what}. It inspects an app's runs from your ` +
+        "terminal (workflow inspect, workflow cancel, the web UI). Apps use unfazed/workflow: its Nitro module, " +
+        'or setWorld(createWorld()) from "unfazed/workflow", not WORKFLOW_TARGET_WORLD=unfazed.', { code: "READ_ONLY" });
+}
+function syntheticEvent(runId, data) {
+    const { correlationId, eventData } = data;
+    return {
+        runId,
+        eventId: "",
+        eventType: data.eventType,
+        createdAt: new Date(),
+        ...(correlationId ? { correlationId } : {}),
+        ...(eventData ? { eventData } : {}),
+    };
+}
+/**
+ * The platform's error as Workflow SDK's tooling expects a World's: a
+ * missing run is `WorkflowRunNotFoundError` (404), a refused token says how
+ * to get one, a token without the deploy scope says what needs it.
+ */
+function translate(error, alias, runId, authSource) {
+    const refused = (status, cause) => new UnfazedInspectError(authSource === "login"
+        ? `unfazed: the platform refused the stored login (HTTP ${status}). Run \`${LOGIN_COMMAND}\` again.`
+        : `unfazed: the platform refused the API token (HTTP ${status}). Check ${TOKEN_ENV_VAR}; ` +
+            `sign in with \`${LOGIN_COMMAND}\` instead, or get an agent token at https://unfazed.dev/auth.md.`, { status, cause });
+    if (error instanceof UnfazedHTTPError) {
+        if (error.status === 401 || error.status === 403)
+            return refused(error.status, error);
+        return new UnfazedInspectError(error.message, { status: error.status, cause: error });
+    }
+    if (!(error instanceof UnfazedGraphQLError))
+        return error;
+    const message = error.errors.map((e) => e.message).join("; ");
+    if (message.trim() === "authentication required")
+        return refused(401, error);
+    if (/^no such run\b/.test(message)) {
+        return new UnfazedInspectError(runId ? `Workflow run "${runId}" not found` : `unfazed: ${message}`, {
+            name: "WorkflowRunNotFoundError",
+            status: 404,
+            runId,
+            cause: error,
+        });
+    }
+    if (/^no such (step|event|stream)\b/.test(message)) {
+        return new UnfazedInspectError(`unfazed: ${message}`, { status: 404, cause: error });
+    }
+    if (message.trim() === "deployment was not found") {
+        return new UnfazedInspectError(`unfazed: no app "${alias}" that this token can see. Check ${APP_ENV_VAR} (the app's alias) and that ` +
+            "the token's account owns the app or shares its team.", { status: 404, cause: error });
+    }
+    const scope = /missing OAuth scope (\S+)/.exec(message);
+    if (scope) {
+        const needs = scope[1] === "unfz:deploy" ? " (cancel and wake need it, like restarting the app)" : "";
+        return new UnfazedInspectError(`unfazed: this API token lacks the ${scope[1]} scope${needs}.`, { status: 403, cause: error });
+    }
+    return new UnfazedInspectError(`unfazed: ${message}`, { cause: error });
+}
+/** The status of the "run … already ended (<status>)" refusal (409 `run_terminal`), else undefined. */
+function endedAs(error) {
+    return /already ended \(([a-z]+)\)/.exec(error instanceof Error ? error.message : "")?.[1];
+}
+function normalizeEndpoint(value) {
+    const trimmed = value.replace(/\/+$/, "");
+    return /\/query$|\/graphql$/.test(trimmed) ? trimmed : `${trimmed}/query`;
+}
+function clamp(value, min, max) {
+    return Number.isFinite(value) ? Math.min(max, Math.max(min, Math.trunc(value))) : min;
+}
+function setDate(record, key, value) {
+    const date = toDate(value);
+    if (date)
+        record[key] = date;
+}
+function setDefined(record, key, value) {
+    if (value !== undefined)
+        record[key] = value;
+}
+/** `fn` over `items`, at most `limit` at a time, results in order. */
+async function mapLimit(items, limit, fn) {
+    const results = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const index = next++;
+            results[index] = await fn(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return results;
+}
+//# sourceMappingURL=world.js.map