@swirls/looms 0.0.2 → 0.1.0

package/dist/runtime/server/auth.d.ts

@@ -0,0 +1,40 @@
+import { Effect } from 'effect';
+/**
+ * What a route can do. `public` routes (health) are never passed to `authorize`; `read` and
+ * `write` cover run state, `worker` covers external worker callbacks, and `operations` covers
+ * operator repair endpoints.
+ */
+export type RouteAccess = 'public' | 'read' | 'write' | 'worker' | 'operations';
+export type AuthorizedAccess = Exclude<RouteAccess, 'public'>;
+export interface RouteInfo {
+    readonly access: AuthorizedAccess;
+    /** Stable route name, such as `runs.signal` or `effects.retry`. */
+    readonly name: string;
+    readonly runId?: string;
+}
+export type AuthDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly status: number;
+    readonly error: string;
+};
+export type Authorize = (request: Request, route: RouteInfo) => Effect.Effect<AuthDecision>;
+export declare const authAllowed: AuthDecision;
+export declare function authDenied(status: number, error: string): AuthDecision;
+/**
+ * Used when a host supplies no `authorize`: run reads and writes stay open, while worker callbacks
+ * and operational endpoints are unavailable until a host opts in.
+ */
+export declare const defaultAuthorize: Authorize;
+export interface BearerTokens {
+    readonly read?: string;
+    readonly write?: string;
+    readonly worker?: string;
+    readonly operations?: string;
+}
+/**
+ * Requires `Authorization: Bearer <token>` for every access level that has a token. Levels without
+ * a token keep the default behavior: reads and writes are open, worker and operations routes 503.
+ */
+export declare function bearerAuth(tokens: BearerTokens): Authorize;

package/dist/runtime/server/auth.js

@@ -0,0 +1,40 @@
+import { Effect } from 'effect';
+export const authAllowed = { allowed: true };
+export function authDenied(status, error) {
+    return { allowed: false, status, error };
+}
+const unauthorized = authDenied(401, 'Unauthorized');
+function notConfigured(access) {
+    return authDenied(503, access === 'worker'
+        ? 'Worker callbacks are not configured'
+        : 'Operational endpoints are not configured');
+}
+/**
+ * Used when a host supplies no `authorize`: run reads and writes stay open, while worker callbacks
+ * and operational endpoints are unavailable until a host opts in.
+ */
+export const defaultAuthorize = (_request, route) => Effect.succeed(route.access === 'worker' || route.access === 'operations'
+    ? notConfigured(route.access)
+    : authAllowed);
+function constantTimeEquals(actual, expected) {
+    const length = Math.max(actual.length, expected.length);
+    let difference = actual.length ^ expected.length;
+    for (let index = 0; index < length; index += 1) {
+        difference |= (actual.charCodeAt(index) || 0) ^ (expected.charCodeAt(index) || 0);
+    }
+    return difference === 0;
+}
+/**
+ * Requires `Authorization: Bearer <token>` for every access level that has a token. Levels without
+ * a token keep the default behavior: reads and writes are open, worker and operations routes 503.
+ */
+export function bearerAuth(tokens) {
+    return (request, route) => {
+        const token = tokens[route.access];
+        if (token === undefined) {
+            return defaultAuthorize(request, route);
+        }
+        const header = request.headers.get('authorization') ?? '';
+        return Effect.succeed(constantTimeEquals(header, `Bearer ${token}`) ? authAllowed : unauthorized);
+    };
+}

package/dist/runtime/server/fetch-handler.d.ts

@@ -0,0 +1,14 @@
+import type { EventStore } from '@swirls/looms/core';
+import type { LoomsRuntime } from '../runtime';
+import { type Authorize } from './auth';
+export interface FetchHandlerOptions {
+    readonly runtime: LoomsRuntime;
+    readonly store: EventStore;
+    /**
+     * Decides whether a request may use a route. Defaults to open reads and writes with worker and
+     * operations routes unavailable; use `bearerAuth` or your own policy to change that.
+     */
+    readonly authorize?: Authorize;
+}
+export declare function isLoomsApiPath(path: string): boolean;
+export declare function createFetchHandler(options: FetchHandlerOptions): (req: Request) => Promise<Response | null>;

package/dist/runtime/server/fetch-handler.js

@@ -0,0 +1,51 @@
+import { Effect, Predicate } from 'effect';
+import { defaultAuthorize } from './auth.js';
+import { acceptsEventStream, toErrorResponse } from './http.js';
+import { matchRoute } from './route-table.js';
+import { effectRoutes } from './routes/effects.js';
+import { operationRoutes } from './routes/operations.js';
+import { runRoutes } from './routes/runs.js';
+function createRoutes(options) {
+    return [...runRoutes(options), ...effectRoutes(options), ...operationRoutes(options)];
+}
+function authorizeRoute(req, matched, authorize) {
+    const { access, name } = matched.route;
+    if (access === 'public') {
+        return Effect.succeed(null);
+    }
+    const runId = matched.params.runId;
+    return authorize(req, Predicate.isString(runId) ? { access, name, runId } : { access, name }).pipe(Effect.map((decision) => decision.allowed
+        ? null
+        : Response.json({ error: decision.error }, { status: decision.status })));
+}
+export function isLoomsApiPath(path) {
+    return (path === '/health' ||
+        path === '/runs' ||
+        path.startsWith('/runs/') ||
+        path.startsWith('/operations/'));
+}
+export function createFetchHandler(options) {
+    const routes = createRoutes(options);
+    const authorize = options.authorize ?? defaultAuthorize;
+    return (req) => {
+        const url = new URL(req.url);
+        if (!isLoomsApiPath(url.pathname)) {
+            return Promise.resolve(null);
+        }
+        const accept = req.headers.get('accept') ?? '';
+        if (req.method === 'GET' && accept.includes('text/html') && !acceptsEventStream(req)) {
+            return Promise.resolve(null);
+        }
+        return Effect.runPromise(Effect.gen(function* () {
+            const matched = matchRoute(routes, req.method, url.pathname);
+            if (!matched) {
+                return new Response('Not Found', { status: 404 });
+            }
+            const denied = yield* authorizeRoute(req, matched, authorize);
+            if (denied) {
+                return denied;
+            }
+            return yield* matched.route.handle({ req, url, params: matched.params });
+        }).pipe(Effect.catch((error) => Effect.succeed(toErrorResponse(error))), Effect.catchCause((cause) => Effect.logError('[@swirls/looms/runtime] request failed', cause).pipe(Effect.as(Response.json({ error: 'Internal server error' }, { status: 500 }))))));
+    };
+}

package/dist/runtime/server/http.d.ts

@@ -0,0 +1,37 @@
+import { Effect, Schema } from 'effect';
+import { EventStoreTag, type EventStore, type JsonValue } from '@swirls/looms/core';
+import { type LoomsRuntime } from '../runtime';
+export interface RouteOptions {
+    readonly runtime: LoomsRuntime;
+    readonly store: EventStore;
+}
+declare const RequestBodyError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RequestBodyError";
+} & Readonly<A>;
+export declare class RequestBodyError extends RequestBodyError_base<{
+    readonly cause: unknown;
+    readonly message: string;
+}> {
+    constructor(cause: unknown);
+}
+declare const RequestQueryError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RequestQueryError";
+} & Readonly<A>;
+export declare class RequestQueryError extends RequestQueryError_base<{
+    readonly message: string;
+}> {
+}
+export declare const EventInputBodySchema: Schema.Struct<{
+    readonly type: Schema.String;
+    readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly threadId: Schema.optional<Schema.NullOr<Schema.String>>;
+}>;
+export declare function provideStore<A, E>(effect: Effect.Effect<A, E, EventStoreTag>, store: EventStore): Effect.Effect<A, E>;
+export declare const readJson: (req: Request) => Effect.Effect<JsonValue, RequestBodyError>;
+export declare function extractIdempotencyKey(req: Request, bodyKey?: string): string | undefined;
+export declare function acceptsEventStream(req: Request): boolean;
+export declare function readIntegerQuery(url: URL, name: string, options: {
+    minimum: number;
+}): Effect.Effect<number | null, RequestQueryError>;
+export declare function toErrorResponse(err: Error): Response;
+export {};

package/dist/runtime/server/http.js

@@ -0,0 +1,62 @@
+import { Data, Effect, Schema } from 'effect';
+import { EventStoreTag, InvalidEventError, InvalidInputError, JsonValueSchema, } from '@swirls/looms/core';
+import { RunOverloadedError, StartRunConflictError } from '../runtime.js';
+export class RequestBodyError extends Data.TaggedError('RequestBodyError') {
+    constructor(cause) {
+        super({ cause, message: 'Invalid JSON request body' });
+        this.name = 'RequestBodyError';
+    }
+}
+export class RequestQueryError extends Data.TaggedError('RequestQueryError') {
+}
+export const EventInputBodySchema = Schema.Struct({
+    type: Schema.String,
+    payload: JsonValueSchema,
+    threadId: Schema.optional(Schema.NullOr(Schema.String)),
+});
+export function provideStore(effect, store) {
+    return Effect.provideService(effect, EventStoreTag, store);
+}
+export const readJson = (req) => Effect.tryPromise({
+    try: () => req.json(),
+    catch: (cause) => new RequestBodyError(cause),
+}).pipe(Effect.flatMap(Schema.decodeUnknownEffect(JsonValueSchema)), Effect.mapError((cause) => cause instanceof RequestBodyError ? cause : new RequestBodyError(cause)));
+export function extractIdempotencyKey(req, bodyKey) {
+    return (bodyKey ??
+        req.headers.get('idempotency-key') ??
+        req.headers.get('x-idempotency-key') ??
+        undefined);
+}
+export function acceptsEventStream(req) {
+    return (req.headers.get('accept') ?? '')
+        .split(',')
+        .some((value) => value.split(';', 1)[0]?.trim().toLowerCase() === 'text/event-stream');
+}
+export function readIntegerQuery(url, name, options) {
+    const raw = url.searchParams.get(name);
+    if (raw === null) {
+        return Effect.succeed(null);
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value < options.minimum || raw.trim() === '') {
+        return Effect.fail(new RequestQueryError({
+            message: `${name} must be an integer greater than or equal to ${options.minimum}`,
+        }));
+    }
+    return Effect.succeed(value);
+}
+export function toErrorResponse(err) {
+    if (err instanceof RequestBodyError || err instanceof RequestQueryError) {
+        return Response.json({ error: err.message }, { status: 400 });
+    }
+    if (err instanceof InvalidInputError || err instanceof InvalidEventError) {
+        return Response.json({ error: err.message, issues: err.issues }, { status: 400 });
+    }
+    if (err instanceof RunOverloadedError) {
+        return Response.json({ error: err.message }, { status: 429 });
+    }
+    if (err instanceof StartRunConflictError) {
+        return Response.json({ error: err.message, mismatches: err.mismatches }, { status: 409 });
+    }
+    return Response.json({ error: err.message }, { status: 500 });
+}

package/dist/runtime/server/route-table.d.ts

@@ -0,0 +1,55 @@
+import type { Effect } from 'effect';
+import type { RouteAccess } from './auth';
+export type ParamValue = string | number;
+/** Decodes one path segment, or returns null when the segment does not match. */
+export interface ParamDecoder<T extends ParamValue> {
+    decode(raw: string): T | null;
+}
+export declare const text: ParamDecoder<string>;
+export declare const integer: ParamDecoder<number>;
+export declare function oneOf<const T extends string>(values: readonly T[]): ParamDecoder<T>;
+type PathParamNames<TPath extends string> = TPath extends `${string}:${infer Param}/${infer Rest}` ? Param | PathParamNames<`/${Rest}`> : TPath extends `${string}:${infer Param}` ? Param : never;
+type ParamDecoders<TPath extends string> = {
+    readonly [K in PathParamNames<TPath>]?: ParamDecoder<ParamValue>;
+};
+type DecodedParams<TPath extends string, TDecoders> = {
+    readonly [K in PathParamNames<TPath>]: K extends keyof TDecoders ? TDecoders[K] extends ParamDecoder<infer T> ? T : string : string;
+};
+export interface RouteContext<TParams> {
+    readonly req: Request;
+    readonly url: URL;
+    readonly params: TParams;
+}
+export interface RouteDefinition<TPath extends string, TDecoders extends ParamDecoders<TPath>> {
+    readonly method: 'GET' | 'POST';
+    /** Path pattern such as `/runs/:runId/effects/:effectId`; parameters decode as text by default. */
+    readonly path: TPath;
+    readonly name: string;
+    readonly access: RouteAccess;
+    readonly params?: TDecoders;
+    handle(context: RouteContext<DecodedParams<TPath, TDecoders>>): Effect.Effect<Response, Error>;
+}
+type Segment = {
+    readonly kind: 'literal';
+    readonly value: string;
+} | {
+    readonly kind: 'param';
+    readonly name: string;
+    readonly decoder: ParamDecoder<ParamValue>;
+};
+export type RouteParams = Readonly<Record<string, ParamValue>>;
+export interface Route {
+    readonly method: 'GET' | 'POST';
+    readonly name: string;
+    readonly access: RouteAccess;
+    readonly segments: readonly Segment[];
+    handle(context: RouteContext<RouteParams>): Effect.Effect<Response, Error>;
+}
+export declare function route<const TPath extends string, const TDecoders extends ParamDecoders<TPath> = Record<never, never>>(definition: RouteDefinition<TPath, TDecoders>): Route;
+export interface MatchedRoute {
+    readonly route: Route;
+    readonly params: RouteParams;
+}
+/** First route, in table order, whose method and path match. */
+export declare function matchRoute(routes: readonly Route[], method: string, pathname: string): MatchedRoute | null;
+export {};

package/dist/runtime/server/route-table.js

@@ -0,0 +1,74 @@
+export const text = {
+    decode: (raw) => {
+        try {
+            return decodeURIComponent(raw);
+        }
+        catch {
+            return null;
+        }
+    },
+};
+export const integer = {
+    decode: (raw) => (/^\d+$/.test(raw) ? Number(raw) : null),
+};
+export function oneOf(values) {
+    return { decode: (raw) => values.find((value) => value === raw) ?? null };
+}
+export function route(definition) {
+    const decoders = definition.params ?? {};
+    const segments = definition.path
+        .split('/')
+        .slice(1)
+        .map((part) => {
+        if (!part.startsWith(':')) {
+            return { kind: 'literal', value: part };
+        }
+        const name = part.slice(1);
+        return { kind: 'param', name, decoder: decoders[name] ?? text };
+    });
+    // SAFETY: matchRoute only calls a route with every path parameter decoded by its decoders.
+    return {
+        method: definition.method,
+        name: definition.name,
+        access: definition.access,
+        segments,
+        handle: (context) => 
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        definition.handle(context),
+    };
+}
+function matchSegments(segments, parts) {
+    if (segments.length !== parts.length) {
+        return null;
+    }
+    const params = {};
+    for (const [index, segment] of segments.entries()) {
+        const part = parts[index];
+        if (segment.kind === 'literal') {
+            if (segment.value !== part) {
+                return null;
+            }
+            continue;
+        }
+        const value = segment.decoder.decode(part);
+        if (value === null) {
+            return null;
+        }
+        params[segment.name] = value;
+    }
+    return params;
+}
+/** First route, in table order, whose method and path match. */
+export function matchRoute(routes, method, pathname) {
+    const parts = pathname.split('/').slice(1);
+    for (const candidate of routes) {
+        if (candidate.method !== method) {
+            continue;
+        }
+        const params = matchSegments(candidate.segments, parts);
+        if (params) {
+            return { route: candidate, params };
+        }
+    }
+    return null;
+}

package/dist/runtime/server/routes/effects.d.ts

@@ -0,0 +1,3 @@
+import { type RouteOptions } from '../http';
+import { type Route } from '../route-table';
+export declare function effectRoutes({ runtime, store }: RouteOptions): readonly Route[];

package/dist/runtime/server/routes/effects.js

@@ -0,0 +1,59 @@
+import { Effect, Schema } from 'effect';
+import { EventInputBodySchema, provideStore, readJson } from '../http.js';
+import { integer, oneOf, route } from '../route-table.js';
+const WORKER_CALLBACK_KINDS = [
+    'started',
+    'heartbeat',
+    'complete',
+    'fail',
+    'cancelled',
+];
+const WorkerCallbackBodySchema = Schema.Struct({
+    events: Schema.optional(Schema.Array(EventInputBodySchema)),
+    error: Schema.optional(Schema.String),
+});
+function workerCallbackInput(params, body) {
+    const callback = { effectId: params.effectId, attempt: params.attempt };
+    switch (params.action) {
+        case 'complete':
+            return { ...callback, kind: 'complete', events: body.events ?? [] };
+        case 'fail':
+            return body.error ? { ...callback, kind: 'fail', error: body.error } : null;
+        default:
+            return { ...callback, kind: params.action };
+    }
+}
+export function effectRoutes({ runtime, store }) {
+    return [
+        route({
+            method: 'GET',
+            path: '/runs/:runId/effects',
+            name: 'effects.list',
+            access: 'read',
+            handle: ({ params }) => provideStore(runtime.inspectRun(params.runId), store).pipe(Effect.map((status) => Response.json({ runId: params.runId, effects: status.effects }))),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/effects/:effectId/retry',
+            name: 'effects.retry',
+            access: 'operations',
+            handle: ({ params }) => provideStore(runtime.retryEffect(params.runId, params.effectId), store).pipe(Effect.map((state) => Response.json({ runId: params.runId, effectId: params.effectId, state }))),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/effects/:effectId/:attempt/:action',
+            name: 'effects.workerCallback',
+            access: 'worker',
+            params: { attempt: integer, action: oneOf(WORKER_CALLBACK_KINDS) },
+            handle: ({ req, params }) => Effect.gen(function* () {
+                const body = yield* readJson(req).pipe(Effect.flatMap(Schema.decodeUnknownEffect(WorkerCallbackBodySchema)));
+                const input = workerCallbackInput(params, body);
+                if (!input) {
+                    return Response.json({ error: 'error required' }, { status: 400 });
+                }
+                const state = yield* provideStore(runtime.workerCallback(params.runId, input), store);
+                return Response.json({ runId: params.runId, state });
+            }),
+        }),
+    ];
+}

package/dist/runtime/server/routes/operations.d.ts

@@ -0,0 +1,3 @@
+import { type RouteOptions } from '../http';
+import { type Route } from '../route-table';
+export declare function operationRoutes({ runtime, store }: RouteOptions): readonly Route[];

package/dist/runtime/server/routes/operations.js

@@ -0,0 +1,14 @@
+import { Effect } from 'effect';
+import { provideStore } from '../http.js';
+import { route } from '../route-table.js';
+export function operationRoutes({ runtime, store }) {
+    return [
+        route({
+            method: 'POST',
+            path: '/operations/deadlines/rescan',
+            name: 'operations.rescanDeadlines',
+            access: 'operations',
+            handle: () => provideStore(runtime.recoverDeadlines, store).pipe(Effect.map((scheduled) => Response.json({ scheduled }))),
+        }),
+    ];
+}

package/dist/runtime/server/routes/runs.d.ts

@@ -0,0 +1,3 @@
+import { type RouteOptions } from '../http';
+import { type Route } from '../route-table';
+export declare function runRoutes({ runtime, store }: RouteOptions): readonly Route[];

package/dist/runtime/server/routes/runs.js

@@ -0,0 +1,192 @@
+import { Effect, Schema } from 'effect';
+import { createRunId, EventStoreTag, JsonValueSchema, stringifyJson, } from '@swirls/looms/core';
+import { createEventStreamResponse } from '../../sse.js';
+import { acceptsEventStream, EventInputBodySchema, extractIdempotencyKey, provideStore, readIntegerQuery, readJson, RequestQueryError, } from '../http.js';
+import { route } from '../route-table.js';
+const StartRunBodySchema = Schema.Struct({
+    kind: Schema.optional(Schema.String),
+    definitionName: Schema.optional(Schema.String),
+    definitionVersion: Schema.optional(Schema.String),
+    name: Schema.optional(Schema.String),
+    input: Schema.optional(JsonValueSchema),
+    runId: Schema.optional(Schema.String),
+    idempotencyKey: Schema.optional(Schema.String),
+});
+const SignalBodySchema = Schema.Struct({
+    events: Schema.optional(Schema.Array(EventInputBodySchema)),
+    type: Schema.optional(Schema.String),
+    payload: Schema.optional(JsonValueSchema),
+    threadId: Schema.optional(Schema.NullOr(Schema.String)),
+    idempotencyKey: Schema.optional(Schema.String),
+});
+function wantsRunStream(req, url) {
+    return url.searchParams.get('stream') === 'true' || acceptsEventStream(req);
+}
+function wantsEventStream(req, url) {
+    const live = url.searchParams.get('live');
+    return live === 'true' || live === '1' || acceptsEventStream(req);
+}
+function readEventStreamFromSeq(req, url) {
+    const lastEventId = req.headers.get('last-event-id');
+    if (lastEventId !== null && lastEventId.trim() !== '') {
+        const value = Number(lastEventId);
+        if (!Number.isSafeInteger(value) || value < 0) {
+            return Effect.fail(new RequestQueryError({
+                message: 'Last-Event-ID must be a non-negative integer',
+            }));
+        }
+        return Effect.succeed(value + 1);
+    }
+    return readIntegerQuery(url, 'fromSeq', { minimum: 1 }).pipe(Effect.map((fromSeq) => fromSeq ?? 1));
+}
+function streamStartRun(req, runtime, store, args) {
+    return createEventStreamResponse({
+        signal: req.signal,
+        request: req,
+        store,
+        runId: args.runId,
+        fromSeq: 1,
+        onStart: (write, close) => runtime
+            .startRun({
+            kind: args.kind,
+            definitionName: args.definitionName,
+            definitionVersion: args.definitionVersion,
+            input: args.input,
+            runId: args.runId,
+            idempotencyKey: args.idempotencyKey,
+        })
+            .pipe(Effect.provideService(EventStoreTag, store), Effect.tap((result) => Effect.sync(() => write(`event: done\ndata: ${stringifyJson(result)}\n\n`))), Effect.catch((error) => Effect.sync(() => write(`event: error\ndata: ${stringifyJson({ error: error.message })}\n\n`))), Effect.ensuring(Effect.sync(close)), Effect.asVoid),
+    });
+}
+export function runRoutes({ runtime, store }) {
+    return [
+        route({
+            method: 'GET',
+            path: '/health',
+            name: 'health',
+            access: 'public',
+            handle: () => Effect.succeed(Response.json({ ok: true })),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs',
+            name: 'runs.list',
+            access: 'read',
+            handle: () => provideStore(runtime.listRuns, store).pipe(Effect.map((runIds) => Response.json({ runIds }))),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs',
+            name: 'runs.start',
+            access: 'write',
+            handle: ({ req, url }) => Effect.gen(function* () {
+                const body = yield* readJson(req).pipe(Effect.flatMap(Schema.decodeUnknownEffect(StartRunBodySchema)));
+                const definitionName = body.definitionName ?? body.name;
+                const kind = body.kind;
+                if (!definitionName || !kind) {
+                    return Response.json({ error: 'kind and definitionName required' }, { status: 400 });
+                }
+                const runId = body.runId ?? createRunId();
+                const idempotencyKey = extractIdempotencyKey(req, body.idempotencyKey);
+                const args = {
+                    kind,
+                    definitionName,
+                    definitionVersion: body.definitionVersion,
+                    input: body.input ?? null,
+                    runId,
+                    idempotencyKey,
+                };
+                if (wantsRunStream(req, url)) {
+                    return streamStartRun(req, runtime, store, args);
+                }
+                const result = yield* provideStore(runtime.startRun(args), store);
+                return Response.json(result);
+            }),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/replay',
+            name: 'runs.replay',
+            access: 'read',
+            handle: ({ url, params }) => provideStore(runtime.replayTo(params.runId, Number(url.searchParams.get('seq') ?? '0')), store).pipe(Effect.map((step) => Response.json({ runId: params.runId, step }))),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/status',
+            name: 'runs.status',
+            access: 'read',
+            handle: ({ params }) => provideStore(runtime.inspectRun(params.runId), store).pipe(Effect.map((status) => Response.json(status))),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/projections/:projectionName',
+            name: 'runs.projection',
+            access: 'read',
+            handle: ({ params }) => {
+                const definition = runtime.registry.projections.get(params.projectionName);
+                if (!definition) {
+                    return Effect.succeed(Response.json({ error: `Unknown projection: ${params.projectionName}` }, { status: 404 }));
+                }
+                return provideStore(runtime.project(params.runId, definition), store).pipe(Effect.map((value) => Response.json({ runId: params.runId, name: params.projectionName, value })));
+            },
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/events',
+            name: 'runs.events',
+            access: 'read',
+            handle: ({ req, url, params }) => Effect.gen(function* () {
+                if (wantsEventStream(req, url)) {
+                    return createEventStreamResponse({
+                        signal: req.signal,
+                        request: req,
+                        store,
+                        runId: params.runId,
+                        fromSeq: yield* readEventStreamFromSeq(req, url),
+                    });
+                }
+                const fromSeq = (yield* readIntegerQuery(url, 'fromSeq', { minimum: 1 })) ?? undefined;
+                const limit = (yield* readIntegerQuery(url, 'limit', { minimum: 1 })) ?? undefined;
+                const events = yield* provideStore(runtime.getEvents(params.runId, { fromSeq, limit }), store);
+                return Response.json({ runId: params.runId, events }, { headers: { vary: 'accept' } });
+            }),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId/threads',
+            name: 'runs.threads',
+            access: 'read',
+            handle: ({ params }) => provideStore(runtime.getRun(params.runId), store).pipe(Effect.map((state) => Response.json({ runId: params.runId, threads: state.threads }))),
+        }),
+        route({
+            method: 'GET',
+            path: '/runs/:runId',
+            name: 'runs.get',
+            access: 'read',
+            handle: ({ params }) => provideStore(runtime.getRun(params.runId), store).pipe(Effect.map((state) => Response.json({ runId: params.runId, state }))),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/events',
+            name: 'runs.signal',
+            access: 'write',
+            handle: ({ req, params }) => Effect.gen(function* () {
+                const body = yield* readJson(req).pipe(Effect.flatMap(Schema.decodeUnknownEffect(SignalBodySchema)));
+                const events = body.events ??
+                    (body.type
+                        ? [{ type: body.type, payload: body.payload ?? null, threadId: body.threadId }]
+                        : []);
+                const idempotencyKey = extractIdempotencyKey(req, body.idempotencyKey);
+                const state = yield* provideStore(runtime.signal(params.runId, events, { idempotencyKey }), store);
+                return Response.json({ runId: params.runId, state });
+            }),
+        }),
+        route({
+            method: 'POST',
+            path: '/runs/:runId/wake',
+            name: 'runs.wake',
+            access: 'write',
+            handle: ({ params }) => provideStore(runtime.wake(params.runId), store).pipe(Effect.map((state) => Response.json({ runId: params.runId, state }))),
+        }),
+    ];
+}