unfazed 0.5.0 → 0.6.0

package/dist/workflow/inspect.js

@@ -0,0 +1,879 @@
+/**
+ * The workflow inspection route: what the unfazed dashboard and MCP read runs,
+ * steps, events and streams through, and wake or cancel a run with (guest
+ * contract v1, unfazed docs/workflow-inspect.md).
+ *
+ * Everything is read through the app's own World (`getWorld()`), so it works
+ * on a cold start and holds no database connection after the request; actions
+ * go through the SDK's own `getRun(id).wakeUp()` / `.cancel()`. Payloads are
+ * hydrated with `workflow/observability`. Only the platform calls it: it
+ * answers 401 to anything without `X-Unfz-Queue-Token` equal to
+ * `UNFZ_STATE_TOKEN`, and public ingress strips that header.
+ */
+import { Buffer } from "node:buffer";
+import { getEventDataRefFields, isTerminalWorkflowRunStatus, stripEventDataRefs, } from "@workflow/world";
+import { hydrateData, hydrateResourceIO, observabilityRevivers, parseStepName, parseWorkflowName } from "workflow/observability";
+import { VERSION } from "../client.js";
+import { envValue } from "./config.js";
+import { cutUtf8, displayText, eventInfo, failedValue, isoTime, redactWebhookTokens, renderError, renderValue, stepInputDisplay, utf8Length, } from "./inspect-render.js";
+import { DELIVERY_HEADERS, describe, verifyQueueToken } from "./queue.js";
+/** Where `unfazed/workflow/nitro` mounts the route; other frameworks mount {@link createInspectHandler} here. */
+export const INSPECT_BASE_PATH = "/.well-known/workflow/v1/unfazed/inspect/v1";
+export const INSPECT_CONTRACT_VERSION = 1;
+// ---------------------------------------------------------------------------
+// Limits of the contract.
+// ---------------------------------------------------------------------------
+const MAX_BODY_BYTES = 1024 * 1024;
+/** Lists shrink their page (fewer items, `has_more`) to stay under this. */
+const PAGE_BUDGET_BYTES = 900 * 1024;
+const MAX_POST_BYTES = 16 * 1024;
+const MAX_ERROR_MESSAGE_BYTES = 1024;
+const IO_CAP_BYTES = 16 * 1024;
+const EVENT_DATA_CAP_BYTES = 64 * 1024;
+const CHUNK_TEXT_CAP_BYTES = 8 * 1024;
+const RUN_PAGE_STEPS = 200;
+const RUN_PAGE_MAX_EVENTS = 10_000;
+const RUN_PAGE_MAX_STREAMS = 50;
+const RUN_PAGE_STREAM_INFOS = 20;
+/** A run page keeps the latest 500 waits and hooks; `waits_truncated` / `hooks_truncated` say when there were more. */
+const RUN_PAGE_MAX_WAITS = 500;
+const RUN_PAGE_MAX_HOOKS = 500;
+const STEP_PAGE_EVENTS = 200;
+const EVENTS_PAGE_SIZE = 500;
+const RUN_STATUSES = ["pending", "running", "completed", "failed", "cancelled"];
+const ID_PATTERN = /^[A-Za-z0-9_.:-]{1,256}$/;
+const CURSOR_PATTERN = /^[\x21-\x7e]{1,1024}$/;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the contract refuses control characters
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/;
+class InspectFailure extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+const invalid = (message) => new InspectFailure(400, "invalid_request", message);
+const notFound = (message) => new InspectFailure(404, "not_found", message);
+const RESPONSE_HEADERS = { "content-type": "application/json", "cache-control": "no-store" };
+function respond(status, body, headers = {}) {
+    return new Response(JSON.stringify(body), { status, headers: { ...RESPONSE_HEADERS, ...headers } });
+}
+function errorResponse(status, code, message, headers) {
+    return respond(status, { error: code, message: cutUtf8(redactWebhookTokens(message), MAX_ERROR_MESSAGE_BYTES).text }, headers);
+}
+const idRule = (value, name) => {
+    if (!ID_PATTERN.test(value))
+        throw invalid(`${name} must be 1 to 256 bytes of [A-Za-z0-9_.:-]`);
+};
+const textRule = (value, name) => {
+    const bytes = utf8Length(value);
+    if (bytes < 1 || bytes > 1024 || CONTROL_CHARACTERS.test(value)) {
+        throw invalid(`${name} must be 1 to 1024 bytes of UTF-8 without control characters`);
+    }
+};
+const cursorRule = (value, name) => {
+    if (!CURSOR_PATTERN.test(value))
+        throw invalid(`${name} must be 1 to 1024 bytes of visible ASCII`);
+};
+const limitRule = (max) => (value, name) => {
+    if (!/^\d{1,6}$/.test(value) || Number(value) < 1 || Number(value) > max) {
+        throw invalid(`${name} must be a decimal integer from 1 to ${max}`);
+    }
+};
+const statusRule = (value, name) => {
+    for (const word of value.split(",")) {
+        if (!RUN_STATUSES.includes(word)) {
+            throw invalid(`${name} must be a comma-separated subset of ${RUN_STATUSES.join(", ")}`);
+        }
+    }
+};
+const orderRule = (value, name) => {
+    if (value !== "asc" && value !== "desc")
+        throw invalid(`${name} must be asc or desc`);
+};
+/** The query, refusing unknown, repeated and missing parameters. */
+function parseQuery(url, rules, required) {
+    const params = {};
+    for (const [name, value] of url.searchParams) {
+        const rule = rules[name];
+        if (!rule)
+            throw invalid(`unknown parameter ${JSON.stringify(name)}`);
+        if (name in params)
+            throw invalid(`parameter ${name} is repeated`);
+        rule(value, name);
+        params[name] = value;
+    }
+    for (const name of required)
+        if (!(name in params))
+            throw invalid(`missing parameter ${name}`);
+    return params;
+}
+async function readBody(req) {
+    const type = req.headers.get("content-type") ?? "";
+    if (!/^application\/json\s*(;|$)/i.test(type))
+        throw invalid("the body must be application/json");
+    const declared = Number(req.headers.get("content-length") ?? "0");
+    if (declared > MAX_POST_BYTES)
+        throw invalid(`the body may be at most ${MAX_POST_BYTES} bytes`);
+    const chunks = [];
+    let size = 0;
+    if (req.body) {
+        const reader = req.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_POST_BYTES) {
+                await reader.cancel().catch(() => { });
+                throw invalid(`the body may be at most ${MAX_POST_BYTES} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw invalid("the body is not valid JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+        throw invalid("the body must be a JSON object");
+    return parsed;
+}
+function checkFields(body, allowed) {
+    for (const key of Object.keys(body)) {
+        if (!allowed.includes(key))
+            throw invalid(`unknown field ${JSON.stringify(key)}`);
+    }
+}
+function bodyId(body, name) {
+    const value = body[name];
+    if (typeof value !== "string")
+        throw invalid(`${name} must be a string`);
+    idRule(value, name);
+    return value;
+}
+function names(parsed, raw) {
+    return { display_name: parsed?.shortName || raw, module: parsed?.moduleSpecifier ?? "" };
+}
+function runSummary(run) {
+    const { display_name, module } = names(parseWorkflowName(run.workflowName), run.workflowName);
+    return {
+        run_id: run.runId,
+        workflow_name: run.workflowName,
+        display_name,
+        module,
+        status: run.status,
+        deployment_id: run.deploymentId,
+        created_at: isoTime(run.createdAt),
+        started_at: isoTime(run.startedAt),
+        completed_at: isoTime(run.completedAt),
+        updated_at: isoTime(run.updatedAt),
+        expired_at: isoTime(run.expiredAt),
+        error_code: run.errorCode ?? null,
+        attributes: Object.fromEntries(Object.entries(run.attributes ?? {}).map(([k, v]) => [redactWebhookTokens(k), redactWebhookTokens(String(v))])),
+    };
+}
+function stepSummary(step) {
+    const { display_name, module } = names(parseStepName(step.stepName), step.stepName);
+    return {
+        step_id: step.stepId,
+        step_name: step.stepName,
+        display_name,
+        module,
+        status: step.status,
+        attempt: step.attempt,
+        created_at: isoTime(step.createdAt),
+        started_at: isoTime(step.startedAt),
+        completed_at: isoTime(step.completedAt),
+        updated_at: isoTime(step.updatedAt),
+        retry_after: isoTime(step.retryAfter),
+    };
+}
+function inspectEvent(event) {
+    const stripped = stripEventDataRefs(event, "none");
+    const { info, truncated } = eventInfo(stripped.eventData);
+    return {
+        event_id: event.eventId,
+        event_type: event.eventType,
+        correlation_id: event.correlationId ?? null,
+        created_at: isoTime(event.createdAt),
+        info,
+        info_truncated: truncated,
+    };
+}
+const pageCursor = (page) => page.hasMore && page.cursor ? page.cursor : null;
+let reviversPromise;
+/**
+ * The revivers payloads are hydrated with: Workflow SDK's common revivers
+ * (`Date`, `Map`, `Error`, typed arrays, … — without them devalue refuses any
+ * payload holding one), display objects for `Request`/`Response`, then
+ * `observabilityRevivers` (streams, runs, class instances and step functions
+ * as display objects), the set Workflow SDK's own CLI inspector layers.
+ */
+function revivers() {
+    reviversPromise ??= (async () => {
+        let common = {};
+        try {
+            const serialization = (await import("@workflow/core/serialization"));
+            common = serialization.getCommonRevivers?.(globalThis) ?? {};
+        }
+        catch (error) {
+            console.warn(`[unfazed/workflow] inspection: Workflow SDK's common revivers are unavailable (${describe(error)}); ` +
+                "payloads holding a Date, Map, Error, … will show as unreadable");
+        }
+        const display = (kind) => (value) => {
+            const out = { $type: kind };
+            for (const key of ["method", "url", "status", "statusText", "headers", "body", "redirected"]) {
+                if (key in value)
+                    out[key] = key === "headers" ? headersObject(value[key]) : value[key];
+            }
+            return out;
+        };
+        return {
+            ...common,
+            Request: display("Request"),
+            Response: display("Response"),
+            ...observabilityRevivers,
+        };
+    })();
+    return reviversPromise;
+}
+function headersObject(value) {
+    if (Array.isArray(value))
+        return Object.fromEntries(value.filter((e) => Array.isArray(e) && e.length === 2));
+    return value;
+}
+/**
+ * A hydrated field and, when it could not be hydrated, why:
+ * `hydrateResourceIO` leaves a field it cannot read untouched, so a field that
+ * comes back as the same serialized value is hydrated again to get the reason.
+ */
+function hydratedField(raw, hydrated, rev) {
+    if (raw === undefined || raw === null)
+        return { value: undefined };
+    if (hydrated === raw && (raw instanceof Uint8Array || Array.isArray(raw))) {
+        try {
+            return { value: hydrateData(raw, rev) };
+        }
+        catch (error) {
+            return { value: undefined, failure: error };
+        }
+    }
+    return { value: hydrated };
+}
+function valueOf(field, cap, secrets) {
+    if (field.failure !== undefined)
+        return failedValue(field.failure, cap);
+    return renderValue(field.value, cap, secrets ? { secrets, dropTokenKeys: true } : {});
+}
+// ---------------------------------------------------------------------------
+// Stream chunks.
+// ---------------------------------------------------------------------------
+const FRAME_FORMATS = new Set(["devl", "gzip", "zstd"]);
+/** The chunk's length-prefixed frames as Workflow SDK's stream writer writes them, or undefined. */
+function sdkFrames(data) {
+    const frames = [];
+    let offset = 0;
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    while (offset < data.byteLength) {
+        if (offset + 8 > data.byteLength)
+            return undefined;
+        const length = view.getUint32(offset, false);
+        if (length < 4 || offset + 4 + length > data.byteLength)
+            return undefined;
+        const frame = data.subarray(offset + 4, offset + 4 + length);
+        if (!FRAME_FORMATS.has(String.fromCharCode(frame[0], frame[1], frame[2], frame[3])))
+            return undefined;
+        frames.push(frame);
+        offset += 4 + length;
+    }
+    return frames.length > 0 ? frames : undefined;
+}
+/**
+ * One chunk as `{index, bytes, encoding, text, truncated}`: `json` when it is
+ * Workflow SDK frames (what `getWritable()` writes), rendered as a Value; a
+ * frame holding bytes (a byte stream's chunk) shows those bytes, as `utf8`
+ * when they are text, else `base64`; anything else is the raw chunk, `utf8`
+ * when it is valid UTF-8, else `base64`. `bytes` is always the raw length.
+ */
+function renderChunk(index, data, rev) {
+    const frames = sdkFrames(data);
+    if (frames) {
+        try {
+            const values = frames.map((frame) => hydrateData(frame, rev));
+            // Encrypted frames come back as the very bytes given: not readable here.
+            if (!values.some((value, i) => value === frames[i])) {
+                if (values.length === 1 && values[0] instanceof Uint8Array)
+                    return rawChunk(index, data.byteLength, values[0]);
+                const cut = cutUtf8(displayText(values.length === 1 ? values[0] : values), CHUNK_TEXT_CAP_BYTES);
+                return { index, bytes: data.byteLength, encoding: "json", text: cut.text, truncated: cut.truncated };
+            }
+        }
+        catch {
+            // not the SDK's framing after all
+        }
+    }
+    return rawChunk(index, data.byteLength, data);
+}
+function rawChunk(index, bytes, data) {
+    try {
+        // Redacted before the cut, so a token can never survive half-cut.
+        const text = redactWebhookTokens(new TextDecoder("utf-8", { fatal: true }).decode(data));
+        const cut = cutUtf8(text, CHUNK_TEXT_CAP_BYTES);
+        return { index, bytes, encoding: "utf8", text: cut.text, truncated: cut.truncated };
+    }
+    catch {
+        // Not text, but a webhook URL may still sit in it as ASCII: redact it in
+        // the bytes (latin1 maps each byte to one character and back).
+        const latin1 = Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("latin1");
+        const redacted = redactWebhookTokens(latin1);
+        const base64 = (redacted === latin1 ? Buffer.from(data.buffer, data.byteOffset, data.byteLength) : Buffer.from(redacted, "latin1")).toString("base64");
+        const truncated = base64.length > CHUNK_TEXT_CAP_BYTES;
+        return { index, bytes, encoding: "base64", text: truncated ? base64.slice(0, CHUNK_TEXT_CAP_BYTES) : base64, truncated };
+    }
+}
+// ---------------------------------------------------------------------------
+// World errors.
+// ---------------------------------------------------------------------------
+function isNotFound(error) {
+    for (let e = error, depth = 0; e instanceof Error && depth < 4; e = e.cause, depth++) {
+        if (e.name === "WorkflowRunNotFoundError" || e.name === "HookNotFoundError")
+            return true;
+        if (e.status === 404)
+            return true;
+        if (e.name === "WorkflowWorldError" && /\bnot found\b/i.test(e.message))
+            return true;
+    }
+    return false;
+}
+async function orNotFound(call, message) {
+    try {
+        return await call;
+    }
+    catch (error) {
+        if (isNotFound(error))
+            throw notFound(message);
+        throw error;
+    }
+}
+/** Shrinks a page until its answer fits the budget; World cursors stay the World's own. */
+async function fitPage(limit, fetchPage) {
+    let size = limit;
+    for (;;) {
+        const answer = await fetchPage(size);
+        if (size === 1 || utf8Length(JSON.stringify(answer)) <= PAGE_BUDGET_BYTES)
+            return answer;
+        size = Math.max(1, Math.floor(size / 2));
+    }
+}
+async function assertRun(world, runId) {
+    return orNotFound(world.runs.get(runId, { resolveData: "none" }), `no such run ${runId}`);
+}
+async function scanEvents(world, runId) {
+    const events = [];
+    let cursor;
+    for (;;) {
+        const page = await world.events.list({
+            runId,
+            pagination: { limit: Math.min(EVENTS_PAGE_SIZE, RUN_PAGE_MAX_EVENTS - events.length), sortOrder: "asc", ...(cursor ? { cursor } : {}) },
+            resolveData: "none",
+        });
+        events.push(...page.data);
+        if (!page.hasMore || !page.cursor)
+            return { events, complete: true };
+        if (events.length >= RUN_PAGE_MAX_EVENTS)
+            return { events, complete: false };
+        cursor = page.cursor;
+    }
+}
+function waitsOf(events) {
+    const waits = new Map();
+    for (const event of events) {
+        const id = event.correlationId;
+        if (!id)
+            continue;
+        const data = event.eventData;
+        if (event.eventType === "wait_created") {
+            waits.set(id, {
+                correlation_id: id,
+                status: "waiting",
+                created_at: isoTime(event.createdAt),
+                resume_at: isoTime(data?.resumeAt),
+                completed_at: null,
+            });
+        }
+        else if (event.eventType === "wait_completed") {
+            const wait = waits.get(id);
+            if (wait) {
+                wait.status = "completed";
+                wait.completed_at = isoTime(event.createdAt);
+            }
+        }
+    }
+    const all = [...waits.values()];
+    return { waits: all.slice(-RUN_PAGE_MAX_WAITS), truncated: all.length > RUN_PAGE_MAX_WAITS };
+}
+function hooksOf(events, entities) {
+    const hooks = new Map();
+    for (const event of events) {
+        const id = event.correlationId;
+        if (!id)
+            continue;
+        const data = event.eventData;
+        if (event.eventType === "hook_created") {
+            hooks.set(id, {
+                hook_id: id,
+                kind: "hook",
+                status: "active",
+                created_at: isoTime(event.createdAt),
+                received_count: 0,
+                last_received_at: null,
+                disposed_at: null,
+                ...(typeof data?.isWebhook === "boolean" ? { isWebhook: data.isWebhook } : {}),
+                ...(typeof data?.isSystem === "boolean" ? { isSystem: data.isSystem } : {}),
+            });
+            continue;
+        }
+        const hook = hooks.get(id);
+        if (!hook)
+            continue;
+        if (event.eventType === "hook_received") {
+            hook.received_count++;
+            hook.last_received_at = isoTime(event.createdAt);
+        }
+        else if (event.eventType === "hook_disposed") {
+            hook.status = "disposed";
+            hook.disposed_at = isoTime(event.createdAt);
+        }
+    }
+    for (const entity of entities) {
+        let hook = hooks.get(entity.hookId);
+        if (!hook) {
+            hook = {
+                hook_id: entity.hookId,
+                kind: "hook",
+                status: "active",
+                created_at: isoTime(entity.createdAt),
+                received_count: 0,
+                last_received_at: null,
+                disposed_at: null,
+            };
+            hooks.set(entity.hookId, hook);
+        }
+        if (typeof entity.isWebhook === "boolean")
+            hook.isWebhook = entity.isWebhook;
+        if (typeof entity.isSystem === "boolean")
+            hook.isSystem = entity.isSystem;
+    }
+    const all = [...hooks.values()].sort((a, b) => (a.created_at ?? "").localeCompare(b.created_at ?? ""));
+    return {
+        hooks: all.slice(-RUN_PAGE_MAX_HOOKS).map(({ isWebhook, isSystem, ...hook }) => ({
+            ...hook,
+            kind: isSystem ? "system" : isWebhook ? "webhook" : "hook",
+        })),
+        truncated: all.length > RUN_PAGE_MAX_HOOKS,
+    };
+}
+const ENDPOINTS = {
+    info: {
+        method: "GET",
+        async run({ world, options }) {
+            const workflows = [...new Set(options.workflows ?? [])].sort().map((name) => ({
+                name,
+                ...names(parseWorkflowName(name), name),
+            }));
+            return {
+                version: INSPECT_CONTRACT_VERSION,
+                package: `unfazed@${VERSION}`,
+                workflow: options.workflowVersion || "unknown",
+                spec_version: typeof world.specVersion === "number" ? world.specVersion : null,
+                workflows,
+            };
+        },
+    },
+    runs: {
+        method: "GET",
+        rules: { status: statusRule, workflow_name: textRule, limit: limitRule(100), cursor: cursorRule },
+        async run({ world }, { params }) {
+            const status = params.status ? [...new Set(params.status.split(","))] : undefined;
+            return fitPage(Number(params.limit ?? 20), async (limit) => {
+                const page = await world.runs.list({
+                    ...(status ? { status: status } : {}),
+                    ...(params.workflow_name ? { workflowName: params.workflow_name } : {}),
+                    pagination: { limit, sortOrder: "desc", ...(params.cursor ? { cursor: params.cursor } : {}) },
+                    resolveData: "none",
+                });
+                return { runs: page.data.map(runSummary), next_cursor: pageCursor(page), has_more: page.hasMore && pageCursor(page) !== null };
+            });
+        },
+    },
+    run: {
+        method: "GET",
+        rules: { run_id: idRule },
+        required: ["run_id"],
+        async run({ world }, { params }) {
+            const runId = params.run_id;
+            const run = await orNotFound(world.runs.get(runId, { resolveData: "all" }), `no such run ${runId}`);
+            const [steps, scan, hookEntities, streamNames] = await Promise.all([
+                world.steps.list({ runId, pagination: { limit: RUN_PAGE_STEPS, sortOrder: "asc" }, resolveData: "none" }),
+                scanEvents(world, runId),
+                world.hooks.list({ runId, pagination: { limit: RUN_PAGE_MAX_HOOKS }, resolveData: "none" }),
+                world.streams.list(runId),
+            ]);
+            const streams = streamNames.slice(0, RUN_PAGE_MAX_STREAMS);
+            const infos = await Promise.all(streams.slice(0, RUN_PAGE_STREAM_INFOS).map((name) => world.streams.getInfo(runId, name).catch(() => undefined)));
+            const waits = waitsOf(scan.events);
+            const hooks = hooksOf(scan.events, hookEntities.data);
+            const rev = await revivers();
+            const hydrated = hydrateResourceIO(run, rev);
+            const raw = run;
+            const errorField = hydratedField(raw.error, hydrated.error, rev);
+            return {
+                run: runSummary(run),
+                input: valueOf(hydratedField(raw.input, hydrated.input, rev), IO_CAP_BYTES),
+                output: valueOf(hydratedField(raw.output, hydrated.output, rev), IO_CAP_BYTES),
+                error: run.status === "failed"
+                    ? renderError(errorField.value ?? null, run.errorCode ?? null, errorField.failure)
+                    : null,
+                steps: steps.data.map(stepSummary),
+                steps_next_cursor: pageCursor(steps),
+                steps_has_more: steps.hasMore && pageCursor(steps) !== null,
+                waits: waits.waits,
+                waits_truncated: waits.truncated,
+                hooks: hooks.hooks,
+                hooks_truncated: hooks.truncated,
+                streams: streams.map((name, i) => {
+                    const info = i < RUN_PAGE_STREAM_INFOS ? infos[i] : undefined;
+                    return { name, tail_index: info ? info.tailIndex : null, done: info ? info.done : null };
+                }),
+                events_scanned: scan.events.length,
+                events_complete: scan.complete,
+            };
+        },
+    },
+    steps: {
+        method: "GET",
+        rules: { run_id: idRule, limit: limitRule(200), cursor: cursorRule },
+        required: ["run_id"],
+        async run({ world }, { params }) {
+            const runId = params.run_id;
+            const [, answer] = await Promise.all([
+                assertRun(world, runId),
+                fitPage(Number(params.limit ?? 100), async (limit) => {
+                    const page = await world.steps.list({
+                        runId,
+                        pagination: { limit, sortOrder: "asc", ...(params.cursor ? { cursor: params.cursor } : {}) },
+                        resolveData: "none",
+                    });
+                    return { steps: page.data.map(stepSummary), next_cursor: pageCursor(page), has_more: page.hasMore && pageCursor(page) !== null };
+                }),
+            ]);
+            return answer;
+        },
+    },
+    step: {
+        method: "GET",
+        rules: { run_id: idRule, step_id: idRule },
+        required: ["run_id", "step_id"],
+        async run({ world }, { params }) {
+            const runId = params.run_id;
+            const stepId = params.step_id;
+            const [step, events] = await Promise.all([
+                orNotFound(world.steps.get(runId, stepId, { resolveData: "all" }), `no such step ${stepId} in run ${runId}`),
+                world.events.listByCorrelationId({
+                    runId,
+                    correlationId: stepId,
+                    pagination: { limit: STEP_PAGE_EVENTS, sortOrder: "asc" },
+                    resolveData: "none",
+                }),
+            ]);
+            const rev = await revivers();
+            const hydrated = hydrateResourceIO(step, rev);
+            const raw = step;
+            const errorField = hydratedField(raw.error, hydrated.error, rev);
+            const input = hydratedField(raw.input, hydrated.input, rev);
+            return {
+                step: stepSummary(step),
+                input: valueOf({ ...input, value: stepInputDisplay(input.value) }, IO_CAP_BYTES),
+                output: valueOf(hydratedField(raw.output, hydrated.output, rev), IO_CAP_BYTES),
+                error: raw.error === undefined || raw.error === null
+                    ? null
+                    : renderError(errorField.value ?? null, null, errorField.failure),
+                events: events.data.map(inspectEvent),
+                events_has_more: events.hasMore,
+            };
+        },
+    },
+    events: {
+        method: "GET",
+        rules: { run_id: idRule, correlation_id: idRule, order: orderRule, limit: limitRule(500), cursor: cursorRule },
+        required: ["run_id"],
+        async run({ world }, { params }) {
+            const runId = params.run_id;
+            const sortOrder = (params.order ?? "asc");
+            const [, answer] = await Promise.all([
+                assertRun(world, runId),
+                fitPage(Number(params.limit ?? 100), async (limit) => {
+                    const pagination = { limit, sortOrder, ...(params.cursor ? { cursor: params.cursor } : {}) };
+                    const page = params.correlation_id
+                        ? await world.events.listByCorrelationId({ runId, correlationId: params.correlation_id, pagination, resolveData: "none" })
+                        : await world.events.list({ runId, pagination, resolveData: "none" });
+                    return { events: page.data.map(inspectEvent), next_cursor: pageCursor(page), has_more: page.hasMore && pageCursor(page) !== null };
+                }),
+            ]);
+            return answer;
+        },
+    },
+    event: {
+        method: "GET",
+        rules: { run_id: idRule, event_id: idRule },
+        required: ["run_id", "event_id"],
+        async run({ world }, { params }) {
+            const runId = params.run_id;
+            const eventId = params.event_id;
+            const event = await orNotFound(world.events.get(runId, eventId, { resolveData: "all" }), `no such event ${eventId} in run ${runId}`);
+            const field = getEventDataRefFields(event.eventType).find((name) => {
+                const data = event.eventData;
+                return data !== undefined && data[name] !== undefined && data[name] !== null;
+            });
+            let data = null;
+            if (field) {
+                const [rev, secrets] = await Promise.all([revivers(), runHookTokens(world, runId, event)]);
+                const raw = event.eventData[field];
+                const hydrated = hydrateResourceIO(event, rev).eventData?.[field];
+                const value = hydratedField(raw, hydrated, rev);
+                // A step's input (step_created, step_started) shows as its arguments.
+                if (field === "input" && event.eventType.startsWith("step_"))
+                    value.value = stepInputDisplay(value.value);
+                data = valueOf(value, EVENT_DATA_CAP_BYTES, secrets);
+            }
+            return { event: inspectEvent(event), data };
+        },
+    },
+    stream: {
+        method: "GET",
+        rules: { run_id: idRule, name: textRule, limit: limitRule(200), cursor: cursorRule },
+        required: ["run_id", "name"],
+        async run({ world }, { params }) {
+            const runId = params.run_id;
+            const name = params.name;
+            const [streamNames, info] = await Promise.all([
+                orNotFound(world.streams.list(runId), `no such run ${runId}`),
+                world.streams.getInfo(runId, name),
+            ]);
+            if (!streamNames.includes(name))
+                throw notFound(`no such stream ${JSON.stringify(name)} in run ${runId}`);
+            const rev = await revivers();
+            return fitPage(Number(params.limit ?? 50), async (limit) => {
+                const page = await world.streams.getChunks(runId, name, { limit, ...(params.cursor ? { cursor: params.cursor } : {}) });
+                return {
+                    name,
+                    chunks: page.data.map((chunk) => renderChunk(chunk.index, chunk.data, rev)),
+                    next_cursor: pageCursor(page),
+                    has_more: page.hasMore && pageCursor(page) !== null,
+                    done: info.done,
+                    tail_index: info.tailIndex,
+                };
+            });
+        },
+    },
+    wake: {
+        method: "POST",
+        async run({ world, getRun }, { body }) {
+            checkFields(body, ["run_id", "correlation_ids"]);
+            const runId = bodyId(body, "run_id");
+            let correlationIds;
+            if (body.correlation_ids !== undefined) {
+                const ids = body.correlation_ids;
+                if (!Array.isArray(ids) || ids.length < 1 || ids.length > 100) {
+                    throw invalid("correlation_ids must be a list of 1 to 100 IDs");
+                }
+                correlationIds = ids.map((id, i) => {
+                    if (typeof id !== "string")
+                        throw invalid(`correlation_ids[${i}] must be a string`);
+                    idRule(id, `correlation_ids[${i}]`);
+                    return id;
+                });
+            }
+            const run = await assertRun(world, runId);
+            if (isTerminalWorkflowRunStatus(run.status))
+                throw terminal(run);
+            const handle = await getRun(runId);
+            const result = await orNotFound(handle.wakeUp(correlationIds ? { correlationIds } : undefined), `no such run ${runId}`);
+            return { stopped_count: result.stoppedCount };
+        },
+    },
+    cancel: {
+        method: "POST",
+        async run({ world, getRun }, { body }) {
+            checkFields(body, ["run_id", "reason"]);
+            const runId = bodyId(body, "run_id");
+            const reason = body.reason;
+            // At most 512 characters (code points), as the platform counts them.
+            if (reason !== undefined && (typeof reason !== "string" || Array.from(reason).length > 512)) {
+                throw invalid("reason must be a string of at most 512 characters");
+            }
+            const run = await assertRun(world, runId);
+            if (isTerminalWorkflowRunStatus(run.status))
+                throw terminal(run);
+            const handle = await getRun(runId);
+            try {
+                await handle.cancel(reason !== undefined ? { cancelReason: sdkCancelReason(reason) } : undefined);
+            }
+            catch (error) {
+                // Lost a race with the run ending: say so rather than fail.
+                const now = await world.runs.get(runId, { resolveData: "none" }).catch(() => undefined);
+                if (now && isTerminalWorkflowRunStatus(now.status))
+                    throw terminal(now);
+                throw error;
+            }
+            return { run_id: runId, status: "cancelled" };
+        },
+    },
+};
+/**
+ * The reason as Workflow SDK stores it: its schema takes at most 512 UTF-16
+ * units, so a reason of 512 characters that holds astral-plane ones (emoji)
+ * is cut on a character boundary to fit, rather than failing the cancel.
+ */
+export function sdkCancelReason(reason) {
+    if (reason.length <= 512)
+        return reason;
+    let out = "";
+    for (const char of reason) {
+        if (out.length + char.length > 512)
+            break;
+        out += char;
+    }
+    return out;
+}
+function terminal(run) {
+    return new InspectFailure(409, "run_terminal", `run ${run.runId} already ended (${run.status})`);
+}
+/**
+ * Every hook token of the run, so none of them, nor a webhook URL built from
+ * one, leaves in an event's data (a webhook's received `Request` carries its
+ * URL, which holds the token): from the hook records and from every event
+ * that names one (`hook_created`, `hook_received`, …), over the same 10 000
+ * events the run page reads.
+ */
+async function runHookTokens(world, runId, event) {
+    const tokens = new Set();
+    const add = (e) => {
+        const token = e?.eventData?.token;
+        if (typeof token === "string" && token.length > 0)
+            tokens.add(token);
+    };
+    add(event);
+    const records = async () => {
+        let cursor;
+        for (let page = 0; page < 20; page++) {
+            const hooks = await world.hooks.list({
+                runId,
+                pagination: { limit: RUN_PAGE_MAX_HOOKS, ...(cursor ? { cursor } : {}) },
+                resolveData: "none",
+            });
+            for (const hook of hooks.data)
+                if (typeof hook.token === "string" && hook.token.length > 0)
+                    tokens.add(hook.token);
+            if (!hooks.hasMore || !hooks.cursor)
+                return;
+            cursor = hooks.cursor;
+        }
+    };
+    const [, scan] = await Promise.all([records(), scanEvents(world, runId)]);
+    for (const e of scan.events)
+        add(e);
+    return [...tokens];
+}
+// ---------------------------------------------------------------------------
+// The handler.
+// ---------------------------------------------------------------------------
+/**
+ * Creates the inspection route's handler: `(request) => Response` for every
+ * request under {@link INSPECT_BASE_PATH}.
+ *
+ * ```ts
+ * // e.g. a catch-all route at /.well-known/workflow/v1/unfazed/inspect/v1/*
+ * import { createInspectHandler } from "unfazed/workflow";
+ * const inspect = createInspectHandler();
+ * export const GET = inspect, POST = inspect;
+ * ```
+ *
+ * `unfazed/workflow/nitro` mounts it for you.
+ */
+export function createInspectHandler(options = {}) {
+    const timeoutMs = options.timeoutMs ?? 19_000;
+    const getWorld = options.getWorld ??
+        (async () => {
+            const runtime = (await import("workflow/runtime"));
+            return runtime.getWorld();
+        });
+    const getRun = options.getRun
+        ? async (runId) => options.getRun(runId)
+        : async (runId) => {
+            const api = (await import("workflow/api"));
+            return api.getRun(runId);
+        };
+    return async (request) => {
+        const expected = options.stateToken ?? envValue(options.env ?? process.env, "UNFZ_STATE_TOKEN")?.trim();
+        if (!verifyQueueToken(expected || undefined, request.headers.get(DELIVERY_HEADERS.token))) {
+            return errorResponse(401, "unauthorized", "missing or invalid queue token");
+        }
+        const url = new URL(request.url);
+        const prefix = `${INSPECT_BASE_PATH}/`;
+        const op = url.pathname.startsWith(prefix) ? url.pathname.slice(prefix.length) : "";
+        const endpoint = Object.hasOwn(ENDPOINTS, op) ? ENDPOINTS[op] : undefined;
+        if (!endpoint)
+            return errorResponse(404, "not_found", `no inspection endpoint at ${url.pathname}`);
+        if (request.method !== endpoint.method) {
+            return errorResponse(405, "method_not_allowed", `${op} takes ${endpoint.method}`, { allow: endpoint.method });
+        }
+        let started = false;
+        const work = (async () => {
+            const params = parseQuery(url, endpoint.rules ?? {}, endpoint.required ?? []);
+            const body = endpoint.method === "POST" ? await readBody(request) : {};
+            let world;
+            try {
+                world = await getWorld();
+                const ready = world.ready;
+                if (typeof ready === "function")
+                    await ready.call(world);
+            }
+            catch (error) {
+                throw new InspectFailure(503, "world_unavailable", describe(error));
+            }
+            started = true;
+            return endpoint.run({ world, options, getRun }, { params, body });
+        })();
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(started
+                ? new InspectFailure(500, "internal", `the World did not answer within ${Math.round(timeoutMs / 1000)} s`)
+                : new InspectFailure(503, "world_unavailable", `the World is still starting after ${Math.round(timeoutMs / 1000)} s`)), timeoutMs);
+        });
+        work.catch(() => { }); // a late failure after the deadline answered
+        try {
+            const answer = await Promise.race([work, deadline]);
+            const text = JSON.stringify(answer);
+            if (utf8Length(text) > MAX_BODY_BYTES) {
+                return errorResponse(500, "internal", `the answer would exceed ${MAX_BODY_BYTES} bytes`);
+            }
+            return new Response(text, { status: 200, headers: RESPONSE_HEADERS });
+        }
+        catch (error) {
+            if (error instanceof InspectFailure)
+                return errorResponse(error.status, error.code, error.message);
+            return errorResponse(500, "internal", describe(error));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}
+//# sourceMappingURL=inspect.js.map