@tangle-network/agent-app 0.45.53 → 0.45.55

package/dist/turn-stream/memory.d.ts

@@ -0,0 +1,41 @@
+/**
+ * In-process turn-stream harness: a fake namespace that routes `idFromName`
+ * to REAL {@link TurnStreamDO} instances over an in-memory storage/socket
+ * state. The adapters and the DO run their production code paths — only the
+ * Cloudflare runtime (isolation, hibernation, real sockets) is simulated.
+ *
+ * For vitest composition tests and keyless local dev (the same role
+ * `createMemoryTurnEventStore` plays for the D1 store). Not for production:
+ * state is per-process and evaporates on restart.
+ */
+import { TurnStreamDO, type TurnStreamDOOptions, type TurnStreamDOState, type TurnStreamSocket } from './do';
+import type { TurnStreamNamespaceLike } from './adapters';
+/** A test-side viewer socket: records frames sent by the DO and lets the
+ *  test drive the `sync` handshake. */
+export interface MemoryTurnStreamSocket extends TurnStreamSocket {
+    readonly frames: string[];
+    readonly closed: boolean;
+}
+/** Define an in-memory channel for streaming turn-based data with viewer socket connection support */
+export interface MemoryTurnStreamChannel {
+    /** Attach a viewer socket to this channel (bypasses the HTTP 101 — the
+     *  upgrade handshake is Cloudflare-runtime-only) and run its `sync`. */
+    connect(input: {
+        sessionId: string;
+        scope: 'thread' | 'workspace';
+        afterSeq?: number;
+    }): Promise<MemoryTurnStreamSocket>;
+    readonly instance: TurnStreamDO;
+}
+/** Provide an interface to manage channels and namespaces for memory-based turn stream testing */
+export interface MemoryTurnStreamHarness {
+    namespace: TurnStreamNamespaceLike;
+    /** The channel (creating its DO instance if needed) for a channel key —
+     *  e.g. `threadChannelKey(ws, thread)` — to connect test viewers. */
+    channel(name: string): MemoryTurnStreamChannel;
+}
+/**
+ * Build the harness. `createInstance` lets a product test run its own
+ * `TurnStreamDO` subclass through the same wiring.
+ */
+export declare function createMemoryTurnStreamHarness(createInstance?: (state: TurnStreamDOState) => TurnStreamDO, _options?: TurnStreamDOOptions): MemoryTurnStreamHarness;

package/dist/vault/ConfirmDialog.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Self-contained confirm dialog — no dialog library. A focus-trapped modal with
+ * Esc-to-cancel and Enter-to-confirm, used for create / delete / discard-unsaved
+ * flows so the pane carries zero UI-kit dependency.
+ */
+import { type ReactNode } from 'react';
+export interface ConfirmDialogProps {
+    open: boolean;
+    title: string;
+    description?: ReactNode;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    /** Styles the confirm button as a destructive action. */
+    destructive?: boolean;
+    /** Disables the confirm button (e.g. while the action is in flight). */
+    confirmDisabled?: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+    /** Optional body (e.g. an input field for the create flow). */
+    children?: ReactNode;
+}
+export declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, destructive, confirmDisabled, onConfirm, onCancel, children, }: ConfirmDialogProps): import("react").JSX.Element | null;

package/dist/vault/VaultPane.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The shared 3-pane vault: tree | artifact viewer | optional agent dock. This is
+ * pure shell MECHANISM — selection, the dirty-guard + pending-nav state machine,
+ * rich/source editor modes, create/delete/refresh, skeletons, an error boundary,
+ * and an empty state. It renders NO file tree and NO artifact viewer of its own:
+ * those arrive through the `renderTree` / `renderArtifact` / `renderDock` seams,
+ * so a product wires sandbox-ui's RichFileTree + FileArtifactPane in ~10 lines.
+ *
+ * Data flows exclusively through `port` (a `VaultDataPort`). The pane never
+ * imports a fetch client, a router, a toast system, or a markdown library — the
+ * optional `codec` seam supplies rich/source parsing (identity passthrough by
+ * default). Chrome uses the shared theme tokens (bg-card, border-border, …).
+ */
+import type { VaultPaneProps } from './contracts';
+export declare function VaultPane(props: VaultPaneProps): import("react").JSX.Element;

package/dist/{VaultPane-BDP6SB_K.d.ts → vault/contracts.d.ts}

@@ -1,6 +1,3 @@
-import * as react from 'react';
-import { ReactNode } from 'react';
-
 /**
  * Seams between the shared VaultPane and the host product. Everything here is
  * interface-only: the pane never imports a file tree, an artifact viewer, a
@@ -14,13 +11,13 @@ import { ReactNode } from 'react';
  * The only import is React's `ReactNode` type — pure type, no runtime, so this
  * file stays server-safe and the contracts are usable without React mounted.
  */
-
+import type { ReactNode } from 'react';
 /**
  * One node in the vault tree. Field-for-field identical to sandbox-ui's
  * `FileNode`, so a `VaultTreeNode[]` IS a `FileNode[]` — the product hands
  * sandbox-ui's `RichFileTree` the `root` from `renderTree` with no conversion.
  */
-interface VaultTreeNode {
+export interface VaultTreeNode {
     name: string;
     path: string;
     type: 'file' | 'directory';
@@ -29,7 +26,7 @@ interface VaultTreeNode {
     mimeType?: string;
 }
 /** A loaded vault file: its text content plus optional preview hints. */
-interface VaultFile {
+export interface VaultFile {
     path: string;
     content: string;
     mimeType?: string;
@@ -44,7 +41,7 @@ interface VaultFile {
  * over fetch, a sandbox session, a worker RPC, whatever the product uses. The
  * pane calls these; it never knows the transport.
  */
-interface VaultDataPort {
+export interface VaultDataPort {
     /** List the full vault tree. The returned nodes feed `renderTree` directly. */
     listTree(): Promise<VaultTreeNode[]>;
     /** Read a single file by path. */
@@ -58,14 +55,14 @@ interface VaultDataPort {
     deleteFile(path: string): Promise<void>;
 }
 /** The Vault operation that failed at the product-owned data-port seam. */
-type VaultOperation = 'list' | 'read' | 'save' | 'create' | 'delete';
+export type VaultOperation = 'list' | 'read' | 'save' | 'create' | 'delete';
 /** Whether the operation itself failed or a mutation succeeded but its
  *  follow-up tree refresh did not. */
-type VaultOperationPhase = 'operation' | 'post-mutation-refresh';
+export type VaultOperationPhase = 'operation' | 'post-mutation-refresh';
 /** Structured failure reported to an optional host observer. VaultPane always
  *  renders its own recovery UI; this payload is for telemetry or additional
  *  product presentation and never controls the pane's state machine. */
-interface VaultOperationFailure {
+export interface VaultOperationFailure {
     operation: VaultOperation;
     phase: VaultOperationPhase;
     path?: string;
@@ -78,7 +75,7 @@ interface VaultOperationFailure {
  * dirtiness, so any structure (frontmatter + body, AST, etc.) works as long as
  * `parse` and `serialize` are inverses for unchanged content.
  */
-type VaultRichParts = unknown;
+export type VaultRichParts = unknown;
 /**
  * Optional rich/source codec. When supplied, the pane's rich mode edits
  * `parse(raw)` and the source mode edits `raw`; switching modes recomputes
@@ -91,18 +88,18 @@ type VaultRichParts = unknown;
  * uses that round-trip to detect edits, so a non-inverse opens files false-dirty
  * and a save corrupts them.
  */
-interface VaultMarkdownCodec {
+export interface VaultMarkdownCodec {
     parse(raw: string): VaultRichParts;
     serialize(parts: VaultRichParts): string;
 }
 /** Props the pane passes to the product's tree renderer (e.g. RichFileTree). */
-interface VaultTreeRenderProps {
+export interface VaultTreeRenderProps {
     root: VaultTreeNode;
     selectedPath?: string;
     onSelect: (path: string) => void;
 }
 /** Props the pane passes to the product's artifact renderer (e.g. FileArtifactPane). */
-interface VaultArtifactRenderProps {
+export interface VaultArtifactRenderProps {
     file: VaultFile | null;
     loading: boolean;
     /** Current editor mode. In 'rich' mode the product MAY host a WYSIWYG editor
@@ -121,13 +118,13 @@ interface VaultArtifactRenderProps {
     onSave: () => void;
 }
 /** Props the pane passes to the product's optional dock renderer (e.g. an agent dock). */
-interface VaultDockRenderProps {
+export interface VaultDockRenderProps {
     file: VaultFile | null;
     open: boolean;
     onClose: () => void;
 }
 /** Configures the dock toggle VaultPane renders above the artifact pane. */
-interface VaultDockToggle {
+export interface VaultDockToggle {
     /** Button + aria label (e.g. 'Discuss', 'Review'). */
     label: string;
     /** Tooltip when enabled. Defaults to `label`. */
@@ -137,9 +134,9 @@ interface VaultDockToggle {
     disabledWhenDirty?: boolean;
 }
 /** The two editor surfaces the pane switches between for editable text files. */
-type VaultEditorMode = 'rich' | 'source';
+export type VaultEditorMode = 'rich' | 'source';
 /** Define the properties and render methods for the vault pane UI components */
-interface VaultPaneProps {
+export interface VaultPaneProps {
     /** Product-owned data access. */
     port: VaultDataPort;
     /** Renders the left tree pane. The product passes sandbox-ui's RichFileTree. */
@@ -186,7 +183,3 @@ interface VaultPaneProps {
     codec?: VaultMarkdownCodec;
     className?: string;
 }
-
-declare function VaultPane(props: VaultPaneProps): react.JSX.Element;
-
-export { type VaultArtifactRenderProps as V, type VaultDataPort as a, type VaultDockRenderProps as b, type VaultDockToggle as c, type VaultEditorMode as d, type VaultFile as e, type VaultMarkdownCodec as f, type VaultOperation as g, type VaultOperationFailure as h, type VaultOperationPhase as i, VaultPane as j, type VaultPaneProps as k, type VaultRichParts as l, type VaultTreeNode as m, type VaultTreeRenderProps as n };

package/dist/vault/index.d.ts

@@ -1,22 +1,15 @@
-export { V as VaultArtifactRenderProps, a as VaultDataPort, b as VaultDockRenderProps, c as VaultDockToggle, d as VaultEditorMode, e as VaultFile, f as VaultMarkdownCodec, g as VaultOperation, h as VaultOperationFailure, i as VaultOperationPhase, j as VaultPane, k as VaultPaneProps, l as VaultRichParts, m as VaultTreeNode, n as VaultTreeRenderProps } from '../VaultPane-BDP6SB_K.js';
-import * as react from 'react';
-import { ReactNode } from 'react';
-
-interface ConfirmDialogProps {
-    open: boolean;
-    title: string;
-    description?: ReactNode;
-    confirmLabel?: string;
-    cancelLabel?: string;
-    /** Styles the confirm button as a destructive action. */
-    destructive?: boolean;
-    /** Disables the confirm button (e.g. while the action is in flight). */
-    confirmDisabled?: boolean;
-    onConfirm: () => void;
-    onCancel: () => void;
-    /** Optional body (e.g. an input field for the create flow). */
-    children?: ReactNode;
-}
-declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, destructive, confirmDisabled, onConfirm, onCancel, children, }: ConfirmDialogProps): react.JSX.Element | null;
-
-export { ConfirmDialog, type ConfirmDialogProps };
+/**
+ * `@tangle-network/agent-app/vault` — the shared 3-pane VaultPane (tree |
+ * artifact viewer | optional agent dock) every Tangle agent product otherwise
+ * hand-rolls. Pure shell mechanism: selection, the dirty-guard state machine,
+ * rich/source editor modes, create/delete, skeletons, and an error boundary.
+ * The product supplies the data (`VaultDataPort`) and the renderers; the pane
+ * imports no file tree, no artifact viewer, and no dialog library.
+ *
+ * Never re-exported from the package root barrel — `react` is an optional peer
+ * and DOM access begins only inside component render. A `React.lazy` code-split
+ * entry lives at `./vault/lazy`.
+ */
+export * from './contracts';
+export { VaultPane } from './VaultPane';
+export { ConfirmDialog, type ConfirmDialogProps } from './ConfirmDialog';

package/dist/vault/lazy.d.ts

@@ -1,8 +1,10 @@
-import * as react from 'react';
-import { j as VaultPane } from '../VaultPane-BDP6SB_K.js';
-export { k as VaultPaneProps } from '../VaultPane-BDP6SB_K.js';
-
+/**
+ * Code-split entry for the vault surface. Products that don't need the vault on
+ * initial load import `VaultPaneLazy` (a `React.lazy` handle) instead of the
+ * component directly, so the pane chunk loads on first render. Mount inside a
+ * `<Suspense>` boundary; the product provides the fallback.
+ */
+import type { VaultPaneProps } from './contracts';
+export type { VaultPaneProps };
 /** Resolve VaultPane component lazily to optimize loading and improve performance */
-declare const VaultPaneLazy: react.LazyExoticComponent<typeof VaultPane>;
-
-export { VaultPaneLazy };
+export declare const VaultPaneLazy: import("react").LazyExoticComponent<typeof import("./VaultPane").VaultPane>;

package/dist/vault/server.d.ts

@@ -29,11 +29,11 @@
  *  live baseline (both this and `VAULT_DELETION_REFUSAL_MIN_LIVE_FILES` must
  *  hold — a tiny vault can lose all its files without tripping this ratio
  *  gate; `refusesAllFiles` catches that case separately). */
-declare const VAULT_DELETION_REFUSAL_RATIO = 0.75;
+export declare const VAULT_DELETION_REFUSAL_RATIO = 0.75;
 /** The blast-radius ratio gate only engages once the live baseline is at
  *  least this large, so a 2-file vault losing 1 file (50%) is not refused on
  *  ratio alone. */
-declare const VAULT_DELETION_REFUSAL_MIN_LIVE_FILES = 10;
+export declare const VAULT_DELETION_REFUSAL_MIN_LIVE_FILES = 10;
 /** Overrides for `assessVaultDeletionBatch`'s two thresholds. Both default to
  *  the exported constants above. Values are validated fail-loud:
  *  `refusalRatio` must be finite and in (0, 1] — `NaN` (a config parse
@@ -41,11 +41,11 @@ declare const VAULT_DELETION_REFUSAL_MIN_LIVE_FILES = 10;
  *  disable the guard, and `0` would refuse a zero-deletion batch; and
  *  `minLiveFiles` must be finite and >= 0. Invalid values throw `RangeError`
  *  instead of running with a guard that cannot fire (or cannot pass). */
-interface VaultDeletionPolicy {
+export interface VaultDeletionPolicy {
     refusalRatio?: number;
     minLiveFiles?: number;
 }
-interface VaultDeletionAssessment {
+export interface VaultDeletionAssessment {
     /** True when no refusal reason fired. */
     allowed: boolean;
     /** Precedence when multiple reasons would fire: `empty-manifest` beats
@@ -74,7 +74,7 @@ interface VaultDeletionAssessment {
  * diagnostic that matters to a caller is "the scan was empty", not merely
  * "everything would go".
  */
-declare function assessVaultDeletionBatch(input: {
+export declare function assessVaultDeletionBatch(input: {
     /** LIVE (non-tombstoned) baseline path set — the caller pre-filters, as gtm does. */
     baselinePaths: readonly string[];
     /** Paths a reconciliation pass proposes to delete; intersected with `baselinePaths` internally. */
@@ -85,7 +85,7 @@ declare function assessVaultDeletionBatch(input: {
 /** The subset of a sandbox's filesystem-incarnation identity this module
  *  needs. A product's real incarnation type is structurally compatible —
  *  no import required. */
-interface FilesystemIncarnationLike {
+export interface FilesystemIncarnationLike {
     filesystemIncarnationId?: string;
     filesystemIncarnationProvenance?: 'fresh' | 'restored' | 'unknown';
     filesystemIncarnationReadiness?: 'transitioning' | 'ready';
@@ -96,7 +96,7 @@ interface FilesystemIncarnationLike {
  * caller's `switch` gets compile-time coverage instead of a stringly-typed
  * status it can forget to branch on.
  */
-type IncarnationComparison = {
+export type IncarnationComparison = {
     verdict: 'match';
 } | {
     verdict: 'mismatch';
@@ -125,6 +125,4 @@ type IncarnationComparison = {
  *  4. `mismatch` — the baseline id and current id disagree.
  *  5. `match` — same incarnation.
  */
-declare function compareIncarnationBaseline(baselineId: string | undefined, current: FilesystemIncarnationLike): IncarnationComparison;
-
-export { type FilesystemIncarnationLike, type IncarnationComparison, VAULT_DELETION_REFUSAL_MIN_LIVE_FILES, VAULT_DELETION_REFUSAL_RATIO, type VaultDeletionAssessment, type VaultDeletionPolicy, assessVaultDeletionBatch, compareIncarnationBaseline };
+export declare function compareIncarnationBaseline(baselineId: string | undefined, current: FilesystemIncarnationLike): IncarnationComparison;

package/dist/web/free-route-limit.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Rate-limit policy for FREE routes: authenticated, unmetered, compute-bearing
+ * endpoints.
+ *
+ * Billing meters the chat turn. Everything deterministic a product adds beside
+ * it — a planning recompute fired on every slider drag, a redline diff, a
+ * deadline computation — runs unmetered, so nothing bounds how much worker CPU
+ * one authenticated caller can spend. `checkRateLimit` is the primitive; this
+ * is the policy around it, so a route declares a cost class instead of each one
+ * inventing a key format, a budget, and a denial response.
+ *
+ * Three rules this enforces that a hand-rolled call site usually does not:
+ *
+ * 1. **Identity is required.** A missing subject is denied, never pooled into a
+ *    shared bucket and never quietly keyed by IP — a shared bucket makes one
+ *    heavy user throttle everyone, and an IP key makes one NAT do the same.
+ * 2. **A limiter that throws denies.** KV `get`/`put` failures are transport
+ *    failures; treating them as "allowed" converts a KV outage into an
+ *    unbounded-compute hole, which is exactly when the limiter matters most.
+ * 3. **The denial is a typed, correctable outcome** — reason, HTTP status and
+ *    `Retry-After` — so the caller answers the client rather than failing
+ *    opaquely or, worse, continuing.
+ *
+ * ```ts
+ * export const action = withFreeRouteLimit(
+ *   {
+ *     route: 'tax.plan.recompute',
+ *     costClass: 'interactive',
+ *     kv: ({ context }) => context.cloudflare.env.RATE_LIMIT_KV,
+ *     identify: async ({ request }) => {
+ *       const session = await requireSession(request)
+ *       return { subject: session.userId, workspace: session.workspaceId }
+ *     },
+ *   },
+ *   async ({ request }) => Response.json(recompute(await request.json())),
+ * )
+ * ```
+ */
+import { type KvLike } from './rate-limit';
+/** Requests allowed per identity inside a sliding window. */
+export interface RateLimitBudget {
+    limit: number;
+    windowSeconds: number;
+}
+/**
+ * How expensive one call is, which is what picks the default budget.
+ *
+ * - `interactive` — a control the user drags or types into, recomputed per
+ *   tick. Sized for sustained two-per-second interaction, so a real slider
+ *   never trips it and a script still stops.
+ * - `compute` — a derivation the user triggers deliberately (recalculate a
+ *   plan, diff a document, compute a deadline set). The default.
+ * - `heavy` — whole-document or whole-matter work measured in seconds of CPU.
+ */
+export type FreeRouteClass = 'interactive' | 'compute' | 'heavy';
+/** Default budget per cost class. A product overrides with an explicit
+ *  `budget` when it has measured its own route. */
+export declare const FREE_ROUTE_BUDGETS: Readonly<Record<FreeRouteClass, RateLimitBudget>>;
+/** A workspace's shared ceiling defaults to this many times one member's, so a
+ *  multi-seat tenant is bounded without a single active member tripping it. */
+export declare const WORKSPACE_BUDGET_MULTIPLIER = 5;
+/** Why a call was refused. Every value is a REFUSAL — there is no reason code
+ *  that lets the handler run. */
+export type FreeRouteDenialReason = 
+/** No authenticated subject. Not correctable by waiting. */
+'unidentified'
+/** The window is full for this subject or workspace. */
+ | 'rate-limited'
+/** The limiter itself failed (KV read/write threw). Denied, not passed. */
+ | 'limiter-unavailable';
+/** Which window refused the call. `null` when no window was consulted. */
+export type FreeRouteDimension = 'subject' | 'workspace' | null;
+/**
+ * A correctable refusal: the caller maps `status` + `retryAfterSeconds` onto a
+ * response (see {@link freeRouteLimitResponse}) so the client learns what to do
+ * next. Carrying the limiter's own failure in `cause` keeps a KV outage
+ * diagnosable instead of collapsing into a generic 429.
+ */
+export declare class FreeRouteLimitError extends Error {
+    readonly reason: FreeRouteDenialReason;
+    readonly status: 401 | 429 | 503;
+    readonly retryAfterSeconds: number;
+    readonly dimension: FreeRouteDimension;
+    readonly route: string;
+    constructor(init: {
+        reason: FreeRouteDenialReason;
+        status: 401 | 429 | 503;
+        retryAfterSeconds: number;
+        dimension: FreeRouteDimension;
+        route: string;
+        message: string;
+        cause?: unknown;
+    });
+}
+/** What remains of the binding window after an allowed call. */
+export interface FreeRouteAllowance {
+    /** Remaining calls in whichever window is tightest. */
+    remaining: number;
+    /** Unix seconds at which that window resets. */
+    resetAt: number;
+    /** The budget that window enforces. */
+    budget: RateLimitBudget;
+    /** Which window is tightest — `subject` unless a workspace ceiling binds. */
+    dimension: Exclude<FreeRouteDimension, null>;
+}
+/** Typed outcome at the route boundary: an allowance, or a refusal that says
+ *  how to correct it. There is no third state and no silent pass. */
+export type FreeRouteLimitOutcome = {
+    succeeded: true;
+    value: FreeRouteAllowance;
+} | {
+    succeeded: false;
+    error: FreeRouteLimitError;
+};
+export interface FreeRouteLimitInput {
+    kv: KvLike;
+    /** Stable route name. Part of the key, so two routes never share a window. */
+    route: string;
+    /** The authenticated subject (user id). Absent or blank ⇒ denied. */
+    subject: string | null | undefined;
+    /** Tenant the call belongs to. When present, a second, wider window bounds
+     *  the workspace as a whole. */
+    workspace?: string | null;
+    /** Cost class picking the default budget. Ignored when `budget` is given.
+     *  Default `'compute'`. */
+    costClass?: FreeRouteClass;
+    budget?: RateLimitBudget;
+    /** Workspace ceiling. Defaults to the subject budget's limit multiplied by
+     *  {@link WORKSPACE_BUDGET_MULTIPLIER} over the same window. */
+    workspaceBudget?: RateLimitBudget;
+}
+/**
+ * Decide whether one authenticated, unmetered call may run.
+ *
+ * Checks the subject's window first, then the workspace ceiling when a
+ * workspace is supplied; the tighter of the two is what the allowance reports.
+ * Every failure path returns a refusal — none returns an allowance.
+ */
+export declare function checkFreeRouteLimit(input: FreeRouteLimitInput): Promise<FreeRouteLimitOutcome>;
+export interface FreeRouteLimitResponseOptions {
+    /** Extra response headers (a product's security headers, CORS). */
+    headers?: Record<string, string>;
+    /** Client-facing message. Defaults to the error's own message. */
+    message?: string;
+}
+/** The refusal as an HTTP response: the error's status, a JSON body carrying
+ *  the machine-readable `reason`, and `Retry-After` when waiting can fix it. */
+export declare function freeRouteLimitResponse(error: FreeRouteLimitError, options?: FreeRouteLimitResponseOptions): Response;
+/** The authenticated caller behind one request. */
+export interface FreeRouteIdentity {
+    subject: string;
+    workspace?: string | null;
+}
+export interface WithFreeRouteLimitOptions<TArgs> {
+    /** Stable route name; part of the key. */
+    route: string;
+    costClass?: FreeRouteClass;
+    budget?: RateLimitBudget;
+    workspaceBudget?: RateLimitBudget;
+    /** The KV binding for this request. */
+    kv: (args: TArgs) => KvLike;
+    /**
+     * Resolve the authenticated caller. Return `null` for an unauthenticated
+     * request — the wrapper then refuses with 401 and the handler never runs.
+     *
+     * A THROW here propagates: an auth lookup that failed is not the same as an
+     * absent session, and the wrapper will not invent a status for it. The
+     * handler still does not run, so the failure stays closed.
+     */
+    identify: (args: TArgs) => Promise<FreeRouteIdentity | null> | FreeRouteIdentity | null;
+    /** Build the refusal response. Defaults to {@link freeRouteLimitResponse}. */
+    onDenied?: (error: FreeRouteLimitError, args: TArgs) => Response | Promise<Response>;
+}
+/**
+ * Wrap an authenticated, unmetered, compute-bearing route handler in its
+ * budget. The limit is applied BEFORE the handler is entered — including
+ * before the request body is read — so a refused call costs a KV read, not the
+ * compute the route exists to do.
+ *
+ * The handler's own response is returned untouched: this never rewrites status,
+ * body or headers on the success path, so it cannot break a streaming or
+ * pre-built response.
+ *
+ * `TArgs` is the router's handler-argument object (react-router's
+ * `ActionFunctionArgs`, or any single-object shape a product uses).
+ */
+export declare function withFreeRouteLimit<TArgs>(options: WithFreeRouteLimitOptions<TArgs>, handler: (args: TArgs) => Response | Promise<Response>): (args: TArgs) => Promise<Response>;