@opengeni/api-router 0.30.1 → 1.0.0

package/dist/http/deprecation.d.ts

@@ -0,0 +1,42 @@
+import type { MiddlewareHandler } from "hono";
+/**
+ * A public `/v1` route whose current behaviour is scheduled for removal.
+ *
+ * See docs/design/api-compatibility-policy.md: a breaking change to the public
+ * surface is announced, advertised on every affected response with the
+ * standard `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers plus a
+ * `Link: rel="deprecation"` to the migration notes, and the old behaviour is
+ * kept for at least 90 days on the managed service or until the next major,
+ * whichever is later. Published SDKs surface these headers to the integrator.
+ */
+export type RouteDeprecation = {
+    /** Upper-case HTTP method. */
+    method: string;
+    /** The exact registered Hono template, e.g. `/v1/workspaces/:workspaceId/packs`. */
+    path: string;
+    /** When the deprecation was announced (ISO 8601). */
+    deprecatedAt: string;
+    /** Earliest removal on the managed service (ISO 8601). */
+    sunset: string;
+    /** Public migration notes (changelog/docs URL). */
+    link: string;
+    /** Optional successor route or document. */
+    successor?: string;
+};
+/**
+ * Every currently deprecated public route. Adding an entry here is the
+ * server-side half of a deprecation; the breaking change itself still needs an
+ * entry in scripts/public-api-breaking-changes.json and a new major.
+ */
+export declare const DEPRECATED_ROUTES: readonly RouteDeprecation[];
+/** Validate one registry entry; the policy's 90-day minimum is enforced here. */
+export declare function assertValidRouteDeprecation(deprecation: RouteDeprecation): void;
+/** The response headers that advertise one deprecation. */
+export declare function deprecationHeaders(deprecation: RouteDeprecation): Record<string, string>;
+/**
+ * Stamp deprecation headers on every response from a registered deprecated
+ * route, including error responses, so an integrator sees the notice whatever
+ * the call's outcome. Matching uses the registered route template, never
+ * request data.
+ */
+export declare function deprecationHeadersMiddleware(registry?: readonly RouteDeprecation[]): MiddlewareHandler;

package/dist/http/interaction-control-error.d.ts

@@ -0,0 +1,13 @@
+import { ErrorCode as AgentErrorCode } from "@opengeni/agent-proto";
+import { type InteractionControlFailureCode } from "@opengeni/contracts";
+import { ApiHttpError } from "./api-error.js";
+export type InteractionControlSurface = "browser" | "computer";
+/**
+ * Projects an internal connected-machine control fault into the public API
+ * vocabulary. This is deliberately an allowlist: the agent's free-form message
+ * and detail map may contain paths, process output, or provider diagnostics and
+ * never cross this boundary. The exact inner request id is safe opaque
+ * correlation and links API logs back to the machine operation.
+ */
+export declare function interactionControlApiError(error: unknown, surface: InteractionControlSurface): ApiHttpError | null;
+export declare function publicControlFailureCode(code: AgentErrorCode): InteractionControlFailureCode;

package/dist/http/keyed-admission.d.ts

@@ -0,0 +1,12 @@
+/**
+ * One token bucket per closed key, for anonymous beacon routes. It bounds
+ * counter inflation and log volume from any caller without per-client state.
+ */
+export type KeyedAdmission<Key extends string> = {
+    admit(key: Key): boolean;
+};
+export declare function createKeyedAdmission<Key extends string>(options?: {
+    capacity?: number;
+    refillPerSecond?: number;
+    now?: () => number;
+}): KeyedAdmission<Key>;

package/dist/http/local-browser-boundary.d.ts

@@ -0,0 +1,72 @@
+import { type Settings } from "@opengeni/config";
+/**
+ * Browser boundary for the unauthenticated local product mode.
+ *
+ * In `local` access mode every request without credentials acts as the local
+ * `dev` user, and the default local sandbox runs agent commands on the host.
+ * Binding the API to loopback keeps other devices out, but a web page open in
+ * the developer's browser can still reach `http://127.0.0.1:<port>`:
+ *
+ * - any site can send cross-origin requests to it (CORS only hides the
+ *   response; a simple POST still runs), and
+ * - a DNS-rebinding site can make its own hostname resolve to 127.0.0.1 and
+ *   read responses as a same-origin page.
+ *
+ * The boundary therefore sorts the `Host` a request is addressed to into two
+ * classes:
+ *
+ * - Browser hosts: loopback, the hosts of the configured web, public, and
+ *   extra origins, the GitHub App callback tunnel, and a specific API bind
+ *   address. A present `Origin` must be this stack's web app, an explicitly
+ *   configured origin, or the API's own address on one of these hosts.
+ * - Sandbox hosts: names only sandboxes and the worker use to reach the API
+ *   (`host.docker.internal` with the Docker sandbox, and the hosts of
+ *   `OPENGENI_MCP_URL` and `OPENGENI_MCP_INTERNAL_URL`). They serve only the
+ *   sandbox routes (Codemode, first-party MCP, and the Git broker) and refuse
+ *   any request that carries browser metadata. A browser cannot tell a
+ *   sandbox name from an attacker's, so a rebinding page on one of these
+ *   names can neither send an accepted `Origin` nor reach the rest of the API.
+ *
+ * Every other `Host` is refused. Non-browser clients (the SDK, curl, sandbox
+ * callbacks, host-app servers) send no `Origin` and are unaffected. The `Host`
+ * port is not compared: a rebinding page controls only the hostname, while
+ * local proxies and forwarders legitimately present their own port.
+ *
+ * It applies only to `local` access mode in the `local` environment (the
+ * `bun run dev` stack and manual local runs). Managed and configured access
+ * modes, and deployments that set another `OPENGENI_ENVIRONMENT`, keep their
+ * existing CORS policy.
+ */
+export type LocalBrowserBoundarySettings = Pick<Settings, "productAccessMode" | "environment" | "apiHost" | "webBaseUrl" | "publicBaseUrl" | "opengeniMcpUrl" | "opengeniMcpInternalUrl" | "githubAppManifestBaseUrl" | "localAllowedOrigins" | "sandboxBackend">;
+export type LocalBrowserBoundaryRejectionCode = "LOCAL_HOST_NOT_ALLOWED" | "LOCAL_ORIGIN_NOT_ALLOWED" | "LOCAL_SANDBOX_ROUTE_ONLY";
+export type LocalBrowserBoundaryRejection = {
+    status: 403;
+    code: LocalBrowserBoundaryRejectionCode;
+    message: string;
+    /** The refused `Host` or `Origin`, for the API log only; never sent back. */
+    refused: string;
+};
+/** Called once per distinct refused value, so an operator can see why. */
+export type LocalBrowserBoundaryWarn = (message: string, attributes: Record<string, string>) => void;
+export type LocalBrowserBoundary = {
+    readonly allowedOrigins: ReadonlySet<string>;
+    /** Hostnames a browser may address. */
+    readonly browserHostnames: ReadonlySet<string>;
+    /** Hostnames only sandboxes and the worker use; sandbox routes only, no browsers. */
+    readonly sandboxHostnames: ReadonlySet<string>;
+    /** Whether a present `Origin` may call the API for a request with this `Host`. */
+    originAllowed(origin: string, host: string | null): boolean;
+    /** The rejection for this request, or null when the boundary admits it. */
+    rejection(request: Request): LocalBrowserBoundaryRejection | null;
+};
+/** Mark a request the API dispatches to itself so the boundary admits it. */
+export declare function markLocalInternalDispatch(request: Request): Request;
+export declare function localBrowserBoundaryApplies(settings: Pick<Settings, "productAccessMode" | "environment">): boolean;
+/** Build the boundary, or null when the deployment is not the local dev product. */
+export declare function createLocalBrowserBoundary(settings: LocalBrowserBoundarySettings, options?: {
+    warn?: LocalBrowserBoundaryWarn;
+}): LocalBrowserBoundary | null;
+/** The standard API error envelope for a boundary rejection outside Hono. */
+export declare function localBrowserBoundaryResponse(rejection: LocalBrowserBoundaryRejection): Response;
+/** The `Host` the boundary checks: the header, else the request URL's authority. */
+export declare function localBrowserRequestHost(request: Request): string | null;

package/dist/http/metrics-listener.d.ts

@@ -0,0 +1,22 @@
+import type { Settings } from "@opengeni/config";
+import { Hono } from "hono";
+type PrometheusSource = {
+    prometheusMetrics(): Promise<string>;
+};
+/** Register the Prometheus exposition route on one Hono app. */
+export declare function registerPrometheusMetricsRoute(app: Hono, observability: PrometheusSource): void;
+/**
+ * Whether the public API listener serves `GET /metrics`. A deployment that sets
+ * `OPENGENI_API_METRICS_PORT` moves the exposition to a dedicated internal
+ * listener, so an ingress that forwards every path to the API cannot publish it.
+ */
+export declare function publicListenerServesMetrics(settings: Pick<Settings, "apiMetricsPort">): boolean;
+/**
+ * The dedicated metrics listener: only `GET /metrics`, behind the same
+ * deployment-key perimeter rules as the public listener. Nothing else is
+ * routed here, so exposing this port to a scraper exposes nothing else.
+ */
+export declare function createMetricsListenerApp(settings: Settings, observability: PrometheusSource): Hono;
+/** Start the dedicated listener when configured; returns undefined otherwise. */
+export declare function startApiMetricsListener(settings: Settings, observability: PrometheusSource): ReturnType<typeof Bun.serve> | undefined;
+export {};

package/dist/http/path-identifier.d.ts

@@ -0,0 +1,17 @@
+import { ApiHttpError } from "./api-error.js";
+/**
+ * A resource id taken verbatim from the URL path that is not a UUID cannot
+ * name any row. Routes pass such ids straight to PostgreSQL, which rejects the
+ * cast (SQLSTATE 22P02); that is a client addressing error, so answer 404
+ * instead of an unhandled 500.
+ *
+ * Deliberately narrow: only a uuid-syntax failure whose rejected text is
+ * exactly one of this request's own path segments qualifies. A malformed UUID
+ * produced by server code (a stored value, a derived subject, a body field)
+ * does not appear as a path segment and stays a genuine 500.
+ *
+ * Typical cause: a client built against a newer API calls a literal route
+ * (for example `.../scheduled-tasks/attention`) that an older server does not
+ * have, so the literal falls through to `.../scheduled-tasks/:taskId`.
+ */
+export declare function invalidPathIdentifierHttpError(error: unknown, pathname: string): ApiHttpError | null;

package/dist/http/registered-route-label.d.ts

@@ -0,0 +1,16 @@
+import type { Context } from "hono";
+/**
+ * The registered Hono path template of the handler that answers this request.
+ *
+ * Hono resolves every route matching a request before the first middleware
+ * runs, so the metrics middleware can read the exact code-owned template (for
+ * example `/v1/workspaces/:workspaceId/rigs/:rigId`) without re-implementing
+ * routing. Templates come only from route registrations, never from request
+ * data, so they are a closed and bounded metric/log label set.
+ *
+ * Middleware (arity two: `(context, next)`) and global catch-alls never name a
+ * route; the first matched terminal handler is the one Hono dispatches to.
+ */
+export declare function registeredHandlerRoutePath(context: Context): string | null;
+/** Normalize a registered template; drop catch-alls that would name nothing. */
+export declare function boundedRegisteredRouteLabel(path: string | null | undefined): string | null;

package/dist/http/request-body.d.ts

@@ -0,0 +1,27 @@
+import type { Context } from "hono";
+import type { z } from "zod";
+import { ZodError } from "zod";
+import { ApiHttpError } from "./api-error.js";
+/** Parse an already-read request body against its public request schema. */
+export declare function parseRequestBody<Schema extends z.ZodType>(schema: Schema, body: unknown): z.output<Schema>;
+/**
+ * Read the request body as JSON. Malformed JSON is a client error (400), never
+ * an unhandled `SyntaxError` 500. Other failures (body limit, aborted stream)
+ * keep their own mapping.
+ */
+export declare function readRequestJson(c: Context): Promise<unknown>;
+/** Read and validate a JSON request body in one step. */
+export declare function parseRequestJson<Schema extends z.ZodType>(c: Context, schema: Schema): Promise<z.output<Schema>>;
+/**
+ * Tag malformed-JSON failures of `c.req.json()` for this request. The same
+ * `SyntaxError` instance is rethrown so routes that already catch it keep
+ * their own mapping; an uncaught one becomes a 400 in `app.onError` instead of
+ * a 500. A `SyntaxError` from parsing stored or upstream data is never tagged.
+ */
+export declare function tagRequestJsonParseErrors(c: Context): void;
+export declare function isRequestBodyValidationError(error: unknown): error is ZodError | SyntaxError;
+/**
+ * Public 400 for a registered request-body validation failure, naming every
+ * offending field (bounded) so API callers can correct the request.
+ */
+export declare function requestBodyValidationHttpError(error: unknown): ApiHttpError | null;

package/dist/http/request-source.d.ts

@@ -0,0 +1,52 @@
+import { type Settings } from "@opengeni/config";
+import type { Context } from "hono";
+declare const TRANSPORT_PEER_ADDRESS_BINDING = "opengeniTransportPeerAddress";
+/** Returned when the runtime supplied no transport peer (for example an
+ * in-process test request). Callers treat it as one shared bucket. */
+export declare const UNKNOWN_REQUEST_SOURCE_ADDRESS = "unknown";
+/**
+ * App-owned request header carrying the server-resolved client address into
+ * Better Auth, which reads client addresses only from request headers. It is
+ * removed from every inbound request and re-stamped on managed-auth routes, so
+ * a caller-supplied value never reaches the auth rate limiter or session IP.
+ */
+export declare const TRUSTED_CLIENT_ADDRESS_HEADER = "x-opengeni-trusted-client-address";
+type ApiRequestBindings = {
+    [TRANSPORT_PEER_ADDRESS_BINDING]?: string | null;
+};
+/** The deployment's declared proxy chain (`OPENGENI_API_TRUSTED_PROXY_*`). */
+export type RequestSourceTrust = Pick<Settings, "apiTrustedProxyHops" | "apiTrustedProxyCidrs">;
+export declare function apiRequestBindingsForTransportPeer(address: string | null | undefined): ApiRequestBindings;
+/**
+ * Resolve a quota/audit source from the server-owned transport peer. Forwarded
+ * values are considered only when the operator declares an exact trusted proxy
+ * hop count (`OPENGENI_API_TRUSTED_PROXY_HOPS`) and, when
+ * `OPENGENI_API_TRUSTED_PROXY_CIDRS` is set, only for a transport peer inside
+ * those ranges. Each trusted proxy must append the address of the peer that
+ * connected to it, or overwrite the header with the original client address;
+ * the chain is then walked from the server side so caller-prepended values
+ * cannot replace the address observed by the trusted edge. A missing, short,
+ * or malformed chain falls back to the transport peer.
+ */
+export declare function trustedRequestSourceAddress(c: Context, trust: RequestSourceTrust): string;
+/**
+ * Rate-limit key for a trusted source address. An IPv6 address keys on its
+ * /64, the block one subscriber normally holds and the granularity Better
+ * Auth applies to the same stamped address, so rotating addresses inside one
+ * /64 cannot mint fresh buckets. An IPv4-mapped IPv6 address (how a
+ * dual-stack listener reports an IPv4 peer) keys on the embedded IPv4 address
+ * instead of collapsing every IPv4 client into one /64. Anything else,
+ * including {@link UNKNOWN_REQUEST_SOURCE_ADDRESS}, is returned unchanged.
+ */
+export declare function requestSourceRateLimitKey(address: string): string;
+/** {@link trustedRequestSourceAddress} as an application rate-limit key. */
+export declare function trustedRequestSourceRateLimitKey(c: Context, trust: RequestSourceTrust): string;
+/**
+ * Replace any caller-supplied {@link TRUSTED_CLIENT_ADDRESS_HEADER}. When
+ * `stamp` is true the header is set to the trusted source address, so every
+ * Better Auth request derived from this request (direct handler calls,
+ * isolated provider requests, and `auth.api.*` calls built from its headers)
+ * keys rate limits and session records on the real client.
+ */
+export declare function replaceTrustedClientAddressHeader(c: Context, trust: RequestSourceTrust, stamp: boolean): void;
+export {};

package/dist/http/sse.d.ts

@@ -5,6 +5,8 @@ import type { Observability } from "@opengeni/observability";
 export declare const SSE_QUEUED_FRAME_MAX_COUNT = 1;
 export declare const SSE_WRITE_STALL_TIMEOUT_MS = 30000;
 export declare const SSE_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const HTTP1_BROWSER_SSE_BATCH_MAX_BYTES: number;
+export declare const HTTP1_BROWSER_SSE_BATCH_CONTENT_TYPE = "application/vnd.opengeni.sse-batch";
 export type SseDeliveryBoundObservation = {
     reason: "desired_size_non_positive" | "stall_timeout" | "frame_too_large";
     desiredSize: number | null;
@@ -12,6 +14,7 @@ export type SseDeliveryBoundObservation = {
     queuedBytes: number;
 };
 export type ByteBoundedSseStreamOptions = {
+    connectionLifetimeMs?: number | undefined;
     maxQueuedBytes?: number;
     stallTimeoutMs?: number;
     onStop?: () => void;
@@ -30,11 +33,12 @@ export type ByteBoundedSseStream = {
  * checking `desiredSize` can still accumulate an unbounded server-side queue.
  *
  * One writer is expected per stream. The Web Streams queue holds at most one
- * complete frame, and that frame must fit inside the byte cap. A second write
+ * complete frame. One oversized frame is delivered intact rather than lost;
+ * the byte budget is a batching target, not a content limit. A second write
  * waits for consumer pull only for a bounded interval; cancellation or a stalled
  * reader wakes it and terminates upstream delivery before another durable page is
- * read. One frame is deliberate: it makes both queued-frame count and queued
- * bytes independently bounded instead of relying on byte accounting alone.
+ * read. One frame is deliberate: queued memory is bounded by one event, not
+ * by the size of the session, without imposing a lossy per-message limit.
  */
 export declare function createByteBoundedSseStream(options?: ByteBoundedSseStreamOptions): ByteBoundedSseStream;
 export type LatestWinsDelivery<T extends {
@@ -76,14 +80,21 @@ export declare function sseWorkspaceLiveStream(db: Database, bus: EventBus, acco
  */
 export declare function sseWorkspaceInteractionRevisionStream(db: Database, accountId: string, workspaceId: string, after: number, signal: AbortSignal, options?: WorkspaceInteractionSseOptions): Promise<Response>;
 export type SseDeliveryOptions = {
+    connectionLifetimeMs?: number | undefined;
+    /** Return a known-length batch instead of a chunked response. HTTP/1 only. */
+    finiteResponseMaxBytes?: number | undefined;
+    /** Browser transport classification for a finite response. */
+    finiteResponseMediaType?: "event-stream" | "http1-browser-batch" | undefined;
     maxQueuedBytes?: number;
     stallTimeoutMs?: number;
     heartbeatIntervalMs?: number;
     observability?: Observability | undefined;
     onObservation?: ((observation: SseDeliveryBoundObservation) => void) | undefined;
-};
-export type SessionSseDeliveryOptions = SseDeliveryOptions & {
-    /** Host ACL re-check, run even while the event stream is otherwise idle. */
+    /** Current ACL re-check, run even while the event stream is idle. */
     reauthorize?: (() => Promise<void>) | undefined;
     reauthorizeAfterMs?: number | undefined;
+    /** Exact selected actor emitted on the stream response for cross-tab fencing. */
+    actorEpoch?: string | undefined;
 };
+export declare function browserSseDeliveryOptions(transport: string | undefined): Pick<SseDeliveryOptions, "connectionLifetimeMs" | "finiteResponseMaxBytes" | "finiteResponseMediaType">;
+export type SessionSseDeliveryOptions = SseDeliveryOptions;

package/dist/http/unmatched-route.d.ts

@@ -0,0 +1,18 @@
+import type { Context, Hono } from "hono";
+export type UnmatchedRoute = {
+    status: 404;
+} | {
+    status: 405;
+    allow: string[];
+};
+/**
+ * Classify a request no registered handler can answer, BEFORE authentication
+ * or authorization middleware runs. Those layers otherwise turn a request for a
+ * route that does not exist into an authorization-shaped failure (for example
+ * the fail-closed session operation classifier answering a retryable 503), so
+ * a client probing an unknown method or path would be told to retry forever.
+ *
+ * Returns null when the request has a handler, or when classification itself
+ * fails (fail open: the request keeps its previous routing behavior).
+ */
+export declare function unmatchedRoute(app: Hono, c: Context): UnmatchedRoute | null;

package/dist/http/user-content.d.ts

@@ -0,0 +1,36 @@
+export declare const USER_CONTENT_SECURITY_POLICY = "default-src 'none'; img-src 'self' data: blob:; media-src 'self' data: blob:; style-src 'unsafe-inline'; sandbox";
+/** Media players only; scripts stay disabled (see the module comment). */
+export declare const USER_MEDIA_CONTENT_SECURITY_POLICY = "default-src 'none'; img-src 'self' data: blob:; media-src 'self' data: blob:; style-src 'unsafe-inline'; sandbox allow-same-origin";
+export declare const USER_CONTENT_SECURITY_HEADERS: Readonly<{
+    readonly "Content-Security-Policy": "default-src 'none'; img-src 'self' data: blob:; media-src 'self' data: blob:; style-src 'unsafe-inline'; sandbox";
+    readonly "Cross-Origin-Resource-Policy": "same-origin";
+    readonly "X-Content-Type-Options": "nosniff";
+}>;
+/**
+ * True when a browser would render this type as an active document (HTML,
+ * XHTML, SVG, any XML dialect, or multipart replacement streams). Anything that
+ * is not a clean `type/subtype` token is treated as active too.
+ */
+export declare function isActiveUserContentType(contentType: string): boolean;
+/** `Content-Disposition: attachment` for active markup; inline types are unchanged. */
+export declare function userContentDispositionHeaders(contentType: string, filename?: string | null): {
+    "Content-Disposition": string;
+} | Record<string, never>;
+/**
+ * Signed object-storage GET options for one stored object: active markup gets
+ * a signed `attachment` response override, so a browser that opens the URL
+ * downloads the bytes instead of rendering them with their stored type. The
+ * storage endpoint is not always a separate site (local development serves it
+ * from loopback, and a preview may route the bucket path on the app origin),
+ * so a signed URL follows the same rule as the API routes. Spread into
+ * `createGetUrl`; inline types add nothing.
+ */
+export declare function userContentSignedGetUrlOptions(contentType: string, filename?: string | null): {
+    responseContentDisposition: string;
+} | Record<string, never>;
+/** True for audio and video types the browser plays in a synthesized media document. */
+export declare function isPlayableMediaUserContentType(contentType: string): boolean;
+/** Sandbox policy for one response; only playable media keeps its origin. */
+export declare function userContentSecurityPolicy(contentType: string): string;
+/** Full header set for one user-content response with the given content type. */
+export declare function userContentResponseHeaders(contentType: string, filename?: string | null): Record<string, string>;

package/dist/http/websocket-upgrade-dispatch.d.ts

@@ -0,0 +1,18 @@
+import { type LocalBrowserBoundary } from "./local-browser-boundary.js";
+export type ApiWebSocketUpgradeRoute<Server> = {
+    handles(request: Request): boolean;
+    upgrade(request: Request, server: Server): Response | undefined;
+};
+export type ApiWebSocketUpgradeDispatch = {
+    handled: false;
+} | {
+    handled: true;
+    response: Response | undefined;
+};
+/**
+ * WebSocket upgrades bypass the Hono app, so the local-mode browser boundary
+ * (./local-browser-boundary.ts) is applied here before a transport upgrades.
+ * Returns `{ handled: false }` when no transport claims the request, so the
+ * caller dispatches it to the app, where the boundary runs as middleware.
+ */
+export declare function dispatchApiWebSocketUpgrade<Server>(request: Request, server: Server, routes: ReadonlyArray<ApiWebSocketUpgradeRoute<Server>>, localBrowserBoundary: LocalBrowserBoundary | null): ApiWebSocketUpgradeDispatch;

package/dist/index.d.ts

@@ -1,17 +1,24 @@
 import { getSettings } from "@opengeni/config";
 import type { ScheduledTaskOverlapPolicy, ScheduledTaskScheduleSpec } from "@opengeni/contracts";
 import { type Database } from "@opengeni/db";
+import { type Observability } from "@opengeni/observability";
 import { ScheduleOverlapPolicy } from "@temporalio/client";
 import type { ScheduleSpec } from "@temporalio/client";
 import { type DocumentIndexClient, type SessionWorkflowClient } from "./app.js";
-import { type EditableArtifactWebSocketConnection } from "./editable-artifact-websocket.js";
 export declare function createTemporalWorkflowClient(settings: ReturnType<typeof getSettings>, db: Database): Promise<{
     client: SessionWorkflowClient;
     documentIndexer: DocumentIndexClient;
     close: () => Promise<void>;
 }>;
-export declare function startApi(): Promise<{
-    server: Bun.Server<EditableArtifactWebSocketConnection>;
+export declare function startApi(options?: {
+    settings?: ReturnType<typeof getSettings>;
+    observability?: Observability;
+}): Promise<{
+    server: Bun.Server<Readonly<{
+        attach(socket: import("./api-websocket.js").ApiWebSocketLike): void;
+        receive(message: string | Uint8Array | ArrayBuffer): void;
+        transportClosed(): void;
+    }>>;
     close: () => Promise<void>;
 }>;
 export declare function temporalOverlapPolicy(policy: ScheduledTaskOverlapPolicy): ScheduleOverlapPolicy;