@opengeni/api-router 3.0.1 → 3.1.2

package/dist/organization-mcp.d.ts

@@ -0,0 +1,82 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type CallToolResult, type Icon } from "@modelcontextprotocol/sdk/types.js";
+import { type OrganizationAccessPolicy } from "@opengeni/contracts";
+import { z } from "zod";
+import type { ActionCatalogEntry } from "./mcp/action-catalog-types.js";
+export type OrganizationMcpCaller = {
+    kind: "person";
+    accountId: string;
+    subjectId: string;
+    access: OrganizationAccessPolicy;
+} | {
+    kind: "key";
+    authorization: string;
+    accessKey: string | null;
+};
+/**
+ * Requests that only read but are sent as POST (a search query or a file path
+ * in the body). Read only connections may run them; each route still checks
+ * its own read permission.
+ */
+export declare const READ_ONLY_POST_ACTIONS: ReadonlySet<string>;
+export declare const OrganizationActionSearchInput: z.ZodObject<{
+    query: z.ZodDefault<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    offset: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const OrganizationActionDescribeInput: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strict>;
+export declare const OrganizationActionCallInput: z.ZodObject<{
+    id: z.ZodString;
+    pathParameters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    query: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
+    body: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+/**
+ * MCP `serverInfo.icons` (spec 2025-11-25). Self-contained data URIs work for
+ * every deployment; the web app's PNG is added when its public origin is known.
+ */
+export declare function organizationMcpIcons(publicOrigin: string | null): Icon[];
+export type OrganizationActionContext = {
+    caller: OrganizationMcpCaller;
+    /** This API's own origin; the call never leaves the process. */
+    origin: string;
+    /** The web app's public origin, when configured; serves the PNG icon. */
+    publicOrigin?: string | null;
+    dispatch: (request: Request) => Promise<Response>;
+    signal?: AbortSignal;
+};
+export declare function buildOrganizationMcpServer(input: OrganizationActionContext): Server;
+export declare function findAction(id: string): ActionCatalogEntry | undefined;
+export declare function searchActions(input: {
+    query: string;
+    limit: number;
+    offset: number;
+}): {
+    total: number;
+    offset: number;
+    actions: {
+        id: string;
+        method: string;
+        path: string;
+        description?: string;
+    }[];
+};
+/** The describe tool's answer for an action id, or why it can't be used. */
+export declare function describeActionResult(id: string): CallToolResult;
+export declare function describeAction(entry: ActionCatalogEntry): {
+    id: string;
+    method: string;
+    path: string;
+    description?: string;
+    pathParameters: string[];
+    input: {
+        name: string;
+        in: string;
+        schema: unknown;
+    }[];
+    response: string[];
+};
+/** Run one public action in process as the caller; the route's own checks decide. */
+export declare function callOrganizationAction(context: OrganizationActionContext, input: z.infer<typeof OrganizationActionCallInput>): Promise<CallToolResult>;

package/dist/prepared-mcp-actor.d.ts

@@ -0,0 +1,77 @@
+import type { ConnectAttempt } from "@opengeni/contracts/connect";
+import { type Database } from "@opengeni/db";
+import { type AccessGrantAuthorization, type ApiRouteDeps } from "@opengeni/core";
+/** The normal browser and the exact agent attempt share Connect storage and
+ * verification. This adapter is ONLY for prepared MCP keys, never interactive
+ * OAuth, arbitrary native connections, or a caller-supplied owner identity. */
+export declare function connectRequestActor(deps: ApiRouteDeps, authorization: AccessGrantAuthorization): Promise<{
+    scope: {
+        accountId: string;
+        workspaceId: string;
+        subjectId: string;
+        personalOwnerVerified: boolean;
+        externalContinuation?: {
+            identity: {
+                externalId: string;
+                source: string;
+            };
+            actor: {
+                accountId: string;
+                authenticatingApiKeyId: string;
+                externalIdentityId: string;
+                externalSubjectId: string;
+                externalAuthorizationRevision: number;
+                effectiveSubjectId: string;
+                actingMode: "external" | "linked_native";
+                linkId?: string | undefined;
+                linkRevision?: number | undefined;
+            };
+        };
+    };
+    grant: {
+        workspaceId: string;
+        accountId: string;
+        subjectId: string;
+        subjectLabel?: string | undefined;
+        permissions: ("account:admin" | "account:read" | "api_keys:manage" | "artifacts:publish" | "artifacts:read" | "billing:manage" | "billing:read" | "capabilities:manage" | "codemode:call" | "connections:read" | "connections:write" | "documents:manage" | "documents:search" | "enrollments:manage" | "enrollments:read" | "environments:manage" | "environments:use" | "files:read" | "files:upload" | "files:write" | "github:manage" | "github:use" | "goals:manage" | "mcp_servers:attach" | "members:manage" | "rigs:manage" | "rigs:use" | "scheduled_tasks:manage" | "scheduled_tasks:run" | "secrets:list" | "secrets:read" | "secrets:use" | "secrets:write" | "sessions:control" | "sessions:create" | "sessions:read" | "stream:acknowledge" | "stream:control" | "stream:view" | "terminal:attach" | "usage_allowances:manage" | "variable-sets:attach" | "variable-sets:list" | "variable-sets:manage" | "variable-sets:read" | "variable-sets:use" | "variable-sets:write" | "workspace:admin" | "workspace:create" | "workspace:read")[];
+        permissionMode?: "explicit" | "legacy" | undefined;
+        principalKind?: "agent_attempt" | "api_key" | "configured_key" | "human_session" | "service" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        serviceInitiator?: {
+            kind: "service";
+            subjectId: string;
+            label?: string | undefined;
+        } | undefined;
+        serviceInitiatorContext?: Record<string, unknown> | undefined;
+    };
+    beforeOperation: undefined;
+    preparedOnly: boolean;
+} | {
+    scope: {
+        accountId: string;
+        workspaceId: string;
+        subjectId: string;
+        personalOwnerVerified: boolean;
+    };
+    grant: {
+        workspaceId: string;
+        accountId: string;
+        subjectId: string;
+        subjectLabel?: string | undefined;
+        permissions: ("account:admin" | "account:read" | "api_keys:manage" | "artifacts:publish" | "artifacts:read" | "billing:manage" | "billing:read" | "capabilities:manage" | "codemode:call" | "connections:read" | "connections:write" | "documents:manage" | "documents:search" | "enrollments:manage" | "enrollments:read" | "environments:manage" | "environments:use" | "files:read" | "files:upload" | "files:write" | "github:manage" | "github:use" | "goals:manage" | "mcp_servers:attach" | "members:manage" | "rigs:manage" | "rigs:use" | "scheduled_tasks:manage" | "scheduled_tasks:run" | "secrets:list" | "secrets:read" | "secrets:use" | "secrets:write" | "sessions:control" | "sessions:create" | "sessions:read" | "stream:acknowledge" | "stream:control" | "stream:view" | "terminal:attach" | "usage_allowances:manage" | "variable-sets:attach" | "variable-sets:list" | "variable-sets:manage" | "variable-sets:read" | "variable-sets:use" | "variable-sets:write" | "workspace:admin" | "workspace:create" | "workspace:read")[];
+        permissionMode?: "explicit" | "legacy" | undefined;
+        principalKind?: "agent_attempt" | "api_key" | "configured_key" | "human_session" | "service" | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        serviceInitiator?: {
+            kind: "service";
+            subjectId: string;
+            label?: string | undefined;
+        } | undefined;
+        serviceInitiatorContext?: Record<string, unknown> | undefined;
+    };
+    beforeOperation: (tx: Database) => Promise<void>;
+    preparedOnly: boolean;
+}>;
+export declare function assertAgentPreparedConnect(actor: {
+    preparedOnly: boolean;
+}, attempt: Pick<ConnectAttempt, "providerId" | "mcpSetup">): void;

package/dist/prepared-mcp-permissions.d.ts

@@ -0,0 +1,8 @@
+import type { AttemptToolCatalog, Permission } from "@opengeni/contracts";
+export declare const PREPARED_MCP_PERMISSIONS: readonly ["connections:read", "connections:write", "capabilities:manage"];
+/** Only the existing native Connect resource can receive setup permissions.
+ * This never expands SDK access to unrelated credential or settings routes. */
+export declare function isPreparedMcpConnectPath(path: string, method: string): boolean;
+/** The accepted tool must be present without an outstanding human-review gate.
+ * A session/settings edit can remove authority but cannot add it to this attempt. */
+export declare function preparedMcpProxyPermissions(catalog: AttemptToolCatalog, livePermissions: readonly Permission[]): Permission[];

package/dist/routes/analytics-consent.d.ts

@@ -0,0 +1,26 @@
+import type { Settings } from "@opengeni/config";
+import { ANALYTICS_CONSENT_DECISIONS, ANALYTICS_CONSENT_PATH, type AnalyticsConsentDecision } from "@opengeni/contracts/analytics-consent-report";
+import type { Observability } from "@opengeni/observability";
+import type { Hono } from "hono";
+import { z } from "zod";
+import { type KeyedAdmission } from "../http/keyed-admission.js";
+export { ANALYTICS_CONSENT_DECISIONS, ANALYTICS_CONSENT_PATH, type AnalyticsConsentDecision };
+export declare const AnalyticsConsentReport: z.ZodObject<{
+    decision: z.ZodEnum<{
+        denied: "denied";
+        granted: "granted";
+    }>;
+}, z.core.$strict>;
+export type AnalyticsConsentReport = z.infer<typeof AnalyticsConsentReport>;
+export type AnalyticsConsentAdmission = KeyedAdmission<AnalyticsConsentDecision>;
+export declare function parseAnalyticsConsentReport(body: string | null): AnalyticsConsentReport | null;
+/**
+ * The exact beacon request. The app-wide request-body limit skips it because
+ * the route enforces its own small limit on the streamed body.
+ */
+export declare function isAnalyticsConsentReportRequest(method: string, pathname: string): boolean;
+export declare function registerAnalyticsConsentRoutes(app: Hono, deps: {
+    observability: Observability;
+    settings: Pick<Settings, "corsAllowOriginRegex" | "publicBaseUrl" | "webBaseUrl">;
+    admission?: AnalyticsConsentAdmission;
+}): void;

package/dist/routes/api-integrations.d.ts

@@ -12,10 +12,21 @@ export declare function apiIntegrationRequiresConnection(authScheme: Record<stri
 /** Shared native/embedded install validation. The caller must still authorize
  * capabilities:manage and commit under its own live-authority boundary. */
 export declare function validatedIntegrationInstallInput(grant: AccessGrant, workspaceId: string, payload: InstallApiIntegrationRequest, resolved: ResolvedApiIntegrationPreview): Parameters<typeof installApiIntegration>[1];
+/**
+ * `allowedTools` names tools by their preview `id`, the stable identity the
+ * install persists. Reject anything else as a client error that lists the
+ * valid ids; a caller that sent a preview `operationKey` is told which id it
+ * maps to rather than having it silently reinterpreted.
+ */
+export declare function validatedAllowedToolIds(allowedTools: readonly string[], tools: readonly {
+    id: string;
+    operationKey: string;
+}[]): string[];
 export declare function registerApiIntegrationRoutes(app: Hono, deps: ApiRouteDeps, overrides?: ApiIntegrationRouteOverrides): void;
 export declare function resolveForRoute(input: {
     deps: ApiRouteDeps;
     transport: ReturnType<typeof createPinnedIntegrationTransport>;
+    accountId: string;
     workspaceId: string;
     subjectId: string;
     payload: PreviewApiIntegrationRequest | InstallApiIntegrationRequest;

package/dist/routes/api-keys.d.ts

@@ -1,6 +1,7 @@
-import { Permission, type OrganizationApiKeyAccess } from "@opengeni/contracts";
+import { CreateOrganizationApiKeyRequest, Permission, type AccessContext, type OrganizationApiKeyAccess } from "@opengeni/contracts";
 import type { Hono } from "hono";
 import type { ApiRouteDeps } from "@opengeni/core";
+export { organizationApiKeyAccess } from "@opengeni/core";
 /** Permissions minted onto a `full` organization API key. */
 export declare const organizationApiKeyPermissions: Permission[];
 /**
@@ -11,10 +12,9 @@ export declare const organizationApiKeyPermissions: Permission[];
  */
 export declare const organizationReadApiKeyPermissions: Permission[];
 export declare function organizationApiKeyPermissionsForAccess(access: OrganizationApiKeyAccess): Permission[];
-/**
- * The access tier is derived from stored permissions rather than a column: a
- * key that carries the `workspace:admin` wildcard administers the
- * organization, any other organization key is read-only.
- */
-export declare function organizationApiKeyAccess(permissions: Permission[]): OrganizationApiKeyAccess;
+/** Existing callers retain their expiry; setup keys default to one day. */
+export declare function organizationApiKeyExpiryDate(request: Pick<CreateOrganizationApiKeyRequest, "preset" | "expiresAt"> & Partial<Pick<CreateOrganizationApiKeyRequest, "access">>, now?: Date): Date | null;
 export declare function registerApiKeyRoutes(app: Hono, deps: ApiRouteDeps): void;
+/** Service account problems read as the person would expect. */
+export declare function throwServiceAccountError(error: unknown): void;
+export declare function requireOrganizationApiKeyControlPermission(context: AccessContext, organizationId: string): void;

package/dist/routes/automations.d.ts

@@ -7,6 +7,8 @@ export declare function acceptAutomationEvent(deps: ApiRouteDeps, source: Automa
     deliveryKey: string;
     requestDigest: string;
     normalizedEvent: AutomationNormalizedEvent;
+    /** Canonical manual caller restriction, not normalized event metadata. */
+    credentialRestriction?: "developer_setup";
 }): Promise<{
     accepted: boolean;
     duplicate: boolean;

package/dist/routes/billing.d.ts

@@ -1,3 +1,4 @@
+import { type AccessContext, type Permission, type PromotionalCreditScope } from "@opengeni/contracts";
 import type { Hono } from "hono";
 import Stripe from "stripe";
 import type { ApiRouteDeps } from "@opengeni/core";
@@ -9,13 +10,71 @@ export declare function stripeCheckoutSessionCreateParams(input: {
     amountMicros: number;
     creditsProductId?: string | undefined;
     publicBaseUrl?: string | undefined;
+    webBaseUrl?: string | undefined;
     successUrl?: string | undefined;
     cancelUrl?: string | undefined;
     idempotencyKey: string;
+    /** Apply this promotion code up front instead of letting Stripe ask for one. */
+    promotionCodeId?: string | undefined;
+    couponId?: string | undefined;
+    promotionalScope?: PromotionalCreditScope | undefined;
+    /**
+     * The applied code covers the whole package, so the total is $0. Nothing is
+     * taxable, so Checkout skips tax and with it the billing address: the
+     * customer only confirms.
+     */
+    fullyDiscounted?: boolean | undefined;
 }): Stripe.Checkout.SessionCreateParams;
 export declare function stripeBillingPortalSessionCreateParams(input: {
     customerId: string;
     publicBaseUrl?: string | undefined;
+    webBaseUrl?: string | undefined;
     returnUrl?: string | undefined;
 }): Stripe.BillingPortal.SessionCreateParams;
+export type StripeCheckoutCreditDecision = {
+    action: "grant";
+    credit: CheckoutCreditMetadata;
+} | {
+    action: "ignore";
+    reason: "foreign_checkout" | "not_payment_mode" | "payment_not_paid";
+};
+/**
+ * Decides whether a Checkout Session webhook grants Opengeni credits.
+ *
+ * Sessions created outside Opengeni on the same Stripe account carry no
+ * `opengeni_` metadata and are acknowledged without effect. An Opengeni
+ * session with malformed credit metadata still throws so the failure stays
+ * visible. Credits are granted once Stripe reports the payment `paid` or a
+ * completed checkout fully covered by a coupon:
+ * on `checkout.session.completed` for immediate methods, or on
+ * `checkout.session.async_payment_succeeded` for delayed methods, whose
+ * completion event arrives `unpaid`. Both events carry the same session
+ * metadata, so the ledger idempotency key grants at most once.
+ */
+export declare function stripeCheckoutCreditDecision(session: Stripe.Checkout.Session): StripeCheckoutCreditDecision;
+/**
+ * One paid credit purchase (a `credit_topup` ledger row from a Stripe
+ * checkout). Fully discounted coupon checkouts are grants, not purchases, and
+ * are counted by `opengeni_credit_granted_micros_total{grant_class="coupon"}`.
+ * Labels are the closed `mode` (live | test) only; never an account or
+ * customer identifier.
+ */
+export declare function recordCreditPurchaseMetrics(observability: ApiRouteDeps["observability"], input: {
+    livemode: boolean;
+    creditMicros: number;
+    currency: string | null | undefined;
+    amountTotal: number | null | undefined;
+}): void;
+export type CheckoutCreditMetadata = {
+    accountId: string;
+    amountMicros: number;
+    idempotencyKey: string;
+    amountUsd?: string;
+    packageId?: string;
+};
 export declare function stripeCustomerProvider(input: ApiRouteDeps | Stripe.Event): "stripe:live" | "stripe:test";
+/** Billing routes do not traverse the workspace actor middleware. Always bind
+ * these reads explicitly; only a revalidated live attempt may supply a human
+ * initiator. Neither query parameters nor serviceInitiator claims are proof. */
+export declare function withBillingUsageActor<T>(deps: ApiRouteDeps, context: AccessContext, accountId: string, read: () => Promise<T>): Promise<T>;
+export declare function requireSelectedAccount(context: AccessContext, requested: string | undefined, permission: Permission): string;

package/dist/routes/browser-sessions.d.ts

@@ -1,12 +1,75 @@
-import { InteractionActor, type AccessGrant, type FileAsset } from "@opengeni/contracts";
+import { InteractionActor, type AccessGrant, type FileAsset, type CreateBrowserSessionRequest as CreateBrowserSessionRequestValue, type InteractionPlacement } from "@opengeni/contracts";
 import { type ApiRouteDeps, type ResolvedSessionAuthorization } from "@opengeni/core";
+import { type BrowserControlScreenshotOptions, type BrowserControlFrame } from "@opengeni/runtime/sandbox";
 import type { Hono } from "hono";
-export declare function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps): void;
+import { type InteractionSecretsPort } from "../interaction-secrets.js";
+export declare function registerBrowserSessionRoutes(app: Hono, deps: ApiRouteDeps, options?: {
+    interactionSecrets?: InteractionSecretsPort | null;
+}): void;
+export declare function browserCreateInput(grant: AccessGrant, workspaceId: string, request: CreateBrowserSessionRequestValue, placement: InteractionPlacement): {
+    accountId: string;
+    workspaceId: string;
+    operationId: string;
+    associatedSessionId: string;
+    actorSubjectId: string;
+    name: string;
+    initialUrl: string | null;
+    placement: {
+        kind: "sandbox_group";
+        sandboxGroupId: string;
+    } | {
+        kind: "connected_machine";
+        sandboxId: string;
+    } | {
+        kind: "attached_device";
+        deviceId: string;
+    } | {
+        kind: "external_provider";
+        providerId: string;
+        placementId: string;
+    };
+    driverId: string;
+    engine: "chrome" | "chromium" | "external" | "lightpanda";
+    headless: boolean;
+    identityId: string | null;
+    baseRevisionId: string | null;
+    networkRouteId: string | null;
+    linkedComputerSessionId: string | null;
+    resolveDefaultRevision: boolean;
+    capabilities?: {
+        semanticObservation: boolean;
+        screenshots: boolean;
+        liveFrames: boolean;
+        humanInput: boolean;
+        tabs: boolean;
+        downloads: boolean;
+        uploads: boolean;
+        clipboard: boolean;
+        permissions: boolean;
+        diagnostics: boolean;
+        rawCdp: boolean;
+        linkedComputer: boolean;
+        privateCheckpoint: boolean;
+        identityPublication: boolean;
+        parallelTargets: boolean;
+    };
+};
 export declare function browserNeedsStandaloneDisplayStack(input: {
     headless: boolean;
     linkedComputer: boolean;
     nativeBrowserControl: boolean;
 }): boolean;
+export declare function parseBrowserScreenshotOptions(query: URLSearchParams): BrowserControlScreenshotOptions;
+/** Preserve the controller's definite tab diagnosis (a tab that stopped
+ * answering, or one whose renderer crashed) through the public API with its
+ * own code and guidance. Any other controller failure keeps the ordinary
+ * envelope, which never publishes driver diagnostics. This only handles typed
+ * read/pre-dispatch failures. Dispatched action uncertainty stays in the
+ * action receipt, never relabeled as a safe retry. */
+export declare function browserTabDiagnosisError(error: unknown): unknown;
+/** Keep a definite read timeout useful without publishing driver diagnostics. */
+export declare function browserScreenshotError(error: unknown): unknown;
+export declare function browserScreenshotResponse(frame: Pick<BrowserControlFrame, "data" | "mediaType" | "metadataHeader">): Response;
 export declare function interactionActorForGrant(grant: AccessGrant): ReturnType<typeof InteractionActor.parse>;
 /** Resolve Drive authority from the same immutable session authorization that
  * admitted the browser action. Agent-attempt subjects are technical worker

package/dist/routes/chat-completions.d.ts

@@ -0,0 +1,11 @@
+import { type ApiRouteDeps, type ModelCallService } from "@opengeni/core";
+import type { Hono } from "hono";
+/**
+ * OpenAI-compatible stateless model calls. A stock OpenAI SDK works with its
+ * base URL set to `/v1/workspaces/{workspaceId}` and an Opengeni API key.
+ * Running one costs what the same model call costs inside a session, and
+ * requires the same `sessions:create` authority.
+ */
+export declare function registerChatCompletionRoutes(app: Hono, deps: ApiRouteDeps & {
+    modelCalls: ModelCallService | null;
+}): void;

package/dist/routes/claude-core-usage.d.ts

@@ -0,0 +1,20 @@
+import type { Context } from "hono";
+import type { ClaudeSubscriptionUsage } from "@opengeni/contracts";
+import type { ApiRouteDeps } from "@opengeni/core";
+/** An authenticated usage caller whose organization serves Claude from the core. */
+export type CoreClaudeUsageCaller = {
+    core: true;
+    accountId: string;
+    /** Null on the organization path. */
+    workspaceId: string | null;
+    subjectId: string;
+    /** The route's account id: a canonical connection id or a cutover alias. */
+    accountIdParam: string;
+};
+/**
+ * Require Claude's core route for an authenticated usage caller. Missing or
+ * disabled receipts fail closed with the typed 503 the Codex routes use.
+ */
+export declare function claudeUsageRoute(deps: ApiRouteDeps, accountId: string, workspaceId: string | null): Promise<"core">;
+/** GET or POST refresh of one Claude account's usage on the core. */
+export declare function coreClaudeUsage(c: Context, deps: ApiRouteDeps, caller: CoreClaudeUsageCaller, mutation: boolean): Promise<ClaudeSubscriptionUsage>;

package/dist/routes/claude-subscription-accounts.d.ts

@@ -0,0 +1,3 @@
+import type { ApiRouteDeps } from "@opengeni/core";
+import type { Hono } from "hono";
+export declare function registerClaudeSubscriptionAccountRoutes(app: Hono, deps: ApiRouteDeps): void;

package/dist/routes/claude-subscription-oauth.d.ts

@@ -0,0 +1,3 @@
+import { type ApiRouteDeps } from "@opengeni/core";
+import { type Hono } from "hono";
+export declare function registerClaudeSubscriptionOAuthRoutes(app: Hono, deps: ApiRouteDeps, fetchImpl?: typeof fetch): void;

package/dist/routes/client-errors.d.ts

@@ -0,0 +1,182 @@
+import type { Settings } from "@opengeni/config";
+import { CLIENT_ERROR_KINDS, CLIENT_ERROR_REPORT_MAX_BYTES, CLIENT_ERRORS_PATH, type ClientErrorDetail, type ClientErrorKind } from "@opengeni/contracts/client-error-report";
+import type { Observability } from "@opengeni/observability";
+import type { Hono } from "hono";
+import { z } from "zod";
+import { type KeyedAdmission } from "../http/keyed-admission.js";
+export { CLIENT_ERROR_KINDS, CLIENT_ERROR_REPORT_MAX_BYTES, CLIENT_ERRORS_PATH, type ClientErrorKind, };
+export declare const ClientErrorReport: z.ZodPipe<z.ZodObject<{
+    kind: z.ZodEnum<{
+        chunk_load: "chunk_load";
+        route_error: "route_error";
+        unhandled_rejection: "unhandled_rejection";
+        window_error: "window_error";
+    }>;
+    route: z.ZodString;
+    revision: z.ZodString;
+    error: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        stack: z.ZodOptional<z.ZodString>;
+        componentStack: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodTransform<{
+    kind: "chunk_load" | "route_error" | "unhandled_rejection" | "window_error";
+    route: string;
+    revision: string;
+} | {
+    kind: "chunk_load" | "route_error" | "unhandled_rejection" | "window_error";
+    route: string;
+    revision: string;
+    error: Partial<Record<"componentStack" | "message" | "name" | "stack", string>>;
+}, {
+    kind: "chunk_load" | "route_error" | "unhandled_rejection" | "window_error";
+    route: string;
+    revision: string;
+    error?: {
+        name?: string | undefined;
+        message?: string | undefined;
+        stack?: string | undefined;
+        componentStack?: string | undefined;
+    } | undefined;
+}>>;
+export type ClientErrorReport = {
+    kind: ClientErrorKind;
+    route: string;
+    revision: string;
+    error?: ClientErrorDetail;
+};
+export declare const ClientSignalReport: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    signal: z.ZodLiteral<"request_failure">;
+    action: z.ZodEnum<{
+        checkout_start: "checkout_start";
+        composer_submit: "composer_submit";
+        connect_integration: "connect_integration";
+        connect_model: "connect_model";
+        create_session: "create_session";
+        retry_turn: "retry_turn";
+        send_message: "send_message";
+        steer_message: "steer_message";
+    }>;
+    reason: z.ZodEnum<{
+        network: "network";
+        offline: "offline";
+        timeout: "timeout";
+    }>;
+    route: z.ZodString;
+    revision: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    signal: z.ZodLiteral<"stream">;
+    stream: z.ZodEnum<{
+        session: "session";
+        workspace: "workspace";
+    }>;
+    event: z.ZodEnum<{
+        long_disconnect: "long_disconnect";
+        reconnect: "reconnect";
+        reconnect_exhausted: "reconnect_exhausted";
+    }>;
+    route: z.ZodString;
+    revision: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    signal: z.ZodLiteral<"web_vital">;
+    metric: z.ZodEnum<{
+        cls: "cls";
+        inp: "inp";
+        lcp: "lcp";
+        ttfb: "ttfb";
+    }>;
+    page: z.ZodEnum<{
+        "account-auth": "account-auth";
+        agents: "agents";
+        artifacts: "artifacts";
+        capabilities: "capabilities";
+        "checkout-return": "checkout-return";
+        "connect-agent": "connect-agent";
+        device: "device";
+        documents: "documents";
+        environments: "environments";
+        files: "files";
+        home: "home";
+        "identity-link": "identity-link";
+        inbox: "inbox";
+        insights: "insights";
+        "integration-return": "integration-return";
+        machines: "machines";
+        memory: "memory";
+        "native-sign-in": "native-sign-in";
+        organization: "organization";
+        other: "other";
+        "personal-security": "personal-security";
+        playground: "playground";
+        plugins: "plugins";
+        priority: "priority";
+        "read-only-chats": "read-only-chats";
+        "reset-password": "reset-password";
+        rigs: "rigs";
+        schedules: "schedules";
+        secrets: "secrets";
+        "session-link": "session-link";
+        sessions: "sessions";
+        settings: "settings";
+        "setup-account": "setup-account";
+        "site-auth": "site-auth";
+        state: "state";
+        "variable-sets": "variable-sets";
+    }>;
+    value: z.ZodNumber;
+    revision: z.ZodString;
+}, z.core.$strict>], "signal">;
+export type ClientSignalReport = z.infer<typeof ClientSignalReport>;
+export type ClientBeaconReport = ClientErrorReport | ClientSignalReport;
+/**
+ * Bucket bounds cover the published good/poor thresholds of every metric:
+ * CLS 0.1/0.25, INP 0.2/0.5 s, TTFB 0.8/1.8 s, LCP 2.5/4 s.
+ */
+export declare const CLIENT_WEB_VITAL_BUCKETS: number[];
+export type ClientErrorAdmission = KeyedAdmission<ClientErrorKind>;
+/** Keyed by `<signal>:<closed dimension>`, a finite set of buckets. */
+export type ClientSignalAdmission = KeyedAdmission<string>;
+/** Same bounds as the error kinds: one bucket per closed signal key. */
+export declare function createClientSignalAdmission(options?: {
+    capacity?: number;
+    refillPerSecond?: number;
+    now?: () => number;
+}): ClientSignalAdmission;
+/**
+ * Web vitals arrive from every page load rather than only on failure, so they
+ * get a much larger dedicated bucket per metric (burst 1,200, then 20 a
+ * second per process). The browser samples vitals before sending.
+ */
+export declare function createClientWebVitalAdmission(options?: {
+    capacity?: number;
+    refillPerSecond?: number;
+    now?: () => number;
+}): ClientSignalAdmission;
+/**
+ * One token bucket per closed kind bounds counter inflation and log volume
+ * from any caller, including an anonymous one, without per-client state.
+ */
+export declare function createClientErrorAdmission(options?: {
+    capacity?: number;
+    refillPerSecond?: number;
+    now?: () => number;
+}): ClientErrorAdmission;
+export declare function parseClientErrorReport(body: string | null): ClientErrorReport | null;
+/** Parse any accepted beacon body: an error report or a closed signal report. */
+export declare function parseClientBeaconReport(body: string | null): ClientBeaconReport | null;
+export declare function isClientSignalReport(report: ClientBeaconReport): report is ClientSignalReport;
+/**
+ * The exact beacon request. The app-wide request-body limit skips it because
+ * the route enforces its own small limit on the streamed body; the generic
+ * ceiling would otherwise buffer a chunked body of many megabytes on an
+ * anonymous route before this one could refuse it.
+ */
+export declare function isClientErrorReportRequest(method: string, pathname: string): boolean;
+export declare function registerClientErrorRoutes(app: Hono, deps: {
+    observability: Observability;
+    settings: Pick<Settings, "corsAllowOriginRegex" | "publicBaseUrl" | "webBaseUrl">;
+    admission?: ClientErrorAdmission;
+    signalAdmission?: ClientSignalAdmission;
+    webVitalAdmission?: ClientSignalAdmission;
+}): void;